How gokulrajaram/productspec works
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: repo-scan.ts Repository Scanner · valid Product Specs · mcp-tools.ts MCP Tool Logic · cli.ts ProductSpec CLI
Components 16
User Interfaces
- ProductSpec CLI
parsers/ts/src/cli.ts - MCP Server
parsers/ts/src/mcp.ts - MCP Tool Logic
parsers/ts/src/mcp-tools.ts
Intent Runtime
- Parser and Validators
parsers/ts/src/index.ts - Artifact Schemas
schema
Repo Operations
- Repository Scanner
parsers/ts/src/repo-scan.ts - Garden and Reconcile
parsers/ts/src/repo-scan.ts - Local Dashboard
parsers/ts/src/repo-scan.ts
Intent Artifacts
- Product Specs
conformance/valid - Agent Run Receipts
schema/agent-run.schema.json - Decision Traces
schema/decision-trace.schema.json - Agent Handoff
parsers/ts/src/mcp-tools.ts - Agent Skills
skills
Other components
- Author or Agent
- Coding Agent
- Implementation and Evidence
Connections 26
- Author or Agent → Product Specs: authors
README.md - ProductSpec CLI → Parser and Validators: validates and parses
parsers/ts/src/cli.ts - MCP Server → MCP Tool Logic: dispatches tools
parsers/ts/src/mcp.ts - MCP Tool Logic → Parser and Validators: validates and parses
parsers/ts/src/mcp-tools.ts - ProductSpec CLI → Repository Scanner: calls scan and reconcile
parsers/ts/src/cli.ts - Repository Scanner → Parser and Validators: validates artifacts
parsers/ts/src/repo-scan.ts - Repository Scanner → Garden and Reconcile: builds health report
parsers/ts/src/repo-scan.ts - ProductSpec CLI → Local Dashboard: serves report
parsers/ts/src/cli.ts - Repository Scanner → Local Dashboard: serves HTML
parsers/ts/src/repo-scan.ts - MCP Tool Logic → Agent Handoff: generates
parsers/ts/src/mcp.ts - Coding Agent → MCP Server: requests structured intent
README.md - Coding Agent → ProductSpec CLI: runs commands
README.md - MCP Tool Logic → Product Specs: reads
parsers/ts/src/mcp-tools.ts - Repository Scanner → Product Specs: scans
parsers/ts/src/repo-scan.ts - Repository Scanner → Agent Run Receipts: scans and reconciles
parsers/ts/src/repo-scan.ts - Repository Scanner → Decision Traces: scans
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
README.md - Agent Handoff → Coding Agent: guides implementation
README.md - Coding Agent → Implementation and Evidence: produces
README.md - Implementation and Evidence → Agent Run Receipts: records execution
README.md - Implementation and Evidence → Product Specs: attaches evidence
README.md - Decision Traces → Product Specs: records intent changes
README.md - Agent Skills → Coding Agent: instructs workflow
README.md - Garden and Reconcile → Local Dashboard: feeds report
parsers/ts/src/repo-scan.ts