diff --git a/schemas/spec-driven/schema.yaml b/schemas/spec-driven/schema.yaml index 45f61e222..0c3869eca 100644 --- a/schemas/spec-driven/schema.yaml +++ b/schemas/spec-driven/schema.yaml @@ -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//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//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" - diff --git a/src/core/templates/workflows/continue-change.ts b/src/core/templates/workflows/continue-change.ts index 4b2176728..7e4158ef2 100644 --- a/src/core/templates/workflows/continue-change.ts +++ b/src/core/templates/workflows/continue-change.ts @@ -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 --change "" --json @@ -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//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. @@ -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 --change "" --json @@ -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//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. diff --git a/src/core/templates/workflows/ff-change.ts b/src/core/templates/workflows/ff-change.ts index 9e02983be..93db0a598 100644 --- a/src/core/templates/workflows/ff-change.ts +++ b/src/core/templates/workflows/ff-change.ts @@ -31,7 +31,18 @@ export function getFfChangeSkillTemplate(): SkillTemplate { \`\`\` This creates a scaffolded change at \`openspec/changes//\`. -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 "" --json \`\`\` @@ -39,7 +50,7 @@ export function getFfChangeSkillTemplate(): SkillTemplate { - \`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. @@ -133,7 +144,18 @@ export function getOpsxFfCommandTemplate(): CommandTemplate { \`\`\` This creates a scaffolded change at \`openspec/changes//\`. -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 "" --json \`\`\` @@ -141,7 +163,7 @@ export function getOpsxFfCommandTemplate(): CommandTemplate { - \`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. diff --git a/src/core/templates/workflows/propose.ts b/src/core/templates/workflows/propose.ts index 74a9ce2d0..d212ceb34 100644 --- a/src/core/templates/workflows/propose.ts +++ b/src/core/templates/workflows/propose.ts @@ -40,7 +40,18 @@ When ready to implement, run /opsx:apply \`\`\` This creates a scaffolded change at \`openspec/changes//\` 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 "" --json \`\`\` @@ -48,7 +59,7 @@ When ready to implement, run /opsx:apply - \`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. @@ -151,7 +162,18 @@ When ready to implement, run /opsx:apply \`\`\` This creates a scaffolded change at \`openspec/changes//\` 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 "" --json \`\`\` @@ -159,7 +181,7 @@ When ready to implement, run /opsx:apply - \`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.