# distinta/sdd-harness-kit architecture

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

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

## Overview

SDD Harness Kit equips a development team’s AI-assisted workflow with canonical skills and agents, OpenSpec templates, deterministic Claude Code hooks, and stack-specific standards. The principal workflow starts with a ticket: product and engineering refine scope and contract, approve a code plan, implement task-by-task with TDD, verify evidence, document, deliver, and retrospect. Hooks enforce safeguards during work; agents and skills guide the phases. The README documents these capabilities and the installation/doctor flow. Source excerpts are limited to adapter examples, so detailed hook-to-skill or installer wiring is not asserted.

Main entry points: [`install.sh`](https://github.com/distinta/sdd-harness-kit/blob/main/install.sh) (Kit installer), [`core/.claude/hooks`](https://github.com/distinta/sdd-harness-kit/tree/main/core/.claude/hooks) (Lifecycle hooks), [`adapters`](https://github.com/distinta/sdd-harness-kit/tree/main/adapters) (Stack adapters), [`core/ai-specs/skills`](https://github.com/distinta/sdd-harness-kit/tree/main/core/ai-specs/skills) (Workflow skills)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Project Setup"]
  node_installer["Kit installer<br/>[install.sh]"]
  node_doctor["Install checker<br/>[doctor.sh]"]
end

subgraph group_workflow["SDD Workflow"]
  node_skills["Workflow skills"]
  node_agents["Phase agents"]
  node_templates["Spec templates"]
  node_openspec["OpenSpec changes"]
end

subgraph group_enforcement["Guardrails"]
  node_hooks["Lifecycle hooks<br/>[hooks]"]
  node_session["Session context<br/>[session-context.sh]"]
  node_standards["Core standards<br/>[base-standards.md]"]
  node_taskrules["Task requirements"]
end

subgraph group_adaptation["Stack Adaptation"]
  node_adapters["Stack adapters"]
  node_fastifyrules["Dependency rules"]
  node_frontend["Frontend guidance"]
end

node_team(("Development team"))
node_ai(("AI copilot"))

node_team -->|"installs kit"| node_installer
node_team -->|"checks setup"| node_doctor
node_installer -->|"installs sources"| node_skills
node_installer -->|"installs sources"| node_agents
node_installer -->|"installs templates"| node_templates
node_team -->|"defines changes"| node_openspec
node_skills -->|"guide spec work"| node_openspec
node_ai -->|"uses guidance"| node_skills
node_ai -->|"uses specialists"| node_agents
node_ai -->|"triggers safeguards"| node_hooks
node_hooks -->|"loads context"| node_session
node_hooks -->|"enforce doctrine"| node_standards
node_hooks -->|"validate tasks"| node_taskrules
node_installer -->|"selects standards"| node_adapters
node_adapters -->|"includes rules"| node_fastifyrules
node_adapters -->|"provides guidance"| node_frontend
node_ai -->|"implements contract"| node_openspec
node_team -->|"reviews evidence"| node_ai

click node_installer "https://github.com/distinta/sdd-harness-kit/blob/main/install.sh"
click node_doctor "https://github.com/distinta/sdd-harness-kit/blob/main/doctor.sh"
click node_skills "https://github.com/distinta/sdd-harness-kit/tree/main/core/ai-specs/skills"
click node_agents "https://github.com/distinta/sdd-harness-kit/tree/main/core/ai-specs/agents"
click node_templates "https://github.com/distinta/sdd-harness-kit/tree/main/core/ai-specs/templates"
click node_openspec "https://github.com/distinta/sdd-harness-kit/tree/main/openspec"
click node_hooks "https://github.com/distinta/sdd-harness-kit/tree/main/core/.claude/hooks"
click node_session "https://github.com/distinta/sdd-harness-kit/blob/main/core/.claude/hooks/session-context.sh"
click node_standards "https://github.com/distinta/sdd-harness-kit/blob/main/core/docs/base-standards.md"
click node_taskrules "https://github.com/distinta/sdd-harness-kit/blob/main/core/docs/openspec-tasks-mandatory-steps.md"
click node_adapters "https://github.com/distinta/sdd-harness-kit/tree/main/adapters"
click node_fastifyrules "https://github.com/distinta/sdd-harness-kit/blob/main/adapters/fastify.dependency-cruiser.js"
click node_frontend "https://github.com/distinta/sdd-harness-kit/blob/main/adapters/react.frontend-standards.md"

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_installer,node_doctor toneBlue
class node_skills,node_agents,node_templates,node_openspec toneAmber
class node_hooks,node_session,node_standards,node_taskrules toneMint
class node_adapters,node_fastifyrules,node_frontend toneRose
class node_team,node_ai toneIndigo
```

## Components

### Project Setup

- [Kit installer](https://github.com/distinta/sdd-harness-kit/blob/main/install.sh): `install.sh`
- [Install checker](https://github.com/distinta/sdd-harness-kit/blob/main/doctor.sh): `doctor.sh`

### SDD Workflow

- [Workflow skills](https://github.com/distinta/sdd-harness-kit/tree/main/core/ai-specs/skills): `core/ai-specs/skills`
- [Phase agents](https://github.com/distinta/sdd-harness-kit/tree/main/core/ai-specs/agents): `core/ai-specs/agents`
- [Spec templates](https://github.com/distinta/sdd-harness-kit/tree/main/core/ai-specs/templates): `core/ai-specs/templates`
- [OpenSpec changes](https://github.com/distinta/sdd-harness-kit/tree/main/openspec): `openspec`

### Guardrails

- [Lifecycle hooks](https://github.com/distinta/sdd-harness-kit/tree/main/core/.claude/hooks): `core/.claude/hooks`
- [Session context](https://github.com/distinta/sdd-harness-kit/blob/main/core/.claude/hooks/session-context.sh): `core/.claude/hooks/session-context.sh`
- [Core standards](https://github.com/distinta/sdd-harness-kit/blob/main/core/docs/base-standards.md): `core/docs/base-standards.md`
- [Task requirements](https://github.com/distinta/sdd-harness-kit/blob/main/core/docs/openspec-tasks-mandatory-steps.md): `core/docs/openspec-tasks-mandatory-steps.md`

### Stack Adaptation

- [Stack adapters](https://github.com/distinta/sdd-harness-kit/tree/main/adapters): `adapters`
- [Dependency rules](https://github.com/distinta/sdd-harness-kit/blob/main/adapters/fastify.dependency-cruiser.js): `adapters/fastify.dependency-cruiser.js`
- [Frontend guidance](https://github.com/distinta/sdd-harness-kit/blob/main/adapters/react.frontend-standards.md): `adapters/react.frontend-standards.md`

### Other components

- **Development team**
- **AI copilot**

## Connections

- Development team → Kit installer: installs kit (evidence: `README.md`)
- Development team → Install checker: checks setup (evidence: `README.md`)
- Kit installer → Workflow skills: installs sources (evidence: `README.md`)
- Kit installer → Phase agents: installs sources (evidence: `README.md`)
- Kit installer → Spec templates: installs templates (evidence: `README.md`)
- Development team → OpenSpec changes: defines changes (evidence: `README.md`)
- Workflow skills → OpenSpec changes: guide spec work (evidence: `README.md`)
- AI copilot → Workflow skills: uses guidance (evidence: `README.md`)
- AI copilot → Phase agents: uses specialists (evidence: `README.md`)
- AI copilot → Lifecycle hooks: triggers safeguards (evidence: `README.md`)
- Lifecycle hooks → Session context: loads context (evidence: `README.md`)
- Lifecycle hooks → Core standards: enforce doctrine (evidence: `README.md`)
- Lifecycle hooks → Task requirements: validate tasks (evidence: `README.md`)
- Kit installer → Stack adapters: selects standards (evidence: `README.md`)
- Stack adapters → Dependency rules: includes rules (evidence: `README.md`)
- Stack adapters → Frontend guidance: provides guidance (evidence: `README.md`)
- AI copilot → OpenSpec changes: implements contract (evidence: `README.md`)
- Development team → AI copilot: reviews evidence (evidence: `README.md`)
