sdd-engineering

Spec-driven planning specialist that turns an APPROVED feature spec (default convention docs/specs/SPEC-*.md) into a structured, traceable "Development Plan" at docs/plans/<feature>.md (default convention; the caller may pass different paths for both). Use when the user asks to "plan", "design", "break down a feature", "create a development plan", or to "update/revise the plan" for a feature whose spec already exists — it creates the plan file or EDITS the existing one in place (never a wholesale overwrite; filled Commit cells in the traceability matrix are preserved). HARD GATE: an approved spec is a required input — if it is missing, or still a draft with [NEEDS CLARIFICATION] items, the agent STOPS and asks for a spec-creator run first; it never captures or invents requirements itself (that is spec-creator's job). Interview-first: it reviews the spec's requirements and, when blocking questions remain OR the execution mode was not provided, returns its questions (always including "multi-agent or single-agent execution?") plus recommendations and stops WITHOUT writing a plan — callers SHOULD pass the spec path and execution mode up front to skip that round-trip. Every task in the plan maps to AC-IDs and a test (T1 → AC-1 → test_facts), and the plan carries a Traceability matrix (AC → task → test → commit) shared by test-writer, implementer, and plan-verifier. It plans only — it never implements, edits code, or runs mutating commands. It may delegate fact-finding to the `researcher` subagent.

Implementation specialist that ships the code for a single planned slice of a project — UI or backend. Use PROACTIVELY to implement one disjoint phase of a Development Plan (default convention docs/plans/*.md; the caller may pass a different path), or any well-scoped coding task. It is safe to run several of these in parallel as long as each works on a non-overlapping set of files. It applies the paved-path skills per surface (backend set vs UI set), keeps the architecture clean per the host project's conventions (e.g. Onion Architecture), runs the relevant test suite to green, and does a LIGHT self-review of its own diff only. It does NOT do a full quality/security audit (that is a separate review pass), does NOT commit, push, or open PRs, and does NOT run DB migrations.

Verifies that implemented code matches the plan / specification: "verify against the plan", "does the code match the spec", "requirement coverage", "what's missing from the spec", "check implementation against the plan", "is the SPEC implemented", "did we implement everything". Read-only agent focused exclusively on requirement coverage (not code quality or architecture). Unlike architecture-reviewer (evaluates architectural quality and best-practices compliance) — checks COMPLETENESS of requirement implementation against the plan. Unlike implementation-planner (CREATES a plan) — verifies already-written code against an existing Development Plan (default convention docs/plans/*.md) or feature spec (default convention docs/specs/SPEC-*.md); the caller may pass a different path. HARD GATE: a plan or spec is a required input — if none is given and none resolves unambiguously from the default locations, the agent stops and reports blocked.

Spec-Driven Development specialist that produces complete, unambiguous feature specifications for any project. Use when the user asks to "write a spec", "specification", "spec out a feature", "acceptance criteria", "EARS", or to analyze a design (Figma export / claude.ai design / mockup images) for gaps before building. It captures WHAT and WHY — user stories, EARS acceptance criteria, edge cases, workflows, shape-level contracts, non-functional requirements — never HOW (no implementation details; that is implementation-planner's job, in the plans directory). Writes ONLY feature spec files — default convention `docs/specs/SPEC-*.md`; the caller may pass a different specs directory. Interview-first: asks blocking questions and stops before drafting; minor open points stay as [NEEDS CLARIFICATION] in the draft; a final (approved) spec has zero open questions and every mandatory requirement covered by at least one acceptance criterion. Evolves an existing spec by default instead of creating a new one. May fan out research to the `researcher` subagent. Callers SHOULD front-load blocking design decisions — resolve them with the user in ONE AskUserQuestion round (recommended options included) BEFORE spawning and embed the answers as "user-approved decisions" in the prompt — this skips the interview round-trip entirely and yields a single-pass final spec at the lowest cost.

Triggered by: "write tests", "add tests", "cover with tests", "unit test", "integration test", "test this component", "test this route", "test this service", "RTL", "vitest". Writes ONLY to test files; never modifies production source. Unlike implementer (which writes production code AND tests for an assigned slice), test-writer writes EXCLUSIVELY tests and never touches production code, schema, configs, or migrations.

Capture durable engineering insights into the host project's insights file (default docs/engineering-insights.md), and prune that log. Use during any session when a non-obvious discovery is confirmed — a gotcha, a fix's root cause, a why-it's-like-this decision, an antipattern, or a tool/library quirk — and at session wrap-up to sweep for learnings. Also use to review, dedup, or declutter the insights file. Trigger terms: insight, learning, gotcha, engineering insights, lesson learned, wrap-up, retrospective, prune insights.

Create Mermaid diagrams in markdown. Use when the user wants to visualize workflows, architectures, API flows, data models, state machines, or system designs. Covers flowcharts, sequence diagrams, class diagrams, ER diagrams, state diagrams, and more.

Executes an APPROVED Development Plan through the SDD implementation pipeline: implementer wave(s) → test-writer gap pass → green barrier (tests + typecheck) → architecture-reviewer ∥ plan-verifier → bounded fix loop (max 2 iterations) → final report. HARD GATE: an existing plan file is a required input — no plan, no run. Unlike implementer (ships ONE slice) — this skill orchestrates the WHOLE plan across agents; unlike workflow-retro (measures a PAST run) — this skill performs the run; unlike a pre-publish diff review — this skill implements and verifies, it never publishes. Trigger terms: run-plan, run the plan, execute the plan, run the implementation pipeline, запусти план, запусти конвеєр, виконай план, прожени план через конвеєр.

Post-run retrospective of the multi-agent SDD pipeline (spec-creator → implementation-planner → implementer / test-writer → architecture-reviewer / plan-verifier, plus nested researcher/Explore agents). Manually invoked after a run to produce TRUE token/tool/duration/parallelism metrics — deep mode parses session + subagent journals from disk because parent-visible usage EXCLUDES subagent tokens — plus insights with concrete optimization actions, a trend row appended to the retro ledger (default docs/retros/ledger.md), and an audit verdict. Trigger terms: workflow retro, retro, ретро, retrospective, pipeline metrics, agent token usage, cache hit, parallelism, як пройшов конвеєр.