Features
Foundation Document

Foundation Document

Living architecture documentation that guides discovery and implementation.

Before writing code, you need context—who are your users? What problems are you solving? What technical constraints exist? The Foundation Document captures this essential context in a structured, AI-friendly format that evolves with your project.

What Is the Foundation Document?

The Foundation Document is your project's single source of truth for:

  • Problem Space - What problem are you solving and for whom?
  • Solution Space - What capabilities does your system provide?
  • Personas - Who uses the system and what are their goals?
  • Architecture - What technical decisions and constraints guide implementation?

It lives in two files:

  • spec/foundation.json - Machine-readable data (AI can query this)
  • spec/FOUNDATION.md - Human-readable markdown (auto-generated, do not edit)

Why Use a Foundation Document?

Benefits:

  1. Guides Discovery - Personas inform Example Mapping (As a X, I want Y...)
  2. Prevents Drift - Architecture section keeps code aligned with technical decisions
  3. Onboards AI - Machine-readable format AI can reference during development
  4. Documents Decisions - Captures "why" decisions were made
  5. Evolves Over Time - Living document that grows with the project

Draft-Driven Discovery Workflow

fspec uses a draft-driven workflow with placeholders that AI fills field-by-field:

The 8 Discovery Fields

Field-by-field discovery ensures nothing is missed:

  1. Project Name - What is this project called?
  2. Project Vision - What is the elevator pitch?
  3. Project Type - cli-tool, web-app, library, service, etc.
  4. Problem Title - What's the core problem?
  5. Problem Description - Detailed problem explanation
  6. Solution Overview - High-level solution approach
  7. Capabilities - What does the system do?
  8. Personas - Who uses it and why?

Natural Language Discovery

Scenario 1: Starting a New Project

YOU: "Let's set up the foundation document for this project."

AI: "I'll start the foundation discovery process."

AI runs: fspec discover-foundation

Output: Created foundation.json.draft

ULTRATHINK guidance:
  Field 1/8: project.name
  QUESTION: What is the project name?

  This is the simple name of the project (e.g., "fspec", "my-app").

  Run: fspec update-foundation projectName "your-name"

AI: "What should we name this project?"

YOU: "Call it 'task-tracker'."

AI runs: fspec update-foundation projectName "task-tracker"

Output: Updated field 1/8

ULTRATHINK guidance:
  Field 2/8: project.vision
  QUESTION: What is the project's vision (elevator pitch)?

  Focus on WHY this exists, not HOW it works.
  Example: "Enable teams to track work without complex overhead"

  Run: fspec update-foundation projectVision "your vision"

AI: "What problem does task-tracker solve? Give me an elevator pitch."

YOU: "It helps solo developers track tasks without enterprise bloat."

AI runs: fspec update-foundation projectVision \
  "Lightweight task tracking for solo developers"

Scenario 2: Completing Discovery

AI: "We've filled 7 of 8 fields. Final field is personas."

AI: "Who will use this system?"

YOU: "Solo developers and small teams."

AI runs: fspec add-persona "Solo Developer" \
  "Individual developer managing personal projects" \
  --goal "Track tasks without overhead" \
  --goal "Focus on coding, not process"

AI runs: fspec add-persona "Small Team" \
  "2-5 person development team" \
  --goal "Coordinate work asynchronously" \
  --goal "Maintain visibility without meetings"

AI: "All 8 fields complete. Finalizing foundation..."

AI runs: fspec discover-foundation --finalize

Output:
  ✓ Validated foundation.json.draft
  ✓ Created spec/foundation.json
  ✓ Generated spec/FOUNDATION.md
  ✓ Deleted foundation.json.draft

AI: "Foundation document complete! You can view it with: fspec show-foundation"

Scenario 3: Adding Capabilities

YOU: "Add a capability for kanban board visualization."

AI runs: fspec add-capability "Kanban Board" \
  "Visual board showing work across workflow states"

AI runs: fspec add-capability "Work Unit Management" \
  "Create and track work units through ACDD lifecycle"

AI runs: fspec add-capability "Example Mapping" \
  "Discover acceptance criteria through rules, examples, questions"

AI: "Added 3 capabilities to the foundation. These define WHAT the system does."

Foundation Structure

Project Section

{
  "project": {
    "name": "task-tracker",
    "vision": "Lightweight task tracking for solo developers",
    "projectType": "cli-tool"
  }
}

Project Types:

  • cli-tool - Command-line interface
  • web-app - Web application
  • library - Reusable library
  • sdk - Software development kit
  • mobile-app - Mobile application
  • desktop-app - Desktop application
  • service - Backend service
  • api - API server
  • other - Custom type

Problem Space Section

{
  "problemSpace": {
    "primaryProblem": {
      "title": "Solo developers lack lightweight task tracking",
      "description": "Existing tools are too complex for individual developers...",
      "impact": "high"
    }
  }
}

Impact Levels:

  • low - Nice to have
  • medium - Significant pain point
  • high - Critical blocker

Solution Space Section

{
  "solutionSpace": {
    "overview": "CLI-based task tracker with visual board",
    "capabilities": [
      {
        "name": "Kanban Board",
        "description": "Visual board showing work across states"
      },
      {
        "name": "Work Unit Management",
        "description": "Create and track work through lifecycle"
      }
    ]
  }
}

Key Point: Focus on WHAT (capabilities), not HOW (implementation)

Personas Section

{
  "personas": [
    {
      "name": "Solo Developer",
      "description": "Individual developer managing personal projects",
      "goals": [
        "Track tasks without overhead",
        "Focus on coding, not process"
      ]
    }
  ]
}

Personas drive Example Mapping:

  • "As a Solo Developer, I want..."
  • "As a Small Team, I need..."

Architecture Diagrams Section

{
  "architectureDiagrams": [
    {
      "title": "System Context",
      "mermaidCode": "graph TB\n  Human[Developer]\n  ...",
      "description": "High-level system context diagram"
    }
  ]
}

Rendered in FOUNDATION.md as Mermaid diagrams.

Integration with ACDD

Foundation in the ACDD Workflow:

  1. Initialization - Discover foundation before creating work units
  2. Example Mapping - Reference personas for "As a X, I want Y" scenarios
  3. Implementation - Check architecture section for technical constraints
  4. Review - Validate code aligns with foundation principles

Commands Reference

Discover Foundation

# Start discovery (creates draft)
fspec discover-foundation
 
# Check progress (shows current field)
fspec discover-foundation --scan-only
 
# Finalize (validate and create foundation.json)
fspec discover-foundation --finalize

Update Foundation Fields

# Project fields
fspec update-foundation projectName "my-app"
fspec update-foundation projectVision "Elevator pitch here"
fspec update-foundation projectType "web-app"
 
# Problem space
fspec update-foundation problemTitle "Core problem title"
fspec update-foundation problemDefinition "Detailed problem description"
 
# Solution space
fspec update-foundation solutionOverview "High-level solution approach"

Add Capabilities

fspec add-capability "<name>" "<description>"
 
# Example
fspec add-capability "User Authentication" \
  "OAuth and JWT-based authentication system"
 
fspec add-capability "Data Export" \
  "Export data to CSV and JSON formats"

Add Personas

fspec add-persona "<name>" "<description>" \
  --goal "<goal1>" \
  --goal "<goal2>"
 
# Example
fspec add-persona "Admin User" \
  "System administrator managing users" \
  --goal "Control user access" \
  --goal "Monitor system health"

View Foundation

# Show current foundation
fspec show-foundation
 
# Show specific section
fspec show-foundation --section personas
fspec show-foundation --section capabilities

Generate Markdown

# Regenerate FOUNDATION.md from foundation.json
fspec generate-foundation-md

Auto-runs after finalization, but useful if you manually edit foundation.json.

Validation and Schema

JSON Schema Validation

The foundation document is validated against a JSON Schema:

Schema Location: schemas/generic-foundation.schema.json

Validation Checks:

  • All required fields present
  • No [QUESTION:] or [DETECTED:] placeholders
  • projectType is valid enum value
  • capabilities array has at least 3 items
  • personas array has at least 1 item with goals
  • Mermaid diagrams have valid syntax

Validation Errors

fspec discover-foundation --finalize
 
Error: Validation failed
  - Field 'project.vision': Value contains placeholder '[QUESTION:...]'
  - Field 'solutionSpace.capabilities': Must have at least 3 capabilities
  - Field 'personas': Must have at least 1 persona
 
Fix errors in spec/foundation.json.draft and try again.

Common Patterns

Pattern 1: Bootstrap New Project

# 1. Initialize project
fspec init
 
# 2. Start foundation discovery
fspec discover-foundation
 
# 3. Fill fields via AI conversation
# (AI prompts for each field)
 
# 4. Finalize
fspec discover-foundation --finalize
 
# 5. Begin creating work units
fspec create-story AUTH "User Authentication"

Pattern 2: Iterate on Capabilities

# 1. Add initial capabilities
fspec add-capability "User Management" "CRUD operations for users"
fspec add-capability "Authentication" "Login and session management"
fspec add-capability "Authorization" "Role-based access control"
 
# 2. Check progress
fspec discover-foundation --scan-only
 
# 3. Continue with remaining fields

Pattern 3: Reference During Example Mapping

# 1. Read foundation to understand personas
fspec show-foundation --section personas
 
# 2. Use personas in Example Mapping
fspec add-rule AUTH-001 "As a Solo Developer, I want to login with GitHub OAuth"
 
# 3. Reference capabilities
fspec show-foundation --section capabilities
fspec add-example AUTH-001 "User clicks Login, redirects to GitHub, returns with token"

Decision Flow

Best Practices

✅ DO

  • Discover early - Create foundation before first work unit
  • Focus on WHY - Explain why the project exists, not how it works
  • Clear vision - One sentence elevator pitch
  • Concrete personas - Specific people with real goals
  • Capabilities, not features - High-level what, not implementation details
  • Validate before finalizing - Check draft completeness

❌ DON'T

  • Skip discovery - Don't start work units without foundation
  • Describe implementation - Architecture section is for constraints, not code
  • Leave placeholders - Finalize foundation completely
  • Edit FOUNDATION.md - It's auto-generated, edit foundation.json instead
  • Overcomplicate - Keep it simple and focused
  • Forget personas - They drive Example Mapping scenarios

Troubleshooting

Draft Already Exists

fspec discover-foundation
 
Error: foundation.json.draft already exists
  Current field: 3/8 (project.projectType)
 
  Options:
  - Continue: fspec update-foundation projectType "cli-tool"
  - Check status: fspec discover-foundation --scan-only
  - Start over: rm spec/foundation.json.draft && fspec discover-foundation

Finalization Fails

fspec discover-foundation --finalize
 
Error: Cannot finalize - 2 field(s) incomplete
  - personas: Add at least 1 persona
  - capabilities: Add at least 3 capabilities

Fix:

fspec add-persona "User" "End user" --goal "Use the app"
fspec add-capability "Core Feature 1" "Description"
fspec add-capability "Core Feature 2" "Description"
fspec add-capability "Core Feature 3" "Description"
fspec discover-foundation --finalize

Summary

The Foundation Document provides essential project context:

Key Components:

  • Problem Space: What problem you're solving
  • Solution Space: What capabilities you provide
  • Personas: Who uses the system
  • Architecture: Technical constraints and decisions

Integration with ACDD:

  • Guides Example Mapping with personas
  • Enforces architectural constraints during implementation
  • Evolves as the project grows
  • Machine-readable for AI agents

Create your foundation document first—it's the context that makes everything else make sense.

AttachmentsEpic Management