Spec Format Reference

A spec is a structured directory that serves as a complete blueprint for a Ralph Loop. This page documents every file, every field, and every convention.

Directory Structure

my-spec/
├── spec.yaml                # Manifest — metadata, cost estimates, tags
├── PROMPT.md                # Agent entry point — what the AI reads first
├── SPEC.md                  # Functional specification — what to build
├── SUCCESS_CRITERIA.md      # Machine + human evaluable criteria
├── stdlib/                  # Technical standards
│   ├── STACK.md             # Required technologies and versions
│   ├── PATTERNS.md          # Code patterns to follow
│   └── SECURITY.md          # Security requirements
└── examples/                # Optional example outputs
    └── README.md

Required Files

Every spec must include:

spec.yaml — Without this, the spec can’t be published or run
PROMPT.md — The agent’s entry point
SPEC.md — The functional specification
SUCCESS_CRITERIA.md — How to verify the output works

Optional Files

stdlib/STACK.md — Recommended. Constrains the tech stack so the agent doesn’t guess.
stdlib/PATTERNS.md — Recommended. Defines code patterns for consistency.
stdlib/SECURITY.md — Recommended. Defines security requirements.
examples/ — Optional. Reference implementations or example outputs.

spec.yaml Schema

The manifest file. All fields use snake_case.

# Required fields
name: "docusign-replacement"            # URL-safe, lowercase, hyphens only
display_name: "DocuSign Replacement"     # Human-readable name
description: >
  A complete e-signature application that handles document generation,
  signature field placement, email-based signing workflows, and
  signed document storage.
version: "1.0.0"                         # Semver (major.minor.patch)
runner: "claude-code"                    # Only "claude-code" supported in v1
 
# Estimated resources (displayed on marketplace, not enforced)
min_model: "claude-sonnet-4"             # Minimum model for reliable results
estimated_tokens: 150000                 # Estimated total tokens consumed
estimated_cost_usd: 11.40               # Estimated cost in USD
estimated_time_minutes: 35               # Estimated wall-clock time
 
# Classification
output_type: "web-app"                   # web-app | cli-tool | api-service | library | mobile-app
primary_stack: "nextjs-typescript"       # nextjs-typescript | astro-typescript | python-fastapi | go | rust | other
tags:                                    # Up to 10 tags for discovery
  - "e-signature"
  - "document-generation"
  - "legal"
 
# SaaS replacement metadata (optional but recommended)
replaces_saas: "DocuSign"                # Name of the SaaS being replaced
replaces_pricing: "$25/user/month"       # What the SaaS charges
 
# Infrastructure requirements (optional)
infrastructure:
  monthly_cost: 15.00                    # Estimated monthly hosting cost
  setup_time_minutes: 20                 # Time to set up infrastructure
  deployment_targets:                    # Where this can be deployed
    - "vercel"
    - "railway"
    - "self-hosted"
  user_provided:                         # Services the user must set up
    - "Stripe API key"
  services:                              # External service dependencies
    - category: "database"
      name: "Supabase"
      purpose: "Document and signature storage"
      required: true
      user_provided: false
      providers:
        - name: "Supabase"
          free_tier: true
          paid_starts_usd: 25.00
          notes: "Free tier supports up to 500MB"
      default_provider: "Supabase"
      setup_notes: "Create a Supabase project and add the connection URL to .env"
 
# Fork metadata (set automatically, do not edit manually)
forked_from_id: null                     # Convex ID of the parent spec
forked_from_version: null                # Version that was forked

Field Reference

Field	Type	Required	Description
`name`	string	Yes	URL-safe identifier. Lowercase, hyphens only.
`display_name`	string	Yes	Human-readable name for the marketplace.
`description`	string	Yes	What this spec builds. Be specific.
`version`	string	Yes	Semver format. Increment on every publish.
`runner`	string	Yes	Must be `"claude-code"` in v1.
`min_model`	string	Yes	Minimum model for reliable results.
`estimated_tokens`	integer	Yes	Total tokens estimate.
`estimated_cost_usd`	number	Yes	Total cost estimate in USD.
`estimated_time_minutes`	integer	Yes	Wall-clock build time estimate.
`output_type`	enum	Yes	One of: `web-app`, `cli-tool`, `api-service`, `library`, `mobile-app`.
`primary_stack`	enum	Yes	One of: `nextjs-typescript`, `astro-typescript`, `python-fastapi`, `go`, `rust`, `other`.
`tags`	string[]	Yes	1-10 tags for marketplace discovery.
`replaces_saas`	string	No	Name of the SaaS this replaces.
`replaces_pricing`	string	No	What the SaaS charges (e.g., “$25/user/month”).
`infrastructure`	object	No	External service dependencies and hosting info.
`forked_from_id`	string	No	Set automatically when forking.
`forked_from_version`	string	No	Set automatically when forking.

PROMPT.md

The agent’s entry point. This is the first file the AI coding agent reads when starting a Ralph Loop.

A good PROMPT.md:

Tells the agent to read SPEC.md for requirements
Points to stdlib/ for technical standards
References SUCCESS_CRITERIA.md for verification
Sets expectations for the build process

Example:

# Build Prompt
 
You are building a DocuSign replacement application.
 
## Instructions
 
1. Read SPEC.md for the complete functional specification
2. Follow the technical standards in stdlib/
3. Build the application iteratively — write code, run tests, fix errors
4. Verify your work against SUCCESS_CRITERIA.md
5. Do not stop until all success criteria pass
 
## Key Constraints
 
- Use the technology stack defined in stdlib/STACK.md
- Follow the code patterns in stdlib/PATTERNS.md
- Meet all security requirements in stdlib/SECURITY.md
- Every feature must have tests

SPEC.md

The functional specification. Describes what to build (not how).

A good SPEC.md:

Describes features in concrete, testable terms
Specifies input/output formats
Defines error handling behaviour
Lists explicit edge cases
Is specific enough that two different agents would build similar systems

SUCCESS_CRITERIA.md

Machine-evaluable checks that determine whether the build succeeded.

A good SUCCESS_CRITERIA.md includes:

Automated checks (tests pass, build succeeds, linting clean)
Functional checks (specific CLI commands work, specific API endpoints respond)
Integration checks (database connects, auth flows work)

Example:

# Success Criteria
 
## Automated
- [ ] `pnpm install` completes without errors
- [ ] `pnpm build` produces output in dist/ or .next/
- [ ] `pnpm test` passes with 0 failures
- [ ] TypeScript strict mode: 0 errors
 
## Functional
- [ ] POST /api/documents creates a new document
- [ ] GET /api/documents/:id returns document details
- [ ] POST /api/documents/:id/sign records a signature
- [ ] Signed documents are stored and retrievable
- [ ] Email notifications are sent (or logged in dev mode)
 
## Integration
- [ ] Database migrations run successfully
- [ ] Application starts on port 3000
- [ ] Health check endpoint returns 200

stdlib/ Directory

Technical standards that constrain the build. These are optional but strongly recommended — without them, the agent makes its own technology choices, which reduces consistency and success rates.

STACK.md

Defines the required technology stack with specific versions:

# Technology Stack
 
- Runtime: Node.js 20+
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Database: Supabase (PostgreSQL)
- ORM: Drizzle
- Styling: Tailwind CSS 4
- Testing: Vitest + Playwright
- Package Manager: pnpm

PATTERNS.md

Defines code patterns for consistency:

# Code Patterns
 
## File Structure
- Pages in app/ (Next.js App Router)
- Server actions in app/actions/
- Database queries in lib/db/
- Shared types in lib/types.ts
 
## Error Handling
- Use Result<T, E> pattern for fallible operations
- Never throw in API routes — return proper HTTP status codes
- Log errors with structured context

SECURITY.md

Defines security requirements:

# Security Requirements
 
- All user input validated with Zod schemas
- SQL injection prevention via parameterised queries (Drizzle handles this)
- CSRF protection on all mutation endpoints
- Rate limiting: 100 requests/minute per IP
- Secrets in environment variables, never in code

Validation

Validate your spec before publishing:

specmarket validate ./my-spec

The validator checks:

spec.yaml exists and all required fields are present
spec.yaml field types match the schema
Semver format is valid
PROMPT.md, SPEC.md, and SUCCESS_CRITERIA.md exist
Files are non-empty
Tags are within the 1-10 limit

Publishing

Once validated, publish to the marketplace:

specmarket publish

The spec goes through an automated security scan before listing. See Security & Trust for details on what’s scanned.

Getting Started — Install the CLI and run your first spec
What is a Ralph Loop? — How the autonomous build process works
Publishing Your First Spec — Step-by-step creator guide