Command Creator – Patterns

# 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