mirror of
https://github.com/wesammustafa/opencode-primer.git
synced 2026-11-18 18:04:22 +00:00
Community and contributor support:
- CONTRIBUTING.md: what we welcome, what we don't, style guide,
templates for MCP walkthroughs and specialized-agent prompts.
- CODE_OF_CONDUCT.md: Contributor Covenant 2.1.
- SECURITY.md: scope (this is a docs repo, not application code), how
to report a vulnerability in the example plugins or in misleading
documentation, where OpenCode-core bugs should go instead.
GitHub plumbing:
- .github/PULL_REQUEST_TEMPLATE.md: type, sources, hygiene checklist.
- .github/ISSUE_TEMPLATE/{bug_report,feature_request}.md and config.yml
that redirects OpenCode-tool issues to the right place.
- .github/workflows/lint-docs.yml: three jobs on every push and PR —
markdownlint, link check (with sensible ignore patterns for
../../issues, security advisories, localhost), codespell with a
project-specific ignore list.
Lint/style configs:
- .markdownlint.json + .markdownlintignore: ATX headings, ordered list
numbering, line-length and inline-HTML rules tuned for our content.
- .editorconfig: LF, UTF-8, 2-space indent, trim trailing whitespace
except in markdown (where trailing spaces are line breaks).
82 lines
4.0 KiB
Markdown
82 lines
4.0 KiB
Markdown
# Contributing
|
||
|
||
Thank you for considering a contribution. This repo is a community-maintained guide to [OpenCode](https://opencode.ai) — every typo fix, fact correction, and new example helps the next reader.
|
||
|
||
## What we welcome
|
||
|
||
| Contribution | What's helpful |
|
||
|---|---|
|
||
| **Fact corrections** | OpenCode moves fast. If something here is out of date, fix it and cite the source. |
|
||
| **New MCP walkthroughs** | A short page in [`mcp-servers/`](mcp-servers/) with verified setup steps, example prompts, and gotchas. |
|
||
| **New specialized-agent prompts** | A new role under [`specialized-agents/system-prompts/`](specialized-agents/system-prompts/) + a one-page description. |
|
||
| **Better examples** | Real-world patterns that worked for you. |
|
||
| **Typo and grammar fixes** | Just send the PR. |
|
||
| **Image / diagram contributions** | Drop PNG/SVG in [`Images/`](Images/) and reference them inline. |
|
||
|
||
## What we don't accept
|
||
|
||
- **Unverified claims.** Every factual statement must trace back to [opencode.ai/docs](https://opencode.ai/docs/), the [OpenCode GitHub repo](https://github.com/anomalyco/opencode), or a primary source. No "I heard that…".
|
||
- **Marketing language.** This guide is practical, not a sales pitch.
|
||
- **Affiliate links or sponsored content** without prior agreement.
|
||
- **AI-generated content that hasn't been read and verified by you.** If you used an AI to draft, that's fine — but read it carefully, fact-check, and remove fluff before submitting.
|
||
|
||
## How to contribute
|
||
|
||
1. **Open an issue first** for non-trivial changes (new sections, restructuring) so we can align on scope.
|
||
2. **Fork → branch → PR.** One topic per PR; smaller is better.
|
||
3. **Match the existing style.** See [AGENTS.md](AGENTS.md) for style conventions (markdown, tone, link form).
|
||
4. **Cite your sources.** If you're updating a fact, include a link to the source in the PR description.
|
||
5. **Update the "Last reviewed" date** at the bottom of the README if you've made material changes.
|
||
|
||
## Style basics
|
||
|
||
- Short lines, plain English.
|
||
- Lead with the mental model, then the syntax, then the example.
|
||
- Comparison tables when there's a choice to make.
|
||
- Code fences with language tags. JSON examples should be valid `opencode.json` snippets.
|
||
- Emoji callouts: `> 💡 Pro Tip`, `> ⚠️ Warning`, `> 🆕 New`, `> 📚 Further reading`.
|
||
|
||
## Tips for adding a new MCP walkthrough
|
||
|
||
A good walkthrough has:
|
||
|
||
1. **When to reach for it** — one-line use case
|
||
2. **Setup** — exact JSON snippet for `opencode.json` and any auth steps
|
||
3. **Example prompts** — 2–3 realistic prompts (not "hello world")
|
||
4. **What it can do / won't do** — set expectations
|
||
5. **Gotchas** — things you wish you'd known
|
||
6. **Resources** — links to the upstream project
|
||
|
||
See [`mcp-servers/playwright.md`](mcp-servers/playwright.md) as a template.
|
||
|
||
## Tips for adding a new specialized-agent prompt
|
||
|
||
A good system prompt has:
|
||
|
||
1. **Frontmatter** with `description`, `mode`, `model`, `temperature`, `permission` — use the format in [`docs/agents.md`](docs/agents.md).
|
||
2. **Principles** — 3–5 numbered, prescriptive items. What the agent prioritizes.
|
||
3. **Workflow** — concrete steps the agent should follow.
|
||
4. **Defaults** — the stack and tools the agent uses.
|
||
5. **What I won't do** — explicit constraints. This is what makes specialized agents different from a generic LLM.
|
||
6. **Communication style** — how the agent talks (terse, surfaces trade-offs, etc.).
|
||
|
||
Add the matching short description under [`specialized-agents/descriptions/`](specialized-agents/descriptions/) and update the table in [`specialized-agents/README.md`](specialized-agents/README.md).
|
||
|
||
## Local check
|
||
|
||
There's no build system to run, but a quick mental checklist before submitting:
|
||
|
||
- [ ] All links resolve (in-page anchors and external URLs)
|
||
- [ ] Code fences have language tags
|
||
- [ ] No trailing whitespace
|
||
- [ ] No emoji clutter
|
||
- [ ] Facts cite a source
|
||
|
||
## Questions
|
||
|
||
Open a [GitHub Discussion](../../discussions) or an [issue](../../issues). Drive-by PRs are welcome too — we'll suggest changes in review.
|
||
|
||
---
|
||
|
||
*Thanks for making this resource better.*
|