Project Spec

Machine-readable specs that link intent to code, with tooling to surface drift.

Software is full of implicit knowledge—what the system should do versus what it does. This gap becomes critical when AI agents enter the picture: an agent can't distinguish between a test that's wrong and a test that's protecting something important. Without explicit intent, agents silently regress functionality, drift from requirements, and lose context between sessions.

Project Spec solves this by declaring intent in YAML specs, linking those declarations bidirectionally to code via markers, and running reconciliation to surface gaps.

Read the manifesto → for the full philosophy and motivation.

---

Prerequisites

• Python 3.10+

Installation

# Install from source (PyPI coming soon)
git clone https://github.com/codewithcheese/projectspec.git
pip install ./projectspec[validation]

Quick Start

# Run reconciliation on the example project
cd projectspec/examples/taskflow
projectspec reconcile

Example output:

Reconciliation complete: 3/5 features OK
  (1 planned features skipped)

spec/capabilities/auth.yaml:
  user-authentication/password-reset: [ERROR] Path does not exist
    → tests/api/test_password_reset.py

Unlinked files (not referenced in any spec):
  src/api/routes/teams.py

The output shows:

• OK - Features where all linked files exist
• ERROR - Missing implementation or test files
• WARNING - Missing documentation files
• Planned - Features with status: planned (skipped)
• Unlinked - Files not referenced by any spec

What You Get

• Schema validation - Specs validated against JSON Schema defined in KindDefinitions
• File existence checking - Verify implementedIn, testedIn, documentedIn paths exist
• Coverage verification - Match @implements, @tests, @documents markers to acceptance criteria
• Relationship graphs - Track dependencies, detect cycles, validate entity references
• JSON output - Machine-readable results for CI integration (--format json)
• Custom kinds - Define domain-specific entity types (not just Capability/Feature)
• GitHub Action - Run reconciliation and spec review on PRs with comments and labels

CI Integration

Add ProjectSpec checks to your GitHub workflow:

# .github/workflows/projectspec.yml
name: Projectspec
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: codewithcheese/projectspec/.github/actions/projectspec@main

On PRs, this posts a comment summarizing spec changes and adds severity labels (spec-info, spec-warning). See the CI Integration Guide for configuration options.

How It Works

┌─────────────────┐
│   SPEC FILES    │ ← Human-controlled source of truth
│   (yaml)        │
└────────┬────────┘
         │
         │ declares
         ▼
┌─────────────────┐      ┌─────────────────┐
│  CAPABILITIES   │ ───► │ IMPLEMENTATION  │
│  (what it does) │      │ (code, tests,   │
│                 │ ◄─── │  docs)          │
└─────────────────┘      └─────────────────┘
         │                        │
         └────────┬───────────────┘
                  │
                  ▼
         ┌─────────────────┐
         │ RECONCILIATION  │ ← Surface drift, resolve intentionally
         │ (diff spec vs   │
         │  reality)       │
         └─────────────────┘

Code links back to specs via markers:

"""
@implements feature:auth/login
  - User can log in with email and password
  - Invalid credentials return 401
"""
def login(email: str, password: str) -> Token:
    ...

Adding Specs to Your Project

1. Create spec directory structure:

   your-project/
   ├── spec/
   │   ├── kinds/           # Copy from examples or define your own
   │   │   ├── capability.yaml
   │   │   └── feature.yaml
   │   └── capabilities/    # Your specs go here
   │       └── auth.yaml
   └── src/
   

2. Write your first spec:

   apiVersion: projectspec/v1alpha1
   kind: Feature
   metadata:
     name: auth/login
   spec:
     status: implemented
     acceptance:
       - User can log in with email and password
       - Invalid credentials return 401
     implementedIn:
       - src/auth/login.py
     testedIn:
       - tests/test_auth.py
   

3. Add markers to your code:

   # src/auth/login.py
   """
   @implements feature:auth/login
     - User can log in with email and password
     - Invalid credentials return 401
   """
   

4. Run reconciliation:

   projectspec reconcile
   

Core Concepts

Spec as contract - The spec is a machine-readable agreement, not documentation that rots. Every statement is verifiable: "feature is implemented" → linked files exist.

Reconciliation - Drift between spec and reality is expected. The goal isn't to prevent drift—it's to surface it and resolve it intentionally.

Human authority over spec - Agents implement what specs say; changing specs requires human approval. This prevents agents from "solving" problems by redefining them away.

Documentation

Understand the concepts:

• About - Core principles and rationale
• Methodology - Reconciliation loop and workflow
• Schema Design - Why specs are structured this way

Reference:

• Spec Format - How to write spec files
• Entity Model - Entity categories and relationships
• Defining Kinds - How to create custom KindDefinitions

Working with specs:

• Agent Guidelines - How AI agents should interact with specs
• CI Integration - Add ProjectSpec checks to GitHub Actions
• Worked Example - The taskflow example explained

Status

This is an early exploration of the methodology. The format and tooling will evolve.

Current limitations:

• No watch mode for continuous reconciliation
• Limited adapter support (Python, Markdown)
• No IDE integration yet