Spec-driven development workflow engine for Claude Code. Manages the full lifecycle of a change - explore, plan, build, verify, evolve, archive - through structured artifacts. 12 Claude Code skills cover each phase; none enforce a specific model, so the user picks the model at invocation time.
# Requires Python 3.14+
uv pip install -e .devspec manages a spec-driven development cycle:
explore -> plan -> build -> verify -> evolve -> archive
Each change lives in the project's global data store (~/.local/share/devspec/<project>/changes/<name>/) and produces artifacts in dependency order:
proposal --> specs -----> tasks
\-----> design --/
Two schemas: spec-driven-custom (full pipeline above) and quick (tasks-only for small changes).
Proposal, specs, design, and tasks with dependency-ordered generation. Templates and enriched instructions guide each artifact. Delta specs (ADDED/MODIFIED/REMOVED/RENAMED sections) describe changes to main specs and get merged at archive time.
- Mechanical checks - tests, linters, coverage, stub detection, task completion (11 deterministic checks)
- Spec drift - TF-IDF term containment detects divergence between specs and implementation
- Cross-artifact analysis - 6-pass consistency checks across proposal, specs, design, and tasks
- Ambiguity scoring - 4-dimension heuristic analysis of handoff documents with 12 smell types
- Slop detection - pattern-based scanning for AI slop (debug prints, breakpoints, placeholders) across Python, C, and Shell
Verify-fix loops with state tracking across iterations. Stagnation detection (5 patterns: spinning, oscillation, no_progress, diminishing_returns, repair_loop) triggers thinking minds - 8 reasoning perspectives (advocate, architect, contrarian, interviewer, ontologist, premortem, researcher, simplifier) that reframe stuck problems.
Persistent findings store (JSONL). Clustering by error category, failure rate computation, and pipeline effectiveness auditing with per-stage metrics. Retrospective analysis generates improvement suggestions after archive.
3-factor complexity scoring with model routing. Heuristic dependency analysis with Kahn's topological sort. BFS repair scope computation from failed tasks through reverse dependency edges. Task format validation with sidecar generation.
Forward-looking ideas with trigger conditions. Dormant signals match against change descriptions and get promoted when relevant.
Tech stack detection, dependency extraction, and file scouting for changes. Pre-flight environment checks (git, tools, data store) before starting work.
Comprehensive change health assessment with auto-repair. Structured questions via MCP elicitation with Textual TUI fallback (claude-ask).
17 commands registered in devspec:
devspec init # Initialize project data directory
devspec new <name> # Create a new change
devspec list [--json] # List active changes
devspec status [<name>] [--json] # Artifact completion status
devspec instructions <artifact> [--json] # Enriched artifact template
devspec context <name> [--max-tokens N] # Token-budgeted context dump
devspec analyze <name> [--json] # Cross-artifact consistency analysis
devspec validate [<name>] # Validate specs or change deltas
devspec verify [<name>] [--mechanical] [--json] # Run verification checks
devspec handoff write|read <name> # Context bridge for skill transitions
devspec archive <name> [--skip-specs] # Archive completed change
devspec preflight [--json] # Environment pre-flight checks
devspec signal list|create|show|match|dismiss|promote # Manage signals
devspec slop scan|add-rule # Slop pattern detection
devspec ask --session <id> # Structured questions TUI
devspec migrate # Migrate from legacy layout
devspec migrate-signals # Migrate seeds/ to signals/devspec includes an MCP server (devspec-mcp) that exposes all operations as structured tool calls over stdio.
devspec-mcp # Starts MCP server on stdioAdd to .claude/settings.json to register:
{
"mcpServers": {
"devspec": {
"command": "devspec-mcp"
}
}
}Change management
| Tool | Description |
|---|---|
devspec_change |
Manage changes (list/new/delete/status/archive/preview/retrospective) |
devspec_context |
Token-budgeted context dump |
Artifact lifecycle
| Tool | Description |
|---|---|
devspec_instructions |
Enriched artifact template with dependency bundling |
devspec_write_artifact |
Write an artifact file (with task format validation) |
devspec_handoff |
Read or write handoff content |
Quality and validation
| Tool | Description |
|---|---|
devspec_preflight |
Environment pre-flight checks |
devspec_validate |
Validate delta specs or main specs |
devspec_analyze |
Cross-artifact consistency analysis |
devspec_health |
Comprehensive health check with auto-repair |
devspec_ambiguity |
Handoff ambiguity scoring (4 dimensions) |
devspec_slop |
Scan files for slop patterns or add rules |
devspec_mechanical_checks |
Deterministic mechanical verification (tests, linters, coverage) |
Verification
| Tool | Description |
|---|---|
devspec_drift |
Spec-to-implementation drift detection |
devspec_assemble_report |
Assemble full verification report |
Task management
| Tool | Description |
|---|---|
devspec_task |
Manage tasks (list/mark/add/state/deps/repair) |
devspec_complexity |
Task complexity scoring with model routing |
Evolution
| Tool | Description |
|---|---|
devspec_evolve |
Evolution state (create/record/check/suggest) |
Debt and findings
| Tool | Description |
|---|---|
devspec_debt |
Verification debt (scan/query/resolve/stats/cluster/audit) |
devspec_log |
Append/read events, record metrics |
Supporting
| Tool | Description |
|---|---|
devspec_mind |
Load a thinking mind by name |
devspec_codebase |
Tech stack detection, file scouting |
devspec_signal |
Manage signals (create/match/list/show/dismiss/promote) |
devspec_ask_questions |
Structured questions (elicitation or TUI) |
| Resource | Description |
|---|---|
devspec://changes/ |
List active changes |
devspec://changes/{name}/{artifact} |
Read a change artifact |
devspec://changes/{name}/specs/{capability} |
Read a delta spec |
devspec://specs/{capability} |
Read a main spec |
devspec://schema |
Read the workflow schema |
12 skills in skills/ - symlink to ~/.claude/skills/ to activate:
ln -s $(pwd)/skills/ds-* ~/.claude/skills/| Skill | Purpose |
|---|---|
/ds-explore |
Thinking partner. Investigates problems, writes handoff |
/ds-plan |
Create artifacts (proposal, specs, design, tasks) |
/ds-build |
Implement tasks with round-based parallel execution |
/ds-verify |
Check implementation against specs |
/ds-evolve |
Iterative verify-fix loop with stagnation detection |
/ds-archive |
Archive change, sync delta specs to main |
| Skill | Purpose |
|---|---|
/ds-auto |
Run full pipeline autonomously from a handoff |
/ds-memory |
Generate Claude Code auto memory for a project |
/ds-improve |
Analyze codebase for improvements, quick-fix P0-P1, handoff P2+ |
/ds-arch |
Generate or check ARCHITECTURE.md, detect drift |
/ds-audit |
Pipeline effectiveness audit with stage metrics |
/ds-error-analysis |
Finding clustering, category naming, failure rates |
No skill specifies a model: field - they all run at the current session model. /ds-auto spawns sub-agents at sonnet.
4 agent definitions in agents/:
| Agent | Purpose |
|---|---|
ds-worker |
Build agent for task implementation |
review |
Code review for architecture, performance, and security |
orchestrator |
Read-only coordination (plans and delegates, no edits) |
think-hard |
Deep reasoning for architectural decisions and tradeoffs |
6 hooks in hooks/ for Claude Code event integration:
| Hook | Event | Purpose |
|---|---|---|
devspec-postcompact.sh |
PostCompact | Inject next-step guidance |
devspec-memory.sh |
PreCompact | Save session context to auto memory |
devspec-build-guard.sh |
Stop | Block completion when build tasks pending |
devspec-pipeline-validate.sh |
SubagentStop | Validate auto pipeline results |
devspec-artifact-validate.sh |
PostToolUse | Validate artifacts after file writes |
devspec-task-complete-guard.sh |
TaskCompleted | Verify artifact state on task completion |
uv run pytest tests/ -v # Tests (~1245 across 58 files)
uv run ruff check src/ tests/ # LintSee ARCHITECTURE.md for module layout, key abstractions, data flow, and the full core module index (40 modules across 9 dependency layers).
MIT