First Specification

Create a specification, see SpecForge decompose it into epics and tickets, and prepare for implementation.

A specification is the highest-level unit of work in SpecForge. You describe what you want to build in natural language. SpecForge analyzes it, decomposes it into epics (logical groupings) and tickets (atomic implementation tasks), and builds a dependency graph so work executes in the right order.

You write the intent. SpecForge produces the plan.

Try It in 60 Seconds

Don’t have a project yet? Use this example to see SpecForge in action immediately.

Step 1 — Bootstrap the spec, then plan

Bootstrap the specification yourself with the CLI — this is the human step:

specforge init

Then hand the intent to your coding agent:

Plan the "User Authentication System" specification:

Implement email/password authentication with JWT tokens, refresh token
rotation, password reset via email, rate limiting on login attempts, and
account lockout after 5 failed attempts. Use bcrypt for hashing. Include
middleware for protected routes.

The agent calls start_planning_session and begins planning. In about 30 seconds, you’ll have:

• 4 epics — Core Authentication, Token Management, Password Reset Flow, Rate Limiting & Lockout
• 13 tickets — Each with implementation steps, acceptance criteria, and expected files
• A dependency graph — Tickets linked in the right execution order

Step 2 — Validate with Planning Review

The specification exists, but is it ready for implementation? Tell your agent:

Run the planning review for this specification

The Planning Review is a quality gate that evaluates the specification BEFORE any code is written. It checks:

• Completeness — Do all tickets have steps and acceptance criteria?
• Dependencies — Is the graph valid? No circular references?
• Coverage — Does the decomposition cover everything in the description?
• Ticket Quality — Are tickets atomic and implementable, not vague epics disguised as tickets?
• Acceptance Criteria — Are criteria specific and verifiable, not “should work well”?

If the review passes (score ≥ 80), the specification is ready. If not, you get specific findings — “ticket X has no acceptance criteria”, “the description mentions rate limiting but no ticket addresses it” — and you refine until it passes.

This is the first control loop: the AI decomposes, the quality gate validates, you refine. The spec gets better with each iteration. No code is written until the plan is solid.

Step 3 — Implement

Once Planning Review passes, you have two paths:

• Manual — Pick up tickets yourself, use MCP tools to track progress
• Autonomous — Let your coding agent implement the entire specification with Autonomous Implementation

The quality gate validated the plan. Now the dependency graph ensures agents implement in the right order. And each ticket’s assay gate validates the code as the work lands — the second control loop, running per ticket inside complete_work_session.

Quality in, quality out. The spec drives everything.

Now try it with YOUR project. You don’t need to get it perfect on the first attempt — the Planning Review will tell you exactly what’s missing. Provide your intent, let the AI decompose, run the review, and refine based on the findings. Each iteration gets you closer to a spec that agents can implement correctly the first time.

Create a Specification from the Dashboard

1. Open your project in the SpecForge dashboard
2. Click New Specification
3. Enter a title — a concise name for the feature or system you’re building
4. Write a description — the more detail you provide, the better the decomposition

For example:

• Title: User Authentication System
• Description: Implement email/password authentication with JWT tokens, refresh token rotation, password reset via email, rate limiting on login attempts, and account lockout after 5 failed attempts. Use bcrypt for hashing. Include middleware for protected routes.

Click Create and SpecForge begins planning.

Bootstrap a Specification from the CLI

If you’re already in the terminal with your coding agent, you don’t need to switch to the browser. Bootstrap the spec yourself, then let the agent plan it:

specforge init

Then hand the intent to your agent:

Plan the "User Authentication System" specification: Implement email/password
authentication with JWT tokens, refresh token rotation, password reset via
email, rate limiting on login attempts, and account lockout after 5 failed
attempts.

The agent calls the start_planning_session MCP tool and begins planning. Everything you can do in the webapp, you can do from the terminal.

How Decomposition Works

After you create a specification, the planning phase runs through your coding agent via MCP tools:

1. Analysis — Your description is parsed for features, constraints, and technical requirements
2. Epic generation — Logical groupings emerge (e.g., “Core Auth”, “Password Reset”, “Rate Limiting”)
3. Ticket creation — Each epic is split into atomic, implementable tickets
4. Dependency mapping — Tickets are linked by what must finish before something else can start

This isn’t a flat task list. It’s a directed acyclic graph where every ticket knows its prerequisites.

💡 The quality of the decomposition scales with the quality of your description. Include technical constraints, library preferences, and edge cases. SpecForge uses everything you provide. A vague description produces a vague plan — quality in, quality out.

What a Planned Specification Looks Like

When planning finishes, your specification contains a detailed breakdown. Here’s what the example above might produce:

Epics

Example Tickets (Core Authentication)

Tickets with status ready have no pending dependencies — they can be worked on immediately. Tickets with status pending are waiting on upstream work.

Refining Your Specification

Before implementation, you can refine from the webapp (visual editing) or through your coding agent (MCP tools):

• Edit tickets — Adjust scope, add acceptance criteria, or clarify requirements
• Add dependencies — Link tickets that need ordering with the action_planning_session op create_dependencies
• Check for cycles — SpecForge rejects circular dependencies automatically inside create_dependencies — an edge that would form a cycle is refused when the batch is submitted (there is no separate tool)
• Review the critical path — See which chain of tickets determines the overall timeline with get_critical_path

The webapp gives you visual drag-and-drop editing. The MCP tools give you the same power from the terminal. Use whichever fits your context.

✅ The planning-review gate runs inside complete_planning_session — it returns an AI evaluation (score + findings) of your specification’s completeness before you move to implementation.

What Happens Next

With a fully planned specification and tickets in ready state, you have two paths:

1. Manual implementation — Pick up tickets yourself, use MCP tools to track progress, link commits and PRs
2. Autonomous implementation — Let your coding agent implement the entire specification with orchestrated parallel execution

Most teams start manual to build confidence, then go autonomous on larger specifications.

Next: Install CLI →