build

/vibeos:build — Autonomous Build Orchestrator

Execute work orders autonomously with TDD, layered agents, quality gates, and error recovery.

Communication Contract

Follow the full USER-COMMUNICATION-CONTRACT.md (docs/USER-COMMUNICATION-CONTRACT.md). Key rules:

• Lead with outcome, follow with mechanism
• Present decisions with consequences
• Introduce every concept on first use with plain English definition

Skill-specific addenda:

• Never ask "what do you want to build?" — read the plan and execute
• Explain results in plain English first; add technical detail after that only when it helps the user understand the impact
• Every escalation or check-in choice must include options, pros, cons, and a recommendation

First-Run Onboarding

Check if this is the user's first time using VibeOS on this project (second entry point — users may invoke /vibeos:build directly):

1. Read .vibeos/config.json — if it does not exist or onboarding_complete is false, this is the first run
2. If first run, present the onboarding message:

Welcome to VibeOS

VibeOS turns Claude into an autonomous development engine. Here's how it works:

1. You describe what you want to build — I'll ask questions to understand your vision
2. I create a development plan — broken into phases and work orders (detailed task specs)
3. I build autonomously — writing tests first, then code, with quality checks at every step
4. I check in with you — at natural pause points so you can review, redirect, or continue

Your role: You make the decisions — what to build, what quality level to target, when to ship. I handle the implementation, testing, and quality enforcement.

What to expect: You'll see progress updates as each piece is built. I'll explain what I'm doing in plain English. When I need your input, I'll present clear options with their implications.

3. Create .vibeos/config.json (or update it) with "onboarding_complete": true

Prerequisites

Before starting, verify these exist:

• docs/planning/DEVELOPMENT-PLAN.md
• docs/planning/WO-INDEX.md
• project-definition.json
• Git repository: Run git rev-parse --is-inside-work-tree. If not a git repo, warn: "This directory is not a git repository. State tracking, baselines, and convergence features won't work correctly. Initialize git with git init before building." Build can proceed but with degraded convergence.

If planning files are missing, tell the user to run /vibeos:plan first.

Completion Discipline

Use process only where it materially protects software quality, truthful status, security, architecture, and recoverability.

A WO is only Complete when all of these are true:

• the intended behavior is implemented
• the real execution path is verified
• relevant tests pass
• relevant quality checks pass
• the status artifacts are truthful
• the repo is left in a clean resumable state

Hard blockers:

• broken real path
• failing tests for changed behavior
• meaningful architecture violations
• security or compliance regressions
• fallback behavior hiding a broken primary path
• ambiguous repo state or misleading status updates

Do not block on low-value bureaucracy:

• formatting and import ordering
• cosmetic doc polish
• minor wording issues
• unrelated cleanup outside the touched scope

Auto-fix trivial hygiene when cheap. Log or defer low-value cleanup when it does not materially affect correctness or trust.

Truthful partial WO states:

• Implemented Locally — code exists, but the real path is not yet proven
• Awaiting Gate Cleanup — behavior exists, but blocking gates still fail
• Awaiting Real-Path Verification — tests or modules pass, but the actual entrypoint is not yet exercised
• Dev-Mode Complete — works in a dev or mocked path, but not yet through the production-like path
• Awaiting Checkpoint — WO-level work is clear, but required checkpoint or ratchet closure is still pending
• Awaiting Evidence — behavior may be done, but documentation, audit evidence, or handoff state is not yet truthful

Never mark fallback-only, degraded-only, or skip-the-gates work as Complete.

WO Checkpoint & Resume

The build loop saves progress after each agent completes. If interrupted (context window reset, user pause, crash), the build resumes from where it left off.

Checkpoint file: .vibeos/checkpoints/WO-NNN.json

Schema:

{
  "wo": "WO-NNN",
  "started_at": "ISO-8601",
  "last_updated": "ISO-8601",
  "current_step": 5,
  "total_steps": 8,
  "completed_agents": [
    {"agent": "investigator", "step": 4, "result": "PROCEED", "completed_at": "ISO-8601"},
    {"agent": "tester", "step": 5, "result": "tests-written", "completed_at": "ISO-8601"}
  ],
  "gate_attempts": 0,
  "audit_iterations": 0,
  "state_hash": "sha256"
}

On WO start (Step 1): Check for existing checkpoint:

1. Look for .vibeos/checkpoints/WO-NNN.json
2. If found: read checkpoint and announce resume:

   "Resuming WO-NNN from step [N]/8. Already completed: [agent list]. Picking up at: [next step name]."

3. Skip to the next incomplete step
4. If not found: start fresh, create checkpoint directory: mkdir -p .vibeos/checkpoints

After each agent completes (Steps 4-9): Write/update checkpoint file with the completed agent and step number.

On WO completion (Step 10): Delete checkpoint file. If .vibeos/checkpoints/ is empty, remove directory.

Build Flow

Step 1: Identify Next WO

If $ARGUMENTS contains a WO number, use that. Otherwise:

1. Read docs/planning/DEVELOPMENT-PLAN.md

2. Read docs/planning/WO-INDEX.md

3. After the WO file path is known, initialize session state for this WO:

   bash scripts/activate-session.sh "<WO-file-path>"
   

   This records the active WO in .vibeos/session-state.json and prepares audit tracking state for the build cycle.

4. Phase 0 enforcement (midstream projects): If Phase 0 exists (remediation phase) and has incomplete fix-now WOs, those must be built first. Do not proceed to Phase 1 until all Phase 0 fix-now WOs are complete. Tell the user:

   "Phase 0 (remediation) has [N] incomplete fix-now items. These critical issues must be resolved before starting feature work. Building WO-NNN ([title]) next.

   Your options:

   1. Build Phase 0 first — Fix the [N] critical issues before feature work.
      • Pros: your codebase starts cleaner and the issues will not compound as you add code
      • Cons: delays feature work in the short term
      • Technical note: Phase 0 is the remediation phase for fix-now findings
   2. Skip Phase 0 for now — Start feature work immediately while leaving the [N] issues unresolved.
      • Pros: fastest path to visible feature progress
      • Cons: unresolved issues may spread into new code and this will be logged as an accepted risk
      • Technical note: the skipped Phase 0 work orders remain in the plan and can be resumed later

   I recommend option 1 because [specific reasoning based on finding severity — e.g., 'the security findings could expose user data if exploited']."

   If user chooses to skip: log risk acceptance in .vibeos/build-log.md with timestamp and justification. Append to docs/planning/ACCEPTED-RISKS.md if it exists.

5. Find the current phase (first phase with incomplete WOs)

6. Within that phase, find the first WO whose:

   • Dependencies are all Complete
   • Status is one of:
     • Draft
     • Implementation Ready
     • In Progress
     • Implemented Locally
     • Awaiting Gate Cleanup
     • Awaiting Real-Path Verification
     • Dev-Mode Complete
     • Awaiting Checkpoint
     • Awaiting Evidence
     • Pre-Commit Audit

If no WO is available, report that all WOs in the current phase are complete and suggest running /vibeos:status for the current session view or /vibeos:project-status for the overall project picture.

Step 2: Read Autonomy Config

Read .vibeos/config.json if it exists:

• autonomy.level = "wo" — pause after this WO completes
• autonomy.level = "phase" — continue until phase completes
• autonomy.level = "major" — continue until a major decision is needed
• autonomy.session_override.mode = "autonomous" with active = true — temporarily suppress routine check-ins and keep building until blocked, complete, or explicitly stopped

Default to "wo" if config doesn't exist.

Step 2b: Initialize or Refresh Session State

Read .vibeos/session-state.json if it exists.

If the autonomous session override is active:

1. Create .vibeos/session-state.json if it does not exist
2. Ensure it contains:
   • session_id
   • mode
   • active
   • started_at
   • last_updated
   • started_from_wo
   • completed_wos
   • phase_checkpoints
3. If it already exists, preserve completed_wos and phase_checkpoints, update last_updated, and keep active: true
4. If .vibeos/build-log.md does not exist, create it before logging any session events

Step 3: Set Agent Identity

Write the current agent name to .vibeos/current-agent.txt before each agent dispatch. This enables the test file protection hook to identify which agent is running.

echo "investigator" > .vibeos/current-agent.txt

Update this file before each agent dispatch.

Step 4: Dispatch Investigator Agent

Progress banner:

"Starting WO-NNN: [title]. [1-sentence description of what this builds]." "[Step 1/8] Investigator — Reviewing requirements and checking dependencies before we start building..."

Dispatch agents/investigator.md with:

• Input: WO file path, development plan path
• Purpose: Revalidate assumptions, check dependencies, analyze codebase, flag risks, and verify anchor/freshness readiness

On result:

• If recommendation is BLOCK (critical issues): pause, report to user, ask how to proceed
• If recommendation is PROCEED WITH CAUTION: log risks, continue
• If recommendation is PROCEED: continue
• If the investigation report cannot identify the real entrypoint for the changed behavior (route, handler, job, CLI, webhook, scheduler), treat that as a material readiness gap. Do not allow the WO to close as Complete until that path is mapped or explicitly accepted as a partial state.

Cross-validate agent claims about code state (mandatory):

When the investigator (or any auditor) reports that a file is empty, a stub, missing, or broken:

1. Read the file directly using the Read tool — do not trust the agent's claim without verification
2. Compare the actual file contents (line count, first/last non-empty lines) against the agent's report
3. If the claim does not match actual contents: log the discrepancy in the build log, use the actual file state for all downstream decisions
4. If the claim matches: proceed normally

This prevents cascading false diagnoses where a single agent hallucination leads to wrong plans, wasted reimplementation, and misleading status reports.

Log the dispatch to .vibeos/build-log.md:

[timestamp] investigator WO-NNN investigate [PROCEED|CAUTION|BLOCK]

Step 5: Dispatch Tester Agent (TDD)

Progress banner:

"[Step 2/8] Tester — Writing tests from your requirements. These tests define what 'working' means before any code is written."

Set agent identity: echo "tester" > .vibeos/current-agent.txt

Dispatch agents/tester.md with:

• Input: WO file path, project language/framework info
• Purpose: Write tests from spec BEFORE implementation exists

On result:

• Verify test files were created
• Verify tests fail (correct TDD behavior — no implementation yet)
• If tests somehow pass: investigate (might indicate the feature already exists)
• If the WO changes user-visible or system-visible behavior, require at least one integration or smoke-style test for the real path when the environment allows it. If the tester cannot exercise the real path yet, record the exact gap and carry the WO as a partial state instead of silently treating unit coverage as closure.

Log: [timestamp] tester WO-NNN write-tests [count] tests written, all failing

Step 6: Dispatch Prompt Engineer / Implementation Agent

Progress banner:

"[Step 3/8] [Prompt Engineer/Backend/Frontend] — Applying prompt standards where needed and writing the implementation to satisfy the work order..."

Determine which agent to use:

• Read WO scope and the investigation report to determine if it changes prompt artifacts, backend code, frontend code, or a combination
• Prompt artifacts include agents/*.md, skills/*/SKILL.md, CLAUDE.md, instruction files, prompt registries, or other behavior-governing prompt assets
• If prompt artifacts are in scope: dispatch agents/prompt-engineer.md first
• If backend code is in scope: dispatch agents/backend.md
• If frontend code is in scope: dispatch agents/frontend.md
• If both backend and frontend are in scope: run prompt-engineer first if needed, then backend, then frontend

Set agent identity before each dispatch:

• echo "prompt-engineer" > .vibeos/current-agent.txt
• echo "backend" > .vibeos/current-agent.txt
• echo "frontend" > .vibeos/current-agent.txt

Dispatch agents/prompt-engineer.md with:

• Input: WO file path, investigation report, target prompt artifact paths, target agent type
• Purpose: Apply the embedded Prompt Engineering Bible before any prompt or agent-instruction changes are written

Dispatch implementation agents with:

• Input: WO file path, test file paths, investigation report
• Purpose: Implement code to make tests pass

On result:

• If prompt-engineer ran, verify its report names the Bible profile used and the prompt files updated
• Check test results — all tests should pass
• Check self-check results — no stubs, no secrets, types present
• If tests still failing: retry once with specific failure details
• If retry fails: escalate to user
• If the implementation only works through a mocked, fallback, or dev-only path, classify the WO as Implemented Locally or Dev-Mode Complete until the primary path is verified.

Log: [timestamp] [agent-name] WO-NNN implement [PASS|FAIL] [details]

Step 7: Run Real-Path Verification and Quality Gates

Progress banner:

"[Step 4/8] Quality Gates — Running [N] automated quality checks..."

On result: Report inline: "Quality checks: [passed]/[total] passed. [top issue if any]." On retry: "[issue description]. Fixing and re-checking (attempt [N] of 3)..."

Real-path verification is mandatory for meaningful behavior changes.

Before treating gate output as closure evidence:

1. Read the investigator's real-path map.
2. Identify the actual route, handler, job runner, CLI entrypoint, webhook, scheduler, or other runtime trigger.
3. Exercise that path through the most realistic available verification method: integration test, smoke test, scripted request, CLI invocation, job run, or equivalent.
4. Confirm the primary path works without relying on a fallback, default branch, or degraded behavior that could manufacture success.
5. If the environment cannot exercise the real path, stop short of Complete. Use Awaiting Real-Path Verification, Dev-Mode Complete, or Implemented Locally, and record exactly what still needs to be proven.

Run pre_commit gates:

bash scripts/gate-runner.sh pre_commit --project-dir "${CLAUDE_PROJECT_DIR:-.}"

Baseline-aware gate evaluation:

After running gates, check each failure against known baselines.

Auto-migration: If .vibeos/baselines/midstream-baseline.json exists with version 1.0 (old count-based format), auto-migrate to finding-level format:

bash ".vibeos/convergence/migrate-baseline.sh" \
  --input ".vibeos/baselines/midstream-baseline.json" \
  --output ".vibeos/baselines/midstream-baseline.json"

Tell user: "I upgraded your quality baseline to the new finding-level format. This gives more precise tracking of individual issues."

No baseline exists: If .vibeos/baselines/midstream-baseline.json does not exist and .vibeos/findings-registry.json exists, create the baseline:

bash ".vibeos/convergence/baseline-check.sh" create \
  --mode finding-level \
  --baseline-file ".vibeos/baselines/midstream-baseline.json" \
  --current-findings-file ".vibeos/findings-registry.json"

Tell user: "No quality baseline existed yet. I've created one from your audit findings — [N] existing issues are now tracked. Only new issues will block builds."

If neither baseline nor findings-registry exists (greenfield project), skip baseline checks entirely.

The system supports two modes:

Finding-level mode (preferred, if .vibeos/findings-registry.json exists):

bash ".vibeos/convergence/baseline-check.sh" check \
  --mode finding-level \
  --baseline-file ".vibeos/baselines/midstream-baseline.json" \
  --current-findings-file ".vibeos/findings-registry.json"

This compares individual findings by fingerprint (SHA-256 of category:file:pattern:severity). New findings not in the baseline are flagged individually by ID and file, enabling precise tracking.

Count-based mode (fallback, for projects without findings registry):

bash ".vibeos/convergence/baseline-check.sh" check \
  --baseline-file ".vibeos/baselines/midstream-baseline.json" \
  --category "[gate-name]" --current-count [failure-count]

Results:

• PASS: No failures — proceed
• TRACKED: Failures within baseline (pre-existing) — log as tracked, proceed
• FAIL: Failures exceed baseline (new issues) — trigger fix cycle

VC-Audit-Aligned gates (advisory by default, blocking for production+): The gate suite includes gates targeting VC technical due diligence dimensions: code complexity, API contracts, observability, data integrity, auth boundaries, AI integration, resilience patterns, and dev environment. These are configured by the decision engine based on deployment_context and ai_provider in project-definition.json. Advisory failures from these gates should be logged and addressed when practical — they represent areas that a VC auditor would flag during due diligence.

Gate fix loop (max 3 cycles):

1. Parse gate results for new failures (exceeding baseline)
2. If all pass or tracked: proceed to Step 8
3. If new failures: notify user before acting:

   "[Specific issue, e.g. 'Type annotations missing on 3 functions in src/api.py']. Fixing automatically and re-running quality checks (attempt [N] of 3)..."

4. Re-dispatch implementation agent with specific failure details
5. Re-run gates
6. Repeat until pass or 3 cycles exhausted

After successful gate pass with fewer failures than baseline, ratchet:

# Finding-level ratchet (removes fixed findings from baseline)
bash ".vibeos/convergence/baseline-check.sh" ratchet \
  --mode finding-level \
  --baseline-file ".vibeos/baselines/midstream-baseline.json" \
  --current-findings-file ".vibeos/findings-registry.json"

# Count-based ratchet (fallback)
bash ".vibeos/convergence/baseline-check.sh" ratchet \
  --baseline-file ".vibeos/baselines/midstream-baseline.json" \
  --category "[gate-name]" --current-count [failure-count]

On 3 failed cycles: Escalate to user with consequences:

"Quality checks are still failing after 3 attempts. Here's what's failing: [specific issues].

Your options:

1. Try a different approach — I'll rethink the implementation and try again.
   • Pros: best chance of preserving quality without asking you to step in
   • Cons: uses more time and may still fail
   • Technical note: this triggers another implementation plus gate-validation cycle
2. Skip these checks for now — I'll move forward without passing [gate-name].
   • Pros: fastest path to continuing the work
   • Cons: [specific risk, e.g., "type annotations won't be verified, which could let type-related bugs through"]
   • Technical note: the gate remains failing until rerun and should be treated as deferred risk; the WO status must remain Awaiting Gate Cleanup or another truthful partial state
3. Fix it yourself — I'll show you exactly what's failing and where, then wait for your change.
   • Pros: you keep full control over the fix
   • Cons: requires manual work from you
   • Technical note: I'll re-run the same gate after your update

I recommend option 1 because [reason based on which gates are failing and their severity]."

Log each gate run: [timestamp] gate-runner WO-NNN pre_commit [PASS|FAIL] [details]

Step 7b: Ground Truth Checkpoint

For WOs that modify API endpoints or UI:

• If the WO added or modified backend API routes:
  • Boot the test server (if a test fixture exists for this)
  • Hit the actual endpoint with a real HTTP request (not a test client mock)
  • Verify the response shape matches what the frontend or consumer expects
  • Log the actual response in the evidence bundle
• If the WO added or modified frontend pages:
  • Verify the API URLs in the frontend code match actual backend routes
  • Verify field names in TypeScript types match Pydantic model field names
  • If build succeeds without errors, log "Frontend builds clean"
• If ground truth verification is not possible (e.g., requires live Azure services):
  • Status MUST be capped at "Dev-Mode Complete" or "Awaiting Real-Path Verification"
  • Document exactly what's needed for full verification in the evidence bundle
• Evidence from this step goes into docs/evidence/WO-{N}/ground-truth.md

Step 8: Run Audit Cycle (Layer 2)

Progress banner:

"[Step 5/8] Audit — Running 8 independent quality reviewers, including red-team adversarial checks and a product-drift check. This is the longest step and may take a minute..."

On result: "Audit complete: [confirmed] confirmed findings, [warnings] warnings. [critical summary if any]." On convergence retry: "Fix applied. Re-running auditors to verify (iteration [N] of 5)..."

After gates pass, run the full audit cycle for deeper quality enforcement.

Stale finding discard: When consuming audit agent results, verify the commit SHA in the findings matches the current HEAD of the working branch. If the SHA is stale (differs from HEAD), discard the findings and log: "Discarded stale audit findings from commit {SHA} (HEAD is {HEAD_SHA})" in the build log. Do not act on stale findings.

Audit visibility selection (mandatory, autonomous-safe): Before dispatching auditors for a WO, choose visibility automatically:

bash scripts/select-audit-visibility-mode.sh "${WO_FILE:-${WO_NUMBER:-}}"

Read .vibeos/session-state.json after that command and use:

• audit_visibility_mode
• audit_dispatch_profile
• audit_snapshot_ref

Rules:

• If audit_dispatch_profile is same-tree, dispatch the *-same-tree.md auditor variants.
• If audit_dispatch_profile is worktree, dispatch the standard isolated-worktree auditors.
• Do not pause autonomy to ask which audit mode to use.
• If a saved audit report is produced, it must include audit_visibility_mode and audit_snapshot_ref in its header.

Dispatch the audit skill logic (do NOT invoke /vibeos:audit as a skill — instead, dispatch the audit agents directly following the same pattern as skills/audit/SKILL.md):

1. Dispatch all 8 audit agents in parallel where possible, selecting the correct variant (*-same-tree.md or standard) based on audit_dispatch_profile:

   • agents/security-auditor.md or agents/security-auditor-same-tree.md
   • agents/architecture-auditor.md or agents/architecture-auditor-same-tree.md
   • agents/correctness-auditor.md or agents/correctness-auditor-same-tree.md
   • agents/test-auditor.md or agents/test-auditor-same-tree.md
   • agents/evidence-auditor.md or agents/evidence-auditor-same-tree.md
   • agents/product-drift-auditor.md or agents/product-drift-auditor-same-tree.md
   • agents/red-team-auditor.md or agents/red-team-auditor-same-tree.md (adversarial verification — reports corruption score)
   • agents/contract-validator.md or agents/contract-validator-same-tree.md (validates frontend-backend contracts; skip only when scope is a pure documentation WO with no code changes)

2. Collect findings and apply consensus logic (see skills/audit/SKILL.md Step 4)

3. Filter by severity:

   • Critical or High findings: trigger audit-fix cycle
   • Medium or Low findings: log as warnings in build log, do not block

Audit-fix cycle with convergence control:

Before starting the fix cycle, capture the initial state hash:

PREV_HASH=$(bash ".vibeos/convergence/state-hash.sh" --project-dir "${CLAUDE_PROJECT_DIR:-.}")

For each fix cycle iteration:

1. Extract critical/high findings with file paths and recommendations
2. Notify user before acting:

   "Audit found [N] issues to fix: [top finding summary]. Fixing automatically (iteration [N] of 5)..."

3. Re-dispatch the appropriate implementation agent (backend or frontend) with:
   • The specific findings to fix
   • The file paths and line numbers
   • The recommended fixes from the auditors
4. Capture new state hash after fixes:

   CURR_HASH=$(bash ".vibeos/convergence/state-hash.sh" --project-dir "${CLAUDE_PROJECT_DIR:-.}")
   

5. Run convergence check:

   bash ".vibeos/convergence/convergence-check.sh" \
     --current-hash "$CURR_HASH" --previous-hash "$PREV_HASH" \
     --iteration $N --max-iterations 5 \
     --critical-count $CRITICAL --high-count $HIGH \
     --previous-critical $PREV_CRITICAL --previous-high $PREV_HIGH \
     --tests-pass "$TESTS_PASS"
   

6. Act on convergence decision:
   • CONVERGED: proceed to Step 9
   • CONTINUE: re-run audit agents, loop back to step 1
   • STUCK or MAX_ITER: escalate to user
7. Update PREV_HASH=$CURR_HASH and store previous finding counts

Escalation format (STUCK or MAX_ITER):

"After [N] fix attempts, these issues remain: [list of findings with severity, file, description]

These were flagged by: [auditor names] Fix attempts: [what was tried]

Your options:

1. Try a different approach — I'll use a different strategy and run the audit again.
   • Pros: best chance of clearing the findings without leaving risk behind
   • Cons: uses more time and may still not resolve everything
   • Technical note: this starts another fix-and-audit cycle
2. Accept these findings — Keep moving and track these issues as known risks.
   • Pros: preserves momentum on the current work order
   • Cons: [If security]: [specific security risk] remains in the code. [If architecture]: [specific maintenance risk] remains and may resurface later. [If product drift]: the work may move away from the intended experience until corrected
   • Technical note: accepted findings remain in the audit trail and should be logged in docs/decisions/DEVIATIONS.md when they are deliberate compromises
3. Fix it yourself — I'll give you exact file locations and details, then verify your changes.
   • Pros: you control the exact remediation
   • Cons: requires manual intervention from you
   • Technical note: I'll re-run the audit after your changes

I recommend [X] because [specific reasoning based on finding severity and project context]."

Log each audit run:

[timestamp] audit WO-NNN layer2-audit cycle-[N] [PASS|FINDINGS] critical:[N] high:[N] medium:[N] low:[N]

Save the audit report to .vibeos/audit-reports/WO-NNN-[timestamp].md.

The report header must include:

• audit_visibility_mode: value from session-state.json
• audit_snapshot_ref: value from session-state.json (or none)

After saving the report, register it and validate independent audit coverage before proceeding:

bash scripts/register-audit-report.sh ".vibeos/audit-reports/WO-NNN-[timestamp].md"
bash scripts/validate-independent-audit.sh "${WO_FILE:-${WO_NUMBER:-}}" ".vibeos/audit-reports/WO-NNN-[timestamp].md"

If validate-independent-audit.sh returns non-zero, treat the WO as Awaiting Evidence until the validation passes.

Step 9: Dispatch Doc Writer Agent

Progress banner:

"[Step 6/8] Documentation — Updating project docs and work order tracking..."

Set agent identity: echo "doc-writer" > .vibeos/current-agent.txt

Dispatch agents/doc-writer.md with:

• Input: WO file path, implementation report, test report, prompt-engineering report (if any)
• Purpose: Update documentation, WO file, and tracking docs

On result:

• Verify WO file was updated with implementation notes
• Verify WO-INDEX.md was updated

Log: [timestamp] doc-writer WO-NNN document [COMPLETE]

Step 10: WO Completion

Progress banner:

"[Step 7/8] Completing WO — Updating tracking documents..."

After all agents succeed:

1. Check completion truthfulness before updating any status artifacts:
   • intended behavior implemented
   • real path verified
   • relevant tests passing
   • relevant blocking gates and audits resolved
   • repo left in a resumable, unambiguous state
2. If any item above is still false, do not mark the WO Complete. Use the most accurate partial state instead:
   • Implemented Locally
   • Awaiting Gate Cleanup
   • Awaiting Real-Path Verification
   • Dev-Mode Complete
   • Awaiting Checkpoint
   • Awaiting Evidence
3. Mark WO status as Complete in the WO file only when the truthfulness check passes (if doc-writer didn't already)
4. Update WO-INDEX.md and DEVELOPMENT-PLAN.md to match the truthful final state and add the completion date only when the WO is actually Complete
5. Clean up .vibeos/current-agent.txt
6. Delete checkpoint file only on true completion; otherwise preserve or refresh resumable state so the next session can pick up cleanly
7. Remediation aging check (if .vibeos/findings-registry.json exists):
   • Read fix-later items from findings-registry.json
   • For each, check the baselined_at_wo field (set by WO-043 when the finding was baselined)
   • Read aging threshold from .vibeos/config.json remediation_aging_threshold (default: 5 WOs)
   • Count WOs completed since the finding was baselined
   • If any fix-later item exceeds the threshold, remind the user:

     "Reminder: [N] fix-later remediation items have been deferred for [M] work orders. Consider scheduling them soon:

     • [finding title] (deferred since WO-NNN)
     • [finding title] (deferred since WO-NNN) Run /vibeos:status for the current session view or /vibeos:project-status for the big-picture project view."

8. If .vibeos/session-state.json exists and the session is active:
   • append this WO to completed_wos with WO number, title, completion time, and 1-line summary
   • update last_updated
   • if a phase checkpoint was run during this WO, append it to phase_checkpoints

Report to user:

"WO-NNN ([title]) is complete.

• [N] tests written and passing
• [M] quality gates passed
• [L] audit findings resolved
• [K] files created/modified
• TDD enforcement: [B] test file modification attempts blocked
• Documentation updated
• This work order dispatched [N] agents across [M] iterations ([X] gate retries, [Y] audit convergence cycles)

Phase [P]: [completed]/[total] work orders complete. Next: WO-NNN+1 ([next title]) is ready."

If the WO is left in a truthful partial state, the closeout must say so plainly:

"WO-NNN ([title]) is not fully closed yet.

• Current state: [Implemented Locally / Awaiting Gate Cleanup / Awaiting Real-Path Verification / Dev-Mode Complete / Awaiting Checkpoint / Awaiting Evidence]
• What is real today: [working behavior that is actually evidenced]
• What remains unresolved: [material blocker]
• Exact next step: [the next action to reach true completion]"

TDD metric source: Count lines matching test-file-protection | BLOCKED in .vibeos/build-log.md since this WO started (compare timestamps against checkpoint started_at).

Step 11: Multi-WO Orchestration & Autonomy Check

Progress banner:

"[Step 8/8] Check-in — Here's what was built: [summary]"

After WO completion, determine whether to continue with the next WO.

11a. Read autonomy config from .vibeos/config.json (default: "wo"), including any autonomy.session_override.

11b. Detect phase boundary:

• Read the current WO's phase from DEVELOPMENT-PLAN.md
• Identify the next eligible WO (Step 1 logic)
• If the next WO is in a different phase: this is a phase boundary

11c. Apply autonomy rules:

If autonomy.session_override.mode = "autonomous" and active = true:

• Continue automatically to the next eligible WO without routine human check-ins
• Do not pause at normal WO boundaries
• If a phase boundary is reached, run the checkpoint flow automatically before entering the next phase
• If the checkpoint passes, continue automatically into the next phase
• Pause only if one of these happens:
  • investigator returns BLOCK
  • an escalation or explicit risk decision is required
  • the automatic checkpoint finds a blocking regression
  • no eligible WOs remain
  • the user explicitly says stop, pause, or change autonomy
• When pausing under this mode, explain that the pause is required by the governance rules, not a routine check-in

If level = "wo": Stop. Report completion and wait for user to say "continue" or "proceed".

If level = "phase":

• If phase boundary reached: stop and report phase completion
• If more WOs in current phase: loop back to Step 1 for the next WO
• At phase boundary, report:

  "Phase [N] ([name]) is complete.

  • WOs completed in this phase
  • [Y] total tests passing
  • [Z] audit findings resolved

  Next phase: Phase [N+1] ([name]) with [W] WOs."

If level = "major": Continue to next WO unless:

• Phase boundary reached (pause for phase transition report)
• A WO has BLOCK recommendation from investigator
• An escalation was triggered during the WO
• Architecture change is needed (flagged by architecture auditor)

11d. Dependency check for next WO: Before looping back to Step 1:

1. Read DEVELOPMENT-PLAN.md for the next WO's dependencies
2. Verify all dependencies have status "Complete"
3. If dependencies unmet: skip to the next eligible WO in the same phase
4. If no eligible WOs remain in the phase: report phase complete, stop
5. If skipping: log which WO was skipped and why

11e. Human check-in report:

When pausing (any autonomy level), generate a check-in report.

If an autonomous session override is active and the pause is required, lead with:

"I stayed in full autonomous mode until I hit something that needs your decision or review. This pause is required by the rules, not a routine progress check-in."

Then provide the standard report:

Build Progress Check-in

Completed this session:

• WO-NNN: [title] — [1-line summary of what was built]
• [additional WOs if autonomy=phase or major]

Quality summary:

• Tests: [N] passing, [M] failing
• Gates: [N]/[M] passing
• Audit: [N] findings resolved, [M] warnings remaining

Next up: WO-NNN ([title]) [1-sentence description of what this WO will build]

Your options:

1. Continue — move straight into the next work order.
   • Pros: keeps momentum and reduces context switching
   • Cons: you review less between steps
   • Technical note: the build loop immediately selects the next eligible WO from the plan
2. Adjust plan — change scope, reorder priorities, or add new work orders.
   • Pros: keeps the roadmap aligned with what you want now
   • Cons: adds planning time before more code is written
   • Technical note: this updates DEVELOPMENT-PLAN.md and WO-INDEX.md before continuing
3. Change autonomy — switch between work-order, phase, major-decision, or full autonomous session mode.
   • Pros: better matches how hands-on you want the system to be
   • Cons: may create more check-ins or fewer opportunities to redirect early
   • Technical note: this updates the autonomy setting or session override in .vibeos/config.json
4. Redirect — work on something different by creating a new WO.
   • Pros: lets you respond to a new priority immediately
   • Cons: can interrupt the current roadmap and create dependency churn
   • Technical note: the new work is added to the plan as a new work order
5. Stop — save progress and end the build session.
   • Pros: safe pause point with no lost state
   • Cons: progress waits until you resume later
   • Technical note: session state is written to the build log and checkpoints are preserved if needed

I recommend Continue when the current phase is still aligned with your priorities and there are no blockers. If priorities changed, choose Adjust plan instead."

On user response:

• Continue: loop back to Step 1 with next eligible WO
• Adjust plan: ask user for changes, update DEVELOPMENT-PLAN.md and WO-INDEX.md, then loop back to Step 1
• Change autonomy: present the 3 negotiated levels plus the temporary full autonomous session override, save selection to .vibeos/config.json, then loop back to Step 1
• Redirect: create a new WO using the WO template from reference/governance/WO-TEMPLATE.md.ref, add to plan, then build it
• Stop: log session end to build-log.md, clear any active autonomous session override, mark .vibeos/session-state.json inactive with an ended_at timestamp, report final progress summary, exit

Log the check-in: [timestamp] check-in WO-NNN [user-choice]

11f. Loop or stop:

• If continuing: loop back to Step 1 with the next eligible WO
• If stopping: report final progress summary, clear any active autonomous session override, mark .vibeos/session-state.json inactive with ended_at, and save build state

Error Recovery

Agent Timeout

If an agent doesn't complete within its maxTurns:

1. Log the timeout
2. Notify user before retrying:

   "The [agent-name] agent didn't complete in time. Retrying with a simplified prompt to help it focus on the essentials..."

3. Retry once with a simplified prompt
4. If retry fails: escalate to user

Garbage Output

If an agent returns output that doesn't match the expected structure:

1. Log the raw output
2. Notify user before retrying:

   "The [agent-name] agent returned unexpected output. Retrying with explicit format requirements..."

3. Retry once with explicit output format reminder
4. If retry fails: escalate to user

Escalation Format

When escalating to user, always explain:

• What step was being executed
• What went wrong (in plain English)
• What was tried to fix it
• What options the user has (with consequences per Communication Contract)

Build Log

All events are appended to .vibeos/build-log.md. Format:

# Build Log

## WO-NNN: [title]

| Timestamp | Agent | Action | Result |
|---|---|---|---|
| [ISO-8601] | [agent] | [action] | [result summary] |

The build log is append-only — never overwrite previous entries.

Output Summary

Artifact	Path	Purpose
Build log	.vibeos/build-log.md	Append-only execution history
Session state	.vibeos/session-state.json	Tracks the active or most recent autonomous build session
Checkpoint	.vibeos/checkpoints/WO-NNN.json	Resume state (deleted after WO completes)
Agent marker	.vibeos/current-agent.txt	Current agent identity for hooks
Test files	{test_dir}/	TDD tests written by tester agent
Prompt assets	{prompt_paths}/	Behavior-governing prompt files updated by prompt-engineer when a WO changes agent behavior
Source files	{source_dirs}/	Implementation by backend/frontend agents
Updated WO	docs/planning/	Implementation notes and evidence