Skip to Content
QuickstartFirst Specification

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.

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

#EpicTickets
1Core Authentication4
2Token Management3
3Password Reset Flow3
4Rate Limiting & Lockout3

Example Tickets (Core Authentication)

TicketDepends OnStatus
Set up User model and database schema—ready
Implement password hashing with bcryptUser modelready
Build registration endpointPassword hashingpending
Build login endpointPassword hashingpending

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 →

Create AccountInstall CLI