# openspec-cn/openspec architecture

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

- Interactive diagram: https://gitdiagram.com/openspec-cn/openspec
- Repository: https://github.com/openspec-cn/openspec

## Overview

OpenSpec is a Node.js CLI for spec-driven development across AI coding tools. A project maintainer initializes a project, creates and iterates on change artifacts (proposal, specs, design, tasks), applies the change, validates it, and archives it. The graph preserves documented setup, tool adaptation, completions, and telemetry capabilities. Relationships for unsampled subsystems are included only where the README documents them; source-level implementation details are limited to indexed or excerpted evidence.

Main entry points: [`src/cli/index.ts`](https://github.com/openspec-cn/openspec/blob/main/src/cli/index.ts) (OpenSpec CLI), [`src/core/validation/validator.ts`](https://github.com/openspec-cn/openspec/blob/main/src/core/validation/validator.ts) (Validator), [`src/core/parsers/change-parser.ts`](https://github.com/openspec-cn/openspec/blob/main/src/core/parsers/change-parser.ts) (Change parser), [`src/core/init.ts`](https://github.com/openspec-cn/openspec/blob/main/src/core/init.ts) (Project setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_cli["OpenSpec CLI<br/>[index.ts]"]
end

subgraph group_workflow["Change workflow"]
  node_change_cmd["Change commands<br/>[change.ts]"]
  node_workflow_cmds["Workflow commands"]
  node_artifact_graph["Artifact graph"]
  node_archive["Change archive<br/>[archive.ts]"]
end

subgraph group_domain["Specs and validation"]
  node_spec_cmd["Spec commands<br/>[spec.ts]"]
  node_spec_parser["Markdown parser<br/>[markdown-parser.ts]"]
  node_change_parser["Change parser<br/>[change-parser.ts]"]
  node_schemas["Domain schemas"]
  node_validator["Validator<br/>[validator.ts]"]
  node_validate_cmd["Validation command<br/>[validate.ts]"]
end

subgraph group_integration["Tool integrations"]
  node_tool_generation["Agent command generation"]
  node_completions["Shell completions"]
  node_completion_cmd["Completion command<br/>[completion.ts]"]
end

subgraph group_platform["Configuration and telemetry"]
  node_init["Project setup<br/>[init.ts]"]
  node_config["Project configuration<br/>[config.ts]"]
  node_telemetry["Usage telemetry<br/>[index.ts]"]
end

node_maintainer(("Project maintainer"))
node_analytics_service[("PostHog")]

node_maintainer -->|"runs commands"| node_cli
node_cli -.->|"initializes project"| node_init
node_cli -->|"dispatches changes"| node_change_cmd
node_cli -->|"dispatches workflow"| node_workflow_cmds
node_cli -->|"invokes archive"| node_archive
node_cli -->|"dispatches specs"| node_spec_cmd
node_cli -.->|"dispatches validation"| node_validate_cmd
node_cli -.->|"dispatches completion"| node_completion_cmd
node_cli -->|"tracks command"| node_telemetry
node_maintainer -->|"iterates artifacts"| node_workflow_cmds
node_workflow_cmds -->|"uses artifact guidance"| node_artifact_graph
node_maintainer -->|"archives change"| node_archive
node_change_cmd -->|"parses change"| node_change_parser
node_change_parser -->|"parses sections"| node_spec_parser
node_spec_parser -->|"uses domain types"| node_schemas
node_change_parser -->|"uses domain types"| node_schemas
node_validate_cmd -->|"runs validation"| node_validator
node_validator -->|"parses changes"| node_change_parser
node_validator -->|"parses specs"| node_spec_parser
node_validator -->|"checks schemas"| node_schemas
node_init -->|"configures project"| node_config
node_init -->|"generates agent commands"| node_tool_generation
node_maintainer -->|"uses AI tools"| node_tool_generation
node_completion_cmd -->|"builds completions"| node_completions
node_telemetry -->|"sends anonymous events"| node_analytics_service

click node_cli "https://github.com/openspec-cn/openspec/blob/main/src/cli/index.ts"
click node_init "https://github.com/openspec-cn/openspec/blob/main/src/core/init.ts"
click node_config "https://github.com/openspec-cn/openspec/blob/main/src/core/config.ts"
click node_change_cmd "https://github.com/openspec-cn/openspec/blob/main/src/commands/change.ts"
click node_workflow_cmds "https://github.com/openspec-cn/openspec/tree/main/src/commands/workflow"
click node_artifact_graph "https://github.com/openspec-cn/openspec/tree/main/src/core/artifact-graph"
click node_archive "https://github.com/openspec-cn/openspec/blob/main/src/core/archive.ts"
click node_spec_cmd "https://github.com/openspec-cn/openspec/blob/main/src/commands/spec.ts"
click node_spec_parser "https://github.com/openspec-cn/openspec/blob/main/src/core/parsers/markdown-parser.ts"
click node_change_parser "https://github.com/openspec-cn/openspec/blob/main/src/core/parsers/change-parser.ts"
click node_schemas "https://github.com/openspec-cn/openspec/tree/main/src/core/schemas"
click node_validator "https://github.com/openspec-cn/openspec/blob/main/src/core/validation/validator.ts"
click node_validate_cmd "https://github.com/openspec-cn/openspec/blob/main/src/commands/validate.ts"
click node_tool_generation "https://github.com/openspec-cn/openspec/tree/main/src/core/command-generation"
click node_completions "https://github.com/openspec-cn/openspec/tree/main/src/core/completions"
click node_completion_cmd "https://github.com/openspec-cn/openspec/blob/main/src/commands/completion.ts"
click node_telemetry "https://github.com/openspec-cn/openspec/blob/main/src/telemetry/index.ts"

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 toneBlue
class node_change_cmd,node_workflow_cmds,node_artifact_graph,node_archive,node_analytics_service toneAmber
class node_spec_cmd,node_spec_parser,node_change_parser,node_schemas,node_validator,node_validate_cmd toneMint
class node_tool_generation,node_completions,node_completion_cmd toneRose
class node_init,node_config,node_telemetry,node_maintainer toneIndigo
```

## Components

### CLI entry

- [OpenSpec CLI](https://github.com/openspec-cn/openspec/blob/main/src/cli/index.ts): `src/cli/index.ts`

### Change workflow

- [Change commands](https://github.com/openspec-cn/openspec/blob/main/src/commands/change.ts): `src/commands/change.ts`
- [Workflow commands](https://github.com/openspec-cn/openspec/tree/main/src/commands/workflow): `src/commands/workflow`
- [Artifact graph](https://github.com/openspec-cn/openspec/tree/main/src/core/artifact-graph): `src/core/artifact-graph`
- [Change archive](https://github.com/openspec-cn/openspec/blob/main/src/core/archive.ts): `src/core/archive.ts`

### Specs and validation

- [Spec commands](https://github.com/openspec-cn/openspec/blob/main/src/commands/spec.ts): `src/commands/spec.ts`
- [Markdown parser](https://github.com/openspec-cn/openspec/blob/main/src/core/parsers/markdown-parser.ts): `src/core/parsers/markdown-parser.ts`
- [Change parser](https://github.com/openspec-cn/openspec/blob/main/src/core/parsers/change-parser.ts): `src/core/parsers/change-parser.ts`
- [Domain schemas](https://github.com/openspec-cn/openspec/tree/main/src/core/schemas): `src/core/schemas`
- [Validator](https://github.com/openspec-cn/openspec/blob/main/src/core/validation/validator.ts): `src/core/validation/validator.ts`
- [Validation command](https://github.com/openspec-cn/openspec/blob/main/src/commands/validate.ts): `src/commands/validate.ts`

### Tool integrations

- [Agent command generation](https://github.com/openspec-cn/openspec/tree/main/src/core/command-generation): `src/core/command-generation`
- [Shell completions](https://github.com/openspec-cn/openspec/tree/main/src/core/completions): `src/core/completions`
- [Completion command](https://github.com/openspec-cn/openspec/blob/main/src/commands/completion.ts): `src/commands/completion.ts`

### Configuration and telemetry

- [Project setup](https://github.com/openspec-cn/openspec/blob/main/src/core/init.ts): `src/core/init.ts`
- [Project configuration](https://github.com/openspec-cn/openspec/blob/main/src/core/config.ts): `src/core/config.ts`
- [Usage telemetry](https://github.com/openspec-cn/openspec/blob/main/src/telemetry/index.ts): `src/telemetry/index.ts`

### Other components

- **Project maintainer**
- **PostHog**

## Connections

- Project maintainer → OpenSpec CLI: runs commands
- OpenSpec CLI → Project setup: initializes project (evidence: `src/cli/index.ts`)
- OpenSpec CLI → Change commands: dispatches changes (evidence: `src/cli/index.ts`)
- OpenSpec CLI → Workflow commands: dispatches workflow (evidence: `src/cli/index.ts`)
- OpenSpec CLI → Change archive: invokes archive (evidence: `src/cli/index.ts`)
- OpenSpec CLI → Spec commands: dispatches specs (evidence: `src/cli/index.ts`)
- OpenSpec CLI → Validation command: dispatches validation (evidence: `src/cli/index.ts`)
- OpenSpec CLI → Completion command: dispatches completion (evidence: `src/cli/index.ts`)
- OpenSpec CLI → Usage telemetry: tracks command (evidence: `src/cli/index.ts`)
- Project maintainer → Workflow commands: iterates artifacts
- Workflow commands → Artifact graph: uses artifact guidance (evidence: `src/commands/workflow/shared.ts`)
- Project maintainer → Change archive: archives change
- Change commands → Change parser: parses change (evidence: `src/commands/change.ts`)
- Change parser → Markdown parser: parses sections (evidence: `src/core/parsers/change-parser.ts`)
- Markdown parser → Domain schemas: uses domain types (evidence: `src/core/parsers/markdown-parser.ts`)
- Change parser → Domain schemas: uses domain types (evidence: `src/core/parsers/change-parser.ts`)
- Validation command → Validator: runs validation (evidence: `src/commands/validate.ts`)
- Validator → Change parser: parses changes (evidence: `src/core/validation/validator.ts`)
- Validator → Markdown parser: parses specs (evidence: `src/core/validation/validator.ts`)
- Validator → Domain schemas: checks schemas (evidence: `src/core/validation/validator.ts`)
- Project setup → Project configuration: configures project (evidence: `src/core/init.ts`)
- Project setup → Agent command generation: generates agent commands (evidence: `src/core/init.ts`)
- Project maintainer → Agent command generation: uses AI tools
- Completion command → Shell completions: builds completions (evidence: `src/commands/completion.ts`)
- Usage telemetry → PostHog: sends anonymous events (evidence: `src/telemetry/index.ts`)