# alfredoperez/speckit-companion architecture

> Architecture diagram of the GitHub repository alfredoperez/speckit-companion, 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/alfredoperez/speckit-companion
- Repository: https://github.com/alfredoperez/speckit-companion

## Overview

SpecKit Companion is a VS Code spec-driven development workspace: developers choose a workflow, dispatch AI-assisted steps, and follow recorded progress through a structured spec viewer. Its major branches include pipeline customization, inline review, living specs, and sidebar steering documents. The graph follows only relationships stated in the README or visible in supplied excerpts and SOURCE INDEX references; several substantial viewer and living-spec internals were not sampled, so their connections are intentionally limited.

Main entry points: [`apps/vscode/src/ai-providers/aiProvider.ts`](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/ai-providers/aiProvider.ts) (AI providers), [`apps/vscode/src/features/workflows/workflowManager.ts`](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/workflows/workflowManager.ts) (Workflow manager), [`apps/speckit-extension/scripts/build-pipeline.py`](https://github.com/alfredoperez/speckit-companion/blob/main/apps/speckit-extension/scripts/build-pipeline.py) (Pipeline build), [`apps/vscode/src/features/specs/pipelineBuildCommands.ts`](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/specs/pipelineBuildCommands.ts) (Pipeline builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow execution"]
  node_extension["VS Code extension<br/>[extension.ts]"]
  node_workflow_manager["Workflow manager<br/>[workflowManager.ts]"]
  node_pipeline_resolution["Pipeline resolution"]
  node_ai_provider["AI providers<br/>[aiProvider.ts]"]
  node_agent_manager["Agent manager<br/>[agentManager.ts]"]
  node_spec_context["Spec context"]
  node_terminal["Integrated terminal"]
end

subgraph group_pipeline["Pipeline customization"]
  node_pipeline_builder["Pipeline builder"]
  node_pipeline_graph["Pipeline graph<br/>[pipelineGraph.ts]"]
  node_pipeline_contract["Pipeline contract<br/>[pipeline.ts]"]
  node_builder_ui["Builder interface<br/>[index.tsx]"]
  node_pipeline_build["Pipeline build<br/>[build-pipeline.py]"]
  node_command_assembly["Command assembly<br/>[assemble_nodes.py]"]
  node_companion_config["Workflow configuration"]
end

subgraph group_review["Spec review"]
  node_spec_viewer["Spec viewer"]
  node_viewer_app["Viewer interface<br/>[App.tsx]"]
  node_viewer_messages["Viewer messages<br/>[messageHandlers.ts]"]
  node_inline_review["Inline review<br/>[reviewComments.ts]"]
  node_spec_editor["Spec editor"]
end

subgraph group_workspace["Workspace context"]
  node_living_specs["Living specs"]
  node_spec_sidebar["Specs sidebar"]
  node_steering["Steering documents<br/>[steeringManager.ts]"]
  node_project_files["Project specs"]
end

node_developer(("Developer"))
node_ai_agent(("AI agent"))

node_developer -->|"uses"| node_extension
node_extension -.->|"configures"| node_workflow_manager
node_workflow_manager -->|"selects provider"| node_ai_provider
node_workflow_manager -->|"resolves workflow"| node_pipeline_resolution
node_pipeline_resolution -->|"reads context"| node_spec_context
node_ai_provider -->|"dispatches prompt"| node_terminal
node_terminal -->|"runs commands"| node_ai_agent
node_agent_manager -->|"checks provider"| node_ai_provider
node_spec_viewer -.->|"renders"| node_viewer_app
node_viewer_app -.->|"sends actions"| node_viewer_messages
node_viewer_messages -.->|"handles comments"| node_inline_review
node_inline_review -.->|"dispatches refinements"| node_ai_provider
node_spec_editor -.->|"writes specs"| node_project_files
node_living_specs -.->|"provides context"| node_spec_context
node_spec_sidebar -.->|"shows status"| node_project_files
node_steering -->|"dispatches prompts"| node_ai_provider
node_pipeline_builder -->|"requests graph"| node_pipeline_graph
node_pipeline_builder -->|"runs build"| node_pipeline_build
node_pipeline_graph -->|"returns structure"| node_pipeline_contract
node_builder_ui -->|"uses messages"| node_pipeline_contract
node_pipeline_build -->|"loads config"| node_companion_config
node_pipeline_build -->|"assembles commands"| node_command_assembly
node_companion_config -.->|"configures workflow"| node_project_files

click node_extension "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/extension.ts"
click node_workflow_manager "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/workflows/workflowManager.ts"
click node_pipeline_resolution "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/workflows/pipelineResolution.ts"
click node_ai_provider "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/ai-providers/aiProvider.ts"
click node_agent_manager "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/agents/agentManager.ts"
click node_spec_viewer "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/spec-viewer/specViewerProvider.ts"
click node_viewer_app "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/webview/src/spec-viewer/App.tsx"
click node_viewer_messages "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/spec-viewer/messageHandlers.ts"
click node_inline_review "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/spec-viewer/reviewComments.ts"
click node_spec_editor "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/spec-editor/specDraftManager.ts"
click node_living_specs "https://github.com/alfredoperez/speckit-companion/tree/main/apps/vscode/src/features/living-specs"
click node_spec_sidebar "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/specs/specExplorerProvider.ts"
click node_steering "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/steering/steeringManager.ts"
click node_spec_context "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/specs/specContextReader.ts"
click node_pipeline_builder "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/specs/pipelineBuildCommands.ts"
click node_pipeline_graph "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/specs/pipelineGraph.ts"
click node_pipeline_contract "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/protocol/pipeline.ts"
click node_builder_ui "https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/webview/src/pipeline-builder/index.tsx"
click node_pipeline_build "https://github.com/alfredoperez/speckit-companion/blob/main/apps/speckit-extension/scripts/build-pipeline.py"
click node_command_assembly "https://github.com/alfredoperez/speckit-companion/blob/main/apps/speckit-extension/scripts/assemble_nodes.py"
click node_companion_config "https://github.com/alfredoperez/speckit-companion/blob/main/apps/speckit-extension/scripts/companion_config.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_extension,node_workflow_manager,node_pipeline_resolution,node_ai_provider,node_agent_manager,node_spec_context,node_terminal toneBlue
class node_pipeline_builder,node_pipeline_graph,node_pipeline_contract,node_builder_ui,node_pipeline_build,node_command_assembly,node_companion_config toneAmber
class node_spec_viewer,node_viewer_app,node_viewer_messages,node_inline_review,node_spec_editor toneMint
class node_living_specs,node_spec_sidebar,node_steering,node_project_files toneRose
class node_developer,node_ai_agent toneIndigo
```

## Components

### Workflow execution

- [VS Code extension](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/extension.ts): `apps/vscode/src/extension.ts`
- [Workflow manager](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/workflows/workflowManager.ts): `apps/vscode/src/features/workflows/workflowManager.ts`
- [Pipeline resolution](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/workflows/pipelineResolution.ts): `apps/vscode/src/features/workflows/pipelineResolution.ts`
- [AI providers](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/ai-providers/aiProvider.ts): `apps/vscode/src/ai-providers/aiProvider.ts`
- [Agent manager](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/agents/agentManager.ts): `apps/vscode/src/features/agents/agentManager.ts`
- [Spec context](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/specs/specContextReader.ts): `apps/vscode/src/features/specs/specContextReader.ts`
- **Integrated terminal**

### Pipeline customization

- [Pipeline builder](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/specs/pipelineBuildCommands.ts): `apps/vscode/src/features/specs/pipelineBuildCommands.ts`
- [Pipeline graph](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/specs/pipelineGraph.ts): `apps/vscode/src/features/specs/pipelineGraph.ts`
- [Pipeline contract](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/protocol/pipeline.ts): `apps/vscode/src/protocol/pipeline.ts`
- [Builder interface](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/webview/src/pipeline-builder/index.tsx): `apps/vscode/webview/src/pipeline-builder/index.tsx`
- [Pipeline build](https://github.com/alfredoperez/speckit-companion/blob/main/apps/speckit-extension/scripts/build-pipeline.py): `apps/speckit-extension/scripts/build-pipeline.py`
- [Command assembly](https://github.com/alfredoperez/speckit-companion/blob/main/apps/speckit-extension/scripts/assemble_nodes.py): `apps/speckit-extension/scripts/assemble_nodes.py`
- [Workflow configuration](https://github.com/alfredoperez/speckit-companion/blob/main/apps/speckit-extension/scripts/companion_config.py): `apps/speckit-extension/scripts/companion_config.py`

### Spec review

- [Spec viewer](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/spec-viewer/specViewerProvider.ts): `apps/vscode/src/features/spec-viewer/specViewerProvider.ts`
- [Viewer interface](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/webview/src/spec-viewer/App.tsx): `apps/vscode/webview/src/spec-viewer/App.tsx`
- [Viewer messages](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/spec-viewer/messageHandlers.ts): `apps/vscode/src/features/spec-viewer/messageHandlers.ts`
- [Inline review](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/spec-viewer/reviewComments.ts): `apps/vscode/src/features/spec-viewer/reviewComments.ts`
- [Spec editor](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/spec-editor/specDraftManager.ts): `apps/vscode/src/features/spec-editor/specDraftManager.ts`

### Workspace context

- [Living specs](https://github.com/alfredoperez/speckit-companion/tree/main/apps/vscode/src/features/living-specs): `apps/vscode/src/features/living-specs`
- [Specs sidebar](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/specs/specExplorerProvider.ts): `apps/vscode/src/features/specs/specExplorerProvider.ts`
- [Steering documents](https://github.com/alfredoperez/speckit-companion/blob/main/apps/vscode/src/features/steering/steeringManager.ts): `apps/vscode/src/features/steering/steeringManager.ts`
- **Project specs**

### Other components

- **Developer**
- **AI agent**

## Connections

- Developer → VS Code extension: uses (evidence: `README.md`)
- VS Code extension → Workflow manager: configures
- Workflow manager → AI providers: selects provider (evidence: `apps/vscode/src/features/workflows/workflowManager.ts`)
- Workflow manager → Pipeline resolution: resolves workflow (evidence: `apps/vscode/src/features/workflows/pipelineResolution.ts`)
- Pipeline resolution → Spec context: reads context (evidence: `apps/vscode/src/features/workflows/pipelineResolution.ts`)
- AI providers → Integrated terminal: dispatches prompt (evidence: `apps/vscode/src/ai-providers/aiProvider.ts`)
- Integrated terminal → AI agent: runs commands (evidence: `README.md`)
- Agent manager → AI providers: checks provider (evidence: `apps/vscode/src/features/agents/agentManager.ts`)
- Spec viewer → Viewer interface: renders
- Viewer interface → Viewer messages: sends actions
- Viewer messages → Inline review: handles comments
- Inline review → AI providers: dispatches refinements
- Spec editor → Project specs: writes specs
- Living specs → Spec context: provides context
- Specs sidebar → Project specs: shows status
- Steering documents → AI providers: dispatches prompts (evidence: `apps/vscode/src/features/steering/steeringManager.ts`)
- Pipeline builder → Pipeline graph: requests graph (evidence: `apps/vscode/src/features/specs/pipelineGraph.ts`)
- Pipeline builder → Pipeline build: runs build (evidence: `apps/vscode/src/features/specs/pipelineBuildCommands.ts`)
- Pipeline graph → Pipeline contract: returns structure (evidence: `apps/vscode/src/features/specs/pipelineGraph.ts`)
- Builder interface → Pipeline contract: uses messages
- Pipeline build → Workflow configuration: loads config (evidence: `apps/speckit-extension/scripts/build-pipeline.py`)
- Pipeline build → Command assembly: assembles commands (evidence: `apps/speckit-extension/scripts/build-pipeline.py`)
- Workflow configuration → Project specs: configures workflow