build

```

/build [options] [description]

```

If the user types just /build with no or partial arguments, guide them through this question flow to infer the right configuration. Use AskUserQuestion for each phase.

Phase 0: Workflow Selection

```yaml

question: "What would you like to do?"

header: "Workflow"

options:

- label: "Help me choose (Recommended)"

description: "I'll ask a few questions to pick the right workflow"

- label: "Greenfield - new feature"

description: "Chain: discovery → plan → validate → implement → commit → PR"

- label: "Brownfield - existing code"

description: "Chain: onboard → research → plan → validate → implement"

- label: "TDD - test-first"

description: "Chain: plan → test-driven-development → implement"

- label: "Refactor - improve structure"

description: "Chain: impact analysis → plan → TDD → implement"

```

Mapping:

• "Help me choose" → Continue to Phase 1-4 questions
• "Greenfield" → Set mode=greenfield, skip to Phase 5 (description)
• "Brownfield" → Set mode=brownfield, skip to Phase 5 (description)
• "TDD" → Set mode=tdd, skip to Phase 5 (description)
• "Refactor" → Set mode=refactor, skip to Phase 5 (description)

If Answer is Unclear (via "Other"):

```yaml

question: "I want to understand your workflow needs. Did you mean..."

header: "Clarify"

options:

- label: "Help me choose"

description: "Not sure which workflow - guide me through questions"

- label: "Greenfield - new feature"

description: "Building something new with no existing code"

- label: "Brownfield - existing code"

description: "Adding to or modifying existing codebase"

- label: "Neither - let me explain differently"

description: "I'll describe what I'm trying to do"

```

Phase 1: Project Context

```yaml

question: "Is this a new feature or work in existing code?"

header: "Context"

options:

- label: "New feature from scratch"

description: "No existing code to integrate with"

- label: "Adding to existing codebase"

description: "Need to understand current code first"

- label: "Refactoring existing code"

description: "Improving without changing behavior"

```

Mapping:

• "New feature from scratch" → greenfield mode
• "Adding to existing codebase" → brownfield mode
• "Refactoring existing code" → refactor mode

If Answer is Unclear (via "Other"):

```yaml

question: "I want to make sure I understand. Did you mean..."

header: "Clarify"

options:

- label: "New feature from scratch"

description: "Building something new with no existing code"

- label: "Adding to existing codebase"

description: "Integrating with code that already exists"

- label: "Refactoring existing code"

description: "Improving structure without changing behavior"

- label: "Neither - let me explain differently"

description: "I'll provide more details"

```

Phase 2: Requirements Clarity

```yaml

question: "How clear are your requirements?"

header: "Requirements"

options:

- label: "I have a clear spec/description"

description: "Know exactly what to build"

- label: "I have a rough idea"

description: "Need help fleshing out details"

- label: "Just exploring possibilities"

description: "Want to discover what's possible"

```

Mapping:

• "Clear spec" → --skip-discovery
• "Rough idea" → run discovery-interview first
• "Exploring" → run discovery-interview with broader scope

If Answer is Unclear (via "Other"):

```yaml

question: "I want to make sure I understand your requirements state. Did you mean..."

header: "Clarify"

options:

- label: "I have a clear spec/description"

description: "Ready to implement - no discovery needed"

- label: "I have a rough idea"

description: "Need some help defining the details"

- label: "Just exploring possibilities"

description: "Don't know exactly what's possible yet"

- label: "Neither - let me explain differently"

description: "I'll describe my situation better"

```

Phase 3: Development Approach

```yaml

question: "How should I approach development?"

header: "Approach"

options:

- label: "Just implement it"

description: "Standard implementation flow"

- label: "Write tests first (TDD)"

description: "Test-driven development"

- label: "Validate plan before coding"

description: "Get plan reviewed before implementation"

```

Mapping:

• "Just implement" → standard chain
• "Tests first" → tdd mode (overrides previous if not refactor)
• "Validate plan" → keep validate-agent in chain

If Answer is Unclear (via "Other"):

```yaml

question: "I want to make sure I understand your preferred approach. Did you mean..."

header: "Clarify"

options:

- label: "Just implement it"

description: "Standard development - implement then test"

- label: "Write tests first (TDD)"

description: "Test-driven - tests before implementation"

- label: "Validate plan before coding"

description: "Review plan with validate-agent first"

- label: "Neither - let me explain differently"

description: "I have a different workflow in mind"

```

Phase 4: Post-Implementation

```yaml

question: "What should happen after implementation?"

header: "Finish"

multiSelect: true

options:

- label: "Auto-commit changes"

description: "Create git commit when done"

- label: "Create PR description"

description: "Generate PR summary"

- label: "Just leave files changed"

description: "I'll handle git myself"

```

Mapping:

• No "Auto-commit" selected → --skip-commit
• No "Create PR" selected → --skip-pr

If Answer is Unclear (via "Other"):

```yaml

question: "I want to understand what you need after implementation. Which apply?"

header: "Clarify"

multiSelect: true

options:

- label: "Auto-commit changes"

description: "I'll create a git commit with your changes"

- label: "Create PR description"

description: "I'll generate a PR summary for you"

- label: "Just leave files changed"

description: "No git operations - you'll handle it"

- label: "Neither - let me explain differently"

description: "I have different post-implementation needs"

```

Phase 5: Description

Finally, ask for the feature description:

```yaml

question: "Describe what you want to build (1-2 sentences):"

header: "Feature"

options: [] # Free text input via "Other"

```

Summary Before Execution

Before starting, show what will run:

```

Based on your answers, I'll run:

Mode: brownfield

Chain: onboard → research-codebase → plan-agent → implement_plan

Options: --skip-commit

Description: "Add user authentication with OAuth"

Proceed? [Yes / Adjust settings]

```

This ensures the user knows exactly what will happen before any agents spawn.

| Mode | Chain | Use Case |

|------|-------|----------|

| greenfield | discovery-interview -> plan-agent -> validate-agent -> implement_plan -> commit -> describe_pr | New feature from scratch |

| brownfield | onboard -> research-codebase -> plan-agent -> validate-agent -> implement_plan | Feature in existing codebase |

| tdd | plan-agent -> test-driven-development -> implement_plan | Test-first implementation |

| refactor | tldr-code (impact) -> plan-agent -> test-driven-development -> implement_plan | Safe refactoring with impact analysis |

| Option | Effect |

|--------|--------|

| --skip-discovery | Skip interview phase (use existing spec or description) |

| --skip-validate | Skip validation phase (trust plan as-is) |

| --skip-commit | Don't auto-commit after implementation |

| --skip-pr | Don't create PR description |

| --parallel | Run independent research agents in parallel |

All handoffs go to: thoughts/shared/handoffs//

Session name derived from:

1. Existing continuity ledger name, OR
2. Generated from feature description: build--

Step 0: Parse Arguments

Parse the mode and options from user input:

```

/build greenfield --skip-validate Add user authentication

^mode ^options ^description

```

Build the skill chain based on mode:

```python

CHAINS = {

"greenfield": ["discovery-interview", "plan-agent", "validate-agent", "implement_plan", "commit", "describe_pr"],

"brownfield": ["onboard", "research-codebase", "plan-agent", "validate-agent", "implement_plan"],

"tdd": ["plan-agent", "test-driven-development", "implement_plan"],

"refactor": ["tldr-impact", "plan-agent", "test-driven-development", "implement_plan"]

}

```

Apply options to modify chain:

• --skip-discovery: Remove "discovery-interview" from chain
• --skip-validate: Remove "validate-agent" from chain
• --skip-commit: Remove "commit" from chain
• --skip-pr: Remove "describe_pr" from chain

Step 1: Setup

1. Create handoff directory:

```bash

SESSION="build-$(date +%Y%m%d)-"

mkdir -p "thoughts/shared/handoffs/$SESSION"

```

1. Create orchestration state file:

```bash

cat > "thoughts/shared/handoffs/$SESSION/orchestration.yaml" << EOF

session: $SESSION

mode:

options: []

description: ""

started: $(date -u +"%Y-%m-%dT%H:%M:%SZ")

chain: [, , ...]

current_phase: 0

phases:

- skill:

status: pending

- skill:

status: pending

...

EOF

```

Step 2: Execute Chain

For each skill in the chain:

#### Phase Execution Pattern

```

1. Read previous handoff (if exists)
2. Execute skill (spawn agent or invoke directly)
3. Capture skill output/handoff
4. Update orchestration state
5. Human checkpoint (if phase boundary)
6. Continue or handle error

```

#### Skill Execution Details

discovery-interview:

```

Task(

subagent_type="discovery-interview",

prompt="""

[Contents of discovery-interview SKILL.md]

---

## Context

Feature request:

Handoff directory: thoughts/shared/handoffs//

Conduct the interview and create spec.

"""

)

```

Output: Spec file at thoughts/shared/specs/-spec.md

onboard:

```

Task(

subagent_type="onboard",

prompt="""

[Contents of onboard SKILL.md]

---

Analyze this codebase and create continuity ledger.

Handoff directory: thoughts/shared/handoffs//

"""

)

```

Output: TLDR caches, continuity ledger

research-codebase:

```

Task(

subagent_type="research-codebase",

prompt="""

[Contents of research-codebase SKILL.md]

---

Research question: How should we implement ?

Focus areas: [based on spec or description]

Handoff directory: thoughts/shared/handoffs//

"""

)

```

Output: Research document at thoughts/shared/research/-.md

tldr-impact (for refactor mode):

```bash

# Run impact analysis on the function/module being refactored

tldr impact src/ --depth 3 > thoughts/shared/handoffs//impact-analysis.json

# Also run architecture analysis

tldr arch src/ > thoughts/shared/handoffs//architecture.json

```

Output: Impact and architecture analysis files

plan-agent:

```

Task(

subagent_type="plan-agent",

prompt="""

[Contents of plan-agent SKILL.md]

---

## Context

Feature request:

[Include spec if exists from discovery-interview]

[Include research findings if exists]

[Include impact analysis if refactor mode]

Handoff directory: thoughts/shared/handoffs//

"""

)

```

Output: Plan at thoughts/shared/plans/PLAN-.md, handoff at /plan-.md

CHECKPOINT: After plan-agent

```

Plan created: thoughts/shared/plans/PLAN-.md

Please review the plan. Options:

1. Approve and continue to [next phase]
2. Request changes to plan
3. Abort workflow

[Show plan summary]

```

validate-agent:

```

Task(

subagent_type="validate-agent",

prompt="""

[Contents of validate-agent SKILL.md]

---

Plan to validate: [Plan content]

Plan path: thoughts/shared/plans/PLAN-.md

Handoff directory: thoughts/shared/handoffs//

"""

)

```

Output: Validation handoff at /validation-.md

CHECKPOINT: After validate-agent (if issues found)

```

Validation complete with issues:

• [Issue 1]
• [Issue 2]

Options:

1. Proceed anyway (acknowledge risks)
2. Update plan and re-validate
3. Abort workflow

```

test-driven-development (for tdd/refactor modes):

```

Present TDD guidance to user:

"Entering TDD mode. For each feature:

1. Write failing test first
2. Implement minimal code to pass
3. Refactor while keeping tests green

I'll guide you through each cycle. Starting with first test..."

```

This is interactive - guide user through TDD cycles.

implement_plan:

```

# Check plan size

if task_count <= 3:

# Direct implementation

Follow implement_plan skill directly

else:

# Agent orchestration mode

For each task:

Task(

subagent_type="implement_task",

prompt="""

[Contents of implement_task SKILL.md]

---

Plan: [Plan content]

Your task: Task N of M:

Previous handoff: [Previous task handoff or "First task"]

Handoff directory: thoughts/shared/handoffs//

"""

)

```

Output: Task handoffs at /task-NN-.md

CHECKPOINT: After each implementation phase

```

Phase [N] Complete

Automated verification:

• [x] Tests passing
• [x] Type check passed
• [ ] Manual testing required

Please verify:

• [Manual test items from plan]

Continue to next phase? [Y/n]

```

commit:

```

Follow commit skill:

1. Show git status and diff
2. Present commit plan
3. Execute on user approval
4. Generate reasoning file

```

describe_pr:

```

Follow describe_pr skill:

1. Create PR if not exists
2. Generate description from changes
3. Update PR with description

```

Step 3: Handle Errors

If any phase fails or returns blocked status:

```yaml

# Update orchestration.yaml

phases:

- skill: plan-agent

status: complete

- skill: validate-agent

status: blocked

error: "Validation found deprecated library"

blocker: "Need to replace X with Y"

```

Present to user:

```

Workflow blocked at: validate-agent

Issue: Validation found deprecated library

Blocker: Need to replace X with Y

Options:

1. Retry this phase
2. Skip this phase (not recommended)
3. Abort workflow
4. Manual intervention (I'll help you fix it)

```

Step 4: Completion

When all phases complete:

```

Build workflow complete!

Session: thoughts/shared/handoffs//

Artifacts created:

• Spec: thoughts/shared/specs/-spec.md (if greenfield)
• Plan: thoughts/shared/plans/PLAN-.md
• Validation: /validation-.md
• Implementation handoffs: /task-*.md
• PR: # (if --skip-pr not set)

Commit: (if --skip-commit not set)

Total phases: N completed, M skipped

```

Checkpoints pause for human verification at critical decision points:

| After Phase | Checkpoint Purpose |

|-------------|-------------------|

| discovery-interview | Verify spec captures requirements |

| plan-agent | Approve implementation plan |

| validate-agent (if issues) | Acknowledge validation concerns |

| Each implement task | Verify phase works before continuing |

| commit | Approve commit message and files |

To skip checkpoints: Run with --no-checkpoint (advanced users only)

If workflow is interrupted, resume from last checkpoint:

```bash

/build resume thoughts/shared/handoffs//

```

This reads orchestration.yaml and continues from the last incomplete phase.

Greenfield Feature

```

User: /build greenfield Add user authentication with OAuth

Claude: Starting greenfield workflow for "Add user authentication with OAuth"

Creating session: build-20260108-user-auth-oauth

Chain: discovery-interview -> plan-agent -> validate-agent -> implement_plan -> commit -> describe_pr

Phase 1/6: Discovery Interview

[Spawns discovery-interview agent]

Interview questions:

1. What OAuth providers do you need? (Google, GitHub, etc.)
2. What user data should we store after auth?
3. Should sessions persist across browser closes?

...

[After interview completes]

Spec created: thoughts/shared/specs/2026-01-08-user-auth-spec.md

Phase 2/6: Planning

[Spawns plan-agent]

Plan created: thoughts/shared/plans/PLAN-user-auth.md

--- CHECKPOINT ---

Plan Summary:

• Task 1: Set up OAuth provider configuration
• Task 2: Create user model and session storage
• Task 3: Implement OAuth callback endpoints
• Task 4: Add auth middleware
• Task 5: Create login/logout routes

Approve plan and continue? [Y/n]

User: Y

Phase 3/6: Validation

[Spawns validate-agent]

Validation: PASSED

All tech choices are current best practices.

Phase 4/6: Implementation (5 tasks)

[Spawns implementation agents for each task]

Task 1/5: OAuth configuration... Complete

Task 2/5: User model... Complete

Task 3/5: OAuth callbacks... Complete

Task 4/5: Auth middleware... Complete

Task 5/5: Login/logout routes... Complete

--- CHECKPOINT ---

All implementation complete.

Tests: 24 passing

Manual verification needed:

• [ ] Test OAuth flow end-to-end
• [ ] Verify session persistence

Continue to commit? [Y/n]

User: Y

Phase 5/6: Commit

[Shows changes, creates commit]

Phase 6/6: PR Description

[Creates/updates PR]

Build complete!

PR #42: https://github.com/user/repo/pull/42

```

TDD Mode

```

User: /build tdd Add rate limiting to API endpoints

Claude: Starting TDD workflow for "Add rate limiting to API endpoints"

Phase 1/3: Planning

[Creates plan with test specifications]

--- CHECKPOINT ---

Plan approved? [Y/n]

User: Y

Phase 2/3: TDD Implementation

Let's start with the first test. According to the plan, we need to test:

"Rate limiter returns 429 after 100 requests per minute"

RED - Write failing test:

```python

def test_rate_limiter_returns_429_after_limit():

limiter = RateLimiter(limit=100, window=60)

for _ in range(100):

assert limiter.check("user1") == True

assert limiter.check("user1") == False

```

Running test... FAILED (as expected - RateLimiter doesn't exist)

GREEN - Implement minimal code:

[Guides through implementation]

Running test... PASSED

REFACTOR - Any cleanup needed?

Next test: "Rate limiter resets after window expires"

...

Phase 3/3: Implementation

[Integrates rate limiter into endpoints]

Build complete!

```

Refactor Mode

```

User: /build refactor Extract auth logic into separate module

Claude: Starting refactor workflow for "Extract auth logic into separate module"

Phase 1/4: Impact Analysis

Running: tldr impact auth src/ --depth 3

Impact analysis complete:

• 12 files directly call auth functions
• 3 entry points affected
• No circular dependencies detected

Architecture analysis:

• auth is currently in: src/api/middleware/
• Callers in: src/api/routes/, src/api/handlers/

--- CHECKPOINT ---

Review impact before planning? [Y/n]

User: Y

[Shows detailed impact report]

Phase 2/4: Planning

[Creates refactor plan based on impact analysis]

...

```

If a phase fails:

```

Phase 3 (validate-agent) failed:

Error: WebSearch unavailable

Options:

1. Retry phase (recommended)
2. Skip validation (--skip-validate)
3. Abort workflow

Choice:

```

If implementation is blocked:

```

Task 3/5 blocked:

Blocker: Database schema doesn't match expected structure

Found: users.email (VARCHAR)

Expected: users.email (UNIQUE VARCHAR)

Options:

1. Create migration to fix schema
2. Adjust plan to work with current schema
3. Abort and investigate

Choice:

```

With --parallel option, independent phases run concurrently:

```

/build brownfield --parallel Add dashboard feature

Phase 1: Onboard (started)

Phase 2: Research-codebase (started in parallel)

[Both complete]

Phase 3: Plan-agent (uses results from both)

...

```

Only truly independent phases run in parallel. Dependencies are respected.

Default mode preferences

Set in .claude/settings.json:

```json

{

"skills": {

"build": {

"default_mode": "brownfield",

"always_validate": true,

"auto_commit": false,

"checkpoint_phases": ["plan-agent", "implement_plan"]

}

}

}

```

| Issue | Solution |

|-------|----------|

| "No continuity ledger found" | Run /onboard first or use greenfield mode |

| "Plan validation failed" | Review validation output, update plan |

| "Implementation blocked" | Check blocker in handoff, resolve dependency |

| "Workflow stuck" | Check orchestration.yaml for state, resume or restart |

• /discovery-interview - Deep interview for requirements
• /plan-agent - Create implementation plans
• /validate-agent - Validate tech choices
• /implement_plan - Execute implementation plans
• /implement_task - Single task implementation
• /test-driven-development - TDD workflow
• /commit - Create commits
• /describe_pr - Generate PR descriptions
• /onboard - Codebase analysis
• /research-codebase - Research existing code
• /tldr-code - Code analysis CLI