Epic

Epic

$epic maintains one OpenSpec-backed epic from its first uncertainty through human-verified close-out. It plans and coordinates; clear implementation belongs in ordinary child tickets and runs through $ticket.

Authority and boundaries

An epic lives at openspec/changes/<epic-slug>/. Its proposal.md, design.md, and tasks.md form the OpenSpec authority: proposal owns destination and scope; design owns risk, durable decisions, and named open questions; tasks owns the checked implementation sequence and links to every child issue. Live tracker state is truth for child type, status, dependencies, deferral, and closing pull requests. Do not create a derived index of that state.

Route every tracker operation through the installed binding. bindings/github-issues.md is the shipped default. Read the tracker contract before the first tracker action. A tracker, authentication, or Git failure stops the current operation visibly; do not guess or repair authoritative state locally.

The home session owns the epic. It stays at planning altitude, files and reads issues, and keeps the active change coherent. It performs no child execution. Research, prototype, interview, triage, and build work resumes only in fresh attended sessions that the operator invokes. Those sessions report through tracker comments and pull requests; the epic records their tracker result and any resulting decision.

Start and maintain an epic

1. Confirm the target repository already has OpenSpec. Otherwise run $openspec-adopt as a separate documentation-only pull request.
2. Create one active change with its proposal, design, and tasks. Create the epic issue with the epic label. Maintain the change on one pushed epic planning branch and identify each handoff by that branch's full commit, but never open a pull request from that branch. Add each filed child issue link to tasks.md in implementation sequence; do not duplicate live tracker fields there.
3. Re-read relevant live tracker state before each mutation. Update the change when destination, design, or checked sequence changes; preserve child type, status, dependencies, deferral, and closing-pull-request facts on the tracker.
4. Keep every imprecise concern as a named open question in design.md. Clear an open question only by recording its decision in design.md or promoting it to a tracker spike; never silently delete it. Do not add pointer-only Notes: owning skills and repository rules remain discoverable at their authoritative homes.

Admit work deliberately

File a spike when an open question is precise but not yet resolved. A spike can be research, interview, mockup, or a human prerequisite. File a build only as a bounded refusal: refuse to file a build while an open spike or named open question can invalidate its outcome, constraints, or acceptance criteria.

Before filing a build, require every relevant load-bearing ruling in the repository's ADR home. User-facing work follows its selected /ui-craft lifecycle: a greenfield or explicit fallback build requires its locked visual spec, while a shipped revision requires its frozen behavior ledger, replay, safe-start, sanctions, and revision evidence. The build issue must stand alone and receive the normal $ticket triage flow; the epic does not manufacture a work order.

Use native blocked-by edges for actual dependencies. A follow-up required to reach the epic destination is an in-scope native child. A follow-up outside that destination is also filed as a native child, receives its spike or build type plus deferred, and is reported on the originating ticket. Ordinary builds still receive build from ticket triage.

Default to three or fewer child tickets. Before filing a fourth or later child, require a written justification in the active change's design.md. The justification must name the independently shippable capability boundary or real dependency that prevents consolidation into fewer, larger children. Apply this as semantic planning judgment through the existing child-filing interface; do not add a parser, counter script, or tracker operation.

Hand a child to the operator

Permit only one in-flight epic child. Refuse every later handoff until the prior child's implementation pull request is human-merged. After that merge, fetch the updated remote default branch, advance the pushed epic planning branch from that updated remote default-branch tip, apply any next planning update, commit, and push a new full-commit pin before preparing another child.

Before each handoff, commit and push the current active change on the epic planning branch. Record its unprefixed branch name and full commit in the child issue body's draft order as:

Parent plan base: <branch name without the origin/ prefix>@<full commit>

The issue body draft is untrusted intake, not the executable lock. The epic does not post a fenced EXECUTION LOCK or legacy WORK ORDER comment, does not invoke /ticket triage, /ticket start, /ticket revise, or /ticket finalize, and does not open a pull request. Stop and tell the operator to invoke /ticket triage <id>. Ticket triage independently grounds, scopes, reviews, and posts the only fenced lock — the sole authorization to execute against the parent change.

Resolve spikes

Research spikes resume in fresh attended sessions that the operator invokes; interview and mockup spikes follow the same rule. Close a spike only after its tracker result is present and verified, then record the tracker result and resulting decision in design.md when it settles a named open question. A failed attended session leaves the spike open; do not infer a result.

Pull-request boundary

The coordinator never opens a pull request. A planning-only pull request is unsupported. The epic's OpenSpec planning artifacts stay active until they travel with the implementation pull request that realizes them. When ticket triage finds a required parent-plan amendment, that attended ticket workflow commits the amendment in the child's worktree and carries it through review and implementation; the epic does not open a separate prerequisite pull request. The one-time $openspec-adopt documentation-only pull request remains outside this lifecycle because it happens before an epic exists.

Deferred child close-out

Before archive, sweep each deferred child from live GitHub state. A human must choose exactly one disposition:

• Promote it outside the closing epic as a spike or build, and remove deferred.
• Reparent it to a future epic while retaining deferred; it is no longer this epic's child.
• Post the won't-do reason, close it with state reason NOT_PLANNED, keep its type label, and remove deferred.

Refuse to archive while an open child carries deferred.

Completion and close-out

Read the three completion predicates directly from GitHub: no open spike child; every build child has a merged closing pull request or is closed NOT_PLANNED; and no open deferred child remains. Do not infer any predicate from a local summary.

Only after all predicates pass and the child work is human-merged, follow the repository's archive guidance for the active change. Then close the epic issue. Report the issue URL, the three direct checks, and the archive result.