Skip to content

feat: add sub-agent spec discovery step to proposal workflows #902

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sh940701 wants to merge 2 commits into
base: main
Choose a base branch
from
+68 −11
Open

feat: add sub-agent spec discovery step to proposal workflows #902

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eca7a04
feat: add structured spec discovery step to proposal instruction
sh940701 Apr 2, 2026
9ae8e0b
feat: add sub-agent spec discovery step to all proposal workflows
sh940701 Apr 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions schemas/spec-driven/schema.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,13 @@ artifacts:
- **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
- **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
- **Capabilities**: Identify which specs will be created or modified:
- **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<name>/spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`).
- **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Check `openspec/specs/` for existing spec names. Leave empty if no requirement changes.
- 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.
- **New Capabilities**: List capabilities being introduced that don't overlap with any existing spec. Each becomes a new `specs/<name>/spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`).
- **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the `id` from the catalog output above. Leave empty if no requirement changes.
- **Impact**: Affected code, APIs, dependencies, or systems.

IMPORTANT: The Capabilities section is critical. It creates the contract between
proposal and specs phases. Research existing specs before filling this in.
proposal and specs phases. Always run spec discovery before filling this in.
Each capability listed here will need a corresponding spec file.

Keep it concise (1-2 pages). Focus on the "why" not the "how" -
Expand Down
12 changes: 12 additions & 0 deletions src/core/templates/workflows/continue-change.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,11 @@ export function getContinueChangeSkillTemplate(): SkillTemplate {
**If artifacts are ready to create** (status shows artifacts with \`status: "ready"\`):
- Pick the FIRST artifact with \`status: "ready"\` from the status output
- **If the artifact is \`proposal\`**: Before creating it, discover existing specs first.
Use the **Agent tool** to spawn a sub-agent for spec discovery:
- **prompt**: "Run \`openspec list --specs --json --detail\` in the project directory. Parse the JSON output — each spec has id, title, overview, and requirementCount. The user wants to build: [describe the change]. Compare each spec's overview against this description and return ONLY the specs that are related. Format your response as a JSON array: [{id, overview, reason}]. Do not return unrelated specs."
- Use the sub-agent's results to classify the proposal's Capabilities section (New vs Modified).
- If sub-agents are unavailable, run \`openspec list --specs --json --detail\` directly.
- Get its instructions:
\`\`\`bash
openspec instructions <artifact-id> --change "<name>" --json
Expand Down Expand Up @@ -100,6 +105,7 @@ Common artifact patterns:
**spec-driven schema** (proposal → specs → design → tasks):
- **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
- Before writing Capabilities, use the **Agent tool** to spawn a sub-agent for spec discovery: "Run \`openspec list --specs --json --detail\` and find specs related to [the proposed change]. Return a JSON array of related specs with id, overview, and reason." If sub-agents are unavailable, run the CLI directly.
- The Capabilities section is critical - each capability listed will need a spec file.
- **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).
- **design.md**: Document technical decisions, architecture, and implementation approach.
Expand Down Expand Up @@ -172,6 +178,11 @@ export function getOpsxContinueCommandTemplate(): CommandTemplate {
**If artifacts are ready to create** (status shows artifacts with \`status: "ready"\`):
- Pick the FIRST artifact with \`status: "ready"\` from the status output
- **If the artifact is \`proposal\`**: Before creating it, discover existing specs first.
Use the **Agent tool** to spawn a sub-agent for spec discovery:
- **prompt**: "Run \`openspec list --specs --json --detail\` in the project directory. Parse the JSON output — each spec has id, title, overview, and requirementCount. The user wants to build: [describe the change]. Compare each spec's overview against this description and return ONLY the specs that are related. Format your response as a JSON array: [{id, overview, reason}]. Do not return unrelated specs."
- Use the sub-agent's results to classify the proposal's Capabilities section (New vs Modified).
- If sub-agents are unavailable, run \`openspec list --specs --json --detail\` directly.
- Get its instructions:
\`\`\`bash
openspec instructions <artifact-id> --change "<name>" --json
Expand Down Expand Up @@ -219,6 +230,7 @@ Common artifact patterns:
**spec-driven schema** (proposal → specs → design → tasks):
- **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
- Before writing Capabilities, use the **Agent tool** to spawn a sub-agent for spec discovery: "Run \`openspec list --specs --json --detail\` and find specs related to [the proposed change]. Return a JSON array of related specs with id, overview, and reason." If sub-agents are unavailable, run the CLI directly.
- The Capabilities section is critical - each capability listed will need a spec file.
- **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).
- **design.md**: Document technical decisions, architecture, and implementation approach.
Expand Down
30 changes: 26 additions & 4 deletions src/core/templates/workflows/ff-change.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,15 +31,26 @@ export function getFfChangeSkillTemplate(): SkillTemplate {
\`\`\`
This creates a scaffolded change at \`openspec/changes/<name>/\`.

3. **Get the artifact build order**
3. **Discover existing specs (via sub-agent)**
Use the **Agent tool** to spawn a sub-agent for spec discovery. This keeps the catalog analysis in a separate context:
- **prompt**: "Run \`openspec list --specs --json --detail\` in the project directory. Parse the JSON output — each spec has id, title, overview, and requirementCount. The user wants to build: [paste the user's description here]. Compare each spec's overview against this description and return ONLY the specs that are related. Format your response as a JSON array: [{id, overview, reason}]. Do not return unrelated specs."
- The sub-agent analyzes all specs in its own context window and returns only the relevant ones.
- Use the sub-agent's results to classify the proposal's Capabilities section (New vs Modified).

If your tool does not support sub-agents, run the CLI directly instead:
\`\`\`bash
openspec list --specs --json --detail
\`\`\`

Comment on lines +34 to +44
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Spec discovery prompt depends on unsupported list output/flag

Line 36 and Line 149 require --detail plus title/overview in list JSON, which is not guaranteed by current CLI/list behavior. This breaks the discovery prerequisite and can cascade into incorrect “New vs Modified” capability classification.

Proposed fix (same adjustment as propose workflow) 
-   - **prompt**: "Run `openspec list --specs --json --detail` in the project directory. Parse the JSON output — each spec has id, title, overview, and requirementCount. The user wants to build: [paste the user's description here]. Compare each spec's overview against this description and return ONLY the specs that are related. Format your response as a JSON array: [{id, overview, reason}]. Do not return unrelated specs."
+   - **prompt**: "Run `openspec list --specs --json` in the project directory to get spec ids. Then read each spec's Purpose/overview (from `openspec/specs/<id>/spec.md`, or `openspec spec show <id> --json` if available). The user wants to build: [paste the user's description here]. Compare each spec overview against this description and return ONLY related specs as JSON: [{id, overview, reason}]. Do not return unrelated specs."
@@
-   openspec list --specs --json --detail
+   openspec list --specs --json
+   # then inspect each listed spec's Purpose/overview before classifying capabilities

Also applies to: 147-157

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/core/templates/workflows/ff-change.ts` around lines 34 - 44, The
spec-discovery prompt currently assumes the CLI returns title/overview via a
--detail flag; update the workflow so it does not depend on an unsupported
--detail output: change the "Discover existing specs (via sub-agent)" prompt to
ask the sub-agent to first run "openspec list --specs --json" and, if
title/overview/requirementCount are missing, to call the per-spec detail command
(e.g., openspec show <id> or openspec get --id) for each ID to gather
title/overview/requirementCount before comparing to the user description; make
the prompt tolerant of missing fields (explicitly state fallbacks) and apply the
same fix to the duplicate block used for capability classification (the repeated
propose/workflow section).

4. **Get the artifact build order**
\`\`\`bash
openspec status --change "<name>" --json
\`\`\`
Parse the JSON to get:
- \`applyRequires\`: array of artifact IDs needed before implementation (e.g., \`["tasks"]\`)
- \`artifacts\`: list of all artifacts with their status and dependencies

4. **Create artifacts in sequence until apply-ready**
5. **Create artifacts in sequence until apply-ready**
Comment on lines +45 to +53
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Final step label should be renumbered to 6

After adding the new discovery step, “Create artifacts” is now Step 5 (Line 53 and Line 166), but “Show final status” remains 5. (Line 85 and Line 198). This should be 6. in both blocks.

Proposed fix 
-5. **Show final status**
+6. **Show final status**

Also applies to: 158-166

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/core/templates/workflows/ff-change.ts` around lines 45 - 53, The "Show
final status" step number was not updated after adding the new "Create
artifacts" step; locate the two occurrences of the final step label in
src/core/templates/workflows/ff-change.ts (the blocks around the "Create
artifacts" and the final status sections) and change the numbered list marker
from "5." to "6." in both places (the first occurrence after the "Create
artifacts" section and the second occurrence in the later block that mirrors
lines ~158-166) so the sequence reads correctly with "Create artifacts" as step
5 and "Show final status" as step 6.


Use the **TodoWrite tool** to track progress through the artifacts.

Expand Down Expand Up @@ -133,15 +144,26 @@ export function getOpsxFfCommandTemplate(): CommandTemplate {
\`\`\`
This creates a scaffolded change at \`openspec/changes/<name>/\`.

3. **Get the artifact build order**
3. **Discover existing specs (via sub-agent)**
Use the **Agent tool** to spawn a sub-agent for spec discovery. This keeps the catalog analysis in a separate context:
- **prompt**: "Run \`openspec list --specs --json --detail\` in the project directory. Parse the JSON output — each spec has id, title, overview, and requirementCount. The user wants to build: [paste the user's description here]. Compare each spec's overview against this description and return ONLY the specs that are related. Format your response as a JSON array: [{id, overview, reason}]. Do not return unrelated specs."
- The sub-agent analyzes all specs in its own context window and returns only the relevant ones.
- Use the sub-agent's results to classify the proposal's Capabilities section (New vs Modified).

If your tool does not support sub-agents, run the CLI directly instead:
\`\`\`bash
openspec list --specs --json --detail
\`\`\`

4. **Get the artifact build order**
\`\`\`bash
openspec status --change "<name>" --json
\`\`\`
Parse the JSON to get:
- \`applyRequires\`: array of artifact IDs needed before implementation (e.g., \`["tasks"]\`)
- \`artifacts\`: list of all artifacts with their status and dependencies

4. **Create artifacts in sequence until apply-ready**
5. **Create artifacts in sequence until apply-ready**

Use the **TodoWrite tool** to track progress through the artifacts.

Expand Down
30 changes: 26 additions & 4 deletions src/core/templates/workflows/propose.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,15 +40,26 @@ When ready to implement, run /opsx:apply
\`\`\`
This creates a scaffolded change at \`openspec/changes/<name>/\` with \`.openspec.yaml\`.

3. **Get the artifact build order**
3. **Discover existing specs (via sub-agent)**
Use the **Agent tool** to spawn a sub-agent for spec discovery. This keeps the catalog analysis in a separate context:
- **prompt**: "Run \`openspec list --specs --json --detail\` in the project directory. Parse the JSON output — each spec has id, title, overview, and requirementCount. The user wants to build: [paste the user's description here]. Compare each spec's overview against this description and return ONLY the specs that are related. Format your response as a JSON array: [{id, overview, reason}]. Do not return unrelated specs."
- The sub-agent analyzes all specs in its own context window and returns only the relevant ones.
- Use the sub-agent's results to classify the proposal's Capabilities section (New vs Modified).

If your tool does not support sub-agents, run the CLI directly instead:
\`\`\`bash
openspec list --specs --json --detail
\`\`\`

Comment on lines +43 to +53
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

--detail contract in instructions does not match current CLI behavior

Line 45 and Line 167 instruct openspec list --specs --json --detail and assume title/overview fields, but current CLI/list implementation does not support that option/shape. This makes Step 3 fail or forces fabricated data during capability classification.

Proposed fix (template guidance aligned to currently available data) 
-   - **prompt**: "Run `openspec list --specs --json --detail` in the project directory. Parse the JSON output — each spec has id, title, overview, and requirementCount. The user wants to build: [paste the user's description here]. Compare each spec's overview against this description and return ONLY the specs that are related. Format your response as a JSON array: [{id, overview, reason}]. Do not return unrelated specs."
+   - **prompt**: "Run `openspec list --specs --json` in the project directory to get spec ids. Then read each spec's Purpose/overview (from `openspec/specs/<id>/spec.md`, or `openspec spec show <id> --json` if available). The user wants to build: [paste the user's description here]. Compare each spec overview against this description and return ONLY related specs as JSON: [{id, overview, reason}]. Do not return unrelated specs."
@@
-   openspec list --specs --json --detail
+   openspec list --specs --json
+   # then inspect each listed spec's Purpose/overview before classifying capabilities

Also applies to: 165-175

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/core/templates/workflows/propose.ts` around lines 43 - 53, The template
in propose.ts instructs the sub-agent to run "openspec list --specs --json
--detail" and parse title/overview, but the current CLI does not emit --detail
or those fields; update the Step 3 prompt and guidance to match the real CLI
output shape (e.g., use "openspec list --specs --json" and parse the actual
fields returned such as id and any available summary/description keys or map
existing fields to overview), and change the JSON response contract in the
prompt to request only fields that the CLI actually provides (e.g., [{id,
<actualSummaryField>, reason}]); ensure any later references that classify
Capabilities (New vs Modified) use the real field names instead of
title/overview.

4. **Get the artifact build order**
\`\`\`bash
openspec status --change "<name>" --json
\`\`\`
Parse the JSON to get:
- \`applyRequires\`: array of artifact IDs needed before implementation (e.g., \`["tasks"]\`)
- \`artifacts\`: list of all artifacts with their status and dependencies

4. **Create artifacts in sequence until apply-ready**
5. **Create artifacts in sequence until apply-ready**
Comment on lines +54 to +62
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Step numbering is now inconsistent after insertion

You renumbered creation to Step 5 (Line 62 and Line 184), but “Show final status” is still labeled 5. (Line 94 and Line 216). Please renumber final status to 6. in both templates.

Proposed fix 
-5. **Show final status**
+6. **Show final status**

Also applies to: 176-184

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/core/templates/workflows/propose.ts` around lines 54 - 62, The "Show
final status" step in the propose workflow template is still labeled "5." after
you inserted a new step; update the numbering to "6." wherever the literal "Show
final status" heading or its preceding numbered list entry shows "5." (there are
two occurrences in this file/template), and ensure any other cross-references or
subsequent step numbers (e.g., the later "Create artifacts..."/renumbered "5.")
remain consistent; search for the exact text "Show final status" and replace its
list number from 5 to 6 and adjust any matching step labels in the same template
blocks (including the duplicate template instance) so numbering is sequential.


Use the **TodoWrite tool** to track progress through the artifacts.

Expand Down Expand Up @@ -151,15 +162,26 @@ When ready to implement, run /opsx:apply
\`\`\`
This creates a scaffolded change at \`openspec/changes/<name>/\` with \`.openspec.yaml\`.

3. **Get the artifact build order**
3. **Discover existing specs (via sub-agent)**
Use the **Agent tool** to spawn a sub-agent for spec discovery. This keeps the catalog analysis in a separate context:
- **prompt**: "Run \`openspec list --specs --json --detail\` in the project directory. Parse the JSON output — each spec has id, title, overview, and requirementCount. The user wants to build: [paste the user's description here]. Compare each spec's overview against this description and return ONLY the specs that are related. Format your response as a JSON array: [{id, overview, reason}]. Do not return unrelated specs."
- The sub-agent analyzes all specs in its own context window and returns only the relevant ones.
- Use the sub-agent's results to classify the proposal's Capabilities section (New vs Modified).

If your tool does not support sub-agents, run the CLI directly instead:
\`\`\`bash
openspec list --specs --json --detail
\`\`\`

4. **Get the artifact build order**
\`\`\`bash
openspec status --change "<name>" --json
\`\`\`
Parse the JSON to get:
- \`applyRequires\`: array of artifact IDs needed before implementation (e.g., \`["tasks"]\`)
- \`artifacts\`: list of all artifacts with their status and dependencies

4. **Create artifacts in sequence until apply-ready**
5. **Create artifacts in sequence until apply-ready**

Use the **TodoWrite tool** to track progress through the artifacts.

Expand Down