---
name: patterns
description: Common agent patterns and templates for Claude Code. Use when implementing agents to follow proven patterns for proxy mode, TodoWrite integration, and quality checks.
---

# Agent Patterns

## Proxy Mode Pattern

Enable agents to delegate to external AI models via Claudish.

```xml
<critical_constraints>
  <proxy_mode_support>
    **FIRST STEP: Check for Proxy Mode Directive**

    Before executing, check if the incoming prompt starts with:
    ```
    PROXY_MODE: {model_name}
    ```

    If you see this directive:

    1. **Extract model name** (e.g., "x-ai/grok-code-fast-1")
    2. **Extract actual task** (everything after PROXY_MODE line)
    3. **Construct agent invocation**:
       ```bash
       AGENT_PROMPT="Use the Task tool to launch the '{agent-name}' agent:

{actual_task}"
       ```
    4. **Delegate via Claudish**:
       ```bash
       printf '%s' "$AGENT_PROMPT" | npx claudish --stdin --model {model_name} --quiet --auto-approve
       ```
    5. **Return attributed response**:
       ```markdown
       ## {Task Type} via External AI: {model_name}

       {EXTERNAL_AI_RESPONSE}

       ---
       *Generated by: {model_name} via Claudish*
       ```
    6. **STOP** - Do not execute locally

    **If NO PROXY_MODE directive**: Proceed with normal workflow
  </proxy_mode_support>
</critical_constraints>
```

**Key Elements:**
- Check for directive first
- Use `--auto-approve` flag
- Clear attribution in response
- STOP after proxy (don't continue locally)

---

## TodoWrite Integration Pattern

Every agent must track workflow progress.

```xml
<critical_constraints>
  <todowrite_requirement>
    You MUST use TodoWrite to track your workflow.

    **Before starting**, create todo list:
    1. Phase 1 description
    2. Phase 2 description
    3. Phase 3 description

    **Update continuously**:
    - Mark "in_progress" when starting
    - Mark "completed" immediately after finishing
    - Keep only ONE task "in_progress" at a time
  </todowrite_requirement>
</critical_constraints>

<workflow>
  <phase number="1" name="Phase Name">
    <step>Initialize TodoWrite with all phases</step>
    <step>Mark PHASE 1 as in_progress</step>
    <step>... perform work ...</step>
    <step>Mark PHASE 1 as completed</step>
    <step>Mark PHASE 2 as in_progress</step>
  </phase>
</workflow>
```

---

## Quality Checks Pattern (Implementers)

```xml
<implementation_standards>
  <quality_checks mandatory="true">
    Before presenting code, perform these checks in order:

    <check name="formatting" order="1">
      <tool>Biome.js</tool>
      <command>bun run format</command>
      <requirement>Must pass</requirement>
      <on_failure>Fix and retry</on_failure>
    </check>

    <check name="linting" order="2">
      <tool>Biome.js</tool>
      <command>bun run lint</command>
      <requirement>All errors resolved</requirement>
      <on_failure>Fix errors, retry</on_failure>
    </check>

    <check name="type_checking" order="3">
      <tool>TypeScript</tool>
      <command>bun run typecheck</command>
      <requirement>Zero type errors</requirement>
      <on_failure>Resolve errors, retry</on_failure>
    </check>

    <check name="testing" order="4">
      <tool>Vitest</tool>
      <command>bun test</command>
      <requirement>All tests pass</requirement>
      <on_failure>Fix failing tests</on_failure>
    </check>
  </quality_checks>
</implementation_standards>
```

---

## Review Feedback Pattern (Reviewers)

```xml
<review_criteria>
  <feedback_format>
    ## Review: {name}

    **Status**: PASS | CONDITIONAL | FAIL
    **Reviewer**: {model}

    **Issue Summary**:
    - CRITICAL: {count}
    - HIGH: {count}
    - MEDIUM: {count}
    - LOW: {count}

    ### CRITICAL Issues
    #### Issue 1: {Title}
    - **Category**: YAML | XML | Security | Completeness
    - **Description**: What's wrong
    - **Impact**: Why it matters
    - **Fix**: How to fix it
    - **Location**: Section/line reference

    ### HIGH Priority Issues
    [Same format]

    ### Approval Decision
    **Status**: PASS | CONDITIONAL | FAIL
    **Rationale**: Why this status
  </feedback_format>
</review_criteria>

<approval_criteria>
  <status name="PASS">
    - 0 CRITICAL issues
    - 0-2 HIGH issues
    - All core sections present
  </status>
  <status name="CONDITIONAL">
    - 0 CRITICAL issues
    - 3-5 HIGH issues
    - Core functionality works
  </status>
  <status name="FAIL">
    - 1+ CRITICAL issues
    - OR 6+ HIGH issues
    - Blocks functionality
  </status>
</approval_criteria>
```

---

## Orchestrator Phase Pattern (Commands)

```xml
<phases>
  <phase number="1" name="Descriptive Name">
    <objective>Clear statement of what this phase achieves</objective>

    <steps>
      <step>Mark PHASE 1 as in_progress in TodoWrite</step>
      <step>Detailed action step</step>
      <step>Detailed action step</step>
      <step>Mark PHASE 1 as completed</step>
    </steps>

    <quality_gate>
      Exit criteria - what must be true to proceed
    </quality_gate>
  </phase>
</phases>

<delegation_rules>
  <rule scope="design">ALL design → architect agent</rule>
  <rule scope="implementation">ALL implementation → developer agent</rule>
  <rule scope="review">ALL reviews → reviewer agent</rule>
</delegation_rules>
```

---

## Agent Templates

### Planner Template
```yaml
---
name: {domain}-architect
description: |
  Plans {domain} features with comprehensive design.
  Examples: (1) "Design X" (2) "Plan Y" (3) "Architect Z"
model: sonnet
color: purple
tools: TodoWrite, Read, Write, Glob, Grep, Bash
---
```

### Implementer Template
```yaml
---
name: {domain}-developer
description: |
  Implements {domain} features with quality checks.
  Examples: (1) "Create X" (2) "Build Y" (3) "Implement Z"
model: sonnet
color: green
tools: TodoWrite, Read, Write, Edit, Bash, Glob, Grep
---
```

### Reviewer Template
```yaml
---
name: {domain}-reviewer
description: |
  Reviews {domain} code for quality and standards.
  Examples: (1) "Review X" (2) "Validate Y" (3) "Check Z"
model: sonnet
color: cyan
tools: TodoWrite, Read, Glob, Grep, Bash
---
```

### Orchestrator Template
```yaml
---
description: |
  Orchestrates {workflow} with multi-agent coordination.
  Workflow: PHASE 1 → PHASE 2 → PHASE 3
allowed-tools: Task, AskUserQuestion, Bash, Read, TodoWrite, Glob, Grep
---
```