Quickstart

cd your-project
scafld init

scafld new add-auth -t "Add JWT authentication" -s medium -r high

spec_version: "1.1"
task_id: add-auth
created: "2026-04-16T10:00:00Z"
updated: "2026-04-16T10:00:00Z"
status: draft

task:
  title: "Add JWT authentication"
  summary: "Add token-based auth to the API layer"
  size: medium
  risk_level: high
  context:
    packages: ["src/auth", "src/middleware"]
    invariants: [public_api_stable, config_from_env]
  objectives:
    - "Issue JWT tokens on successful login"
    - "Validate tokens on protected routes"
  touchpoints:
    - area: "src/middleware"
      description: "New auth middleware"

  acceptance:
    definition_of_done:
      - id: dod1
        description: "All auth endpoints return standard error envelope"
        status: pending

phases:
  - id: phase1
    name: "Token generation"
    objective: "Create JWT signing and verification"
    changes:
      - file: src/auth/token.ts
        action: create
        content_spec: "Sign and verify JWTs using RS256"
    acceptance_criteria:
      - id: ac1_1
        type: test
        description: "Token round-trips correctly"
        command: "npm test -- --grep 'token'"
        expected: "exit code 0"
    status: pending

  - id: phase2
    name: "Auth middleware"
    objective: "Request validation pipeline"
    dependencies: [phase1]
    changes:
      - file: src/middleware/auth.ts
        action: create
        content_spec: "Extract and validate JWT from Authorization header"
    acceptance_criteria:
      - id: ac2_1
        type: test
        description: "Middleware blocks unauthenticated requests"
        command: "npm test -- --grep 'auth middleware'"
        expected: "exit code 0"
    status: pending

planning_log:
  - timestamp: "2026-04-16T10:00:00Z"
    actor: agent
    summary: "Initial spec draft"

# Validate against the schema
scafld validate add-auth

# Approve (moves drafts/ → approved/)
scafld approve add-auth

# Start execution (moves approved/ → active/)
scafld start add-auth

# Hand the spec to your agent...

# Run acceptance criteria
scafld exec add-auth

# Check for scope drift against git
scafld audit add-auth -b main

# Run the review (automated + adversarial scaffold)
scafld review add-auth

# Archive as completed (requires passing review)
scafld complete add-auth

scafld report