Skill: wpank/command-creator (version 0.1.0)

--- name: command-creator model: fast description: | WHAT: Create Claude Code slash commands - reusable markdown workflows invoked with /command-name. WHEN: User wants to create, make, or add a slash command. User wants to automate a repetitive workflow or document a consistent process for reuse. KEYWORDS: "create a command", "make a slash command", "add a command", "new command", "/command", "automate this workflow", "make this repeatable" --- # Command Creator Slash commands are markdown files in `.claude/commands/` (project) or `~/.claude/commands/` (global) that expand into prompts when invoked. ## Command Structure ```markdown --- description: Brief description for /help (required) argument-hint: <required> or [optional] (if takes arguments) --- # Command Title [Instructions for agent to execute autonomously] ``` --- ## Creation Workflow ### Step 1: Determine Location 1. Check if in git repo: `git rev-parse --is-inside-work-tree` 2. Default: Git repo → `.claude/commands/`, No git → `~/.claude/commands/` 3. Override if user explicitly says "global" or "project" Report chosen location before proceeding. ### Step 2: Identify Pattern Load [references/patterns.md](references/patterns.md) and present options: | Pattern | Structure | Use When | |---------|-----------|----------| | Workflow Automation | Analyze → Act → Report | Multi-step with clear sequence | | Iterative Fixing | Run → Parse → Fix → Repeat | Fix issues until passing | | Agent Delegation | Context → Delegate → Iterate | Complex tasks, user review | | Simple Execution | Parse → Execute → Return | Wrapper for existing tools | Ask: "Which pattern is closest to what you want?" ### Step 3: Gather Information **A. Name and Purpose** - "What should the command be called?" (kebab-case: `my-command`) - "What does it do?" (for description field) **B. Arguments** - "Does it take arguments? Required or optional?" - Required: `<placeholder>`, Optional: `[placeholder]` **C. Workflow Steps** - "What specific steps should it follow?" - "What tools or commands should it use?" **D. Constraints** - "Any specific tools to use or avoid?" - "Any files to read for context?" ### Step 4: Generate Command Load [references/best-practices.md](references/best-practices.md) for: - Template structure - Writing style (imperative form) - Quality checklist Key principles: - Use imperative form: "Run X", not "You should run X" - Be explicit: "Run `make lint`", not "Check for errors" - Include expected outcomes - Define error handling - State success criteria ### Step 5: Create File ```bash mkdir -p [directory-path] ``` Write the command file. Report: - File location - What the command does - How to use: `/command-name [args]` ### Step 6: Test (Optional) Suggest: "Test with `/command-name [args]`" Iterate based on feedback. --- ## Writing Guidelines **Imperative form (verb-first)**: - ✅ "Run git status" - ❌ "You should run git status" **Specific, not vague**: - ✅ "Run `make lint` to check for errors" - ❌ "Check for errors" **Include outcomes**: - ✅ "Run `git status` - should show modified files" - ❌ "Run git status" **Realistic examples**: - ✅ `git commit -m "Add OAuth2 authentication"` - ❌ `git commit -m "foo bar"` --- ## Command Patterns Quick Reference ### Workflow Automation ```markdown 1. Check for .PLAN.md 2. Analyze git status/diff 3. Perform actions 4. Report results ``` ### Iterative Fixing ```markdown 1. Run make all-ci (max 10 iterations) 2. Parse errors by category 3. Apply targeted fixes 4. Repeat until success or stuck ``` ### Agent Delegation ```markdown 1. Present context 2. Invoke subagent with Task tool 3. Iterate with user feedback 4. Save output after approval ``` See [references/examples.md](references/examples.md) for full command examples. --- ## Quality Checklist Before finalizing: - [ ] Name is kebab-case (`my-command`, not `my_command`) - [ ] Description is action-oriented - [ ] Steps are numbered and specific - [ ] Tool usage explicitly specified - [ ] Error handling defined - [ ] Success criteria stated - [ ] Uses imperative form --- ## NEVER - Use underscores in command names (use hyphens) - Write vague instructions ("fix errors") - Skip error handling - Use second person ("You should...") - Create commands without testing - Leave success criteria undefined

path: README.md
content: # Command Creator

Create Claude Code slash commands — reusable markdown workflows invoked with `/command-name`. Slash commands are markdown files in `.claude/commands/` (project) or `~/.claude/commands/` (global) that expand into prompts when invoked.

## What's Inside

- Command structure and frontmatter format
- Creation workflow (location, pattern, info gathering, generation, testing)
- Writing guidelines (imperative form, specificity, outcomes)
- Command patterns: Workflow Automation, Iterative Fixing, Agent Delegation, Simple Execution
- Quality checklist for finalizing commands
- Reference files for patterns, best practices, and examples

## When to Use

- User wants to create, make, or add a slash command
- User wants to automate a repetitive workflow
- User wants to document a consistent process for reuse
- Triggered by: "create a command", "make a slash command", "add a command", "new command", "/command", "automate this workflow", "make this repeatable"

## Installation

```bash
npx add https://github.com/wpank/ai/tree/main/skills/tools/command-creator
```

### Manual Installation

#### Cursor (per-project)

From your project root:

```bash
mkdir -p .cursor/skills
cp -r ~/.ai-skills/skills/tools/command-creator .cursor/skills/command-creator
```

#### Cursor (global)

```bash
mkdir -p ~/.cursor/skills
cp -r ~/.ai-skills/skills/tools/command-creator ~/.cursor/skills/command-creator
```

#### Claude Code (per-project)

From your project root:

```bash
mkdir -p .claude/skills
cp -r ~/.ai-skills/skills/tools/command-creator .claude/skills/command-creator
```

#### Claude Code (global)

```bash
mkdir -p ~/.claude/skills
cp -r ~/.ai-skills/skills/tools/command-creator ~/.claude/skills/command-creator
```

## Related Skills

- **skill-creator** — For creating agent skills (broader than slash commands)
- **subagent-driven-development** — Uses commands within delegated workflows

---

Part of the [Tools](..) skill category.


path: references/best-practices.md
content: # Command Best Practices

This document provides quality guidelines, writing style recommendations, common pitfalls, and a detailed template structure for creating effective slash commands.

## Command Writing Style

Commands are executed by AI agents, so optimize for autonomous execution.

### Writing Form

**ALWAYS use imperative/infinitive form** (verb-first instructions), not second person.

```markdown
✅ CORRECT:

- "Run git status to check current branch"
- "Check if .PLAN.md exists before proceeding"
- "Use the Task tool with Bash tool"

❌ WRONG:

- "You should run git status"
- "You need to check if .PLAN.md exists"
- "You'll want to use the Task tool"
```

### Specificity

Be explicit and specific, not vague.

```markdown
✅ CORRECT:

- "Run make lint to check for linting errors"
- "Read src/config.py lines 45-67 to understand the config structure"
- "Use Edit tool to replace 'List[str]' with 'list[str]'"

❌ WRONG:

- "Check for errors"
- "Look at the config file"
- "Fix the type annotation"
```

### Expected Outcomes

Include what should happen after each action.

```markdown
✅ CORRECT:

- "Run git status - this should show modified files in src/ directory"
- "After running make format, all Python files should be formatted"
- "The output should contain PR URLs for each submitted branch"

❌ WRONG:

- "Run git status"
- "Run make format"
- "Submit the PRs"
```

### Concrete Examples

Provide realistic examples, not placeholders like foo/bar.

```markdown
✅ CORRECT:

- "Example: `git commit -m 'Add user authentication with OAuth2'`"
- "Example: `/submit-stack 'Implement caching for API responses'`"
- "If error shows: `src/erk/cli/commands/init.py:45: Type error`"

❌ WRONG:

- "Example: `git commit -m 'foo bar'`"
- "Example: `/submit-stack 'something'`"
- "If error shows: `file.py:123: Error message`"
```

## Template Structure

Use this template structure for comprehensive commands:

```markdown
---
description: [One-line description for /help output]
argument-hint: [<required>] or [[optional]] (omit if no arguments)
---

# [Command Title]

[1-2 sentence overview of what this command does]

## What This Command Does

[Numbered list of main steps, user-facing description]

1. **[First action]**: [What it does]
2. **[Second action]**: [What it does]
3. **[Third action]**: [What it does]

## Usage

\`\`\`bash

# [Example with arguments]

/command-name "argument example"

# [Example without arguments if optional]

/command-name
\`\`\`

## Implementation Steps

When this command is invoked:

### 1. [First Major Step]

[Clear instructions with specifics]

\`\`\`bash

# Example commands if applicable

command --flag value
\`\`\`

[Explain what to do with results]

### 2. [Second Major Step]

[Continue with clear, actionable instructions]

### 3. [Continue for all steps]

## Important Notes

- **[Key constraint or requirement]**
- **[What to check first]**
- **[What NOT to do]**
- **[Error handling approach]**

## Error Handling

[Specify how to handle failures]

If any step fails:

- Report the specific command that failed
- Show the error message
- [What to do next - retry/ask user/stop]

## Example Output

\`\`\`
[Show expected terminal output]
\`\`\`
```

## Agent Optimization Elements

### 1. Explicit File Checks

Tell the agent exactly what to check and when.

```markdown
**FIRST**: Check if `.PLAN.md` exists in the repository root:

\`\`\`bash
if [ -f .PLAN.md ]; then

# Use .PLAN.md for context

else

# Fall back to alternative approach

fi
\`\`\`
```

### 2. Tool Usage Guidance

Be explicit about which tools to use.

```markdown
**Use the Bash tool for pytest/pyright/ruff/prettier/make/gt commands:**

Use Bash tool to run:
\`\`\`bash
make all-ci
\`\`\`

**DO NOT use Bash tool for make commands**
```

### 3. Anti-Patterns

Call out what NOT to do.

```markdown
## Important Notes

- **NEVER run additional exploration commands** beyond checking .PLAN.md, git status/diff
- **DO NOT batch completions** - mark todos complete immediately after finishing
- **DO NOT use Edit tool during planning phase**
- **DO NOT retry automatically** - ask user how to proceed
```

### 4. Conditional Logic

Use clear if/else structure.

```markdown
If condition A:

- Do X
- Then do Y

Otherwise (if condition B):

- Do Z
- Then do W

If neither condition is met:

- Report to user
- Exit gracefully
```

### 5. Success Criteria

Define exactly when to stop.

```markdown
## When to Stop

**SUCCESS**: Stop when `make all-ci` exits with code 0 (all checks passed)

**STUCK**: Stop and report to user if:

1. You've completed 10 iterations without success
2. The same error persists after 3 fix attempts
3. You encounter an error you cannot automatically fix
```

### 6. Error Handling

Provide explicit error handling instructions.

```markdown
## Error Handling

If any step fails:

- Report the specific command that failed
- Show the error message to the user
- Ask how to proceed (don't retry automatically)

Example:

\`\`\`
Error: git commit failed with exit code 1

Error message:
nothing to commit, working tree clean

Next steps: Please make changes before committing.
\`\`\`
```

### 7. Progress Tracking

Specify when and how to track progress.

```markdown
## Progress Reporting

Use TodoWrite to track your progress:

- Create todos at the start for each iteration
- Mark as in_progress when starting
- Mark as completed immediately after finishing (not batched)
- Update with iteration number: "Iteration 3: Fixing type errors"
```

## Common Patterns

### Pattern: TodoWrite Usage

```markdown
## Progress Tracking

Use TodoWrite to create todos for:

1. Each major step in the workflow
2. Each iteration in a loop
3. Each error category being fixed

Mark todos as completed IMMEDIATELY after finishing each task, not batched at the end.
```

### Pattern: File Operations

```markdown
### Read Before Modifying

Before making any changes:

1. Use Read tool to examine the current file state
2. Understand the code structure and context
3. Identify exact changes needed
4. Use Edit tool with precise old_string/new_string
```

### Pattern: Git Operations

```markdown
### Git Workflow

1. Check current git status:
   \`\`\`bash
   git status
   \`\`\`

2. Review changes:
   \`\`\`bash
   git diff HEAD
   \`\`\`

3. Check recent commits for style:
   \`\`\`bash
   git log --oneline -5
   \`\`\`

4. Stage all changes:
   \`\`\`bash
   git add .
   \`\`\`

5. Create commit:
   \`\`\`bash
   git commit -m "[message]"
   \`\`\`
```

### Pattern: Conditional Tool Selection

```markdown
### Tool Selection Based on Scope

Analyze the changes first:

If changes span 3+ files OR involve new abstractions:

- Use Task tool with subagent_type="subagent"
- Create detailed plan
- Execute with subagent agent

Otherwise (changes are contained):

- Execute changes directly
- Use Edit tool for modifications
- Skip planning overhead
```

### Pattern: Makefile Integration

```markdown
### Running Make Commands

**ALWAYS use Bash tool for pytest/pyright/ruff/prettier/make/gt commands**

Use Bash tool:

\`\`\`markdown
Use Bash tool to run command: "make all-ci"
\`\`\`

**DO NOT use Bash tool for make commands** - this is less efficient and provides worse output handling.
```

## Quality Checklist

Before finalizing a command, verify:

**Structure:**

- [ ] Command name is descriptive and kebab-case
- [ ] Description is concise and action-oriented (for `/help` output)
- [ ] Frontmatter includes `description` (required)
- [ ] Frontmatter includes `argument-hint` if applicable
- [ ] Has "What This Command Does" user-facing summary
- [ ] Has "Implementation Steps" with numbered sections

**Content:**

- [ ] Steps are numbered and clearly ordered
- [ ] Each step has specific, actionable instructions
- [ ] Tool usage is explicitly specified
- [ ] File checks are explicit (with code examples)
- [ ] Conditional logic uses clear if/else structure
- [ ] Anti-patterns are called out with "NEVER" or "DO NOT"
- [ ] Error handling is defined with specific actions
- [ ] Success criteria are clearly stated

**Writing Style:**

- [ ] Uses imperative/infinitive form (not second person)
- [ ] Specific, not vague ("Run make lint" not "Check for errors")
- [ ] Includes expected outcomes ("This should output...")
- [ ] Provides realistic examples (not foo/bar placeholders)

**Location:**

- [ ] Location (project vs global) is appropriate
- [ ] Directory exists or will be created
- [ ] File path is correct (`.claude/commands/` or `~/.claude/commands/`)

**Testing:**

- [ ] User knows how to invoke: `/command-name [arguments]`
- [ ] Command has been tested if possible
- [ ] Iterations incorporated user feedback

## Common Pitfalls

### 1. Vague Instructions

❌ **WRONG:**

```markdown
Fix any errors that appear
```

✅ **CORRECT:**

```markdown
If lint errors appear:

- Run `make fix` to auto-fix lint errors
- Run `make format` to fix formatting errors
- For manual fixes, use Edit tool to modify files
```

### 2. Missing Error Handling

❌ **WRONG:**

```markdown
Run make all-ci
Apply fixes
Done
```

✅ **CORRECT:**

```markdown
Run make all-ci

If exit code is 0:

- All checks passed, report success

If exit code is non-zero:

- Parse error output
- Apply targeted fixes
- Run again to verify
- Stop if same error appears 3 times
```

### 3. Ambiguous Conditionals

❌ **WRONG:**

```markdown
Check if file exists and do something
```

✅ **CORRECT:**

```markdown
Check if .PLAN.md exists:

If file exists:

- Read .PLAN.md for context
- Use plan summary in commit message

If file does not exist:

- Run git diff to analyze changes
- Create commit message from diff
```

### 4. Batch Operations

❌ **WRONG:**

```markdown
Fix all the errors, then mark all todos as completed
```

✅ **CORRECT:**

```markdown
For each error category:

1. Fix the errors in that category
2. Mark the todo as completed immediately
3. Move to next category

Do NOT batch todo completions at the end
```

### 5. Tool Confusion

❌ **WRONG:**

```markdown
Use an agent to run make
```

✅ **CORRECT:**

```markdown
Use Bash tool to run make commands:

\`\`\`bash
make all-ci
\`\`\`

DO NOT use Bash tool for make commands
```

### 6. Missing Context

❌ **WRONG:**

```markdown
Create a commit and submit PRs
```

✅ **CORRECT:**

```markdown
### 1. Check for Context Files

FIRST, check if .PLAN.md exists in repository root

### 2. Analyze Changes

- If .PLAN.md exists: read for context
- Otherwise: run git status and git diff HEAD

### 3. Create Commit

Based on context from step 1 and 2:

- Draft single-sentence commit message
- Check git log for repo style
- Create commit with git commit -m "message"

### 4. Submit PRs

Run: gt submit --stack --publish --no-edit
```

### 7. Poor Descriptions

❌ **WRONG:**

```yaml
---
description: A command that helps with CI stuff
---
```

✅ **CORRECT:**

```yaml
---
description: Run make all-ci and iteratively fix issues until all checks pass
---
```

The description appears in `/help` output - make it clear and action-oriented.

## Advanced Best Practices

### Multi-Step Verification

For complex workflows, verify each step:

```markdown
### 3. Create Commit

1. Stage changes:
   \`\`\`bash
   git add .
   \`\`\`

2. Verify staging:
   \`\`\`bash
   git status
   \`\`\`
   Should show files in "Changes to be committed"

3. Create commit:
   \`\`\`bash
   git commit -m "message"
   \`\`\`
   Should output "[branch-name abc1234] message"

4. Verify commit created:
   \`\`\`bash
   git log -1 --oneline
   \`\`\`
   Should show the new commit
```

### Iteration Control

For iterative commands, implement safeguards:

```markdown
## Iteration Control

**Maximum iterations**: 10 attempts

**Stuck detection logic:**

- Track errors seen in each iteration
- If same error appears 3 consecutive times: STOP
- If no progress after 5 iterations: STOP

**Stop immediately if:**

- Max iterations reached (10)
- Same error persists (3 times)
- Unrecoverable error encountered
```

### Context Gathering

For analysis-heavy commands, gather context systematically:

```markdown
## Context Gathering

Check these sources in order:

1. **Context files** (if they exist):
   - .PLAN.md - implementation plan
   - AGENTS.md - coding standards
   - CONTRIBUTING.md - contribution guidelines

2. **Git information**:
   - git status - current changes
   - git diff HEAD - actual diff
   - git log -5 --oneline - recent commits

3. **Project files** (if needed):
   - pyproject.toml - project config
   - Makefile - available commands
   - README.md - project overview

Stop gathering context once you have enough information - don't over-analyze.
```

### Output Formatting

Provide clear output format specifications:

```markdown
## Expected Output Format

After command completes, output should follow this format:

\`\`\`

## [Command Name] Results

**Status**: [SUCCESS/STUCK/ERROR]

**Actions Taken**:

1. [First action and result]
2. [Second action and result]
3. [Third action and result]

**Summary**:
[One sentence summary of what was accomplished]

**Next Steps**:
[What the user should do next, if applicable]
\`\`\`
```

## Summary

Effective slash commands:

1. **Use imperative form** (verb-first, not second person)
2. **Be specific** (not vague)
3. **Include outcomes** (what should happen)
4. **Provide examples** (realistic, not foo/bar)
5. **Specify tools** (Task tool with subagent_type)
6. **Call out anti-patterns** (NEVER/DO NOT)
7. **Define error handling** (explicit actions)
8. **State success criteria** (when to stop)
9. **Track progress** (TodoWrite for multi-step)
10. **Verify each step** (check results before proceeding)

Focus on creating commands that agents can execute autonomously without asking clarifying questions.


path: references/examples.md
content: # Command Examples

This document provides complete, real-world examples of slash commands from the erk project. Use these as references when creating new commands.

## Example 1: submit-stack (Workflow Automation Pattern)

**Pattern:** Workflow Automation (Analyze → Act → Report)

**Full source:**

```markdown
---
description: Create git commit and submit stack with Graphite
argument-hint: <description>
---

# Submit Stack

Automatically create a git commit with a helpful summary message and submit the entire Graphite stack as pull requests.

## What This Command Does

1. **Analyze changes**: First checks for .PLAN.md file to understand context, otherwise reviews git status and diff
2. **Create commit**: Generates a concise single-sentence commit message summarizing the changes
3. **Restack**: Runs `gt restack` to ensure all branches in the stack are properly rebased
4. **Submit stack**: Runs `gt submit --stack --publish --no-edit` to create/update PRs for the entire stack
5. **Report results**: Shows the submitted PRs and their URLs

## Usage

\`\`\`bash

# With description argument

/submit-stack "Add user authentication feature"

# Without argument (will analyze changes automatically)

/submit-stack
\`\`\`

## Implementation Steps

When this command is invoked:

### 1. Analyze Current Changes

**FIRST**: Check if `.PLAN.md` exists in the repository root:

\`\`\`bash
if [ -f .PLAN.md ]; then

# Use .PLAN.md for context

else

# Fall back to git analysis

fi
\`\`\`

If `.PLAN.md` exists:

- Read the plan file to understand what was implemented
- Use the plan's summary and goals to create the commit message

If no `.PLAN.md`:

- Run `git status` and `git diff HEAD` to see changes
- Review the changes to create an accurate summary

### 2. Create Git Commit

Based on the analysis:

- If user provided an argument, use it as the basis for the commit message
- If `.PLAN.md` exists, summarize what was implemented from the plan
- Otherwise, analyze the git changes and create a descriptive single-sentence summary
- Ensure the commit message follows the repository's commit style (check `git log` for patterns)
- **DO NOT include any Claude Code footer or co-authorship attribution**

\`\`\`bash
git add .
git commit -m "[Single sentence summary of what was done]"
\`\`\`

### 3. Restack the Stack

Ensure all branches in the stack are properly rebased:

\`\`\`bash
gt restack
\`\`\`

### 4. Submit Stack

Submit all PRs in the stack without interactive prompts:

\`\`\`bash
gt submit --stack --publish --no-edit --restack
\`\`\`

Flags explained:

- `--stack`: Submit entire stack (upstack + downstack)
- `--publish`: Publish any draft PRs
- `--no-edit`: Use commit messages as PR titles/descriptions without prompting
- `--restack`: Restack branches before submitting (if needed)

### 5. Show Results

After submission, show:

- Number of PRs created/updated
- PR URLs (extract from `gt` output)
- Current stack status with `gt log short`

## Important Notes

- **Check for .PLAN.md FIRST** before analyzing git changes
- **NEVER run additional exploration commands** beyond checking .PLAN.md, git status/diff/log
- **Stage all changes** with `git add .` before committing
- **Single sentence summary**: Keep commit message concise and focused
- **Follow repo patterns**: Check recent commits with `git log` to match style
- **NO Claude footer**: Do not add any attribution or generated-by footer
- If there are no staged or unstaged changes, report to the user and exit

## Error Handling

If any step fails:

- Report the specific command that failed
- Show the error message
- Ask the user how to proceed (don't retry automatically)

## Example Output

\`\`\`
Analyzing changes...
✓ Found .PLAN.md - using plan context
✓ Found changes in 3 files

Creating commit: "Add dot-agent submit-stack command for automated PR workflow"
✓ Commit created

Restacking branches...
✓ Stack restacked successfully

Submitting stack...
✓ 2 PRs created/updated:

- PR #123: dot-agent-claude-folder-support (new)
- PR #122: base-branch (updated)

Current stack:
◯ dot-agent-claude-folder-support (current)
◯ base-branch
◉ main
\`\`\`
```

**Key features of this example:**

- Argument handling (optional `<description>`)
- Context file priority check (`.PLAN.md` first)
- Conditional logic based on file existence
- Specific command flags explained
- Clear anti-patterns ("NEVER run additional exploration")
- Expected output format shown

## Example 2: ensure-ci (Iterative Fixing Pattern)

**Pattern:** Iterative Fixing (Run → Parse → Fix → Repeat)

**Full source:**

```markdown
---
description: Run make all-ci and iteratively fix issues until all checks pass
---

You are an implementation finalizer. Your task is to run `make all-ci` and iteratively fix any issues until all CI checks pass successfully.

## Your Mission

Run the full CI pipeline (`make all-ci`) and automatically fix any failures. Keep iterating until all checks pass or you get stuck on an issue that requires human intervention.

## CI Pipeline (make all-ci)

The `make all-ci` target runs these checks in order:

1. **lint** - Ruff linting checks
2. **format** - Ruff code formatting checks
3. **prettier-check** - Markdown formatting checks
4. **pyright** - Type checking
5. **test** - Pytest test suite

## Iteration Process

### 1. Initial Run

Start by running `make all-ci` to see the current state:

\`\`\`bash
make all-ci
\`\`\`

### 2. Parse Failures

Analyze the output to identify which check(s) failed. Common failure patterns:

- **Ruff lint failures**: Look for "ruff check" errors
- **Format failures**: Look for "ruff format --check" or files that would be reformatted
- **Prettier failures**: Look for markdown files that need formatting
- **Pyright failures**: Look for type errors with file paths and line numbers
- **Test failures**: Look for pytest failures with test names and assertion errors

### 3. Apply Targeted Fixes

Based on the failure type, apply appropriate fixes:

#### Ruff Lint Failures

\`\`\`bash
make fix # Runs: uv run ruff check --fix --unsafe-fixes
\`\`\`

#### Ruff Format Failures

\`\`\`bash
make format # Runs: uv run ruff format
\`\`\`

#### Prettier Failures

\`\`\`bash
make prettier # Runs: prettier --write '\*_/_.md'
\`\`\`

#### Pyright Type Errors

- Use Read tool to examine the file at the reported line number
- Use Edit tool to fix type annotations, add type hints, or fix type mismatches
- Follow the coding standards in AGENTS.md (use `list[...]` not `List[...]`, etc.)

#### Test Failures

- Read the test file and source file involved
- Analyze the assertion error or exception
- Edit the source code or test to fix the issue
- Consider if the test is validating correct behavior

### 4. Verify Fix

After applying fixes, run `make all-ci` again to verify:

\`\`\`bash
make all-ci
\`\`\`

### 5. Repeat Until Success

Continue the cycle: run → identify failures → fix → verify

## Iteration Control

**Safety Limits:**

- **Maximum iterations**: 10 attempts
- **Stuck detection**: If the same error appears 3 times in a row, stop
- **Progress tracking**: Use TodoWrite to show iteration progress

## Progress Reporting

Use TodoWrite to track your progress:

\`\`\`
Iteration 1: Fixing lint errors
Iteration 2: Fixing format errors
Iteration 3: Fixing type errors in src/erk/cli/commands/switch.py
Iteration 4: All checks passed
\`\`\`

Update the status as you work through each iteration.

## When to Stop

**SUCCESS**: Stop when `make all-ci` exits with code 0 (all checks passed)

**STUCK**: Stop and report to user if:

1. You've completed 10 iterations without success
2. The same error persists after 3 fix attempts
3. You encounter an error you cannot automatically fix

## Stuck Reporting Format

If you get stuck, report clearly:

\`\`\`markdown

## Finalization Status: STUCK

I was unable to resolve the following issue after N attempts:

**Check**: [lint/format/prettier/pyright/test]

**Error**:
[Exact error message]

**File**: [file path if applicable]

**Attempted Fixes**:

1. [What you tried first]
2. [What you tried second]
3. [What you tried third]

**Next Steps**:
[Suggest what needs to be done manually]
\`\`\`

## Success Reporting Format

When all checks pass:

\`\`\`markdown

## Finalization Status: SUCCESS

All CI checks passed after N iteration(s):

- Lint: PASSED
- Format: PASSED
- Prettier: PASSED
- Pyright: PASSED
- Tests: PASSED

The code is ready for commit/PR.
\`\`\`

## Important Guidelines

1. **Be systematic**: Fix one type of error at a time
2. **Run full CI**: Always run full `make all-ci`, not individual checks
3. **Track progress**: Use TodoWrite for every iteration
4. **Don't guess**: Read files before making changes
5. **Follow standards**: Adhere to AGENTS.md coding standards
6. **Fail gracefully**: Report clearly when stuck
7. **Be efficient**: Use targeted fixes (don't reformat everything for one lint error)

## Example Flow

\`\`\`
Iteration 1:

- Run make all-ci
- Found: 5 lint errors, 2 files need formatting
- Fix: Run make fix && make format
- Result: 3 lint errors remain

Iteration 2:

- Run make all-ci
- Found: 3 lint errors (imports)
- Fix: Edit files to fix import issues
- Result: All lint/format pass, 2 type errors

Iteration 3:

- Run make all-ci
- Found: 2 pyright errors in switch.py:45 and switch.py:67
- Fix: Add type annotations
- Result: All checks pass

SUCCESS
\`\`\`

## Begin Now

Start by running `make all-ci` and begin the iterative fix process. Track your progress with TodoWrite and report your final status clearly.
```

**Key features of this example:**

- Maximum iteration limit (10 attempts)
- Stuck detection (same error 3 times)
- Per-error-type fix instructions
- TodoWrite progress tracking requirement
- Clear success/failure reporting formats
- Detailed example flow showing iterations

## Example 3: create-implementation-plan (Agent Delegation Pattern)

**Pattern:** Agent Delegation (Context → Delegate → Iterate)

**Full source:**

```markdown
---
description: Create an implementation plan using the subagent agent
---

## ⚠️ PLANNING-ONLY MODE ACTIVE

I'll help you create an implementation plan using the specialized planning agent. This workflow is designed for **planning only** - no code will be written until the plan is finalized and saved to disk.

### How This Works

1. **You provide context** about what needs to be built
2. **The agent creates a plan** (displayed in terminal for review)
3. **We iterate together** until the plan is perfect
4. **Plan is saved to disk** as a markdown file
5. **Then (and only then)** implementation can begin

### Provide Your Planning Context

You can share:

- A feature you want to implement
- An error message or bug to fix
- Performance issues to optimize
- A refactoring goal
- Any relevant context or requirements

**What would you like to plan?**

---

**IMPORTANT AGENT INSTRUCTIONS:**

When invoking the subagent agent:

1. **DO NOT write any code during planning phase**
2. **DO NOT use Edit, Write, or any modification tools**
3. **ONLY output the plan to terminal for iterative review**
4. **ONLY persist to disk after explicit user approval**
5. The agent should remain in "Phase 1: Human-Readable Planning" mode until the user explicitly approves with signals like "looks good", "approved", or "ready to implement"

The goal is to create a comprehensive implementation plan that will be saved as a `.md` file at the repository root, which can then guide future implementation work.
```

**Key features of this example:**

- User-facing explanation of the workflow
- Clear phase boundaries (planning vs implementation)
- Explicit anti-patterns ("DO NOT write code")
- User approval trigger ("looks good", "approved")
- Tells agent which specialized agent to invoke
- Specifies where to save output (`.md` at root)

## Example 4: codex-review (Simple Execution Pattern)

**Pattern:** Simple Execution (Parse Arguments → Execute → Return Output)

**Minimal example structure:**

```markdown
---
description: Perform a local code review using repository standards and best practices
argument-hint: [base-branch]
---

# Codex Review

Performs a thorough code review of changes between the current branch and the base branch.

## What This Command Does

1. Determines base branch (uses provided argument or defaults to main/master)
2. Runs codex-review script with the base branch
3. Displays review findings and suggestions

## Usage

\`\`\`bash

# With explicit base branch

/codex-review develop

# Without argument (auto-detects main/master)

/codex-review
\`\`\`

## Implementation Steps

### 1. Determine Base Branch

If `[base-branch]` argument is provided:

- Use the specified branch

If no argument:

- Check if `main` branch exists: `git rev-parse --verify main`
- If yes, use `main`
- If no, use `master`

### 2. Run Review Script

Execute the review script with the determined base branch:

\`\`\`bash
scripts/codex-review.py [base-branch]
\`\`\`

### 3. Display Results

Show the script output directly to the user, including:

- Files reviewed
- Issues found
- Suggestions for improvements
- Compliance with coding standards

## Error Handling

If the script fails:

- Show the error message
- Check if the base branch exists
- Verify the script is executable

## Notes

- Square brackets `[base-branch]` indicate optional argument
- Script handles actual review logic
- Command is a simple wrapper for convenience
```

**Key features of this example:**

- Optional argument handling (square brackets)
- Argument defaulting logic
- Direct script invocation
- Minimal additional logic
- Clear output pass-through

## Pattern Comparison

| Feature               | submit-stack             | ensure-ci          | create-implementation-plan | codex-review             |
| --------------------- | ------------------------ | ------------------ | -------------------------- | ------------------------ |
| **Pattern**           | Workflow Automation      | Iterative Fixing   | Agent Delegation           | Simple Execution         |
| **Arguments**         | Optional `<description>` | None               | None                       | Optional `[base-branch]` |
| **Context Files**     | Checks `.PLAN.md`        | Checks `AGENTS.md` | None                       | None                     |
| **Iterations**        | Single pass              | Up to 10           | Iterative (user-driven)    | Single pass              |
| **Tool Usage**        | Git, Graphite            | Make, Edit tools   | Task tool (agent)          | Script execution         |
| **Progress Tracking** | Inline reporting         | TodoWrite required | None (user reviews)        | None                     |
| **Error Handling**    | Ask user                 | Stop if stuck      | None specified             | Show error message       |
| **Success Criteria**  | PRs submitted            | Exit code 0        | User approves plan         | Script completes         |

## Usage Guidance

**Use submit-stack as a reference when:**

- Command needs to check context files first
- Workflow has clear sequential steps
- Git operations are involved
- Results need clear reporting

**Use ensure-ci as a reference when:**

- Command needs to iterate until success
- Multiple error types need different fixes
- Progress tracking is important
- Stuck detection is needed

**Use create-implementation-plan as a reference when:**

- Command delegates to specialized agent
- User review/approval is required
- No direct code modification should happen
- Output is saved to specific location

**Use codex-review as a reference when:**

- Command is a simple wrapper
- Main logic is in external script
- Argument handling is straightforward
- Output is passed through directly


path: references/patterns.md
content: # Command Patterns

This document describes the common patterns for slash commands, helping you choose the right structure for your workflow.

## Pattern Categories

### 1. Workflow Automation Pattern

**Structure:** Analyze → Act → Report

**When to use:**

- Multi-step workflows with clear sequence
- Commands that need to analyze before acting
- Workflows that produce specific outputs (commits, PRs, reports)

**Example workflow:**

1. Check for context files (e.g., `.PLAN.md`)
2. Analyze current state (git status, file changes)
3. Perform actions (create commit, submit PR)
4. Report results to user

**Key features:**

- Explicit file check order
- Conditional logic based on file existence
- Clear success output format
- Context-aware decision making

**Pattern example:**

```markdown
1. Check for .PLAN.md in repository root
   - If exists: use plan context for commit message
   - If not: analyze git changes and draft message

2. Review git status and diff
   - Identify staged and unstaged changes
   - Determine scope of changes

3. Create commit with descriptive message
   - Follow repository's commit message style
   - Include co-author attribution

4. Submit PRs with Graphite
   - Use gt stack submit
   - Report PR URLs to user
```

### 2. Iterative Fixing Pattern

**Structure:** Run → Parse → Fix → Repeat

**When to use:**

- Commands that fix issues iteratively (linting, tests, CI)
- Workflows that need multiple attempts to succeed
- Tasks with clear pass/fail criteria

**Example workflow:**

1. Run check command (e.g., `make all-ci`)
2. Parse failures by type
3. Apply targeted fixes
4. Run check again to verify
5. Repeat until success or max iterations reached

**Key features:**

- Iteration control (max attempts, stuck detection)
- Progress tracking with TodoWrite
- Clear stopping conditions
- Categorization of failure types
- Incremental fix application

**Pattern example:**

```markdown
1. Run make all-ci (max 10 iterations)

2. If check fails:
   - Parse error output by category (pyright, ruff, tests)
   - Create todos for each error category
   - Apply fixes for each category sequentially
   - Mark todo complete after fixing each category

3. After each fix iteration:
   - Run make all-ci again
   - Check if new errors appeared
   - If stuck (same errors 2+ times): stop and report

4. Stop when:
   - All checks pass (exit code 0)
   - Max iterations reached
   - Detected stuck state
```

### 3. Agent Delegation Pattern

**Structure:** Context → Delegate → Iterate

**When to use:**

- Complex tasks requiring specialized agents
- Multi-phase workflows with human review
- Tasks that benefit from agent specialization

**Example workflow:**

1. Present planning context to user
2. Invoke specialized agent (via Task tool)
3. Agent creates plan/output iteratively
4. Plan is reviewed and refined by user
5. Save results to disk after approval

**Key features:**

- Clear agent invocation instructions
- Phase-based workflow (planning → review → execution)
- Explicit save-to-disk trigger
- User review checkpoints
- Context gathering before delegation

**Pattern example:**

```markdown
1. Present planning context
   - Explain what the agent will do
   - Set expectations for iterative process
   - Mention that user can refine the output

2. Invoke subagent agent
   - Use Task tool with subagent_type="subagent"
   - Pass task description and context
   - Do NOT attempt to write plan yourself

3. Agent works autonomously
   - Creates initial plan
   - Iterates with user feedback
   - Refines based on questions/concerns

4. After user approves plan
   - Save to .PLAN.md
   - Confirm location with user
   - Explain next steps (execution)
```

### 4. Simple Execution Pattern

**Structure:** Parse Arguments → Execute → Return Output

**When to use:**

- Single-step commands with arguments
- Wrapper commands for existing tools
- Commands that simply run and report

**Example workflow:**

1. Parse command arguments
2. Run specific command or script with arguments
3. Handle and display output
4. Report success or failure

**Key features:**

- Argument handling (required vs optional)
- Direct tool invocation
- Minimal logic
- Output formatting

**Pattern example:**

```markdown
1. Parse [base-branch] argument
   - If provided: use specified branch
   - If not provided: use main/master

2. Run codex-review script
   - Pass base-branch to script
   - Capture output

3. Display results
   - Show review findings
   - Report issues found
   - Suggest fixes if applicable
```

## Advanced Patterns

### Multi-Agent Orchestration

**When to use:** Complex workflows requiring multiple specialized agents in sequence

**Pattern:**

```markdown
1. Use Task tool with subagent_type="Explore" to find relevant files
   - Search for specific patterns
   - Identify key components

2. Use Task tool with subagent_type="subagent" to create plan
   - Pass context from exploration
   - Generate detailed implementation plan
   - Review with user

3. Execute the plan directly in the main conversation
   - Load plan from .PLAN.md
   - Use TodoWrite to track phases
   - Execute steps systematically
   - Report completion
```

### Context File Priority Checks

**When to use:** Commands that can operate in different modes based on available context

**Pattern:**

```markdown
Check these files in order for context:

1. .PLAN.md - implementation plan (highest priority)
2. .github/CONTRIBUTING.md - contribution guidelines
3. AGENTS.md - coding standards
4. README.md - project overview

Use the first file found to inform the workflow. Different files trigger different behaviors.
```

### Conditional Tool Selection

**When to use:** Commands that choose tools/approach based on task complexity

**Pattern:**

```markdown
Analyze scope of changes:

If changes span 3+ files OR involve new abstractions:

- Use subagent agent
- Create detailed plan
- Execute with subagent

Otherwise:

- Execute changes directly
- Use simpler workflow
- Skip planning overhead
```

### Makefile Integration Pattern

**When to use:** Commands that need to run make targets

**Pattern:**

```markdown
**IMPORTANT:** Always use Bash tool for pytest/pyright/ruff/prettier/make/gt commands

1. Use Bash tool directly
   - Run commands like: "make all-ci", "pytest tests/", "pyright", etc.
   - Bash tool will execute and return output

2. Process command results
   - Check exit code
   - Parse any errors
   - Apply fixes if needed
```

### Progressive Disclosure Pattern

**When to use:** Commands that start simple but can get more complex based on results

**Pattern:**

```markdown
1. Start with minimal check
   - Run basic validation
   - Identify if deeper work needed

2. If issues found:
   - Expand scope progressively
   - Add todos for each issue category
   - Handle incrementally

3. Only go deeper if necessary
   - Don't over-analyze upfront
   - Let results guide next steps
   - Stop when criteria met
```

## Pattern Selection Guide

| If the command needs to...              | Use this pattern           |
| --------------------------------------- | -------------------------- |
| Create commits/PRs based on analysis    | Workflow Automation        |
| Fix issues iteratively until passing    | Iterative Fixing           |
| Create plans or delegate to specialists | Agent Delegation           |
| Run a tool and display results          | Simple Execution           |
| Coordinate multiple agents              | Multi-Agent Orchestration  |
| Check multiple context files            | Context File Priority      |
| Choose approach based on complexity     | Conditional Tool Selection |
| Run make targets                        | Makefile Integration       |
| Start simple and expand as needed       | Progressive Disclosure     |

## Combining Patterns

Commands often combine multiple patterns. For example:

**submit-stack combines:**

- Context File Priority (check .PLAN.md)
- Workflow Automation (analyze → commit → submit)
- Conditional Tool Selection (use plan if exists)

**ensure-ci combines:**

- Iterative Fixing (run → fix → repeat)
- Makefile Integration (use makefile-runner)
- Progressive Disclosure (expand todos as issues found)

## Writing Pattern-Specific Instructions

When implementing a pattern, include these elements:

### For All Patterns

- Clear sequence of steps (numbered)
- Expected outcomes at each step
- Error handling approach
- Success criteria

### Pattern-Specific Elements

**Workflow Automation:**

- File checks before analysis
- Conditional branches
- Output format specifications

**Iterative Fixing:**

- Max iteration count
- Stuck detection logic
- Progress tracking requirements
- Per-category fix instructions

**Agent Delegation:**

- Exact Task tool invocation syntax
- Context to pass to agent
- User review checkpoints
- Save-to-disk instructions

**Simple Execution:**

- Argument parsing logic
- Command invocation syntax
- Output formatting requirements


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (MEDIUM)