---
name: command-generator
description: Command file generator - 5 phase workflow for creating Claude Code command files with YAML frontmatter. Generates .md command files for project or user scope. Triggers on "create command", "new command", "command generator".
allowed-tools: Read, Write, Edit, Bash, Glob, AskUserQuestion
---

<purpose>
Generate Claude Code command .md files with concrete, domain-specific content in GSD style. Produces command files at project-level (`.claude/commands/`) or user-level (`~/.claude/commands/`) with YAML frontmatter, XML semantic tags (`<purpose>`, `<process>`, `<step>`, `<error_codes>`, `<success_criteria>`), and actionable execution logic — NOT empty placeholders.

Invoked when user requests "create command", "new command", or "command generator".
</purpose>

<required_reading>
- @.claude/skills/command-generator/specs/command-design-spec.md
- @.claude/skills/command-generator/templates/command-md.md
</required_reading>

<process>

<step name="validate_params" priority="first">
**Parse and validate all input parameters.**

Extract from `$ARGUMENTS` or skill args:

| Parameter | Required | Validation | Example |
|-----------|----------|------------|---------|
| `$SKILL_NAME` | Yes | `/^[a-z][a-z0-9-]*$/`, min 1 char | `deploy`, `create` |
| `$DESCRIPTION` | Yes | min 10 chars | `"Deploy application to production"` |
| `$LOCATION` | Yes | `"project"` or `"user"` | `project` |
| `$GROUP` | No | `/^[a-z][a-z0-9-]*$/` or null | `issue`, `workflow` |
| `$ARGUMENT_HINT` | No | any string or empty | `"<url> [--priority 1-5]"` |

**Validation rules:**
- Missing required param → Error with specific message (e.g., `"skillName is required"`)
- Invalid `$SKILL_NAME` pattern → Error: `"skillName must be lowercase alphanumeric with hyphens, starting with a letter"`
- Invalid `$LOCATION` → Error: `"location must be 'project' or 'user'"`
- Invalid `$GROUP` pattern → Warning, continue

**Normalize:** trim + lowercase for `$SKILL_NAME`, `$LOCATION`, `$GROUP`.
</step>

<step name="resolve_target_path">
**Resolve target file path based on location and group.**

Path mapping:

| Location | Base Directory |
|----------|---------------|
| `project` | `.claude/commands` |
| `user` | `~/.claude/commands` (expand `~` to `$HOME`) |

Path construction:

```
If $GROUP:
  $TARGET_DIR = {base}/{$GROUP}
  $TARGET_PATH = {base}/{$GROUP}/{$SKILL_NAME}.md
Else:
  $TARGET_DIR = {base}
  $TARGET_PATH = {base}/{$SKILL_NAME}.md
```

Check if `$TARGET_PATH` already exists → store as `$FILE_EXISTS` (true/false).
</step>

<step name="gather_requirements">
**Gather domain-specific requirements to generate concrete content.**

Infer the command's domain from `$SKILL_NAME`, `$DESCRIPTION`, and `$ARGUMENT_HINT`:

| Signal | Extract |
|--------|---------|
| `$SKILL_NAME` | Action verb (deploy, create, analyze, sync) → step naming |
| `$DESCRIPTION` | Domain keywords → execution logic, error scenarios |
| `$ARGUMENT_HINT` | Flags/args → parse_input step details, validation rules |
| `$GROUP` | Command family → related commands, shared patterns |

**Determine command complexity:**

| Complexity | Criteria | Steps to Generate |
|------------|----------|-------------------|
| Simple | Single action, no flags | 2-3 steps |
| Standard | 1-2 flags, clear workflow | 3-4 steps |
| Complex | Multiple flags, multi-phase | 4-6 steps |

**If complexity is unclear**, ask user:

```
AskUserQuestion(
  header: "Command Scope",
  question: "What are the main execution steps for this command?",
  options: [
    { label: "Simple", description: "Single action: validate → execute → report" },
    { label: "Standard", description: "Multi-step: parse → process → verify → report" },
    { label: "Complex", description: "Full workflow: parse → explore → execute → verify → report" },
    { label: "I'll describe", description: "Let me specify the steps" }
  ]
)
```

Store as `$COMMAND_STEPS`, `$ERROR_SCENARIOS`, `$SUCCESS_CONDITIONS`.
</step>

<step name="draft_content">
**Generate concrete, domain-specific command content in GSD style.**

This is the core generation step. Draft the COMPLETE command file — not a template with placeholders — using the gathered requirements.

**YAML Frontmatter:**
```yaml
---
name: $SKILL_NAME
description: $DESCRIPTION
argument-hint: $ARGUMENT_HINT  # only if provided
---
```

**`<purpose>` section:** Write 2-3 sentences describing:
- What the command does (action + target)
- When it's invoked (trigger conditions)
- What it produces (output artifacts or effects)

**`<required_reading>` section:** Infer from domain:
- If command reads config → `@.claude/CLAUDE.md` or relevant config files
- If command modifies code → relevant source directories
- If command is part of a group → other commands in the same group

**`<process>` section with `<step>` blocks:**

For each step in `$COMMAND_STEPS`, generate a `<step name="snake_case">` block containing:

1. **`parse_input`** (always first, `priority="first"`):
   - Parse `$ARGUMENTS` for flags and positional args derived from `$ARGUMENT_HINT`
   - Include specific flag detection logic (e.g., `if arguments contain "--env"`)
   - Include validation with specific error messages
   - Include decision routing table if multiple modes exist

2. **Domain-specific execution steps** (2-4 steps):
   - Each step has a **bold action description**
   - Include concrete shell commands, file operations, or tool calls
   - Use `$UPPER_CASE` variables for user input, `${computed}` for derived values
   - Include conditional logic with specific conditions (not generic)
   - Reference actual file paths and tool names

3. **`report`** (always last):
   - Format output with banner and status
   - Include file paths, timestamps, next step suggestions

**Shell Correctness Checklist (MANDATORY for every shell block):**

| Rule | Wrong | Correct |
|------|-------|---------|
| Multi-line output | `echo "{ ... }"` (unquoted multi-line) | `cat <<'EOF' > file`...`EOF` (heredoc) |
| Variable init | Use `$VAR` after conditional | `VAR="default"` BEFORE any conditional that sets it |
| Error exit | `echo "Error: ..."` (no exit) | `echo "Error: ..." # (see code: E00X)` + `exit 1` |
| Quoting | `$VAR` in commands | `"$VAR"` (double-quoted in all expansions) |
| Exit on fail | Command chain without checks | `set -e` or explicit `|| { echo "Failed"; exit 1; }` |
| Command from var | `$CMD --flag` (word-split fragile) | `eval "$CMD" --flag` or use array: `cmd=(...); "${cmd[@]}"` |
| Prerequisites | Implicit `git`/`curl` usage | Declare in `<prerequisites>` section |

**Golden Example — a correctly-written execution step:**

```markdown
<step name="run_deployment">
**Execute deployment to target environment.**

$DEPLOY_STATUS="pending"  # Initialize before conditional

```bash
# Save current state for rollback
cp .deploy/latest.json .deploy/previous.json 2>/dev/null || true

# Write deployment manifest via heredoc
cat <<EOF > .deploy/latest.json
{
  "env": "$ENV",
  "tag": "$DEPLOY_TAG",
  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "commit": "$(git rev-parse --short HEAD)",
  "status": "deploying"
}
EOF

# Execute deployment
if ! deploy_cmd --env "$ENV" --tag "$DEPLOY_TAG" 2>&1 | tee .deploy/latest.log; then
  echo "Error: Deployment to $ENV failed" # (see code: E004)
  exit 1
fi

$DEPLOY_STATUS="success"
```

| Condition | Action |
|-----------|--------|
| Deploy succeeds | Update status → `"deployed"`, continue to verify |
| Deploy fails | Log error `# (see code: E004)`, exit 1 |
| `$ROLLBACK_MODE` | Load `.deploy/previous.json`, redeploy prior version |
</step>
```

**Optional `<prerequisites>` section** (include when command uses external tools):

```markdown
<prerequisites>
- git (2.20+) — version control operations
- curl — health check endpoints
- jq — JSON processing (optional)
</prerequisites>
```

**`<error_codes>` table:** Generate 3-6 specific error codes:
- Derive from `$ARGUMENT_HINT` validation failures (E001-E003)
- Derive from domain-specific failure modes (E004+)
- Include 1-2 warnings (W001+)
- Each code has: Code, Severity, Description, **Stage** (which step triggers it)
- **Cross-reference rule**: Every `# (see code: E00X)` comment in `<process>` MUST have a matching row in `<error_codes>`, and every error code row MUST be referenced by at least one inline comment

**`<success_criteria>` checkboxes:** Generate 4-8 verifiable conditions:
- Input validation passed
- Each execution step completed its action
- Output artifacts exist / effects applied
- Report displayed

**Quality rules for generated content:**
- NO bracket placeholders (`[Describe...]`, `[List...]`) — all content must be concrete
- Steps must contain actionable logic, not descriptions of what to do
- Error codes must reference specific failure conditions from this command's domain
- Success criteria must be verifiable (not "command works correctly")
- Every shell block must pass the Shell Correctness Checklist above
- Follow patterns from @.claude/skills/command-generator/templates/command-md.md for structural reference only
</step>

<step name="write_file">
**Write generated content to target path.**

**If `$FILE_EXISTS`:** Warn: `"Command file already exists at {path}. Will overwrite."`

```bash
mkdir -p "$TARGET_DIR"
```

Write the drafted content to `$TARGET_PATH` using Write tool.

**Verify:** Read back the file and confirm:
- File exists and is non-empty
- Contains `<purpose>` tag with concrete content (no placeholders)
- Contains at least 2 `<step name=` blocks with shell code or tool calls
- Contains `<error_codes>` with at least 3 rows including Stage column
- Contains `<success_criteria>` with at least 4 checkboxes
- No unresolved `{{...}}` or `[...]` placeholders remain
- Every `# (see code: E0XX)` has a matching `<error_codes>` row (cross-ref check)
- Every shell block uses heredoc for multi-line output (no bare multi-line echo)
- All state variables initialized before conditional use
- All error paths include `exit 1` after error message

**If verification fails:** Fix the content in-place using Edit tool.

**Report completion:**

```
Command generated successfully!

File: {$TARGET_PATH}
Name: {$SKILL_NAME}
Description: {$DESCRIPTION}
Location: {$LOCATION}
Group: {$GROUP or "(none)"}
Steps: {number of <step> blocks generated}
Error codes: {number of error codes}

Next Steps:
1. Review and customize {$TARGET_PATH}
2. Test: /{$GROUP}:{$SKILL_NAME} or /{$SKILL_NAME}
```
</step>

</process>

<error_codes>

| Code | Severity | Description | Stage |
|------|----------|-------------|-------|
| E001 | error | skillName is required | validate_params |
| E002 | error | description is required (min 10 chars) | validate_params |
| E003 | error | location is required ("project" or "user") | validate_params |
| E004 | error | skillName must be lowercase alphanumeric with hyphens | validate_params |
| E005 | error | Failed to infer command domain from description | gather_requirements |
| E006 | error | Failed to write command file | write_file |
| E007 | error | Generated content contains unresolved placeholders | write_file |
| W001 | warning | group must be lowercase alphanumeric with hyphens | validate_params |
| W002 | warning | Command file already exists, will overwrite | write_file |
| W003 | warning | Could not infer required_reading, using defaults | draft_content |

</error_codes>

<success_criteria>
- [ ] All required parameters validated ($SKILL_NAME, $DESCRIPTION, $LOCATION)
- [ ] Target path resolved with correct scope (project vs user) and group
- [ ] Command domain inferred from description and argument hint
- [ ] Concrete `<purpose>` drafted (no placeholders)
- [ ] 2-6 `<step>` blocks generated with domain-specific logic
- [ ] `<error_codes>` table generated with 3+ specific codes
- [ ] `<success_criteria>` generated with 4+ verifiable checkboxes
- [ ] File written to $TARGET_PATH and verified
- [ ] Zero bracket placeholders in final output
- [ ] Completion report displayed
</success_criteria>