/build <mode> [options] [description]

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"

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"

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"

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"

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"

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"

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"

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"

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"

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"

question: "Describe what you want to build (1-2 sentences):"
header: "Feature"
options: []  # Free text input via "Other"

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]

/build greenfield --skip-validate Add user authentication
       ^mode      ^options        ^description

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"]
}

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

Task(
  subagent_type="discovery-interview",
  prompt="""
  [Contents of discovery-interview SKILL.md]

  ---

  ## Context
  Feature request: <description>
  Handoff directory: thoughts/shared/handoffs/<session>/

  Conduct the interview and create spec.
  """
)

Task(
  subagent_type="onboard",
  prompt="""
  [Contents of onboard SKILL.md]

  ---

  Analyze this codebase and create continuity ledger.
  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

Task(
  subagent_type="research-codebase",
  prompt="""
  [Contents of research-codebase SKILL.md]

  ---

  Research question: How should we implement <description>?
  Focus areas: [based on spec or description]
  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

# Run impact analysis on the function/module being refactored
tldr impact <target> src/ --depth 3 > thoughts/shared/handoffs/<session>/impact-analysis.json

# Also run architecture analysis
tldr arch src/ > thoughts/shared/handoffs/<session>/architecture.json

Task(
  subagent_type="plan-agent",
  prompt="""
  [Contents of plan-agent SKILL.md]

  ---

  ## Context
  Feature request: <description>

  [Include spec if exists from discovery-interview]
  [Include research findings if exists]
  [Include impact analysis if refactor mode]

  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

Plan created: thoughts/shared/plans/PLAN-<name>.md

Please review the plan. Options:
1. Approve and continue to [next phase]
2. Request changes to plan
3. Abort workflow

[Show plan summary]

Task(
  subagent_type="validate-agent",
  prompt="""
  [Contents of validate-agent SKILL.md]

  ---

  Plan to validate: [Plan content]
  Plan path: thoughts/shared/plans/PLAN-<name>.md
  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

Validation complete with issues:
- [Issue 1]
- [Issue 2]

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

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..."

# 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: <task description>
          Previous handoff: [Previous task handoff or "First task"]
          Handoff directory: thoughts/shared/handoffs/<session>/
          """
        )

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]

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

Follow describe_pr skill:
1. Create PR if not exists
2. Generate description from changes
3. Update PR with description

# 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"

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)

Build workflow complete!

Session: thoughts/shared/handoffs/<session>/

Artifacts created:
- Spec: thoughts/shared/specs/<name>-spec.md (if greenfield)
- Plan: thoughts/shared/plans/PLAN-<name>.md
- Validation: <session>/validation-<name>.md
- Implementation handoffs: <session>/task-*.md
- PR: #<number> (if --skip-pr not set)

Commit: <hash> (if --skip-commit not set)

Total phases: N completed, M skipped

/build resume thoughts/shared/handoffs/<session>/

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

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

### Refactor Mode

## Error Recovery

### If a phase fails:

### If implementation is blocked:

## Parallel Execution

With `--parallel` option, independent phases run concurrently:

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

## Configuration

### 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"]
    }
  }
}