# gokulrajaram/productspec architecture

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

- Interactive diagram: https://gitdiagram.com/gokulrajaram/productspec
- Repository: https://github.com/gokulrajaram/productspec

## Overview

ProductSpec is a portable product-intent standard with a TypeScript parser/tooling layer that helps humans and coding agents validate specs, retrieve structured intent, track execution evidence, and detect drift. The principal workflow runs from a spec author or agent through CLI/MCP access to parsing and validation, then to Agent Run reconciliation and repository health reporting; evidence-driven changes can be captured in Decision Traces and revised specs. The README documents broader companion-artifact and agent-handoff capabilities. Source excerpts establish the parser, CLI, MCP, and repo-scan connections; unsampled branches are represented only where documented.

Main entry points: [`parsers/ts/src/repo-scan.ts`](https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/repo-scan.ts) (Repository Scanner), [`conformance/valid`](https://github.com/gokulrajaram/productspec/tree/main/conformance/valid) (Product Specs), [`parsers/ts/src/mcp-tools.ts`](https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/mcp-tools.ts) (MCP Tool Logic), [`parsers/ts/src/cli.ts`](https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/cli.ts) (ProductSpec CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["ProductSpec CLI<br/>[cli.ts]"]
  node_mcp["MCP Server<br/>[mcp.ts]"]
  node_tools["MCP Tool Logic<br/>[mcp-tools.ts]"]
end

subgraph group_core["Intent Runtime"]
  node_parser["Parser and Validators<br/>[index.ts]"]
  node_schemas["Artifact Schemas"]
end

subgraph group_operations["Repo Operations"]
  node_repo["Repository Scanner<br/>[repo-scan.ts]"]
  node_health["Garden and Reconcile<br/>[repo-scan.ts]"]
  node_dashboard["Local Dashboard<br/>[repo-scan.ts]"]
end

subgraph group_artifacts["Intent Artifacts"]
  node_specs["Product Specs"]
  node_runs["Agent Run Receipts"]
  node_traces["Decision Traces"]
  node_handoff["Agent Handoff<br/>[mcp-tools.ts]"]
  node_skills["Agent Skills"]
end

node_author(("Author or Agent"))
node_agent(("Coding Agent"))
node_implementation["Implementation and Evidence"]

node_author -->|"authors"| node_specs
node_cli -->|"validates and parses"| node_parser
node_mcp -->|"dispatches tools"| node_tools
node_tools -->|"validates and parses"| node_parser
node_cli -->|"calls scan and reconcile"| node_repo
node_repo -->|"validates artifacts"| node_parser
node_repo -->|"builds health report"| node_health
node_cli -->|"serves report"| node_dashboard
node_repo -->|"serves HTML"| node_dashboard
node_tools -->|"generates"| node_handoff
node_agent -->|"requests structured intent"| node_mcp
node_agent -->|"runs commands"| node_cli
node_tools -->|"reads"| node_specs
node_repo -->|"scans"| node_specs
node_repo -->|"scans and reconciles"| node_runs
node_repo -->|"scans"| node_traces
node_schemas -.->|"defines structure"| node_runs
node_schemas -.->|"defines structure"| node_traces
node_mcp -->|"returns tool results"| node_agent
node_handoff -->|"guides implementation"| node_agent
node_agent -->|"produces"| node_implementation
node_implementation -->|"records execution"| node_runs
node_implementation -->|"attaches evidence"| node_specs
node_traces -->|"records intent changes"| node_specs
node_skills -->|"instructs workflow"| node_agent
node_health -.->|"feeds report"| node_dashboard

click node_cli "https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/cli.ts"
click node_mcp "https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/mcp.ts"
click node_tools "https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/mcp-tools.ts"
click node_parser "https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/index.ts"
click node_specs "https://github.com/gokulrajaram/productspec/tree/main/conformance/valid"
click node_runs "https://github.com/gokulrajaram/productspec/blob/main/schema/agent-run.schema.json"
click node_traces "https://github.com/gokulrajaram/productspec/blob/main/schema/decision-trace.schema.json"
click node_schemas "https://github.com/gokulrajaram/productspec/tree/main/schema"
click node_repo "https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/repo-scan.ts"
click node_health "https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/repo-scan.ts"
click node_dashboard "https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/repo-scan.ts"
click node_handoff "https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/mcp-tools.ts"
click node_skills "https://github.com/gokulrajaram/productspec/tree/main/skills"

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_mcp,node_tools toneBlue
class node_parser,node_schemas toneAmber
class node_repo,node_health,node_dashboard toneMint
class node_specs,node_runs,node_traces,node_handoff,node_skills toneRose
class node_author,node_agent,node_implementation toneIndigo
```

## Components

### User Interfaces

- [ProductSpec CLI](https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/cli.ts): `parsers/ts/src/cli.ts`
- [MCP Server](https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/mcp.ts): `parsers/ts/src/mcp.ts`
- [MCP Tool Logic](https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/mcp-tools.ts): `parsers/ts/src/mcp-tools.ts`

### Intent Runtime

- [Parser and Validators](https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/index.ts): `parsers/ts/src/index.ts`
- [Artifact Schemas](https://github.com/gokulrajaram/productspec/tree/main/schema): `schema`

### Repo Operations

- [Repository Scanner](https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/repo-scan.ts): `parsers/ts/src/repo-scan.ts`
- [Garden and Reconcile](https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/repo-scan.ts): `parsers/ts/src/repo-scan.ts`
- [Local Dashboard](https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/repo-scan.ts): `parsers/ts/src/repo-scan.ts`

### Intent Artifacts

- [Product Specs](https://github.com/gokulrajaram/productspec/tree/main/conformance/valid): `conformance/valid`
- [Agent Run Receipts](https://github.com/gokulrajaram/productspec/blob/main/schema/agent-run.schema.json): `schema/agent-run.schema.json`
- [Decision Traces](https://github.com/gokulrajaram/productspec/blob/main/schema/decision-trace.schema.json): `schema/decision-trace.schema.json`
- [Agent Handoff](https://github.com/gokulrajaram/productspec/blob/main/parsers/ts/src/mcp-tools.ts): `parsers/ts/src/mcp-tools.ts`
- [Agent Skills](https://github.com/gokulrajaram/productspec/tree/main/skills): `skills`

### Other components

- **Author or Agent**
- **Coding Agent**
- **Implementation and Evidence**

## Connections

- Author or Agent → Product Specs: authors (evidence: `README.md`)
- ProductSpec CLI → Parser and Validators: validates and parses (evidence: `parsers/ts/src/cli.ts`)
- MCP Server → MCP Tool Logic: dispatches tools (evidence: `parsers/ts/src/mcp.ts`)
- MCP Tool Logic → Parser and Validators: validates and parses (evidence: `parsers/ts/src/mcp-tools.ts`)
- ProductSpec CLI → Repository Scanner: calls scan and reconcile (evidence: `parsers/ts/src/cli.ts`)
- Repository Scanner → Parser and Validators: validates artifacts (evidence: `parsers/ts/src/repo-scan.ts`)
- Repository Scanner → Garden and Reconcile: builds health report (evidence: `parsers/ts/src/repo-scan.ts`)
- ProductSpec CLI → Local Dashboard: serves report (evidence: `parsers/ts/src/cli.ts`)
- Repository Scanner → Local Dashboard: serves HTML (evidence: `parsers/ts/src/repo-scan.ts`)
- MCP Tool Logic → Agent Handoff: generates (evidence: `parsers/ts/src/mcp.ts`)
- Coding Agent → MCP Server: requests structured intent (evidence: `README.md`)
- Coding Agent → ProductSpec CLI: runs commands (evidence: `README.md`)
- MCP Tool Logic → Product Specs: reads (evidence: `parsers/ts/src/mcp-tools.ts`)
- Repository Scanner → Product Specs: scans (evidence: `parsers/ts/src/repo-scan.ts`)
- Repository Scanner → Agent Run Receipts: scans and reconciles (evidence: `parsers/ts/src/repo-scan.ts`)
- Repository Scanner → Decision Traces: scans (evidence: `parsers/ts/src/repo-scan.ts`)
- Artifact Schemas → Agent Run Receipts: defines structure
- Artifact Schemas → Decision Traces: defines structure
- MCP Server → Coding Agent: returns tool results (evidence: `README.md`)
- Agent Handoff → Coding Agent: guides implementation (evidence: `README.md`)
- Coding Agent → Implementation and Evidence: produces (evidence: `README.md`)
- Implementation and Evidence → Agent Run Receipts: records execution (evidence: `README.md`)
- Implementation and Evidence → Product Specs: attaches evidence (evidence: `README.md`)
- Decision Traces → Product Specs: records intent changes (evidence: `README.md`)
- Agent Skills → Coding Agent: instructs workflow (evidence: `README.md`)
- Garden and Reconcile → Local Dashboard: feeds report (evidence: `parsers/ts/src/repo-scan.ts`)
