# Build Epic

> Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one epic capsule; updates status via bp-yaml-set or direct edit. Resume mode runs one step per invocation. Use instead of ad-hoc execute-plan for release work.

- **Type:** Skill
- **Install:** `agentstack add skill-danielvm-git-bigpowers-build-epic`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [danielvm-git](https://agentstack.voostack.com/s/danielvm-git)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [danielvm-git](https://github.com/danielvm-git)
- **Source:** https://github.com/danielvm-git/bigpowers/tree/main/.gemini/extensions/bigpowers/skills/build-epic
- **Website:** https://github.com/danielvm-git/bigpowers

## Install

```sh
agentstack add skill-danielvm-git-bigpowers-build-epic
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`.
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. 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`.

### 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: `grep -q 'active_flow: build_epic' specs/state.yaml && test -f specs/epics/*/epic.yaml`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [danielvm-git](https://github.com/danielvm-git)
- **Source:** [danielvm-git/bigpowers](https://github.com/danielvm-git/bigpowers)
- **License:** MIT
- **Homepage:** https://github.com/danielvm-git/bigpowers

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-danielvm-git-bigpowers-build-epic
- Seller: https://agentstack.voostack.com/s/danielvm-git
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.