---
name: Scout-Plan-Build
description: |
  Three-step delegated workflow for complex engineering tasks.
  Scout explores, Plan architects, Build executes.

  WHEN TO USE:
  - "Scout this codebase"
  - "Plan before building"
  - "Use scout-plan-build workflow"
  - "Explore then implement"
  - Starting work in unfamiliar codebase
  - Complex feature implementation
  - Need structured approach to large tasks

  CAPABILITIES:
  - Codebase exploration (Scout)
  - Implementation planning (Plan)
  - Structured execution (Build)
  - Delegated sub-agent workflow

allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
  - Write
  - Edit
---

# Scout-Plan-Build

## Purpose

Don't jump into coding. Scout the territory first, plan the attack, then build with confidence. This three-step workflow prevents wasted effort and ensures alignment.

## The Three Phases

```
┌─────────┐     ┌─────────┐     ┌─────────┐
│  SCOUT  │ ──→ │  PLAN   │ ──→ │  BUILD  │
│ Explore │     │ Design  │     │ Execute │
└─────────┘     └─────────┘     └─────────┘
```

## Phase 1: Scout

**Objective**: Understand the territory before acting.

### What Scout Does
- Explores codebase structure
- Finds relevant files
- Identifies patterns and conventions
- Maps dependencies
- Discovers existing implementations

### Scout Commands
```bash
# Find files matching pattern
/scout "authentication implementation"

# Explore specific area
/scout "how does the API handle errors"

# Map dependencies
/scout "what uses the UserService class"
```

### Scout Output
```markdown
## Scout Report: Authentication

### Files Found
- src/auth/login.ts (main login handler)
- src/auth/session.ts (session management)
- src/middleware/auth.ts (auth middleware)

### Patterns Observed
- JWT tokens for session
- Redis for token storage
- Middleware pattern for route protection

### Dependencies
- jsonwebtoken package
- redis client
- express-session

### Relevant Tests
- tests/auth.test.ts
```

## Phase 2: Plan

**Objective**: Design implementation before coding.

### What Plan Does
- Creates detailed implementation spec
- Identifies files to modify
- Defines success criteria
- Anticipates edge cases
- Sets verification commands

### Plan Structure
```markdown
## Implementation Plan: [Feature Name]

### Objective
[What we're building and why]

### Files to Modify
1. path/to/file1.ts - [What changes]
2. path/to/file2.ts - [What changes]

### New Files
1. path/to/new.ts - [Purpose]

### Implementation Steps
1. [Step 1 with details]
2. [Step 2 with details]
3. [Step 3 with details]

### Success Criteria
- [ ] Tests pass
- [ ] No type errors
- [ ] Follows existing patterns

### Verification Command
npm test && npm run lint
```

### Plan-Wait-Review Pattern
```
1. PLAN: Create detailed spec
2. WAIT: Hand off to agent
3. REVIEW: Validate output

During WAIT, start planning NEXT task!
```

## Phase 3: Build

**Objective**: Execute the plan systematically.

### What Build Does
- Follows plan step by step
- Creates/modifies files
- Runs verification after each step
- Reports progress
- Handles errors gracefully

### Build Execution
```bash
# Execute plan
/build specs/feature-plan.md

# Build with specific focus
/build specs/feature-plan.md --focus "Step 2"
```

### Build Best Practices
1. **One step at a time** - Don't batch changes
2. **Verify after each step** - Run tests frequently
3. **Log progress** - Track what's done
4. **Stop on failure** - Don't continue if step fails

## Workflow Integration

### Sequential Workflow
```
Scout → Plan → Build → Review → Done
```

### Parallel Workflow (Git Worktrees)
```
Scout → Plan
         ├→ Worktree 1: Build (version A)
         ├→ Worktree 2: Build (version B)
         └→ Worktree 3: Build (version C)
              ↓
         Pick best → Merge
```

## Custom Slash Commands

```markdown
# .claude/commands/scout.md
Read the codebase around $ARGUMENTS[0].
Find relevant files, patterns, and dependencies.
Output a scout report in markdown format.

# .claude/commands/plan.md
Based on scout report in $ARGUMENTS[0],
create detailed implementation plan.
Include file changes, steps, and verification.

# .claude/commands/build.md
Execute plan from $ARGUMENTS[0].
Follow each step systematically.
Run verification after each major change.
```

## When to Use Each Phase

| Scenario | Scout | Plan | Build |
|----------|-------|------|-------|
| New codebase | Deep | Detailed | Careful |
| Bug fix | Quick | Light | Focused |
| New feature | Moderate | Detailed | Systematic |
| Refactor | Deep | Detailed | Incremental |

## Example: Adding New Endpoint

```
1. Scout: "Find existing API endpoints"
   → Report: Found REST patterns, auth middleware, validation

2. Plan: Create endpoint plan
   → Steps: Create route, add validation, write tests

3. Build: Execute plan
   → Create file, add route, run tests, verify
```

## References

See `references/` for example plans and workflows.
