SPEC-driven development system for Claude Code. Enforces a structured, specification-first workflow where every feature follows a strict lifecycle: spec → plan → tasks → execute → verify → merge.
Each feature lives on its own branch, produces structured artifacts (JSON + Markdown), and contributes to shared project memory:
MEMORY.mdfor high-level project context (tech stack, features, patterns, conventions)MEMORY.jsonfor machine-checkable entity/API contracts used for conflict detection
npx specificoRun this in the root of any project you want to use Specifico in. It installs the Claude Code slash commands into .claude/commands/specifico/.
To upgrade or reinstall without a prompt:
npx specifico --force- Claude Code CLI or desktop app
- Git repository
Open your project in Claude Code. All commands are available as /specifico:<command>.
If your repo already has code, run /specifico:init first. It scans the codebase for existing architecture context, confirms findings with you, and writes an initial MEMORY.md.
/specifico:init
/specifico:spec "add payment flow"
...
/specifico:spec "build user authentication with JWT"
/specifico:plan
/specifico:tasks
/specifico:implement ← implements all tasks, verifies, fixes gaps — runs to completion
/specifico:memory-update
/specifico:merge
Bootstraps Specifico in an existing repository. Scans the codebase for technologies, implemented features, and architectural patterns, presents findings for your review, then writes the initial specifico/MEMORY.md.
Also initializes specifico/ and journal.json if they do not exist yet.
Run this once, before creating your first spec, when adding Specifico to a project that already has code.
Creates a new spec for a feature. Generates a sequential ID (001, 002, …), creates a dedicated branch (specifico/001-user-auth), and produces:
specifico/001-user-auth/SPEC.md— human-readable specspecifico/001-user-auth/SPEC.json— structured: problem, goals, non-goals, entities, API endpoints, acceptance criteriaspecifico/001-user-auth/STATE.json— current phase trackerspecifico/001-user-auth/DECISIONS.md— append-only decision log
Checks existing memory for entity/API conflicts before proceeding.
Drafts the implementation plan for the current spec. Validates spec completeness first, then produces:
PLAN.md— approach, components, data flow, risks, open questionsPLAN.json— structured plan data
Transitions state: spec → plan.
Breaks the plan into atomic, ordered tasks. Each task maps to one or more acceptance criteria and has explicit dependencies. Validates the dependency graph for cycles.
TASKS.md— checklist with dependency annotationsTASKS.json— structured task list
Transitions state: plan → tasks.
Runs the spec to completion in a single invocation:
- Task loop — implements each ready task in dependency order, commits, and marks it done. Repeats until no tasks remain.
- Verify loop — evaluates every acceptance criterion. If any fail, implements fixes and re-verifies. Repeats until all criteria pass.
- Finalize — transitions state to
verifywithverifyPassed: trueand prompts for the next step.
Before writing any code, checks MEMORY.json for entity/API contract conflicts and blocks if any are found.
Commit formats:
specifico(001/T003): add JWT validation middleware ← task commit
specifico(001/fix): add missing rate limiting ← verification fix commit
A specific task-id can be passed as the second argument to start from that task.
Transitions state: tasks → execute → verify.
Evaluates the implementation against every acceptance criterion in the spec. For each criterion, finds evidence in the codebase (file:line) and assigns a pass, fail, or partial verdict.
If all pass: sets verifyPassed: true, suggests next steps.
If any fail: lists gaps and suggests which tasks to re-run.
Transitions state: execute → verify.
Merges the spec branch into main. Requires verification to have passed.
specifico/001-user-auth → main
Transitions state: verify → merged.
Shows progress across all specs, or detailed status for a specific one:
ID SLUG PHASE TASKS BRANCH
001 user-auth execute 5/8 done specifico/001-user-auth
002 payment-flow plan — specifico/002-payment-flow
Updates a spec mid-lifecycle and resets state to the earliest invalidated phase. Appends the rationale to DECISIONS.md. Downstream artifacts (plan, tasks, verify) are invalidated and must be re-run.
Extracts entity and API endpoint definitions from a completed spec and merges them into specifico/MEMORY.json. Blocks on schema conflicts.
Reconstructs specifico/MEMORY.json from scratch by replaying all merged specs in order. Useful after manual edits or corruption.
All Specifico artifacts live in a specifico/ folder at your project root (committed to the repo):
specifico/
├── MEMORY.md ← project context memory (tech/features/patterns)
├── MEMORY.json ← entity/API contract memory (conflict checking)
├── journal.json ← registry of all specs and phases
├── 001-user-auth/
│ ├── SPEC.md + SPEC.json
│ ├── PLAN.md + PLAN.json
│ ├── TASKS.md + TASKS.json
│ ├── STATE.json
│ └── DECISIONS.md
└── 002-payment-flow/
└── ...
MEMORY.md stores human-readable project context and evolves over time as specs are merged.
MEMORY.json accumulates the entities and API contracts introduced by each merged spec. Before executing any task, Specifico checks incoming entity/API definitions against this contract memory and blocks on conflicts like type mismatches, removed fields, or changed HTTP methods.
This prevents specs from silently diverging from each other over time.
- One branch per spec:
specifico/<id>-<slug> - One commit per task:
specifico(<id>/<task-id>): <title> - Verification fix commits (when needed):
specifico(<id>/fix): <title> - Merge into main only after verification passes
MIT