project-spine

the missing context layer for software delivery

Project Spine

A context compiler for software projects.

Project Spine turns a client brief, a repo, and optional design-system inputs into a machine-readable project operating layer: agent instructions, architecture summary, UX rules, scaffold decisions, QA guardrails, and a sprint-ready backlog — all in one pass, all in your repo.

brief.md ──┐
repo/   ───┼──▶  spine.json ──▶  AGENTS.md + CLAUDE.md + copilot-instructions.md + project-spine.mdc
design.md ─┘                    scaffold-plan.md, qa-guardrails.md, sprint-1-backlog.md,
                                component-plan.md, route-inventory.md, rationale.md

Status — v0.9.x (beta). The CLI works end-to-end: brief + repo + optional design + optional template → canonical spine.json + generated exports. Drift detection, design-token ingestion, Cursor-native exports, MCP, the GitHub drift action, generated social assets, and agent skills for Claude Code / Codex / Cursor are all live. The compiler path is ready for public evaluation while templates and integrations continue to harden before 1.0.

See the full product thinking in PRD.md, the research evidence in docs/research-citations.md, and the "why not just Claude?" moat analysis in docs/positioning.md.

Why

Developers save ~10 hours a week with AI tools and lose the same ~10 hours to fragmented context (Atlassian 2025 DevEx). Only ~5% of repositories contain AI configuration files (arXiv, Oct 2025), and the ones that do tend to drift immediately. Practitioners consistently warn against auto-generated AGENTS.md / CLAUDE.md boilerplate — Addy Osmani, March 2026.

The gap isn't more AI. It's a repo-native, drift-aware compiler that turns actual project intent (brief, code, design rules) into rules agents and humans can both trust. That's what Project Spine is.

Install

# from npm — the @beta tag tracks the current public beta train
npm install -g project-spine@beta

# or from source
git clone https://github.com/PetriLahdelma/project-spine.git
cd project-spine
npm install
npm run build
node dist/cli.js --help

Requires Node ≥ 20.

60-second demo — init → compile → drift check → drift diff:

Regenerate via VHS: vhs docs/demo/demo.tape. See docs/demo/.

Quickstart

# 1. scaffold a brief from a preset
spine init --template saas-marketing

# 2. compile brief + repo (+ optional template + optional tokens) into spine.json and exports
spine compile --brief ./brief.md --repo . --template saas-marketing
# or with a Figma / Tokens Studio JSON export:
spine compile --brief ./brief.md --repo . --tokens ./tokens.json

# 3. regenerate a subset without recompiling
spine export --targets claude,copilot,cursor

# 4. analyze any existing repo without a brief
spine inspect --repo .

# optional: inspect what Codex, Claude, Copilot, and Cursor will load
spine inspect --repo . --agent-files

# 5. check drift between last compile and current state (CI-friendly)
spine drift check --fail-on any

# 6. verify local beta readiness
spine doctor

# 7. browse templates
spine template list
spine template show design-system

What you get

A single spine compile run writes at least 21 files:

./AGENTS.md                                  (agents.md convention — tool-discovery location)
./CLAUDE.md                                  (Claude Code — uses @import to keep lean)
./.github/copilot-instructions.md            (Copilot — self-contained)
./.cursor/rules/project-spine.mdc            (Cursor — always-on project rule)
./.cursor/rules/project-spine-*.mdc          (Cursor — scoped workspace rules for monorepos)

./.project-spine/
  spine.json                                 canonical machine-readable model (hashed)
  brief.normalized.json                      parsed brief
  repo-profile.json                          detected stack + conventions
  warnings.json                              ambiguities, conflicts, missing fields
  export-manifest.json                       hashed inventory used by `spine drift check`
  exports/
    AGENTS.md, CLAUDE.md, copilot-instructions.md, cursor-project-rule.mdc
    architecture-summary.md                  detected stack at a glance
    brief-summary.md                         normalized brief at a glance
    scaffold-plan.md                         routes, components, sprint-1 seed
    route-inventory.md                       route list with rationale
    component-plan.md                        component buckets + usage rules
    qa-guardrails.md                         actionable QA checklist + DoD
    sprint-1-backlog.md                      sprint 1 backlog with acceptance criteria
    rationale.md                             client-facing project rationale

See docs/sample-output/ for real compiled examples — including this repo compiled by itself. Regenerate the template-backed proof pack with npm run build && npm run samples:generate.

Principles

• Repo-native first. Outputs live in files you can version, diff, and trust.
• Useful without AI. A human reviewer should want to keep the files.
• Opinionated, not magical. Good defaults, transparent reasoning, no black box.
• Fast path to value. First run under 30 seconds on a typical repo.
• Drift-aware. spine drift check flags input drift, hand-edited exports, and missing files. Generation is cheap; staying aligned is the moat.
• Deterministic before enriched. LLM calls (when they arrive) never load-bear.
• Security by default. No implicit network calls, no uninvited uploads.

How it works

┌────────────┐   ┌────────────┐   ┌──────────────┐   ┌──────────────┐
│ brief.md   │──▶│  Brief     │──▶│   Rules      │──▶│  Exporters   │
└────────────┘   │  parser    │   │  compiler    │   │  (MD + JSON) │
┌────────────┐   └────────────┘   │  (merge,     │   └──────────────┘
│ repo/      │──▶┌────────────┐──▶│  dedupe,     │
└────────────┘   │ Repo       │   │  conflict    │
┌────────────┐   │ analyzer   │   │  detection)  │
│ design.md  │──▶└────────────┘──▶│              │
└────────────┘                    └──────────────┘
                                         │
                                         ▼
                                  ┌───────────────┐
                                  │ spine.json    │
                                  │ warnings.json │
                                  └───────────────┘

Every rule in spine.json carries a source pointer — brief.md#section0/item3, repo-profile#framework, template:saas-marketing/contributes#2, or inferred:... — so reviewers can audit why a rule exists, not just trust that it does.

Templates

Six starter presets ship in the box:

Template	Project type	Contributes
saas-marketing	Marketing site	7 routes, 7 components, LCP/CLS budgets, privacy guardrails
app-dashboard	Authenticated dashboard	role-gated routes, PermissionGate/DataTable/AppShell, PII scrubbing
design-system	Library	zero routes, tokens/primitives/Storybook QA, ships its own design-rules.md
docs-portal	Documentation site	docs-specific routes, TOC/CodeBlock/SearchBar, broken-link QA
api-service	HTTP API (Node/TS)	/health + /ready probes, ErrorEnvelope/RequestContext/RateLimiter, log + SLO QA
monorepo	pnpm / Turborepo / Nx	packages/* + apps/* layout, BuildGraph + ChangeGate, affected-only CI rules

Each template contributes routes, components, QA, UX, a11y, and agent rules — not just a brief scaffold. Every contributed rule is tagged kind: "template" in spine.json for traceability.

Agent skills (for Claude Code, Codex CLI, Cursor)

The skills/ directory ships six agent skills for Project Spine: active workflows for kickoff, drift, project-local templates, and local rationale review; a hosted-workspace guardrail for dormant commands; plus an orientation skill that triggers on phrases like "new client project" or "AGENTS.md is stale".

# install into ~/.claude/skills (Claude Code)
./skills/install.sh

# also install into ~/.codex/skills (Codex CLI)
./skills/install.sh --codex

# preview without touching disk
./skills/install.sh --dry-run

Each skill is a single SKILL.md with YAML frontmatter describing its trigger phrases. The installer symlinks them so edits land immediately. See skills/README.md for what each skill does and how they chain.

MCP server (spine-mcp)

The npm install also drops a second binary on PATH: spine-mcp, a stdio MCP server that exposes compile, doctor, drift check, drift diff, init, and tokens pull as tools any MCP-speaking client can call — Claude Code, Cursor, Continue.

Claude Code / Cursor config:

{
  "mcpServers": {
    "project-spine": { "command": "spine-mcp" }
  }
}

Full setup notes + tool reference: docs/mcp.md.

For site analytics observability, use the public stream metadata plus Google's read-only GA4 MCP server. Setup notes: docs/ga4-observability.md.

Desktop wrapper

The opt-in Electron wrapper in apps/desktop runs spine doctor, spine compile, and spine template list against a local repo through the same public CLI surface. It is a private companion package, not part of the root npm tarball.

npm install --prefix apps/desktop
npm run build
npm run verify --prefix apps/desktop
npm start --prefix apps/desktop

Security posture: the renderer loads local files only, Node integration is disabled, context isolation and sandboxing are enabled, IPC is whitelisted in preload, and CLI commands are spawned without a shell.

GitHub Action: spine drift check in your CI

Fail your own CI when AGENTS.md / CLAUDE.md / copilot-instructions.md drift from the brief or tokens. No release to Marketplace yet — reference by full repo path:

- uses: PetriLahdelma/project-spine/.github/actions/drift-check@main
  with:
    fail-on: any

Use @main to track the current action. Pin the action ref to a release tag or commit SHA when you need immutable CI.

Inputs, outputs, and more examples: .github/actions/drift-check/README.md.

Roadmap

What's shipped (beta train):

• v0.1–v0.2 — brief parser, repo inspector, deterministic exporters, the first 4 starter templates, init / compile / inspect / export.
• v0.3 — spine drift check with CI-friendly --fail-on, idempotent compile, hash manifest.
• v0.8 — agent skills for Claude Code, Codex CLI, and Cursor (skills/install.sh).
• v0.9 — --tokens import for DTCG and Tokens Studio design tokens. spine tokens pull pulls directly from Figma Variables on Enterprise plans; Tokens Studio plugin export is the path on Team / Pro / Starter.
• Desktop companion — an opt-in Electron wrapper under apps/desktop for running the public CLI from a local GUI without changing the npm CLI package.

What's next is TBD. Project Spine is positioned as pure OSS for now — the direction will be shaped by what agencies and dev-tool teams actually use it for. Open an issue, a discussion, or email with field notes and we'll fold it into the plan.

See PRD.md §16 for the original phasing; ground truth is the changelog at /changelog.

Development

npm install
npm run typecheck    # tsc --noEmit
npm test             # vitest
npm run build        # tsc → dist/

Project layout:

src/
  analyzer/      stack + convention detection (§7.2 of the PRD)
  brief/         Markdown + frontmatter brief parser (§7.1)
  cli-client/    auth + API client for dormant hosted experiments
  commands/      citty subcommands. Routed today:
                 init, compile, inspect, export, template, explain, drift,
                 tokens, doctor.
                 Dormant hosted experiments are excluded from the public
                 npm build while they remain unrouted:
                 login, logout, whoami, workspace, publish, rationale.
  compiler/      the rules compiler, hash, deterministic ID (§7.3)
  design/        design-rules parser + DTCG / Tokens Studio ingestion
  drift/         drift detection against the stored manifest
  exporters/     one file per output target (§7.4 / §7.5)
  llm/           opt-in LLM enrichment (never load-bearing)
  model/         zod schemas for every artifact
  reporters/     Markdown summaries
  templates/     registry + manifest loader (§11)
  ui/            CLI presentation helpers (banners, styling)
templates/       bundled starter presets (§11)
skills/          agent skills for Claude Code, Codex, Cursor
examples/        sample briefs for tests and demos
docs/
  research-citations.md
  sample-output/ a real compiled example
PRD.md

Contributing

See CONTRIBUTING.md. This is a single-maintainer project right now; issues and sharp feedback are welcome. PRs get a warmer reception after an issue discussion.

Security

See SECURITY.md for how to report vulnerabilities.

License

MIT. See LICENSE.

Stars over time