run-epic
Autonomously drains every open task in a single epic. Pulls ready tasks via the forge CLI, executes the work in-context using the matching discipline (fix-bug / new-feature / refactor), files newly-discovered work as follow-up tasks without stopping to ask, opens a PR per completed task via /create-pr, and repeats until the epic has zero ready/in-progress/pending tasks. Use when the user says `/run-epic E##`, "run epic autonomously", "finish all remaining tasks for epic X", or "drive epic X to completion".
- License 许可
- MIT
- 最近更新
- 2026-10-23
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- run-epic
- description
- Autonomously drains every open task in a single epic. Pulls ready tasks via the forge CLI, executes the work in-context using the matching discipline (fix-bug / new-feature / refactor), files newly-discovered work as follow-up tasks without stopping to ask, opens a PR per completed task via /create-pr, and repeats until the epic has zero ready/in-progress/pending tasks. Use when the user says `/run-epic E##`, "run epic autonomously", "finish all remaining tasks for epic X", or "drive epic X to completion".
02 资源文件 5
- 参考文档AUTONOMY.md6.5 KB
- 参考文档GUARDRAILS.md6.0 KB
- 参考文档LOOP.md4.4 KB
- 参考文档PARALLEL.md5.5 KB
- 参考文档TASK-CREATION.md4.4 KB
03 SKILL.md 正文
Run Epic
/run-epic takes a named epic and drains it to zero open tasks without human ping-pong between every task. The skill runs the work itself — it follows the discipline of /fix-bug, /new-feature, or /refactor inline in the same context rather than spawning them as sub-skills, which would lose the epic-level context (queued tasks, files already touched, follow-ups already filed).
The distinguishing capability is the self-feeding loop: when execution surfaces a bug, a missing prerequisite, or a task too coarse to finish in one go, /run-epic files a new forge task into the same epic and continues. The epic grows until reality stops surprising it; then it shrinks to zero. It works directly on the forge task registry (docs/tasks/registry.json) via forge task ... — the only sanctioned mutation path.
Index
| File or section | Read when… |
|---|---|
AUTONOMY.md |
Step 3 start — read it and hold its block for the rest of the run; with --parallel, paste the block verbatim into every spawned agent's prompt |
LOOP.md |
Step 3 — every iteration's body: pick, lock, classify, execute, verify, file follow-ups, PR |
GUARDRAILS.md |
Step 1 with --parallel (§5 spawn projection); any iteration failure (circuit breaker); an escalation gate (§3) or auto-file rate limit (§4); Step 4 halt-summary format |
TASK-CREATION.md |
The loop's file-follow-ups step — auto-file rules, task shapes, dependency wiring, limits |
PARALLEL.md |
--parallel only — per-iteration spawn, checkpoint discipline, reaping, guardrail interactions |
_shared/task-triage.md |
Before auto-filing any follow-up, and when the loop meets a backlog epic — "what breaks if this ships later?" |
_shared/orchestrated-development.md |
Step 1.6 — the one subagent-driven-development question; then every Execute step when the answer is yes |
_shared/model-routing.md |
--parallel spawn and the §5 cap probe — tier → (model, effort) table and documented environment caps |
_shared/report-format.md |
--parallel spawn — the four-field report every spawned agent returns |
The loop's execute step follows /fix-bug, /new-feature (its phase guide) or /refactor inline, and the PR step invokes /create-pr.
Invocation
/run-epic E37 [--max-iter=20] [--dry-run] [--no-pr] [--resume] [--parallel [--max-agents=3]]
E##— required; the single epic to drain.--max-iter=<n>— hard cap on iterations this run. Default: 50.--dry-run— list what would be done (next task, discipline, projected parallel groups); no mutations.--no-pr— skip/create-prper task;forge task completeand continue (batched-PR workflows).--resume— explicitly opt in to picking up interrupted (in_progress/pr_pending) tasks.--parallel— spawn background agents in isolated worktrees for scope-disjoint ready tasks while the main loop drives the primary task; each agent runs on a model and effort matched to its task's effort tier (skills/_shared/model-routing.md). See PARALLEL.md.--max-agents=<n>— ceiling on concurrent background agents. Default: 3.
Step 0: Map the surface
Read docs/code-map.md (auto-regenerated each SessionStart). For an autonomous run the map is non-negotiable — without per-file symbol info the loop re-discovers the same code structure every task. Missing → run /audit-code-map first. Refuse to start without it.
Step 1: Validate the epic
forge task ls --epic <E##> --json— confirm the epic exists.- Compute the work surface:
ready,in_progress,pr_pending,pendingcounts. - Refuse to start if all four are 0 — nothing to do.
- Refuse to start if
in_progress > 0without--resume— interrupted runs deserve a human glance before clobbering. - With
--parallel: probe the environment's subagent caps and compute the spawn projection (GUARDRAILS.md §5).--max-agentscaps a batch, not the run. - Print the drain plan (counts + cap, and the spawn projection under
--parallel) and confirm once with the user. In the same confirmation ask the subagent-driven development question (_shared/orchestrated-development.md; default yes) and record the answer in the session file.
Step 2: Session start
Generate a session ID and declare scope — the union of scope-dirs across the epic's tasks. Same conflict-scan protocol as any /reflect session.
Step 3: Run the loop
Read AUTONOMY.md and hold its block for the rest of the run. From here the human has left: the Step 1 confirmation was the last one, and an iteration that ends with "Shall I apply this?" burns without moving the epic. The block's stop list is this framework's gates, so it constrains the loop rather than loosening it.
The per-iteration body — pick, lock, classify, execute, verify, file follow-ups, PR — is defined in LOOP.md. With --parallel, each iteration also spawns background agents per PARALLEL.md.
The loop terminates when any of these is true:
forge task ls --epic E## --status ready,in_progress,pending --jsonreturns[]- Iteration count hits
--max-iter - Three consecutive iterations fail (GUARDRAILS.md)
- A task trips an escalation gate (GUARDRAILS.md — halts, not failures)
Step 4: Loop end
Print the halt summary (format in GUARDRAILS.md): completed, PRs opened, new tasks filed, remaining, reason for halt. On --max-iter or consecutive-failure, surface the next-task suggestion explicitly; on escalation, surface the specific blocker.
Hard rules
- Never silently mutate registry.json — all state changes via
forge task .... - Never skip
/create-prfailures — a PR failure halts on that task; don't move on with uncommitted work. - Never run forever —
--max-iteris the ceiling; consecutive-failure is the circuit breaker. - Never spawn into a refusal — with
--parallel, check spawn-budget headroom before each batch and degrade to serial rather than failing mid-epic (GUARDRAILS.md §5). - Auto-file only into the current epic or the backlog epic (E99), per
skills/_shared/task-triage.md— work that belongs to another roadmap epic is surfaced at end-of-run, not filed there. - Never resume
in_progresstasks without--resume.
Gotchas
- Single-epic by design. Two epics → run it twice. Cross-epic dependencies resolve via
pending → readytransitions, not by the skill. --resumeis opt-in for a reason. Auto-resumingin_progresstasks has clobbered uncommitted work in the past.- The classification ask (LOOP.md → Classify) is a sanctioned stop — named in AUTONOMY.md's stop list, so the autonomy block does not override it. Ambiguity means ambiguous after reading the body and scope, not unasked-for caution.
/create-prmay itself surface follow-up work (DRY hotspots, review findings) — those land in the same epic under the same auto-file rules.- Code-map staleness is the silent killer. A map older than the newest commit routes fixes to outdated locations. Do not relax the Step 0 gate.
Project-specific overrides: if SKILL.local.md exists in this directory, read it — it is consumer-owned, survives framework refresh, and wins on conflict. A sidecar that relaxes a gate defined above must state how to prove the gate is wrong in that case. Doctrine: rules/framework-vs-project-root.md.
04 同仓库更多 Skills
wizard
Generates an interactive bash wizard that walks a human through steps only they can perform — opens each URL, says what to click and copy, captures values (hidden entry for secrets), writes .env and GitHub secrets, confirms before irreversible actions. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
vet-idea
Vets an idea, decision, or plan BEFORE it is built. Runs a single model through five fixed adversarial advisor roles, a peer-review pass, and a chairman synthesis that emits a halt-capable GO / NO-GO / RECONSIDER verdict. Advisory and non-mutating — outputs a report, never writes task state. Use when an idea, feature, or costly hard-to-reverse decision is of uncertain worth and the question is whether to build it at all. NOT FOR settled work (bug fixes, approved features) or for shaping how to build it (the ISA Interview workflow).
triage-incident
Production incident triage — from "something is broken for users" to fixed, verified, and learned-from. Pulls the error signal (Sentry/logs/user report), reproduces before touching code, routes the fix through /fix-bug's prod fast path, and closes with a postmortem entry. Use when something is broken for users in production — an outage, data corruption, a Sentry spike, or a crash-rate alert. NOT FOR bugs found in development (use /fix-bug directly) or CI failures (use /diagnose-ci).
setup-review-bot
Configures a repo's AI code reviewers — the post-PR mention bot and the pre-push local reviewer — and writes the AGENTS.md the reviewers read. Interviews the user for what the reviewer should weight, then sets git config forge.reviewBot / forge.localReview and populates AGENTS.md at the project root. Use when a repo has no reviewer configured, when review findings are consistently off-target, or when onboarding a new project.
security-review
Portable security review for a feature, endpoint, or change before it ships. Orchestrates the existing OWASP review (@security-boss) and secrets scan (security_secrets validator), then adds the pass they miss — an explicit business-logic-flaw walkthrough (IDOR, race/TOCTOU, state-machine bypass, privilege escalation, price/quantity tampering). Advisory and non-mutating — produces a findings report; real findings are filed as tasks. Use when a change touching money, access control, or multi-step state is about to ship, or when the auth looks fine but the flow could be abused. NOT FOR SAST or dependency-CVE scanning (consumer CI owns those).
remember
Saves and retrieves project knowledge that persists across sessions — bug patterns, technical decisions, key facts, and code patterns. Use whenever the user wants to record a lesson learned, save a debugging insight, document a technical choice, note a convention, or search past memories.