spar-kit

SPAR-kit is a lightweight, spec-driven workflow for AI-assisted software development.
It helps humans and AI agents align intent, plan clearly, act with less drift, and retain
durable project memory.

View the product homepage: https://jed-tech.github.io/spar-kit/

Specify -> Plan -> Act -> Retain

Install

Choose the install type that matches the repo-local layout you want:

• npx @spar-kit/install
  General SPAR layout. Works with most AI agent platforms.
• npx @spar-kit/install --cursor
  Use when you want the Cursor-native SPAR layout.
• npx @spar-kit/install --claude
  Use when you want the Claude-native SPAR layout.
• npx @spar-kit/install --codex
  Works with Codex. Same repo-local layout as Default.
• npx @spar-kit/install --copilot
  Works with Copilot. Same repo-local layout as Default.
• npx @spar-kit/install --windsurf
  Works with Windsurf. Same repo-local layout as Default.
• npx @spar-kit/install --gemini
  Works with Gemini. Same repo-local layout as Default.
• npx @spar-kit/install --opencode
  Works with OpenCode. Same repo-local layout as Default.

Immediate next step

After install, ask your agent to use spar-init

spar-init does more than a quick setup check. Its purpose is updating SPAR-kit's
local tool index so your AI knows exactly which tools, CLIs, and project commands
are available in your repo.

That matters because agents work better when they do not have to guess. With a tool
index, they spend less time probing the environment, use fewer tokens on tool
discovery, and make more reliable decisions about how to act in your project.

The spar-init skill will quickly:

1. Check that your SPAR-kit install is current
2. Index available repo tools in .spar-kit/.local/tools.yaml

Once that is done, start your first change with spar-specify.

Workflow

SPAR-kit gives every change a clear operating loop from intent to shipped work to retained
project memory.

1. Specify
   Clarify goals, scope, and constraints before implementation starts.
2. Plan
   Turn the change into an explicit sequence that reduces drift.
3. Act
   Implement in the repository with validation tied to the plan and spec.
4. Retain
   Preserve decisions and shipped behavior as durable project memory.

What you get

SPAR-kit installs a small, repo-native workflow layer:

• Skills to guide the work
• Rules to keep agents aligned
• A tool index so AI knows what is available
• A specs/ structure for active and completed changes

Skill-guided workflow

Reusable SPAR skills guide agents through Specify, Plan, Act, and Retain without needing
a heavy framework.

Low-context agent rules

Concise agent guidance keeps AI tools aligned to the SPAR workflow without flooding every
session with instructions.

Tool index

A local tool index helps agents see and efficiently use the commands and project tools
available to them.

Spec structure

Active and completed spec folders give each change a clear home from first intent to
retained project memory.

Safe for existing repos: SPAR-kit layers in without overwriting your existing skills,
rules, or AGENTS.md.

Why SPAR-kit?

AI works best with focused context.

AI agents are powerful, but they are easy to derail when the context is vague, noisy, or
overloaded. SPAR-kit gives each change a small, practical structure: clarify the intent,
capture the constraints, plan the work, act against that plan, and retain what matters
when the work is done.

That structure keeps the model focused on the right problem at the right time. The spec
holds intent. The plan holds execution. Retain turns shipped work into project memory.
Each piece has a job, so your agent does not have to rediscover the same context every
session.

The result is less drift, less rework, and a cleaner path from idea to implemented change.

Repository structure

Repository root = <root>.

Specify, Plan, and Act run against specs/active/. Retain moves the whole
directory from active/ to completed/ with no duplicate left under active/.

Each change folder usually contains <change-name>_spec.md and plan.md, side by side.
Optional files such as research.md, notes, or small artifacts may live in the same
folder.

See specs/README.md for a concise overview of the workflow folders.

Skills

Core workflow and initialization are implemented as agent skills:

Project-local skill locations:

• Codex: .agents/skills/
• Cursor: .agents/skills/
• Claude Code: .claude/skills/

Copy or symlink each skill directory into your agent's supported skills location if needed,
following your tool's documentation.

Templates

templates/spec.md is copied per change to <change-name>_spec.md.

templates/plan.md becomes plan.md.

The spec template lists every heading. spar-specify fills the sections known from
discovery, and spar-plan completes the rest. Both templates include HTML comments noting
paths under specs/active/ through completion under specs/completed/.