[Proposal] Automatic spec catalog discovery during proposal creation

[sh940701]

Problem

The current proposal instruction says:

Check openspec/specs/ for existing spec names.

This is the only guidance the AI gets for discovering existing specs. In practice:

1. The AI often skips this step entirely — there's no structured mechanism to enforce it, just a vague hint buried inside a larger instruction block
2. When it does check, it reads full spec files into context — wasteful when you only need to know what exists and what each spec is about
3. As specs grow, this scales poorly — a project with 20+ capabilities would dump thousands of lines into context just to decide which are relevant

This is exactly why main specs feel underutilized, as raised in #878 ("What's the point to maintain main specs?") and #872 ("openspec files too many"). The specs exist, but the workflow doesn't actively leverage them at the most critical moment — when deciding what a new change touches.

Why this matters at scale

For small projects with 2-3 specs, manually browsing openspec/specs/ works fine. But for teams adopting OpenSpec as a serious engineering harness — especially at enterprise scale with dozens of capabilities across multiple domains — the current approach breaks down:

• An AI agent scanning 30+ spec directories and reading full files burns significant context just for discovery
• Without structured discovery, capabilities get duplicated or contradicted across changes
• The value proposition of accumulated main specs falls apart if they're not reliably consulted

For OpenSpec to serve as a scalable, enterprise-grade development harness, spec discovery needs to be a first-class, structured step — not an afterthought buried in a paragraph.

Proposed Solution

Replace the vague "check openspec/specs/" instruction with a concrete spec discovery step in the proposal instruction, using the CLI to get a lightweight catalog.

Before (current)

Check `openspec/specs/` for existing spec names.

After (proposed)

Before filling this in, run `openspec list --specs --json --detail` to discover
existing specs. Review each spec's `overview` to understand what it covers.

This gives the AI a structured, repeatable workflow instead of a vague hint. The --detail flag (from #700) provides just enough context — id, title, overview, requirementCount — to determine relevance without loading full spec content.

Example output:

{
  "specs": [
    {
      "id": "routine-routing",
      "title": "routine-routing",
      "overview": "Defines in-app routing, deep links, and push notification routing for routine screens.",
      "requirementCount": 8
    },
    {
      "id": "pool-search",
      "title": "pool-search",
      "overview": "Swimming pool search with map integration and region-based filtering.",
      "requirementCount": 12
    }
  ]
}

An AI reading this can immediately tell whether a new "push notification for pool recommendations" change should modify pool-search, routine-routing, or create a new capability — without reading either spec in full.

Extended Proposal: Sub-agent Optimization

For tools that support sub-agents or parallel task execution (e.g., Claude Code's Agent tool, Codex sub-tasks), the discovery step could be delegated to a separate context:

• A sub-agent runs openspec list --specs --json --detail, compares each spec's overview against the proposal description, and returns only the related specs with reasons
• Main context stays clean — the discovery work happens in a disposable context
• This scales to 50+ capabilities without bloating the proposal context

This is entirely optional — tools without sub-agent support just run the CLI inline. The core proposal (structured CLI-based discovery) works everywhere regardless.

Related Issues

Issue	How this helps
#878 ("What's the point to maintain main specs?")	Directly answers this — main specs become actively queried during every proposal via their Purpose/Overview
#872 ("openspec files too many")	Overview-based filtering avoids loading full spec content, making large spec collections manageable
#700 (PR: list --specs --json --detail)	Creates the first real consumer for --detail, giving it a concrete use case in the workflow
#687 ("Incomplete specs after proposal")	Structured discovery reduces missed capabilities — the AI sees all existing specs before writing Capabilities

Scope

• What changes: The proposal artifact instruction in schema.yaml and the proposal guidelines in skill/command templates (continue-change.ts)
• What doesn't change: No new CLI commands, no new artifacts, no schema structure changes
• Dependency: Best with feat: list cmd support json for specs and archive #700 (--detail flag) merged. Without it, the fallback is openspec spec show <id> --json per spec, which still works but requires N calls instead of one.

Alternatives Considered

1. New artifact (discovery.md) — Rejected. Discovery is input to the proposal, not a standalone deliverable. Adds overhead to every change even when there are only 2 specs.

2. Separate /opsx:discover command — Rejected. If it's manual, people won't use it. The whole point is that spec discovery should be embedded in the proposal workflow.

3. Inject full spec catalog into openspec instructions output — Possible but heavy. The proposed approach lets the AI call the CLI on-demand, which is simpler and doesn't bloat the instruction payload.

[TabishB]

I definitely agree that subagent optimization is important; we'll add it after we do some refactoring. Not all coding agents support subagents, and the way to embed them in the skill varies by coding agent.

We can even be smarter and use multiple subagents for search and retrieval.

I'm little unsure about making the process more structured, from the trend in the last 6 months, it seems like models work better when using standard bash tools like grep, find etc to be able to figure out what files exist then figure out what they need to go read in that file.

Most likely, we'll have to add some evals to figure this part out. My current intuition is that there's nothing wrong with telling the model, "Hey, here's our spec directory. Go figure out what specs are relevant to the task at hand."

but thanks, this is a well thought out proposal.