7.2 — Plan & sprints API reference

The Plan & Sprints feature sits between AC approval (Section 3) and the Kanban Tracker (Section 6). It turns a flat list of approved acceptance criteria into an ordered sequence of themed sprints — respecting dependencies — and then gates your agent's work queue so it only picks up ACs whose prerequisites are satisfied.

For the practical walkthrough, see 7.1 — User guide. This page is the reference: object shapes, API routes, validation rules, and limitations.

What it does

Before sprints, the MCP next-ready endpoint returned acceptance criteria in naive creation order. Two consequences:

1. The agent could pick un-buildable ACs. "User can edit profile" might come back before "User can sign in." The agent would try, fail, and the AC would land in blocked for an artificial reason.
2. No structural narrative. All feature ACs sat in one bucket. You had no way to see "we're building auth in Sprint 1, billing in Sprint 2."

The sprint planner fixes both. It analyzes dependencies across your ACs, topologically sorts them, and groups them into themed sprints. The agent's next-ready queue then only surfaces ACs whose dependencies are satisfied and that belong to the active sprint.

Tier gating

On free and starter, your agent works ACs in approval order without sprint gating.

How "active sprint" is computed

The active sprint is not stored — it's derived on each lookup:

Active sprint = the first sprint by position (excluding Backlog) that has at least one AC with status != 'passed'.

If all sprints are complete, there's no active sprint and next-ready returns null (project complete).

Strict re-activation: if a new AC is assigned to a sprint that was previously complete, that sprint becomes active again the moment the AC is non-passed. The active sprint can move backward. This is intentional — you can't accidentally "skip" a sprint by editing later ones.

The Backlog sprint

Every project has an auto-created Backlog sprint that holds ACs that haven't been planned yet (or that you've added since the last plan). It can't be renamed, deleted, or reordered. ACs flow into and out of it freely.

How next-ready gates work

When your agent asks for the next ready criterion:

1. Bootstrap first. If there are any unfinished bootstrap ACs (system foundation work like auth scaffolding), the agent gets one of those.
2. No sprints yet? Falls back to the pre-sprint behavior: oldest ready feature AC.
3. Sprints exist:
   • Look up the active sprint. If none, return null (project complete).
   • Pull all ready ACs in the active sprint, ordered by position.
   • For each candidate, check that every hard prerequisite has status = 'passed'. Return the first that passes.

Hard vs soft dependencies. Each edge in the dependency graph is either:

• Hard (is_hard: true) — "B literally can't be built before A is passed" (e.g. needs the entity / route / column / permission A creates). Hard edges drive both topo-sort and next-ready gating.
• Soft (is_hard: false) — "B is awkward without A but technically possible." Soft edges are advisory; they're used as clustering hints by the planner but not enforced by next-ready.

API surface

All routes live under /api/projects/[projectId]/. All require an authenticated session or API key with project ownership.

Reads

Writes (Pro+)

Both endpoints return immediately; the actual work runs as a background task. Subscribe to progress or poll for status the same way you would for any other generation task.

Mutations

The Backlog sprint is immutable — PATCH/DELETE on it return 422 backlog_immutable.

Hard-dep validation

On move-ac: every hard prerequisite of the AC must be in a sprint with position <= dest.position. Every hard dependent must be in a sprint with position >= dest.position. Otherwise: 422 hard_dep_violation with a detail string explaining which dep would be violated.

On reorder: for every hard edge, the prereq's new sprint position must be <= the dependent's new sprint position. Otherwise 422 hard_dep_violation.

Object shapes

Sprint

{
  "id": "uuid",
  "project_id": "uuid",
  "position": 1,
  "title": "Auth & Onboarding",
  "theme": "Get users signed in and into their first session",
  "status": "planned",
  "created_at": "2026-05-10T...",
  "updated_at": "2026-05-10T..."
}

• position: sprint's display order. Real sprints get 1, 2, 3, …
• The Backlog sprint sits at position = 99999 (sentinel).
• status is planned initially. UI v1 derives "complete" from AC counts.

Dependency edge

{
  "id": "uuid",
  "ac_id": "uuid",
  "depends_on_ac_id": "uuid",
  "is_hard": true,
  "reason": "Profile editing requires the User entity that 'User can sign in' creates",
  "derivation_source": "llm"
}

• Edge meaning: ac_id depends on depends_on_ac_id (the latter is the prereq).
• derivation_source is llm for auto-generated edges (wiped + regenerated on each analyzer run) or user_added (preserved across re-runs, schema supports it but no UI in v1).

AC sprint assignment

Every acceptance criterion gains an optional sprint_id field. null means un-sprinted (legacy or new since last plan). Bootstrap ACs are never assigned a sprint — they're filtered out of the planner.

Backwards compatibility

• Projects without a sprint plan: next-ready falls back to pre-sprint behavior. Track tab renders flat (no per-sprint sections). Plan tab shows the empty-state CTA.
• Projects with a partial plan (sprints exist but some feature ACs have sprint_id = NULL): un-sprinted ACs are excluded from next-ready results. They surface in the Backlog sprint section.
• Bootstrap unaffected: bootstrap ACs are still gated by the existing bootstrap rule. Sprint 0 in the UI is purely visual.
• Existing API contracts: the next-ready response shape is unchanged. Existing MCP tools (claim, submit_for_review, etc.) require zero changes.

v1 limitations

• No drag-and-drop UI for moving ACs between sprints or reordering sprints. The move-ac and reorder routes work; no UI invokes them yet.
• No user-authored dependency edges UI. Schema supports derivation_source = 'user_added'; writer/UI is v2.
• No "active sprint override" — you can't manually pin a different sprint than the computed-active.
• No epics (two-level hierarchy) for huge projects.
• No graphical DAG view of the dependency graph. Inline badges and a side-sheet only.
• No sprint dates / deadlines / capacity planning.
• No manual sprint creation. Only the planner creates sprints.

Where to go next

• Step-by-step → 7.1 — User guide
• Kanban tracker reference → 6.2 — API reference
• General API conventions → 4.1 — API overview