{
  "markdown": "<p align=\"center\">\n  <img src=\"docs/picture/logo.jpg\" alt=\"SolidSpec Logo\" width=\"600\">\n  <p align=\"center\">\n    <strong>AI-Powered Software Development tool — Multi-Methodology,  CLI based</strong>\n  </p>\n  <p align=\"center\">\n    SolidSpec scaffolds your AI agents into structured development workflows. Pick the methodology that fits\n    your feature — from a quick spike to a fully-traced, intent-anchored production build — and SolidSpec\n    drives every artifact, every agent prompt, and every quality gate from idea to ship.\n  </p>\n  <p align=\"center\">\n    <a href=\"#workflows-and-methodologies\">Workflows</a> &bull;\n    <a href=\"#choosing-a-workflow\">Compare</a> &bull;\n    <a href=\"#install\">Install</a> &bull;\n    <a href=\"#parallel-fan-out-ship-gate\">Ship Gate</a> &bull;\n    <a href=\"#using-with-claude-code\">Claude Code</a> &bull;\n    <a href=\"#using-with-opencode\">OpenCode</a> &bull;\n    <a href=\"#using-with-github-copilot\">Copilot</a> &bull;\n    <a href=\"#use-cases\">Use Cases</a> &bull;\n    <a href=\"#all-commands\">Commands</a>\n  </p>\n</p>\n\n---\n\n## The Problem\n\nYou describe a feature to your AI coding agent. It generates code. But the code doesn't match what you actually needed &mdash; scope creeps, edge cases are missed, tests are written after the fact (or not at all), and there's no traceability from requirements to implementation.\n\n**SolidSpec fixes this** by inserting a structured layer between your idea and the code. Every feature gets a spec, a plan, and a task list &mdash; all versioned in your repo, all driving the AI. Which structure exactly depends on what you're building:\n\n- Shipping a quick internal tool? Use `minimal` &mdash; four artifacts, done in minutes.\n- Building a payment feature? Use `security-first` &mdash; OWASP audit gates the task list.\n- Writing a library with strict contracts? Use `tdd-driven` &mdash; real failing tests before any implementation.\n- Building a product feature with uncertain scope? Use `intent-driven` &mdash; capture the *why* first, measure it at the end.\n- Tackling a complex feature that needs structured implementation? Use `apex-driven`.\n- Need all of the above? Use `intent-apex`.\n\n**SolidSpec works with 19 AI agents** (Claude Code, Copilot, OpenCode, Gemini, Cursor, Windsurf, Codex, and more), registers slash commands in each agent's native format, and can invoke them automatically via a fully automated or mixed-mode pipeline.\n\n---\n\n## Install\n\n### Linux / macOS — one line, no Rust toolchain\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/jyjeanne/solidspec/master/scripts/install.sh | sh\n```\n\nDownloads the prebuilt binary for your platform from [GitHub Releases](https://github.com/jyjeanne/solidspec/releases) into `~/.local/bin`. Override the location with `INSTALL_DIR=/some/path`.\n\n### Any platform — with Rust installed\n\n```bash\ncargo install --git https://github.com/jyjeanne/solidspec\n```\n\nNot published to crates.io yet — SolidSpec vendors [okf-rs](https://github.com/jyjeanne/okf-rs)'s knowledge-graph crates as git dependencies (see `docs/okf-rs-integration-plan.md`), and crates.io requires every dependency to itself be a published crate. `cargo install --git` has no such restriction.\n\n### Windows\n\nDownload `solidspec-x86_64-pc-windows-msvc.zip` from the [latest release](https://github.com/jyjeanne/solidspec/releases/latest), extract it, and add the folder to your `PATH` — see below.\n\n<details>\n<summary>Build from source, or manual PATH setup</summary>\n\n```bash\ngit clone https://github.com/jyjeanne/solidspec.git\ncd solidspec\ncargo build --release\n```\n\nThe compiled binary is placed at `target/release/solidspec` (Linux/macOS) or `target\\release\\solidspec.exe` (Windows).\n\n---\n\n### Add to PATH — Linux / macOS\n\n**Option A — copy to a system directory (recommended)**\n\n```bash\nsudo cp target/release/solidspec /usr/local/bin/solidspec\n```\n\n**Option B — add the build output directory to your shell profile**\n\n```bash\n# Bash (~/.bashrc or ~/.bash_profile)\necho 'export PATH=\"$PATH:$HOME/solidspec/target/release\"' >> ~/.bashrc\nsource ~/.bashrc\n\n# Zsh (~/.zshrc)\necho 'export PATH=\"$PATH:$HOME/solidspec/target/release\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n---\n\n### Add to PATH — Windows\n\n**Option A — copy to a permanent directory, then add it to the system PATH (recommended)**\n\n```powershell\n# 1. Create a directory for CLI tools (skip if it already exists)\nNew-Item -ItemType Directory -Force -Path \"$env:USERPROFILE\\bin\"\n\n# 2. Copy the binary\nCopy-Item .\\target\\release\\solidspec.exe \"$env:USERPROFILE\\bin\\solidspec.exe\"\n\n# 3. Add the directory to the permanent user PATH (takes effect in new shells)\n[Environment]::SetEnvironmentVariable(\n    \"PATH\",\n    \"$env:PATH;$env:USERPROFILE\\bin\",\n    [EnvironmentVariableTarget]::User\n)\n```\n\n**Verify the installation:**\n\n```bash\nsolidspec --version\n```\n\n</details>\n\n---\n\n## Quick Reference — Most Used Commands\n\n```bash\n# Bootstrap a new project\nsolidspec init --here\n\n# Start a feature end-to-end (spec, plan, tasks, implement handoff — or\n# whichever phases the project's schema has; minimal by default)\nsolidspec go \"Your feature description\"\n\n# See what's ready to work on, and what to run next\nsolidspec status\n\n# Resume wherever you left off\nsolidspec continue\n\n# List every workflow schema and when to use each\nsolidspec schemas\n\n# Need a specific methodology instead of the default? Use pipeline directly:\nsolidspec pipeline --new \"Feature name\" --schema tdd-driven --no-agent\nsolidspec pipeline --new \"Feature name\" --schema security-first --no-agent\n\n# Propose a change to an existing feature (brownfield)\nsolidspec change propose \"Add social login\" --feature-id 001\n```\n\n---\n\n## Quick Start (3 steps)\n\n### 1. Initialize your project\n\n```bash\nmkdir my-app && cd my-app\nsolidspec init --here\n```\n\nSolidSpec auto-detects your AI agent (if it has a `.claude/`, `.cursor/`, ... directory or CLI already on `PATH` — create an empty one first if this is a brand-new project and you want a specific agent registered) and creates:\n- `.solidspec/` &mdash; constitution, templates, config\n- `specs/` &mdash; where feature artifacts live\n- `solidspec.toml` &mdash; project configuration, including which workflow schema this project defaults to (`minimal` unless you pass `--schema`, e.g. `solidspec init --here --schema spec-driven`)\n- Slash commands in your agent's native format: `/spcx:<schema>:new`/`:apply`/`:finalise` for every built-in workflow, reduced-schema-name namespaced (`/spcx:min:new`, `/spcx:sdd:apply`, `/spcx:tdd:finalise`, ...), plus `/spcx:explore` always — three-segment `<namespace>:<domain>:<action>` naming in Claude Code — see [Workflows and Methodologies](#workflows-and-methodologies) below for what each schema covers\n- On an existing codebase (anything already in the directory besides the files above): a native knowledge-graph bundle at `.solidspec/knowledge/` and an `okf` MCP server entry in `.mcp.json`, so agents can query the codebase instead of re-reading it cold — skipped on a fresh empty directory; run `solidspec okf generate` yourself later if you add code first and want it sooner. Once a bundle exists, `solidspec pipeline`/`go`/`continue` refresh it automatically right after every code-writing handoff (`implement`, `apex`, `tdd-tests`, `tdd-refactor` — whichever your schema uses), so it never goes stale — `solidspec analyze` cross-checks `tasks.md` against it (see below)\n\n### 2. Describe your feature\n\nIn your AI agent, run:\n\n```\n/spcx:min:new \"TODO list with CRUD operations and local storage\"\n```\n\nThis scaffolds and fills in every artifact through the implement handoff for your project's schema in one pass — `spec.md`, `plan.md`, `tasks.md` for the `minimal` default; also `clarify` and test scaffolds for `spec-driven`. (Prefer the terminal? `solidspec go \"...\"` does the same thing from the CLI, always on the project's own schema; `solidspec pipeline --new \"...\" --schema tdd-driven --no-agent` runs any schema explicitly, regardless of the project's default.)\n\n### 3. Implement and ship\n\n```\n/spcx:min:apply       # implement the tasks\n/spcx:min:finalise    # validate, review, and get a SHIP/HOLD decision\n```\n\nOr from the terminal: `solidspec continue` to resume at whatever's next, `solidspec status` any time to see where things stand.\n\n---\n\n## Workflows and Methodologies\n\nSolidSpec ships **7 built-in workflows** covering the full spectrum from lightweight to rigorous. All share the same DAG engine, schema format, agent registration, and pipeline infrastructure. Run `solidspec schemas` any time for this same list with each one's use case, from the terminal.\n\n### At a Glance\n\n| Schema | Artifacts | Methodology | Key addition over `spec-driven` |\n|--------|-----------|-------------|--------------------------------|\n| `minimal` | 4 | Lean SDD | No tests, no review — just spec → plan → tasks → implement |\n| `spec-driven` | 9 | Full SDD | Constitution gates, test scaffolds, analyze, review, ship gate |\n| `security-first` | 5 | SDD + security | Mandatory OWASP audit gates the task list |\n| `tdd-driven` | 10 | AI-TDD | Real failing tests (RED) before implementation; refactor phase after |\n| `intent-driven` | 11 | IDSD | Intent capture (WHY), evidence collection, drift detection |\n| `apex-driven` | 9 | SDD + APEX | Structured A-P-E-X implementation replaces manual handoff |\n| `intent-apex` | 11 | IDSD + APEX | Intent-anchored with APEX implementation and evidence collection |\n\n---\n\n### `minimal` — Lean Specification (default)\n\nThe fastest path from idea to implementation, and what `solidspec init` picks when `--schema` is left unset. No test scaffolds, no review phase, no ship gate. Four artifacts, minimal ceremony.\n\n```\n  spec.md → plan.md → tasks.md → implement\n```\n\n**Use when:**\n- Internal utility scripts or tooling with no ambiguity\n- Hackathon projects or time-boxed spikes\n- The requirements are fully known by the implementer\n- You want the discipline of a written spec but not the full SDD ceremony\n- You're unsure which schema to pick and want to start light — `solidspec init --schema spec-driven` (or any other schema) any time you know you need more\n\n**Avoid when:** quality gates, traceability, or external stakeholders matter — pick `spec-driven` (or a stricter schema below) instead.\n\n---\n\n### `spec-driven` — Full Specification-Driven Development\n\nThe standard SolidSpec workflow. Structured spec, architecture plan, phased tasks, test scaffolds, cross-artifact consistency check, preflight review, and a 4-lane parallel ship gate.\n\n```\n  spec → clarify → plan → tasks → tests → implement → analyze → review → ship\n```\n\n**Use when:**\n- Most greenfield features in a team or solo project\n- Adding a new capability to an existing codebase\n- You need traceability from requirements to tasks but not full intent-to-evidence traceability\n- Brownfield features (combine with `solidspec change propose` for delta specs)\n- Quality gates, traceability, or external stakeholders matter more than getting started fast\n\n---\n\n### `security-first` — Security-Gated Development\n\nIdentical to `spec-driven` through the plan phase, then adds a mandatory OWASP Top 10 security review before tasks can be generated. Security findings must be resolved — every finding becomes a mitigation task.\n\n```\n  spec → plan → security-review → tasks → implement\n```\n\n**Use when:**\n- Payment processing, billing, or financial transactions\n- Authentication, authorization, session management, or OAuth flows\n- Any feature that stores, transmits, or processes PII, credentials, or sensitive data\n- Healthcare, legal, or regulated-industry features\n- API endpoints exposed to the public internet\n- Features that modify access control or permission models\n\n**Key difference:** Tasks cannot be generated until `security-review.md` exists. This is a hard DAG dependency — it cannot be skipped.\n\n---\n\n### `tdd-driven` — AI Test-Driven Development\n\nBrings RED-GREEN-REFACTOR discipline to AI-assisted development. The agent writes real failing tests first (not scaffolds), then implements one test at a time, then refactors with all tests green. Three human-approval gates: before writing tests, before implementing, before refactoring.\n\n```\n  spec → clarify → plan → tasks\n       → tdd-tests (RED)\n       → implement (GREEN — one test at a time)\n       → tdd-refactor (REFACTOR — interface must not grow)\n       → analyze → review → ship\n```\n\n**Use when:**\n- Library code or SDK with a stable public API that multiple consumers depend on\n- Complex business logic (pricing engines, rule evaluators, state machines)\n- Code that will be maintained by a large team or refactored frequently\n- Replacing or rewriting a working system where regressions must be prevented\n- Any feature where \"all tests green\" is the contractual definition of done\n- You want the AI to prove that each behavior works before moving to the next\n\n**Key difference over `spec-driven`:**\n- `tests` (scaffold) → `tdd-tests` (real failing tests using the project's framework)\n- New `tdd-refactor` phase: the AI refactors without adding behavior\n- Agent command bodies enforce: tracer-bullet first, vertical slices, mock boundaries (only external systems), interface preservation during refactor\n\n---\n\n### `intent-driven` — IDSD (Intent-Driven Specification Development)\n\nAdds a root intent anchor before the spec and evidence collection after implementation. Every requirement traces back to the original intent. Drift is measured continuously.\n\n```\n  intent (WHY) → spec → clarify → plan → tasks → tests\n               → implement → evidence → analyze → review → ship\n```\n\n**Use when:**\n- Greenfield features with uncertain or evolving scope\n- Features subject to compliance, audit, or stakeholder approval\n- Long-lived features that will evolve over many iterations (drift detection prevents silent requirement creep)\n- The team suspects implementation has diverged from the original vision\n- You need a versioned, traceable record proving *why* each requirement exists\n\n**Key additions:**\n- `intent.md` (ICE model): Goal / Constraints / Evidence before the first spec line\n- `evidence-report.md`: per-criterion satisfaction from implemented tests\n- Intent drift score in every `solidspec analyze` run\n- Full traceability chain: `INT-001 → FR-001 → T001 → test_file`\n\n---\n\n### `apex-driven` — APEX-Enhanced SDD\n\nSDD with the APEX (Analyze-Plan-Execute-eXamine) implementation workflow replacing the manual handoff. APEX injects `spec.md + plan.md + tasks.md` as pre-loaded context and provides parallel exploration agents and adversarial code review.\n\n```\n  spec → clarify → plan → tasks → tests → apex → analyze → review → ship\n```\n\n**Use when:**\n- Complex features where the implementation itself benefits from a structured A-P-E-X cycle\n- Team-driven development where the agent's implementation choices need structured examination\n- You want to skip the manual `implement` handoff without losing structure\n\n---\n\n### `intent-apex` — Intent + APEX (Maximum Rigor)\n\nThe most comprehensive workflow: intent-anchored requirements, evidence-based validation, AND structured APEX implementation. Every requirement traces to intent; every implementation cycle is structured.\n\n```\n  intent → spec → clarify → plan → tasks → tests\n         → apex → evidence → analyze → review → ship\n```\n\n**Use when:**\n- Enterprise or product-critical features where every decision must be justifiable\n- Compliance-driven development (the evidence report is a versioned, auditable artifact)\n- Complex features that are both uncertain in scope (IDSD value) AND complex in implementation (APEX value)\n- When you need the maximum possible traceability, structure, and quality assurance\n\n---\n\n## Choosing a Workflow\n\n### Decision table\n\n| Situation | Recommended |\n|-----------|-------------|\n| Quick script or internal tool, requirements fully known | `minimal` |\n| Standard team feature, new capability, brownfield addition | `spec-driven` |\n| Payment, auth, PII, or any security-sensitive feature | `security-first` |\n| Library, SDK, or API with strict behavioral contracts | `tdd-driven` |\n| Business logic that will be refactored often | `tdd-driven` |\n| Rewriting existing working code — regressions are unacceptable | `tdd-driven` |\n| Feature with uncertain scope or evolving requirements | `intent-driven` |\n| Compliance, audit, or stakeholder-approval required | `intent-driven` |\n| Feature likely to drift from original intent over iterations | `intent-driven` |\n| Complex implementation needing structured A-P-E-X execution | `apex-driven` |\n| Regulated feature with both uncertain scope AND complex implementation | `intent-apex` |\n\n### Comparison matrix\n\n| | `minimal` | `spec-driven` | `security-first` | `tdd-driven` | `intent-driven` | `apex-driven` | `intent-apex` |\n|--|:---------:|:-------------:|:----------------:|:------------:|:---------------:|:-------------:|:-------------:|\n| **Artifacts** | 4 | 9 | 5 | 10 | 11 | 9 | 11 |\n| **Ceremony level** | Low | Medium | Medium | Medium | High | Medium | Very High |\n| **Test scaffolds** | ✗ | ✓ | ✗ | Real (RED) | ✓ | ✓ | ✓ |\n| **TDD RED-GREEN-REFACTOR** | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ |\n| **Security audit gate** | ✗ | ✗ | ✓ mandatory | ✗ | ✗ | ✗ | ✗ |\n| **Intent capture (WHY)** | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✓ |\n| **Evidence collection** | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✓ |\n| **Intent drift detection** | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✓ |\n| **APEX implementation** | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✓ |\n| **Parallel ship gate** | ✗ | ✓ | ✗ | ✓ | ✓ | ✓ | ✓ |\n| **Full trace chain** | ✗ | partial | ✗ | partial | ✓ full | partial | ✓ full |\n| **Suitable for CI gate** | ✗ | ✓ | ✗ | ✓ | ✓ | ✓ | ✓ |\n\n### Rule of thumb\n\n> Use **`minimal`** when you know exactly what to build and speed matters.\n> Use **`spec-driven`** when you need structure without overhead.\n> Use **`security-first`** when trust boundaries are at stake.\n> Use **`tdd-driven`** when contracts matter more than speed.\n> Use **`intent-driven`** when you need to prove *why* it was built.\n> Use **`apex-driven`** when the implementation itself is the hard part.\n> Use **`intent-apex`** when all of the above apply.\n\n---\n\n## SDD vs IDSD vs TDD: Which to Choose?\n\n### Where SDD alone falls short\n\n| SDD limitation | Impact |\n|----------------|--------|\n| Spec describes *what* but not *why* | Implementations can satisfy requirements while missing the actual user need |\n| No measurement of whether the code achieves the original goal | Drift goes undetected until user feedback |\n| Test scaffolds are stubs, not real failing tests | AI can implement without ever running a test |\n| \"All tests green\" can mask intent drift | Technically correct, functionally wrong |\n\n### What IDSD adds\n\n| IDSD addition | Benefit |\n|---------------|---------|\n| `intent.md` (ICE model) | Anchors the *why* before the *what* |\n| Intent drift score | `solidspec analyze` reports % of evidence criteria not yet covered |\n| Evidence-based validation | Maps each evidence criterion to implemented tests |\n| Full traceability chain | `INT-001 → FR-001 → T001 → test_file.md` |\n| `IntentAlignment` review dimension | Scores 0–10 in `review-report.md` |\n\n### What TDD adds\n\n| TDD addition | Benefit |\n|--------------|---------|\n| Real failing tests before implementation | Agent cannot skip to code — tests must compile and fail first |\n| Tracer-bullet first cycle | Most critical behavior proved end-to-end before expanding |\n| One-test-at-a-time GREEN phase | No bulk implementation; each behavior proven in isolation |\n| Dedicated REFACTOR phase | Code quality improved without adding behavior; tests protect against regression |\n| Mock boundary enforcement | Only external systems mocked; internal collaborators are never mocked |\n\n### IDSD Quick Start\n\n```bash\n# One command runs the full IDSD pipeline (scaffold only, no agent needed)\nsolidspec pipeline --new \"Allow users to manage tasks\" --schema intent-driven --no-agent\n```\n\nOr step by step:\n\n```bash\nsolidspec intent \"Allow users to manage tasks\"\nsolidspec specify \"Task manager with CRUD and local persistence\"\nsolidspec plan 001\nsolidspec tasks 001\nsolidspec tests 001\nsolidspec implement 001\nsolidspec evidence 001\nsolidspec analyze 001\n```\n\nFor a complete walkthrough, see [docs/idsd-workflow-guide.md](docs/idsd-workflow-guide.md).\n\n### TDD Quick Start\n\n```bash\n# Full TDD pipeline scaffold\nsolidspec pipeline --new \"Authentication service\" --schema tdd-driven --no-agent\n```\n\nOr step by step (human-approval gates at tdd-tests, implement, tdd-refactor):\n\n```bash\nsolidspec specify \"Auth service with JWT and refresh tokens\"\nsolidspec plan 001\nsolidspec tasks 001\n\n# RED phase — agent writes real failing tests from acceptance criteria\nsolidspec tdd-tests 001\n# Review tdd-red-report.md, then open your agent: /solidspec-tdd-tests\n\n# GREEN phase — implement one failing test at a time\nsolidspec implement 001\n# Agent follows the cycle table in tdd-red-report.md\n\n# REFACTOR phase — improve without changing behavior\nsolidspec tdd-refactor 001\n# Agent produces tdd-refactor-report.md with per-change audit\n```\n\n---\n\n## Parallel Fan-Out Ship Gate\n\n`solidspec ship` runs four specialized review lanes **concurrently** and aggregates their scores into a single binary **SHIP / HOLD** decision. Each lane invokes a dedicated AI agent with a deep-focus prompt limited to its review cluster, then extracts a 0–100 score from the agent output.\n\n```\n  solidspec ship 001\n                    │\n        ┌───────────┼───────────┐───────────┐\n        ▼           ▼           ▼           ▼\n   Code Review  Security    Test        Performance\n   (completeness  Audit     Coverage    (pagination,\n    clarity,     (OWASP,    (GWT        caching,\n    consistency)  PII,       coverage,   load)\n                  auth)      traceability)\n        │           │           │           │\n        └───────────┴───────────┴───────────┘\n                        │\n               aggregate_results()\n                        │\n                ┌───────┴────────┐\n                │  SHIP ✓        │  HOLD ✗\n                │  all lanes ≥   │  any lane < threshold\n                │  threshold     │  OR critical finding\n                │                │  in security lane\n                └───────┬────────┘\n                        │\n              ship-report.md\n              <!-- ship: true|false -->\n```\n\n### Quick start\n\n```bash\n# Run all 4 lanes with heuristics (no AI agent needed)\nsolidspec ship --no-agent\n\n# Run with AI agents (configured in solidspec.toml)\nsolidspec ship 001\n\n# Preview the planned lanes without executing\nsolidspec ship --dry-run\n\n# CI gate — exit 1 on HOLD\nsolidspec ship --fail-on-hold\n\n# Run only selected lanes\nsolidspec ship --lane code,security\n\n# Ignore timed-out lanes (treat as non-blocking for CI)\nsolidspec ship --ignore-timeout --fail-on-hold\n```\n\n### Review lanes\n\n| Lane | Focus | Default threshold |\n|------|-------|-------------------|\n| `code` | Completeness · Clarity · Consistency · Maintainability | 70 |\n| `security` | OWASP Top 10 · PII handling · Auth constraints · Rate limiting | 80 |\n| `tests` | GWT scenario coverage · Test scaffold status · Edge-case coverage | 70 |\n| `perf` | Pagination · Caching strategy · Unbounded queries · Load targets | 60 |\n\nThe security lane enforces an **unconditional block** on any `CRITICAL` finding, regardless of score or `block_on_critical` config.\n\n### Score extraction\n\nEach lane prompt instructs the agent to end its response with `SCORE: N` (0–100). The last `SCORE:` match wins. If the agent omits the score line, a fallback counts `SEVERITY: LEVEL` keywords and applies the penalty formula: `100 - 10×CRITICAL - 5×HIGH - 2×MEDIUM - 0.5×LOW`.\n\n`--no-agent` mode runs `solidspec review` heuristics and filters findings to each lane's dimension cluster, so scores are never placeholder zeros — a clean spec scores 100, a flawed one is penalized.\n\n### HOLD triggers (in priority order)\n\n1. `TimedOut` lane (skip with `--ignore-timeout`)\n2. `Failed` lane (agent crash or not available)\n3. `CRITICAL` finding in the `security` lane (always blocks)\n4. `CRITICAL` finding in any lane when `block_on_critical = true`\n5. Lane score below its threshold\n\n### Configuration (`solidspec.toml`)\n\n```toml\n[fan_out]\n# Per-lane agent overrides (falls back to [ai].default_agent)\ncode_agent     = \"claude\"\nsecurity_agent = \"gemini\"\ntests_agent    = \"claude\"\nperf_agent     = \"claude\"\n\n# Pass/fail thresholds (0–100)\ncode_threshold     = 70\nsecurity_threshold = 80\ntests_threshold    = 70\nperf_threshold     = 60\n\n# Block on any Critical finding in any lane (not just security)\nblock_on_critical = true\n\n# Per-lane timeout in seconds\ntimeout = 300\n```\n\n### CI / CD integration\n\n```yaml\n# GitHub Actions example\n- name: Ship gate\n  run: solidspec ship --fail-on-hold --ignore-timeout\n  # Exits 0 on SHIP, 1 on HOLD\n```\n\n```bash\n# Pre-merge hook\nsolidspec ship --fail-on-hold --lane security,code && git push\n```\n\n---\n\n## Using with Claude Code\n\nClaude Code gets slash commands automatically registered in `.claude/commands/`.\n\n### Setup\n\n```bash\nmkdir -p .claude\nsolidspec init --here\n```\n\n### Available slash commands\n\nEvery built-in workflow gets 3 commands that chain the per-phase ones underneath, namespaced `/spcx:<schema>:<action>` (reduced schema name : phase, `<namespace>:<domain>:<action>`-style) — run any workflow's DAG-specific steps without touching `solidspec.toml`'s stored default:\n\n| Slash Command | What it does |\n|---------------|-------------|\n| `/spcx:min:new` / `:apply` / `:finalise` | Lean spec → plan → tasks → implement, nothing after |\n| `/spcx:sdd:new` / `:apply` / `:finalise` | Full SDD: spec → clarify → plan → tasks → tests → implement → analyze → review → ship |\n| `/spcx:sec:new` / `:apply` / `:finalise` | Adds a mandatory OWASP-audit gate before tasks |\n| `/spcx:tdd:new` / `:apply` / `:finalise` | Real failing tests (RED) before implementation, refactor phase after |\n| `/spcx:intent:new` / `:apply` / `:finalise` | IDSD: intent capture, evidence collection, drift detection |\n| `/spcx:apex:new` / `:apply` / `:finalise` | Structured APEX (Analyze-Plan-Execute-eXamine) implementation |\n| `/spcx:iapex:new` / `:apply` / `:finalise` | Intent-anchored with APEX and evidence collection |\n| `/spcx:explore` | Exploratory research and discussion — no files written, schema-independent |\n\nSee [Workflows and Methodologies](#workflows-and-methodologies) for what each schema's artifacts actually are — every command above is generated straight from that schema's own DAG (`src/agents/spcx.rs`), so `/spcx:tdd:apply` really does walk you through RED → implement → REFACTOR and `/spcx:min:finalise` really does say there's nothing left to run. `solidspec schemas` prints every schema's `/spcx:<short>:*` commands alongside its description, so you never have to guess a short name.\n\nA project running a fully custom-named schema (`.solidspec/workflows/<name>/schema.yaml`) gets `/spcx:<name>:*` too — registration and `solidspec schemas` both key off the schema's actual identifier (the directory name / `--schema` value), never a `schema.yaml`'s own possibly-stale internal `name:` field, so a custom schema still gets its commands even if that field was left unedited after copying an existing one. The one exception: if the identifier happens to reduce to the same short name as a built-in (checked case-insensitively, since `.claude/commands/spcx/<short>/` is a real directory and macOS/Windows default to case-insensitive filesystems — e.g. a custom schema literally named `tdd` or `TDD`), `solidspec init`/`upgrade` fail loudly with a rename suggestion instead of silently overwriting the built-in's commands.\n\n`/spcx:<short>:apply`'s generated body also reminds the agent to run `solidspec okf generate` before moving on, when a knowledge-graph bundle exists — the interactive flow edits files directly with no `solidspec pipeline` subprocess call in between (unlike `go`/`continue`/`pipeline`, which refresh an existing bundle automatically right after implement/apex/tdd-tests/tdd-refactor), so without that reminder a `/spcx:<short>:finalise` → `solidspec analyze` run right after would flag the agent's own new code as \"orphaned\" against a stale graph.\n\nEvery individual phase also has its own command, for explicit control or other schemas:\n\n| Slash Command | What it does |\n|---------------|-------------|\n| `/solidspec-specify` | Create a new feature spec from a description |\n| `/solidspec-clarify` | Resolve ambiguities in a spec |\n| `/solidspec-plan` | Generate architecture plan + supporting docs |\n| `/solidspec-security-review` | Deepen the OWASP Top 10 heuristic audit of plan.md (security-first workflow) |\n| `/solidspec-tasks` | Generate phased task breakdown |\n| `/solidspec-tests` | Generate test scaffolds from acceptance scenarios |\n| `/solidspec-tdd-tests` | Write real failing tests — TDD RED phase |\n| `/solidspec-implement` | Execute tasks from the breakdown |\n| `/solidspec-tdd-refactor` | Refactor while keeping all tests GREEN |\n| `/solidspec-analyze` | Validate cross-artifact consistency |\n| `/solidspec-review` | Review spec quality with preflight heuristics |\n| `/solidspec-checklist` | Generate quality validation checklist |\n\n### Step-by-step with Claude Code\n\nThe short way:\n\n```\n/spcx:min:new Simple TODO app with add, edit, delete, and local storage\n/spcx:min:apply\n/spcx:min:finalise\n```\n\nOr one phase at a time, for explicit control:\n\n**Step 1** &mdash; Specify your feature:\n\n```\n/solidspec-specify Simple TODO app with add, edit, delete, and local storage\n```\n\n**Step 2** &mdash; Plan the architecture:\n\n```\n/solidspec-plan\n```\n\n**Step 3** &mdash; Generate tasks:\n\n```\n/solidspec-tasks\n```\n\n**Step 4** &mdash; Build it:\n\n```\n/solidspec-implement\n```\n\n**Step 5** &mdash; Validate:\n\n```\n/solidspec-analyze\n```\n\n---\n\n## Using with OpenCode\n\nOpenCode gets skills registered as directories in `.opencode/skills/`.\n\n```bash\nmkdir -p .opencode\nsolidspec init --here\n```\n\nSkills are created at `.opencode/skills/solidspec-*/SKILL.md`. Usage is identical to Claude Code but with OpenCode's `/skill-name` format.\n\n---\n\n## Using with GitHub Copilot\n\nCopilot gets `.agent.md` command files in `.github/agents/` with companion `.prompt.md` files in `.github/prompts/`.\n\n```bash\nmkdir -p .github\nsolidspec init --here\n```\n\n---\n\n## Using Multiple Agents Together\n\nSolidSpec registers commands for **all detected agents simultaneously**. If your project has both `.claude/` and `.opencode/`:\n\n```bash\nmkdir .claude .opencode\nsolidspec init --here\n```\n\nBoth agents get the same commands and work from the same spec artifacts. The artifacts in `specs/` are agent-agnostic — any agent can read and build from them.\n\n### Automated multi-agent pipeline\n\n```bash\n# Configure agent assignments in solidspec.toml, then:\nsolidspec pipeline --new \"Todo list REST API\" --auto\nsolidspec pipeline --new \"Payment checkout\" --schema tdd-driven --auto\nsolidspec pipeline --new \"Auth feature\" --schema intent-driven --auto\n```\n\n---\n\n## Use Cases\n\n### Use Case 1: Standard greenfield feature (spec-driven)\n\nYou're starting a personal finance tracker. Full structure, test scaffolds, review, ship gate.\n\n```bash\nmkdir finance-tracker && cd finance-tracker\nmkdir .claude\nsolidspec init --here\n\nsolidspec specify \"Dashboard showing income, expenses, and monthly balance\"\nsolidspec plan 001\nsolidspec tasks 001\n# In Claude Code: /solidspec-implement, /solidspec-analyze\nsolidspec ship --no-agent    # SHIP/HOLD decision\n```\n\n---\n\n### Use Case 2: Library or API with strict contracts (tdd-driven)\n\nYou're building an authentication library that multiple services will depend on. Behavioral contracts must be precise and regression-free.\n\n```bash\nsolidspec pipeline --new \"JWT authentication library\" --schema tdd-driven --no-agent\n```\n\nThe pipeline scaffolds:\n1. `spec.md` — acceptance criteria become the exact test behaviors\n2. `plan.md` — interface design and mock boundaries documented\n3. `tasks.md` — per-task AC links for the one-test-one-impl cycle\n4. `tdd-red-report.md` — scaffold for real failing tests (agent fills in)\n5. `tests/` — empty directory for the RED-phase test files\n6. `tdd-refactor-report.md` — scaffold for the REFACTOR phase audit\n\n**Step by step:**\n\n```bash\n# Prepare the spec and plan\nsolidspec specify \"JWT library with sign, verify, refresh\"\nsolidspec plan 001\nsolidspec tasks 001\n\n# RED phase: open agent and write all failing tests first\nsolidspec tdd-tests 001\n# In Claude Code: /solidspec-tdd-tests\n# Agent: designs interfaces, writes tracer bullet test (most critical AC),\n#         writes remaining tests — all must FAIL at end of this phase\n\n# GREEN phase: implement one test at a time\nsolidspec implement 001\n# Agent follows the cycle table in tdd-red-report.md: one failing test targeted,\n# minimal code written, full suite re-run, repeat\n\n# REFACTOR phase: clean up without adding behavior\nsolidspec tdd-refactor 001\n# Agent produces tdd-refactor-report.md with before/after for each change\n# Every change followed by a full test run — all GREEN required\n\nsolidspec analyze 001\nsolidspec ship --no-agent\n```\n\n---\n\n### Use Case 3: Payment or auth feature (security-first)\n\nYou're adding Stripe integration. OWASP audit required before any code is written.\n\n```bash\nsolidspec pipeline --new \"Stripe payment integration\" --schema security-first --no-agent\n```\n\nThe DAG enforces: `tasks.md` cannot be generated until `security-review.md` exists. The security review artifact contains OWASP findings; every finding becomes a mandatory mitigation task.\n\n```bash\nsolidspec specify \"Checkout with Stripe, subscription billing, refunds\"\nsolidspec plan 001\n# Plan is reviewed by AI for OWASP Top 10 issues\nsolidspec pipeline 001 --from security-review --schema security-first --no-agent\n# Now check security-review.md: Critical/High findings must be resolved\nsolidspec tasks 001 --schema security-first   # Blocked until security-review.md exists\nsolidspec implement 001\n```\n\n`--schema security-first` is required on `solidspec tasks` for the gate to apply unless the project was already initialized with `solidspec init --schema security-first` (which makes it the project's stored default — see `solidspec.toml`'s `[pipeline].schema`). Without either, `tasks` falls back to whatever schema *is* the project's default (`spec-driven` for a pre-existing project, `minimal` for one initialized without `--schema`) — neither has a security-review dependency, so `tasks.md` would be generated regardless of whether `security-review.md` exists.\n\n---\n\n### Use Case 4: Product feature with uncertain scope (intent-driven)\n\nYou're building a notification system for a SaaS product. The scope is unclear; stakeholders have varying expectations. You need a traceable record.\n\n```bash\n# Capture the WHY before any requirements are written\nsolidspec intent \"Allow users to receive timely notifications across channels\"\n# Fill in intent.md: Goal (one sentence), Constraints, Evidence criteria, Risks\n\nsolidspec specify \"Real-time notification system with email, push, in-app\"\nsolidspec plan 001\nsolidspec tasks 001\nsolidspec tests 001\n# Implement (handoff to AI agent)\n\nsolidspec evidence 001        # per-criterion satisfaction from implemented tests\nsolidspec evidence 001 --update  # rewrite intent.md Status automatically\nsolidspec analyze 001         # drift score + INT→FR→T traceability tree\nsolidspec review 001\nsolidspec ship 001 --no-agent\n```\n\n---\n\n### Use Case 5: Adding SolidSpec to an existing project\n\nYou have a Node.js API that's been running for 6 months. New features going forward should be structured.\n\n```bash\ncd ~/projects/my-existing-api\nmkdir -p .claude\nsolidspec init --here   # adds .solidspec/, specs/ — existing code untouched\n\n# Edit the constitution to match your team's actual patterns\n$EDITOR .solidspec/constitution.md\n\n# New feature — reference existing models and patterns in the spec\nsolidspec specify \"Real-time notification system with email, push, and in-app channels\"\nsolidspec plan 001\nsolidspec tasks 001\n# /solidspec-implement in Claude Code\n```\n\n---\n\n### Use Case 6: Ship gate before merging a feature\n\nQuick smoke check, then full AI review, then CI gate.\n\n```bash\n# Heuristic-only run — instant, no agent tokens consumed\nsolidspec ship --no-agent\n# Fix any HOLD findings, then:\n\n# Full AI review\nsolidspec ship 001\n\n# CI gate\nsolidspec ship --fail-on-hold --ignore-timeout\n```\n\nAdd to CI:\n```yaml\n- name: Ship gate\n  run: solidspec ship --fail-on-hold --ignore-timeout\n```\n\n---\n\n### Use Case 7: Complex enterprise feature (intent-apex)\n\nYou're building a compliance reporting module. Scope is uncertain, implementation is complex, and every decision must be auditable.\n\n```bash\nsolidspec pipeline --new \"Compliance reporting engine\" --schema intent-apex --no-agent\n```\n\nThe `intent-apex` pipeline provides:\n- `intent.md` — Goal, Constraints, Evidence criteria anchoring everything\n- Full SDD spec, plan, tasks\n- APEX structured implementation with parallel exploration agents\n- `evidence-report.md` — per-criterion satisfaction from APEX output\n- Full `INT→FR→T→code` traceability chain\n- Parallel ship gate with 4 review lanes\n\n---\n\n## Multi-Agent Pipeline\n\nRun the entire workflow with one command, using different AI agents per phase.\n\n```toml\n# solidspec.toml\n[pipeline]\nspecify = \"claude\"\nplan    = \"claude\"\ntasks   = \"claude\"\ntests   = \"claude\"\nimplement = \"opencode\"\nanalyze = \"claude\"\nreview  = \"claude\"\n```\n\n```bash\n# Full spec-driven pipeline\nsolidspec pipeline --new \"User auth with OAuth\" --auto\n\n# TDD pipeline\nsolidspec pipeline --new \"User auth with OAuth\" --schema tdd-driven --auto\n\n# IDSD pipeline\nsolidspec pipeline --new \"User auth with OAuth\" --schema intent-driven --auto\n\n# Partial pipeline\nsolidspec pipeline 001 --from plan --to tasks\n\n# Preview without executing\nsolidspec pipeline 001 --dry-run --schema tdd-driven\n\n# Scaffold only — generate templates without invoking AI agents\nsolidspec pipeline --new \"Feature name\" --no-agent --schema security-first\n```\n\n### Pipeline phases per schema\n\n| Schema | Phases (in order) |\n|--------|-------------------|\n| `minimal` | specify → plan → tasks → implement |\n| `spec-driven` | specify → clarify → plan → tasks → tests → implement → analyze → review |\n| `security-first` | specify → plan → security-review → tasks → implement |\n| `tdd-driven` | specify → clarify → plan → tasks → tdd-tests → implement → tdd-refactor → analyze → review |\n| `intent-driven` | intent → specify → clarify → plan → tasks → tests → implement → evidence → analyze → review |\n| `apex-driven` | specify → clarify → plan → tasks → tests → apex → analyze → review |\n| `intent-apex` | intent → specify → clarify → plan → tasks → tests → apex → evidence → analyze → review |\n\n`ship` is available as a separate command (`solidspec ship`) for all schemas that include it in their DAG.\n\n### Execution modes\n\n```\nPipeline: 001-todo-api [fully automated]     # All agents have CLI support\nPipeline: 001-todo-api [mixed mode]          # Some need manual handoff\nPipeline: 001-todo-api [scaffold-only]       # --no-agent flag used\n```\n\n---\n\n## Spec-to-Test Generation\n\nGenerate runnable test scaffolds from your spec's acceptance scenarios (`spec-driven`, `intent-driven`, `apex-driven`):\n\n```bash\nsolidspec tests 001\n# Detected: Jest (JavaScript)\n# Parsed: 6 acceptance scenarios from 4 user stories\n# Generated: 4 test files\n```\n\nAuto-detects your test framework from project files (Jest, Vitest, pytest, cargo test, Go, generic). Each test has Given/When/Then comments and a failing body.\n\n**TDD mode** (`tdd-driven`) uses `solidspec tdd-tests` instead — the agent writes actual, framework-specific failing tests from acceptance criteria. The difference:\n\n| `tests` (SDD) | `tdd-tests` (TDD) |\n|---------------|-------------------|\n| Scaffold with TODO body | Real assertions that fail because code is absent |\n| Agent fills in later | Agent must run the tests; all must FAIL before moving on |\n| Any order | Tracer bullet first, remaining in AC order |\n| No interface design step | Agent designs interfaces before writing any test |\n\n---\n\n## Generated Artifacts\n\n### `spec-driven` / `intent-driven`\n\n```\nspecs/001-feature-name/\n  spec.md                  # User stories, requirements, acceptance criteria\n  plan.md                  # Architecture plan with constitution gates\n  tasks.md                 # Phased task breakdown\n  tests/                   # Test scaffolds from acceptance scenarios\n  analysis-report.md       # Cross-artifact consistency report\n  review-report.md         # Preflight heuristic review report\n  ship-report.md           # Fan-out SHIP/HOLD decision\n  intent.md                # (IDSD only) ICE model — Goal/Constraints/Evidence\n  evidence-report.md       # (IDSD only) per-criterion satisfaction\n  pipeline-log.md          # Pipeline execution log\n```\n\n### `tdd-driven`\n\n```\nspecs/001-feature-name/\n  spec.md\n  plan.md\n  tasks.md\n  tdd-red-report.md        # Interface design + tracer bullet + cycle table + quality checklist\n  tests/                   # Real failing tests (RED phase output)\n  tdd-refactor-report.md   # Per-change audit: refactor type, before/after, test result\n  analysis-report.md\n  review-report.md\n  ship-report.md\n```\n\n### `security-first`\n\n```\nspecs/001-feature-name/\n  spec.md\n  plan.md\n  security-review.md       # OWASP audit — findings by severity\n  tasks.md                 # Every finding has a mitigation task\n```\n\n### Project-level (all schemas)\n\n```\n.solidspec/knowledge/       # OKF knowledge-graph bundle (existing codebase only — see Quick Start)\n.mcp.json                   # okf MCP server entry (Claude Code)\n```\n\n`analysis-report.md` gains a \"Structural cross-check (okf-rs)\" section whenever `.solidspec/knowledge/` exists — it's the one part of `analyze`'s output that's about the codebase's knowledge graph, not `tasks.md`'s own text.\n\n---\n\n## Agent Guardrails\n\nEvery command and pipeline prompt includes built-in guardrails:\n\n| Agent excuse | Built-in rebuttal |\n|-------------|-------------------|\n| \"I'll add tests after\" | Tests written after cover 30% fewer edge cases |\n| \"This spec section is boilerplate\" | Every section serves a purpose — empty = incomplete |\n| \"The constitution check is unnecessary here\" | Constitution gates are NON-NEGOTIABLE |\n| \"I can just infer the missing requirements\" | Inferred requirements diverge — make them explicit |\n| \"It works — ship it\" | \"It works\" is not a review |\n| \"I'll update the docs later\" | Docs and code rot at different rates |\n\nTDD-specific guardrails:\n\n| TDD excuse | Built-in rebuttal |\n|------------|-------------------|\n| \"I'll write all tests first then all code\" | That is horizontal slicing — DO NOT DO THIS |\n| \"The test passes unexpectedly\" | STOP — record in tdd-red-report.md and investigate before proceeding |\n| \"I'll mock the internal service\" | Mock ONLY external systems — never your own modules |\n| \"I'll add this public method during refactor\" | Interface must not grow — FORBIDDEN |\n\n---\n\n## DAG-Based Workflow (Schema-Driven)\n\nSolidSpec uses a **DAG (Directed Acyclic Graph)** artifact engine. Workflows are defined as dependency graphs in YAML schema files:\n\n```yaml\n# schemas/tdd-driven/schema.yaml (excerpt)\nartifacts:\n  - id: tdd-tests\n    generates: [\"tests/\", \"tdd-red-report.md\"]\n    requires: [\"spec\", \"tasks\"]\n  - id: implement\n    generates: [\"tasks.md\"]\n    requires: [\"tdd-tests\"]\n  - id: tdd-refactor\n    generates: [\"tdd-refactor-report.md\"]\n    requires: [\"implement\"]\n```\n\n### Workflow status at a glance\n\n```bash\nsolidspec status 001 --schema tdd-driven\n\n# Feature: 001-auth  |  Schema: tdd-driven (built-in)\n# 10 artifacts, 3 complete, 1 ready\n#\n# #   Artifact       Status          Depends On\n# ─────────────────────────────────────────────────\n# 1   spec           ✓ done          —\n# 2   clarify        ✓ done          spec\n# 3   plan           ✓ done          spec\n# 4   tasks          ▶ ready         spec, plan\n# 5   tdd-tests      ⏸ blocked       spec, tasks\n# 6   implement      ⏸ blocked       tdd-tests\n# 7   tdd-refactor   ⏸ blocked       implement\n# ...\n```\n\n### Custom workflows\n\nDrop a `schema.yaml` in `.solidspec/workflows/<name>/` and use it via `--schema`:\n\n```bash\nsolidspec status 001 --schema custom\nsolidspec pipeline 001 --schema custom\n```\n\n---\n\n## Change-Based Workflow (Delta Specs)\n\nFor **brownfield modifications** — changing existing features without rewriting the entire spec:\n\n```bash\n# Propose a change to an existing feature\nsolidspec change propose \"Add social login\" --feature-id 001\n\n# List active changes\nsolidspec change list --feature-id 001\n\n# Archive when done (merges deltas into main spec)\nsolidspec change archive add-social-login --feature-id 001\n```\n\nDelta specs describe only what changed (ADDED/MODIFIED/REMOVED requirements). On archive, SolidSpec merges deltas into `spec.md` automatically.\n\n---\n\n## Project Constitution\n\nEvery SolidSpec project gets a `constitution.md` defining architectural principles:\n\n| Gate | What it checks |\n|------|---------------|\n| **Simplicity** | Max 3 projects, no speculative features |\n| **Anti-Abstraction** | Use frameworks directly, no wrapper layers |\n| **Integration-First** | Contract tests before implementation, real services over mocks |\n\nThe `plan` command evaluates these gates automatically.\n\n---\n\n## Project Context Configuration\n\n```toml\n# solidspec.toml\n[context]\ndescription = \"\"\"\nWe use Rust edition 2024.\nTesting: inline #[cfg(test)] mod per file.\nArchitecture: strict cli/core layering.\n\"\"\"\n\n[context.rules]\nspec = \"Use **FR-###**: format. Every user story needs Given/When/Then.\"\nplan = \"Document decisions with rationale. Complete the Constitution Check.\"\ntasks = \"Tasks under 2h. Mark parallel-safe with [P].\"\nimplement = \"One task at a time. Update checkboxes as you go.\"\nreview = \"Check for placeholders, ambiguous language, traceability gaps.\"\n```\n\n---\n\n## All Commands\n\n### Core workflow commands\n\nThese per-phase commands are what `go`/`continue`/`pipeline` (and, in Claude Code, `/spcx:<schema>:new`/`:apply`/`:finalise`) run under the hood. They're hidden from `solidspec --help` to keep the top-level surface small, but every one of them still works exactly as documented here — useful for scripting a single phase or debugging one in isolation.\n\n| Command | Description |\n|---------|-------------|\n| `solidspec init [name]` | Initialize project with constitution, templates, agent commands (`--schema`, default `minimal`; on an existing codebase, also generates a knowledge-graph bundle and registers it as an MCP server — see below) |\n| `solidspec specify <desc>` | Create feature spec with user stories and quality checklist |\n| `solidspec clarify [id]` | Resolve `[NEEDS CLARIFICATION]` markers |\n| `solidspec plan [id]` | Generate plan + research + data model + contracts |\n| `solidspec security-review [id]` | Run a no-agent OWASP Top 10 heuristic audit of plan.md/spec.md; writes `security-review.md` (`security-first` schema, `--dry-run`) |\n| `solidspec tasks [id]` | Generate phased task breakdown with `[P]` parallel markers (`--schema` enforces DAG gates, e.g. security-first's security-review requirement) |\n| `solidspec tests [id]` | Generate test scaffolds from Given/When/Then scenarios (`--framework`) |\n| `solidspec implement [id]` | Execute tasks with hook support |\n| `solidspec analyze [id]` | Validate consistency with severity levels; trace tree and drift in IDSD mode; cross-checks `tasks.md` against the project's OKF knowledge graph if one exists (alias: `validate`) |\n| `solidspec review [id]` | Review spec quality with dimension scoring |\n| `solidspec checklist [id]` | Generate/append quality checklists |\n\n### TDD commands\n\n| Command | Description |\n|---------|-------------|\n| `solidspec tdd-tests [id]` | Write real failing tests from acceptance criteria (TDD RED phase). Creates `tdd-red-report.md` with interface design, tracer bullet, cycle table, and quality checklist. |\n| `solidspec tdd-refactor [id]` | Scaffold the REFACTOR phase report. Requires `tdd-red-report.md`. Produces `tdd-refactor-report.md` with refactor candidates checklist and change audit table. |\n\nBoth commands accept `--dry-run` (print scaffold without writing files) and an optional `feature-id` positional argument.\n\n### IDSD commands\n\n| Command | Description |\n|---------|-------------|\n| `solidspec intent <title>` | Capture intent using the ICE model (`intent.md`). IDSD phase 0. |\n| `solidspec evidence [id]` | Cross-reference evidence criteria against implemented tests. Writes `evidence-report.md`. Add `--update` to rewrite `intent.md` Status automatically. |\n\n### Pipeline and status commands\n\n| Command | Description |\n|---------|-------------|\n| `solidspec go \"desc\"` | Start a feature end-to-end on the default schema — shorthand for `pipeline --new \"desc\" --auto` |\n| `solidspec continue [id]` | Resume the current (or given) feature at whatever phase is next — shorthand for `pipeline --auto` |\n| `solidspec schemas` | List every workflow schema, its use case, and its `/spcx:<short>:*` slash commands |\n| `solidspec pipeline [id]` | Run multi-agent pipeline (`--new`, `--from`, `--to`, `--only`, `--auto`, `--no-agent`, `--schema`, `--force`, `--dry-run`) — full control, any schema |\n| `solidspec status [id]` | Show artifact completion status (DAG-based, `--schema`) and what to run next; intent drift in IDSD mode |\n| `solidspec ship [id]` | Run parallel fan-out review (4 concurrent AI lanes) → `SHIP` / `HOLD` decision (`--lane`, `--no-agent`, `--fail-on-hold`, `--dry-run`, `--timeout`, `--ignore-timeout`) |\n\n### Project management commands\n\n| Command | Description |\n|---------|-------------|\n| `solidspec change <cmd>` | Manage changes: `propose \"Title\"`, `list`, `archive <slug>` (`--feature-id`) |\n| `solidspec preset <cmd>` | Manage presets (`add`, `remove`, `list`, `search`, `info`) |\n| `solidspec extension <cmd>` | Manage extensions (`add`, `remove`, `enable`, `disable`, `list`) |\n| `solidspec okf <cmd>` | Generate/validate an OKF knowledge-graph bundle natively (`generate`, `validate`) — see [`extensions/okf/`](extensions/okf/) |\n| `solidspec upgrade` | Refresh templates + agent commands after update |\n| `solidspec completions <shell>` | Generate shell completions (bash, zsh, fish, powershell) |\n| `solidspec check` | Verify system prerequisites |\n\nFeature ID is auto-detected from git branch or latest spec if omitted.\n\n`solidspec init` already generates this bundle automatically for an existing codebase (see step 1 above) —\nno extension needed for that. A bundled example extension at [`extensions/okf/`](extensions/okf/) exists\nfor the same generation via its `after_init` hook on a project that skipped it (e.g. `init` ran before any\ncode existed) or wants it to fire again on a later `init` re-run; install into a project with\n`solidspec extension add extensions/okf --dev`. Either way it's the same native `solidspec okf\ngenerate`/`validate` commands (vendored library crates — no external binary) so AI agents can query the\nbundle instead of re-reading files cold.\n\n---\n\n## Supported AI Agents (19)\n\n| Agent | Directory | Format |\n|-------|-----------|--------|\n| Claude Code | `.claude/commands/` | Markdown |\n| OpenCode | `.opencode/skills/` | Markdown (SKILL.md) |\n| GitHub Copilot | `.github/agents/` | Markdown + `.prompt.md` |\n| Gemini CLI | `.gemini/commands/` | TOML |\n| Cursor | `.cursor/commands/` | Markdown |\n| Windsurf | `.windsurf/workflows/` | Markdown |\n| Codex CLI | `.codex/prompts/` | Markdown |\n| Kiro CLI | `.kiro/prompts/` | Markdown |\n| Kimi Code | `.kimi/skills/` | Markdown (directory-based) |\n| Tabnine CLI | `.tabnine/agent/commands/` | TOML |\n| Qwen Code | `.qwen/commands/` | Markdown |\n| Kilo Code | `.kilocode/workflows/` | Markdown |\n| Auggie CLI | `.augment/commands/` | Markdown |\n| Roo Code | `.roo/commands/` | Markdown |\n| CodeBuddy | `.codebuddy/commands/` | Markdown |\n| Qoder CLI | `.qoder/commands/` | Markdown |\n| Amp | `.agents/commands/` | Markdown |\n| SHAI | `.shai/commands/` | Markdown |\n| IBM Bob | `.bob/commands/` | Markdown |\n\n---\n\n## Configuration\n\n### `solidspec.toml`\n\n```toml\n[project]\nname = \"my_project\"\nversion = \"0.1.0\"\n\n[ai]\ndefault_agent = \"claude\"\n\n[pipeline]\n# The project's default workflow — set by 'solidspec init --schema <name>'\n# (\"minimal\" if omitted). go/continue/status/tasks/pipeline all fall back\n# to this when --schema is left unset.\nschema = \"minimal\"\n\n[git]\nauto_branch = true\nauto_commit = true\n\n[context]\ndescription = \"We use Rust edition 2024 with strict layering.\"\n\n[fan_out]\nsecurity_agent    = \"gemini\"\nsecurity_threshold = 80\nblock_on_critical  = true\ntimeout            = 300\n```\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `SOLIDSPEC_AI` | Override default AI agent |\n| `SOLIDSPEC_FEATURE` | Override feature detection (skip git/scan) |\n| `GH_TOKEN` | GitHub API authentication |\n\n---\n\n## Development\n\n```bash\n# Run all tests\ncargo test\n\n# Build release binary\ncargo build --release\n\n# Generate shell completions\nsolidspec completions bash > ~/.bash_completion.d/solidspec\nsolidspec completions zsh > ~/.zfunc/_solidspec\nsolidspec completions fish > ~/.config/fish/completions/solidspec.fish\n```\n\n### Architecture\n\n```\nsrc/\n  cli/          Command handlers (clap derive) — one module per subcommand\n  core/         All business logic: spec parser, planner, task generator, test generator,\n                tdd (RED/REFACTOR scaffolding), pipeline, analyzer (incl. OKF structural\n                cross-check), constitution, intent_parser, evidence, artifact_graph (DAG +\n                trace), fan_out (ship gate), okf (native knowledge-graph generate/validate/refresh)\n  agents/       19-agent config table, detection, format translation, registration, CLI invoker,\n                spcx (schema-aware /spcx:* body generator)\n  templates/    Tera rendering + 4-layer resolver (project-local → embedded default)\n  presets/      Manifest validation, registry, manager\n  extensions/   Manifest, registry, hooks, manager\n  config/       TOML configuration handling (RootConfig, ProjectInternalConfig, FanOutConfig)\nschemas/\n  spec-driven/    Default 9-artifact SDD workflow\n  minimal/        4-artifact lightweight workflow (the actual `solidspec init` default)\n  security-first/ 5-artifact workflow with mandatory OWASP security review\n  tdd-driven/     10-artifact AI-TDD workflow (RED-GREEN-REFACTOR)\n  intent-driven/  11-artifact IDSD workflow (intent + evidence + drift detection)\n  apex-driven/    9-artifact SDD + APEX implementation\n  intent-apex/    11-artifact IDSD + APEX (maximum rigor)\ndocs/\n  idsd-workflow-guide.md              Complete IDSD walkthrough with Task Manager example\n  Parallel-Fan-out_orchestration-plan.md  Fan-out ship gate design spec\n  okf-rs-integration-plan.md          Native knowledge-graph integration: what's vendored, what's next\n  kg-workflow-vision-gap-analysis.md  Knowledge-graph/workflow architecture review and roadmap\n  graph/                              This repo's own OKF knowledge-graph bundle (dogfooded)\n  tdd/                                TDD skill documentation\n```\n\n---\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 55124,
  "sha": "e17b5769eb22cc867b4869956b1b94bf90273fe007920628e92b07145ed06a22",
  "repo_slug": "jyjeanne/solidspec",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_jyjeanne_solidspec_docs_graph_knowledge__0e9c408f/readme"
}