Command Creator

Command Creator

This skill guides the creation of Claude Code slash commands - reusable workflows that can be invoked with /command-name in Claude Code conversations.

About Slash Commands

Slash commands are markdown files stored in .claude/commands/ (project-level) or ~/.claude/commands/ (global/user-level) that get expanded into prompts when invoked. They're ideal for:

• Repetitive workflows (code review, PR submission, CI fixing)
• Multi-step processes that need consistency
• Agent delegation patterns
• Project-specific automation

When to Use This Skill

Invoke this skill when users:

• Ask to "create a command" or "make a slash command"
• Want to automate a repetitive workflow
• Need to document a consistent process for reuse
• Say "I keep doing X, can we make a command for it?"
• Want to create project-specific or global commands

Bundled Resources

This skill includes reference documentation for detailed guidance:

• references/patterns.md - Command patterns (workflow automation, iterative fixing, agent delegation, simple execution)
• references/examples.md - Real command examples with full source (submit-stack, ensure-ci, create-implementation-plan)
• references/best-practices.md - Quality checklist, common pitfalls, writing guidelines, template structure

Load these references as needed when creating commands to understand patterns, see examples, or ensure quality.

Command Structure Overview

Every slash command is a markdown file with:

---
description: Brief description shown in /help (required)
argument-hint: <placeholder> (optional, if command takes arguments)
---

# Command Title

[Detailed instructions for the agent to execute autonomously]

Command Creation Workflow

Step 1: Determine Location

Auto-detect the appropriate location:

1. Check git repository status: git rev-parse --is-inside-work-tree 2>/dev/null 2. Default location:

• If in git repo → Project-level: .claude/commands/
• If not in git repo → Global: ~/.claude/commands/

3. Allow user override:

• If user explicitly mentions "global" or "user-level" → Use ~/.claude/commands/
• If user explicitly mentions "project" or "project-level" → Use .claude/commands/

Report the chosen location to the user before proceeding.

Step 2: Show Command Patterns

Help the user understand different command types. Load references/patterns.md to see available patterns:

• Workflow Automation - Analyze → Act → Report (e.g., submit-stack)
• Iterative Fixing - Run → Parse → Fix → Repeat (e.g., ensure-ci)
• Agent Delegation - Context → Delegate → Iterate (e.g., create-implementation-plan)
• Simple Execution - Run command with args (e.g., codex-review)

Ask the user: "Which pattern is closest to what you want to create?" This helps frame the conversation.

Step 3: Gather Command Information

Ask the user for key information:

A. Command Name and Purpose

Ask:

• "What should the command be called?" (for filename)
• "What does this command do?" (for description field)

Guidelines:

• Command names MUST be kebab-case (hyphens, NOT underscores)
• ✅ CORRECT: submit-stack, ensure-ci, create-from-plan
• ❌ WRONG: submit_stack, ensure_ci, create_from_plan
• File names match command names: my-command.md → invoked as /my-command
• Description should be concise, action-oriented (appears in /help output)

B. Arguments

Ask:

• "Does this command take any arguments?"
• "Are arguments required or optional?"
• "What should arguments represent?"

If command takes arguments:

• Add argument-hint: <placeholder> to frontmatter
• Use <angle-brackets> for required arguments
• Use [square-brackets] for optional arguments

C. Workflow Steps

Ask:

• "What are the specific steps this command should follow?"
• "What order should they happen in?"
• "What tools or commands should be used?"

Gather details about:

• Initial analysis or checks to perform
• Main actions to take
• How to handle results
• Success criteria
• Error handling approach

D. Tool Restrictions and Guidance

Ask:

• "Should this command use any specific agents or tools?"
• "Are there any tools or operations it should avoid?"
• "Should it read any specific files for context?"

Step 4: Generate Optimized Command

Create the command file with agent-optimized instructions. Load references/best-practices.md for:

• Template structure
• Best practices for agent execution
• Writing style guidelines
• Quality checklist

Key principles:

• Use imperative/infinitive form (verb-first instructions)
• Be explicit and specific
• Include expected outcomes
• Provide concrete examples
• Define clear error handling

Step 5: Create the Command File

1. Determine full file path:

• Project: .claude/commands/[command-name].md
• Global: ~/.claude/commands/[command-name].md

2. Ensure directory exists:

   mkdir -p [directory-path]

3. Write the command file using the Write tool

4. Confirm with user:

• Report the file location
• Summarize what the command does
• Explain how to use it: /command-name [arguments]

Step 6: Test and Iterate (Optional)

If the user wants to test:

1. Suggest testing: You can test this command by running: /command-name [arguments] 2. Be ready to iterate based on feedback 3. Update the file with improvements as needed

Quick Tips

For detailed guidance, load the bundled references:

• Load references/patterns.md when designing the command workflow
• Load references/examples.md to see how existing commands are structured
• Load references/best-practices.md before finalizing to ensure quality

Common patterns to remember:

• Use Bash tool for pytest, pyright, ruff, prettier, make, gt commands
• Use Task tool to invoke subagents for specialized tasks
• Check for specific files first (e.g., .PLAN.md) before proceeding
• Mark todos complete immediately, not in batches
• Include explicit error handling instructions
• Define clear success criteria

Summary

When creating a command:

1. Detect location (project vs global) 2. Show patterns to frame the conversation 3. Gather information (name, purpose, arguments, steps, tools) 4. Generate optimized command with agent-executable instructions 5. Create file at appropriate location 6. Confirm and iterate as needed

Focus on creating commands that agents can execute autonomously, with clear steps, explicit tool usage, and proper error handling.

Command Creator

A comprehensive skill for creating optimized, agent-executable slash commands in Claude Code. This skill guides you through the entire process of designing, implementing, and testing reusable workflow automation commands.

Table of Contents

• Overview
• When to Use This Skill
• What Are Slash Commands?
• Key Features
• How It Works
• Command Patterns
• Location Strategy
• Bundled Resources
• Usage Examples
• Best Practices
• Common Use Cases

---

Overview

The Command Creator skill helps you transform repetitive workflows into reusable slash commands that can be invoked with /command-name in Claude Code conversations. It provides expert guidance on command structure, agent optimization, and best practices to ensure your commands execute reliably and autonomously.

Purpose: Create high-quality, agent-executable slash commands with proper structure, clear instructions, and optimal tool usage patterns.

Target Users: Developers who want to:

• Automate repetitive workflows
• Document consistent processes for reuse
• Create project-specific or global automation
• Delegate complex tasks to specialized agents

---

When to Use This Skill

Invoke this skill when you need to:

• Create a new slash command from scratch
• Automate a workflow you find yourself repeating
• Document a multi-step process for consistent execution
• Convert manual procedures into automated commands
• Create project-specific commands for team workflows
• Build global commands for personal productivity

Trigger Phrases:

• "create a command"
• "make a slash command"
• "add a command"
• "I keep doing X, can we make a command for it?"
• "automate this workflow"
• "create a reusable command"

---

What Are Slash Commands?

Slash commands are markdown files stored in .claude/commands/ (project-level) or ~/.claude/commands/ (global/user-level) that get expanded into prompts when invoked.

Structure:

---
description: Brief description shown in /help (required)
argument-hint: <placeholder> (optional, if command takes arguments)
---

# Command Title

[Detailed instructions for the agent to execute autonomously]

Invocation:

/command-name [arguments]

Storage Locations:

• Project-level: .claude/commands/my-command.md (only available in this project)
• Global/User-level: ~/.claude/commands/my-command.md (available everywhere)

---

Key Features

1. Intelligent Location Detection

Automatically determines whether commands should be project-level or global based on:

• Current directory git repository status
• User explicit preferences
• Command scope and purpose

2. Pattern-Based Design

Guides you through proven command patterns:

• Workflow Automation: Multi-step processes with analysis, action, and reporting
• Iterative Fixing: Continuous improvement loops (run → parse → fix → repeat)
• Agent Delegation: Complex tasks broken into specialized agent work
• Simple Execution: Direct tool or script execution with arguments

3. Agent-Optimized Instructions

Creates commands that agents can execute autonomously with:

• Imperative/infinitive verb-first instructions
• Explicit tool usage specifications
• Clear success criteria
• Concrete error handling
• Expected outcomes defined

4. Quality Assurance

Includes comprehensive best practices for:

• Proper naming conventions (kebab-case enforced)
• Argument handling and hints
• Tool restriction guidelines
• Error recovery strategies
• Progress reporting patterns

5. Bundled Reference Documentation

Provides three comprehensive reference files:

• patterns.md: Command design patterns with detailed examples
• examples.md: Real-world command implementations
• best-practices.md: Quality checklist and writing guidelines

---

How It Works

The Command Creator follows a structured 6-step workflow:

Step 1: Determine Location

Auto-detection Logic: 1. Check if current directory is inside a git repository 2. Default to project-level (.claude/commands/) if in git repo 3. Default to global (~/.claude/commands/) if not in git repo 4. Allow user override for explicit location preference

User is informed of the chosen location before proceeding.

Step 2: Show Command Patterns

Present available command patterns to help frame the conversation:

• Workflow Automation: Analyze → Act → Report (e.g., submit PR stack)
• Iterative Fixing: Run → Parse → Fix → Repeat (e.g., ensure CI passes)
• Agent Delegation: Context → Delegate → Iterate (e.g., create implementation plan)
• Simple Execution: Run command with args (e.g., code review)

User selects the closest pattern to their needs.

Step 3: Gather Command Information

Interactive Q&A to collect:

A. Command Name and Purpose

• Command name (must be kebab-case: my-command, not my_command)
• Description for /help output
• Purpose and scope

B. Arguments

• Does it take arguments? (yes/no)
• Required or optional?
• Argument hint format (<required> or [optional])

C. Workflow Steps

• Specific steps in execution order
• Tools/commands to use
• Success criteria
• Error handling approach

D. Tool Restrictions

• Specific agents or tools to use
• Operations to avoid
• Context files to read

Step 4: Generate Optimized Command

Create agent-executable instructions using:

• Template structure from best-practices.md
• Imperative verb-first language
• Explicit tool specifications
• Clear expected outcomes
• Concrete examples where needed

Step 5: Create the Command File

1. Construct full file path (project or global) 2. Ensure directory exists (mkdir -p) 3. Write command file using Write tool 4. Confirm with user:

• Report file location
• Summarize command function
• Explain invocation syntax

Step 6: Test and Iterate

1. Suggest testing the command 2. Wait for user feedback 3. Iterate and improve based on results 4. Update file with refinements

---

Command Patterns

1. Workflow Automation

Use Case: Multi-step processes requiring analysis, action, and reporting

Example: Submit PR stack

1. Analyze git history to identify commit stack
2. Create PRs for each commit with proper dependencies
3. Report created PRs with links and status

Key Characteristics:

• Sequential steps with dependencies
• Clear analysis phase before action
• Comprehensive final report

2. Iterative Fixing

Use Case: Continuous improvement until success criteria met

Example: Ensure CI passes

1. Run tests and capture output
2. Parse failures and errors
3. Fix identified issues
4. Repeat until all tests pass

Key Characteristics:

• Loop until success condition
• Parse errors to guide fixes
• Progress tracking across iterations

3. Agent Delegation

Use Case: Complex tasks requiring specialized agent expertise

Example: Create implementation plan

1. Gather context (requirements, codebase)
2. Delegate to subagent agent
3. Iterate on plan with user feedback
4. Save final plan to .PLAN.md

Key Characteristics:

• Use Task tool for specialized agents
• Pass relevant context to delegated agent
• Iterate on specialized agent output

4. Simple Execution

Use Case: Direct tool/script execution with arguments

Example: Code review

1. Run codex review on specified files
2. Present results to user

Key Characteristics:

• Minimal logic, direct execution
• Pass through arguments to underlying tool
• Quick feedback loop

---

Location Strategy

Project-Level Commands (.claude/commands/)

When to Use:

• Command is specific to this project's workflow
• Requires project-specific context or files
• Team members should share this command
• Automation tied to project structure

Examples:

• /submit-stack (project's PR submission workflow)
• /ensure-ci (project's test suite)
• /deploy-staging (project's deployment process)

Advantages:

• Version controlled with project
• Shared across team
• Project-specific customization

Global Commands (~/.claude/commands/)

When to Use:

• Command works across any project
• Personal productivity tool
• Generic workflow automation
• No project-specific dependencies

Examples:

• /codex-review (code review any files)
• /create-implementation-plan (generic planning)
• /git-cleanup (git maintenance anywhere)

Advantages:

• Available everywhere
• Personal customization
• Independent of project

---

Bundled Resources

This skill includes three comprehensive reference files in the references/ directory:

references/patterns.md

Purpose: Detailed command design patterns with implementation guidance

Contents:

• Pattern 1: Workflow Automation (Analyze → Act → Report)
• Pattern 2: Iterative Fixing (Run → Parse → Fix → Repeat)
• Pattern 3: Agent Delegation (Context → Delegate → Iterate)
• Pattern 4: Simple Execution (Run command with args)
• When to use each pattern
• Tool usage recommendations
• Real examples for each pattern

Load When: Designing the command workflow and choosing the right pattern

references/examples.md

Purpose: Real-world command implementations with full source code

Contents:

• /submit-stack: Submit PR stack from git history
• /ensure-ci: Iteratively fix CI failures
• /create-implementation-plan: Delegate to planner agent
• Full markdown source for each example
• Annotations explaining key decisions
• Best practices demonstrated in context

Load When: Need concrete examples of how to structure specific command types

references/best-practices.md

Purpose: Quality checklist and writing guidelines

Contents:

• Command template structure
• Agent-optimized writing style
• Common pitfalls to avoid
• Quality checklist before finalizing
• Tool restriction patterns
• Error handling strategies
• Naming conventions

Load When: Finalizing command to ensure quality and completeness

---

Usage Examples

Example 1: Create Project-Level CI Fixer

User Request: "I keep fixing CI failures manually. Can we make a command for this?"

Skill Flow: 1. Detects project-level (in git repo) 2. Suggests "Iterative Fixing" pattern 3. Gathers info:

• Name: ensure-ci
• Description: "Iteratively fix CI failures until all tests pass"
• Arguments: None
• Steps: Run tests → Parse failures → Fix issues → Repeat

4. Generates command with Bash tool for pytest 5. Creates .claude/commands/ensure-ci.md 6. User invokes: /ensure-ci

Example 2: Create Global Code Review Command

User Request: "Create a global command to review code with Codex"

Skill Flow: 1. Detects global (user requests "global") 2. Suggests "Simple Execution" pattern 3. Gathers info:

• Name: codex-review
• Description: "Review code files using Codex"
• Arguments: <files> (required)
• Steps: Run codex review → Present results

4. Generates command with codex skill invocation 5. Creates ~/.claude/commands/codex-review.md 6. User invokes: /codex-review src/app.py src/utils.py

Example 3: Create PR Submission Workflow

User Request: "Make a command that analyzes my commits and creates a PR stack"

Skill Flow: 1. Detects project-level (in git repo) 2. Suggests "Workflow Automation" pattern 3. Gathers info:

• Name: submit-stack
• Description: "Create PR stack from commit history"
• Arguments: [base-branch] (optional, defaults to main)
• Steps: Analyze commits → Create PRs → Report results

4. Generates command with git analysis and gh CLI 5. Creates .claude/commands/submit-stack.md 6. User invokes: /submit-stack or /submit-stack develop

---

Best Practices

Naming Conventions

MUST use kebab-case (hyphens, not underscores):

• Correct: submit-stack, ensure-ci, create-from-plan
• Wrong: submit_stack, ensure_ci, create_from_plan

Argument Hints

• Use <angle-brackets> for required arguments
• Use [square-brackets] for optional arguments
• Examples:
• argument-hint: <file-path> (required)
• argument-hint: [base-branch] (optional)
• argument-hint: <command> [args...] (mixed)

Agent-Optimized Instructions

Write in imperative/infinitive form:

• Correct: "Run pytest to execute tests"
• Wrong: "You should run pytest to execute tests"

Be explicit about tools:

• Correct: "Use the Bash tool to run pytest tests/"
• Wrong: "Run the tests"

Define success criteria:

• Correct: "Continue until all tests pass (exit code 0)"
• Wrong: "Fix the tests"

Include error handling:

• Correct: "If pytest fails, parse the output to identify failing tests, then fix each one"
• Wrong: "Fix any test failures"

Tool Restrictions

Use Bash tool for:

• pytest, pyright, ruff, prettier
• make, npm, yarn
• gt (git-town commands)

Use Task tool for:

• Specialized agents (subagent, subagents)
• Long-running or complex delegated tasks

Avoid in commands:

• Interactive prompts (commands must be autonomous)
• User confirmation loops (unless explicit in pattern)
• Ambiguous instructions that require interpretation

---

Common Use Cases

Development Workflows

• Submit PRs: Analyze commits, create PR stack with dependencies
• Fix CI: Iteratively run tests, parse failures, fix issues
• Code Review: Run linters, formatters, static analysis
• Deploy: Build, test, deploy to staging/production

Project Automation

• Setup: Initialize project structure, install dependencies
• Documentation: Generate docs from code, update README
• Testing: Run full test suite with coverage reports
• Release: Bump version, create changelog, tag release

Personal Productivity

• Git Cleanup: Delete merged branches, prune remotes
• Codebase Analysis: Generate architecture diagrams, dependency graphs
• Refactoring: Apply consistent patterns across files
• Planning: Create implementation plans for features

Team Collaboration

• Onboarding: Setup development environment, clone repos
• Standards: Enforce code style, commit message format
• Knowledge: Document architectural decisions, add examples
• Review: Automated code review checks before human review

---

Summary

The Command Creator skill provides a comprehensive, guided workflow for creating high-quality slash commands in Claude Code. By following proven patterns, gathering detailed requirements, and generating agent-optimized instructions, it ensures your commands are:

• Reliable: Execute autonomously without manual intervention
• Maintainable: Clear structure and documentation
• Reusable: Available project-wide or globally
• Optimized: Use appropriate tools and agents for the task

Next Steps: 1. Identify a repetitive workflow you want to automate 2. Invoke the command-creator skill 3. Follow the guided workflow to create your command 4. Test and iterate based on results 5. Share with your team (project-level) or use personally (global)

Get Started:

/command-creator

Or simply say: "I want to create a command that [does something]"

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.

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

Fix any errors that appear

✅ CORRECT:

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:

Run make all-ci
Apply fixes
Done

✅ CORRECT:

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:

Check if file exists and do something

✅ CORRECT:

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:

Fix all the errors, then mark all todos as completed

✅ CORRECT:

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:

Use an agent to run make

✅ CORRECT:

Use Bash tool to run make commands:

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

DO NOT use Bash tool for make commands

6. Missing Context

❌ WRONG:

Create a commit and submit PRs

✅ CORRECT:

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

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

✅ CORRECT:

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

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

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

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

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

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

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

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:

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:

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:

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:

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:

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:

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:

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:

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

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

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