Lifecycles

SpecForge operates as two interconnected lifecycles — planning and work. Each has a clear input, a quality gate, and a feedback path. Nothing advances without clearance.

The Two Lifecycles

Planning Lifecycle — From Idea to Executable Spec

The planning lifecycle transforms a natural language description into a structured execution plan. You describe what you want. The engine (through your coding agent via MCP) decomposes it into epics, tickets, and a dependency graph. The Planning Review gate validates everything before a single line of code is written.

Input: A specification with a title and description.

What happens:

1. Define — You create a specification. Describe the feature, its goals, constraints, and technical context. This can happen in the webapp or through the CLI.

2. Decompose — Your coding agent (via MCP tools) breaks the description into epics and tickets. Each ticket gets implementation steps, acceptance criteria, and file expectations. Dependencies are mapped into a directed acyclic graph.

3. Refine — You (or the agent) iterate on the plan. Add missing tickets, adjust dependencies, link blueprints, clarify acceptance criteria. This is where the specification gets sharp. Throughout refinement the specification stays in the single planning state; the planning session advances through its own 7-phase machine as you create structure, link dependencies, and run quality checks.

4. Review — The Planning Review gate (inside complete_planning_session) evaluates the specification across five dimensions: completeness, dependencies, coverage, ticket quality, and acceptance criteria. Each produces a score. The overall score must meet the threshold (default: 80).

On pass: The specification advances to ready. Implementation can begin.

On fail: The gate returns specific findings — which tickets lack acceptance criteria, which dependencies are circular, which requirements from the description aren’t covered by any ticket. You go back to Refine with actionable feedback. Not square one — targeted fixes.

💡 The planning lifecycle is where the most important work happens. A well-planned specification with clear tickets, correct dependencies, and linked blueprints produces clean implementations. A hastily planned specification produces rework. The Planning Review exists to catch this before you spend tokens on implementation.

Work Lifecycle — Agents Execute in Dependency Order

The work lifecycle is where code gets written. Agents pick up ready tickets, implement them, and upon completion automatically unlock dependent tickets. The dependency graph drives everything — no manual coordination required. Every ticket carries its own quality gate: a per-ticket assay runs inside complete_work_session, so quality is checked as each ticket lands rather than in one bulk review at the end.

Input: A specification in ready state with tickets in ready status.

What happens:

1. Claim — The agent (or orchestrator in Agent Teams) calls get_next_actionable_tickets to find tickets with all dependencies satisfied. These are the current wave — work that can safely happen in parallel.

2. Execute — The agent opens a work session on a ticket. It receives the full implementation context: steps, acceptance criteria, file expectations, dependency outputs, and linked blueprints. It writes code, runs tests, reports progress.

3. Complete — The agent closes the work session with a summary and validation results. complete_work_session runs the per-ticket assay gate — scoring step completion, acceptance criteria, file delivery, git evidence, and tests. When the assay passes, the ticket transitions to done.

4. Cascade — Completing a ticket triggers recalculation. Every ticket that depended on the completed one is re-evaluated. If all its dependencies are now done, it transitions from pending to ready — joining the next wave. When all tickets in an epic are done, the epic auto-completes. When all epics complete, the specification is marked done.

On block: If an agent discovers an external blocker during implementation (something not captured in the original plan), it reports a block reason. The ticket’s status becomes blocked — a first-class state, not the same as pending. The block is visible in the dashboard and in get_blocked_tickets. The agent or a human resolves the blocker, clears it, and the ticket becomes workable again.

On interruption: If an agent session ends, the work session stays open and progress is preserved. A different agent (or the same agent in a new session) can continue by calling start_work_session on the same ticket. This handles context window resets, multi-day implementations, and manual checkpoints.

Human resolution: A completed work session can be resolved by a human reviewer. The verdict is recorded as a WorkSessionResolution on that ticket’s session — an approval or a request for changes scoped to the ticket. This is per-ticket, not a spec-level gate: the whole specification never passes through a separate review lifecycle after implementation.

💡 The work lifecycle is self-driving once started. The orchestrator doesn’t need to manually sequence work — the dependency graph produces waves automatically. Each completed ticket potentially unlocks the next batch of parallel work. The human’s role is monitoring, not coordinating.

How the Lifecycles Connect

The two lifecycles aren’t independent — they form a pipeline with gates between stages:

Define → Decompose → Refine → [Gate 1: Planning Review ≥ 80] → Execute → [Gate 2: per-ticket assay on each complete_work_session] → Cascade → Done

Gate 1 (Planning Review) sits between the planning lifecycle and the work lifecycle. It answers: “Is this plan good enough to spend tokens implementing?” It runs once, at the specification level, inside complete_planning_session.

Gate 2 (the per-ticket assay) sits inside every work session, at the moment a ticket is completed. It answers: “Did the agent actually build what this ticket asked for?” It runs per ticket, inside complete_work_session — not as a spec-level review after all tickets are done.

Fail at Gate 1, and you go back to planning — cheap, no code wasted. Fail the assay on a ticket, and only that ticket bounces back — targeted fixes, not a full reimplementation.

This is why two gates exist instead of one. A single end-of-run review would catch everything eventually — but only after agents already spent time and tokens implementing a flawed plan or piling completed tickets on top of a broken one. Gate 1 catches structural problems before any code is written. The per-ticket assay catches execution problems the moment each ticket lands.

The Planning Phase

The planning phase has its own internal state machine worth understanding — but it runs on the planning session, not on the specification. Throughout planning the specification sits in a single planning state. The session advances through seven phases:

planning_spec → epic_decomposition → epic_expansion → ticket_decomposition → ticket_expansion → cross_validation → planned

You don’t manage these phase transitions. SpecForge tracks the nature of your operations — creating structure, linking dependencies, running quality checks — and advances the session’s phase accordingly. You can freely alternate between creating structure, linking dependencies, and checking quality without worrying about state management.

This is designed for iterative refinement. Create some tickets, link some dependencies, check coverage, create more tickets, recheck — the session follows you while the specification stays in planning.

Once the Planning Review passes, the specification leaves planning and enters ready. From there, it can only move forward to implementation. To re-open planning, you must explicitly reopen the specification — a deliberate action that acknowledges the plan needs rework.

Failure Paths

The happy path is linear: plan → gate 1 → implement (each ticket passes its assay) → done. But real projects aren’t always linear. Here’s what happens when things go wrong:

Planning Review Fails

The specification stays in planning. The gate returns specific findings. You fix them (add missing acceptance criteria, resolve circular dependencies, add coverage for gaps) and re-run the review. No state is lost — all work done so far is preserved.

Ticket Gets Blocked During Implementation

The ticket moves to blocked (a first-class status) with a block reason. Other tickets continue — the block only affects this ticket and its downstream dependents. The block is visible in the dashboard. Resolve the blocker, clear the reason, and the ticket recalculates its state.

A Ticket Fails Its Assay Gate

When complete_work_session runs the per-ticket assay and the ticket falls short — steps left incomplete, acceptance criteria unmet, expected files missing, or test evidence absent — the assay returns findings for that ticket and it does not advance to done. You address the findings on that ticket alone and complete the session again. Tickets that already passed aren’t affected.

Specification Needs Reopening

A done specification can be reopened with reopen_specification. This moves it back to in_progress, allowing you to reset specific tickets and re-implement them. Use this when post-deployment testing reveals issues that need to be addressed within the specification’s scope.

⚠️ Reopening is a deliberate action. Active work sessions must be completed or reset first. The specification doesn’t silently regress — you’re making a conscious decision to revisit completed work.

Where Am I?

A practical guide to “I’m looking at my specification and don’t know what to do next”:

See Also

• Specifications — The planning unit with full anatomy
• Epics & Tickets — The execution units within a specification
• Quality Gates — The Planning Review and per-ticket assay gates in detail
• Work Sessions — How agents execute tickets
• Specification States — Full state machine reference