spec-architect

Does what was built actually match what was specced?

spec-architect is a CLI + GUI tool that audits the alignment between your spec documents, source code, and tests. It answers the question developers and PMs dread: "Is this thing actually done?"

---

What it does

For each feature, spec-architect:

1. Parses your markdown spec files and extracts requirements (by heading ID pattern)
2. Indexes your TypeScript codebase via AST — not regex
3. Runs your test suite and correlates results back to requirements
4. Builds a delta matrix showing the exact status of every requirement:

Status	Meaning
✅ SYNC	Spec, code, and tests all agree
❌ GAP	Requirement exists in spec, nothing in code
⚡ DRIFT:MODIFIED	Code diverges from spec intent
🗑️ DRIFT:REMOVED	Spec active, code marked @deprecated
➕ DRIFT:ADDED	Code added without spec coverage
🔶 ORPHAN_CODE	Code exists, no spec requirement found
❓ VAGUE	Requirement too ambiguous to map

---

Install

git clone https://github.com/rrtrytcg/spec-architect
cd spec-architect
npm install

Requires Node 18+ and TypeScript. Uses ts-node to run directly — no build step needed.

---

Quick start

1. Create a config

npx ts-node --transpile-only index.ts init

This generates spec-architect.config.json in your project root. Edit it:

{
  "version": "1.0",
  "specGlob": "docs/**/*.md",
  "codeGlob": ["src/**/*.ts", "src/**/*.tsx"],
  "testCommand": "npx vitest run --reporter=json",
  "e2eCommand": "npx playwright test --reporter=json",
  "outputDir": ".spec-architect",
  "mappingStrategy": "heading-regex",
  "features": [
    {
      "id": "my_feature",
      "specPath": "docs/my-feature.md",
      "entryPoints": ["src/my-feature/**/*.ts"],
      "testPattern": "my-feature*.test.ts"
    }
  ]
}

2. Write specs with requirement IDs

Spec files are plain markdown. Requirements are headings that follow the pattern PREFIX-NNN:

# My Feature

## FEAT-001: Users can log in with email

GIVEN a valid email and password
WHEN the user submits the login form
THEN they are redirected to the dashboard

## FEAT-002: Failed login shows error message
...

3. Run an audit

# From your project root
npx ts-node --transpile-only /path/to/spec-architect/index.ts audit my_feature \
  --json \
  --config ./spec-architect.config.json

Outputs:

• .spec-architect/AUDIT_MY_FEATURE_<timestamp>.md — human-readable report
• .spec-architect/AUDIT_MY_FEATURE_<timestamp>.json — machine-readable for CI

---

GUI

spec-architect ships with a local web dashboard. Run it from the spec-architect directory:

npx ts-node --transpile-only gui-server.ts \
  --root /path/to/your/project \
  --port 4747

Then open http://localhost:4747.

The GUI lets you:

• Point at a spec folder and auto-discover all your spec files
• Create and manage spec-architect.config.json visually
• Run audits with live streaming output
• View the delta matrix with color-coded status rows
• Export the delta matrix as a markdown file for AI agents
• Add new features without touching the config directly

---

CLI reference

# Create config template
npx ts-node --transpile-only index.ts init

# Snapshot repo state
npx ts-node --transpile-only index.ts scan --config ./spec-architect.config.json

# Lint spec quality before auditing
npx ts-node --transpile-only index.ts lint my_feature --config ./spec-architect.config.json

# Full audit (add --json for machine output, --ci to exit 1 on gaps)
npx ts-node --transpile-only index.ts audit my_feature --json --config ./spec-architect.config.json

# Approve an audit (sign-off before shipping)
npx ts-node --transpile-only index.ts approve my_feature .spec-architect/AUDIT_MY_FEATURE_<ts>.md

# Verify audit hasn't drifted since approval
npx ts-node --transpile-only index.ts verify my_feature .spec-architect/AUDIT_MY_FEATURE_<ts>.md

---

CI integration

# .github/workflows/spec-audit.yml
- name: Run spec audit
  run: |
    npx ts-node --transpile-only /path/to/spec-architect/index.ts audit my_feature \
      --json --ci \
      --config ./spec-architect.config.json

Exit code is 1 if any blocking gaps exist. Pair with the JSON output for PR annotations.

---

How requirement mapping works

spec-architect maps requirements to code using three strategies, in descending confidence:

Method	Confidence	How
@spec-req FEAT-001 JSDoc tag	1.0	Explicit annotation in code
Frontmatter implements list	0.8	Spec frontmatter declares which files implement it
Heading ID regex match	0.5	Heading pattern FEAT-001: matched to symbol names

Low-confidence mappings are surfaced as VAGUE and never silently ignored.

---

Fidelity score

Each requirement gets a fidelity score (0–100%):

Base: mapping confidence × 40%
+30% if a test references this requirement
+30% if that test passes
×0.5 if implementation is @deprecated
×0.8 if implementation has a @todo

---

License

MIT — see LICENSE.

Contributions welcome.