feat(propose): make agents read existing specs before writing a proposal #2021

The problem

Agents often write a new proposal without reading the project's existing specs. In a review of real proposal sessions across several projects, fewer than half read any main spec (actual content, not just a directory listing) before drafting. When they did read, the proposal was better almost every time: it used the right names, described current behavior correctly, and avoided conflicts or duplicates. Reading works. Agents just skip it.

When they skip it, they also name capabilities blind, so we get near-duplicates and names based on the task instead of the behavior.

Why what's on main isn't enough

Proposed fix

The fix stops depending on the agent remembering to look:

1. The CLI hands over the inventory. openspec instructions proposal (both text and --json) includes the existing main specs: id, path, a one-line purpose, and the requirement count. It respects stores, and it follows the same pattern as the referenced-store index that instructions already prints. When there are no specs, it says so in so many words, which tells "nothing exists yet" apart from "didn't look."

2. The skills make it a required step. propose, ff and continue (when creating a proposal) get an explicit step: review the inventory, then read every spec that looks related in full with openspec show "<id>" --type spec before drafting. The "inspect the project" wording includes main specs instead of pointing away from them.

3. The proposal shows it looked. In the Capabilities section, each new capability names the closest existing specs that were considered (or says "none related"), and each modified capability uses its exact existing path. Reviewers can then check the work, and an agent can't fill this in without reading.

4. validate catches the misses. It warns (doesn't fail) when a new capability's path is a near-duplicate of an existing spec, and when a "new" capability already exists and should be listed as modified. Reuse the existing fuzzy matcher in src/utils/match.ts.

5. Settle how capabilities should be named (needs a decision). The current rules say what a name shouldn't be but give little help choosing a good one. Options:

   • show good and bad examples taken from the project's own specs,
   • set a rule for how much a capability can cover, or
   • have the agent propose a name and confirm it with the user.

   This can ship after 1–4.

Done when

• openspec instructions proposal --json includes the spec inventory, with tests for a flat layout, a nested layout, a store, and an empty project
• Tests pin the generated propose / ff / continue skills (and the skills/ mirror and parity hashes) to contain the required read-the-specs step
• The proposal template and instructions require the "considered" note for each capability
• validate tests: a near-duplicate path warns, a "new" capability that already exists warns, and an exact reuse or an unrelated name is clean
• Before/after check: run propose on a sample project where the right answer is to modify an existing capability. Before, it creates a near-duplicate; after, it lists the existing path under Modified Capabilities
• Decision recorded on item 5

Related

• Covers [Proposal] Automatic spec catalog discovery during proposal creation #901 (same goal, but delivered by the CLI instead of relying on the prompt)
• Replaces the approach in feat: add sub-agent spec discovery step to proposal workflows #902 (has merge conflicts and depends on feat: list cmd support json for specs and archive #700, which is closed)
• Builds on fix(guidance): teach the spec-inventory verb to generated guidance #1700 and fix(propose): guide capability naming #1997