Skillintermediate

Plugin Instructions

These instructions apply when working under `plugins/compound-engineering/`. They supplement the repo-root `AGENTS.md`.

Claude Code Knowledge Pack7/10/2026

Overview

Plugin Instructions

These instructions apply when working under plugins/compound-engineering/. They supplement the repo-root AGENTS.md.

Compounding Engineering Plugin Development

Runtime vs Authoring Context

This plugin's AGENTS.md and CLAUDE.md files are authoring context — they do not ship with the installed plugin. Skills are packaged and installed into end-user environments (their own repos, or folders that may not even be git repos), where they run against the user's AGENTS.md/CLAUDE.md, not this repo's.

Consequences:

Behavioral rules that govern skill runtime behavior must live inside the skill itself — in SKILL.md or files under its references/. Guidance placed in this file is invisible at runtime.
When two or more skills share a behavioral principle, duplicate the guidance into each skill (inline for short rules, references/ for longer ones). There is no cross-skill shared-file mechanism (see "File References in Skills" below).
Do not propose that runtime guidance for ce-ideate, ce-brainstorm, ce-plan, or any other skill live in this AGENTS.md or in the repo-root AGENTS.md. Those files only shape how contributors edit the plugin.

This is easy to miss because authoring feels like using: you edit the plugin while running inside this repo, and the repo's AGENTS.md is loaded — but that load does not follow the installed skill into a user's environment.

Versioning Requirements

IMPORTANT: Routine PRs should not cut releases for this plugin.

The 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.

Contributor Rules

Do not manually bump .claude-plugin/plugin.json version in a normal feature PR.
Do not manually bump .cursor-plugin/plugin.json version in a normal feature PR.
Do not manually bump .codex-plugin/plugin.json version in a normal feature PR — release-please owns this via extra-files in .github/release-please-config.json, parallel to the Claude and Cursor entries.
Do not manually bump .claude-plugin/marketplace.json plugin version in a normal feature PR.
Do not hand-edit .agents/plugins/marketplace.json except to add or remove a plugin. Plugin-list, name, and description drift between the Claude, Cursor, and Codex marketplaces is caught by bun run release:validate.
Do not cut a release section in the canonical root CHANGELOG.md for a normal feature PR.
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.

Pre-Commit Checklist

Before committing ANY changes:

No manual release-version bump in .claude-plugin/plugin.json
No manual release-version bump in .cursor-plugin/plugin.json
No manual release-version bump in .codex-plugin/plugin.json
No manual release-version bump in .claude-plugin/marketplace.json
No manual release entry added to the root CHANGELOG.md
bun run release:validate passes (enforces Claude/Cursor/Codex manifest parity)
README.md component counts verified
README.md tables accurate (agents, commands, skills)
plugin.json description matches current counts

Directory Structure

agents/
└── ce-*.agent.md  # All agents live flat under agents/, prefixed with ce-

skills/
├── ce-*/          # Core workflow skills (ce-plan, ce-code-review, etc.)
└── */             # All other skills

Agents are grouped topically in README.md (Review, Document Review, Research, Design, Workflow, Docs) for reader navigation — those groupings are conceptual, not filesystem subdirectories.

Note: Commands were migrated to skills in v2.39.0. All former /command-name slash commands now live under skills/command-name/SKILL.md and work identically in Claude Code. Other targets may convert or map these references differently.

Debugging Plugin Bugs

Developers 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.

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.
Both versions have the bug: Proceed with the fix normally.

Important: 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.

Naming Convention

All skills and agents use the ce- prefix to unambiguously identify them as compound-engineering components:

/ce-brainstorm - Explore requirements and approaches before planning
/ce-plan - Create implementation plans
/ce-code-review - Run comprehensive code reviews
/ce-work - Execute work items systematically
/ce-compound - Document solved problems

Why ce-? Claude Code has built-in /plan and /review commands. The ce- prefix (short for compound-engineering) makes it immediately clear these components belong to this plugin. The hyphen is used instead of a colon to avoid filesystem issues on Windows and to align directory names with frontmatter names.

Agents follow the same convention: ce-adversarial-reviewer, ce-learnings-researcher, etc. When referencing agents from skills, use the bare ce-<agent-name> form (e.g., ce-adversarial-reviewer) — the ce- prefix is sufficient for uniqueness across plugins.

Known External Limitations

Proof HITL surfaces a ghost "AI collaborator" agent (noted 2026-04-16, may change): The Proof API auto-joins any header-less /state read under a synthetic ai:auto-<hash> identity, so docs created by the skills/proof/ HITL workflow show a phantom participant alongside Compound Engineering. The only way to suppress it is to set ownerId: "agent:ai:compound-engineering" on create — but that transfers document ownership to the agent and prevents the user from claiming it into their Proof library, so we don't use it. Treat as cosmetic noise; don't reintroduce the ownerId workaround. Tracked upstream: https://github.com/EveryInc/proof/issues/951.

Skill Compliance Checklist

When adding or modifying skills, verify compliance with the skill spec:

YAML Frontmatter (Required)

name: present and matches directory name (lowercase-with-hyphens)
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.")
description: is no longer than 1024 characters -- some coding harnesses reject longer skill descriptions. Enforced by tests/frontmatter.test.ts.
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.
description: value does not contain raw angle-bracket tokens like <skill-name>, <tag>, or <placeholder> -- Cowork's plugin validator parses descriptions as HTML and rejects unknown tags with a generic "Plugin validation failed" banner (see issue #602). Claude Code tolerates them, so the bug only surfaces downstream. Backtick-wrap the token (`<skill-name>`) or rephrase. Enforced by tests/frontmatter.test.ts.

Reference File Inclusion (Required if references/ exists)

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
Default: use backtick paths. Most reference files should be referenced with backtick paths so the agent can load them on demand:
```
`references/architecture-patterns.md`
```
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
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:
```
@./references/schema.json
```
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
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

Conditional and Late-Sequence Extraction

Skill 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.

Writing Style

Use imperative/infinitive form (verb-first instructions)
Avoid second person ("you should") - use objective language ("To accomplish X, do Y")

Rationale Discipline

Every line in SKILL.md loads on every invocation. Include rationale only when it changes what the agent does at runtime — if behavior wouldn't differ without the sentence, cut it.

Keep rationale at the highest-level location that covers it; restate behavioral directives at the point they take effect. A 500-line skill shouldn't hinge on the agent remembering line 9 by line 400. Portability notes, defenses against mistakes the agent wasn't going to make, and meta-commentary about this repo's authoring rules belong in commit messages or docs/solutions/, not in the skill body.

Cross-Platform User Interaction

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, ask_user in Pi via the pi-ask-user extension)
For Claude Code, also instruct to load AskUserQuestion via ToolSearch with select:AskUserQuestion first if its schema isn't already loaded — AskUserQuestion is a deferred tool and won't be available at session start. A pending schema load is not a valid reason to fall back to text.
Include a fallback: when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes where request_user_input is unavailable, or ToolSearch returns no match), present numbered options in chat and wait for the user's reply — never silently skip the question.
Narrow exception for legitimate option overflow: when a menu has 5 or more genuinely relevant options — each a distinct destination or workflow, none removable without losing real user choice — render as a numbered list in chat rather than trimming to fit the 4-option cap. This is used with restraint, not as a convenience escape from the blocking tool. Default remains the blocking tool. Before invoking the exception, verify that (a) no option can be cut, (b) no two options can be merged, and (c) no option is better surfaced as contextual prose (e.g., a nudge adjacent to the menu). If any of those reductions work, prefer them over the fallback. When the exception applies, include a hint that free-form input is accepted (e.g., "Pick a number or describe what you want.") so the numbered list retains the blocking tool's open-endedness.

Platform-behavior note (April 2026, may change): The specifics above reflect current behavior — AskUserQuestion is deferred in Claude Code, and request_user_input in Codex is exposed only in Plan mode. If Anthropic changes AskUserQuestion to a non-deferred tool, or Codex exposes request_user_input in edit modes, revisit this guidance rather than carrying the workaround forward indefinitely. Verify before assuming these constraints still hold.

Interactive Question Tool Design

Design rules for blocking question menus (AskUserQuestion / request_user_input / ask_user). Violations silently degrade the UX in harnesses where secondary description text is hidden or labels are truncated.