Plan

Plan is the first stage of an epic: it turns each candidate into a reviewed, approved specification and decomposes that specification into the tasks the Implement stage executes. Its guarantee is that no delivery work starts from an unvetted plan — exactly one spec exists per candidate, approval is an explicit gated act, and decomposition hands off a validated task set.

Plan is where two product opinions become concrete: the spec tool is pluggable behind an adapter, and the loop’s most expensive model spend is deliberate — spec authoring runs at the frontier tier by default.

Spec tools

Every spec tool is driven through one adapter interface. Two ship:

• OpenSpec (default) — the reference implementation. Specs live as OpenSpec changes in the candidate’s working tree, task lists parse natively, and when a candidate merges, its spec deltas fold into the repository’s established specs.
• Generic markdown — for teams with bespoke document conventions: configure the artifact paths, validate with an agent-backed rubric, and use the generic decomposition step.

The adapter is chosen per project and pinned onto each spec at creation, so changing project configuration never retargets work in flight.

Authoring and revisions

Spec content lives on the candidate branch — the branch is the source of truth. The app keeps rendered snapshots for the viewer, the API, and the CLI, flags drift when the branch moves ahead (“Sync now” rather than silently stale), and re-syncs before any approval so nobody approves an outdated snapshot.

Authoring runs as a hosted agent session at the frontier tier, with the full provenance context injected: the proposal, its source report, the intent, and the relevant North Star documents. Validation failures loop back to authoring with structured issues attached.

Revisions are first-class:

• Request changes during review of the spec loops back to authoring as a new revision.
• Re-spec — when review escalates past a fix — reopens the spec as revision n+1 with the review findings attached as context. Prior revisions stay immutable, and per-artifact diffs between any two revisions remain available even after branches are deleted.

Approval

Approving a spec is a checkpoint (spec.approve) — approve-by-default out of the box, meaning it auto-approves after an objection window unless someone objects, and configurable like every gate. Approval re-validates first, then hands the candidate to decomposition.

Decomposition and handoff

The approved spec is decomposed into a task draft — natively by the spec tool where it can, otherwise by a generic decomposition session. Drafts are validated before anything is created: dependencies must form a cycle-free graph, every task must map to exactly one linked repository, and estimated tiers must be real tiers. Multi-repo epics add a human confirmation step before handoff by default.

The handoff materializes the tasks (TSK-n), records which spec revision produced them, and happens at most once per revision — a re-spec’s new handoff reconciles the prior revision’s tasks rather than duplicating them.

Working with Plan