Build Epic

Scope: one story. Called by orchestrate-project Phase 4. Not a replacement for orchestrate-project.

Orchestrates the build flow for a single epic: survey → plan tasks → kickoff → TDD → verify → audit → commit → release.

HARD GATE — Set specs/state.yaml active_flow: build_epic and active_epic: eNN before starting.

HARD GATE — Not on main/master before step 3 (kickoff-branch).

Nine steps (epic_cycle in state.yaml)

Process

1. Read specs/state.yaml, specs/execution-status.yaml, specs/release-plan.yaml, active specs/epics/eNN-slug/epic.yaml.
   • On story start (step 1): Write started_at ISO 8601 timestamp to execution-status.yaml under the story's key in the stories: section. The bp-timing.sh script already tracks skill-level timings — this is story-level.
2. Step 0 — Threat Model: Run security-review against the epic's scope (read from the epic capsule). Output specs/security/epics/<epic-id>/THREAT_MODEL.md with surface area, vulnerability categories, risk level, and mitigation guidance.
3. Assess Impact (Step 2): Before writing tasks, run assess-impact --lightweight on the proposed change. If the risk score exceeds 7, gate — require a grill-me session. Write the impact report to specs/IMPACT-<epic>-<story>.md. For net-new code with no existing dependents, skip.
4. BCP Tracking (Step 2): After plan-work completes, read the bcps: count (Business Complexity Points story size) from the epic capsule and carry it into state.yaml as epic_cycle.story_bcps = N.
5. BCP Plus (Step 2, optional): When the epic capsule carries a bcp_plus_breakdown (13-dimension sizing), also carry it into state.yaml as epic_cycle.bcp_plus. The breakdown maps each of the 13 dimensions to an integer count. NFR dimensions (11–13) that are N/A per the NFR Gate may be set to 0.
6. If epic_cycle.step missing, set to 1.
7. Run only the current step (resume mode) unless user asked for full auto-run.
8. After step verify passes, increment epic_cycle.step in state.yaml (or bash scripts/bp-yaml-set.sh if available).
9. On story complete, set execution-status.yaml story key to done; run bash scripts/sync-status-from-epics.sh.

   • On story complete (step 8): Write completed_at ISO 8601 timestamp to execution-status.yaml under the same story key. Format:

     stories:
       e01s01:
         status: done
         started_at: "2026-07-12T16:00:00-03:00"
         completed_at: "2026-07-12T18:45:00-03:00"

10. Traceability refresh: Before step 8 (release-branch), run bash scripts/trace-stories.sh to regenerate specs/traceability-matrix.json, specs/TRACEABILITY_LATEST.md, and the specs/codebase-wiki/ OKF bundle. Surface dark/orphan/stale findings for the just-built epic in your verify summary. If scripts/trace-stories.sh is missing or fails, note "trace skipped" and continue — trace failure must be visible, not silent (blocking is gate-trace's job, e38s06).

9b. OKF wiki refresh (e39s08): Before step 8, run maintain-wiki INGEST to refresh the OKF wiki bundle:

bash scripts/decompose-conventions.sh
bash scripts/generate-agent-guide.sh

If any script is missing or fails, note "OKF wiki refresh skipped" and continue. This is non-blocking — stale concepts are caught by LINT in verify-work Phase 3.

Step 6 — audit-code gate (non-optional)

After step 5 (verify-work) completes successfully, step 6 runs audit-code automatically in --gate mode:

1. Run audit: Invoke audit-code --gate on the complete diff for this story.
2. Pass (exit 0): All checklist sections pass → run bash scripts/lib/assert-epic-gate.sh advance to mechanically confirm the audit pass, then advance to step 7 (commit-message). Record epic_cycle.audit_result: pass in state.yaml.
3. Fail (exit 1): One or more checklist sections fail → reset epic_cycle.current_step to 4 (develop-tdd) and add the failing section IDs to completed_steps as "1,2,3,4,5,6(fail: ...)". Record epic_cycle.audit_result: fail in state.yaml. Do NOT advance past step 6 until audit passes.
4. Audit artifact: Full audit report saved to specs/verifications/AUDIT-<epic>-<story>.md regardless of pass/fail, for reviewer traceability.
5. Enforce F.I.R.S.T: After audit-code passes, run enforce-first --quick on new/modified tests. Append F.I.R.S.T violations (if any) to the audit report. Failing F.I.R.S.T criteria trigger the same loop-back to step 4.

--fast mode

Coalesces read-and-report steps to reduce token overhead. Activate with build-epic --fast.

Total invocations: 8 → 6 per story.

Rules:

• Steps 3/4/5/8 (kickoff, develop, verify, release) still run sequentially — they require user interaction or branch state.
• --fast does NOT skip any checklist items; it only coalesces steps that are pure read-and-report.
• Record epic_cycle.fast_mode: true in state.yaml when this flag is active.

Handoff

Write handoff.next_skill and handoff.context in state.yaml when pausing mid-epic.

Verify

→ verify: test -f specs/state.yaml && test -f specs/execution-status.yaml && test -f specs/release-plan.yaml && test -d skills/assess-impact && test -d skills/audit-code && test -d skills/security-review