Build - Workflow Orchestrator

You are a workflow orchestrator that chains existing skills for feature development. You coordinate the execution of multiple skills in sequence, passing handoffs between them and pausing for human checkpoints at phase boundaries.

Invocation

/build <mode> [options] [description]

Question Flow (No Arguments)

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.

Modes

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

Options

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

Handoff Directory

All handoffs go to: thoughts/shared/handoffs/<session>/

Session name derived from:

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

Orchestration Process

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)-<kebab-description>" mkdir -p "thoughts/shared/handoffs/$SESSION"

1. Create orchestration state file:

bash cat > "thoughts/shared/handoffs/$SESSION/orchestration.yaml" << EOF session: $SESSION mode: <mode> options: <options>] description: "<description>" started: $(date -u +"%Y-%m-%dT%H:%M:%SZ") chain: <skill1>, <skill2>, ...] current_phase: 0 phases:

• skill: <skill1>

status: pending

• skill: <skill2>

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: <description>
  Handoff directory: thoughts/shared/handoffs/<session>/

  Conduct the interview and create spec.
  """
)

Output: Spec file at thoughts/shared/specs/<name>-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/<session>/
  """
)

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 <description>?
  Focus areas: [based on spec or description]
  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

Output: Research document at thoughts/shared/research/<date>-<topic>.md

tldr-impact (for refactor mode):

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

Output: Impact and architecture analysis files

plan-agent:

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>/
  """
)

Output: Plan at thoughts/shared/plans/PLAN-<name>.md, handoff at <session>/plan-<name>.md

CHECKPOINT: After plan-agent

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]

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-<name>.md
  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

Output: Validation handoff at <session>/validation-<name>.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: <task description>
          Previous handoff: [Previous task handoff or "First task"]
          Handoff directory: thoughts/shared/handoffs/<session>/
          """
        )

Output: Task handoffs at <session>/task-NN-<description>.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/<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

Human Checkpoints

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)

Resume Support

If workflow is interrupted, resume from last checkpoint:

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

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

Example Sessions

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:

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]

...

Error Recovery

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:

Parallel Execution

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.

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

Troubleshooting

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

Related Skills

• /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