sdd-engineering-team

SDD Engineering Team — Sync-distributed SDD team plugin

A reusable VS Code Agent plugin that ships a Spec-Driven Development (SDD) engineering team: one orchestrator plus seven specialist personas (Product, Project, Full-Stack Engineer, Quality Engineer, QA Analyst, Debugger, UX Designer) and the 11-agent speckit.* SDD-generation pipeline.

Distribution model. This plugin is distributed via the scripts/sync-agents.ps1 sync script, not installed as a Claude-format plugin. Consumer repos end up with copies of the agents / skills / scripts / hooks under their own .github/ tree, with model-tier placeholders resolved and hook paths expanded to absolute consumer-specific paths. The legacy .claude-plugin/ manifest was removed 2026-07-08 when the team confirmed all consumers use the sync model and none enable Claude-plugin variable expansion in hook command execution (the ${CLAUDE_PLUGIN_ROOT} token was silently failing to expand, producing Cannot find module 'D:\scripts\...' errors).

Relationship to Spec Kit: This plugin does not bundle GitHub Spec Kit. It ships:

• the 7 persona agents (orchestrator, Engineer, PM, etc.)
• 11 glue agent definitions (speckit.specify, speckit.plan, …) that call into a separately-installed Spec Kit
• a spec-kit skill documenting how agents discover/use the CLI

To use the SDD workflow you must also, per consuming repo:

1. Install the specify CLI: uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
2. Initialize the repo: specify init . --ai claude (creates .specify/, scripts/, templates/)

Without Spec Kit installed, the personas still work for non-SDD tasks (debugging, bug fixes, code review, browser validation). Only the speckit.* SDD-generation chain breaks (its step 1 calls .specify/scripts/powershell/check-prerequisites.ps1, which won't exist).

Install (sync to consumer repo)

Clone this repo anywhere, then run the sync script against each consuming repo. Model-tier placeholders get resolved per-consumer at sync time:

pwsh -File <this-repo>/scripts/sync-agents.ps1 `
  -TargetRoot "D:\code\<consumer-repo>" `
  -ProjectTag "<consumer-tag>" `
  -FlagshipModel "<flagship picker name> (customendpoint)" `
  -CheapModel "<cheap picker name> (customendpoint)" `
  -IncludeHooks

-IncludeHooks auto-enables -IncludeScripts (every hook invokes a node script under .github/scripts/). Other optional switches: -IncludeSpeckit (11 speckit glue agents), -IncludeSkills, -IncludeMcp.

The consuming repo ends up with:

• .github/agents/*.agent.md — 8 personas with model placeholders resolved
• .github/agents/speckit/*.agent.md — 11 pipeline agents (if -IncludeSpeckit)
• .github/hooks/hooks.json — guard hooks with {{SCRIPTS_DIR}} expanded
• .github/scripts/*.js, *.ps1 — guard scripts + dashboard (sync'd as-is)
• .github/skills/ — skills (if -IncludeSkills)
• .mcp.json — MCP config (if -IncludeMcp)

Idempotent: re-running over an existing sync overwrites with fresh source.

Bundle layout

See Install (sync to consumer repo) above for distribution. Source layout:

Path	Contents
agents/	8 persona agents (*.agent.md) + speckit/ subdir with 11 pipeline agents
skills/	14 markdown skills (one SKILL.md per directory)
hooks/hooks.json	Runtime guardrail hooks — paths use the {{SCRIPTS_DIR}} token, expanded at sync time (-IncludeHooks) to the consumer's absolute .github/scripts/ dir. See Two-Layer Receipt Enforcement below.
.mcp.json	MCP server config (zai-vision, zai-web-search, playwright)
scripts/	Helper scripts (no-op-guard.js, speckit-receipt-guard.js, pm-dashboard-loop.ps1, .Tests.ps1, sync-agents.ps1)

Two-Layer Receipt Enforcement (spec-028 hardening)

This plugin enforces the speckit-provenance discipline at TWO layers — the cognitive layer (persona + orchestrator judgement) is the outer defenence; the runtime layer (PreToolUse hook) is the inner safety net. Spec-028 showed that the cognitive layer alone is unreliable: a frozen subagent dispatch + a well-intentioned persona + a permissive orchestrator produced hand-authored artifacts indistinguishable from real speckit output and required full Bracket 1+2 rollback.

Outer layer (cognitive): every persona with SDD-stage ownership (PdM, senior-engineer, quality-engineer, implementation-engineer) carries a refuse-and-escalate clause telling it to NEVER hand-author a speckit artifact, even if the orchestrator authorizes it. The orchestrator then verifies the receipt marker on every accepted artifact before recording a stage complete (see orchestrator.agent.md → Provenance Verification).