# stasmarkov/sdd-kit architecture

> Architecture diagram of the GitHub repository stasmarkov/sdd-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stasmarkov/sdd-kit
- Repository: https://github.com/stasmarkov/sdd-kit

## Overview

SDD Kit packages spec-driven development workflows, agent skills, hooks, and host integrations for Claude Code, with a spec-board CLI. The principal user journey is to invoke an SDD workflow, which guides work from written specification through implementation, QA/security, and shipping; the extensive workflow content is present in host/plugin trees but mostly unsampled. The adapter sources show a second internal layer that builds and installs host-specific assets and dispatches hooks, while the workflow bridge exposes asynchronous jobs over JSON-RPC. Arrows are limited to README statements and visible bridge calls; workflow internals are not inferred.

Main entry points: [`plugins/sdd-kit/workflows`](https://github.com/stasmarkov/sdd-kit/tree/main/plugins/sdd-kit/workflows) (SDD front door), [`adapters/bridge/engine.mjs`](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/engine.mjs) (Job engine), [`adapters/hooks/registrations.mjs`](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/hooks/registrations.mjs) (Hook registry), [`cli/spec-board.mjs`](https://github.com/stasmarkov/sdd-kit/blob/main/cli/spec-board.mjs) (Spec board)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["SDD workflows"]
  node_sdd_entry["SDD front door"]
  node_spec_workflow["Spec creation<br/>[create-spec.js]"]
  node_build_workflow["Greenfield build"]
  node_bug_workflow["Bug fixing<br/>[fix-bug.js]"]
  node_research_workflow["Tech research<br/>[tech-research.js]"]
  node_qa_workflow["QA and docs<br/>[qa-and-docs.js]"]
  node_security_workflow["Security audit<br/>[security-audit.js]"]
  node_ship_workflow["Feature shipping<br/>[ship-feature.js]"]
  node_stack_tools["Stack support<br/>[stacks.js]"]
end

subgraph group_runtime["Workflow bridge"]
  node_bridge_server["JSON-RPC server<br/>[server.mjs]"]
  node_bridge_engine["Job engine<br/>[engine.mjs]"]
  node_bridge_schema["Input validation<br/>[schema.mjs]"]
  node_run_state[("Run state<br/>[state.mjs]")]
  node_bridge_runtime["Artifact runtime<br/>[runtime.mjs]"]
  node_bridge_agents["Agent definitions<br/>[agents.mjs]"]
  node_bridge_stacks["Stack manifests<br/>[stacks.mjs]"]
end

subgraph group_host["Host integration"]
  node_codex_adapter["Codex adapter<br/>[build.mjs]"]
  node_cursor_adapter["Cursor adapter<br/>[build.mjs]"]
  node_installers["Host installers<br/>[install.mjs]"]
  node_hook_dispatch["Hook dispatcher<br/>[dispatch.mjs]"]
  node_hook_registry["Hook registry<br/>[registrations.mjs]"]
end

subgraph group_utilities["Spec tools"]
  node_spec_board["Spec board<br/>[spec-board.mjs]"]
  node_spec_board_impl["Board implementation<br/>[spec-board.mjs]"]
  node_cli["CLI<br/>[sdd-kit.mjs]"]
end

node_developer(("Developer"))

node_developer -->|"invokes"| node_sdd_entry
node_developer -->|"runs"| node_spec_board
node_sdd_entry -->|"routes to"| node_spec_workflow
node_sdd_entry -->|"routes to"| node_build_workflow
node_sdd_entry -->|"routes to"| node_bug_workflow
node_sdd_entry -->|"routes to"| node_research_workflow
node_sdd_entry -->|"routes to"| node_qa_workflow
node_sdd_entry -->|"routes to"| node_security_workflow
node_sdd_entry -->|"routes to"| node_ship_workflow
node_bridge_server -->|"dispatches calls"| node_bridge_engine
node_bridge_server -->|"validates input"| node_bridge_schema
node_bridge_engine -->|"validates output"| node_bridge_schema
node_bridge_engine -->|"reads and writes"| node_run_state
node_bridge_engine -->|"hashes artifacts"| node_bridge_runtime
node_codex_adapter -->|"uses registrations"| node_hook_registry
node_codex_adapter -->|"uses shared build"| node_installers
node_cursor_adapter -->|"plans hooks"| node_hook_registry
node_cursor_adapter -->|"uses dispatcher"| node_hook_dispatch
node_hook_registry -->|"registers dispatch"| node_hook_dispatch
node_spec_board -.->|"starts board"| node_spec_board_impl
node_cli -.->|"offers command"| node_spec_board

click node_sdd_entry "https://github.com/stasmarkov/sdd-kit/tree/main/plugins/sdd-kit/workflows"
click node_spec_workflow "https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/create-spec.js"
click node_build_workflow "https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/greenfield-build.js"
click node_bug_workflow "https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/fix-bug.js"
click node_research_workflow "https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/tech-research.js"
click node_qa_workflow "https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/qa-and-docs.js"
click node_security_workflow "https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/security-audit.js"
click node_ship_workflow "https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/ship-feature.js"
click node_stack_tools "https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/lib/stacks.js"
click node_bridge_server "https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/server.mjs"
click node_bridge_engine "https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/engine.mjs"
click node_bridge_schema "https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/schema.mjs"
click node_run_state "https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/state.mjs"
click node_bridge_runtime "https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/runtime.mjs"
click node_bridge_agents "https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/agents.mjs"
click node_bridge_stacks "https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/stacks.mjs"
click node_codex_adapter "https://github.com/stasmarkov/sdd-kit/blob/main/adapters/codex/build.mjs"
click node_cursor_adapter "https://github.com/stasmarkov/sdd-kit/blob/main/adapters/cursor/build.mjs"
click node_installers "https://github.com/stasmarkov/sdd-kit/blob/main/adapters/shared/install.mjs"
click node_hook_dispatch "https://github.com/stasmarkov/sdd-kit/blob/main/adapters/hooks/dispatch.mjs"
click node_hook_registry "https://github.com/stasmarkov/sdd-kit/blob/main/adapters/hooks/registrations.mjs"
click node_spec_board "https://github.com/stasmarkov/sdd-kit/blob/main/cli/spec-board.mjs"
click node_spec_board_impl "https://github.com/stasmarkov/sdd-kit/blob/main/hosts/codex/sdd-kit/runtime/skills/spec-board/scripts/spec-board.mjs"
click node_cli "https://github.com/stasmarkov/sdd-kit/blob/main/cli/sdd-kit.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdd_entry,node_spec_workflow,node_build_workflow,node_bug_workflow,node_research_workflow,node_qa_workflow,node_security_workflow,node_ship_workflow,node_stack_tools toneBlue
class node_bridge_server,node_bridge_engine,node_bridge_schema,node_run_state,node_bridge_runtime,node_bridge_agents,node_bridge_stacks toneAmber
class node_codex_adapter,node_cursor_adapter,node_installers,node_hook_dispatch,node_hook_registry toneMint
class node_spec_board,node_spec_board_impl,node_cli toneRose
class node_developer toneIndigo
```

## Components

### SDD workflows

- [SDD front door](https://github.com/stasmarkov/sdd-kit/tree/main/plugins/sdd-kit/workflows): `plugins/sdd-kit/workflows`
- [Spec creation](https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/create-spec.js): `plugins/sdd-kit/workflows/create-spec.js`
- [Greenfield build](https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/greenfield-build.js): `plugins/sdd-kit/workflows/greenfield-build.js`
- [Bug fixing](https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/fix-bug.js): `plugins/sdd-kit/workflows/fix-bug.js`
- [Tech research](https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/tech-research.js): `plugins/sdd-kit/workflows/tech-research.js`
- [QA and docs](https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/qa-and-docs.js): `plugins/sdd-kit/workflows/qa-and-docs.js`
- [Security audit](https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/security-audit.js): `plugins/sdd-kit/workflows/security-audit.js`
- [Feature shipping](https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/ship-feature.js): `plugins/sdd-kit/workflows/ship-feature.js`
- [Stack support](https://github.com/stasmarkov/sdd-kit/blob/main/plugins/sdd-kit/workflows/lib/stacks.js): `plugins/sdd-kit/workflows/lib/stacks.js`

### Workflow bridge

- [JSON-RPC server](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/server.mjs): `adapters/bridge/server.mjs`
- [Job engine](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/engine.mjs): `adapters/bridge/engine.mjs`
- [Input validation](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/schema.mjs): `adapters/bridge/schema.mjs`
- [Run state](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/state.mjs): `adapters/bridge/state.mjs`
- [Artifact runtime](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/runtime.mjs): `adapters/bridge/runtime.mjs`
- [Agent definitions](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/agents.mjs): `adapters/bridge/agents.mjs`
- [Stack manifests](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/bridge/stacks.mjs): `adapters/bridge/stacks.mjs`

### Host integration

- [Codex adapter](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/codex/build.mjs): `adapters/codex/build.mjs`
- [Cursor adapter](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/cursor/build.mjs): `adapters/cursor/build.mjs`
- [Host installers](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/shared/install.mjs): `adapters/shared/install.mjs`
- [Hook dispatcher](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/hooks/dispatch.mjs): `adapters/hooks/dispatch.mjs`
- [Hook registry](https://github.com/stasmarkov/sdd-kit/blob/main/adapters/hooks/registrations.mjs): `adapters/hooks/registrations.mjs`

### Spec tools

- [Spec board](https://github.com/stasmarkov/sdd-kit/blob/main/cli/spec-board.mjs): `cli/spec-board.mjs`
- [Board implementation](https://github.com/stasmarkov/sdd-kit/blob/main/hosts/codex/sdd-kit/runtime/skills/spec-board/scripts/spec-board.mjs): `hosts/codex/sdd-kit/runtime/skills/spec-board/scripts/spec-board.mjs`
- [CLI](https://github.com/stasmarkov/sdd-kit/blob/main/cli/sdd-kit.mjs): `cli/sdd-kit.mjs`

### Other components

- **Developer**

## Connections

- Developer → SDD front door: invokes (evidence: `README.md`)
- Developer → Spec board: runs (evidence: `README.md`)
- SDD front door → Spec creation: routes to (evidence: `README.md`)
- SDD front door → Greenfield build: routes to (evidence: `README.md`)
- SDD front door → Bug fixing: routes to (evidence: `README.md`)
- SDD front door → Tech research: routes to (evidence: `README.md`)
- SDD front door → QA and docs: routes to (evidence: `README.md`)
- SDD front door → Security audit: routes to (evidence: `README.md`)
- SDD front door → Feature shipping: routes to (evidence: `README.md`)
- JSON-RPC server → Job engine: dispatches calls (evidence: `adapters/bridge/server.mjs`)
- JSON-RPC server → Input validation: validates input (evidence: `adapters/bridge/server.mjs`)
- Job engine → Input validation: validates output (evidence: `adapters/bridge/engine.mjs`)
- Job engine → Run state: reads and writes (evidence: `adapters/bridge/engine.mjs`)
- Job engine → Artifact runtime: hashes artifacts (evidence: `adapters/bridge/engine.mjs`)
- Codex adapter → Hook registry: uses registrations (evidence: `adapters/codex/build.mjs`)
- Codex adapter → Host installers: uses shared build (evidence: `adapters/codex/build.mjs`)
- Cursor adapter → Hook registry: plans hooks (evidence: `adapters/cursor/build.mjs`)
- Cursor adapter → Hook dispatcher: uses dispatcher (evidence: `adapters/cursor/build.mjs`)
- Hook registry → Hook dispatcher: registers dispatch (evidence: `adapters/hooks/registrations.mjs`)
- Spec board → Board implementation: starts board
- CLI → Spec board: offers command
