spec-dev

spec-dev

English | 简体中文

A design→plan→execute skill pipeline plugin: polish ideas into specs, break them into executable plans, and deliver with TDD discipline in isolated workspaces.

Design→Plan→Execute pipeline | Adversarial validation | Visual preview | All-round acceptance | MCP enhancements

Features

• Exploration mode — exploring, a thinking partner: no-commitment exploration while an idea is unsettled — read-only, no code (HARD-GATE), opens side threads instead of interrogating, ASCII visualization, opt-in exploration notes under .spec-dev/explorations/; hands off to requirement-analysis once the idea crystallizes, and executing-plans can drop back into it when stuck
• Requirement design — requirement-analysis, an 8-phase design workflow: triage (light / standard / deep tiers), parallel internal+external exploration (no subagent cap), one-question-at-a-time clarification, sequential-thinking adversarial validation + 2-3 option comparison, spec writing with double review (structured behavior requirements: Requirement + Scenario); a HARD-GATE guarantees zero implementation before the design is approved
• Visual preview — visual-preview, a browser companion: JIT-proposed during design conversations, renders mockups, wireframes and layout comparisons, and collects click-through choices
• Implementation plans — writing-plans decomposes specs into bite-sized tasks executable with zero context: exact file paths, complete code, embedded 5-step TDD, consume/produce interface contracts, no placeholders allowed
• Plan execution — executing-plans: the main thread executes task-by-task (per-task commit + spec self-check), then wrap-up multi-dimension adversarial review (fan-out code-reviewer + contract validation + loop-until-dry + completeness critic), merge and summary
• Engineering discipline — using-git-worktrees (isolated workspaces, native tools first) and test-driven-development (no production code without a failing test) are standalone skills reusable from any workflow
• All-round acceptance — acceptance-qa runs acceptance over the dimension × execution-nature matrix: unit/integration/API, Playwright E2E, visual regression, accessibility, performance (web CWV / k6 for APIs / client), AI autonomous acceptance (mandatory evidence + serial recheck + verify-assertions-first) and failure diagnosis
• Lightweight fix — quick-fix, a fast path for already-decided fixes with no design space (small bugs, minor adjustments): root cause with spec back-lookup, one-question-at-a-time confirmation, TDD fix, optional acceptance; splits on contract impact to avoid spec drift and escalates to requirement-analysis on contract-crossing / cross-module / new-dependency signals
• Contract-driven orchestration — subagent output goes through JSON Schema contracts, deterministically validated by validate-output.mjs, with one retry on failure
• MCP enhancements — integrates context7, sequential-thinking, playwright, chrome-devtools (optional, graceful degradation)
• 3 specialized agents — code-explorer, external-resource-explorer, code-reviewer (analysis and verification re-runs only; implementation code is always written by the main thread)

Skill Pipeline

exploring (unsettled idea → optional .spec-dev/explorations/<topic>.md)
        ↓ crystallizes
requirement-analysis (design → .spec-dev/YYYY-MM-DD-<feature>/spec/<feature>-design.md)
        ↕ JIT
  visual-preview
        ↓
writing-plans (plan → plan/<feature>-plan.md in the same feature dir)
        ↓
executing-plans (isolated execution + review + summary)
   ├── using-git-worktrees (isolated workspace)
   ├── test-driven-development (TDD discipline)
   └── acceptance-qa (matrix-driven acceptance)

quick-fix (already-decided small fix, no design space)  ── bypass fast path
   root cause + spec back-lookup → one-question confirm → TDD fix → optional acceptance
        ↑ escalates to requirement-analysis on contract-crossing / cross-module / new-dependency signals

roadmap continuation (oversized goals)  ── decomposition registered at .spec-dev/roadmaps/<project>.md ── outer loop
   requirement-analysis registers sub-projects → each runs the full pipeline independently → executing-plans marks delivery and offers the next one

The three entry points split by commitment and design space: exploring (undecided — should we even do this?), quick-fix (decided, no design space — a small bug or adjustment), requirement-analysis (decided, has design space — a feature or change). quick-fix reuses test-driven-development and acceptance-qa, and hands control back to requirement-analysis the moment a fix turns out to need real design.