Commit Graph
17 Commits
Author SHA1 Message Date
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