🔥 LiveSpec — Specs that live beyond implementation

A universal, tool-agnostic specification framework with visual diagrams, living documentation, and spec-to-code traceability for AI-driven development.

---

The Problem

Specs today are throwaway documents:

• Written once, never updated after implementation
• No visual diagrams — just walls of text
• No traceability between spec requirements and actual code
• No history of what changed and why
• Tools and AI assistants forget the context

Six months later, nobody knows why something was built the way it was.

---

What LiveSpec Does Differently

Problem	LiveSpec Solution
No visuals	Mermaid diagrams mandatory in every spec and plan
No traceability	Implementation mapping — every spec requirement links to @spec anchors in code
Specs rot after launch	Living docs — specs updated when behavior changes
No history	Per-feature + journey changelogs — every behavior and journey change is recorded
UI behavior hidden in screenshots	Penflow contracts — root penflow/ owns semantic UI flow correctness
No visual testing	Playwright baselines built into implementation + check
No quality evidence contract	Native QE Analysis built into specify, plan, and test goals
Regression flows tied to one feature	Cross-feature User Journeys v2 — global journeys cover multiple features, compile once, and run as non-regression tests
Stack decisions lost	Stack presets with decision trees — know WHY you chose each tool
One-time init	Brainstorm-driven init — AI interviews you before generating anything
Tool-specific	Tool-agnostic — works with Claude Code or any AI that reads Markdown

---

How It Works

flowchart LR
    P["/spec-propose\nDiscover what\nto build"] --> S["/spec-specify\nWrite the spec\n(stories, AC, FR)"]
    S --> PL["/spec-plan\nTechnical plan\n(diagrams, steps)"]
    PL --> I["/spec-implement\nCode, test,\nmap to spec"]
    I --> J["/spec-journey\nCross-feature\nregression flows"]
    J --> T["/spec-test\nAudit + Penflow\n+ visual gates"]
    T --> C["/spec-check\nVerify spec\nvs code"]
    C --> F["/spec-fix\nFix gaps\n(functional + visual)"]
    F --> E["/spec-explain\nLiving\ndocumentation"]

    style P fill:#e8f4f8,stroke:#2196F3
    style S fill:#e8f4f8,stroke:#2196F3
    style PL fill:#e8f4f8,stroke:#2196F3
    style I fill:#e8f4f8,stroke:#2196F3
    style J fill:#e8f4f8,stroke:#2196F3
    style T fill:#e8f4f8,stroke:#2196F3
    style C fill:#e8f4f8,stroke:#2196F3
    style F fill:#e8f4f8,stroke:#2196F3
    style E fill:#e8f4f8,stroke:#2196F3

Loading

Each command works standalone, or chain them all with /spec-feature for an end-to-end pipeline with validation gates.

Contract and execution evidence

Reviews use complete, bounded source context and feature-qualified requirement IDs. Analyze reports structural reference coverage separately from grounded semantic conclusions: citing an ID cannot prove that a plan implements its meaning. Missing context, contradictions, stale reviews and unresolved critical clarifications block progression. An unchanged valid review is reused; the five-question presentation limit never discards outstanding questions.

Autonomous runs (/spec-ship, --auto pipelines, /spec-implement) carry an outcome goal: one executable stop condition that livespec goal prove verifies itself, a short list of receipt-backed proofs, and the skill inventory as an indicative checklist. Native goal tools (Codex create_goal, Claude Code /goal) are optional mirrors; drifted contracts recompile with their valid evidence, and three rejections of one proof hand control back with a report. Short interactive commands run without a goal. Current goals distinguish documentary, review and execution evidence. Execution certification requires a runner-owned receipt with current source/test/configuration identity, actual test results and independently reviewed acceptance mappings. A success sentence, exit code zero, or global coverage percentage is insufficient. Custom drivers remain runnable and report any certification gap. Existing visual, conventions, finalization, bootstrap and Penflow checks still apply; historical archives retain their original policy rather than becoming new proof.

The generation evaluation corpus contains isolated Python CLI, TypeScript API and UI/Penflow witnesses. Independent frozen oracles check actual behavior and reject faulty mutants. Reports distinguish first-attempt success, repaired success, expected blocking, failure, invalid runs and unavailable runtimes. GitHub checks are deterministic and require no model provider or model credential. Real-model samples and full-corpus evaluations remain explicit local opt-in operations; their reports distinguish actual completed coverage and unknown costs. A passing finite corpus does not establish universal correctness or untested runtime parity.

The spec-feature coordinator binds final acceptance to the complete current independently reviewed specification, including criteria created after its goal was compiled. Proof, archive and archive-read all require that review plus execution and any documentary acceptance evidence. Existing frozen contracts keep their original interpretation.

Read the shared review protocol and execution rules for the internal adapters used by existing commands. Generated review caches and receipts require no additional user-maintained document.

---

Conventions Enforcement

LiveSpec enforces project conventions through three engines:

• Engine A — deterministic subprocess: lint, format, typecheck, and built-in repo checks from .specs/conventions-gates.yaml.
• Engine B — visual receipt: Penflow/design/visual evidence receipts for UI workflows.
• Engine C — Layer 4 LLM review: semantic conventions from the compiled rulebook when deterministic checks are not enough.

Primary CLI commands:

livespec conventions gates init --force
livespec conventions compile --force
livespec conventions scaffold --apply
livespec conventions verify --report
livespec conventions supervisor-gate --base-ref <ref> --head-ref <ref>

Feature-scoped verification resolves mapped source, configuration (.yaml, .yml, .json, .toml) and Markdown files from implementation.md. CI-only features therefore receive the same conventions receipt; declared linters still enforce their diagnostics, while source AST checks keep their supported language set. Internal .specs/ artifacts and paths outside the project cannot establish implementation scope.

livespec conventions verify --json also emits source_manifest, an AI-res/ARS corpus inventory with source counts, explicit exclusions, and a language/domain matrix. Root SECURITY.md and THIRD_PARTY_NOTICES.md notices are explicitly excluded with reasons; nested files with those names and unknown sources remain subject to classification and completeness checks.

For debt remediation, run /spec-fix --conventions. See system/conventions-enforcement.md for the full architecture, human operations, anti-bypass locks, and CLI reference.

---

The 23 Commands

Command	What it does
/spec-init	3-phase conversational brainstorm → generates project profile, stack, .specs/ structure + CLAUDE.md. --from-code: reverse-engineer existing codebase.
/spec-migrate	Upgrade project to latest LiveSpec version — applies pending migrations, updates local symlinks
/spec-propose	Analyze project context and intelligently propose the next feature(s) to build
/spec-specify	Create a new feature spec with user stories, Mermaid flows, AC, FR, and native QE risks/evidence expectations
/spec-plan	Generate technical plan with sequence, state, ER diagrams, and native QE gates/test evidence
/spec-implement	APEX-style auto-pipeline: implement → test → visual baselines → map to spec. Multi-agent orchestration by default (--mono for single-agent)
/spec-test	Audit AC test coverage, generate missing tests from Gherkin, execute suite, validate Penflow expected/actual UI trees, capture visual baselines, verify design fidelity, and enforce native QE evidence sufficiency
/spec-journey	Create, edit, bootstrap, impact-check, inspect, compile, and run global User Journeys v2 across multiple features
/spec-check	Compare spec vs actual code — find gaps, verify AC, report Penflow contract status, detect visual drift; --pre-impl runs a read-only pre-implementation cross-artifact Analyze report (no writes)
/spec-doctor	Project health audit — orchestrates coherence validation and reports stale mappings, missing tests, runner drift, unenforced hooks, lifecycle gaps, visual orphans
/spec-fix	Fix implementation gaps from spec-check — functional and visual corrections with retry loop
/spec-explain	"How does X work?" — living documentation from spec + diagrams + history
/spec-stack	Evolve your stack and analyze impact on existing features
/spec-feature	Full pipeline: specify → clarify → plan → analyze → implement → test, with validation gates between phases
/spec-preflight	Verify tooling, auth, and API tokens before starting implementation — runs auto-install, detects blockers, gates feature work
/spec-hooks	Show, create, or edit lifecycle hooks for a command
/spec-play-coverage	Open spec coverage playground with live grep data
/spec-ship	Batch autopilot: ship multiple features from roadmap end-to-end
/spec-refine	Iteratively refine existing artifacts (project, feature spec, or plan) via guided conversation
/spec-status	Display factual status overview of roadmap and features
/spec-refresh-conventions	Manually initialize or refresh project conventions from the LiveSpec stack
/spec-refresh-from-brainstorm	Sync brainstorm lifecycle deltas into LiveSpec through an interactive Impact Report
/spec-verify-output	Verify a command run artifact against its expectations contract

---

LiveSpec commands are migration-gated: if .specs/livespec-version is older than repo VERSION, normal commands fail before doing work and instruct the user to run /spec-migrate or livespec migrate. /spec-init, /spec-migrate, help output, and internal livespec goal control-plane calls remain available for recovery.

---

User Integrations (~/.config/livespec/*.md)

LiveSpec supports user-level Markdown integrations: drop a <name>.md file under ~/.config/livespec/ and it is automatically injected into the LLM context of the LiveSpec commands you target via its YAML frontmatter. This is a hook-resolution Level 0, prepended to the existing Global / Project / Local levels.

---
integration: <name>
commands: [specify, plan]   # any subset of .agent-sync/skills/spec-*
phase: before               # before | after (default: before)
mode: extend                # extend | override (default: extend)
order: 100                  # lower = injected earlier
---

<markdown body — injected as-is, with {{feature_name}} etc. substituted>

Opt-in by design. Without a file in ~/.config/livespec/, the framework is tool-agnostic — no warning, no error, identical behavior. A starter template is shipped under examples/config/mockups.md.example.

See system/integrations.md for the full specification (eligibility rule, override scope, template variables, chained-pipeline semantics, --economy mode limitation). Diagnostic: livespec integrations list or /spec-hooks <command>.

Implementation steps and pre-commit finalization use an independent read-only native quality reviewer with effort high. Read the review protocol and legacy user-hook replacement procedure; the review preserves the index and blocks on unresolved findings or incomplete evidence. Existing Spec/Plan, conventions and acceptance gates remain required.

This pattern is independent of ~/.config/livespec/provider.py (the existing Python callable that overrides LLM routing).

---

Quick Start

Claude Code (recommended)

# 1. Clone LiveSpec
git clone https://github.com/julien-m/livespec.git ~/livespec

# 2. Install the bootstrap commands globally (required once)
bash ~/livespec/scripts/install.sh

# 3. Initialize LiveSpec in your project (creates .specs/ + CLAUDE.md)
cd your-project
/spec-init

# 4. Discover what to build first
/spec-propose

# 5. Create your first feature spec
/spec-specify "User can receive real-time notifications"

# 6. Generate technical plan
/spec-plan notifications

# 7. Implement with auto-pipeline
/spec-implement notifications

# 8. Add a cross-feature regression journey when a flow spans features
/spec-journey create

# 9. Verify spec vs code
/spec-check notifications

# 10. Explain the feature (living docs)
/spec-explain "how do notifications work?"

# Alternative: full pipeline in one command
/spec-feature "User can receive real-time notifications"

Other AI tools

For any AI tool that reads Markdown, paste the content of system/spec-system.md into your tool's context. The spec system is tool-agnostic — any AI that can read .specs/ will follow the rules.

---

Workflow Guide

Manual flow (step by step)

Run each command individually with full control at every stage:

/spec-specify "User can filter by date"   # 1. Generate spec.md
/spec-plan date-filter                     # 2. Generate plan.md
/spec-implement date-filter                # 3. Implement from plan
/spec-journey create                       # 4. Add cross-feature regression flow
/spec-check date-filter                    # 5. Verify spec vs code

Pipeline flow (/spec-feature)

Run the full pipeline in one command with validation gates between each phase:

# Interactive (default) — pauses for your approval between phases
/spec-feature "User can filter by date"

# Automatic — no pauses, auto-retries if plan review fails
/spec-feature "User can filter by date" --auto

# Resume an interrupted pipeline
/spec-feature --resume date-filter

After implementation

/spec-test date-filter                     # Audit + generate missing tests
/spec-journey impact                       # Detect impacted old journeys
/spec-check date-filter                    # Verify spec-code alignment
/spec-explain "how does date filtering work?"  # Living documentation
/spec-stack                                # View or evolve the stack

---

Command Reference

/spec-init

Initialize LiveSpec through an interactive brainstorm or an observed from-code profile. Autonomous initialization preserves independent native/frontend families, keeps unobserved product facts Unknown and executes actual bounded tooling checks.

/spec-init                       # Full interactive setup
/spec-init --auto                # Use defaults, skip questions
/spec-init --stack web-realtime  # Skip interview, use preset
/spec-init --from-code           # Reverse-engineer existing codebase into specs
/spec-init --from-code --auto    # Observed bootstrap with full verification/hooks/goal closure
/spec-init --from-code --auto --force --dir "/path with spaces" # Backed-up recovery
/spec-init --from-code --deep    # Interactive extended scan; rejected in autonomous mode

Key flags: --auto, --stack [preset], --from-code, --deep, --force, --dir [path], --dry-run

Explicit autonomous force recovery backs up prior specs, conventions and integration documents before overwriting owned bootstrap files, preserving custom history and source bytes. Mutable agents use local copies. --dry-run previews without project writes; the backend's --verify-only rechecks current profile/content identity without mutation. Autonomous --deep and conflicting presets fail before writes. Installer, sync, probes and hook subprocesses share one finite budget; backend exit zero still requires integration proof, after-init hooks, current verification and the authentic goal archive. Tooling READY does not certify application runtime. Conventions are rendered from the ai-ressources clone located as described in ai-ressources location (AIRESOURCES).

/spec-propose

Analyze project context (vision, users, existing features, roadmap) and propose the next feature(s) to build. Read-only — no files created.

/spec-propose                     # Propose the next feature
/spec-propose --count 3           # Propose 3 ranked features
/spec-propose --role admin        # Focus on admin features
/spec-propose --mvp               # Only MVP-critical suggestions

Key flags: --count N, --role [name], --mvp, --auto

/spec-specify

Create a feature spec with user stories, Mermaid flowcharts, AC, and FR.

/spec-specify "User can upload profile photos"
/spec-specify "Payment processing" --branch --priority P1

Key flags: --branch, --no-branch, --priority

/spec-plan

Generate a technical plan with sequence, state, and ER diagrams from a spec.

/spec-plan profile-photos
/spec-plan profile-photos --review          # LLM plan review (advisory)
/spec-plan profile-photos -r -R             # Review with all configured reviewers
/spec-plan profile-photos --no-contracts

Key flags: --review (-r), --all-reviewers (-R), --no-contracts (-C), --diagram-only (-D), --auto (-a)

/spec-implement

Auto-implement from plan: code, test, verify, document. Multi-agent by default.

/spec-implement profile-photos            # Multi-agent (default)
/spec-implement profile-photos --mono     # Single-agent
/spec-implement profile-photos --resume   # Resume interrupted run

Key flags: --mono, --economy, --resume, --no-visual, --no-save, --step

/spec-test

Audit test coverage against AC, generate missing tests from Gherkin scenarios, execute the full suite, and capture visual baselines.

/spec-test profile-photos                 # Test one feature
/spec-test --all                          # Test all implemented features
/spec-test profile-photos --audit-only   # Coverage audit only (no generation/execution)
/spec-test profile-photos --no-generate  # Run existing tests, don't generate missing ones

Key flags: --audit-only, --no-generate, --no-visual, --all, --auto, --update

/spec-journey

Create and govern cross-feature User Journeys v2. Journey sources live globally at .specs/journeys/<journey-id>/journey.yaml and reference every covered feature/FR/AC with qualified covers refs. They can be created for old or already implemented features without /spec-refine.

/spec-journey create                       # Interactive journey from free-form intent
/spec-journey bootstrap --from-existing    # Propose journeys for old projects/features
/spec-journey edit onboarding-first-project # Governed edit with decision + changelog
/spec-journey impact                       # Detect changed files touching old journeys
/spec-journey run                          # Execute compiled native artifacts only
/spec-journey list
/spec-journey inspect onboarding-first-project
/spec-journey visual                       # Agent evaluates LLM visual contracts, writes receipts

Low-level CLI:

livespec journey validate [--journey ID] [--feature SLUG] [--json]
livespec journey compile [--journey ID] [--feature SLUG] [--changed] [--force]
livespec journey run [--journey ID] [--feature SLUG] [--impacted] [--all] [--json]
livespec journey impact --changed-file PATH [--feature SLUG] [--json]
livespec journey migrate --from-v1 [--apply] [--json]
livespec journey visual-verify [--journey ID] [--json]   # verify agent receipts (no model call)
livespec journey list|inspect

Rules: create/edit compiles once; run executes native artifacts without recompiling and fails on stale source or old compiler manifests. XCUITest compilation runs xcodegen generate when project.yml/project.yaml is present. Edits require classification (regression, intentional_update, obsolete, selector_fix, or coverage_expansion) plus decision, changelog, validation, and run evidence. Visual checks may be native deterministic checks or LLM screenshot checks: the agent evaluates each compiled contract and writes a strict JSON receipt that livespec journey visual-verify checks (schema, contract/capture hashes, privacy, verdict). Read system/testing/user-journeys.md.

/spec-check

Compare spec vs actual code — find gaps, verify AC, detect visual drift.

/spec-check profile-photos
/spec-check                               # Check all features

/spec-explain

Living documentation — understand how a feature works from spec + code + history.

/spec-explain "how do notifications work?"
/spec-explain profile-photos

/spec-stack

View current stack, analyze change impact, create Architecture Decision Records.

/spec-stack                               # View current stack
/spec-stack "migrate from Supabase to Prisma"

/spec-feature

Full pipeline: specify → clarify → plan → plan review → analyze → implement, with validation gates.

/spec-feature "Real-time notifications"              # Interactive
/spec-feature "CSV export" --auto                     # Automatic
/spec-feature --resume csv-export                     # Resume
/spec-feature "Dark mode" --mono                      # Single-agent implementation
/spec-feature "Payment processing" --branch --priority P1  # With branch + priority

Key flags: --auto, --resume, --branch, --priority, --mono, --economy, --step

/spec-doctor

Project-level health audit. livespec doctor orchestrates livespec validate --coherence and adds practical downstream checks for stale implementation maps, missing mapped tests, runner inclusion, hook enforcement, lifecycle ambiguity, visual evidence orphans, cleanup safety, and R3.2 traceability infos for mapped files missing @spec(...) anchors.

livespec doctor
livespec doctor --format json
livespec doctor --strict
livespec doctor --fix-plan

Key flags: --format compact|full|json, --strict, --fix-plan, --apply-cleanup; cleanup planning is read-only and destructive cleanup is refused.

/spec-preflight

Verify tooling, authentication, and API tokens are ready before implementation. Auto-installs what it can, groups human blockers, gates feature work until all critical checks pass.

/spec-preflight                     # Full preflight check
/spec-preflight --light             # Light check (only new items since last run)
/spec-preflight --regenerate        # Regenerate manifest from stack

Key flags: --light, --regenerate, --save, --no-save

Runs automatically as part of /spec-init (Phase D), /spec-implement (Phase 0.5), and /spec-feature (Phase 2.7).

/spec-refine

Iteratively refine existing artifacts through guided conversation. Enforces eligibility rules — blocks refinement on specs/plans that already have downstream code.

/spec-refine                        # Interactive menu
/spec-refine project                # Refine project profile, constitution, or testing strategy
/spec-refine notifications          # Refine a feature spec
/spec-refine 002 plan              # Refine a feature plan

Key flags: --auto, --dry-run

/spec-status

Factual status overview — roadmap items, feature statuses, next actions. Read-only.

/spec-status                  # Full status
/spec-status --roadmap        # Roadmap only
/spec-status --features       # Features only
/spec-status --json           # Machine-readable output

Key flags: --roadmap, --features, --json

Full command documentation is in .agent-sync/skills/spec-*/SKILL.md.

---

Read Penflow certification for the distinction between noncertifying READY inspection and current PASS certification. Workflow callers select --required-profile design|implementation; implementation also receives an independent --build-manifest from its runner. Missing evidence or a compatible Penflow CLI blocks closure.

Visual lifecycle closure also checks the approved FR/AC selection and bound plan-review history automatically; reopening and governed visual retirement remain supported. Read Penflow workflow.

Project Structure Created by /spec-init

# Optional: imported from a Brainstorm `handoff/penflow/` folder, legacy `penflow/`, or created by later UI workflow.
penflow/
├── flow-ui-contract/       ← Flow/screen specs used to generate semantic tree
├── ui.pen                  ← Canonical Pencil/Penflow source; no other .pen is allowed
├── semantic-ui-tree.json   ← Primary UI behavior contract
├── expected-ui-tree.json   ← Design-derived structural baseline
├── code-ir.json            ← UI implementation handoff
├── actual-ui-tree.json     ← Runtime tree from external adapter
└── run-report.json         ← C51 report revalidated for explicit design/implementation closure

.specs/
├── README.md               ← Spec registry and artifact index (auto-maintained)
├── spec-system.md          ← The rules (READ FIRST — every tool reads this)
├── constitution.md         ← Project architecture principles
├── project.md              ← Vision, users, constraints (from brainstorm)
├── roadmap.md              ← Feature backlog (MVP / Post-MVP / Future)
│
├── stacks/
│   ├── _default.md         ← Your chosen stack + reasoning
│   └── decisions/          ← Architecture Decision Records (ADRs)
│       └── ADR-001-*.md
│
├── testing/
│   └── strategy.md         ← What to test, how, with which tools
│
├── journeys/
│   └── onboarding-first-project/
│       ├── journey.yaml     ← Global User Journey v2 source
│       ├── compiled/        ← Native compiled artifact + manifest
│       ├── decisions/       ← Required history for governed edits
│       └── changelog.md     ← Journey change history
│
├── features/
│   └── 001-notifications/
│       ├── spec.md          ← WHAT and WHY (user stories, Mermaid flows, AC, FR)
│       ├── plan.md          ← HOW (sequence/state/ER diagrams, file-by-file plan)
│       ├── implementation.md ← WHERE in code (FR/AC → @spec mapping)
│       ├── changelog.md     ← WHEN (every change recorded)
│       ├── journeys.md      ← Generated backlinks to global journeys
│       ├── contracts/       ← API contracts (OpenAPI/GraphQL)
│       └── baselines/       ← Playwright visual screenshots
│
└── changelog.md            ← Global project changelog

---

Installation

Global bootstrap (required once)

Install the two bootstrap skills that must exist before a project can sync the rest of LiveSpec locally:

bash ~/livespec/scripts/install.sh

This asks cc-hub to install only the two bootstrap skills required before a project has .specs/:

• spec-init and spec-migrate as portable skills for Claude Code and Codex

Bugfix lane

/spec-fix <feature> --bugfix fixes a confined bug without whole-feature spec and plan reviews, when the CLI proves eligibility; otherwise it falls back to the complete gate with its reasons.

livespec bugfix capture --feature <slug> --expect red --command "<python> -m pytest tests/test_x.py"
livespec bugfix gate --feature <slug> --red <red-receipt> [--requirement AC-003]
livespec bugfix capture --feature <slug> --expect green --command "<same command>"
livespec bugfix gate --feature <slug> --red <red-receipt> --green <green-receipt> [--base <rev>]
livespec bugfix record --feature <slug> --red <red-receipt> --green <green-receipt> --summary "<one line>"

Eligibility: owner feature with implementation.md, no FR/AC/SC definition or Gherkin change, the same regression test RED then GREEN, at most 8 files and 300 lines (override in .specs/bugfix.yaml). Exit codes: 0 READY/ELIGIBLE, 1 FALLBACK, 2 usage, 3 invalid configuration.

Pinned runtime for consumer projects

Consumer projects should run an immutable LiveSpec snapshot they pin, not the mutable development checkout. Full reference: docs/cli-reference.md.

cd ~/projects/livespec && uv sync    # once: the checkout's venv holds LiveSpec's dependencies
cd ~/projects/livespec && .venv/bin/python -m validator.cli runtime install --source ~/projects/livespec --ref <commit>
# first snapshot via the checkout's own venv; later `livespec runtime install` runs through the shim
export PATH="$HOME/.livespec/bin:$PATH"   # shim before /opt/homebrew/bin/livespec (editable install)
livespec runtime pin                      # in the project: writes .specs/livespec.lock
livespec runtime upgrade --to current     # later, voluntarily; run /spec-migrate if reported
livespec runtime dev --project . --source .   # the LiveSpec repository itself
livespec runtime status --json            # drift findings (also part of livespec doctor)
livespec runtime defect --command '<cmd>' --error '<error>' --feature <slug> --phase <phase>

Fresh machine (no livespec CLI yet): cd <livespec repo> && uv sync && .venv/bin/python -m validator.cli runtime install --source <livespec repo> --ref <commit from lock>, then <home>/versions/<id>/scripts/link-local.sh <project> <home>/versions/<id> and livespec runtime pin --runtime <id from lock>. To delete a read-only snapshot: chmod -R u+w ~/.livespec/versions/<id> && rm -rf ~/.livespec/versions/<id>. Consumer sessions follow system/tool-project-boundary.md.

Migrating an existing consumer project such as Handy (verified by tests/test_runtime_docs.py). Prerequisite: the LiveSpec checkout has its own environment, ~/projects/livespec/.venv (create it once with cd ~/projects/livespec && uv sync). The shim written by step 1 runs that same interpreter, so it keeps LiveSpec's dependencies without an activated venv.

# 1. Install a snapshot of a committed LiveSpec tree (never the dirty dev checkout) with the
#    checkout's own venv: a bare python3 lacks LiveSpec's dependencies (typer, pydantic).
git -C ~/projects/livespec fetch origin
cd ~/projects/livespec && .venv/bin/python -m validator.cli runtime install --source ~/projects/livespec --ref origin/main
# 2. Put the shim before any editable livespec (e.g. /opt/homebrew/bin/livespec); persist in ~/.zshrc.
export PATH="$HOME/.livespec/bin:$PATH"
hash -r
command -v livespec
# 3. Pin the consumer project to that runtime (lock, .livespec-path, LiveSpec-owned links).
cd ~/projects/handy
livespec runtime pin
# 4. Verify: mode "pinned" and no ERROR or WARNING runtime finding.
livespec runtime status --json
# 5. Commit the portable lock (.specs/.livespec-path and .agent-sync.local/ stay machine-local).
git add .specs/livespec.lock
git commit -m "chore: pin LiveSpec runtime"

Per-project (automatic after bootstrap)

When you run /spec-init in a project, LiveSpec syncs .agent-sync assets through cc-hub, which materializes the correct Claude Code and Codex provider outputs. No manual provider-specific installation is needed.

For existing projects initialized before v16, run /spec-migrate to migrate to the .agent-sync sync flow.

For other AI tools, paste system/spec-system.md into your tool's context.

ai-ressources location (AIRESOURCES)

ai-ressources is the conventions corpus read by /spec-init, the validator, the AST catalog and the conventions gate. Clone it anywhere and run its setup.sh: it exports AIRESOURCES=<absolute path of the clone> in your shell profile. AIRESOURCES is the only location variable.

Every LiveSpec consumer resolves the ai-ressources root of a project with one rule, in this order:

1. the AIRESOURCES environment variable, when it is non-empty (an empty or blank value counts as unset; the value is used as is);
2. otherwise the ai_resources_path key of the project's .conventions/manifest.yaml;
3. otherwise the `$AIRESOURCES` = `<path>` declaration of the project's .conventions/index.md.

A recorded path (steps 2 and 3) is used only when it designates an existing directory: .conventions/ files are committed and may name another machine's clone, which is why the environment variable wins. There is no other default location. When nothing resolves, LiveSpec reports an explicit error naming the project and every rejected recorded path, ending with:

Run ./setup.sh from your ai-ressources clone, or export AIRESOURCES=<absolute path of the clone>.

livespec conventions compile then exits 2 with rulebook_error, /spec-init --from-code stops with exit 2 before writing anything, livespec conventions verify reports the error as a catalog_load_error blocker, the corpus and rule decision manifests carry a resolution_error field, and coherence rule R7.3 reports one ERROR.

---

Comparison

Feature	LiveSpec	Spec Kit (GitHub)	APEX (aiblueprint)
Mermaid diagrams	✅ Mandatory	❌ None	❌ None
Spec-to-code traceability	✅ FR/AC → @spec anchors with deep-links	❌ None	⚠️ Partial
Per-feature changelogs	✅ Yes	❌ No	❌ No
Visual testing baselines	✅ Playwright + design fidelity	❌ None	❌ None
Post-impl test validation	✅ /spec-test (audit + generate + run)	❌ None	❌ None
Stack presets + decision trees	✅ Yes	❌ No	⚠️ Minimal
Brainstorm-driven init	✅ 3-phase conversation	❌ No	⚠️ Partial
Gap detection (spec vs code)	✅ /spec-check	❌ None	❌ None
Living documentation	✅ /spec-explain	❌ None	❌ None
Stack evolution + impact	✅ /spec-stack	❌ None	❌ None
Tool-agnostic	✅ Yes (Markdown-based)	⚠️ GitHub only	⚠️ Claude only

---

Portability

LiveSpec separates format from automation:

Layer	Portable?	Details
Spec format (.specs/, Markdown, Mermaid, Gherkin)	✅ Universal	Any AI tool that reads Markdown can follow the rules in spec-system.md
Commands (/spec-*)	⚠️ Claude Code + Codex	spec-init and spec-migrate are bootstrapped globally; project commands sync through .agent-sync via cc-hub
Routing rule (auto-route to /spec-*)	⚠️ Claude Code + Codex	Project-scoped via /spec-init; triggers on .specs/ presence in cwd
Agents (multi-agent orchestration)	⚠️ Claude Code + Codex	Portable .agent-sync/agents sources are built into provider-native outputs by cc-hub
Shell scripts (link-local.sh, migrate.sh, init.sh)	⚠️ macOS	Uses sed -i '' (BSD), open (macOS), mktemp — not tested on Linux

For non-Claude AI tools: paste the content of system/spec-system.md into your tool's context. The spec format and rules are tool-agnostic — the automation layer is Claude Code specific.

---

Multi-Agent Mode (default)

/spec-implement uses multi-agent orchestration by default — a supervisor acts as Orchestrator/Translator, building a Task Payload per step and delegating execution to the superpowers:subagent-driven-development skill:

flowchart TD
    SUP["SUPERVISOR\n(Orchestrator / Translator)"]

    SUP -->|"Task Payload\n(FR/AC, TDD, @spec rules)"| SPW
    SUP -->|"Checkpoint\nafter each step"| DOC

    subgraph SPW ["Superpowers: Subagent-Driven Dev"]
        IMP["Implementer\n(TDD, @spec anchors)"]
        SR["Spec Reviewer\n(FR/AC coverage)"]
        QR["Quality Reviewer\n(tests + code quality)"]
        IMP --> SR --> QR
    end

    subgraph DOC ["Documenter"]
        PROG["progress.md"]
        IMPL["implementation.md"]
        CL["changelog.md"]
    end

    style SUP fill:#fff3e0,stroke:#FF9800
    style IMP fill:#e8f4f8,stroke:#2196F3
    style SR fill:#e8f4f8,stroke:#2196F3
    style QR fill:#e8f4f8,stroke:#2196F3
    style PROG fill:#f3e5f5,stroke:#9C27B0
    style IMPL fill:#f3e5f5,stroke:#9C27B0
    style CL fill:#f3e5f5,stroke:#9C27B0

Loading

# Multi-agent implementation (default)
/spec-implement notifications

# Single-agent mode (original APEX pipeline)
/spec-implement notifications --mono

# Resume an interrupted run
/spec-implement notifications --resume

Per-step cycle: Supervisor builds Task Payload (FR/AC context, TDD commands, @spec rules, Definition of Done) → dispatches to superpowers:subagent-driven-development → Documenter writes progress.md checkpoint. Superpowers handles the full TDD loop, spec compliance review, and code quality review with isolated subagents (no context pollution).

Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1 in settings.

---

Validator CLI

LiveSpec includes a Python-based validator (livespec validate) for structural, coherence, and semantic validation of .specs/ files.

# Install
pip install -e .

# Layer 1 — structural validation
livespec validate

# Layer 2 — cross-file coherence
livespec validate --coherence

# Project health — coherence plus implementation/test/runner/hook/evidence drift
livespec doctor

# Layer 4 — LLM-based plan review
livespec validate --plan-review          # Review with first configured reviewer
livespec validate -r -R                  # Review with all configured reviewers
livespec validate --scorecard            # Quality scorecard
livespec validate --contradiction-only   # Contradiction detection

Visual gate

For features that produce UI, /spec-check, /spec-fix, /spec-test, and /spec-feature MUST call the canonical visual gate before reporting done:

livespec visual-gate certify --feature <slug> --command <spec-*> --target <t> --run-id <run-id> --json
livespec visual-gate validate --feature <slug> --command <spec-*> --target <t> --receipt <receipt-path> --json
livespec visual-gate cleanup  --feature <slug> --dry-run         # then --apply (archive is the default mode)
livespec visual-gate promote  --feature <slug> --target <t> --screen <s> --run-id <ts>

Exit codes: 0 PASS · 6 FAIL (link copy, runtime under .specs/design/screens/, alignment FAIL) · 7 BLOCKED (mockup / baseline registry / compare report missing) · 8 cleanup drift.

The visual-gate receipt is the pixel-fidelity oracle: goal prove accepts {"visual_evidence_receipt_path":"<receipt-path>"} only. Human-visible proof is separate: every validation PNG touched by /spec-test, /spec-feature, or /spec-fix must also print ![visual proof](/absolute/path/to/image.png), register visual-preview url /absolute/path/to/image.png, and report Open for annotation: http://127.0.0.1:<port>/i/<id>. If the CLI is missing, keep the Markdown image proof and print Visual preview: unavailable - visual-preview CLI missing; never forge a preview URL.

Canonical layout (no duplicate physical copies):

Path	Role
.specs/design/screens/<slug>/<screen>.png	Mockup registry. Runtime captures forbidden here.
.specs/design/baselines/<slug>/<target>/<screen>.png	Approved baseline registry — single physical copy.
.specs/features/<slug>/baselines/<screen>.png	Relative symlink (or manifest ref).
.specs/features/<slug>/run/<ts>/<target>/<screen>.png	Runner output. Targets: web, ios, android, tauri.

See docs/cli-reference.md for the full contract.

Registry finalization

End-of-command registry updates (feature changelog, global .specs/changelog.md, README row + Recent Activity, spec status, and the existing roadmap checkbox for Implemented closure) are written deterministically and idempotently by livespec finalize under .specs/.LOCK. The six registry-finalizing commands (/spec-specify, /spec-plan, /spec-implement, /spec-fix, /spec-stack, /spec-feature) prove the finalize.registry goal task with the verify receipt:

livespec finalize apply  --feature <slug> --command <spec-*> --entry-file <entry.md> [--status <Status>] [--retry]
livespec finalize verify --feature <slug> --command <spec-*> --json

Idempotence marker: <!-- finalize:<cmd>:<date>:<hash8> --> (identity is <cmd> + hash8; consistent re-runs are zero-write, while a replay can repair current status/roadmap drift without duplicating changelog entries). Exit codes: 0 OK · 9 BLOCKED (policy_blocked lock timeout / state_invalid hash mismatch) · 10 verify FAIL (R1/R4/R6 violations or missing marker). --retry adds backoff+jitter (~45s budget) for parallel /spec-ship. Distinct from Feature 048 run finalization (RunArtifact verification) — livespec finalize governs registry artifacts only.

Visual closure revalidates C51 under the project write lock immediately before registry decisions and writes; an idempotent return still validates current proof. Nonfinal updates do not check roadmap items.

See docs/cli-reference.md for the full contract.

Plan review configuration (.specs/semantic/config.yaml):

review_model: openai/gpt-5.4      # reviewer of goals, progressions and delivery lanes
review_max_chars: 60000           # 1000 to 200000; out of bounds is refused
review_reviewers:
  - google/gemini-3.1-pro
  - openai/gpt-5.4
review_confidence_threshold: 3.0

livespec goal render, livespec validate --progression and livespec delivery take the reviewer model and budget from --model/--review-max-chars, else from this file (review_model, else the first review_reviewers entry), and stop with review_model_required when neither names a model.

When a single reviewer returns a suspiciously empty review on a complex plan, the validator automatically cascades to the next configured reviewer. If both agree there are no issues, the plan is validated with high confidence.

---

Repository Structure

livespec/
├── README.md
├── system/
│   ├── spec-system.md              ← Core rules (install in .specs/)
│   ├── constitution-template.md    ← Constitution template
│   └── templates/
│       ├── spec-template.md
│       ├── plan-template.md
│       ├── implementation-template.md
│       ├── changelog-template.md
│       ├── project-template.md
│       ├── testing-strategy-template.md
│       └── roadmap-template.md
├── stacks/
│   └── presets/
│       ├── web-realtime.md
│       ├── web-static.md
│       └── api-rest.md
├── .agent-sync/                    ← Portable source for skills, agents, and rules
│   ├── skills/spec-*/              ← LiveSpec command skills + expectations.md
│   ├── skills/source-command-cli/  ← Codex `/cli` picker for the LiveSpec CLI
│   ├── agents/livespec-*/          ← Portable agent.yaml + prompt.md
│   └── rules/livespec/             ← Rules built by cc-hub for Claude/Codex
└── scripts/
    ├── install.sh                  ← Bootstrap global spec-init/spec-migrate skills through cc-hub
    ├── sync-agent-assets.sh        ← Sync .agent-sync assets into projects through cc-hub
    ├── link-local.sh               ← Backward-compatible wrapper around sync-agent-assets.sh
    └── init.sh                     ← Bootstrap .specs/ structure (shell)

---

License

MIT — see LICENSE

Bounded, necessary validation

Managed livespec test and execution capture share a five-minute command budget, including preparation and cleanup. Supported pytest/Cargo tests default to 2s unit, 10s integration and 30s acceptance; other frameworks explicitly report command-only enforcement. Declare justified exact-scope long cases before execution in .specs/testing/test-budgets.yaml (maximum ten minutes). Read the policy and recovery rules and necessary test scope: reuse adequate tests and stop when relevant checks pass. Pinned projects receive these guards after their explicit runtime update/migration; this change does not alter existing consumer pins.

Local Vitest execution observations

Observe an existing Node 22/local Vitest 2.1.x selection through the native test command:

livespec test --feature <feature> --execution-command '<node22> <package>/node_modules/vitest/vitest.mjs run --root <package>' --execution-observation passed --report-adapter junit

Use red for a genuinely failed supported matcher. Observations retain test and matcher outcomes and always return certified_acs=[]; they require no acceptance mapping. Feature acceptance still requires its complete existing requirement evidence. A new official goal render gives the generic implementation task its explicit passed purpose; historical goal files retain their original interpretation.

The observer uses installed local dependencies and preserves governed configuration and selections. It supports built-in sequential matchers and explicitly awaited or returned resolves/rejects assertions. Bare expect, missing matcher evidence, unawaited async assertions (including Vitest auto-await), custom matchers, concurrent tests, direct Chai, unknown options and changed inputs cannot qualify. Runtime, dependencies, configuration, lock, hooks and captured artifacts are bound to the invocation. The shared command deadline includes preparation and cleanup; framework limits can only tighten it. This is cooperative local provenance, without a same-user JavaScript sandbox.

Async consumption requires both executed JavaScript syntax and actual consumption of the exact matcher thenable: direct await, explicit return or concise-arrow return in an inline callback of a bare, unshadowed Vitest test()/it() import. Import aliases are supported. Detached .then() and Promise assimilation never establish consumption. Async helper callbacks, hooks, registration modifiers, Promise compositions and returns inside try/finally remain unsupported; use a direct inline test assertion instead.