--- name: Build Epic slug: build-epic category: DevOps description: Build Epic orchestrates a nine-step build cycle for one epic, from threat modeling and planning through TDD, verification, audit, commit, and release. Use it to resume or run release work with state tracked in YAML files. github: "https://github.com/danielvm-git/bigpowers/tree/main/skills/build-epic" language: Shell stars: 173 forks: 14 install: "npx degit https://github.com/danielvm-git/bigpowers/tree/main/skills/build-epic ~/.claude/skills/build-epic" installs_to: ~/.claude/skills/build-epic source_path: skills/build-epic/SKILL.md collection_size: 23 category_size: 1044 collection_url: "https://dirskills.com/collections/danielvm-git/bigpowers" added: 2026-09-07T05:22:10.224Z last_synced: 2026-09-07T05:22:10.224Z canonical_url: "https://dirskills.com/skills/build-epic" --- # Build Epic Build Epic orchestrates a nine-step build cycle for one epic, from threat modeling and planning through TDD, verification, audit, commit, and release. Use it to resume or run release work with state tracked in YAML files. **Install:** ```bash npx degit https://github.com/danielvm-git/bigpowers/tree/main/skills/build-epic ~/.claude/skills/build-epic ``` ## README # story: e20s05 # 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) | Step | Skill / action | |------|----------------| | 0 | `security-review` — threat-model epic scope → `specs/security/epics//THREAT_MODEL.md` | | 1 | `survey-context` — confirm epic + story | | 2 | `plan-work` — flesh out story `tasks[]` in `specs/epics/eNN-slug/epic.yaml` | | 3 | `kickoff-branch` — feature branch + clean baseline | | 4 | `develop-tdd` — red-green per task | | 5 | `verify-work` — UAT + mechanical gates | | 6 | `audit-code` — **non-optional gate** (pass/fail; fail → loop back to step 4) | | 7 | `commit-message` — Conventional Commits draft | | 8 | `release-branch` — PR or solo land (supports `--squash-state`) | | ## 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//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--.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`. 6. Run **only the current step** (resume mode) unless user asked for full auto-run. 7. After step verify passes, increment `epic_cycle.step` in `state.yaml` (or `bash scripts/bp-yaml-set.sh` if available). 8. 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: ```yaml stories: e01s01: status: done started_at: "2026-07-12T16:00:00-03:00" completed_at: "2026-07-12T18:45:00-03:00" ``` 9. **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 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 → 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--.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`. | Normal | --fast | Change | |--------|--------|--------| | Step 1 (survey-context) | 1+2 together | survey + plan in one invocation | | Step 2 (plan-work) | (absorbed into 1) | — | | Step 3 (kickoff-branch) | Step 2 | unchanged, sequential | | Step 4 (develop-tdd) | Step 3 | unchanged, sequential | | Step 5 (verify-work) | Step 4 | unchanged, sequential | | Step 6 (audit-code) | 5+6 together | audit + commit-message in one invocation | | Step 7 (commit-message) | (absorbed into 6) | — | | Step 8 (release-branch) | Step 7 | unchanged, sequential | **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`