# sukanth/spec-kit architecture

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

- Interactive diagram: https://gitdiagram.com/sukanth/spec-kit
- Repository: https://github.com/sukanth/spec-kit

## Overview

Spec Kit is a CLI toolkit that prepares projects for AI coding agents and supplies structured development processes plus composable extensions. The user initializes a project with an agent integration, then invokes agent-facing commands to produce specifications, plans, tasks, implementation, and convergence; bug-fixing and idea-assessment processes are independent optional extensions. The repository also supports reusable presets, workflows and overlays, custom workflow steps, bundles, catalogs, authentication, artifact inspection, MCP, and lifecycle events. Edges use README capability/workflow statements or SOURCE INDEX references; unsampled subsystem internals are represented by their existing directories.

Main entry points: [`src/specify_cli/integrations/base.py`](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integrations/base.py) (Agent integrations), [`src/specify_cli/__init__.py`](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/__init__.py) (Specify CLI), [`src/specify_cli/integrations/__init__.py`](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integrations/__init__.py) (Agent registry), [`src/specify_cli/workflows/engine.py`](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/workflows/engine.py) (Workflow engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Project and agents"]
  node_cli["Specify CLI<br/>[__init__.py]"]
  node_init_config["Init options<br/>[_init_options.py]"]
  node_agent_adapters["Agent integrations<br/>[base.py]"]
  node_agent_registry["Agent registry<br/>[__init__.py]"]
  node_agent_commands["Command registration<br/>[agents.py]"]
  node_integration_state["Integration state"]
  node_shared_infrastructure["Shared infrastructure<br/>[shared_infra.py]"]
  node_console["CLI presentation<br/>[_console.py]"]
  node_integration_helpers["Integration helpers<br/>[_helpers.py]"]
  node_integration_installer["Integration installer<br/>[installer.py]"]
  node_integration_manifest["Integration manifest<br/>[manifest.py]"]
  node_invocation_style["Invocation styles"]
  node_utility_helpers["CLI utilities<br/>[_utils.py]"]
end

subgraph group_process["Processes and workflows"]
  node_core_assets["Core templates<br/>[_assets.py]"]
  node_workflows["Workflow engine<br/>[engine.py]"]
  node_workflow_steps["Workflow steps"]
  node_expressions["Workflow expressions<br/>[engine.py]"]
end

subgraph group_customize["Customization"]
  node_extensions["Extensions<br/>[__init__.py]"]
  node_presets["Presets<br/>[_manager.py]"]
  node_preset_commands["Preset commands"]
  node_overlays["Workflow overlays"]
end

subgraph group_ecosystem["Components and catalogs"]
  node_bundles["Bundles"]
  node_catalogs[("Catalogs<br/>[catalogs.py]")]
  node_auth["Catalog authentication"]
  node_artifact_inventory["Artifact inventory<br/>[catalog.py]"]
  node_download_security["Safe downloads"]
end

subgraph group_runtime["Runtime access"]
  node_mcp["MCP server<br/>[server.py]"]
  node_events["Agent events<br/>[__init__.py]"]
end

node_user(("Developer"))

node_user -->|"runs commands"| node_cli
node_cli -->|"records setup"| node_init_config
node_cli -->|"selects integration"| node_agent_registry
node_agent_registry -->|"resolves adapter"| node_agent_adapters
node_agent_adapters -->|"registers commands"| node_agent_commands
node_agent_commands -->|"used for registration"| node_preset_commands
node_user -->|"chooses agent"| node_agent_adapters
node_agent_adapters -.->|"installs SDD templates"| node_core_assets
node_user -->|"invokes process"| node_workflows
node_workflows -->|"runs steps"| node_workflow_steps
node_workflows -->|"evaluates expressions"| node_expressions
node_user -->|"installs process"| node_extensions
node_extensions -->|"registers commands"| node_agent_commands
node_user -->|"adapts methodology"| node_presets
node_presets -->|"reconciles commands"| node_preset_commands
node_user -->|"customizes workflows"| node_overlays
node_user -->|"installs setup"| node_bundles
node_user -->|"discovers components"| node_catalogs
node_catalogs -->|"supports private access"| node_auth
node_user -->|"inspects artifacts"| node_artifact_inventory
node_user -.->|"connects MCP client"| node_mcp
node_agent_adapters -->|"installs lifecycle hooks"| node_events
node_cli -->|"renders CLI output"| node_console
node_catalogs -->|"validates downloads"| node_download_security
node_agent_registry -->|"validates catalog data"| node_integration_manifest
node_agent_adapters -.->|"uses helpers"| node_integration_helpers
node_agent_adapters -.->|"loads trusted adapters"| node_integration_installer
node_agent_adapters -->|"formats invocation"| node_invocation_style
node_cli -->|"uses utilities"| node_utility_helpers
node_cli -->|"uses shared services"| node_shared_infrastructure
node_agent_adapters -->|"tracks active integration"| node_integration_state

click node_cli "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/__init__.py"
click node_init_config "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/_init_options.py"
click node_agent_adapters "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integrations/base.py"
click node_agent_registry "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integrations/__init__.py"
click node_agent_commands "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/agents.py"
click node_core_assets "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/_assets.py"
click node_workflows "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/workflows/engine.py"
click node_workflow_steps "https://github.com/sukanth/spec-kit/tree/main/src/specify_cli/workflows/step"
click node_expressions "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/workflows/expressions/engine.py"
click node_extensions "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/extensions/__init__.py"
click node_presets "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/presets/_manager.py"
click node_preset_commands "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/presets/_manager_commands.py"
click node_overlays "https://github.com/sukanth/spec-kit/tree/main/src/specify_cli/workflows/overlay"
click node_bundles "https://github.com/sukanth/spec-kit/tree/main/src/specify_cli/bundles"
click node_catalogs "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/catalogs.py"
click node_auth "https://github.com/sukanth/spec-kit/tree/main/src/specify_cli/authentication"
click node_artifact_inventory "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/artifacts/catalog.py"
click node_mcp "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/mcp_server/server.py"
click node_events "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/events/__init__.py"
click node_integration_state "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integration_state.py"
click node_shared_infrastructure "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/shared_infra.py"
click node_console "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/_console.py"
click node_download_security "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/_download_security.py"
click node_integration_helpers "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integrations/_helpers.py"
click node_integration_installer "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integrations/installer.py"
click node_integration_manifest "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integrations/manifest.py"
click node_invocation_style "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/_invocation_style.py"
click node_utility_helpers "https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/_utils.py"

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_cli,node_init_config,node_agent_adapters,node_agent_registry,node_agent_commands,node_integration_state,node_shared_infrastructure,node_console,node_integration_helpers,node_integration_installer,node_integration_manifest,node_invocation_style,node_utility_helpers toneBlue
class node_core_assets,node_workflows,node_workflow_steps,node_expressions toneAmber
class node_extensions,node_presets,node_preset_commands,node_overlays toneMint
class node_bundles,node_catalogs,node_auth,node_artifact_inventory,node_download_security toneRose
class node_mcp,node_events,node_user toneIndigo
```

## Components

### Project and agents

- [Specify CLI](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/__init__.py): `src/specify_cli/__init__.py`
- [Init options](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/_init_options.py): `src/specify_cli/_init_options.py`
- [Agent integrations](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integrations/base.py): `src/specify_cli/integrations/base.py`
- [Agent registry](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integrations/__init__.py): `src/specify_cli/integrations/__init__.py`
- [Command registration](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/agents.py): `src/specify_cli/agents.py`
- [Integration state](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integration_state.py): `src/specify_cli/integration_state.py`
- [Shared infrastructure](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/shared_infra.py): `src/specify_cli/shared_infra.py`
- [CLI presentation](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/_console.py): `src/specify_cli/_console.py`
- [Integration helpers](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integrations/_helpers.py): `src/specify_cli/integrations/_helpers.py`
- [Integration installer](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integrations/installer.py): `src/specify_cli/integrations/installer.py`
- [Integration manifest](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/integrations/manifest.py): `src/specify_cli/integrations/manifest.py`
- [Invocation styles](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/_invocation_style.py): `src/specify_cli/_invocation_style.py`
- [CLI utilities](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/_utils.py): `src/specify_cli/_utils.py`

### Processes and workflows

- [Core templates](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/_assets.py): `src/specify_cli/_assets.py`
- [Workflow engine](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/workflows/engine.py): `src/specify_cli/workflows/engine.py`
- [Workflow steps](https://github.com/sukanth/spec-kit/tree/main/src/specify_cli/workflows/step): `src/specify_cli/workflows/step`
- [Workflow expressions](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/workflows/expressions/engine.py): `src/specify_cli/workflows/expressions/engine.py`

### Customization

- [Extensions](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/extensions/__init__.py): `src/specify_cli/extensions/__init__.py`
- [Presets](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/presets/_manager.py): `src/specify_cli/presets/_manager.py`
- [Preset commands](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/presets/_manager_commands.py): `src/specify_cli/presets/_manager_commands.py`
- [Workflow overlays](https://github.com/sukanth/spec-kit/tree/main/src/specify_cli/workflows/overlay): `src/specify_cli/workflows/overlay`

### Components and catalogs

- [Bundles](https://github.com/sukanth/spec-kit/tree/main/src/specify_cli/bundles): `src/specify_cli/bundles`
- [Catalogs](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/catalogs.py): `src/specify_cli/catalogs.py`
- [Catalog authentication](https://github.com/sukanth/spec-kit/tree/main/src/specify_cli/authentication): `src/specify_cli/authentication`
- [Artifact inventory](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/artifacts/catalog.py): `src/specify_cli/artifacts/catalog.py`
- [Safe downloads](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/_download_security.py): `src/specify_cli/_download_security.py`

### Runtime access

- [MCP server](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/mcp_server/server.py): `src/specify_cli/mcp_server/server.py`
- [Agent events](https://github.com/sukanth/spec-kit/blob/main/src/specify_cli/events/__init__.py): `src/specify_cli/events/__init__.py`

### Other components

- **Developer**

## Connections

- Developer → Specify CLI: runs commands (evidence: `README.md`)
- Specify CLI → Init options: records setup (evidence: `src/specify_cli/__init__.py`)
- Specify CLI → Agent registry: selects integration (evidence: `src/specify_cli/__init__.py`)
- Agent registry → Agent integrations: resolves adapter (evidence: `src/specify_cli/integrations/__init__.py`)
- Agent integrations → Command registration: registers commands (evidence: `src/specify_cli/integrations/base.py`)
- Command registration → Preset commands: used for registration (evidence: `src/specify_cli/presets/_manager_commands.py`)
- Developer → Agent integrations: chooses agent (evidence: `README.md`)
- Agent integrations → Core templates: installs SDD templates
- Developer → Workflow engine: invokes process (evidence: `README.md`)
- Workflow engine → Workflow steps: runs steps (evidence: `src/specify_cli/workflows/engine.py`)
- Workflow engine → Workflow expressions: evaluates expressions (evidence: `src/specify_cli/workflows/expressions/engine.py`)
- Developer → Extensions: installs process (evidence: `README.md`)
- Extensions → Command registration: registers commands (evidence: `src/specify_cli/extensions/__init__.py`)
- Developer → Presets: adapts methodology (evidence: `README.md`)
- Presets → Preset commands: reconciles commands (evidence: `src/specify_cli/presets/_manager.py`)
- Developer → Workflow overlays: customizes workflows (evidence: `README.md`)
- Developer → Bundles: installs setup (evidence: `README.md`)
- Developer → Catalogs: discovers components (evidence: `README.md`)
- Catalogs → Catalog authentication: supports private access (evidence: `README.md`)
- Developer → Artifact inventory: inspects artifacts (evidence: `README.md`)
- Developer → MCP server: connects MCP client
- Agent integrations → Agent events: installs lifecycle hooks (evidence: `src/specify_cli/events/__init__.py`)
- Specify CLI → CLI presentation: renders CLI output (evidence: `src/specify_cli/__init__.py`)
- Catalogs → Safe downloads: validates downloads
- Agent registry → Integration manifest: validates catalog data (evidence: `src/specify_cli/integrations/__init__.py`)
- Agent integrations → Integration helpers: uses helpers
- Agent integrations → Integration installer: loads trusted adapters (evidence: `src/specify_cli/integrations/installer.py`)
- Agent integrations → Invocation styles: formats invocation (evidence: `src/specify_cli/integrations/base.py`)
- Specify CLI → CLI utilities: uses utilities (evidence: `src/specify_cli/__init__.py`)
- Specify CLI → Shared infrastructure: uses shared services (evidence: `src/specify_cli/__init__.py`)
- Agent integrations → Integration state: tracks active integration
