/build - Execute Implementation Plan
Overview
Autonomous execution of the implementation plan from /warroom. Each phase gets an isolated worktree for safe parallel execution.
Key principles:
- •Build branch isolates all work from main
- •Each phase gets its own worktree (isolated)
- •Independent phases run in parallel (separate worktrees)
- •Tasks run sequentially within a phase (safe commits)
- •Orchestrator merges phases and resolves conflicts
- •Final output is a PR to main
Prerequisites
Requires completed /warroom session with:
- •
docs/office/tasks.yaml- Feature-grouped task structure - •
spec/phase_*/spec.md- TDD implementation specs (one per phase) - •
docs/office/session.yamlwithstatus: plan_complete
Startup
1. Validate Session
Check (use Bash with test/ls, do NOT read file contents): - session.yaml exists: grep -q "status: plan_complete" docs/office/session.yaml - tasks.yaml exists: test -f docs/office/tasks.yaml - spec/phase_*/spec.md exists: ls spec/phase_*/spec.md >/dev/null 2>&1 If any missing: "Run /warroom first to create implementation plan."
CRITICAL - Context Conservation:
- •Do NOT read tasks.yaml into orchestrator context
- •Do NOT read spec files into orchestrator context
- •Only verify files EXIST - subagents will read them
2. Check for Resume
If docs/office/build/ directory exists:
# Check for existing phase directories
phases=$(ls -d docs/office/build/phase-* 2>/dev/null)
If phases exist:
Ask: "Found existing build. Resume or start fresh?"
If resume:
# Find last completed phase
for dir in $phases; do
grep -l "status: completed" "$dir/status.yaml" 2>/dev/null
done
# Resume from first incomplete phase
If fresh:
rm -rf docs/office/build/
# Start over
3. Configure Build
Ask user (use AskUserQuestion tool):
Model preset:
- •
default- Sonnet/Opus/Haiku/Sonnet (recommended) - •
fast- Sonnet/Sonnet/Haiku/Haiku - •
quality- Opus/Opus/Sonnet/Sonnet
Retry limit: (default: 3)
Note: Build always creates a PR to main when complete.
4. Create Build Branch
Create an isolated branch for all build work:
# Generate session ID
session_id=$(date +%Y%m%d-%H%M%S)
# Create and push build branch
git checkout -b build/${session_id}
git push -u origin build/${session_id}
echo "Build branch: build/${session_id}"
Store session_id for later use (worktree names, PR).
5. Prime Permissions
CRITICAL: Task subagents run in background and auto-deny permission prompts. Prime permissions upfront by running check commands.
5a. Extract permissions from tasks.yaml:
# Get required permissions list
sed -n '/^required_permissions:/,/^[a-z]/{ /^ - /p }' docs/office/tasks.yaml | sed 's/^ - //' | head -20
5b. Always-needed permissions:
These are always required for build (logging, commits):
echo "echo" echo "git"
5c. Project-specific permissions (fallback):
If required_permissions section is missing (older tasks.yaml), infer from project:
[ -f package.json ] && echo "npm" [ -f yarn.lock ] && echo "yarn" [ -f pnpm-lock.yaml ] && echo "pnpm" [ -f Cargo.toml ] && echo "cargo" [ -f go.mod ] && echo "go" [ -f requirements.txt ] && echo "pip" && echo "python" [ -f pyproject.toml ] && echo "pip" && echo "python"
5d. Display to user:
Preparing build permissions... Required commands for this build: - npm - git Requesting permissions now. Please approve each prompt.
5e. Run permission check commands:
For each permission, run the corresponding check command:
| Permission | Check Command |
|---|---|
| echo | echo "permission check" |
| npm | npm --version |
| npx | npx --version |
| yarn | yarn --version |
| pnpm | pnpm --version |
| git | git --version |
| node | node --version |
| cargo | cargo --version |
| go | go version |
| python | python --version |
| pip | pip --version |
| pytest | pytest --version |
| make | make --version |
| tsc | npx tsc --version |
| jest | npx jest --version |
| vitest | npx vitest --version |
Run each check command. User will see permission prompts and approve them.
5f. Confirm and proceed:
After all check commands complete:
All permissions granted. Starting build...
5g. Error handling:
If a check command fails (command not found), warn but continue:
Warning: 'cargo' not found. Tasks requiring Rust may fail. Continue anyway? [Y/n]
If user denies a permission prompt, that command won't work for background agents. Warn and ask whether to continue.
6. Initialize Build Directory
Create the build output structure:
docs/office/build/ └── config.yaml # Build configuration
Extract phase list from tasks.yaml without reading full file:
# Get phase IDs and names only grep -E "^- id:|^ name:" docs/office/tasks.yaml | paste - - | \ sed 's/- id: //; s/ name: /|/'
Create config.yaml with build settings:
models: implementer: sonnet clarifier: opus spec_reviewer: haiku code_reviewer: sonnet retry_limit: 3 started_at: [ISO timestamp]
Note: Each phase executor will create its own docs/office/build/phase-{id}/ directory with status.yaml and progress.log. The orchestrator does NOT create per-phase directories.
7. Start Dashboard
REQUIRED: Invoke /office:dashboard skill to start build dashboard.
Use the Skill tool: skill: "office:dashboard"
8. Extract Phase Dependencies
Extract phase-level dependencies from tasks.yaml (without reading full file):
# Get phase IDs and their depends_on grep -E "^- id:|^ depends_on:" docs/office/tasks.yaml | paste - - | \ sed 's/- id: //; s/ depends_on: /|/'
Example output:
phase-1|[] phase-2|[phase-1] phase-3|[phase-1] phase-4|[phase-2, phase-3]
Parse output to build phase dependency graph:
- •Phases with
depends_on: []→ ready immediately (can start in parallel) - •Phases with dependencies → wait until all dependencies complete and merge
Store dependency graph in memory for orchestration. Do NOT read full tasks.yaml.
Main Loop (Parallel Phases with Worktrees)
Key principle: Independent phases run in parallel in separate worktrees. Tasks within each phase run sequentially (handled by phase-execution skill).
While phases remain incomplete:
1. Find ready phases:
- Status is 'pending'
- All depends_on phases are 'completed' (merged to build branch)
2. For each ready phase IN PARALLEL (single message, multiple Task tools):
a. Create worktree from build branch:
git worktree add .worktrees/phase-{id} -b phase/{id} build/${session_id}
b. Dispatch phase execution (foreground subagent per phase):
Task tool:
subagent_type: general-purpose
description: "Execute phase: {phase-id}"
prompt: |
Execute phase {phase-id} in worktree.
Working directory: {project_path}/.worktrees/phase-{id}
Phase spec: spec/phase_{N}_{name}/spec.md
Tasks file: docs/office/tasks.yaml (your phase only)
Run tasks SEQUENTIALLY (one at a time):
- For each task: implement (TDD) → self-review → commit
- All commits go to phase/{id} branch in your worktree
When all tasks complete:
PHASE_COMPLETE: {phase-id}
On blocking issue:
FLAG: {type} | {task-id} | {description}
3. Wait for ANY phase to complete:
- Poll TaskOutput for each in-progress phase (block=false)
- On completion, process result
4. On PHASE_COMPLETE:
a. Switch to build branch and merge phase:
git checkout build/${session_id}
git merge phase/{id} --no-ff -m "Merge phase: {phase-name}"
b. If merge conflict:
- Read conflicting files to understand the conflict
- Resolve based on phase context (you have full visibility)
- git add -A && git commit -m "Resolve conflicts: phase {id}"
c. Cleanup worktree:
git worktree remove .worktrees/phase-{id}
git branch -d phase/{id}
d. Update phase status to 'completed'
e. Check if new phases are now ready (their dependencies now met)
5. On FLAG:
- Present to user with options (see Flag Handling section)
- Handle user choice
- Resume or skip as directed
All phases complete → Continue to Completion section
Dispatching Multiple Phases in Parallel
CRITICAL: To run independent phases in parallel, dispatch multiple Task tools in a SINGLE message:
Example: phase-1 and phase-3 both have depends_on: [] [Task tool: Execute phase-1 in .worktrees/phase-1] [Task tool: Execute phase-3 in .worktrees/phase-3] Both dispatch in same message → both run simultaneously
Each phase works in its own worktree on its own branch - no conflicts possible.
Conflict Resolution
When merging a phase to build branch, conflicts can occur if:
- •Two parallel phases modified the same file
- •A phase modified a file that was also changed in a dependency
The orchestrator (you) resolves conflicts because:
- •You have context of all phases
- •You can read both versions and understand intent
- •Phase subagents only know their own scope
Resolution approach:
- •
git diff --name-only --diff-filter=Uto list conflicted files - •Read each conflicted file
- •Understand what each phase was trying to do
- •Edit to combine both changes appropriately
- •
git addand commit the resolution
State Management
Key principle: Each phase executor OWNS its status file. No race conditions, no shared state.
Directory Structure
docs/office/build/
├── config.yaml # Build config (created by orchestrator)
└── phase-{id}/ # Created by phase executor
├── status.yaml # Phase executor OWNS this file
└── progress.log # Append-only event log
status.yaml format (per-phase)
phase: phase-1 status: in_progress # pending | in_progress | completed | failed started_at: "2026-01-16T10:30:00Z" tasks: setup-001: completed setup-002: in_progress setup-003: in_progress # parallel with 002 (different dependency chain) setup-004: blocked # waiting on 002, 003
progress.log format (append-only)
2026-01-16T10:30:00 PHASE_START 2026-01-16T10:30:01 TASK_START:setup-001 2026-01-16T10:31:30 TASK_DONE:setup-001 2026-01-16T10:31:31 TASK_START:setup-002 2026-01-16T10:31:31 TASK_START:setup-003 2026-01-16T10:32:45 CODE_REVIEW:setup-002 2026-01-16T10:33:00 TASK_DONE:setup-002
Benefits:
- •No race conditions (each phase has its own file)
- •Dashboard watches
build/directory for all updates - •Orchestrator stays lean (no state file reads)
Invoking Phase Execution
Use the Skill tool to invoke /phase-execution:
Skill tool: skill: "office:phase-execution"
Before invoking, set context for the skill (it reads from conversation):
- •Current phase ID
- •Project path (absolute)
- •Model configuration from config.yaml
- •Retry limit
The skill will:
- •Read tasks.yaml to get this phase's tasks and dependencies
- •Initialize status.yaml and progress.log
- •Spawn task subagents in parallel based on DAG
- •Wait for tasks to complete, spawn newly-ready tasks
- •Return PHASE_COMPLETE or FLAG
Example conversation flow:
Orchestrator: "Executing phase-1: Project Foundation" Orchestrator: "Phase ID: phase-1" Orchestrator: "Project: /Users/dev/my-project" Orchestrator: "Models: sonnet/opus/haiku/sonnet, Retry: 3" [Invokes Skill: office:phase-execution] ... skill runs, spawns parallel tasks ... Skill returns: "PHASE_COMPLETE: phase-1" Orchestrator: Applies completion policy, moves to phase-2
Skill Completion
The /phase-execution skill runs in the foreground (main context). When it returns:
| Output | Meaning | Action |
|---|---|---|
PHASE_COMPLETE: [id] | Phase finished | Apply completion policy |
FLAG: [type] | [task] | [desc] | Needs human input | Handle flag |
Dashboard integration: The skill updates status.yaml and progress.log as tasks complete. Dashboard watches these files for real-time progress display.
Flag Handling
Flags are the only time human intervention is needed.
Flag Types
| Type | Trigger | Severity |
|---|---|---|
clarifier_blocked | Clarifier can't answer from codebase | BLOCKING |
spec_review_exhausted | 3 attempts, still not compliant | BLOCKING |
code_review_exhausted | 3 attempts, still has issues | WARNING |
implementation_error | Unrecoverable error | BLOCKING |
security_concern | Potential vulnerability | BLOCKING |
On Flag Received
1. Read flag details from TaskOutput result 2. Present to user: FLAG: [type] Task: [task-id] - [task-title] Phase: [phase-id] [Context from flag payload] Options: [1] Provide guidance [2] Skip task [3] Accept as-is [4] Abort phase 3. On user choice: - Guidance: Resume phase with user's input - Skip: Mark task skipped, continue to next - Accept: Mark task completed with warnings - Abort: Mark phase aborted, continue others
Severity Behavior
| Severity | Feature | Other Features |
|---|---|---|
| BLOCKING | Paused until resolved | Continue |
| WARNING | Continues (task has warnings) | Unaffected |
Completion
On Phase Complete
Merge phase to build branch:
1. Switch to build branch:
git checkout build/${session_id}
2. Merge phase:
git merge phase/{id} --no-ff -m "Merge phase: {phase-name}"
3. Handle conflicts if any (orchestrator resolves)
4. Cleanup worktree:
git worktree remove .worktrees/phase-{id}
git branch -d phase/{id}
5. Update phase status to 'completed'
Check: Any blocked phases now unblocked?
On All Phases Complete
All phases have been merged to build/${session_id} branch.
Create Pull Request:
gh pr create \
--base main \
--head build/${session_id} \
--title "Build: {project-name}" \
--body "$(cat <<'EOF'
## Build Summary
**Session:** ${session_id}
**Phases:** {N} completed
| Phase | Tasks | Status |
|-------|-------|--------|
| phase-1 | {n}/{m} | completed |
| phase-2 | {n}/{m} | completed |
## Changes
{summary of major changes from each phase}
---
Generated by Office Plugin /build
EOF
)"
echo "PR created: $(gh pr view --json url -q .url)"
Report to user:
## Build Complete!
**PR Created:** {pr_url}
**Summary:**
- Phases: {N} completed
- Total tasks: {M}
| Phase | Tasks | Commits |
|-------|-------|---------|
| {phase-name} | {completed}/{total} | {commit-count} |
**Next steps:**
1. Review the PR: {pr_url}
2. CI checks will run automatically
3. Merge when ready
Note: Build branch `build/${session_id}` will be deleted when PR is merged.
Cleanup
# Update session status sed -i '' 's/status: .*/status: build_complete/' docs/office/session.yaml # Stop dashboard pkill -f "server.py.*office" 2>/dev/null # Worktrees already cleaned up after each phase merge # Build branch remains until PR is merged/closed
Context Budget Guidelines
| Item | Approach | Context Cost |
|---|---|---|
| tasks.yaml | Read once per phase by skill | ~500-1k (per phase) |
| spec files | Read by task subagents | ~0 (in main) |
| State updates | Skill owns status files | ~50 per update |
| /build skill | Loaded once | ~5k |
| /phase-execution skill | Loaded per phase | ~3k (per phase) |
| Task subagent results | Brief completion messages | ~100 per task |
Total per phase: ~5-8k context
Why this works:
- •Each task subagent gets fresh context (no accumulation)
- •Skill reads tasks.yaml once, stores dependency graph in memory
- •Heavy implementation work happens in isolated subagents
Files
Skills:
- •
skills/building/SKILL.md- This orchestrator - •
skills/phase-execution/SKILL.md- Phase executor (DAG + task parallelism)
Runtime files:
- •
docs/office/build/config.yaml- Build configuration - •
docs/office/build/phase-{id}/status.yaml- Per-phase status (owned by phase-execution skill) - •
docs/office/build/phase-{id}/progress.log- Per-phase event log - •
docs/office/session.yaml- Updated on completion