sdd-engineering
Spec Driven Development pipeline: spec, plan, implement, verify and retro with dedicated agents
Claude Code plugins for Spec Driven Development and engineering paved paths
Spec Driven Development pipeline: spec, plan, implement, verify and retro with dedicated agents
Read-only architecture reviewer for a change or an area, against onion architecture and frontend UI placement rules
Stack skills for React, Next.js and Fastify apps: architecture, component placement, testing and security
Read-only researcher agent for codebase and external questions, with cited evidence and an explicit list of what it could not establish
Shows the state of the Spec Driven Development pipeline in this project: the ACTIVE sdd-engineering version (read from the installed plugin's own manifest, so it proves which copy is running), whether the project config exists, specs by status with open [NEEDS CLARIFICATION] markers, plans, configured verify commands, the plugin's dependencies, and the one next step. Read-only. Manual only: runs when the user invokes /sdd-engineering:sdd-status.
Shared format of the Spec Driven Development pipeline: the project config file (.claude/sdd-engineering.json), the feature spec template with EARS acceptance criteria and verification hints, the [NEEDS CLARIFICATION] marker grammar and its checker, the implementation plan template, the default glob-to-skill routing table and how verification commands are run. Use when writing, reading, planning from or verifying a spec or a plan, or when a project's SDD paths, routing or verify commands must be resolved.
Turns EXISTING requirements (a spec in the specs directory, a user request, a brainstorm brief) into a written Implementation Plan for the current repository: where each file goes, which stack skills the routing table assigns to it, which project knowledge constraints apply, which contracts change, how each item is verified, and how it is executed — single-agent or multi-agent lanes. Spec-driven by default: given a detailed spec (SPEC-NN-*.md with checkable acceptance criteria, no blocking open question and no [NEEDS CLARIFICATION] marker) it plans straight from it with no requirements questions — only the execution mode must be settled. Without a spec it first reviews the requirements and returns clarifying questions, recommendations and the execution-mode question for the caller to put to the user, and writes the plan only after the answers. Use after a spec is approved, or when a request needs a plan before implementation. Writes one plan file to the plans directory. Never writes or edits specifications, never implements, never reviews.
Writes feature specifications for Spec Driven Development: turns a feature request (plus design sources and any screenshots) into one <specsDir>/SPEC-NN-<slug>.md with EARS acceptance criteria, verification hints, NFRs, edge cases, module interactions, provenance, untrusted inputs and a traceability matrix. Works in two passes: first analyses the request, the design and the code (dispatching research-tools:researcher subagents in parallel when it needs facts it cannot read itself) and returns design gaps, uncovered corner cases, cross-module questions and UX proposals for the caller to put to the user; only after those answers does it write the spec and self-check it. Use when a feature needs a spec before planning, or to approve or mark implemented an existing spec. Writes only in the specs directory. Never plans implementation, never writes code.
Captures durable, non-obvious engineering insights into the project's knowledge file for the area the work touched (config knowledgeFiles in .claude/sdd-engineering.json): gotchas, approaches that worked, dead ends and antipatterns, codebase conventions, tool or library quirks, recurring errors with their fix, open questions. Use in the main session when something was learned that a future session would otherwise relearn, at the end of substantial work, on "wrap up", "retro", "save this learning", "remember this gotcha", or when /sdd-engineering:engineering-insights is invoked. Reads the file first, never duplicates, writes only specific file-grounded entries, appends through a script that cannot overwrite prior content, and rebuilds the file's index. Never runs inside a subagent.
Guides development of Fastify Node.js backend servers and REST APIs using TypeScript or JavaScript. Use when building, configuring, or debugging a Fastify application — including defining routes, implementing plugins, setting up JSON Schema validation, handling errors, optimising performance, managing authentication, configuring CORS and security headers, integrating databases, working with WebSockets, and deploying to production. Covers the full Fastify request lifecycle (hooks, serialization, logging with Pino) and TypeScript integration via strip types. Trigger terms: Fastify, Node.js server, REST API, API routes, backend framework, fastify.config, server.ts, app.ts.
Runs the implementation half of Spec Driven Development from a finished plan: implementer (lanes or phases) → integration checks → plan-verifier → architecture review with fix iterations until clean → final verification and a per-requirement report. Takes a plan path from the project's plans directory, plus optional notes and design or screenshot paths. The spec (spec-creator) and the plan (implementation-planner) are made beforehand; this command never writes either. Never commits. Runs only when the user invokes /sdd-engineering:run-plan.
Read-only architecture review of backend and frontend code against two standards: onion architecture (rings, the inward-only dependency rule, ports and adapters, injection through the composition root) and frontend UI architecture (component homes, file roles, where state and business logic live, the server/client boundary). Scope is either a change (changed files, a diff, or a plan whose files were just implemented) or a named area (a module, a directory, a ring, a route segment); it also re-reviews a fix against the previous round's findings. Returns findings with file:line, the rule violated and the failure scenario, graded CRITICAL / WARNING / SUGGESTION. Use when asked to review a change or PR for layering, boundaries, dependency direction, component placement or 'use client' placement, or to audit a module's architecture. Not a bug hunter, not a security review. Other agents dispatch it as architecture-review:architecture-reviewer, for example the review step of the sdd-engineering run-plan pipeline.
Decides where frontend UI code belongs and how far to split it: component homes, file roles (constants, helpers, styles, barrels), business-logic and state placement, and the App Router server/client boundary. Use when creating, moving or renaming any React/Next.js file, extracting a helper or constant, choosing route-local vs shared vs design system, placing data fetching or business rules, or reviewing a PR that adds UI files. Applies even to one-file changes — that is how structure erodes.
Executes an existing Implementation Plan from the plans directory: loads the stack skills the plan and the routing table assign to each file, writes the code, runs the project's configured verify commands, and reports per plan item with evidence. Runs a whole plan, one lane, or one phase. Also runs in fix mode: the plan path plus a list of findings (from sdd-engineering:plan-verifier or a reviewer) to fix, and nothing else. Use from /sdd-engineering:run-plan, or when a written plan needs executing — dispatch it ONLY after the plan file exists on disk, and always with that path; it refuses to start otherwise. Does not design the plan, does not commit, and does not perform architecture or security review.
Creates Mermaid diagrams embedded in markdown: flowcharts, sequence, class, ER, state, Gantt, mindmap and other diagram types, with a guide to picking the right one. Use when writing a spec, a design note or docs that need a workflow, user flow, feature states, service communication, API flow, data model or architecture diagram, or when the user asks to visualize something as a diagram.
Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling. Use when writing, reviewing or debugging Next.js App Router code - pages, layouts, route handlers, Server Components and Server Actions, next/image, next/font, metadata, hydration errors or self-hosting.
Enforces Onion Architecture in Node.js/TypeScript backends and MCP servers: which ring a file belongs to, the inward-only dependency rule, when a port/interface is justified, where business rules live vs. routes vs. repositories, and how Fastify, an ORM such as Drizzle, Zod, a DI container / composition root and the MCP SDK map onto the rings. Use when adding or moving any backend file, creating a module, writing a route, service, repository or MCP tool, introducing an adapter for an external system, placing a business rule, or reviewing a backend PR for layering. Applies to one-file changes — that is how layering erodes.
Checks finished code against an existing Implementation Plan in the plans directory, work item by work item, as a party that wrote neither, and rolls the result up per spec acceptance criterion through the plan's traceability table. Enumerates every item and its Done means from the plan file FIRST, then settles each against the working tree with evidence (it may run the project's configured verify commands), and returns exactly one verdict row per item plus one per requirement. Use after implementation and before review, or for the final per-requirement verdict that lets a spec be marked implemented; also re-checks named items after fixes. Refuses to start without a plan path. Never substitutes generic code-review advice for the per-item check, and never edits anything.
Modern React best practices and anti-pattern catalog (2025-26). Use when writing, reviewing, or refactoring React components, hooks, and state management. Covers component design, state patterns, hooks misuse, performance, data fetching, and code organization.
General-purpose React Testing Library guide with Vitest. Use when writing, reviewing, or setting up React component and hook tests. Covers project setup from scratch, RTL query priority, userEvent, async patterns, mocking strategies, and common anti-patterns. Applicable to any Vite + React project.
Read-only researcher for two kinds of question: what this repository already does and decided (codebase research), and what the world outside it says (external research: library behaviour, API contracts, specs, versions, known errors). Returns a structured report with conclusions, evidence cited as file:line, commits or dated sources, and an explicit list of what it could NOT establish. Asks clarifying questions first when the task carries no concrete question. Never writes a file. Use when someone needs facts before deciding, e.g. 'how does X work here', 'where is Y handled', 'why was Z changed', 'does our code match what the library recommends', 'what changed between versions'. It is the research agent other agents (for example the sdd-engineering agents) dispatch as research-tools:researcher.
Web application security best practices based on OWASP Top 10:2025. Use when reviewing code for vulnerabilities, implementing auth/authorization, handling user input, working with file uploads, managing secrets, or building API endpoints. Covers React, Express, MongoDB, and JWT security.
Retrospective of a finished multi-agent run (spec-creator, /sdd-engineering:run-plan, a Workflow script, any session that dispatched subagents): how many agents ran and in what order, token spend, what each agent found hard or easy, what was duplicated, missed or lost, plus concrete proposals. Output goes to chat and to one append-only entry in the project's retro ledger (config retroLedger, default docs/retro/ledger.md), project learnings included. Source: this conversation's context by default; deep parses the session transcripts. Manual only: runs when the user invokes /sdd-engineering:workflow-retro, never automatically.