Repolode
Submit
ruvnet

ruvnet/sparc

An evidence-gated engineering workflow that enforces the five SPARC phases (Specification, Pseudocode, Architecture, Refinement, Completion) through a TypeScript state machine, CLI, and MCP server.

View on GitHub
Stars
479
Forks
91
Open issues
38
Last commit
7 days ago

What is it?

SPARC is a workflow framework for software changes that enforces the five phases of Specification, Pseudocode, Architecture, Refinement, and Completion in code rather than relying on prompts. Each phase has required artifacts, and a phase can only advance when its gate passes. Mutations must match the current revision, and retries replay only the exact original request.

The project ships an npm CLI and both local stdio and remote Streamable HTTP MCP transports, with shared skills for Claude and OpenAI-compatible hosts. Completion requires verifier-attested passing evidence for every in-scope acceptance test, and evidence can be checked with Ed25519 signatures. Runs are isolated per authenticated principal, state is written atomically with restricted file modes, and receipt chains are verified on load.

SPARC records development evidence and does not execute acceptance-test commands stored in a run. The Python CLI from earlier versions remains available as a compatibility surface.

Key features

  • 01Enforces the five SPARC phases in order with deterministic gates.
  • 02Uses revision checks and idempotency keys to prevent conflicting or repeated mutations.
  • 03Requires signed, verifier-attested test evidence before completion.
  • 04Provides an npm CLI and local and remote MCP servers.
  • 05Keeps state private, atomically written, and tamper-evident.

Use cases

  • Running AI-assisted code changes with auditable phase gates and test evidence.
  • Exposing a structured development workflow to Claude or Codex through MCP.
  • Requiring signed verification results before accepting a change as complete.

Quick start

  1. 1

    Check the install with the doctor command (requires Node.js 20 or newer)

    npx --yes @ruvnet/sparc@1.0.0 doctor
  2. 2

    Initialize SPARC state

    npx --yes @ruvnet/sparc@1.0.0 init
  3. 3

    Create a run definition JSON file with requirements and acceptance tests, then start a run

Things to know

  • Passing and exception evidence requires configuring Ed25519 verifier public keys in every process that reads or writes state.
  • Remote MCP use requires an authenticated HTTPS reverse proxy and an external identity provider.

In collections

Claude Code tools, skills & pluginsMCP serversCLI & terminal tools

Topics

#workflow#state-machine#mcp#cli#typescript#llm-agents#evidence#claude

FAQ

What is sparc?
An evidence-gated engineering workflow that enforces the five SPARC phases (Specification, Pseudocode, Architecture, Refinement, Completion) through a TypeScript state machine, CLI, and MCP server. SPARC is a workflow framework for software changes that enforces the five phases of Specification, Pseudocode, Architecture, Refinement, and Completion in code rather than relying on prompts. Each phase has required artifacts, and a phase can only advance when its gate passes. Mutations must match the current revision, and retries replay only the exact original request.
Is sparc free to use? What license does it have?
sparc is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is sparc still maintained?
Actively maintained. The last commit to sparc was on Oct 31, 2026.
What can I use sparc for?
Running AI-assisted code changes with auditable phase gates and test evidence. Exposing a structured development workflow to Claude or Codex through MCP. Requiring signed verification results before accepting a change as complete.
How do I install sparc?
Check the install with the doctor command (requires Node.js 20 or newer): npx --yes @ruvnet/sparc@1.0.0 doctor Initialize SPARC state: npx --yes @ruvnet/sparc@1.0.0 init Create a run definition JSON file with requirements and acceptance tests, then start a run
Where can I get sparc?
The source code and installation instructions are on GitHub: https://github.com/ruvnet/sparc

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects