epic

Imported from A2Y-D5L/agentskills (skills/epic/SKILL.md). Install upstream with npx skills add A2Y-D5L/agentskills --skill epic. Copyright stays with the author.

epic — subcommand-driven epic implementation workflow

This skill is a dispatcher. It routes /epic <subcommand> [key=value …] to a sub-workflow file. Do not improvise the workflow — read the routed reference and follow it. The references encode hard-won discipline that agents skip by default (findings ledgers, premise-verification, anchored verdicts, shift-left gating).

Step 1 — parse the invocation

The text after /epic is <subcommand> [positional] [key=value …] — e.g. run <epic-id> max-minutes=90, or the config shorthand <user|project> config …. Normalize it (applies defaults; emits target and config_scope) by running:

bash ~/.claude/skills/epic/scripts/epic-args.sh "<the args>"

It prints SUBCOMMAND=… plus every option with its default. Read those values.

Step 2 — route (conditional execution)

Read the file with the Read tool (do not @-link it). Then execute its steps, honoring the parsed options. implement calls review at each phase gate and learn-lessons at the end; run is the autonomous, resumable, bounded wrapper around implement (one bounded step per wake, checkpoint, re-arm) — drive those by reading their references too. Re-invoking /epic run <epic-id> always RESUMES from the on-disk ledger, so it survives context compaction and session restarts.

Required background (read when the subcommand needs them)

• REQUIRED for implement: superpowers:executing-plans, superpowers:test-driven-development, superpowers:using-git-worktrees.
• REQUIRED for review: dual-independent-adversarial-review, orchestrating-codex-headless-reviews.
• REQUIRED for learn-lessons: superpowers:writing-skills, superpowers:verification-before-completion.

Scripts (deterministic helpers — prefer them over hand-rolling)

• scripts/epic-paths.sh <id> [init] — resolve (and scaffold) the central epic state dir ~/.agents/epic/projects/<project-id>/epics/<id>/; project id is stable across worktrees/clones. ALL epic state lives here, not in the repo.
• scripts/epic-config.sh paths|get <user\|project>|init — locate/scaffold the user config ~/.agents/epic/config.json and project config <root>/.epic.json.
• scripts/epic-jsonget.sh <file> <dotted.key> — read one config value (jq, else a grep fallback). Used to layer config into defaults and honor project_id.
• scripts/epic-args.sh — parse subcommand + positional + key=value, applying the effective-default layering: built-in < user config < project config < CLI.
• scripts/run-bounds.sh <id> step|unlock|done|stop|status [max-it] [max-min] — durable bound tracker + concurrency lock for run; emits DECISION=CONTINUE|STOP (reason=locked when another wake holds the lock) and poll_timeout_s. A CONTINUE step holds the lock until you unlock. Survives restarts (state on disk).
• scripts/epic-list.sh [--running-latest] — list this project's epics from their run.state; --running-latest prints the newest RUNNING id (for resume).
• scripts/review-poll.sh <timeout_s> <file…> — poll until EVERY reviewer file has an anchored ^VERDICT: line; warns on SHIP/BLOCK disagreement.
• scripts/codex-review.sh <brief> <out> — one headless Codex review (preflight
  • MCP disabled); exits nonzero with "NO VERDICT" if it didn't actually review.
• scripts/lint-gate.sh — mechanical pre-review checks (.epic/lint-rules.sh).

Red flags — STOP, you are skipping the discipline

• Remediating a finding before all reviewers' verdicts have landed.
• "Fixing" a finding without checking its premise is true (e.g. a "deleted route" — git log it first; reviewers hallucinate and contradict each other).
• Re-litigating a finding a prior round already decided — feed the findings ledger back into the brief instead.
• Using a same-provider reviewer as a gate (e.g. Claude reviewing a Claude implementer) — BARRED. The gate must be cross-provider (Claude impl → Codex gate). If the cross-provider reviewer can't run, substitute another NON-same-provider reviewer or defer/block; NEVER drop to a same-provider gate. See references/review.md.
• Re-running an expensive review for a class of bug a lint-gate.sh rule could catch in seconds, or fixing one instance of a class without sweeping for the rest.
• run: doing work without first checking run-bounds.sh (DECISION=STOP means stop), re-arming the loop after STOP/DONE, holding one turn for hours instead of checkpointing + re-arming each step, or advancing past an un-SHIP'd gate because a bound was hit (record it blocked, stop). Storing epic state in the repo or in a hand-rolled location instead of the central epic-paths.sh store (run-bounds.sh + <BASE>/state.md) — a divergent path breaks cross-session resume.

The "why" behind each rule is in references/lessons.md.