AGENTS.md

1<!-- forgecat:@forgecat/everyinc_compound-engineering-plugin:compound-engineering-agents:start -->
2# Plugin Instructions
3 
4These instructions apply when working under `plugins/compound-engineering/`.
5They supplement the repo-root `AGENTS.md`.
6 
7# Compounding Engineering Plugin Development
8 
9## Versioning Requirements
10 
11**IMPORTANT**: Routine PRs should not cut releases for this plugin.
12 
13The repo uses an automated release process to prepare plugin releases, including version selection and changelog generation. Because multiple PRs may merge before the next release, contributors cannot know the final released version from within an individual PR.
14 
15### Contributor Rules
16 
17- Do **not** manually bump `.claude-plugin/plugin.json` version in a normal feature PR.
18- Do **not** manually bump `.claude-plugin/marketplace.json` plugin version in a normal feature PR.
19- Do **not** cut a release section in the canonical root `CHANGELOG.md` for a normal feature PR.
20- Do update substantive docs that are part of the actual change, such as `README.md`, component tables, usage instructions, or counts when they would otherwise become inaccurate.
21 
22### Pre-Commit Checklist
23 
24Before committing ANY changes:
25 
26- [ ] No manual release-version bump in `.claude-plugin/plugin.json`
27- [ ] No manual release-version bump in `.claude-plugin/marketplace.json`
28- [ ] No manual release entry added to the root `CHANGELOG.md`
29- [ ] README.md component counts verified
30- [ ] README.md tables accurate (agents, commands, skills)
31- [ ] plugin.json description matches current counts
32 
33### Directory Structure
34 
35```
36agents/
37├── review/           # Code review agents
38├── document-review/  # Plan and requirements document review agents
39├── research/         # Research and analysis agents
40├── design/           # Design and UI agents
41└── docs/             # Documentation agents
42 
43skills/
44├── ce-*/          # Core workflow skills (ce:plan, ce:review, etc.)
45└── */             # All other skills
46```
47 
48> **Note:** Commands were migrated to skills in v2.39.0. All former
49> `/command-name` slash commands now live under `skills/command-name/SKILL.md`
50> and work identically in Claude Code. Other targets may convert or map these references differently.
51 
52## Debugging Plugin Bugs
53 
54Developers of this plugin also use it via their marketplace install (`~/.claude/plugins/`). When a developer reports a bug they experienced while using a skill or agent, the installed version may be older than the repo. Glob for the component name under `~/.claude/plugins/` and diff the installed content against the repo version.
55 
56- **Repo already has the fix**: The developer's install is stale. Tell them to reinstall the plugin or use `--plugin-dir` to load skills from the repo checkout. No code change needed.
57- **Both versions have the bug**: Proceed with the fix normally.
58 
59Important: Just because the developer's installed plugin may be out of date, it's possible both old and current repo versions have the bug. The proper fix is to still fix the repo version.
60 
61## Command Naming Convention
62 
63**Workflow commands** use `ce:` prefix to unambiguously identify them as compound-engineering commands:
64- `/ce:brainstorm` - Explore requirements and approaches before planning
65- `/ce:plan` - Create implementation plans
66- `/ce:review` - Run comprehensive code reviews
67- `/ce:work` - Execute work items systematically
68- `/ce:compound` - Document solved problems
69 
70**Why `ce:`?** Claude Code has built-in `/plan` and `/review` commands. The `ce:` namespace (short for compound-engineering) makes it immediately clear these commands belong to this plugin.
71 
72## Skill Compliance Checklist
73 
74When adding or modifying skills, verify compliance with the skill spec:
75 
76### YAML Frontmatter (Required)
77 
78- [ ] `name:` present and matches directory name (lowercase-with-hyphens)
79- [ ] `description:` present and describes **what it does and when to use it** (per official spec: "Explains code with diagrams. Use when exploring how code works.")
80- [ ] `description:` value is quoted (single or double) if it contains colons -- unquoted colons break `js-yaml` strict parsing and crash `install --to opencode/codex`. Run `bun test tests/frontmatter.test.ts` to verify.
81 
82### Reference File Inclusion (Required if references/ exists)
83 
84- [ ] Do NOT use markdown links like `[filename.md](./references/filename.md)` -- agents interpret these as Read instructions with CWD-relative paths, which fail because the CWD is never the skill directory
85- [ ] **Default: use backtick paths.** Most reference files should be referenced with backtick paths so the agent can load them on demand:
86```
87  `references/architecture-patterns.md`
88```
89  This keeps the skill lean and avoids inflating the token footprint at load time. Use for: large reference docs, routing-table targets, code scaffolds, executable scripts/templates
90- [ ] **Exception: `@` inline for small structural files** that the skill cannot function without and that are under ~150 lines (schemas, output contracts, subagent dispatch templates). Use `@` file inclusion on its own line:
91```
92  @./references/schema.json
93```
94  This resolves relative to the SKILL.md and substitutes content before the model sees it. If a file is over ~150 lines, prefer a backtick path even if it is always needed
95- [ ] For files the agent needs to *execute* (scripts, shell templates), always use backtick paths -- `@` would inline the script as text content instead of keeping it as an executable file
96 
97### Conditional and Late-Sequence Extraction
98 
99Skill content loaded at trigger time is carried in every subsequent message — every tool call, agent dispatch, and response. This carrying cost compounds across the session. For skills that orchestrate many tool or agent calls, extract blocks to `references/` when they are conditional (only execute under specific conditions) or late-sequence (only needed after many prior calls) and represent a meaningful share of the skill (~20%+). The more tool/agent calls a skill makes, the more aggressively to extract. Replace extracted blocks with a 1-3 line stub stating the condition and a backtick path reference (e.g., "Read `references/deepening-workflow.md`"). Never use `@` for extracted blocks — it inlines content at load time, defeating the extraction.
100 
101### Writing Style
102 
103- [ ] Use imperative/infinitive form (verb-first instructions)
104- [ ] Avoid second person ("you should") - use objective language ("To accomplish X, do Y")
105 
106### Cross-Platform User Interaction
107 
108- [ ] When a skill needs to ask the user a question, instruct use of the platform's blocking question tool and name the known equivalents (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini)
109- [ ] Include a fallback for environments without a question tool (e.g., present numbered options and wait for the user's reply before proceeding)
110 
111### Cross-Platform Task Tracking
112 
113- [ ] When a skill needs to create or track tasks, describe the intent (e.g., "create a task list") and name the known equivalents (`TaskCreate`/`TaskUpdate`/`TaskList` in Claude Code, `update_plan` in Codex)
114- [ ] Do not reference `TodoWrite` or `TodoRead` — these are legacy Claude Code tools replaced by `TaskCreate`/`TaskUpdate`/`TaskList`
115- [ ] When a skill dispatches sub-agents, prefer parallel execution but include a sequential fallback for platforms that do not support parallel dispatch
116 
117### Script Path References in Skills
118 
119- [ ] In bash code blocks, reference co-located scripts using relative paths (e.g., `bash scripts/my-script ARG`) — not `${CLAUDE_PLUGIN_ROOT}` or other platform-specific variables
120- [ ] All platforms resolve script paths relative to the skill's directory; no env var prefix is needed
121- [ ] Reference the script with a backtick path (e.g., `` `scripts/my-script` ``) so agents can locate it; a markdown link is not needed since the bash code block already provides the invocation
122 
123### Cross-Platform Reference Rules
124 
125This plugin is authored once, then converted for other agent platforms. Commands and agents are transformed during that conversion, but `plugin.skills` are usually copied almost exactly as written.
126 
127- [ ] Because of that, slash references inside command or agent content are acceptable when they point to real published commands; target-specific conversion can remap them.
128- [ ] Inside a pass-through `SKILL.md`, do not assume slash references will be remapped for another platform. Write references according to what will still make sense after the skill is copied as-is.
129- [ ] When one skill refers to another skill, prefer semantic wording such as "load the `document-review` skill" rather than slash syntax.
130- [ ] Use slash syntax only when referring to an actual published command or workflow such as `/ce:work` or `/ce:compound`.
131 
132### Tool Selection in Agents and Skills
133 
134Agents and skills that explore codebases must prefer native tools over shell commands.
135 
136Why: shell-heavy exploration causes avoidable permission prompts in sub-agent workflows; native file-search, content-search, and file-read tools avoid that.
137 
138- [ ] Never instruct agents to use `find`, `ls`, `cat`, `head`, `tail`, `grep`, `rg`, `wc`, or `tree` through a shell for routine file discovery, content search, or file reading
139- [ ] Describe tools by capability class with platform hints — e.g., "Use the native file-search/glob tool (e.g., Glob in Claude Code)" — not by Claude Code-specific tool names alone
140- [ ] When shell is the only option (e.g., `ast-grep`, `bundle show`, git commands), instruct one simple command at a time — no chaining (`&&`, `||`, `;`) and no error suppression (`2>/dev/null`, `|| true`). Simple pipes (e.g., `| jq .field`) and output redirection (e.g., `> file`) are acceptable when they don't obscure failures
141- [ ] Do not encode shell recipes for routine exploration when native tools can do the job; encode intent and preferred tool classes instead
142- [ ] For shell-only workflows (e.g., `gh`, `git`, `bundle show`, project CLIs), explicit command examples are acceptable when they are simple, task-scoped, and not chained together
143 
144### Passing Reference Material to Sub-Agents
145 
146When a skill orchestrates sub-agents that need codebase reference material, prefer passing file paths over file contents. The sub-agent reads only what it needs. Content-passing is fine for small, static material consumed in full (e.g., a JSON schema under ~50 lines).
147 
148### Sub-Agent Permission Mode
149 
150When dispatching sub-agents, **omit the `mode` parameter** on the Agent/Task tool call unless the skill explicitly needs a specific mode (e.g., `mode: "plan"` for plan-approval workflows). Passing `mode: "auto"` or any other value overrides the user's configured permission settings (e.g., `bypassPermissions` in their user-level config), which is never the intended behavior for routine subagent dispatch. Omitting `mode` lets the user's own `defaultMode` setting apply.
151 
152### Quick Validation Command
153 
154```bash
155# Check for broken markdown link references (should return nothing)
156grep -E '\[.*\]\(\./references/|\[.*\]\(\./assets/|\[.*\]\(references/|\[.*\]\(assets/' skills/*/SKILL.md
157 
158# Check description format - should describe what + when
159grep -E '^description:' skills/*/SKILL.md
160```
161 
162## Adding Components
163 
164- **New skill:** Create `skills/<name>/SKILL.md` with required YAML frontmatter (`name`, `description`). Reference files go in `skills/<name>/references/`. Add the skill to the appropriate category table in `README.md` and update the skill count.
165- **New agent:** Create `agents/<category>/<name>.md` with frontmatter. Categories: `review`, `document-review`, `research`, `design`, `docs`, `workflow`. Add the agent to `README.md` and update the agent count.
166 
167## Upstream-Sourced Skills
168 
169Some skills are exact copies from external upstream repositories, vendored locally so the plugin is self-contained. Prefer syncing from upstream, but apply the reference file inclusion rules from the skill compliance checklist after each sync -- upstream skills often use markdown links for references which break in plugin contexts.
170 
171| Skill | Upstream | Local deviations |
172|-------|----------|------------------|
173| `agent-browser` | `github.com/vercel-labs/agent-browser` (`skills/agent-browser/SKILL.md`) | Markdown link refs replaced with backtick paths to fix CWD resolution bug (#374) |
174 
175## Beta Skills
176 
177Beta skills use a `-beta` suffix and `disable-model-invocation: true` to prevent accidental auto-triggering. See `docs/solutions/skill-design/beta-skills-framework.md` for naming, validation, and promotion rules.
178 
179### Stable/Beta Sync
180 
181When modifying a skill that has a `-beta` counterpart (or vice versa), always check the other version and **state your sync decision explicitly** before committing — e.g., "Propagated to beta — shared test guidance" or "Not propagating — this is the experimental delegate mode beta exists to test." Syncing to both, stable-only, and beta-only are all valid outcomes. The goal is deliberate reasoning, not a default rule.
182 
183## Documentation
184 
185See `docs/solutions/plugin-versioning-requirements.md` for detailed versioning workflow.
186<!-- forgecat:@forgecat/everyinc_compound-engineering-plugin:compound-engineering-agents:end -->
187