build

name	build
description	Use when the user wants to execute an implementation plan and build a companion project. Triggers on requests to build, execute tickets, start implementation, or run the shaping phase. Requires /plan to have been completed first with a tickets.yaml in place.
disable-model-invocation	true
argument-hint	[client/companion]

/build -- Execute Implementation Plan

Orchestrate sub-agents to execute tickets and build the project.

Usage:

• /build -- Use current companion
• /build [client/companion] -- Override for specific companion

---

Phase 1: Validate -- Resolve Companion and Load Ticket Data

Step 1: Determine the Companion

1. If $ARGUMENTS contains a companion path, use that
2. Otherwise, read tracking/current-companion.md for the current companion
3. If no companion is set:

   No companion set. Use /companion to set or create one first.
   

Store the companion path (e.g., acme-corp/api-service) and the full directory path (companions/[client]/[companion]/).

---

Step 2: Load Ticket Data and Validate Schema

Load tickets.yaml:

1. Check for companions/[client]/[companion]/docs/plans/tickets.yaml
2. If not exists, STOP:

   No tickets.yaml found for [companion].
   Run /plan first to create tickets.
   

3. Parse the file and extract:
   • project_path -- absolute path to project directory
   • spec_file -- relative path to implementation spec
   • linear_parent_issue -- parent Linear issue
   • tickets -- list of ticket objects

Validate schema (MANDATORY -- do not skip):

Check that tickets.yaml has the required structure. For each ticket, verify these fields exist:

Field	Check
id	integer (1, 2, 3...)
title	non-empty string
status	one of: pending, in_progress, completed, skipped
blocked_by	list (may be empty)
description	non-empty string
input_files	list (may be empty)
output_files	list with at least one entry
acceptance_criteria	list with at least one entry

Also verify top-level fields exist:

• project_path -- must be an absolute path that exists on disk
• spec_file -- must point to a file that exists

If validation fails, STOP:

## tickets.yaml Schema Validation Failed

Missing or malformed fields:
- [list each problem]

Fix tickets.yaml or re-run /plan to regenerate it.

Do NOT proceed with a malformed tickets.yaml. This is the #1 cause of silent build failures.

Check for prior progress:

Check companions/[client]/[companion]/docs/plans/build-progress.md for prior progress:

• If some tickets show completed, verify those output files still exist on disk
• If output files exist, skip those tickets
• If output files are missing despite "completed" status, reset those tickets to pending
• Resume from first pending ticket
• Report: "Resuming build from ticket #N (tickets 1-M already complete and verified)"

---

Compliance Checkpoint -- Phase 1 Complete:

Phase 1 Complete. Collected values:
- Companion: [client/companion]
- Project path: [project_path value]
- Spec file: [spec_file value]
- Linear parent: [linear_parent_issue value]
- Total tickets: [N]
- Schema validation: PASSED
- Previously completed: [N] (if resuming, else 0)

Proceeding to Phase 2.

---

Phase 2: Dispatch -- Build Execution Order and Execute Tickets

Step 3: Build Execution Order

From the tickets (yaml or Linear):

1. Identify all tickets -- These are the actual work items to execute
2. Parse dependencies -- Check dependencies field (yaml) or blockedBy relationships (Linear)
3. Build execution order using topological sort:
   • Tickets with no dependencies come first
   • Tickets are ordered so dependencies are completed before dependents
   • Identify tickets at the same "depth" that could theoretically run in parallel

Create an ordered list of tickets to execute.

---

Step 4: Present Execution Plan and Confirm

Display the plan for user review:

## Build Plan: [companion]

**Source:** [tickets.yaml | Linear]
**Tickets to execute:** [N]
**Previously completed:** [N] (if resuming)

### Execution Order

| # | Ticket | Dependencies | Status |
|---|--------|--------------|--------|
| 1 | [Title] | None | pending |
| 2 | [Title] | After #1 | pending |
| 3 | [Title] | After #1 | pending |
| 4 | [Title] | After #2, #3 | pending |
...

**Estimated context sessions:** [N] (one per ticket)

---

Proceed with build? (yes/no)

Wait for explicit user confirmation before proceeding.

If user says no, ask what they'd like to adjust.

After user confirms, set parent ticket to In Progress:

If linear_parent_issue exists in tickets.yaml, update it to "In Progress":

1. Get the "In Progress" state ID from workflow states (using mcp__linear__linear_getWorkflowStates)
2. Update the parent issue: mcp__linear__linear_updateIssue with id: [linear_parent_issue] and stateId: [in_progress_state_id]

Build started -- [linear_parent_issue] -> In Progress

---

Compliance Checkpoint -- Execution Plan Confirmed:

Execution plan confirmed by user. Values:
- Tickets in order: [list ticket IDs in execution order]
- Parallel opportunities: [list any parallel groups]
- Linear parent status: In Progress

Proceeding to ticket execution.

---

Step 5: Execute Tickets Sequentially

For each ticket in the execution order:

5a. Announce the Ticket

---
## Executing Ticket [#]/[total]: [Title]
---

5b. Read Full Ticket Details

From tickets.yaml:

• Title, description, acceptance criteria
• Input files and output files
• Any additional context

From Linear (fallback): Use mcp__linear__linear_getIssueById with the ticket ID to get:

• Full title
• Complete description
• Acceptance criteria
• Any comments with additional context

5b-ii. Update Linear Status to In Progress

If the ticket has a linear_id, update its status to "In Progress":

1. Get the team's workflow states using mcp__linear__linear_getWorkflowStates (team ID from prior lookup)
2. Find the state ID for "In Progress"
3. Update the issue: mcp__linear__linear_updateIssue with id: [linear_id] and stateId: [in_progress_state_id]

Ticket [#]: [Title] -- Linear status -> In Progress

5c. Invoke Ticket Executor Agent

This step uses the Task tool to spawn a real subagent. Do NOT simulate or reason about what the agent would do.

Step 5c-i: Read the agent definition

Read .claude/agents/ticket-executor.md. Extract from frontmatter:

• model: -- the model to use (e.g., opus)
• tools: -- available tools (for reference)
• skills: -- reference skills preloaded into the agent (e.g., companion-standards)

The executor agent has skills: [companion-standards] in its frontmatter. This means companion-standards is preloaded into the agent automatically. Do NOT include instructions telling the agent to "read" or "load" the companion-standards skill -- it is already injected.

Step 5c-ii: Build the complete prompt

Construct the full prompt with ALL actual values filled in. No placeholders.

You are the ticket-executor agent. Your job is to implement a single ticket.

## Project Context

**Project Directory:** [ACTUAL absolute path from project_path]
**Implementation Spec:** [ACTUAL absolute path: project_path + "/" + spec_file]

## Ticket: [ACTUAL title from tickets.yaml]

**Description:**
[ACTUAL description from tickets.yaml -- full text, not a reference]

## Instructions

[ACTUAL description from tickets.yaml -- includes all implementation details]

## Acceptance Criteria

[ACTUAL acceptance_criteria list from tickets.yaml, numbered]
1. [criterion 1]
2. [criterion 2]
...

## Input Files (read these for context)

[ACTUAL input_files from tickets.yaml, as absolute paths: project_path + "/" + each path]
- [absolute path 1]
- [absolute path 2]
...

## Output Files (create or modify these)

[ACTUAL output_files from tickets.yaml, as absolute paths: project_path + "/" + each path]
- [absolute path 1]
...

## Instructions

1. Read the implementation spec for architecture context
2. Read all input files
3. Implement the changes -- create/modify the output files
4. Self-check against each acceptance criterion
5. Return your execution report in the format below

## Report Format

Return EXACTLY this format:

**Status:** COMPLETED | PARTIAL | BLOCKED

**Files Created:**
- [absolute path]

**Files Modified:**
- [absolute path]

**Acceptance Criteria Status:**
- [x] [Criterion] -- [how it was met]
- [ ] [Criterion] -- [why not met]

**Issues Encountered:**
- [any problems]

Step 5c-iii: Show the prompt to the user

Display the constructed prompt so the user can verify all values are correct.

Step 5c-iv: Dispatch via Task tool

Task tool call:
  subagent_type: general-purpose
  model: [from agent frontmatter, e.g., "opus"]
  description: "Execute ticket [#]: [short title]"
  prompt: [the complete prompt from step 5c-ii]

Wait for the Task tool to return the executor's report.

5d. Invoke Ticket Verifier Agent

Same pattern: real Task tool dispatch, not simulation.

Step 5d-i: Read the agent definition

Read .claude/agents/ticket-verifier.md. Extract model: from frontmatter (e.g., sonnet).

The verifier agent also has skills: [companion-standards] preloaded. Do NOT include instructions telling the agent to "read" or "load" the skill.

Step 5d-ii: Build the verifier prompt

You are the ticket-verifier agent. You verify that a ticket was correctly implemented. You do NOT make changes -- only observe and report.

## Project Directory

[ACTUAL absolute path from project_path]

## Expected Output Files

[ACTUAL output_files as absolute paths]
- [absolute path 1]
...

## Acceptance Criteria

[ACTUAL acceptance_criteria, numbered]
1. [criterion 1]
2. [criterion 2]
...

## Executor's Report

[PASTE the executor's actual report from Step 5c]

## Instructions

1. Check that each expected output file EXISTS on disk (use Glob or Read)
2. Read each file and verify it meets the acceptance criteria
3. Cross-reference the executor's claims against actual file contents
4. Return your verification report

## Report Format

**Status:** PASS | FAIL | PARTIAL

**Files Verified:**
- [path] -- EXISTS | MISSING -- [notes]

**Acceptance Criteria:**
- [x] [Criterion] -- VERIFIED -- [evidence]
- [ ] [Criterion] -- FAILED -- [what's wrong]

**Recommendation:** PROCEED | RETRY | ESCALATE

**Issues Found:**
- [specific problems]

Step 5d-iii: Dispatch via Task tool

Task tool call:
  subagent_type: general-purpose
  model: [from agent frontmatter, e.g., "sonnet"]
  description: "Verify ticket [#]: [short title]"
  prompt: [the complete verifier prompt]

5e. Orchestrator File-Existence Check (MANDATORY)

After the verifier returns, the orchestrator MUST independently verify that output files exist.

This is a hard guardrail. Even if the verifier says "PASS", check yourself:

ls -la [project_path]/[output_file_1]
ls -la [project_path]/[output_file_2]
...

For EACH output file in the ticket's output_files list:

• If file exists and is non-empty -> CONFIRMED
• If file is missing or empty -> FAIL (regardless of what executor/verifier claimed)

If any output file is missing:

## Orchestrator Check FAILED

Ticket [#]: [Title]
Executor claimed: COMPLETED
Verifier claimed: PASS
But these files do not exist:
- [missing file 1]
- [missing file 2]

This means the executor simulated the work instead of executing it.
Retrying with explicit instructions...

Then retry (see 5f).

5f. Handle Results

Based on verifier recommendation AND orchestrator file check:

• PROCEED (verifier PASS + all files confirmed): Continue to next ticket
• RETRY:
  1. Pass verifier's issues AND orchestrator's missing files to executor
  2. Re-run executor with: "Previous attempt failed. These specific problems must be fixed: [list]. These files MUST exist on disk after you finish: [list]."
  3. Re-run verifier
  4. Re-run orchestrator file check
  5. Max 2 retries, then escalate
• ESCALATE: Stop and present issues to user

5g. Update Local Progress (ONLY after file-existence confirmed)

NEVER update build-progress.md until Step 5e confirms files exist.

After each ticket completes AND files are confirmed:

Update companions/[client]/[companion]/docs/plans/build-progress.md:

• Change ticket status from pending to completed
• Add timestamp
• Log any issues that were resolved

Update tickets.yaml:

• Change the ticket's status from pending to completed

This enables recovery if context is lost mid-build.

Also report progress:

Ticket [#]/[total] complete: [Title]
- Files confirmed on disk: [list]
- Issues resolved: [list, if any]

Update Linear status to Done:

If the ticket has a linear_id, update its status to "Done":

1. Get the "Done" state ID from workflow states (cached from earlier lookup)
2. Update the issue: mcp__linear__linear_updateIssue with id: [linear_id] and stateId: [done_state_id]

Ticket [#]: [Title] -- Linear status -> Done

---

Compliance Checkpoint -- After each ticket:

Ticket [#]/[total] checkpoint:
- Title: [title]
- Executor status: [COMPLETED/PARTIAL/BLOCKED]
- Verifier status: [PASS/FAIL/PARTIAL]
- File existence: [ALL CONFIRMED / N missing]
- Linear status: Done
- Cumulative progress: [N]/[total] tickets complete

Proceeding to ticket [#+1].

---

Phase 3: Present -- Complete Build and Report

Step 6: Handle Failures

If executor or verifier fails:

Executor Failure

The implementation agent couldn't complete the ticket.

• Check if ticket is under-specified
• Check if dependencies are actually complete
• Review executor's error output

Verifier Failure

Implementation was attempted but doesn't pass verification.

• Review verifier's specific issues
• May need to clarify acceptance criteria
• Check if acceptance criteria are testable

Escalation Flow

After max retries, pause and escalate:

## Build Paused

**Failed ticket:** [Title] (#[N])

**Failure type:** [Executor | Verifier]

**What happened:**
[Description of the failure - specific issues from executor/verifier]

**Attempts:** [N]/2

---

**Options:**
1. **Provide additional guidance** -- I'll pass your instructions to the agent and retry
2. **Skip this ticket** -- Mark as blocked, continue (may break dependent tickets)
3. **Abort build** -- Stop here and revise the plan

Choose an option (1/2/3):

Handle each option:

• Option 1: Ask user for guidance, re-run executor with that context, re-run verifier
• Option 2: Mark ticket as skipped in build-progress.md, warn about dependent tickets, continue
• Option 3: Stop execution, summarize what was completed

---

Step 7: Complete Build

After all tickets complete (or are skipped):

## Build Complete: [companion]

**Tickets completed:** [N]/[total]
**Tickets skipped:** [N] (if any)

### Files Created
- [full path to each new file]

### Files Modified
- [full path to each modified file]

### Skipped Tickets (if any)
- [Ticket title] (#N) -- [reason]

---

## Next Steps

1. **Review the companion** at `companions/[client]/[companion]/`
2. **Test the implementation** -- Run any commands or workflows
3. **Run /checkpoint** to capture session state

The project is ready for review.

Set parent ticket to Done:

If linear_parent_issue exists, update it to "Done":

1. Get the "Done" state ID from workflow states (cached from earlier lookup)
2. Update the parent issue: mcp__linear__linear_updateIssue with id: [linear_parent_issue] and stateId: [done_state_id]

Build complete -- [linear_parent_issue] -> Done

---

Compliance Checkpoint -- Phase 3 Complete (Build Summary):

Build complete. Final values:
- Companion: [client/companion]
- Tickets completed: [N]/[total]
- Tickets skipped: [N]
- Total files created: [N]
- Total files modified: [N]
- Linear parent: Done

---

Phase 4: Gate -- Update Reference Projects

Step 8: Update Reference Projects (if persona was used)

After the build completes, check whether this project was created from a persona:

1. Check for persona -- Read context/decisions.md and look for a "Persona:" entry (recorded by /intake Step 2b)

2. If no persona was used -- Skip this step

3. If a persona was used:

   a. Determine the organization from the project path (client portion)

   b. Locate the persona's reference-projects.md:

   • companion-kits/public-kits/personas/[persona]/reference-projects.md or
   • companion-kits/private-kits/[org]-companion-kit/personas/[persona]/reference-projects.md

   c. If reference-projects.md doesn't exist yet, create it using the template from another persona's reference-projects.md

   d. Read the built project's key files to extract reference data:

   • CLAUDE.md -- Configuration and voice
   • context/decisions.md -- Key decisions with rationale
   • context/requirements.md -- What was built and why
   • context/constraints.md -- Constraints that shaped the project

   e. Append a new reference project entry:

   ## [Project Name]
   
   **Location:** `companions/[client]/[companion]/`
   **Client:** [client name]
   **Status:** Active, newly built
   
   ### Configuration
   
   | Dimension | Setting |
   |-----------|---------|
   | [Persona-relevant dimension] | [Value] |
   ...
   
   ### Key Decisions
   
   1. [Decision] -- [Rationale]
   ...
   
   ### What Works Well
   
   - [Learnings from the build -- what patterns emerged]
   
   ### Files Worth Studying
   
   - `[path]` -- [Why it's worth reading]
   ...
   

   f. If prior reference projects exist, add a comparison section:

   ### Differences from [Prior Project]
   
   | Aspect | [Prior] | [This Project] |
   |--------|---------|----------------|
   ...
   

4. Report the update:

Why this matters: Reference projects are the most valuable part of a persona. Each successful build makes the persona better for the next project. This step captures learnings while context is fresh -- you'll never have a better view of what worked than right after building it.

---

Key Principles

Execute, Don't Simulate

The #1 failure mode is reasoning about what agents would do instead of dispatching them.

When this skill says "invoke the executor agent", it means:

1. Read the agent definition file
2. Build a complete prompt with actual values
3. Call the Task tool with the correct model
4. Wait for the real result

It does NOT mean: imagine what the agent would produce and write a plausible report.

Agent Skills Are Preloaded

Both ticket-executor and ticket-verifier agents have skills: [companion-standards] in their frontmatter. This means companion-standards is injected into the agent's context at startup. Do NOT tell agents to "read" or "load" companion-standards -- it is already there. Instructing them to read it wastes tokens and creates confusion.

Three-Layer Verification

Never trust a single source of truth:

1. Executor claims it created files -> but maybe it simulated
2. Verifier confirms files meet criteria -> but maybe it also simulated
3. Orchestrator checks files exist on disk -> this is the hard truth

All three must pass. The orchestrator file check (Step 5e) is the final gate.

Stay Lightweight

The orchestrator (this main conversation) should:

• Dispatch work to executor agent via Task tool
• Dispatch verification to verifier agent via Task tool
• Independently verify file existence
• Handle failures and retries
• Track progress locally

The orchestrator should NOT:

• Do implementation work itself
• Read and analyze code in detail
• Make architectural decisions during build

Agent Separation

• Executor: Implements the ticket, creates/modifies files (dispatched via Task tool, model from frontmatter)
• Verifier: Checks that implementation meets acceptance criteria (dispatched via Task tool, model from frontmatter)
• Orchestrator: Coordinates, tracks progress, verifies file existence, handles failures

Context Isolation

Each agent invocation gets:

• Fresh context window via Task tool
• ALL necessary information in the prompt (absolute paths, full descriptions)
• No assumptions about what they "know"

This means prompts must be self-contained with full paths and complete descriptions. Never pass placeholder values.

Sequential by Default

Execute tickets one at a time. This:

• Ensures dependencies are respected
• Makes debugging easier
• Prevents file conflicts

Parallel execution is a future optimization -- don't attempt it now.

Verify Before Proceeding

Never assume a ticket completed successfully:

• Executor report says COMPLETED -> verify with verifier
• Verifier report says PASS -> verify files exist on disk
• Files exist on disk -> NOW mark complete

---

Error Reference

Situation	Response
No tickets.yaml	"Run /plan first"
tickets.yaml schema invalid	"Schema validation failed -- list problems, stop"
project_path doesn't exist	"Project directory not found -- check path"
Executor timeout	Retry once, then escalate
Verifier returns RETRY	Retry with feedback, max 2 times
Verifier returns ESCALATE	Present issues to user
Orchestrator file check fails	Retry -- executor simulated instead of executing
"Completed" tickets missing files	Reset to pending, re-execute
User aborts	Summarize progress, suggest next steps
Resuming partial build	Verify completed ticket files exist, then resume from first pending

---

Progress Tracking

Throughout the build, maintain awareness of:

• Current ticket number / total
• Tickets completed successfully
• Tickets failed or skipped
• Files created/modified

Local tracking in build-progress.md enables:

• Recovery from context loss
• Resuming partial builds
• Audit trail of what happened

This enables accurate reporting at completion and helps with failure recovery.