Specifications

A specification is a complete description of a feature or deliverable. It contains everything an agent needs to understand, plan, and implement — from goals and constraints to the full dependency graph.

What Is a Specification?

The spec is the planning unit in SpecForge. You describe what you want in natural language, and the engine decomposes it into epics, tickets, and a dependency graph. Two quality gates validate the plan and the implementation before anything ships.

But a specification is more than a description. After planning, it becomes a structured object with context, quality criteria, technical decisions, and inherited patterns. Every field exists to give agents the information they need to implement correctly — without guessing.

Anatomy of a Specification

A planned specification contains four groups of fields. You don’t fill all of these manually — some are set during creation, others emerge during the planning phase as the agent decomposes and refines.

Context — What to Build

These fields define the problem space. They answer: “What are we building, why, and what’s in scope?”

goals — What the spec must achieve. These are outcomes, not tasks. “Users can reset their password via email” is a goal. “Create a password reset endpoint” is a ticket step — it belongs lower.

Use goals to align the agent with intent. When the agent faces a decision not covered by tickets (and it will), goals are the tiebreaker. If a goal says “minimize user friction,” the agent picks the simpler UX option.

requirements — Functional and non-functional requirements. “JWT tokens expire after 15 minutes” is functional. “Login endpoint responds in under 200ms” is non-functional.

Goals vs requirements: Goals describe outcomes. Requirements describe constraints on how those outcomes must work. A spec can have the goal “secure authentication” and the requirement “use bcrypt with cost factor 12.” The goal explains why, the requirement explains how tightly.

scope — What’s in and what’s out. Explicit scope prevents agents from gold-plating. “In scope: email/password auth, password reset. Out of scope: OAuth providers, 2FA.” Without this, an ambitious agent might build OAuth because it seems like the right thing to do.

Always define out-of-scope. It’s more useful than in-scope. Agents understand what to build from tickets. What they don’t know is where to stop.

background — Context for understanding the feature. Existing system architecture, relevant business logic, user personas, previous decisions. This is the onboarding document for the agent — everything a new developer would need to know before starting.

Background is optional but high-leverage. A spec with good background produces better decomposition because the agent understands the system it’s building into.

Quality — How to Validate

These fields define success criteria and boundaries. They answer: “How do we know it’s done, and what must the agent never do?”

acceptanceCriteria — Conditions that must be met for the spec to be considered complete. These are spec-level criteria, distinct from ticket-level acceptance criteria. “All endpoints return consistent error format” is spec-level. “Login returns 401 on invalid credentials” is ticket-level.

Spec-level acceptance criteria catch cross-cutting concerns. Individual tickets might pass their own criteria but violate a spec-wide standard. The Implementation Review evaluates both levels.

guardrails — Constraints that agents must follow during implementation. “Never store passwords in plain text.” “Always use parameterized queries.” “Do not modify the existing user model schema.”

Guardrails vs constraints: Guardrails are about agent behavior — what the agent must or must not do. Constraints are about the system — technical or business limitations that exist regardless of who’s implementing.

constraints — Technical or business limitations. “Must work with PostgreSQL 15.” “Cannot exceed 50MB bundle size.” “Must support Node 18+.”

Constraints are facts about the world. Guardrails are rules you’re imposing. The distinction matters because constraints can’t be negotiated — they’re hard limits. Guardrails can be adjusted if circumstances change.

successMetrics — How to measure whether the spec achieved its goals after implementation. “Login success rate > 99.5%.” “Password reset completion rate > 80%.” “Average auth response time < 150ms.”

Success metrics are post-implementation. They don’t affect the Implementation Review — they’re for you to evaluate after deployment whether the feature is working as intended.

Technical — How to Build

These fields capture architectural decisions and technical structure. They answer: “What does the system look like?”

architecture — System design decisions. Service boundaries, data flow, component relationships. This is where you document “the auth service is a separate module that the API gateway calls” or “we use a middleware chain for request validation.”

Architecture prevents the agent from inventing its own. Without it, two agents working in parallel might build the same feature with incompatible architectures.

techStack — Technologies and frameworks. “TypeScript, Fastify, Prisma, PostgreSQL, Jest.” Agents use this to generate code in the right language with the right libraries.

fileStructure — Expected file organization. “Services go in src/services/. Tests mirror the source tree in tests/.” This ensures agents produce code that fits your project layout.

apiContracts — Interface definitions. Request/response shapes, error formats, authentication headers. Can reference OpenAPI specs, GraphQL schemas, or plain descriptions.

Inherited Patterns — How Your Code Looks

These fields are special. They define patterns that are inherited by every ticket in the specification. Instead of repeating “use this import style” in 15 tickets, you set it once at the spec level.

codeStandards — Code conventions and style rules. “Use named exports. Prefer interface over type for object shapes. Error messages follow the format [SERVICE_NAME] description.”

commonImports — Shared imports across tickets. “Every service file imports { logger } from '@/lib/logger'.” Agents include these automatically without each ticket needing to specify them.

returnTypes — Return type patterns. “All service methods return Result<T, AppError>.” “API endpoints return { data, error, metadata }.” This ensures consistency across all implemented code.

Inherited patterns are the highest-leverage fields in a specification. They compound across every ticket. One codeStandards entry affects dozens of files. Without them, each agent invents its own conventions, and the codebase looks like it was written by 15 different people — because it was.

Status Lifecycle

A specification moves through 10 states across three phases:

Planning: draft → planning → specifying → validating → ready

Implementation: in_progress → ready_for_review

Review: in_review → reviewed → completed

Transitions within the planning phase (the “planning corridor”) happen automatically based on your operations. Creating structure moves to planning. Adding dependencies moves to specifying. Running reports moves to validating. You don’t manage these transitions — SpecForge tracks what you’re doing and moves the state accordingly.

For the complete state machine with all transitions and rules, see Specification States.

What Makes a Good Specification

The Planning Review will catch structural problems. But the difference between a spec that scores 82 (barely passes) and one that scores 95 (clean pass) comes down to how you write it.

Be specific about constraints. “Use bcrypt” is better than “use secure hashing.” The agent won’t guess wrong.

Define out-of-scope explicitly. Agents are ambitious. Without boundaries, they build more than you asked for.

Include background. A spec that says “add auth to the API” produces a generic plan. A spec that says “add auth to the existing Fastify API that serves a React SPA, currently using cookie-based sessions, migrating to JWT” produces a plan that fits your system.

Set inherited patterns early. codeStandards, commonImports, and returnTypes cascade to every ticket. Set them once, benefit everywhere.

Write goals as outcomes, not tasks. “Users can log in with email and password” drives better decomposition than “build a login endpoint.”