feat: add structured spec discovery step to proposal instruction (Layer 1)

[sh940701]

Summary

Replaces the vague "Check openspec/specs/ for existing spec names" instruction with a concrete, CLI-based spec discovery step in the proposal workflow.

Before:

Check `openspec/specs/` for existing spec names. Leave empty if no requirement changes.

After:

Before filling this in, discover existing specs by running
`openspec list --specs --json --detail`. Review each spec's `overview`
to understand what it covers. If `--detail` is unavailable, browse
`openspec/specs/` and read each spec's Purpose section instead.

Motivation

As projects accumulate specs, the current approach — "just check the directory" — breaks down:

• The AI often skips it entirely (no enforcement, just a hint)
• When it does check, it reads full spec files into context unnecessarily
• At enterprise scale (20+ capabilities), this burns significant context for discovery alone

This is why main specs feel underutilized (#878) and why growing spec collections become unwieldy (#872). The fix is simple: give the AI a specific CLI command that returns a lightweight catalog (id + overview), so it can determine relevance without loading full spec content.

Scope — Layer 1 only

This PR implements the core proposal from #901: structured CLI-based spec discovery embedded in the proposal instruction.

The extended proposal from #901 (Layer 2 — sub-agent optimization for tools that support delegating tasks to separate contexts) is intentionally deferred to a follow-up PR to keep this change minimal and reviewable.

Changes

File	What changed
schemas/spec-driven/schema.yaml	Proposal instruction: replaced vague "check openspec/specs/" with concrete openspec list --specs --json --detail step, plus fallback for environments without --detail
src/core/templates/workflows/continue-change.ts	Added spec discovery guidance to the proposal.md section in both skill and command templates

Not changed (but covered): propose.ts and ff-change.ts read the proposal instruction from schema.yaml via openspec instructions proposal --json, so they pick up the change automatically.

Related issues

• Closes [Proposal] Automatic spec catalog discovery during proposal creation #901
• Addresses What's the point to maintain main specs? #878 (main specs now actively queried during every proposal)
• Addresses feat: openspec file too many than changes and spec #872 (overview-based filtering avoids loading full spec content)
• Benefits from feat: list cmd support json for specs and archive #700 (--detail flag creates the lightweight catalog this relies on)

Test plan

• Verified schema.yaml is valid YAML with correct indentation
• Verified continue-change.ts compiles (template literal escaping intact)
• Confirmed propose.ts and ff-change.ts don't need changes (they delegate to schema instruction)
• Fallback instruction covers environments where --detail is not yet available
• No breaking changes — instruction text only, no API/CLI/schema structure modifications

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated proposal instructions to require running openspec list --specs --json --detail and using the returned spec id/overview to classify New vs Modified Capabilities before populating the Capabilities section; applied to spec-driven schema and continue-change templates.

Changes

Cohort / File(s)	Summary
Spec-driven Schema schemas/spec-driven/schema.yaml	Mandated running openspec list --specs --json --detail prior to filling New/Modified Capabilities; require using catalog id and reviewing overview for classification; tightened IMPORTANT contract language to always perform discovery.
Continue-change Templates src/core/templates/workflows/continue-change.ts	Added the same pre-fill discovery step and guidance into getContinueChangeSkillTemplate() and getOpsxContinueCommandTemplate() proposal instructions; no control-flow or signature changes.

Sequence Diagram(s)

sequenceDiagram
  participant AI as AI Agent
  participant CLI as CLI (`openspec`)
  participant Catalog as Spec Catalog (JSON)
  participant Proposal as Proposal/`proposal.md`

  AI->>CLI: run `openspec list --specs --json --detail`
  CLI-->>Catalog: return specs JSON (id, title, overview, requirementCount)
  AI->>Catalog: review overviews, map relevant specs
  AI->>Proposal: populate Capabilities section using catalog `id` for Modified entries and mark New entries

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• feat: enhance artifact instructions with inline guidance and XML output #422: Edits the same spec-driven proposal artifact instructions in schemas/spec-driven/schema.yaml.
• fix: clarify spec naming convention and task checkbox format #595: Similar changes to schema and templates to adjust how capabilities/specs are discovered and referenced.
• feat: add Agent Skills for experimental artifact workflow #424: Modifies the continue-change template functions that were also updated here.

Suggested reviewers

• TabishB

Poem

🐰
I hopped the repo trail today,
Found specs in neat JSON array,
No more file-hunts in the hay,
openspec list lights the way,
Proposals snug and ready to play. 🥕✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The pull request fully implements the objectives from issue #901: replaces vague directory-check guidance with a concrete CLI-based spec discovery step using openspec list --specs --json --detail and provides fallback instructions.
Out of Scope Changes check	✅ Passed	All changes are scoped to the proposal instruction and templates as required by issue #901; no new CLI commands, artifacts, or schema structure changes were introduced.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding a structured spec discovery step to the proposal instruction workflow.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}