davila7--claude-code-templates/cli-tool/components/skills/development/command-creator/references/examples.md

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:

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

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

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

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