dev-spec-driven

Imported from linofcp007/dev-spec-driven (AGENTS.md). Install upstream with npx skills add linofcp007/dev-spec-driven. Copyright stays with the author.

dev-spec-driven — agent instructions (tool-agnostic)

This file is the portable version of the dev-spec-driven workflow. Any agent tool that reads an instructions file — Codex CLI, Gemini CLI, Cursor, Windsurf, Copilot, Claude, Zed, Cline, … — can follow it. The full reference lives in skills/dev-spec-driven/SKILL.md and references/.

Language: detect the user's language and respond in it (English, Português, Español), including the prose inside generated artifacts. Pass --lang en|pt|es to dev-spec init (sets the project default) and dev-spec create (per feature; inherits the project default) so the scaffolds, steering and tool messages come out already localized — you only fill the placeholders. Keep structural tokens stable (AC IDs like US-1.AC-1, task markers _Requirements:_, track names core/+tdd/+saas/+ai). EARS keywords work in all three: SHALL/DEVE/DEBE, WHEN/QUANDO/CUANDO, etc.

What this is

Spec-driven development that scales rigor to the feature. You classify each feature into composable tracks, then run an approval-gated pipeline producing traceable artifacts in .specs/.

Tracks combine (e.g. a billing webhook in a multi-tenant SaaS that calls an LLM = core +tdd +saas +ai).

The engine: CLI and/or MCP (both local, zero-cost, no CI)

Do the mechanical steps with the bundled engine instead of hand-editing files. Two equivalent ways:

• CLI (works anywhere): node cli/dev-spec.js <command> (or dev-spec <command> if on PATH).
• MCP (if your tool speaks MCP): the spec-driven server exposes the same operations as tools.

Key operations (CLI form):

dev-spec classify "<feature description>"     # recommend tracks (multilingual, weighted)
dev-spec init [tracks...] [--lang en|pt|es]    # scaffold .specs/steering (incl. constitution.md); --lang sets the project default
dev-spec steering <file> [--lang]              # one steering file from its template (constitution.md, tech.md, …)
dev-spec create "<name>" [tracks...] [--lang] [--summary "…"]  # scaffold the feature (no tracks → auto-classify; inherits project lang)
dev-spec status [feature] | list               # progress, phase, tracks
dev-spec clarify <feature>                      # surface requirement gaps before design
dev-spec doctor <feature>                      # health-check → ready to advance? (exit 1 on FAIL — scriptable)
dev-spec ears <feature|file.md>                # lint EARS (SHALL/DEVE/DEBE, IDs, vague words)
dev-spec trace <feature>                       # AC ↔ task ↔ test ↔ code (_Implements:_, phantom refs)
dev-spec next <feature> [--batch]              # next task (--batch: + the [P] tasks that can run beside it)
dev-spec done <feature> <n> --run              # run the task's _Verify:_ command and record the evidence (failure → stays open)
dev-spec bugfix "<name>" [--summary "…"]       # bugfix flow: reproduce → root cause → regression test → fix
dev-spec finish <feature> [--write]            # blockers + fresh checks + merge summary from the spec chain (merge locally; no PRs)
dev-spec brief <feature> [n] [--write]         # self-contained brief for one task (ACs + tests resolved, DoD)
dev-spec approve <feature> <phase>             # record an approval gate
dev-spec roadmap                               # multi-feature roadmap: %, dependencies, cycles
dev-spec depend <feature> [deps...]            # declare dependencies / order (rejects cycles)
dev-spec scan [path]  /  dev-spec coverage     # brownfield: inventory existing code + spec coverage
dev-spec evals <feature> [--dry-run]           # run local eval harness (+ai; your API key)
dev-spec mcp-config [client]                   # print MCP config for your tool

The pipeline (Spec mode)

For anything beyond a quick fix (Vibe mode = just do it, no artifacts):

0. Classify — dev-spec classify to seed tracks; confirm against references/classification-matrix.md; write .specs/<feature>/classification.md. Get user approval of the track set.
1. Requirements — dev-spec create scaffolds; write EARS criteria with stable AC IDs; run dev-spec ears to lint. Add track-specific ACs (tenant isolation for +saas; quality/safety/cost for +ai). Approve.
2. Design — base sections + the mandatory sections of the active tracks (5 for +saas, 10 for +ai). The scaffold marks each with a > **TODO** sentinel; replace it with real content. No blank mandatory sections. Approve.
3. Test/Eval plan — +tdd: enumerate tests mapped to AC IDs. +ai: golden/adversarial/regression sets + thresholds + baseline. Approve.
4. Failing tests / eval harness — +tdd: write tests, all red for the right reason (hard gate). +ai: deterministic tests + runnable eval harness + baseline. No implementation before this passes.
5. Tasks — ordered, traceable; markers _Requirements:_ always, _Makes green:_ (+tdd), _Emits metrics:_ (+saas), _Affects evals:_ (+ai). Run dev-spec trace — every AC must map to a task.
6. Execute — per task: implement-and-test (core) / red→green→refactor (+tdd) / prompt-iteration gated on eval delta (+ai). dev-spec brief <feature> gives you the task with its ACs and tests already resolved — handy to focus, or to hand one task to another agent. Mark done with dev-spec done <feature> <n> --run — evidence before claims: the task's _Verify:_ command runs and its result is recorded; a failure leaves the task open. Close the feature with dev-spec finish. (In Claude Code, /executeTask --subagents runs an implementer + reviewer subagent per task — see references/subagent-execution.md; tools without subagents run inline.) Before "done": load test + observability (+saas), cost + safety validation (+ai).

At each phase boundary, run dev-spec doctor <feature>; only advance when it reports readyToAdvance. Record sign-off with dev-spec approve <feature> <phase>.

Non-negotiables

• No implementation without approval at each gate.
• Traceability end-to-end: code → tasks → (tests/evals) → design → requirements → need.
• Mandatory track sections are mandatory — an honest "not needed because X" is fine; blank is not.
• Everything is local. No GitHub Actions, no paid CI, no pull requests — integrate by merging locally. Tests/load/evals run in the user's own env.

See skills/dev-spec-driven/references/ for EARS, scale, eval, safety, and prompt-engineering guides.