gh-vanman2024-domain-plugin-builder-plugins-domain-plugin-builder/skills/build-assistant/templates/commands/template-command-patterns.md

Master Command Pattern Template

This template shows how to structure slash commands using the Goal → Actions → Phase pattern. Choose the appropriate pattern based on your command's complexity.

---

Pattern Selection Guide

Pattern 1: Simple (No Agents)

• Use for: Mechanical tasks, script execution, file operations
• Examples: version bumping, config updates, git operations
• No AI decision-making needed

Pattern 2: Single Agent

• Use for: One specialized capability needed
• Examples: project analysis, code generation, architecture design
• One focused AI task

Pattern 3: Sequential (Multiple Phases)

• Use for: Multi-phase workflows with dependencies
• Examples: build → test → deploy, setup → configure → verify
• Steps must run in order

Pattern 4: Parallel (Multiple Agents)

• Use for: Independent tasks that can run simultaneously
• Examples: lint + test + security audit
• No dependencies between tasks, faster execution

---

Pattern 1: Simple Command Template

---
description: [What this command does]
argument-hint: [argument-placeholder]
allowed-tools: Read, Write, Bash(*), Glob, Grep
---

**Arguments**: $ARGUMENTS

Goal: [What this command accomplishes]

Core Principles:
- [Principle 1: e.g., "Detect don't assume"]
- [Principle 2: e.g., "Validate before executing"]
- [Principle 3: e.g., "Provide clear feedback"]

Phase 1: Discovery
Goal: [Understand what needs to be done]

Actions:
- Parse $ARGUMENTS for required inputs
- Detect project type/framework
- Load relevant configuration files
- Example: !{bash ls package.json pyproject.toml 2>/dev/null}

Phase 2: Validation
Goal: [Verify inputs and environment]

Actions:
- Check if required files exist
- Validate input parameters
- Confirm prerequisites met
- Example: @package.json

Phase 3: Execution
Goal: [Perform the main task]

Actions:
- Execute scripts or commands
- Example: !{bash npm run build}
- Handle errors gracefully
- Provide progress feedback

Phase 4: Summary
Goal: [Report results]

Actions:
- Display what was accomplished
- Show next steps if applicable
- Report any warnings or issues

---

Pattern 2: Single Agent Template

---
description: [What this command does]
argument-hint: [argument-placeholder]
allowed-tools: Task, Read, Write, Bash(*), Glob, Grep, AskUserQuestion
---

**Arguments**: $ARGUMENTS

Goal: [What this command accomplishes]

Core Principles:
- [Principle 1: e.g., "Understand before acting"]
- [Principle 2: e.g., "Ask when uncertain"]
- [Principle 3: e.g., "Follow existing patterns"]

Phase 1: Discovery
Goal: [Gather context and requirements]

Actions:
- If $ARGUMENTS is unclear, use AskUserQuestion to gather:
  - What is the goal?
  - What are the constraints?
  - Any specific requirements?
- Load relevant files for context
- Example: @src/config.ts

Phase 2: Analysis
Goal: [Understand existing codebase and patterns]

Actions:
- Read relevant files identified
- Understand current architecture
- Identify where changes need to be made
- Example: !{bash find src -name "*.ts" | head -10}

Phase 3: Planning
Goal: [Design the approach]

Actions:
- Outline the implementation steps
- Identify potential issues
- Confirm approach with user if significant
- Present clear plan

Phase 4: Implementation
Goal: [Execute with agent]

Actions:

Task(description="[Accomplish task]", subagent_type="[agent-name]", prompt="You are the [agent-name] agent. [Accomplish task] for $ARGUMENTS.

Context: [What context is needed]

Requirements:
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

Expected output: [What should be delivered]")

Phase 5: Review
Goal: [Verify results]

Actions:
- Check agent's output
- Verify functionality
- Run validation if applicable
- Example: !{bash npm run typecheck}

Phase 6: Summary
Goal: [Document what was accomplished]

Actions:
- Summarize changes made
- Highlight key decisions
- Suggest next steps

---

Pattern 3: Sequential Multi-Phase Template

---
description: [What this command does]
argument-hint: [argument-placeholder]
allowed-tools: Task, Read, Write, Edit, Bash(*), Glob, Grep, AskUserQuestion, TodoWrite
---

**Arguments**: $ARGUMENTS

Goal: [What this command accomplishes - typically a complete workflow]

Core Principles:
- Ask clarifying questions early
- Understand before acting
- Track progress with TodoWrite
- Get user approval before major changes

Phase 1: Discovery
Goal: [Understand what needs to be built]

Actions:
- Create todo list with all phases using TodoWrite
- Parse $ARGUMENTS for initial context
- If unclear, use AskUserQuestion to gather:
  - What problem are they solving?
  - What should the outcome be?
  - Any constraints or requirements?
- Summarize understanding and confirm with user

Phase 2: Exploration
Goal: [Understand relevant existing code and patterns]

Actions:
- Launch 2-3 explorer agents in parallel to understand different aspects:
  - Agent 1: Find similar features and trace their implementation
  - Agent 2: Map the architecture and key abstractions
  - Agent 3: Analyze current state of related areas
- Each agent should return list of 5-10 key files to read
- Wait for all agents to complete
- Read all files identified by agents to build deep understanding
- Present comprehensive summary of findings
- Update todos as each exploration completes

Phase 3: Clarifying Questions
Goal: [Fill in gaps and resolve ambiguities]

CRITICAL: Do not skip this phase

Actions:
- Review findings and original request
- Identify underspecified aspects:
  - Edge cases
  - Error handling
  - Integration points
  - Design preferences
- Present all questions to user in organized list
- Wait for answers before proceeding
- Update todos

Phase 4: Design
Goal: [Plan the implementation approach]

Actions:
- Based on exploration and answers, design approach
- For complex tasks, consider launching architect agents with different focuses
- Present design to user with:
  - What will be changed
  - Why this approach
  - Any trade-offs
- Get user approval before implementing
- Update todos

Phase 5: Implementation
Goal: [Build the solution]

DO NOT START WITHOUT USER APPROVAL

Actions:
- Read all relevant files identified
- Implement following planned approach
- Follow codebase conventions
- Write clean, documented code
- Update todos as each piece completes

Phase 6: Verification
Goal: [Ensure quality and correctness]

Actions:
- Run tests if applicable
- Run type checking if applicable
- Example: !{bash npm run test && npm run typecheck}
- Verify functionality works as expected
- Update todos

Phase 7: Summary
Goal: [Document what was accomplished]

Actions:
- Mark all todos complete
- Summarize:
  - What was built
  - Key decisions made
  - Files modified
  - Suggested next steps

---

Pattern 4: Parallel Multi-Agent Template

---
description: [What this command does - typically comprehensive analysis or audit]
argument-hint: [argument-placeholder]
allowed-tools: Task, Read, Write, Bash(*), Glob, Grep, TodoWrite
---

**Arguments**: $ARGUMENTS

Goal: [What this command accomplishes - typically running independent checks]

Core Principles:
- Launch independent tasks in parallel for speed
- Consolidate results at the end
- Track progress with TodoWrite
- Provide comprehensive summary

Phase 1: Discovery
Goal: [Understand the target and scope]

Actions:
- Create todo list using TodoWrite
- Parse $ARGUMENTS for target (file, directory, etc.)
- Validate target exists
- Example: !{bash test -e "$ARGUMENTS" && echo "Found" || echo "Not found"}
- Load context about target
- Update todos

Phase 2: Parallel Execution
Goal: [Run multiple independent agents simultaneously]

Actions:

Run the following agents IN PARALLEL (all at once):

Task(description="[First Check Name]", subagent_type="[agent-type-1]", prompt="You are the [agent-type-1] agent. [Accomplish first task] for $ARGUMENTS. Focus on: [Focus area 1], [Focus area 2]. Deliverable: [Expected output]")

Task(description="[Second Check Name]", subagent_type="[agent-type-2]", prompt="You are the [agent-type-2] agent. [Accomplish second task] for $ARGUMENTS. Focus on: [Focus area 1], [Focus area 2]. Deliverable: [Expected output]")

Task(description="[Third Check Name]", subagent_type="[agent-type-3]", prompt="You are the [agent-type-3] agent. [Accomplish third task] for $ARGUMENTS. Focus on: [Focus area 1], [Focus area 2]. Deliverable: [Expected output]")

Wait for ALL agents to complete before proceeding.

Update todos as each agent completes.

Phase 3: Consolidation
Goal: [Combine and analyze results from all agents]

Actions:
- Review all agent outputs
- Identify common themes or critical issues
- Prioritize findings by severity/importance
- Cross-reference findings for validation
- Update todos

Phase 4: Summary
Goal: [Present comprehensive results]

Actions:
- Mark all todos complete
- Present consolidated report:
  - Results from each agent
  - Critical issues (high priority)
  - Warnings and recommendations
  - Suggested next steps
- Organize by priority or category

---

Key Patterns and Syntax

Arguments

Always use $ARGUMENTS never $1, $2, etc.

If user provided --fix flag:
  Parse from $ARGUMENTS

File Loading

Use @ prefix to load files:

@package.json
@src/config.ts

Bash Execution

Use !{bash command} for inline execution:

!{bash npm run build}
!{bash ls -la | grep package}

Script Execution

Reference shared scripts using ABSOLUTE paths:

!{bash ~/.claude/plugins/marketplaces/domain-plugin-builder/plugins/domain-plugin-builder/skills/build-assistant/scripts/validate-plugin.sh}

Agent Invocation

Use Task() tool calls with proper parameters:

Single agent:

Task(description="Validate setup", subagent_type="verifier-agent", prompt="You are the verifier agent. Validate the setup for $ARGUMENTS. Focus on: configuration files, dependencies, environment variables. Return validation report with pass/fail status.")

Parallel agents (run all at once in SAME message):

Task(description="Security check", subagent_type="security-checker", prompt="Audit security for $ARGUMENTS")
Task(description="Code scan", subagent_type="code-scanner", prompt="Scan code quality for $ARGUMENTS")
Task(description="Performance analysis", subagent_type="performance-analyzer", prompt="Analyze performance for $ARGUMENTS")

Wait for ALL agents to complete before proceeding.

Claude Code will convert this natural language to actual Task() tool calls during execution.

Examples:

• Single agent: "Invoke the refactorer agent to improve code quality"
• Sequential: "First launch the detector agent, then based on findings, invoke the fixer agent"
• Parallel: "Launch 3 reviewer agents in parallel focusing on: security, performance, and maintainability"

TodoWrite Integration

Track progress throughout:

Phase 1: Create initial todo list
Phase N: Update todos as work progresses
Phase Final: Mark all todos complete

---

Best Practices

1. Ask Before Acting: Use AskUserQuestion for clarification
2. Detect Don't Assume: Check what exists rather than assuming structure
3. Progressive Disclosure: Load context as needed, not all upfront
4. Clear Communication: Explain what's happening at each phase
5. Error Handling: Check for issues and provide helpful messages
6. User Approval: Get confirmation before major changes
7. Track Progress: Use TodoWrite for complex workflows
8. Validation: Verify results before completing

---

When to Use Each Pattern

Use Pattern 1 (Simple) when:

• No AI decision-making needed
• Clear, deterministic steps
• Configuration updates, version bumps
• Running predefined scripts

Use Pattern 2 (Single Agent) when:

• One specialized capability needed
• Analysis, generation, or transformation task
• Agent can handle the full scope
• Example: code refactoring, project setup

Use Pattern 3 (Sequential) when:

• Multiple phases with dependencies
• User input needed at checkpoints
• Complex workflows: understand → design → implement → verify
• Example: feature development, major refactoring

Use Pattern 4 (Parallel) when:

• Multiple independent checks or analyses
• Tasks have no dependencies
• Speed matters (parallel execution faster)
• Example: comprehensive audits, multi-aspect validation