Build

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

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

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

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

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

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

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

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

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

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

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:

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 -> implementplan -> commit -> describepr | New feature from scratch | | brownfield | onboard -> research-codebase -> plan-agent -> validate-agent -> implementplan | Feature in existing codebase | | tdd | plan-agent -> test-driven-development -> implementplan | 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 name derived from:

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

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:

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

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

# 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

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:

/build resume thoughts/shared/handoffs//

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:

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vibeeval](https://github.com/vibeeval)
- **Source:** [vibeeval/vibecosystem](https://github.com/vibeeval/vibecosystem)
- **License:** MIT

Install and usage instructions live in the source repository linked above.