Project Spine
An OSS CLI that compiles a client brief, a repo, and optional design-system inputs into a repo-native, machine-readable operating layer for humans and AI coding agents. One command, 19 structured files, zero hosted dependencies.
How it works
Ingestion
- Client brief (brief.md)
- Repo scan (framework signals)
- Design tokens (DTCG/Tokens Studio)
- Template selection (6 built-in)
Compilation
- Normalize brief → spine.json
- Profile repo structure
- Resolve token aliases (10-hop)
- Generate component plan
Export
- Agent discovery layer (root)
- 11 markdown exports
- Hashed export manifest
- Source pointers for traceability
Drift Detection
- SHA-256 per export file
- spine drift check
- spine drift diff
- CI-blocking on hand-edits
Inputs
Brief + Repo + Tokens
brief.md. A client or product brief. Can be hand-written or scaffolded from one of six built-in templates: saas-marketing, saas-dashboard, saas-auth, agency-site, ecommerce, b2b-marketing.
Repo directory. Scanned for package.json, tsconfig.json, and framework signals. Spine doesn't need you to describe your stack; it reads it.
tokens.json (optional). DTCG or Tokens Studio format, auto-detected. Nested groups flattened to dotted paths. Aliases resolved recursively with a 10-hop cap.
spine init --template saas-marketing: one command scaffolds a production-shape brief
Outputs
19 files per compile
Tool-discovery layer at repo root. AGENTS.md, CLAUDE.md, .github/copilot-instructions.md. The paths where Claude Code, Cursor, and GitHub Copilot look first. Spine writes them with repo-specific content, not boilerplate.
Full compiled layer under .project-spine/. Architecture summary, brief summary, component plan, QA guardrails, rationale, route inventory, scaffold plan, sprint-1 backlog, plus the canonical spine.json and hashed export-manifest.json.
Compiled output tree: agent discovery layer + 11 markdown exports + manifest
Enforcement
Drift detection as first-class
Drift detection is first-class. spine drift check --fail-on any exits non-zero if any export has been hand-edited since the last compile. spine drift diff shows exactly what changed. The hashed manifest makes this deterministic. No fuzzy matching, no false positives.
The same instinct Rhythmguard applies to spacing values, Spine applies to compiled context. If the brief changes but the exports don't, the pipeline catches it.
spine drift diff: unified diff between compiled and current state
Design Systems
Why design systems are the highest-leverage context
Token dictionaries, component APIs, naming conventions. This is the difference between an AI agent that generates consistent UI and one that generates noise. Spine records source pointers in spine.json so every downstream rule is traceable back to the token definition.
Spine does not transform tokens to platform code. That's Style Dictionary's job. It consumes tokens as input signal so the compiled operating layer references the right values. Complementary to token transformers, not competitive.
19 Files
Per compile. Agent discovery layer + full compiled operating context + hashed manifest.
121 Tests
Vitest suite. TypeScript strict mode. No runtime telemetry. No hosted dependency.
6 Templates
Production-shape briefs: SaaS marketing, dashboard, auth, agency, ecommerce, B2B.
Repo-Native
Outputs are markdown in the repo, versioned like code. No external service, no vendor lock-in.
Positioning
Not a scaffolder, not a doc generator
AGENTS.md generators dump boilerplate. Spine reads the actual brief + repo + tokens and produces repo-specific content. Design token transformers emit platform code. Spine consumes tokens as input signal. Hosted AI project management requires a service. Spine is local-first, repo-native, OSS.
Interested in working together?
Let's discuss how design systems, AI and thoughtful UX can elevate your product.