25 Commits
Author SHA1 Message Date
Wesam Abousaid fe71432a72 chore: align branding and URLs with opencode-primer rename (#6)
- H1 and banner now lead with 'OpenCode Primer' (old title kept as tagline)
- All absolute repo URLs updated to wesammustafa/opencode-primer
  (GitHub redirects the old slug, but canonical links are cleaner)
- Social preview re-rendered from the updated banner
2026-07-05 14:29:34 +02:00
Wesam Abousaid 064ee20a34 Merge pull request #5 from wesammustafa/docs/opencode-v1.17-rebrand 2026-07-05 14:22:47 +02:00
Wesam Abousaid a3f328c043 docs: refresh for OpenCode v1.17.13, add Go coverage, and rebrand
- 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
2026-07-05 14:11:51 +02:00
Wesam Abousaid 17a72ee8f1 Merge pull request #3 from wesammustafa/docs/opencode-v1.16-refresh
docs: refresh for OpenCode v1.16.2 and fix correctness bugs
2026-06-08 19:01:25 +02:00
Wesam AbousaidandClaude Opus 4.8 29a69a35b0 docs: refresh for OpenCode v1.16.2 and fix correctness bugs
Update the guide to the current release (v1.16.2, 2026-06-05), verified
against opencode.ai/docs and github.com/anomalyco/opencode.

Correctness fixes:
- Plugins: tool.execute.before/after and shell.env are top-level hooks
  with an (input, output) signature, not event.type values. Rewrite both
  shipped example plugins plus the docs/migration examples so they fire.
- Permissions: bash glob maps resolve last-matching-rule-wins (catch-all
  "*" first), not most-specific-wins. Fix prose, reorder examples, and fix
  the shipped opencode.json (rm -rf* deny was shadowed by a later rm *).
- Drop non-existent permission keys repo_clone/repo_overview (15 keys, not
  17); fix steps (integer), deprecate maxSteps/tools, move reasoningEffort
  into model options; fix the `mise` install command.

Currency updates:
- v1.15.4 -> v1.16.2; add v1.16 highlights and a changelog section.
- Refresh OpenCode Zen lineup/pricing (Claude Opus 4.8, gpt-5.4,
  gemini-3.5-flash, qwen3.7, grok-build-0.1; correct free-tier IDs).
- Add `opencode mcp add`, run --replay, extra skill paths, shift+tab, and
  native GitHub commands; correct the specialist-prompt count; bump dates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-08 19:00:39 +02:00
Wesam Abousaid 99e6c6b2a1 fix(ci): disable MD029 entirely
The 'one_or_ordered' setting didn't fix the issue — markdownlint
breaks numbered lists into separate lists wherever there's intervening
non-list content (code fences, paragraphs, shell prompts), and then
flags the second list's first item as a continuation that should have
been numbered 1.

Our command/skill markdown files intentionally interleave numbered
steps with non-list content (shell prompts the agent executes,
explanations). The lint is fighting an editing pattern, not catching
a real readability bug.
2026-05-18 20:29:06 +02:00
Wesam Abousaid 4d5ed82511 fix(ci): green markdownlint and link-check
markdownlint
- Disable MD028 (no-blanks-blockquote): we intentionally separate
  adjacent blockquote callouts (a tip + a warning side-by-side) with
  a blank line; visually this renders as two callouts, which is the
  intent.
- Switch MD029 (ol-prefix) to "one_or_ordered": both "1. / 2. / 3."
  and "1. / 1. / 1." (auto-renumber) are valid; the rule was hitting
  ordered lists that have intervening code blocks, where the lint
  loses count.
- Add blank lines before lists in five places where MD032 fired
  (test.md, git-release/SKILL.md, agents.md, skills.md, migration.md).
- Fix nested code-fence bug in database-engineer-prompt.md: the
  outer ``` was being closed by an inner ```sql; switched the outer
  fence to ```` (4 backticks) so the inner one stays nested.

link-check
- Ignore https://mcp.grep.app and https://ai.google.dev/ — the first
  returns 405 to HEAD requests (verified working via GET); the second
  trips an infinite-redirect bug in the link checker (real URL works).
- Ignore github.com/anomalyco/opencode/discussions — the upstream
  repo currently has discussions disabled.
- Add 405 to aliveStatusCodes for endpoints that accept GET but
  reject HEAD.
2026-05-18 20:26:07 +02:00
Wesam Abousaid 8937f9da4b docs(readme): restructure layout — H2 groups, merged sections, reordered flow
The previous README was 21 flat H3 sections with three competing
H2 navigation blocks at the top. Several pieces sat in unnatural places
and three pairs of sections were artificial splits of the same concept.

This rewrite simplifies the layout:

Hierarchy
- One H2 navigation block at the top: 'Choose your path' (was three).
- Four H2 content groups: Getting started, Using OpenCode, Extending
  OpenCode, Reference. Each holds a small number of H3 sections.
- 17 H3 sections total (down from 21). Clearer GitHub TOC.

Reordered for a top-to-bottom narrative
- 'When OpenCode isn't the right tool' moved up to right after
  'What is OpenCode?', so trade-offs are visible before sinking time
  into Setup.
- TUI & Themes moved from end-of-page into 'Using OpenCode' alongside
  Prompt Engineering, where 'how do I drive this?' belongs.
- 'Pick the right extension' (the mermaid decision tree) now opens
  'Extending OpenCode' inline, where it has context. Previously it sat
  at the top of the page before any extension had been introduced.

Merged artificial splits
- OpenCode Zen + Configuring providers → Models & Providers, with a
  3-way comparison up front (direct / Zen / local) and the Zen lineup
  as an H4 inside it.
- Subagents + Custom Agents → Agents, with built-in agents first,
  custom agents second. They're the same file format with different
  'mode:' values; the old split made the reader trace forward refs.
- TUI Mastery + Themes → TUI & Themes.

Trimmed redundancy
- Removed the table that duplicated the mermaid decision tree in
  'When to use what'. The mermaid was the unique visual; the table
  was repetition.
- Dropped the standalone 'What's inside' index — replaced by the H2
  group hierarchy itself.

Compatibility
- Added <a id> compatibility anchors for old internal links
  (#opencode-setup, #configuring-providers, #prompt-engineering-deep-dive,
  #tui-mastery, #subagents, #custom-agents, #model-context-protocol-mcp,
  #when-to-use-what, #whats-inside) so any external bookmarks still land
  on the page.
- Anchors for #opencode-zen and #themes are still produced by their
  H4 headings inside the merged sections, so existing deep links still
  resolve.

Net effect: 893 lines → 708 lines, same factual coverage, clearer flow.
2026-05-18 20:16:57 +02:00
Wesam Abousaid ccac453cdb chore(oss): add OSS infrastructure — CoC, security, contributing, CI
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).
2026-05-18 20:00:51 +02:00
Wesam Abousaid cbb87bff3f chore: ship example opencode.json, tui.json, and Images/ guidance
- opencode.json: a real, runnable project config with safe defaults —
  edit:"ask", glob-pattern bash map (auto-allow common read-only ops,
  deny rm -rf and git push --force), webfetch and websearch on "ask",
  external_directory denied. Useful as a starting point readers can
  copy verbatim.
- tui.json: minimal example covering theme, scroll speed, leader
  timeout, keybinds, attention/notifications.
- Images/README.md: replaces .gitkeep with explicit contribution rules
  — no copyrighted material, prefer SVG over PNG, prefer mermaid over
  raster when the concept fits.
2026-05-18 20:00:35 +02:00
Wesam Abousaid d75be39290 feat(mcp-servers): walkthroughs for Playwright, Context7, Sentry, Grep
Each walkthrough follows the same template: when to reach for it, setup
(verbatim opencode.json snippet), example prompts, capabilities and
limitations, gotchas, resources.

- playwright.md: browser automation — visual iteration loop, e2e
  scaffolding, bug repro from a URL
- context7.md: live, version-pinned library docs piped into the prompt,
  with the "resolve first, query second" pattern
- sentry.md: errors / traces / releases via OAuth (DCR), with the
  error-to-root-cause pattern
- grep.md: code search across public GitHub via the Vercel-hosted MCP

README.md ranks "when to add a server" against the cost of the extra
tokens it puts in the model's context every turn, with a tools-map
example for disabling chatty MCP tools per agent.

All endpoint URLs and package names link-checked at commit time.
2026-05-18 20:00:21 +02:00
Wesam Abousaid b170bea020 feat(specialized-agents): seven drop-in role prompts with descriptions
Ready-to-copy prompts under specialized-agents/system-prompts/:
- code-reviewer-prompt.md (subagent, read-only)
- security-reviewer-prompt.md (subagent, read-only, CWE-aware)
- backend-engineer-prompt.md (primary or all)
- frontend-engineer-prompt.md (primary or all)
- tech-lead-prompt.md (primary, opus-tier)
- database-engineer-prompt.md (Postgres-first, adapts)
- ux-engineer-prompt.md (design-system-first)

Matching one-page descriptions in specialized-agents/descriptions/.

Every prompt opens with a "one defensible set of opinions, not the only
right answer" disclaimer so readers don't treat them as authoritative.
Stack-specific defaults (Tailwind, FastAPI, Postgres) are explicitly
overridable per project.

To install one:
  cp specialized-agents/system-prompts/code-reviewer-prompt.md \
     .opencode/agents/code-reviewer.md
or reference via {file:...} from opencode.json without copying.
2026-05-18 20:00:09 +02:00
Wesam Abousaid 5ce285d088 feat(.opencode): worked-example agents, commands, plugins, skills
This repo doubles as a fully-configured OpenCode project so readers can
see real files instead of abstract format docs.

Agents (.opencode/agents/, OpenCode YAML + markdown body):
- code-reviewer.md — read-only subagent, glob-gated bash perms,
  Severity/Where/Why/Fix output format. Rewrites the pre-refactor file
  which used incorrect frontmatter shape (no YAML, claude-sonnet-4.6
  as bare ID, made-up tool keys).
- security-auditor.md — OWASP-focused review subagent, deny edit,
  ask bash, CWE-aware output template.

Commands (.opencode/commands/):
- review.md, pr.md, test.md, optimize.md — uses real placeholders
  ($ARGUMENTS, @file, !shell), points the right agent at each task.

Plugins (.opencode/plugins/):
- protect-secrets.js — blocks tool calls touching .env*, secrets/,
  credentials*, SSH keys, .npmrc, .pypirc. Pure JS, no deps.
- audit-log.js — appends one JSON line per successful tool call to
  .opencode/audit.jsonl (also added to .gitignore).
- README.md — how to install/disable, sample audit-log line, link to
  docs/plugins.md.

Skills (.opencode/skills/git-release/SKILL.md):
- Proper folder-with-SKILL.md format. Trigger-shaped description so the
  model actually loads it when the conversation touches release prep.
2026-05-18 19:59:56 +02:00
Wesam Abousaid 73e9274bac docs(reference): add CLI, slash-commands, permissions, FAQ, changelog, further-reading
Six reference pages, each a single-purpose cheatsheet:

- cli.md: full CLI surface (21 commands + global flags + experimental
  env vars) sourced from packages/web/src/content/docs/cli.mdx
- slash-commands.md: every built-in TUI slash command verified against
  packages/web/src/content/docs/tui.mdx
- permissions.md: all 17 permission keys verified against PermissionConfig
  in the JSON schema (read, edit, bash, glob, grep, list, task, todowrite,
  question, external_directory, repo_clone, repo_overview, webfetch,
  websearch, lsp, skill, doom_loop)
- faq.md: covers free-vs-paid, OpenCode vs Claude Code, offline, model
  picks (multi-provider, not Anthropic-only), config locations, sharing,
  privacy, migration, troubleshooting
- changelog.md: notable releases through v1.15.4 (verified via GitHub
  releases API, published 2026-05-17T17:44Z)
- further-reading.md: curated external resources — only links that
  resolve (link-checked at commit time)
2026-05-18 19:59:40 +02:00
Wesam Abousaid 9522c859fd docs(guides): add 10 deep-dive guides verified against opencode.ai/docs
- quickstart.md: 5-minute path from curl to first commit
- zen.md: model gateway with full lineup, pricing, BYOK, patterns
- tui.md: keybinds, leader chords, themes, customization, sessions
- agents.md: custom agents and subagents, full frontmatter, permission map
- commands.md: custom slash commands, placeholders, patterns, override rules
- skills.md: discoverable workflows, SKILL.md format, description-as-trigger
- plugins.md: lifecycle hooks, full event catalog, four real patterns
- mcp.md: local/remote MCP, OAuth (DCR), token budget, featured servers,
  with mermaid N×M → N+M diagram
- migration.md: Claude Code, Cursor, Copilot, Aider — with "what X does
  better" subsections so the comparisons aren't one-sided
- workflows.md: seven real recipes (TDD, bug investigation, multi-agent
  review, cross-repo research, migrations, CI, visual iteration) — CI
  example shows GitHub Actions + GitLab CI to avoid platform bias

Every model slug, permission key, config key, env var, and CLI flag
verified against the JSON schema or the live docs site.
2026-05-18 19:59:28 +02:00
Wesam Abousaid 7d347eef74 docs: rewrite README and AGENTS.md with verified, balanced content
README
- Match the structure of common practical-guide repos: title, badges,
  install one-liner, "Choose your path", "When to use what" decision
  tree (mermaid) + table, "What's inside" topical map, deep dives,
  Limitations, FAQ, Updates, References.
- Add explicit not-affiliated-with-OpenCode disclaimer per OpenCode's
  own README request for third-party projects using "opencode" in the
  name.
- Add AI-coding caveat (you're still the reviewer, hallucinations are
  real) at the top.
- Add balanced "When OpenCode isn't the right tool" subsection naming
  Claude Code, Cursor, Aider, Copilot, Codeium, Supermaven as better
  fits for specific use cases.
- All factual claims verified against opencode.ai/docs and the JSON
  config schema. Pricing/model table dated 2026-05-18.

AGENTS.md
- Repurpose from generic React boilerplate to actually describe this
  repo: a documentation guide. Includes editing rules, style guide,
  emoji policy, and "when to update what" matrix.
2026-05-18 19:59:14 +02:00
Wesam Abousaid 0ebc00e33a chore: remove obsolete docs, scaffolding, and third-party assets
- Delete eight pre-refactor doc files under docs/ (AGENTS-GUIDE,
  COMMANDS-REFERENCE, FAQ-TROUBLESHOOTING, MCP-GUIDE, MIGRATION-GUIDE,
  SKILLS-GUIDE, TUI-MASTERY, ZEN-GUIDE). They were inaccurate to current
  OpenCode behavior; replacements land in a follow-up commit.
- Remove .opencode/skills/{pr,review}.md — these were placed as files,
  but OpenCode skills require folder-with-SKILL.md format. Equivalent
  content is being re-shipped as .opencode/commands/ entries.
- Remove Images/opencode.png and opencode-installation.png — these are
  OpenCode's own branding assets; not appropriate to redistribute from
  a non-affiliated community guide.
- Remove Images/.gitkeep — superseded by Images/README.md in a later commit.
2026-05-18 19:59:01 +02:00
Wesam Abousaid 4e08d17321 chore(gitignore): allow tracking .opencode example subdirectories
The previous .gitignore excluded .opencode/agents/, /commands/, and /skills/ —
which prevented committing the very example files this repo is meant to
showcase. Keep user-specific runtime state (cache, logs, sessions, audit log,
local state) ignored; un-ignore the example folders.
2026-05-18 19:58:12 +02:00
Wesam Abousaid efe5c71eeb refactor: remove wrong links resources 2026-02-27 09:38:15 +01:00
Wesam Abousaid 296847155f refactor: update comparison table to be more precise 2026-02-26 23:54:37 +01:00
Wesam Abousaid ebe87d8426 refactor: remove acks from README 2026-02-26 23:34:15 +01:00
Wesam Abousaid 7b684929dc Rewrite README for optimal user onboarding: concise structure, migration guide, improved navigation 2026-02-26 22:33:59 +01:00
Wesam Abousaid 5669921aa5 Add comprehensive .gitignore and reorganize README with Installation before Zen 2026-02-26 22:10:44 +01:00
Wesam Abousaid b63f1c7f57 Initiate OpenCode repo 2026-02-26 22:00:58 +01:00
Wesam Abousaid c5250b0f85 Initial commit 2026-02-26 21:58:09 +01:00