command-creator

Create Claude Code commands — user-invocable workflows that orchestrate agents, interview users, and delegate complex work through structured phases. --- ## Core Process **1. Classify Command Scope** Determine structure before drafting: - How many phases? Simple commands (1-2 phases) vs orchestration commands (5+ phases). - Does the command need subagents, or can it run entirely in the main context with Read/Glob/Grep/Bash? Default to main context; only add Agent delegation when the work must run in a fresh context or with a different model. - Interactive (AskUserQuestion gates) or autonomous (runs end-to-end without prompts)? - What approval gates are needed before destructive or irreversible actions? **2. Research Existing Commands** Use Glob + Read directly to find similar commands in the target project: - Glob `**/commands/*.md`, read 2-3 representative files - Note phase structure, frontmatter fields, and whether they use subagents or direct tools **3. Dedup Audit** Read `${CLAUDE_SKILL_DIR}/../prompt-writer/references/cc-dedup-guide.md` before drafting. Key dedup rules for commands: - Commands receive CLAUDE.md automatically — do not re-state its global directives. - Do not repeat Intent Gate, Delegation Check, or barrier semantics — these load every message. - Do not re-explain agent model routing rules already in global CLAUDE.md. - Commands specify WHAT to do (which agents, which phases) not HOW CC should behave. **4. Draft Command** Follow phase-based structure from `references/command-patterns.md`. Each phase uses: ```markdown ## Phase N: Name **Goal**: One sentence — what this phase achieves. **Actions**: 1. First action 2. Second action 3. Third action (with sub-steps if needed) ``` Rules: - Phases must be sequential — later phases depend on earlier ones. - Insert AskUserQuestion approval gates before destructive actions. - Delegate heavy work to agents — commands orchestrate, agents execute. - Reference `$ARGUMENTS` for user-supplied input. - Use `${CLAUDE_PLUGIN_ROOT}` for paths to bundled templates. **5. Frontmatter** ```yaml --- description: "Short, action-oriented. What does this command do? ≤250 chars." argument-hint: "[expected-input]" effort: low | medium | high --- ``` Notes: - Do not declare `allowed-tools`, `disallowedTools`, or `model`. CC ignores them at runtime for user-level plugin components; tool access flows from session permissions. - Always include `AskUserQuestion` and `Agent` if the command interviews users or delegates to agents. - `effort` signals expected token budget: `low` (single task, <5 phases), `medium` (multi-agent, 5-7 phases), `high` (full orchestration, 7+ phases). - Do not add `model` to command frontmatter — commands inherit the session model. Only agents have model routing. **6. Review** Present draft. Verify before finalizing: - Phases sequential? No phase assumes work from a later phase. - Approval gates present before destructive or irreversible actions? - Agent delegation clear? Each Agent call has TASK + EXPECTED OUTCOME + MUST DO + MUST NOT DO + CONTEXT. - Error handling covers: missing input, agent failure, no changes found, user cancellation. - `$ARGUMENTS` referenced at the right phase (usually Phase 1)? - No ineffective frontmatter declared (`model`, `allowed-tools`, `disallowedTools`)? --- ## Agent Delegation Patterns ### Parallel Foreground (wait for all) All agents in a single message block — CC waits automatically: ``` Agent(subagent_type: "<your-search-agent>", prompt: "...") Agent(subagent_type: "<your-analysis-agent>", prompt: "...") ``` Use when results are needed before proceeding. Do NOT advance to the next phase until all agents complete. ### Background (genuinely independent work) ``` Agent(subagent_type: "<your-worker>", run_in_background: true, prompt: "...") Agent(subagent_type: "<your-worker>", run_in_background: true, prompt: "...") ``` Use only when you have independent work to continue while agents run. Collect all completion notifications before the next phase. ### Model Routing per Agent Pass `model:` to override per agent — do not upgrade all agents to Opus: | Task type | Model | |-----------|-------| | Search, file reading, fast lookup | haiku | | Standard execution, analysis | sonnet | | Planning, architecture, deep review | opus | ### Agent Prompt Template Every agent delegation follows this structure: ``` TASK: [What the agent must accomplish — one clear sentence] EXPECTED OUTCOME: [What the agent returns — file:line refs, verdict, structured output] MUST DO: - [Specific constraint 1] - [Specific constraint 2] MUST NOT DO: - [What to exclude or avoid] CONTEXT: [Relevant state — plan path, conventions, prior findings] ``` --- ## String Substitutions Variables available in command bodies (replaced at load time by CC): | Variable | Where | Description | |----------|-------|-------------| | `$ARGUMENTS` | Commands | All arguments passed on invocation | | `${CLAUDE_PLUGIN_ROOT}` | Commands | Absolute path to the plugin's root directory | | `${CLAUDE_SKILL_DIR}` | Skills only | Absolute path to the skill's directory — NOT available in commands | Use `${CLAUDE_PLUGIN_ROOT}` to reference bundled templates: ```markdown Read template from `${CLAUDE_PLUGIN_ROOT}/references/my-template.md` ``` --- ## References | Topic | File | When to read | |-------|------|-------------| | Command templates | [command-patterns.md](references/command-patterns.md) | Before drafting — full phase template, AskUserQuestion patterns, pipeline profiles, agent spawning examples | | Dedup guide | `${CLAUDE_SKILL_DIR}/../prompt-writer/references/cc-dedup-guide.md` | Before drafting — what not to repeat from global CLAUDE.md and auto-loaded context | | Frontmatter schemas | `${CLAUDE_SKILL_DIR}/../prompt-writer/references/frontmatter-schemas.md` | During frontmatter validation — field schemas, invocation control, tool control semantics |