# open-gsd/gsd-core architecture

> Architecture diagram of the GitHub repository open-gsd/gsd-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/open-gsd/gsd-core
- Repository: https://github.com/open-gsd/gsd-core

## Overview

GSD Core is a context-engineering and spec-driven development framework for AI coding agents. Its principal workflow moves a project through discussion, planning, execution, verification, and shipping, with fresh-context subagents doing intensive work and structured artifacts carrying state between sessions. The repository also includes runtime installation and configuration, agent/runtime integration, capability management, and profiling. README statements support the phase-loop relationships; source-index references support the cited internal calls. Unsampled modules are represented at subsystem level where their exact runtime wiring is not shown.

Main entry points: [`src/install-engine.cts`](https://github.com/open-gsd/gsd-core/blob/next/src/install-engine.cts) (Runtime installer), [`src/config-loader.cts`](https://github.com/open-gsd/gsd-core/blob/next/src/config-loader.cts) (Project configuration), [`src/verification.cts`](https://github.com/open-gsd/gsd-core/blob/next/src/verification.cts) (Verify work), [`src/planning-workspace.cts`](https://github.com/open-gsd/gsd-core/blob/next/src/planning-workspace.cts) (Plan and research)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and configuration"]
  node_installer["Runtime installer<br/>[install-engine.cts]"]
  node_artifact_conversion["Artifact conversion"]
  node_artifact_layout["Runtime artifact layout"]
  node_security["Path security<br/>[security.cts]"]
  node_config_loader["Project configuration<br/>[config-loader.cts]"]
  node_runtime_names["Runtime naming"]
  node_shell_projection["Command projection"]
end

subgraph group_workflow["Phase workflow"]
  node_command_hub["Command routing"]
  node_discussion["Discuss decisions"]
  node_planning["Plan and research"]
  node_execution["Execute plans"]
  node_verification["Verify work<br/>[verification.cts]"]
  node_shipping["Ship phase"]
end

subgraph group_artifacts["Project artifacts"]
  node_phase_identity["Phase identity<br/>[phase-id.cts]"]
  node_planning_snapshot["Planning snapshots"]
  node_state_document["Session state<br/>[state-document.cts]"]
  node_io["Filesystem I/O<br/>[io.cts]"]
end

subgraph group_integration["Agent integration"]
  node_capabilities["Capability lifecycle"]
  node_profile_pipeline["Behavioral profiling"]
  node_host_adapters["Host integration"]
end

node_agent(("AI coding agent"))

node_agent -->|"selects runtime"| node_installer
node_installer -->|"converts artifacts"| node_artifact_conversion
node_installer -->|"uses layout"| node_artifact_layout
node_installer -->|"checks paths"| node_security
node_installer -.-> node_config_loader
node_config_loader -->|"normalizes runtime"| node_runtime_names
node_config_loader -->|"projects commands"| node_shell_projection
node_agent -.->|"invokes commands"| node_command_hub
node_command_hub -->|"routes to"| node_verification
node_agent -->|"captures decisions"| node_discussion
node_discussion -->|"informs plan"| node_planning
node_planning -->|"produces plans"| node_execution
node_execution -->|"submits work"| node_verification
node_verification -->|"clears phase"| node_shipping
node_shipping -->|"repeats phase"| node_discussion
node_planning -.->|"persists snapshot"| node_planning_snapshot
node_planning_snapshot -->|"uses phase IDs"| node_phase_identity
node_state_document -->|"uses phase IDs"| node_phase_identity
node_verification -.->|"updates state"| node_state_document
node_config_loader -->|"reads config"| node_io
node_shell_projection -->|"escapes names"| node_runtime_names
node_agent -.->|"manages capabilities"| node_capabilities
node_agent -.->|"profiles sessions"| node_profile_pipeline
node_agent -.->|"uses host binding"| node_host_adapters

click node_installer "https://github.com/open-gsd/gsd-core/blob/next/src/install-engine.cts"
click node_artifact_conversion "https://github.com/open-gsd/gsd-core/blob/next/src/runtime-artifact-conversion.cts"
click node_artifact_layout "https://github.com/open-gsd/gsd-core/blob/next/src/runtime-artifact-layout.cts"
click node_security "https://github.com/open-gsd/gsd-core/blob/next/src/security.cts"
click node_config_loader "https://github.com/open-gsd/gsd-core/blob/next/src/config-loader.cts"
click node_runtime_names "https://github.com/open-gsd/gsd-core/blob/next/src/runtime-name-policy.cts"
click node_shell_projection "https://github.com/open-gsd/gsd-core/blob/next/src/shell-command-projection.cts"
click node_command_hub "https://github.com/open-gsd/gsd-core/blob/next/src/command-routing-hub.cts"
click node_planning "https://github.com/open-gsd/gsd-core/blob/next/src/planning-workspace.cts"
click node_verification "https://github.com/open-gsd/gsd-core/blob/next/src/verification.cts"
click node_phase_identity "https://github.com/open-gsd/gsd-core/blob/next/src/phase-id.cts"
click node_planning_snapshot "https://github.com/open-gsd/gsd-core/blob/next/src/planning-snapshot.cts"
click node_state_document "https://github.com/open-gsd/gsd-core/blob/next/src/state-document.cts"
click node_io "https://github.com/open-gsd/gsd-core/blob/next/src/io.cts"
click node_capabilities "https://github.com/open-gsd/gsd-core/blob/next/gsd-core/bin/lib/capability-registry.cjs"
click node_profile_pipeline "https://github.com/open-gsd/gsd-core/blob/next/src/profile-pipeline.cts"
click node_host_adapters "https://github.com/open-gsd/gsd-core/blob/next/src/host-integration-adapters/cline-sdk-binding.cts"

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_artifact_conversion,node_artifact_layout,node_security,node_config_loader,node_runtime_names,node_shell_projection toneBlue
class node_command_hub,node_discussion,node_planning,node_execution,node_verification,node_shipping toneAmber
class node_phase_identity,node_planning_snapshot,node_state_document,node_io toneMint
class node_capabilities,node_profile_pipeline,node_host_adapters toneRose
class node_agent toneIndigo
```

## Components

### Setup and configuration

- [Runtime installer](https://github.com/open-gsd/gsd-core/blob/next/src/install-engine.cts): `src/install-engine.cts`
- [Artifact conversion](https://github.com/open-gsd/gsd-core/blob/next/src/runtime-artifact-conversion.cts): `src/runtime-artifact-conversion.cts`
- [Runtime artifact layout](https://github.com/open-gsd/gsd-core/blob/next/src/runtime-artifact-layout.cts): `src/runtime-artifact-layout.cts`
- [Path security](https://github.com/open-gsd/gsd-core/blob/next/src/security.cts): `src/security.cts`
- [Project configuration](https://github.com/open-gsd/gsd-core/blob/next/src/config-loader.cts): `src/config-loader.cts`
- [Runtime naming](https://github.com/open-gsd/gsd-core/blob/next/src/runtime-name-policy.cts): `src/runtime-name-policy.cts`
- [Command projection](https://github.com/open-gsd/gsd-core/blob/next/src/shell-command-projection.cts): `src/shell-command-projection.cts`

### Phase workflow

- [Command routing](https://github.com/open-gsd/gsd-core/blob/next/src/command-routing-hub.cts): `src/command-routing-hub.cts`
- **Discuss decisions**
- [Plan and research](https://github.com/open-gsd/gsd-core/blob/next/src/planning-workspace.cts): `src/planning-workspace.cts`
- **Execute plans**
- [Verify work](https://github.com/open-gsd/gsd-core/blob/next/src/verification.cts): `src/verification.cts`
- **Ship phase**

### Project artifacts

- [Phase identity](https://github.com/open-gsd/gsd-core/blob/next/src/phase-id.cts): `src/phase-id.cts`
- [Planning snapshots](https://github.com/open-gsd/gsd-core/blob/next/src/planning-snapshot.cts): `src/planning-snapshot.cts`
- [Session state](https://github.com/open-gsd/gsd-core/blob/next/src/state-document.cts): `src/state-document.cts`
- [Filesystem I/O](https://github.com/open-gsd/gsd-core/blob/next/src/io.cts): `src/io.cts`

### Agent integration

- [Capability lifecycle](https://github.com/open-gsd/gsd-core/blob/next/gsd-core/bin/lib/capability-registry.cjs): `gsd-core/bin/lib/capability-registry.cjs`
- [Behavioral profiling](https://github.com/open-gsd/gsd-core/blob/next/src/profile-pipeline.cts): `src/profile-pipeline.cts`
- [Host integration](https://github.com/open-gsd/gsd-core/blob/next/src/host-integration-adapters/cline-sdk-binding.cts): `src/host-integration-adapters/cline-sdk-binding.cts`

### Other components

- **AI coding agent**

## Connections

- AI coding agent → Runtime installer: selects runtime (evidence: `README.md`)
- Runtime installer → Artifact conversion: converts artifacts (evidence: `src/install-engine.cts`)
- Runtime installer → Runtime artifact layout: uses layout (evidence: `src/install-engine.cts`)
- Runtime installer → Path security: checks paths (evidence: `src/install-engine.cts`)
- Runtime installer → Project configuration
- Project configuration → Runtime naming: normalizes runtime (evidence: `src/config-loader.cts`)
- Project configuration → Command projection: projects commands (evidence: `src/config-loader.cts`)
- AI coding agent → Command routing: invokes commands
- Command routing → Verify work: routes to (evidence: `src/command-routing-hub.cts`)
- AI coding agent → Discuss decisions: captures decisions (evidence: `README.md`)
- Discuss decisions → Plan and research: informs plan (evidence: `README.md`)
- Plan and research → Execute plans: produces plans (evidence: `README.md`)
- Execute plans → Verify work: submits work (evidence: `README.md`)
- Verify work → Ship phase: clears phase (evidence: `README.md`)
- Ship phase → Discuss decisions: repeats phase (evidence: `README.md`)
- Plan and research → Planning snapshots: persists snapshot
- Planning snapshots → Phase identity: uses phase IDs (evidence: `src/health-diagnostic-rules/state-consistency.cts`)
- Session state → Phase identity: uses phase IDs (evidence: `src/health-diagnostic-rules/state-consistency.cts`)
- Verify work → Session state: updates state
- Project configuration → Filesystem I/O: reads config (evidence: `src/config-loader.cts`)
- Command projection → Runtime naming: escapes names (evidence: `src/shell-command-projection.cts`)
- AI coding agent → Capability lifecycle: manages capabilities
- AI coding agent → Behavioral profiling: profiles sessions
- AI coding agent → Host integration: uses host binding