Lifecycles

SpecForge operates as three interconnected cycles. Each cycle has a clear input, a quality gate, and a feedback path. Nothing advances without approval.

The Three Cycles

Planning Cycle — From Idea to Executable Spec

The planning cycle 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. The planning corridor (planning ↔ specifying ↔ validating) handles state transitions automatically based on what operations you perform — create structure, link dependencies, or run quality checks.

4. Review — The Planning Review gate 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 cycle 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.

Implementation Cycle — Agents Execute in Dependency Order

The implementation cycle 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.

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. 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 advances to ready_for_review.

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 reverts to 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 pause: Work sessions can be paused and resumed. Progress is preserved. A different agent (or the same agent in a new session) can pick up where it left off. This handles context window resets, multi-day implementations, and manual review checkpoints.

💡 The implementation cycle 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.

Review Cycle — Quality Assurance Before Delivery

The review cycle validates the implemented work against the original specification. Two gates guard quality — Planning Review before code (covered above) and Implementation Review after code. Both produce scores, both must pass. Nothing ships without clearance.

Input: A specification in ready_for_review state (all tickets done).

What happens:

1. Trigger — The review can be triggered manually via CLI or MCP, or automatically when all tickets complete.

2. Evaluate — The Implementation Review gate checks five dimensions: step completion, acceptance criteria satisfaction, file delivery, git evidence, and test results. Each dimension is independently toggleable in your project’s quality standards.

3. Score — Each dimension produces a score from 0 to 100. The overall score must meet the threshold.

4. Verdict — Pass or fail.

On pass: The specification advances to reviewed, then to completed upon final confirmation. The work is done.

On fail: The gate returns a detailed findings report. Which tickets have incomplete steps. Which acceptance criteria weren’t met. Which files were expected but not delivered. Which tickets are missing test evidence. The specification stays in in_review — you address the findings (reopen specific tickets, fix the issues, re-run the review) without starting over.

ℹ️ maxReviewAttempts (default: 3) limits retries before requiring manual intervention. This prevents infinite loops on specifications with fundamental issues that automated review can’t resolve.

How the Cycles Connect

The three cycles aren’t independent — they form a pipeline with gates between each stage:

Define → Decompose → Refine → [Gate 1: Planning Review ≥ 80] → Execute → Cascade → [Gate 2: Implementation Review ≥ 80] → Deliver

Gate 1 (Planning Review) sits between the Planning Cycle and the Implementation Cycle. It answers: “Is this plan good enough to spend tokens implementing?”

Gate 2 (Implementation Review) sits between the Implementation Cycle and delivery. It answers: “Did the agents actually build what the spec asked for?”

Fail at Gate 1, and you go back to planning — cheap, no code wasted. Fail at Gate 2, and you go back to specific tickets — targeted fixes, not a full reimplementation.

This is why two gates exist instead of one. A single post-implementation review would catch everything eventually — but only after agents already spent time and tokens implementing a flawed plan. Gate 1 catches structural problems before any code is written. Gate 2 catches execution problems after.

The Planning Corridor

The planning phase has its own internal state machine worth understanding. Three states — planning, specifying, validating — form a corridor that transitions automatically based on what you’re doing:

• Structural operations (creating epics, creating tickets, deleting) → moves to planning
• Linking operations (adding dependencies, linking blueprints) → moves to specifying
• Evaluation operations (requesting reports, running quality checks) → moves to validating

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

The corridor is designed for iterative refinement. Create some tickets, link some dependencies, check coverage, create more tickets, recheck — the state follows you.

Once the Planning Review passes, the specification exits the corridor and enters ready. From there, it can only move forward to implementation. To re-enter the planning corridor, 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 → gate 2 → done. But real projects aren’t always linear. Here’s what happens when things go wrong:

Planning Review Fails

The specification stays in the planning corridor. 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 reverts to pending 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.

Implementation Review Fails

The specification stays in in_review. The gate identifies which tickets have issues. You reopen those specific tickets, fix them, and re-run the review. Tickets that passed aren’t affected.

Specification Needs Reopening

A completed or reviewed 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 two gates in detail
• Work Sessions — How agents execute tickets
• Specification States — Full state machine reference