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 — Create the spec

Tell your coding agent:

Create a new SpecForge specification titled "User Authentication System"
with the following 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.

The agent calls create_specification 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 the Implementation Review will validate the code after — the second control loop.

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.

Create 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. Tell your agent:

Create a new SpecForge specification titled "User Authentication System"
with the following 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.

The agent calls the create_specification MCP tool and returns the new specification ID. 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 add_dependency
• Check for cycles — SpecForge prevents circular dependencies automatically, but you can verify with check_circular_dependencies
• 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.

✅ Use the review_planning tool to get an AI evaluation of your specification’s completeness before moving 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 →