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

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

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