Tweet by gokulr

July 19, 2026

PRODUCTSPEC UPDATE: REPO MAINTENANCE We just added repo maintenance commands to the open source ProductSpec repo. (link in comments) ProductSpec started as a way to make product intent readable by humans and executable by agents. The next problem shows up once a team has more than one spec. You get a folder full of Product Specs, Agent Runs, Decision Traces, evidence links, dependencies, and revisions. At that point, the question changes. Which specs are ready for agents? Which specs are blocked? Which ones are missing evidence? Which Agent Runs actually satisfy the Product Spec they claim to implement? Which revision did the agent build against? So we added 3 commands. productspec garden: Scans the repo and reports spec health: Product Specs, Agent Runs, Decision Traces, graph health, missing evidence, stale revision pins, run gaps, unscoped specs, contention, and build waves. productspec reconcile <spec> --against <agent-run>: Checks whether one Agent Run satisfies one Product Spec revision before anyone claims the work is complete. It catches missing checked items, failed items, stale revisions, passed items without evidence, and drift without a Decision Trace. productspec serve --port 4317: Opens a local read-only dashboard over the same repo health report. No hosted service required. No files uploaded. Just a local view of the ProductSpec library in your repo. This matters because agent-led development needs more than a good prompt. It needs a durable product contract. It needs revision pins. It needs evidence. It needs a way to tell when the agent built what the team actually intended. The Product Spec defines the intent. The Agent Run records what happened. Related Artifacts attach evidence. Decision Trace records what changed when reality disagreed. And now garden, reconcile, and serve help teams operate that loop across an actual repo. If you're experimenting with AI coding agents in a real software repo, try running: productspec garden That is the first command I want every agent and every product team to run before picking up consequential work.

Author
gokulr
Date
July 19, 2026
Open on X