# coodiepee/grspec architecture

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

- Interactive diagram: https://gitdiagram.com/coodiepee/grspec
- Repository: https://github.com/coodiepee/grspec

## Overview

grspec is a CLI framework that structures AI-assisted development around proposals, requirements, designs, task plans, implementation, and archival spec synchronization. The main user workflow starts with project initialization and tool-specific artifact generation, then an AI assistant uses generated workflows to create and apply changes; CLI commands support validation, status, and archive operations. Additional product branches provide tool customization, wiki knowledge, UI/UX guidance, and a terminal dashboard. Several command implementations are not sampled, so links between registered CLI commands and internal subsystems are shown only where the README documents the behavior.

Main entry points: [`src/cli/index.ts`](https://github.com/coodiepee/grspec/blob/main/src/cli/index.ts) (grspec CLI), [`src/commands/workflow/index.ts`](https://github.com/coodiepee/grspec/blob/main/src/commands/workflow/index.ts) (Workflow Commands), [`src/commands/init.ts`](https://github.com/coodiepee/grspec/blob/main/src/commands/init.ts) (Project Init), [`src/core/archive.ts`](https://github.com/coodiepee/grspec/blob/main/src/core/archive.ts) (Archive Changes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI Entry"]
  node_cli["grspec CLI<br/>[index.ts]"]
  node_init["Project Init<br/>[init.ts]"]
end

subgraph group_workflow["Spec Workflow"]
  node_workflow_cmd["Workflow Commands<br/>[index.ts]"]
  node_change_artifacts["Change Artifacts<br/>[new-change.ts]"]
  node_markdown_parser["Markdown Parser<br/>[markdown-parser.ts]"]
  node_change_parser["Change Delta Parser<br/>[change-parser.ts]"]
  node_artifact_graph["Artifact Graph<br/>[index.ts]"]
  node_apply_specs["Apply Specs<br/>[specs-apply.ts]"]
  node_archive["Archive Changes<br/>[archive.ts]"]
  node_validation["Spec Validation<br/>[validator.ts]"]
end

subgraph group_delivery["Tool Delivery"]
  node_command_gen["Command Generation<br/>[index.ts]"]
  node_rule_gen["Rule Generation<br/>[index.ts]"]
  node_skill_templates["Workflow Skills"]
end

subgraph group_knowledge["Knowledge and Design"]
  node_wiki["Wiki Knowledge<br/>[wiki.ts]"]
  node_ui_search["Design Search<br/>[search.ts]"]
  node_ui_review["UX Review<br/>[review.ts]"]
end

subgraph group_management["Project Management"]
  node_dashboard["Terminal Dashboard<br/>[view.ts]"]
  node_config["Project Config<br/>[project-config.ts]"]
  node_workspace["Project Workspace"]
  node_telemetry["Usage Telemetry<br/>[index.ts]"]
end

node_developer(("Developer"))
node_assistant(("AI Assistant"))
node_analytics_service(("Analytics Service"))

node_developer -->|"runs commands"| node_cli
node_cli -->|"dispatches"| node_init
node_cli -->|"dispatches"| node_workflow_cmd
node_cli -->|"tracks command"| node_telemetry
node_telemetry -.->|"sends events"| node_analytics_service
node_init -->|"generates commands"| node_command_gen
node_init -->|"generates rules"| node_rule_gen
node_init -->|"installs skills"| node_skill_templates
node_init -->|"configures project"| node_config
node_workflow_cmd -->|"creates workflow"| node_change_artifacts
node_assistant -->|"follows instructions"| node_change_artifacts
node_workflow_cmd -->|"resolves artifacts"| node_artifact_graph
node_workflow_cmd -->|"validates changes"| node_validation
node_workflow_cmd -->|"applies specs"| node_apply_specs
node_workflow_cmd -->|"archives changes"| node_archive
node_change_parser -->|"extends parsing"| node_markdown_parser
node_assistant -->|"implements changes"| node_workspace
node_archive -->|"syncs archived specs"| node_workspace
node_cli -->|"opens dashboard"| node_dashboard
node_cli -->|"dispatches wiki"| node_wiki
node_cli -->|"dispatches UI search"| node_ui_search
node_cli -->|"dispatches UX review"| node_ui_review

click node_cli "https://github.com/coodiepee/grspec/blob/main/src/cli/index.ts"
click node_init "https://github.com/coodiepee/grspec/blob/main/src/commands/init.ts"
click node_workflow_cmd "https://github.com/coodiepee/grspec/blob/main/src/commands/workflow/index.ts"
click node_change_artifacts "https://github.com/coodiepee/grspec/blob/main/src/core/templates/workflows/new-change.ts"
click node_markdown_parser "https://github.com/coodiepee/grspec/blob/main/src/core/parsers/markdown-parser.ts"
click node_change_parser "https://github.com/coodiepee/grspec/blob/main/src/core/parsers/change-parser.ts"
click node_artifact_graph "https://github.com/coodiepee/grspec/blob/main/src/core/artifact-graph/index.ts"
click node_apply_specs "https://github.com/coodiepee/grspec/blob/main/src/core/specs-apply.ts"
click node_archive "https://github.com/coodiepee/grspec/blob/main/src/core/archive.ts"
click node_validation "https://github.com/coodiepee/grspec/blob/main/src/core/validation/validator.ts"
click node_command_gen "https://github.com/coodiepee/grspec/blob/main/src/core/command-generation/index.ts"
click node_rule_gen "https://github.com/coodiepee/grspec/blob/main/src/core/rule-generation/index.ts"
click node_skill_templates "https://github.com/coodiepee/grspec/tree/main/src/core/templates/workflows"
click node_wiki "https://github.com/coodiepee/grspec/blob/main/src/core/wiki.ts"
click node_ui_search "https://github.com/coodiepee/grspec/blob/main/src/core/ui/search.ts"
click node_ui_review "https://github.com/coodiepee/grspec/blob/main/src/core/ui/review.ts"
click node_dashboard "https://github.com/coodiepee/grspec/blob/main/src/core/view.ts"
click node_config "https://github.com/coodiepee/grspec/blob/main/src/core/project-config.ts"
click node_telemetry "https://github.com/coodiepee/grspec/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,node_init toneBlue
class node_workflow_cmd,node_change_artifacts,node_markdown_parser,node_change_parser,node_artifact_graph,node_apply_specs,node_archive,node_validation toneAmber
class node_command_gen,node_rule_gen,node_skill_templates toneMint
class node_wiki,node_ui_search,node_ui_review toneRose
class node_dashboard,node_config,node_workspace,node_telemetry,node_developer,node_assistant,node_analytics_service toneIndigo
```

## Components

### CLI Entry

- [grspec CLI](https://github.com/coodiepee/grspec/blob/main/src/cli/index.ts): `src/cli/index.ts`
- [Project Init](https://github.com/coodiepee/grspec/blob/main/src/commands/init.ts): `src/commands/init.ts`

### Spec Workflow

- [Workflow Commands](https://github.com/coodiepee/grspec/blob/main/src/commands/workflow/index.ts): `src/commands/workflow/index.ts`
- [Change Artifacts](https://github.com/coodiepee/grspec/blob/main/src/core/templates/workflows/new-change.ts): `src/core/templates/workflows/new-change.ts`
- [Markdown Parser](https://github.com/coodiepee/grspec/blob/main/src/core/parsers/markdown-parser.ts): `src/core/parsers/markdown-parser.ts`
- [Change Delta Parser](https://github.com/coodiepee/grspec/blob/main/src/core/parsers/change-parser.ts): `src/core/parsers/change-parser.ts`
- [Artifact Graph](https://github.com/coodiepee/grspec/blob/main/src/core/artifact-graph/index.ts): `src/core/artifact-graph/index.ts`
- [Apply Specs](https://github.com/coodiepee/grspec/blob/main/src/core/specs-apply.ts): `src/core/specs-apply.ts`
- [Archive Changes](https://github.com/coodiepee/grspec/blob/main/src/core/archive.ts): `src/core/archive.ts`
- [Spec Validation](https://github.com/coodiepee/grspec/blob/main/src/core/validation/validator.ts): `src/core/validation/validator.ts`

### Tool Delivery

- [Command Generation](https://github.com/coodiepee/grspec/blob/main/src/core/command-generation/index.ts): `src/core/command-generation/index.ts`
- [Rule Generation](https://github.com/coodiepee/grspec/blob/main/src/core/rule-generation/index.ts): `src/core/rule-generation/index.ts`
- [Workflow Skills](https://github.com/coodiepee/grspec/tree/main/src/core/templates/workflows): `src/core/templates/workflows`

### Knowledge and Design

- [Wiki Knowledge](https://github.com/coodiepee/grspec/blob/main/src/core/wiki.ts): `src/core/wiki.ts`
- [Design Search](https://github.com/coodiepee/grspec/blob/main/src/core/ui/search.ts): `src/core/ui/search.ts`
- [UX Review](https://github.com/coodiepee/grspec/blob/main/src/core/ui/review.ts): `src/core/ui/review.ts`

### Project Management

- [Terminal Dashboard](https://github.com/coodiepee/grspec/blob/main/src/core/view.ts): `src/core/view.ts`
- [Project Config](https://github.com/coodiepee/grspec/blob/main/src/core/project-config.ts): `src/core/project-config.ts`
- **Project Workspace**
- [Usage Telemetry](https://github.com/coodiepee/grspec/blob/main/src/telemetry/index.ts): `src/telemetry/index.ts`

### Other components

- **Developer**
- **AI Assistant**
- **Analytics Service**

## Connections

- Developer → grspec CLI: runs commands
- grspec CLI → Project Init: dispatches
- grspec CLI → Workflow Commands: dispatches
- grspec CLI → Usage Telemetry: tracks command
- Usage Telemetry → Analytics Service: sends events
- Project Init → Command Generation: generates commands
- Project Init → Rule Generation: generates rules
- Project Init → Workflow Skills: installs skills
- Project Init → Project Config: configures project
- Workflow Commands → Change Artifacts: creates workflow
- AI Assistant → Change Artifacts: follows instructions
- Workflow Commands → Artifact Graph: resolves artifacts
- Workflow Commands → Spec Validation: validates changes
- Workflow Commands → Apply Specs: applies specs
- Workflow Commands → Archive Changes: archives changes
- Change Delta Parser → Markdown Parser: extends parsing
- AI Assistant → Project Workspace: implements changes
- Archive Changes → Project Workspace: syncs archived specs
- grspec CLI → Terminal Dashboard: opens dashboard
- grspec CLI → Wiki Knowledge: dispatches wiki
- grspec CLI → Design Search: dispatches UI search
- grspec CLI → UX Review: dispatches UX review