diff --git a/.github/workflows/opencode-smoke.yml b/.github/workflows/opencode-smoke.yml new file mode 100644 index 0000000..5b48fa1 --- /dev/null +++ b/.github/workflows/opencode-smoke.yml @@ -0,0 +1,22 @@ +name: OpenCode smoke + +on: + pull_request: + paths: + - ".opencode/**" + - "skills/**" + - "scripts/opencode-smoke.mjs" + - "package.json" + - ".github/workflows/opencode-smoke.yml" + workflow_dispatch: + +jobs: + opencode-1-18-7: + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "24" + - run: node scripts/opencode-smoke.mjs 1.18.7 diff --git a/.gitignore b/.gitignore index 498fd50..864d962 100644 --- a/.gitignore +++ b/.gitignore @@ -44,6 +44,13 @@ NOTES.md .opencode/local.json .opencode/cache/ +# Local behavioral evaluation reports +.artifacts/behavioral-evals/ + +# Planning docs for behavioral evaluations (not delivered to main) +docs/superpowers/plans/2026-07-30-behavioral-evaluations*.md +docs/superpowers/specs/2026-07-30-behavioral-evaluations*.md + # Node / Bun node_modules/ *.log diff --git a/.opencode/plugins/agent-config.js b/.opencode/plugins/agent-config.js new file mode 100644 index 0000000..65d1e79 --- /dev/null +++ b/.opencode/plugins/agent-config.js @@ -0,0 +1,65 @@ +import { readFileSync } from "fs"; +import path from "path"; + +const AGENT_NAMES = ["code-explorer", "code-architect", "code-reviewer"]; +const READ_ONLY_PERMISSION = { + "*": "deny", + read: { + "*": "allow", + "*.env": "deny", + "*.env.*": "deny", + "*.env.example": "allow", + }, + glob: "allow", + grep: "allow", + list: "allow", + edit: "deny", + task: "deny", + webfetch: "deny", + websearch: "deny", + external_directory: "deny", +}; +const REVIEW_BASH_PERMISSION = { + "*": "deny", + "git status*": "allow", + "git diff*": "allow", + "git show*": "allow", + "git log*": "allow", + "git blame*": "allow", + "git rev-parse*": "allow", + "git merge-base*": "allow", + "git ls-files*": "allow", + "git *--output*": "deny", + "git *--ext-diff*": "deny", + "git *>*": "deny", +}; + +function readSkill(skillsDir, name) { + const source = readFileSync(path.join(skillsDir, name, "SKILL.md"), "utf8"); + const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/); + if (!match) throw new Error(`Invalid frontmatter in ${name}/SKILL.md`); + + const description = match[1] + .split(/\r?\n/) + .find((line) => line.startsWith("description:")) + ?.slice("description:".length) + .trim(); + if (!description) throw new Error(`Missing description in ${name}/SKILL.md`); + + return { description, prompt: match[2].trim() }; +} + +export function loadAgentConfigs(skillsDir) { + return Object.fromEntries(AGENT_NAMES.map((name) => { + const skill = readSkill(skillsDir, name); + const permission = name === "code-reviewer" + ? { ...READ_ONLY_PERMISSION, bash: REVIEW_BASH_PERMISSION } + : { ...READ_ONLY_PERMISSION, bash: "deny" }; + + return [name, { + ...skill, + mode: "subagent", + permission, + }]; + })); +} diff --git a/.opencode/plugins/opencode-power-pack.js b/.opencode/plugins/opencode-power-pack.js index fd4c4fa..6531ee7 100644 --- a/.opencode/plugins/opencode-power-pack.js +++ b/.opencode/plugins/opencode-power-pack.js @@ -7,11 +7,9 @@ * mcp-builder, skill-creator, agents-md-improver, agents-md-revise) without * requiring symlinks or manual config. * - * Slash commands are NOT registered here on purpose — they are provided by - * physical markdown files under `commands/` in this repo, intended to be - * symlinked into `~/.config/opencode/commands/`. Each command file inlines - * the full SKILL.md content, so the model receives the actual workflow as - * its prompt rather than a meta-instruction telling it to load the skill. + * OpenCode 1.18.7+ exposes discovered skills as same-named slash commands. + * The plugin also registers the feature workflow's specialist roles as + * read-only subagents derived from their SKILL.md bodies. * * ──── Attribution ──────────────────────────────────────────────────────── * @@ -28,9 +26,11 @@ import path from 'path'; import { fileURLToPath } from 'url'; +import { loadAgentConfigs } from './agent-config.js'; const __dirname = path.dirname(fileURLToPath(import.meta.url)); const skillsDir = path.resolve(__dirname, '../../skills'); +const bundledAgents = loadAgentConfigs(skillsDir); export const OpencodePowerPack = async () => { return { @@ -40,6 +40,10 @@ export const OpencodePowerPack = async () => { if (!config.skills.paths.includes(skillsDir)) { config.skills.paths.push(skillsDir); } + config.agent = config.agent || {}; + for (const [name, agent] of Object.entries(bundledAgents)) { + if (!config.agent[name]) config.agent[name] = agent; + } }, }; }; diff --git a/README.md b/README.md index 2447d4b..de11a2c 100644 --- a/README.md +++ b/README.md @@ -3,46 +3,67 @@

- Eleven Claude Code skills, ported to OpenCode.
- Code review, security audit, feature dev, frontend design, and the rest of the kit — installable in one line.
+ Eleven Claude Code workflows, adapted for modern OpenCode.
+ Code review, security audit, feature development, frontend design, project memory, and authoring tools.

+<<<<<<< HEAD + License: MIT and Apache-2.0 +======= License: MIT and Apache-2.0 +>>>>>>> origin/main GitHub stars Last commit - Issues - Skills - OpenCode - Claude Code compat + GitHub issues + Skills: 11 + OpenCode 1.18.7+

Install · Skills · Commands · - How it works · - Credits · - License + Architecture · + Credits

+<<<<<<< HEAD +## Why This Exists +=======

Built on top of anthropics/claude-plugins-official, anthropics/skills, anthropics/claude-code-security-review, and obra/superpowers. See Acknowledgments.

+>>>>>>> origin/main ---- +OpenCode reads `SKILL.md` natively, but many valuable Claude Code workflows originated as Claude-specific commands and agents. Copying those artifacts directly does not preserve their orchestration, permissions, or subagent behavior. -## Why this exists +This package adapts the portable methodology into OpenCode skills, registers the feature-development specialist roles as real read-only subagents, and ships immutable provenance for every upstream work. -OpenCode reads Claude Code's `SKILL.md` format natively, but **most of Anthropic's official Claude Code plugins put their value in `commands/` and `agents/`** — and those are Claude-Code-only. So if you want `/code-review`, `/security-review`, or `/feature-dev` in OpenCode, copy-paste won't get you there. +It complements [obra/superpowers](https://github.com/obra/superpowers), which provides process skills such as brainstorming, TDD, debugging, and plan execution. -This pack does the **translation**: the multi-agent workflows from those plugins are rewritten as OpenCode-compatible skills, so the methodology survives the platform jump. Plus a few direct ports of skills that already lived in Anthropic's `skills/` repo. +## What's Inside -It pairs nicely with **[obra/superpowers](https://github.com/obra/superpowers)**, which provides the meta-workflow skills (brainstorming, TDD, executing-plans). This pack adds the domain-specific muscle. +| Category | Skill | Purpose | +|---|---|---| +| Review | `code-review` | Multi-agent PR review with confidence filtering and reproduction scenarios | +| Review | `security-review` | Security-focused review with category coverage and exploit-path validation | +| Feature development | `feature-dev` | Seven-phase workflow from discovery through implementation and review | +| Feature development | `code-explorer` | Trace a feature across entry points, layers, state, and dependencies | +| Feature development | `code-architect` | Produce a file-level architecture and implementation blueprint | +| Feature development | `code-reviewer` | Adversarial review of a focused local change set | +| Design | `frontend-design` | Create distinctive interfaces with an accessibility and craft rubric | +| Authoring | `mcp-builder` | Design and build MCP servers in TypeScript or Python | +| Authoring | `skill-creator` | Create, test, and improve reusable `SKILL.md` workflows | +| Project memory | `agents-md-improver` | Audit project rules and propose targeted improvements | +| Project memory | `agents-md-revise` | Capture durable session learnings in project rules | +<<<<<<< HEAD +`code-explorer`, `code-architect`, and `code-reviewer` are available both as standalone skills and as least-privilege subagents used by `feature-dev`. +======= --- ## What's inside @@ -101,54 +122,32 @@ It pairs nicely with **[obra/superpowers](https://github.com/obra/superpowers)** --- +>>>>>>> origin/main ## Installation ### Prerequisites -- **OpenCode** installed and on your PATH. If you do not have it: -- **git** (used by OpenCode to fetch the plugin) -- **Bun** is bundled with OpenCode, so the plugin's `npm install` step at startup is automatic +- OpenCode 1.18.7 or newer: +- Git, used by OpenCode to fetch Git-based plugins -### Pick an install method +### Install From GitHub -Two paths that work today; pick whichever fits how you plan to use the pack. - -| | **A — Install from GitHub** | **B — Install from a local git clone** | -|---|---|---| -| Best for | Just using the pack | Tinkering, contributing, or running offline | -| Requires | Network during first install | A local clone of the repo | -| Updates | `git pull` + cache clear (the cache holds Bun's checkout) | `git pull` updates everything live; symlinks pick up changes immediately | -| Internet at runtime | Only at first install / on cache miss | Never | - -Both methods share **steps 2 (symlink commands) and 3 (restart)**. Only step 1 differs. - ---- - -### A — Install from GitHub - -**Step 1A.** Add to `~/.config/opencode/opencode.json`: - -```jsonc -{ - "$schema": "https://opencode.ai/config.json", - "plugin": [ - "opencode-power-pack@git+https://github.com/waybarrios/opencode-power-pack.git" - ] -} +```bash +opencode plugin --global "opencode-power-pack@git+https://github.com/waybarrios/opencode-power-pack.git" ``` -If you already use other plugins (e.g. `superpowers`), keep all of them in the array: +Restart OpenCode after installation. OpenCode discovers each skill and creates its same-named slash command automatically. -```jsonc -{ - "plugin": [ - "superpowers@git+https://github.com/obra/superpowers.git", - "opencode-power-pack@git+https://github.com/waybarrios/opencode-power-pack.git" - ] -} +To pin a published release, append its tag: + +```bash +opencode plugin --global "opencode-power-pack@git+https://github.com/waybarrios/opencode-power-pack.git#" ``` +<<<<<<< HEAD +### Install From A Local Clone +======= To pin a specific published tag: ```jsonc @@ -156,267 +155,175 @@ To pin a specific published tag: ``` You still need a local copy of the repo for **step 2** (the slash command files live there). Clone it next to wherever you keep code: +>>>>>>> origin/main ```bash git clone https://github.com/waybarrios/opencode-power-pack.git ~/code/opencode-power-pack +opencode plugin --global "opencode-power-pack@git+file:///home/you/code/opencode-power-pack" ``` -Then jump to **step 2 (symlink commands)** below. +Use an absolute `file://` URL adjusted for your operating system. The target directory must be a Git repository. ---- - -### B — Install from a local git clone - -This avoids the GitHub round-trip entirely. The plugin lives on your disk, and OpenCode reads it via a `file://` URL. - -**Step 1B.1.** Clone the repo wherever you keep code: +### Verify ```bash -git clone https://github.com/waybarrios/opencode-power-pack.git ~/code/opencode-power-pack +opencode debug skill +opencode debug agent code-explorer ``` -If the repo is not yet on GitHub and you only have it locally, skip the clone — just point at the existing directory. - -**Step 1B.2.** Add to `~/.config/opencode/opencode.json`, using the **absolute path** to your clone: - -```jsonc -{ - "$schema": "https://opencode.ai/config.json", - "plugin": [ - "opencode-power-pack@git+file:///Users/you/code/opencode-power-pack" - ] -} -``` - -Notes: - -- The `file://` URL needs to be an **absolute path** with three slashes (`file:///Users/...`) and no trailing slash. -- The directory must be a git repo (have a `.git/`). If you copied the files without git, run `git init && git add . && git commit -m init` inside the directory first — Bun's git-style installer requires a real git tree. -- Updating is just `cd ~/code/opencode-power-pack && git pull`, then clear the cache and restart (see [Updating](#updating)). - -Then continue to **step 2** below. - -### 2. Symlink the slash commands (both methods) - -The plugin auto-registers the skills directory programmatically. Slash commands, however, need to live in OpenCode's canonical commands path; the plugin ships physical markdown files under `commands/` for you to symlink in. - -```bash -mkdir -p ~/.config/opencode/commands -ln -s ~/code/opencode-power-pack/commands/*.md ~/.config/opencode/commands/ -``` - -Adjust the source path if you cloned somewhere other than `~/code/opencode-power-pack`. If a command of the same name already exists in `~/.config/opencode/commands/`, that file wins — `ln -s` will refuse to overwrite, which is the desired behavior. - -If you prefer **copies** over symlinks (e.g. you do not want `git pull` to silently change your commands): - -```bash -cp ~/code/opencode-power-pack/commands/*.md ~/.config/opencode/commands/ -``` - -Trade-off: copies are static — you have to re-copy after every `git pull`. Symlinks track the working tree live. - -### 3. Restart OpenCode (both methods) - -```bash -# kill ALL opencode processes (not just the active TUI) -pkill -f opencode - -# clear the npm-style plugin cache so the new version is fetched fresh -rm -rf ~/.cache/opencode/node_modules/opencode-power-pack 2>/dev/null - -# start again -opencode -``` - -### 4. Verify - -In a new OpenCode session, run: - -``` -List the skills you have available. -``` - -You should see the eleven skills under the `opencode-power-pack:` namespace (or unprefixed, depending on your OpenCode version). - -Then hit **`ctrl+p`** to open the command palette and look for any of: - -- `code-review` -- `security-review` -- `feature-dev` -- `frontend-design` -- `agents-md-improver` - -If they show up, you're done. If not, see [Troubleshooting](#troubleshooting). - ---- +The first command should include all eleven unprefixed skill names. The second should report a `subagent` with editing denied. In the TUI, `ctrl+p` should list `/code-review`, `/feature-dev`, `/frontend-design`, and the other skill-derived commands. ## Updating +For a GitHub installation: + ```bash -# 1. Pull the latest skills + commands -cd ~/code/opencode-power-pack -git pull - -# 2. If new skills were added, the existing symlinks are unaffected, -# but new commands need to be linked in: -ln -s ~/code/opencode-power-pack/commands/*.md ~/.config/opencode/commands/ 2>/dev/null - -# 3. Clear the plugin cache and restart OpenCode -rm -rf ~/.cache/opencode/node_modules/opencode-power-pack -pkill -f opencode -opencode +opencode plugin --global --force "opencode-power-pack@git+https://github.com/waybarrios/opencode-power-pack.git" ``` +<<<<<<< HEAD +Restart OpenCode after the command finishes. For a pinned installation, update the tag first. Local-clone users should run `git pull` in the clone and reinstall with the same `git+file://` spec. +======= If you pinned a version in `opencode.json`, bump the tag in the JSON before restarting, otherwise OpenCode keeps using the pinned commit. --- +>>>>>>> origin/main ## Uninstalling -```bash -# 1. Remove from opencode.json -# delete the "opencode-power-pack@..." line from the "plugin" array - -# 2. Remove the symlinked commands -for f in ~/code/opencode-power-pack/commands/*.md; do - rm -f ~/.config/opencode/commands/"$(basename "$f")" -done - -# 3. Remove the plugin cache -rm -rf ~/.cache/opencode/node_modules/opencode-power-pack - -# 4. Restart OpenCode -pkill -f opencode -opencode - -# 5. Optional: delete the local clone -rm -rf ~/code/opencode-power-pack -``` - -To remove **just one skill** (keeping the rest), delete its symlink only: - -```bash -rm ~/.config/opencode/commands/code-review.md -``` - -The skill itself remains discoverable via the native `skill` tool unless you also remove it from the skills directory, but the slash command will no longer appear. - ---- +Remove the `opencode-power-pack@...` entry from the `plugin` array in the config where it was installed, then restart OpenCode. There are no command symlinks or copied command files to remove. ## Troubleshooting | Symptom | Cause | Fix | |---|---|---| -| `/code-review` not in command palette | Symlinks not in `~/.config/opencode/commands/` | Re-run the `ln -s` step from Installation | -| `/code-review` shows the old meta-prompt ("If the skill is not yet loaded, load it via the native skill tool…") | Stale plugin cache from a pre-`v0.1.0` build | `rm -rf ~/.cache/opencode/node_modules/opencode-power-pack && pkill -f opencode && opencode` | -| Skills do not appear when you run "list available skills" | Plugin entry missing or misspelled in `opencode.json` | Validate JSON: `python3 -m json.tool ~/.config/opencode/opencode.json` | -| Plugin install fails with a git error | Bad URL, network issue, or private repo | Check the `git+...` URL works manually: `git ls-remote ` | -| Symlink command fails on macOS with permission denied | `~/.config/opencode/commands/` does not exist | `mkdir -p ~/.config/opencode/commands` first | -| Command appears but model "rushes" and gives a one-line answer | Local model not following multi-step instructions | Use a stronger backing model. The skill content is correct; small models may still skim. The skills mark themselves as "expected to take multiple minutes" — bigger models honor that. | -| Want to disable for one project | Project-level override | Add `"plugin": []` (empty) to `/.opencode/opencode.json` | +| Skills or commands do not appear | OpenCode is older than 1.18.7 | Upgrade OpenCode, restart, and run `opencode debug skill` | +| Skills are missing from debug output | Plugin installation failed or its config entry is absent | Re-run `opencode plugin --global --force ` and inspect the reported error | +| Specialist agents are missing | Stale plugin checkout | Force reinstall, restart, and run `opencode debug agent code-explorer` | +| Installation reports a Git error | Invalid URL, network failure, or inaccessible repository | Validate the source with `git ls-remote ` | +| A workflow is rushed or incomplete | The backing model skipped multi-stage instructions | Use a stronger model and inspect whether required subagent tools are available | -If none of the above match: `tail -f ~/.cache/opencode/log/*.log` while you start OpenCode and look for plugin-load errors. +## Slash Commands ---- +OpenCode 1.18.7+ automatically exposes every discovered skill as a same-named slash command: ---- - -## Slash commands - -Each skill is exposed as a slash command. The command body inlines the **full skill workflow**, so the model receives the actual instructions as its prompt — not a meta-instruction telling it to load something else. - -``` -/code-review Multi-agent PR review with cross-check and reproduction scenarios -/security-review OWASP-bucketed audit with three-stage filtering and PoC requirement -/feature-dev Start the 7-phase guided feature workflow -/code-explorer Trace a feature deeply across the codebase -/code-architect Produce a complete architecture blueprint for a feature -/code-reviewer Two-pass adversarial review of a small change set -/frontend-design Generate a distinctive frontend with a bold aesthetic direction -/mcp-builder Guide MCP server creation -/skill-creator Author a new SKILL.md -/agents-md-improver Audit and improve AGENTS.md / CLAUDE.md -/agents-md-revise Capture session learnings into the rules file +```text +/code-review +/security-review +/feature-dev +/code-explorer +/code-architect +/code-reviewer +/frontend-design +/mcp-builder +/skill-creator +/agents-md-improver +/agents-md-revise ``` -### Examples +Examples: -``` +```text /code-review --comment -/code-review can you review https://github.com/owner/repo/pull/449 +/code-review review https://github.com/owner/repo/pull/449 /feature-dev add a logout button to the topbar /security-review /frontend-design pricing page, brutalist tone, single-screen -/agents-md-improver ``` -If you have a command of the same name in `~/.config/opencode/commands/foo.md` or under `command` in `opencode.json`, **your version wins** — the plugin only registers the skill discovery path, never overwrites a command. +An explicit command with the same name takes precedence over a skill-derived command. ---- +## How It Works -## How it works - -``` -┌─────────────────────────── opencode-power-pack ────────────────────────────┐ -│ │ -│ .opencode/plugins/opencode-power-pack.js │ -│ ├── exports OpencodePowerPack(ctx) → { config(c) } │ -│ └── pushes skills/ into c.skills.paths (live config singleton) │ -│ │ -│ skills//SKILL.md │ -│ └── frontmatter: name + description (+ license) │ -│ body: the actual workflow the model executes │ -│ │ -│ commands/.md ──symlink──▶ ~/.config/opencode/commands/ │ -│ ├── frontmatter: description (for menu) │ -│ └── body: full inlined SKILL.md content + $ARGUMENTS │ -│ │ -└────────────────────────────────────────────────────────────────────────────┘ +```text +opencode-power-pack +| ++-- .opencode/plugins/opencode-power-pack.js +| +-- registers skills/ in config.skills.paths +| +-- registers code-explorer as a read-only subagent +| +-- registers code-architect as a read-only subagent +| +-- registers code-reviewer with read-only Git commands +| ++-- skills//SKILL.md +| +-- native skill-tool entry +| +-- native same-named slash command +| +-- immutable source and license metadata +| ++-- UPSTREAMS.json + +-- repository, commit, path, blob, date, and adaptation type ``` -**Two surfaces, one source of truth.** The skills directory feeds OpenCode's native `skill` tool (so the model can load any skill on demand). The commands directory feeds the slash-command palette (so you can invoke a skill directly with `/`). Both are generated from the same `SKILL.md` files — edit the SKILL.md, regenerate the command file with the script in the repo, and both paths stay in sync. +Each `SKILL.md` is the single source for its workflow. The plugin derives specialist-agent prompts from those files at startup, so the agent and standalone skill cannot drift apart. Existing user-defined agents with the same names take precedence. -The plugin entry-point only registers the skills path. Slash commands are **physical files**, not programmatic — this avoids OpenCode's runtime-config caching gotchas and means you can edit, symlink, or selectively delete commands without touching code. +The packaged agents deny edits, external network access, and nested tasks. `code-reviewer` additionally allows a narrow set of read-only Git commands. ---- - -## Scope and non-goals +## Scope And Non-Goals | In scope | Out of scope | |---|---| +<<<<<<< HEAD +| Portable Claude Code workflow methodology | Claude Code hook contracts | +| OpenCode-native skills, commands, and subagents | Proprietary or non-redistributable plugins | +| Licensed adaptations with immutable provenance | Automatic trust of third-party skill catalogs | +| Explicit permission boundaries and regression tests | Supporting OpenCode versions older than 1.18.7 | +======= | Porting Claude Code skills where the methodology is portable | Claude Code slash commands ported as Claude-Code-style commands | | Translating commands and agents into SKILL.md format | Claude Code hooks | | Licensed adaptations of upstream skills with immutable provenance | Claude Code output styles | | OpenCode-native slash commands generated from skills | Anything that breaks if you also use Claude Code | --- +>>>>>>> origin/main ## Contributing -Pull requests welcome, especially for: +Contributions are welcome for: -- New skill ports (Trail of Bits security skills, language-specific packs from `wshobson/agents`, document skills, etc.) -- Improvements to existing skill instructions based on real-world failure modes -- Tooling to keep `commands/*.md` in sync with `skills/*/SKILL.md` automatically +- Improvements based on reproducible workflow failures +- Behavioral evaluations and adversarial fixtures +- Portable references and deterministic helper scripts +- New ports with a verified license and immutable upstream source -Skill format must follow the OpenCode spec: +Before opening a PR: -- Directory name matches the `name` frontmatter field -- Lowercase alphanumeric with single hyphens, regex `^[a-z0-9]+(-[a-z0-9]+)*$` -- `description` 1–1024 chars, specific enough to trigger correctly -- Body in markdown, ideally under 500 lines -- Cite the upstream source in `license` frontmatter when porting +```bash +npm test +npm run smoke:opencode +npm pack --dry-run +``` ---- +Live behavioral evaluation is opt-in, needs `OPENCODE_EVAL_MODEL`, and runs only from a source checkout: + +```bash +OPENCODE_EVAL_MODEL=provider/model npm run eval:behavioral +``` + +See [`evals/behavioral/README.md`](evals/behavioral/README.md) for the replay, review, and acceptance workflow. Snapshots are content-addressed evidence from one reviewed model execution, not universal guarantees. + +Every skill must use a lowercase hyphenated directory/name, provide a trigger-specific description, remain under 500 lines where practical, and record its exact upstream in `UPSTREAMS.json`. ## Acknowledgments +<<<<<<< HEAD +The bundled skills are modified upstream works. This repository contributes their OpenCode adaptation, packaging, additional workflow guidance, tests, and compatibility layer. +======= **The bundled skills are modified upstream works.** Most content in `skills/` is adapted from skills, commands, or agent definitions written by **Anthropic**, plus an adaptation of the OpenCode plugin pattern from **Jesse Vincent (obra)**. This repository contributes the OpenCode port, packaging, and additional workflow guidance. Exact sources and Git blobs are recorded in [`UPSTREAMS.json`](UPSTREAMS.json). +>>>>>>> origin/main -### Upstream sources - -| Upstream | Project | What we use from it | +| Upstream | Pinned source | Used for | |---|---|---| +<<<<<<< HEAD +| Anthropic | [`claude-plugins-official@bdca23e8`](https://github.com/anthropics/claude-plugins-official/tree/bdca23e8e46f8832d0030c05804ae207786ae37f) | Code review, feature development, frontend design, and project memory | +| Anthropic | [`skills@5128e186`](https://github.com/anthropics/skills/tree/5128e1865d670f5d6c9cef000e6dfc4e951fb5b9) | MCP Builder and Skill Creator | +| Anthropic | [`claude-code-security-review@0c6a49f1`](https://github.com/anthropics/claude-code-security-review/tree/0c6a49f1fa56a1d472575da86a94dbc1edb78eda) | Security Review | +| Jesse Vincent | [`superpowers@6efe32c9`](https://github.com/obra/superpowers/tree/6efe32c9e2dd002d0c394e861e0529675d1ab32e) | OpenCode plugin registration pattern | + +See [`UPSTREAMS.json`](UPSTREAMS.json) for exact source paths and Git blobs. See [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) for attribution and modification notices. + +## License + +The wrapper code and original project material are MIT-licensed under [LICENSE](LICENSE). Modified skills derived from Anthropic's official plugins and skills are Apache-2.0, except `security-review`, whose upstream is MIT. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), [UPSTREAMS.json](UPSTREAMS.json), and [LICENSES/](LICENSES/) for exact terms. +======= | Anthropic | [`claude-plugins-official/code-review`](https://github.com/anthropics/claude-plugins-official/tree/bdca23e8e46f8832d0030c05804ae207786ae37f/plugins/code-review) | The confidence-filtered parallel-review methodology adapted as `code-review` | | Anthropic | [`claude-plugins-official/feature-dev`](https://github.com/anthropics/claude-plugins-official/tree/bdca23e8e46f8832d0030c05804ae207786ae37f/plugins/feature-dev) | The seven-phase workflow and three specialist roles | | Anthropic | [`claude-plugins-official/frontend-design`](https://github.com/anthropics/claude-plugins-official/tree/bdca23e8e46f8832d0030c05804ae207786ae37f/plugins/frontend-design) | The base `frontend-design` methodology, substantially extended here | @@ -440,3 +347,4 @@ If you are one of the upstream authors and you'd like the attribution worded dif ## License The wrapper code and original project material are MIT-licensed under [LICENSE](LICENSE). Modified skills and command prompts derived from Anthropic's official plugins and skills are Apache-2.0, except `security-review`, whose upstream is MIT. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), [UPSTREAMS.json](UPSTREAMS.json), and [LICENSES/](LICENSES/) for exact terms and sources. +>>>>>>> origin/main diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index c10b4b9..a6fde65 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -4,10 +4,17 @@ The repository wrapper, plugin integration, packaging, tests, and original documentation are licensed under the root MIT `LICENSE` unless a file states otherwise. +<<<<<<< HEAD +The skills are modified derivatives of the sources recorded in +`UPSTREAMS.json`. They are not represented as original work. Every entry +records the immutable upstream commit, source path, Git blob, license, and +adaptation type reviewed for this distribution. +======= The skills and generated command prompts are modified derivatives of the sources recorded in `UPSTREAMS.json`. They are not represented as original work. Every entry records the immutable upstream commit, source path, Git blob, license, and adaptation type reviewed for this distribution. +>>>>>>> origin/main ## Anthropic Official Plugins diff --git a/commands/agents-md-improver.md b/commands/agents-md-improver.md deleted file mode 100644 index 787a4ed..0000000 --- a/commands/agents-md-improver.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -description: Audit and improve project-rules files (AGENTS.md, CLAUDE.md, .agents/instructions, local overrides) so the agent keeps accurate project context. Use when the user asks to check, audit, review, update, improve, or fix their AGENTS.md or CLAUDE.md, mentions "project rules maintenance" or "agent context optimization", or when the codebase has changed enough that the rules file may be stale. Scans the repository for every rules file, grades each against a quality rubric, outputs a quality report, and applies targeted edits only after user approval. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# AGENTS.md / CLAUDE.md Improver - -Audit, evaluate, and improve project-rules files across a codebase to ensure the agent has optimal project context. - -OpenCode resolves project rules **first-match-wins per directory**: when a directory holds both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is loaded and the `CLAUDE.md` is never read. Resolution walks from the working directory up to the git root, takes the first match at each level, and merges those with the global `~/.config/opencode/AGENTS.md` and any paths declared in the `instructions` field of `opencode.json`. Treat `AGENTS.md` as canonical when creating new files, and report any directory that contains both files as a finding, since its `CLAUDE.md` is silently ignored. - -**This skill can write to project-rules files.** After presenting a quality report and getting user approval, it updates the files with targeted improvements. - -## Workflow - -### Phase 1: Discovery - -Find all relevant files in the repository: - -```bash -find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name ".claude.local.md" -o -name ".agents.local.md" \) 2>/dev/null | head -50 -``` - -**File types and locations:** - -| Type | Location | Purpose | -|------|----------|---------| -| Project root (OpenCode native) | `./AGENTS.md` | Primary project context (committed, shared) | -| Project root (Claude compat) | `./CLAUDE.md` | Same purpose; OpenCode reads it as fallback | -| Local overrides | `./.agents.local.md` or `./.claude.local.md` | Personal/local settings (gitignored) | -| Global defaults | `~/.config/opencode/AGENTS.md` or `~/.claude/CLAUDE.md` | User-wide defaults | -| Package-specific | `./packages/*/AGENTS.md` | Module-level context in monorepos | -| Subdirectory | Any nested location | Feature/domain-specific context | - -OpenCode walks up from the working directory toward the git root, loading any matching rules files along the way, so monorepos and nested projects work automatically. - -### Phase 2: Quality assessment - -For each rules file, evaluate against the criteria below. - -**Quick assessment checklist:** - -| Criterion | Weight | Check | -|-----------|--------|-------| -| Commands / workflows documented | High | Are build / test / deploy commands present? | -| Architecture clarity | High | Can the agent understand the codebase structure? | -| Non-obvious patterns | Medium | Are gotchas and quirks documented? | -| Conciseness | Medium | No verbose explanations or obvious info? | -| Currency | High | Does it reflect the current codebase state? | -| Actionability | High | Are instructions executable, not vague? | - -**Quality scores:** - -- **A (90–100)** — Comprehensive, current, actionable. -- **B (70–89)** — Good coverage, minor gaps. -- **C (50–69)** — Basic info, missing key sections. -- **D (30–49)** — Sparse or outdated. -- **F (0–29)** — Missing or severely outdated. - -### Phase 3: Quality-report output - -**Always output the quality report BEFORE making any updates.** - -Format: - -``` -## Project-Rules Quality Report - -### Summary -- Files found: X -- Average score: X/100 -- Files needing update: X - -### File-by-File Assessment - -#### 1. ./AGENTS.md (Project Root) -**Score: XX/100 (Grade: X)** - -| Criterion | Score | Notes | -|-----------|-------|-------| -| Commands / workflows | X/20 | ... | -| Architecture clarity | X/20 | ... | -| Non-obvious patterns | X/15 | ... | -| Conciseness | X/15 | ... | -| Currency | X/15 | ... | -| Actionability | X/15 | ... | - -**Issues:** -- [List specific problems] - -**Recommended additions:** -- [List what should be added] - -#### 2. ./packages/api/AGENTS.md (Package-specific) -... -``` - -### Phase 4: Targeted updates - -After the quality report, ask the user for confirmation before updating. - -**Update guidelines (critical):** - -1. **Propose targeted additions only.** Focus on genuinely useful info: - - Commands or workflows discovered during analysis - - Gotchas or non-obvious patterns found in code - - Package relationships that were unclear - - Testing approaches that work - - Configuration quirks - -2. **Keep it minimal.** Avoid: - - Restating what is obvious from the code - - Generic best practices already covered - - One-off fixes unlikely to recur - - Verbose explanations when a one-liner suffices - -3. **Show diffs.** For each change, show: - - Which file to update - - The specific addition (diff or quoted block) - - A brief explanation of why this helps future sessions - -**Diff format:** - -````markdown -### Update: ./AGENTS.md - -**Why:** Build command was missing, causing confusion about how to run the project. - -```diff -+ ## Quick Start -+ -+ ```bash -+ npm install -+ npm run dev # Start development server on port 3000 -+ ``` -``` -```` - -### Phase 5: Apply updates - -After user approval, apply changes using the editor tool. Preserve the existing content structure; only add what was approved. - -## Common issues to flag - -1. **Stale commands** — build commands that no longer work. -2. **Missing dependencies** — required tools not mentioned. -3. **Outdated architecture** — file structure that has changed. -4. **Missing environment setup** — required env vars or config. -5. **Broken test commands** — test scripts that have changed. -6. **Undocumented gotchas** — non-obvious patterns not captured. -7. **Shadowed `CLAUDE.md`** — a directory that contains both `AGENTS.md` and `CLAUDE.md`. OpenCode loads only `AGENTS.md`, so the `CLAUDE.md` is silently ignored; merge its contents into `AGENTS.md` or remove it. - -## What makes a great rules file - -**Key principles:** - -- Concise and human-readable. -- Actionable commands that can be copy-pasted. -- Project-specific patterns, not generic advice. -- Non-obvious gotchas and warnings. - -**Recommended sections** (use only what is relevant): - -- Commands (build, test, dev, lint) -- Architecture (directory structure) -- Key files (entry points, config) -- Code style (project conventions) -- Environment (required vars, setup) -- Testing (commands, patterns) -- Gotchas (quirks, common mistakes) -- Workflow (when to do what) - -## Tips to share with the user - -- **Keep it concise** — the rules file is part of the prompt, so brevity matters. Dense is better than verbose. -- **Actionable commands** — all documented commands should be copy-paste ready. -- **Use a `.local` override** — for personal preferences not shared with the team (add to `.gitignore`). -- **Global defaults** — put user-wide preferences in `~/.config/opencode/AGENTS.md` (or `~/.claude/CLAUDE.md`). -- **Prefer `AGENTS.md`.** Use `AGENTS.md` for new rules files: OpenCode reads it natively and Claude Code reads it as a fallback. Do not add an `AGENTS.md` alongside an existing `CLAUDE.md` — under first-match-wins, OpenCode would load only the `AGENTS.md` and ignore the `CLAUDE.md` entirely. Either keep maintaining the `CLAUDE.md` in place, or migrate its contents into `AGENTS.md` and remove it. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/agents-md-revise.md b/commands/agents-md-revise.md deleted file mode 100644 index 3ca925c..0000000 --- a/commands/agents-md-revise.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -description: Capture learnings from the current session into the project-rules file (AGENTS.md, CLAUDE.md, or local override) so future sessions benefit. Use when the user says "revise the rules", "update AGENTS.md / CLAUDE.md with what we just learned", "save this to project memory", "remember this for next time", or at the end of a productive session when valuable context has emerged that is not yet documented. This is the COMPLEMENT to agents-md-improver: improver audits, this one captures. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# AGENTS.md / CLAUDE.md Revise - -Review the current session for learnings about working in this codebase, then update the project-rules file with context that would help future sessions be more effective. - -OpenCode resolves project rules first-match-wins per directory: if a directory holds both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is loaded and the `CLAUDE.md` is never read. When capturing learnings, prefer `AGENTS.md` for a new file; if both already exist in the same directory, write to `AGENTS.md` — never into the shadowed `CLAUDE.md`, or the notes land in a file OpenCode ignores. If only `CLAUDE.md` exists, update it in place (and consider migrating it to `AGENTS.md`). - -## Step 1 — Reflect - -Look back over the session and identify what context was missing that would have helped the agent work more effectively. Examples: - -- Bash commands that were used or discovered -- Code-style patterns followed -- Testing approaches that worked -- Environment / configuration quirks -- Warnings or gotchas encountered -- Build steps that surprised you -- Tool versions that mattered -- Project-specific conventions that took time to figure out - -Be selective. Only capture things that: - -1. Will recur in future sessions (not one-off fixes). -2. Would have saved time if known up front. -3. Cannot be derived by reading the code. - -## Step 2 — Find rules files - -```bash -find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name ".agents.local.md" -o -name ".claude.local.md" \) 2>/dev/null | head -20 -``` - -Decide where each addition belongs: - -- **`AGENTS.md` / `CLAUDE.md`** — team-shared, committed to git. Use for project-wide conventions, build commands, architectural notes. -- **`.agents.local.md` / `.claude.local.md`** — personal / local only, gitignored. Use for personal preferences that should not affect teammates. - -If both `AGENTS.md` and `CLAUDE.md` exist in the same directory, target `AGENTS.md` — OpenCode ignores the co-located `CLAUDE.md`, so anything written there is lost. - -If no rules file exists yet, propose creating `AGENTS.md` at the project root. - -## Step 3 — Draft additions - -**Keep it concise.** The rules file is part of every prompt, so brevity matters. One line per concept when possible. - -Format: ` — ` - -**Avoid:** - -- Verbose explanations -- Obvious information that any reader of the code would already know -- One-off fixes unlikely to recur -- Restating what is already documented elsewhere in the rules file - -**Prefer:** - -- Imperative commands ("Run `pnpm i --frozen-lockfile` after pulling") -- Concrete gotchas ("The `dev` script binds to port 3000 — kill any other process on that port first") -- Project-specific patterns ("All dates are stored in UTC; convert at the boundary") - -## Step 4 — Show proposed changes - -For each addition, show the user the diff before applying. Format: - -````markdown -### Update: ./AGENTS.md - -**Why:** [one-line reason this matters for future sessions] - -```diff -+ [the addition — keep it brief] -``` -```` - -If multiple additions go to the same file, group them under one header so the user can review the whole change in one view. - -## Step 5 — Apply with approval - -Ask the user explicitly: *"Apply these changes?"* Edit only files they approve. - -Preserve the existing structure. Place additions in the most relevant section (e.g., a new build command goes under "Commands" if that section exists). If no obvious section fits, create one with a clear header. - -If the user rejects an addition, do not retry it in the same session — they may have a reason. Move on. - -## Notes - -- This skill **writes** to project files. Always show the diff first and wait for approval. -- Pair this skill with `agents-md-improver` for the full maintenance loop: improver audits and identifies gaps; this one captures fresh session-specific learnings. -- Do not include sensitive information (API keys, tokens, internal URLs) in committed rules files. Put those in `.agents.local.md` / `.claude.local.md` or in environment variables. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/code-architect.md b/commands/code-architect.md deleted file mode 100644 index e2c3c67..0000000 --- a/commands/code-architect.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -description: Design a feature architecture by analyzing existing codebase patterns and conventions, then provide a comprehensive implementation blueprint with specific files to create or modify, component designs, data flows, and a build sequence. Use this skill when the user asks for an architecture design, an implementation plan for a non-trivial feature, or when dispatched as a sub-task during feature-dev architecture phase. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Code Architect - -You are a senior software architect who delivers comprehensive, actionable architecture blueprints by deeply understanding codebases and making confident architectural decisions. - -## Working discipline - -These bias toward caution over speed — use judgment on trivial tasks. - -- **Think before acting** — state assumptions; if the request has more than one reading, surface them instead of silently choosing; if a simpler path exists, say so. -- **Simplicity first** — the minimum that solves the problem; no speculative features, abstractions, configurability, or handling of impossible cases. -- **Surgical changes** — touch only what the task needs; do not refactor or restyle adjacent code; match existing style; clean up only the orphans your change created, and mention unrelated dead code rather than deleting it. -- **Goal-driven** — turn the task into a concrete success check and iterate until it passes. - -## Core process - -### 1. Codebase pattern analysis - -Extract existing patterns, conventions, and architectural decisions. Identify: - -- The technology stack -- Module boundaries and abstraction layers -- Project guidelines (`CLAUDE.md` / `AGENTS.md`) -- Similar features already implemented — how were they structured? -- Key abstractions the codebase already provides - -### 2. Architecture design - -Based on patterns found, design the complete feature architecture: - -- Make decisive choices. Pick one approach and commit to it. -- Ensure seamless integration with existing code. -- Design for testability, performance, and maintainability. - -### 3. Complete implementation blueprint - -Specify every file to create or modify, component responsibilities, integration points, and data flow. Break the implementation into clear phases. - -## Output - -Deliver a decisive, complete architecture blueprint. Include: - -- **Patterns & conventions found** — list existing patterns with `file:line` references, similar features, and key abstractions to leverage. -- **Architecture decision** — your chosen approach with rationale and trade-offs. -- **Component design** — each component with its file path, responsibilities, dependencies, and interfaces. -- **Implementation map** — specific files to create or modify, with detailed change descriptions. -- **Data flow** — complete flow from entry points through transformations to outputs. -- **Build sequence** — phased implementation steps as a checklist. -- **Critical details** — error handling, state management, testing approach, performance, security. - -Make confident architectural choices. Be specific and actionable: provide file paths, function names, and concrete steps. Avoid presenting multiple equally-weighted options unless the user specifically asked for trade-off analysis. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/code-explorer.md b/commands/code-explorer.md deleted file mode 100644 index fcb15c9..0000000 --- a/commands/code-explorer.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -description: Deeply analyze an existing codebase feature by tracing execution paths, mapping architecture layers, understanding patterns and abstractions, and documenting dependencies. Use this skill when you need to understand how a feature works before modifying or extending it, when dispatched as a sub-task during feature-dev exploration, or when the user asks "how does X work in this codebase". -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Code Explorer - -You are an expert code analyst specializing in tracing and understanding feature implementations across codebases. - -## Core mission - -Provide a complete understanding of how a specific feature works by tracing its implementation from entry points to data storage, through all abstraction layers. - -## Analysis approach - -### 1. Feature discovery - -- Find entry points: APIs, UI components, CLI commands. -- Locate core implementation files. -- Map feature boundaries and configuration surface. - -### 2. Code-flow tracing - -- Follow call chains from entry to output. -- Trace data transformations at each step. -- Identify all dependencies and integrations. -- Document state changes and side effects. - -### 3. Architecture analysis - -- Map abstraction layers: presentation → business logic → data. -- Identify design patterns and architectural decisions. -- Document interfaces between components. -- Note cross-cutting concerns: auth, logging, caching, observability. - -### 4. Implementation details - -- Key algorithms and data structures. -- Error handling and edge cases. -- Performance considerations. -- Technical debt or improvement areas. - -## Output - -Deliver a comprehensive analysis that helps developers understand the feature deeply enough to modify or extend it. Always include: - -- **Entry points** with `file:line` references -- **Step-by-step execution flow** with data transformations -- **Key components** and their responsibilities -- **Architecture insights** — patterns, layers, design decisions -- **Dependencies** — internal and external -- **Observations** about strengths, issues, or opportunities -- **Essential files list** — the files a developer absolutely must read to understand this topic - -Structure the response for maximum clarity and usefulness. Always cite specific file paths and line numbers. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/code-review.md b/commands/code-review.md deleted file mode 100644 index a7f2f8e..0000000 --- a/commands/code-review.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -description: Review a pull request or a set of code changes for bugs, logic errors, and project-convention violations using a confidence-filtered, multi-agent process. Use this skill when the user asks to review a PR, audit pending changes, or inspect a diff for problems before merging. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Code Review - -Provide a high-signal code review for a pull request or set of pending changes. The goal is to surface only issues that are clearly real and actionable, while filtering out noise, nitpicks, and false positives. - -## When to use this skill - -Trigger on phrases like "review this PR", "code review", "check my diff", "audit the pending changes on this branch", or when the user asks for a security/quality pass before merging. - -## High-level process - -Follow these steps in order. Use OpenCode's parallel sub-task dispatch where the original Claude Code workflow used parallel agents. - -### 1. Pre-flight check - -Before doing any review work, verify the PR (or change set) is worth reviewing. Skip the review and stop early if any of the following hold: - -- The PR is closed -- The PR is a draft -- The change is trivial (single-line typo, formatting, automated dependency bump) and obviously correct -- A previous review by the agent already exists on this PR - -Use `gh pr view ` (or the local `git diff` for non-PR review) to gather state. - -### 2. Identify project conventions - -Build a list of all project-convention files relevant to the change: - -- The repository root `CLAUDE.md` / `AGENTS.md` (whichever exists) -- Any nested `CLAUDE.md` / `AGENTS.md` in directories containing modified files - -You only need the file paths at this stage, not the contents. - -### 3. Summarize the change - -Read `gh pr view --json title,body` and `gh pr diff` (or `git diff`) and produce a one-paragraph summary of what the PR is doing and why. This grounds the rest of the review. - -### 4. Parallel issue detection (deep mode) - -Dispatch **seven independent reviewers** in parallel. Each returns a list of candidate issues, where each issue includes a description, a reason category, an initial confidence (0–100), and a one-sentence failure scenario explaining how this would manifest in practice. - -- **Reviewer 1 + Reviewer 2 — Convention compliance.** Audit the diff against the relevant `CLAUDE.md` / `AGENTS.md` rules. Only consider rule files that apply to the file being reviewed (same path or ancestor directory). Quote the exact rule being violated. -- **Reviewer 3 — Diff-only bug scan.** Scan the diff for obvious bugs without reading surrounding files. Flag only clear issues that do not need unseen context. -- **Reviewer 4 — Deep-context bug scan.** Read the **full file(s)** for each changed function, not just the diff hunks. Trace data flow into and out of the changed code. Flag bugs that depend on context the diff alone does not show (e.g., callers that pass `None`, shared state mutated elsewhere, lock ordering across files). -- **Reviewer 5 — Concurrency, ordering & state.** Race conditions, time-of-check-time-of-use, cache invalidation, idempotency, retry safety, ordering guarantees. Especially important in PRs that touch caches, queues, locks, or any shared mutable state. -- **Reviewer 6 — Error handling & edge cases.** What happens on empty input, max input, partial failure, downstream errors, network timeouts, malformed data? Is failure logged, swallowed, or propagated? Are exceptions caught at the right layer? -- **Reviewer 7 — Test coverage gap.** What scenarios in the changed code are *not* covered by existing tests? List them concretely (no generic "needs more tests"). Especially flag changed branches with no test exercising them. - -Each reviewer must receive the PR title, description, and the relevant project rules. Take the time to read the actual files; do not rely on the diff alone for reviewers 4–7. - -**Critical: only HIGH-SIGNAL issues should be flagged.** Do flag: -- Code that will fail to compile or parse (syntax, type errors, missing imports) -- Code that will definitely produce wrong results regardless of inputs -- Clear, unambiguous convention violations (must quote the exact rule) -- Concrete edge cases that are reachable in production with a specific trigger -- Scope creep — code that adds abstractions, configurability, or features that do not trace to the change's stated goal - -Do NOT flag: -- Style or quality concerns that aren't in the project rules -- Potential issues that depend on specific runtime state or inputs -- Subjective suggestions -- Anything a linter would catch — you are not the linter -- Pre-existing issues -- Issues silenced via lint-ignore comments - -When uncertain, do not flag. False positives erode trust. - -### 5. Cross-check pass - -Before validation, dispatch a **second-pass reviewer** that explicitly tries to **break** each candidate finding: - -- For each candidate, ask: "What is the strongest argument this is *not* a real issue?" Write that argument out. -- If the strongest counter-argument holds, drop the finding before validation (it is likely a false positive). -- If the candidate survives, keep it for validation in step 6. - -This pass exists to catch the failure mode of "looks suspicious but is actually correct in this codebase". - -### 6. Validate each surviving issue - -For each candidate from step 5, dispatch a validator sub-task. Give it the PR title, description, the exact issue description, and the failure scenario. Its job is to verify with high confidence that the issue is real: - -- For "variable not defined" → verify it is actually undefined in the relevant scope by reading the imports and surrounding code. -- For convention violations → verify the rule applies to the file's path and is genuinely violated. Quote the rule. -- For concurrency / state issues → trace the state through at least two callers and confirm the unsafe interleaving is reachable. -- For edge cases → identify the specific input or condition that triggers the failure. - -For each validated issue, the validator must produce: -1. A re-stated confidence score (0–100). Drop anything below 80. -2. A 1–3 line **reproduction scenario**: concrete inputs or conditions that trigger the failure. -3. A pointer to the smallest test that would have caught this (if no such test exists, that goes in the suggested fix). - -Drop any issue the validator cannot confirm with confidence ≥ 80 *and* a concrete reproduction scenario. - -### 7. Output - -Output a summary to the terminal. For each validated issue include: - -- File path and line number -- Severity (Critical / Important) -- Confidence (0–100) -- One-sentence problem statement -- 1–3 line reproduction scenario from step 6 -- Concrete fix suggestion (or path to add a missing test) -- The exact rule or bug category - -Group by severity. If no issues were validated, output exactly: `No issues found. Checked for bugs, edge cases, concurrency, and project-convention compliance.` - -This review is expected to take multiple minutes when run on a non-trivial PR. Quality and concrete reproduction scenarios are the deliverable; if you find yourself finishing in seconds, you have skipped steps 4–6. - -### 8. Optional GitHub posting - -If the user invoked the review with a `--comment` style instruction (i.e. "post the review on the PR"): - -- If no issues found, post the summary as a single PR comment via `gh pr comment` -- If issues found, post one inline comment per issue using the GitHub inline-comment API. Do not duplicate comments. Include a link to the relevant code with the format: - ``` - https://github.com///blob//#L-L - ``` - Always provide the full SHA (no shell substitution), include 1+ line of context above and below, and use `L-L` format. - -For small, self-contained fixes, include a committable suggestion block. For larger fixes (6+ lines, multi-location, or structural), describe the issue and suggested fix without a suggestion block. Never post a committable suggestion unless committing it fixes the issue entirely. - -## Notes - -- Use `gh` CLI for all GitHub interactions; do not use web fetch -- Keep a todo list for the steps above -- Cite each issue with a link when posting - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/code-reviewer.md b/commands/code-reviewer.md deleted file mode 100644 index 5004c01..0000000 --- a/commands/code-reviewer.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -description: Review code for bugs, logic errors, security vulnerabilities, code quality issues, and adherence to project conventions, using confidence-based filtering to report only high-priority issues that truly matter. Use this skill when reviewing a small set of changes locally (such as unstaged diff), when dispatched as a sub-task during feature-dev quality review, or when the user wants a critique of a specific file or function. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Code Reviewer - -You are an expert code reviewer specializing in modern software development across multiple languages and frameworks. Your primary responsibility is to review code against project guidelines (typically `CLAUDE.md` or `AGENTS.md`) with high precision to minimize false positives. - -## Scope - -By default, review unstaged changes from `git diff`. The user may specify different files, a commit range, or a specific function to review. - -## Required reading depth - -Do not review from the diff alone. For each function or class touched by the change: - -1. Read the **entire file** containing it, not just the changed hunks. -2. Identify and read at least **one caller** of the changed code (search with grep / glob for call sites). -3. If the change touches shared state (caches, globals, locks, queues, modules with module-level data), trace at least one path that mutates and one path that reads that state. - -This reading is the input to the analysis below. Skipping it is the most common cause of both false positives and missed bugs. - -## Core review responsibilities - -### Project-guidelines compliance - -Verify adherence to explicit project rules: - -- Import patterns -- Framework conventions -- Language-specific style -- Function declarations -- Error handling and logging conventions -- Testing practices -- Platform compatibility -- Naming conventions - -### Bug detection - -Identify actual bugs that will impact functionality: - -- Logic errors -- Null / undefined handling -- Race conditions -- Memory leaks -- Security vulnerabilities -- Performance problems - -### Code quality - -Evaluate significant issues: - -- Code duplication -- Missing critical error handling -- Accessibility problems -- Inadequate test coverage -- Scope creep — speculative abstractions, configurability, or features that do not trace to the change's goal - -## Multi-pass analysis - -Do **two analysis passes**, not one. The first pass is broad; the second pass is adversarial. - -### Pass 1 — Broad scan - -Walk through every changed function and check it against the four review categories above (project-guidelines compliance, bug detection, code quality, edge cases). Produce a candidate list with initial confidence scores. - -### Pass 2 — Adversarial / edge-case pass - -For every candidate from pass 1, AND for every changed function regardless of whether it raised a flag in pass 1, ask the following questions explicitly. Each one should produce either a "no issue here" line or a new candidate. - -- What happens with empty / `None` / zero-length input? -- What happens with the maximum input size or boundary value? -- What happens if a downstream call fails or times out? -- Is there shared mutable state? Can two callers race? -- Does the cache (or memoization, or singleton) invalidate on every relevant change, or only some? Could it serve a stale value? -- Is there a comparison or check that uses a length, count, or hash where the underlying values can change while preserving that key? (Common cache-invalidation bug pattern.) -- For each new branch, is there a test that exercises it? If not, that is a candidate. -- Could an exception silently swallow a real failure? - -For every candidate from either pass, write a one-sentence **reproduction scenario** that names a concrete input or condition triggering the failure. If you cannot write one, drop the candidate before scoring. - -## Confidence scoring - -Rate each potential issue on 0–100: - -- **0** — Not confident at all. False positive, or pre-existing. -- **25** — Somewhat confident. Might be real, might be a false positive. If stylistic and not in project rules, lower. -- **50** — Moderately confident. Real issue, but possibly a nitpick or rare in practice. Not very important relative to the rest of the changes. -- **75** — Highly confident. Verified twice. Likely to be hit in practice. The existing approach is insufficient. Important and impacts functionality, or directly mentioned in project guidelines. -- **100** — Absolutely certain. Confirmed this will happen frequently. Direct evidence. - -**Only report issues with confidence ≥ 80.** Quality over quantity. - -## Output - -Start by stating clearly what you are reviewing (files, scope, branch). - -For each high-confidence issue, provide: - -- Clear description with confidence score -- File path and line number -- Specific project-guideline reference or bug explanation -- **Reproduction scenario** from the multi-pass analysis (concrete inputs or conditions that trigger the failure) -- Concrete fix suggestion (and where to add a test if none exists) - -Group issues by severity (Critical vs. Important). - -If no high-confidence issues exist, confirm the code meets standards with a brief summary that lists the four categories you checked and the multi-pass questions you asked. - -Structure the response for maximum actionability. The developer should know exactly what to fix and why. - -A thorough review of a non-trivial change set will take multiple minutes. If you finish in under a minute on a non-trivial PR, you have skipped the required reading depth or the multi-pass analysis. Do not rush. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/feature-dev.md b/commands/feature-dev.md deleted file mode 100644 index a67903a..0000000 --- a/commands/feature-dev.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -description: Guide a feature implementation through a structured seven-phase workflow with deep codebase understanding, clarifying questions, parallel architecture design, and quality review. Use this skill when the user asks to build a new feature, add functionality, or wants a methodical approach to implementation rather than diving straight to code. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Feature Development - -Help a developer implement a new feature systematically. Understand the codebase deeply, identify and ask about underspecified details, design elegant architectures, then implement. - -## Core principles - -- **Ask clarifying questions** — Identify ambiguities, edge cases, and underspecified behaviors. Ask specific, concrete questions rather than making assumptions. Wait for user answers before proceeding. -- **Understand before acting** — Read and comprehend existing code patterns first. -- **Read files identified by sub-tasks** — When dispatching code-explorer sub-tasks, ask them to return lists of the most important files to read. After they complete, read those files yourself to build detailed context. -- **Simple and elegant** — Prioritize readable, maintainable, architecturally sound code. -- **Track progress** — Use a todo list throughout. - -## Working discipline - -These bias toward caution over speed — use judgment on trivial tasks. - -- **Think before acting** — state assumptions; if the request has more than one reading, surface them instead of silently choosing; if a simpler path exists, say so. -- **Simplicity first** — the minimum that solves the problem; no speculative features, abstractions, configurability, or handling of impossible cases. -- **Surgical changes** — touch only what the task needs; do not refactor or restyle adjacent code; match existing style; clean up only the orphans your change created, and mention unrelated dead code rather than deleting it. -- **Goal-driven** — turn the task into a concrete success check and iterate until it passes. - -## Phase 1: Discovery - -Goal: Understand what needs to be built. - -1. Create a todo list covering all seven phases. -2. If the feature is unclear, ask the user: - - What problem are they solving? - - What should the feature do? - - Any constraints or requirements? -3. Summarize your understanding and confirm with the user before proceeding. - -## Phase 2: Codebase exploration - -Goal: Understand relevant existing code at both high and low levels. - -1. Dispatch 2–3 `code-explorer` sub-tasks in parallel. Each should: - - Trace through the code comprehensively, focusing on abstractions, architecture, and control flow. - - Target a different aspect (similar features, high-level architecture, UX, extension points). - - Return a list of 5–10 key files to read. -2. After they return, read every file they identified to build deep understanding. -3. Present a comprehensive summary of findings and patterns to the user. - -## Phase 3: Clarifying questions - -Goal: Fill gaps and resolve ambiguities before designing. - -**This is one of the most important phases. Do not skip.** - -1. Review the codebase findings and the original feature request. -2. Identify underspecified aspects: edge cases, error handling, integration points, scope boundaries, design preferences, backward compatibility, performance. -3. Present all questions to the user as a clear, organized list. -4. **Wait for answers** before moving to architecture. - -If the user says "whatever you think is best", make your recommendation explicit and get confirmation. - -## Phase 4: Architecture design - -Goal: Design multiple implementation approaches with different trade-offs. - -1. Dispatch 2–3 `code-architect` sub-tasks in parallel, each with a different focus: - - **Minimal changes** — smallest diff, maximum reuse of existing code. - - **Clean architecture** — maintainability, elegant abstractions. - - **Pragmatic balance** — speed plus quality. -2. Review all approaches and form an opinion on which fits best for this task. Consider scope (small fix vs. large feature), urgency, complexity, and team context. -3. Present to the user: a brief summary of each approach, a trade-offs comparison, your recommendation with reasoning, and concrete differences in implementation. -4. **Ask the user which approach they prefer.** - -## Phase 5: Implementation - -Goal: Build the feature. - -**Do not start without explicit user approval.** - -1. Wait for approval. -2. Re-read all relevant files identified earlier. -3. Implement following the chosen architecture. -4. Strictly follow codebase conventions (naming, style, error-handling patterns). -5. Update todos as you progress. - -## Phase 6: Quality review - -Goal: Ensure the code is simple, DRY, elegant, readable, and correct. - -1. Dispatch 3 `code-reviewer` sub-tasks in parallel, each with a different focus: - - Simplicity / DRY / elegance - - Bugs / functional correctness - - Project conventions and abstractions -2. Consolidate findings and rank issues by severity. -3. Present findings to the user and ask what they want to do (fix now, fix later, proceed as-is). -4. Address issues based on their decision. - -## Phase 7: Summary - -Goal: Document what was accomplished. - -1. Mark all todos complete. -2. Summarize: - - What was built - - Key decisions made - - Files modified - - Suggested next steps - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/frontend-design.md b/commands/frontend-design.md deleted file mode 100644 index a6fc9e0..0000000 --- a/commands/frontend-design.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -description: Create distinctive, production-grade frontend interfaces with high design quality and accessible markup. Use this skill when the user asks to build or beautify web components, pages, applications, landing pages, dashboards, artifacts, or React/HTML/CSS UI. Generates creative, polished code that avoids generic AI aesthetics, then self-checks it against an objective accessibility and quality rubric. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices, then audit it against the self-critique rubric before returning. - -The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints. - -## Design Thinking - -Before coding, understand the context and commit to a BOLD aesthetic direction: - -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity. - -Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is: - -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -Focus on: - -- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font. -- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. -- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise. -- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density. -- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays. - -NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations. - -**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well. - -Remember: the model is capable of extraordinary creative work. Don't hold back; show what can truly be created when thinking outside the box and committing fully to a distinctive vision. - -## Concrete moves (counter the defaults) - -Left to its own devices a model drifts to the statistical center — white background, a blue or purple button, the Inter typeface, a single centered card or a three-column grid. Counter each default on purpose: - -- **Typography**: commit to one distinctive family that fits the direction — editorial → Fraunces, Playfair Display, Crimson Pro; product → Clash Display, Satoshi, Cabinet Grotesk; technical → IBM Plex, Source Sans 3; code → JetBrains Mono, Fira Code. Reach for real contrast: extreme weight pairs (200 against 800, not 400 against 600) and size jumps of 3x or more. Avoid Space Grotesk — good, but a known convergence trap. -- **Layout**: name an archetype before you build — bento grid, split-screen, asymmetric or broken grid, magazine, sidebar — rather than letting it fall back to a centered column. A bento grid (varied block sizes, largest element first) gives dashboards structure without the uniform "AI" look. -- **Color**: a dominant color with one sharp accent beats a timid, evenly spread palette. Anchor it to a concrete reference — an IDE theme, a cultural or era aesthetic — not generic brand-blue, and give color semantic meaning where it helps. -- **Tokens and theming**: route every color, space, radius, and shadow value through CSS custom properties; never scatter magic numbers. Implement dark mode by redefining those variables under `.dark`, not by restyling. If the user already has a brand or design system, inject its tokens and skip your defaults entirely. -- **Inspiration over adjectives**: anchor the work to a specific source — a material, an era, a piece of software — instead of "modern and clean", which collapses straight back to the default. -- **Vary across generations**: the font and layout lists above are seeds, not a menu to pick from every time — treat them as starting points and rotate. Do not reach for the same direction, type pairing, or palette twice; if a brief resembles one handled before, deliberately diverge. Two interfaces for different products should not be recognizably the same template. Sameness across outputs is itself a failure, even when each one looks fine on its own. - -## Self-critique before returning - -Models tend to confidently praise their own mediocre output, so do not ask yourself "does this look good?" Instead run the concrete pass/fail checks below and fix every failure before returning the code. These target WCAG 2.2 AA and basic craft — things checkable from the markup, not matters of taste. - -Accessibility: - -- Body-text contrast is at least 4.5:1; large text (24px+, or 18.66px+ bold) and the borders of UI controls and meaningful icons are at least 3:1. Meaning is never carried by color alone. -- Semantics are native: `