mirror of
https://github.com/wesammustafa/opencode-primer.git
synced 2026-11-19 02:17:58 +00:00
- Bump every version pin, pricing table, and model ID to the verified 2026-07-05 state (v1.17.13): Claude Fable 5 / Sonnet 5 on Zen, new free tier, deprecation sunset table, v1.17.x changelog section - Cover gaps: OpenCode Go vs Zen billing, Anthropic subscription-login removal (PR #18186), MCP resources, --mini mode, --auto flag, yolo mode - Fix correctness bugs: command-template !`cmd` syntax in docs and .opencode/commands, protect-secrets regex missing 'cat .env', dual plugin exports, quickstart PATH fix, Playwright MCP flags, ctrl+d keybind conflict, agent/command required-field claims - Fix links: cursor.com, windsurf.com, platform.claude.com, code.claude.com, opencode.ai/discord, Vercel Grep announcement - Rebrand: banner (Images/banner.svg), 1280x640 social preview asset, hero redesign with star CTA, ecosystem stats, private vulnerability reporting channel, CI-matching local checks, MD060 lint opt-out
6.9 KiB
6.9 KiB
AGENTS.md
Project instructions for OpenCode. Read every session.
What this repo is
A practical, opinionated guide to using OpenCode — README, supporting docs, drop-in agent prompts, MCP walkthroughs, and a worked example of a fully-configured .opencode/ directory. It's a documentation repository, not application code.
Repo layout
.
├── README.md # Main guide (the centerpiece)
├── AGENTS.md # This file
├── CONTRIBUTING.md # How to contribute
├── SECURITY.md · CODE_OF_CONDUCT.md
├── LICENSE # MIT
├── opencode.json · tui.json # Example configs with safe defaults
├── docs/
│ ├── quickstart.md # 5-minute getting-started
│ ├── zen.md # Zen model gateway details
│ ├── tui.md # TUI mastery
│ ├── agents.md # Custom agent deep dive
│ ├── commands.md # Custom slash commands
│ ├── skills.md # Agent skills
│ ├── plugins.md # Plugin/hook system
│ ├── mcp.md # MCP integration
│ ├── workflows.md # Real-world recipes
│ ├── migration.md # Migration from Claude Code / Cursor
│ └── reference/
│ ├── cli.md # All CLI commands
│ ├── slash-commands.md # All TUI slash commands
│ ├── permissions.md # Permission model
│ ├── changelog.md # OpenCode releases
│ ├── faq.md # FAQ + troubleshooting
│ └── further-reading.md # External resources
├── .opencode/
│ ├── agents/ # Example custom agents
│ ├── commands/ # Example custom commands
│ ├── plugins/ # Example plugins (audit log, secret blocker)
│ └── skills/ # Example agent skills
├── .github/ # CI (lint-docs.yml), issue/PR templates
├── mcp-servers/ # MCP server walkthroughs
├── specialized-agents/ # Drop-in specialist prompts
│ ├── system-prompts/ # System prompts (7 roles)
│ └── descriptions/ # Role descriptions
└── Images/ # Banner, diagrams, screenshots
Editing rules
Always
- Cite the source. Every factual claim about OpenCode must trace back to opencode.ai/docs, the GitHub repo, or an official release note. Don't paraphrase from memory.
- Verify version-specific claims. Pricing, model names, commands, and flags change. When in doubt, check the docs page that owns the topic.
- Use OpenCode's actual terminology. "Custom commands" not "slash skills"; "agents" and "subagents" not "personas"; "plugins" not "hooks" (OpenCode plugins serve the hook role).
- Match the README's tone. Practical, mental-model-first, prescriptive ("Reach for it when…"). No marketing fluff.
- Update the
Last revieweddate at the bottom of the README when making material changes.
Never
- Don't invent commands, flags, or features. If you can't verify it, leave it out.
- Don't hardcode prices without a "verified" date. Always show the date next to any pricing table.
- Don't add
Co-Authored-Bylines to commits unless the user asks for them. - Don't
git push --forcetomain, ever, without explicit permission. - Don't introduce affiliate links or sponsorship blocks without the maintainer's approval.
Style conventions
Markdown
- One blank line between sections. No trailing whitespace.
- Code fences with language tags:
```bash,```json,```markdown. - Internal links use anchor form:
[label](#section-id). Anchors are auto-derived from headings (lowercased, spaces → dashes, special chars stripped). - Tables: header row, separator row, no leading/trailing pipes. Keep column widths reasonable for desktop reading.
- Callouts use blockquotes with emoji prefixes:
> 💡 **Pro Tip:** …for tips> ⚠️ **Warning:** …for foot-guns> 🆕 …for new features> 📚 …for deeper-reading pointers
- Emoji policy:
- OK — one leading emoji on H2 navigation headings (🧭 🧠 📚 📖), and the callout-prefix set above.
- Not OK — decorative emoji inside prose, in code, or on H3/H4 headings. One per spot, never decorative density.
Code samples
- JSON examples in this repo are valid
opencode.jsonsnippets — paste-ready. Include the$schemaline on full-file examples. - Shell examples assume a POSIX shell. Use
bashfence; quote variables ("$VAR"). - Markdown front-matter uses YAML with
---fences. Match the exact key spelling from the OpenCode docs (e.g.,description,mode,model,permission,tools).
Tone
- Be concrete. "Reach for it when X" beats "useful for X."
- Lead with the mental model, then the syntax, then the example.
- Compare options side-by-side when there's a choice to make (custom commands vs. skills, etc.).
- Emoji discipline. Allowed: H2 navigation marker, and the callout prefixes listed under "Markdown" above. Not allowed: decoration inside prose or on H3/H4 headings.
Commands
No build step, but CI (.github/workflows/lint-docs.yml) lints every push/PR to main. Run the same checks locally before committing:
# Markdown lint (config: .markdownlint.json)
npx markdownlint-cli2 "**/*.md"
# Spell-check (ignore list: .github/codespell-ignore.txt)
codespell --ignore-words=.github/codespell-ignore.txt --skip="./LICENSE,./.git,./node_modules" .
# Link check (config: .github/markdown-link-check.json)
npx markdown-link-check -c .github/markdown-link-check.json README.md
How OpenCode should work in this repo
- Default agent:
buildis fine — edits are local-file-only and easily reversible. - No network-dependent tools needed for editing docs.
webfetch/websearchare useful only when verifying external claims. - Bash: read-only commands (
ls,grep,git status,git diff) are safe to auto-allow. Writes (rm,mv,git push) should always require confirmation.
When to update what
| Trigger | What to update |
|---|---|
| New OpenCode release | docs/reference/changelog.md + version line in README footer |
| Pricing change | Pricing table in README + docs/zen.md, with new "verified" date |
| New built-in command | Slash-command list in README + docs/reference/slash-commands.md |
| Discovered factual error | Fix the source location; grep for repeats |
This file is read by OpenCode at every session. Keep it short, accurate, and actionable.