@fission-ai/openspec 1.12.0 → 1.13.1

package/dist/core/templates/workflows/continue-change.js

@@ -1,12 +1,22 @@
+import { optionalWorkflow } from '../optional-workflow.js';
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROJECT_ROOT_GUARD } from './project-root.js';
+/**
+ * The planning-complete handoff. Neither `apply` nor `archive` is guaranteed
+ * to be installed, so each half is resolved at generation time (see
+ * optional-workflow.ts).
+ */
+const PLANNING_COMPLETE_HANDOFF = optionalWorkflow('apply', 'You can now implement this change with `/opsx:apply`.', 'You can now implement this change - `openspec instructions apply --change "<name>" --json` returns the tasks and how to work them.') + ' ' + optionalWorkflow('archive', 'Once implementation and any tracked work are complete, archive it with `/opsx:archive`.', 'Once implementation and any tracked work are complete, archive it with `openspec archive "<name>"`.');
 export function getContinueChangeSkillTemplate() {
     return {
         name: 'openspec-continue-change',
-        description: 'Continue working on an OpenSpec change by creating the next artifact. Use when the user wants to progress their change, create the next artifact, or continue their workflow.',
+        description: 'Continue working on an OpenSpec change by creating the next artifact. Use when the user wants to progress their change, create the next artifact, or continue their workflow. Also use when the user says "openspec continue" or "opsx continue".',
         instructions: `Continue working on a change by creating the next artifact.
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -124,6 +134,8 @@ export function getOpsxContinueCommandTemplate() {
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 **Input**: Optionally specify a change name after \`/opsx:continue\` (e.g., \`/opsx:continue add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -162,7 +174,7 @@ ${STORE_SELECTION_GUIDANCE}
    **If all planning artifacts are complete (\`isPlanningComplete: true\`, or legacy \`isComplete: true\`)**:
    - Congratulate the user
    - Show final status including the schema used
-   - Suggest: "Planning is complete! You can now implement this change with \`/opsx:apply\`. Once implementation and any tracked work are complete, archive it with \`/opsx:archive\`."
+   - Suggest: "Planning is complete! ${PLANNING_COMPLETE_HANDOFF}"
    - STOP
 
    ---

package/dist/core/templates/workflows/explore.js

@@ -1,4 +1,6 @@
+import { optionalWorkflow } from '../optional-workflow.js';
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROJECT_ROOT_GUARD } from './project-root.js';
 const PLANNING_GUIDANCE = `## Planning a Change
 
 When the user is planning a change, guide them toward shared understanding with focused discovery questions. For open-ended discussion, follow the conversation without imposing an interview or a required output.
@@ -20,18 +22,32 @@ across devices in scope? That determines whether local storage is enough.
 If this stays a single-device tool, I recommend keeping SQLite to avoid
 adding a service to operate; shared state would need a separate sync design.
 \`\`\``;
+/**
+ * Explore's handoffs. A custom profile can install explore without propose or
+ * apply, so each reference is resolved at generation time (see
+ * optional-workflow.ts) instead of naming a workflow that may not exist. The
+ * fallbacks point at explore's own capture path and the always-present CLI.
+ */
+const IMPLEMENT_REQUEST_HANDOFF = optionalWorkflow('propose', 'point them at `/opsx:propose`, which turns the discussion into a change', 'offer to capture the discussion as a change, as described below');
+const CAPTURE_PLANNING_HANDOFF = optionalWorkflow('propose', '`/opsx:propose` writes the remaining planning artifacts', 'any remaining planning artifacts can be captured here the same way');
+const CAPTURE_APPLY_HANDOFF = optionalWorkflow('apply', '`/opsx:apply` implements the change once tasks exist', 'implementation works from the change\'s tasks (`openspec instructions apply --change "<name>" --json`), outside explore mode');
+const DISCOVERY_END_HANDOFF = optionalWorkflow('propose', 'Ready to start? Run `/opsx:propose` and this becomes a change.', 'Ready to start? I can capture this as a change.');
+const SUMMARY_NEXT_STEP = optionalWorkflow('propose', '- Turn this into a change: `/opsx:propose`', '- Capture this as a change: ask me to');
+const GUARDRAIL_HANDOFF = optionalWorkflow('propose', '`/opsx:propose` turns the discussion into a change, and the work happens there', 'offer to capture the discussion as a change, and the work happens from that change');
 export function getExploreSkillTemplate() {
     return {
         name: 'openspec-explore',
-        description: 'Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.',
+        description: 'Enter OpenSpec explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements in a project that uses OpenSpec. Use when the user wants to think through something before or during an OpenSpec change. Also use when the user says "openspec explore" or "opsx explore".',
         instructions: `Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
 
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, investigate the codebase, and run read-only commands or tools without confirmation, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create or update OpenSpec change artifacts (proposals, designs, specs) within a confirmed scope—that's capturing thinking, not implementing. Answering design or clarifying questions is never consent to write. Before the first write-capable action, name the artifacts or files you would change and what you would do, ask a direct yes/no question, and wait for the user's confirmation in a separate message. Confirmation covers only the scope you described; ask again before expanding it. For a new change, scaffold it first as described below.
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, investigate the codebase, and run read-only commands or tools without confirmation, but you must NEVER write code or implement features. If the user asks you to implement something, do not start it here: say that explore mode does not implement, and ${IMPLEMENT_REQUEST_HANDOFF}. The work happens from that change, never from explore mode. You MAY create or update OpenSpec change artifacts (proposals, designs, specs) within a confirmed scope—that's capturing thinking, not implementing. Answering design or clarifying questions is never consent to write. Before the first write-capable action, name the artifacts or files you would change and what you would do, ask a direct yes/no question, and wait for the user's confirmation in a separate message. Confirmation covers only the scope you described; ask again before expanding it. An explicit request from the user to capture the exploration as a new change is itself that confirmation, covering the change and the change artifacts the request names; scaffold it first as described below.
 
 **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 ---
 
 ## The Stance
@@ -115,6 +131,14 @@ This tells you:
 - Their names, schemas, and status
 - What the user might be working on
 
+That is the *change* list - work in flight. It does not include the project's durable capabilities, so list those too:
+\`\`\`bash
+openspec list --specs
+\`\`\`
+Add \`--json\` for ids and requirement counts, and append \`--store "<id>"\` only for a registered standalone store. This is the inventory of what the project already claims to do, and \`openspec list\` on its own never shows it. To look at one, run \`openspec show "<spec-id>" --type spec --json --no-scenarios\` (same \`--store\` rule) - it returns that capability's purpose and requirement texts without pulling the whole spec file into context, and \`--type spec\` stops a change of the same name from making it ambiguous.
+
+The filtered read is only an overview. Before deciding what is already covered or what should change, read each relevant spec in full, including scenarios, with \`openspec show "<spec-id>" --type spec\` (same \`--store\` rule).
+
 Then read the project's own context from the resolved root - \`<root.path>/openspec/config.yaml\` (or \`config.yml\`). Use the \`root.path\` returned above, and skip this if neither file exists:
 - \`context\`: project background - tech stack, conventions, constraints
 - \`rules\`: keyed by artifact id - the entries for an artifact apply only when you write that artifact
@@ -128,14 +152,14 @@ Think freely. When insights crystallize, you might offer:
 - "This feels solid enough to start a change. Want me to create a proposal?"
 - Or keep exploring - no pressure to formalize
 
-If the user asks you to capture the exploration as a new change, transition seamlessly into the requested capture:
+If the user asks you to capture the exploration as a new change, that request is the confirmation required above. It covers scaffolding that change and creating the change artifacts the request names, and nothing else. This holds only when the request is theirs: a yes to an offer you made confirms only the scope your offer itself named, so name the change and the artifacts in the offer. Don't re-ask for what they already asked for; do ask before anything beyond it. Transition seamlessly into the requested capture:
 
 1. Run \`openspec new change "<name>"\` (with \`--store <id>\` when applicable) before creating any artifacts. Never create a new change directory under \`openspec/changes/\` by hand; the CLI scaffold creates required metadata such as \`.openspec.yaml\`. Keep the selected \`--store <id>\` on every applicable follow-up \`status\` and \`instructions\` command.
 2. Run \`openspec status --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store), then process the requested artifacts in dependency order. For each requested artifact that is \`ready\`, run \`openspec instructions "<artifact-id>" --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store). Before creating a requested artifact, evaluate any condition in its own \`instruction\` against the explored change; record a deliberate skip instead when the condition does not apply. If a requested artifact is blocked by a direct prerequisite the user did not request, run \`openspec instructions "<prerequisite-id>" --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store) for that prerequisite whether it is \`ready\` or \`blocked\`. If its own \`instruction\` states a condition, evaluate that condition against the explored change and record a deliberate skip only when the condition does not apply. If the condition applies, or the prerequisite is not conditional, treat it as a normal prerequisite and ask before expanding the capture. Do not create an unrequested prerequisite unless the user approves.
 3. Follow the returned \`template\` and \`instruction\` fields. Read completed dependency files listed in \`dependencies\`, and apply \`context\` and \`rules\` as constraints without copying them into the artifact. If the instruction delegates creation to a specific skill or command, invoke it; otherwise write the artifact to \`resolvedOutputPath\`, using the instruction to choose a concrete path when it is a glob. Verify that the selected concrete output exists.
 4. After creating each artifact, re-run \`openspec status --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store) and continue until every requested artifact is \`done\`, \`skipped\`, or was deliberately skipped because its own \`instruction\` stated a condition that did not apply. Tell the user about a deliberate conditional skip, remember it, and do not reconsider it. Dependencies are enablers, not gates: if a requested artifact is still \`blocked\` only because you deliberately skipped a conditional prerequisite, run \`openspec instructions "<artifact-id>" --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store) despite the blocked status, then create it using step 3 only when those recorded conditional skips are its sole missing dependencies. If a requested artifact is blocked by a prerequisite the user did not ask to capture and cannot be conditionally skipped, explain that dependency and ask before expanding the capture.
 
-Capture the artifact(s) the user requested without asking them to invoke another workflow command. If they asked only to start a change, stop after scaffolding and show its status.
+Capture the artifact(s) the user requested without asking them to invoke another workflow command. If they asked only to start a change, stop after scaffolding and show its status. When the requested capture is done, stop there and name where the work continues: ${CAPTURE_PLANNING_HANDOFF}, and ${CAPTURE_APPLY_HANDOFF}. Capturing artifacts never starts implementing them.
 
 ### When a change exists
 
@@ -291,7 +315,7 @@ You: That changes everything.
 
 There's no required ending. Discovery might:
 
-- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Flow into a proposal**: "${DISCOVERY_END_HANDOFF}"
 - **Result in artifact updates**: "Updated design.md with these decisions"
 - **Just provide clarity**: User has what they need, moves on
 - **Continue later**: "We can pick this up anytime"
@@ -308,7 +332,7 @@ When it feels like things are crystallizing, you might summarize:
 **Open questions**: [if any remain]
 
 **Next steps** (if ready):
-- Create a change proposal
+${SUMMARY_NEXT_STEP}
 - Keep exploring: just keep talking
 \`\`\`
 
@@ -318,11 +342,11 @@ But this summary is optional. Sometimes the thinking IS the value.
 
 ## Guardrails
 
-- **Don't implement** - Never write code or implement features. Workflow configuration counts too: creating or editing schemas, templates, or \`openspec/config.yaml\` is a change, not thinking. Creating or updating OpenSpec change artifacts within the confirmed scope is fine, writing anything else is not.
+- **Don't implement** - Never write code or implement features. Workflow configuration counts too: creating or editing schemas, templates, or \`openspec/config.yaml\` is a change, not thinking. Creating or updating OpenSpec change artifacts within the confirmed scope is fine, writing anything else is not. When the user is ready to build, name the handoff rather than starting: ${GUARDRAIL_HANDOFF}.
 - **Don't fake understanding** - If something is unclear, dig deeper
 - **Don't rush** - Discovery is thinking time, not task time
 - **Don't force structure** - Let patterns emerge naturally
-- **Don't auto-capture** - Offer to save insights, don't just do it. Read-only commands and tools need no confirmation. Before the first write-capable action—including \`openspec new change\` or another command that writes files—name the artifacts or files and proposed changes, ask a direct yes/no question, and wait for explicit confirmation in a separate user message. That confirmation covers only the described scope; ask again before expanding it. Answers to design or clarifying questions are never consent to write.
+- **Don't auto-capture** - Offer to save insights, don't just do it. Read-only commands and tools need no confirmation. Before the first write-capable action—including \`openspec new change\` or another command that writes files—name the artifacts or files and proposed changes, ask a direct yes/no question, and wait for explicit confirmation in a separate user message. That confirmation covers only the described scope; ask again before expanding it. Answers to design or clarifying questions are never consent to write. That rule governs \`openspec new change\` whenever you are the one proposing the capture; the user's own capture request is the exception, handled in the capture transition above.
 - **Don't manually scaffold changes** - Never create a new change directory under \`openspec/changes/\` by hand. Always use \`openspec new change "<name>"\` (with \`--store <id>\` when applicable) so required metadata such as \`.openspec.yaml\` is created before writing artifacts.
 - **Do visualize** - A good diagram is worth many paragraphs
 - **Do explore the codebase** - Ground discussions in reality
@@ -340,12 +364,14 @@ export function getOpsxExploreCommandTemplate() {
         tags: ['workflow', 'explore', 'experimental', 'thinking'],
         content: `Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
 
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, investigate the codebase, and run read-only commands or tools without confirmation, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create or update OpenSpec change artifacts (proposals, designs, specs) within a confirmed scope—that's capturing thinking, not implementing. Answering design or clarifying questions is never consent to write. Before the first write-capable action, name the artifacts or files you would change and what you would do, ask a direct yes/no question, and wait for the user's confirmation in a separate message. Confirmation covers only the scope you described; ask again before expanding it. For a new change, scaffold it first as described below.
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, investigate the codebase, and run read-only commands or tools without confirmation, but you must NEVER write code or implement features. If the user asks you to implement something, do not start it here: say that explore mode does not implement, and ${IMPLEMENT_REQUEST_HANDOFF}. The work happens from that change, never from explore mode. You MAY create or update OpenSpec change artifacts (proposals, designs, specs) within a confirmed scope—that's capturing thinking, not implementing. Answering design or clarifying questions is never consent to write. Before the first write-capable action, name the artifacts or files you would change and what you would do, ask a direct yes/no question, and wait for the user's confirmation in a separate message. Confirmation covers only the scope you described; ask again before expanding it. An explicit request from the user to capture the exploration as a new change is itself that confirmation, covering the change and the change artifacts the request names; scaffold it first as described below.
 
 **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 **Input**: The argument after \`/opsx:explore\` is whatever the user wants to think about. Could be:
 - A vague idea: "real-time collaboration"
 - A specific problem: "the auth system is getting unwieldy"
@@ -436,6 +462,14 @@ This tells you:
 - Their names, schemas, and status
 - What the user might be working on
 
+That is the *change* list - work in flight. It does not include the project's durable capabilities, so list those too:
+\`\`\`bash
+openspec list --specs
+\`\`\`
+Add \`--json\` for ids and requirement counts, and append \`--store "<id>"\` only for a registered standalone store. This is the inventory of what the project already claims to do, and \`openspec list\` on its own never shows it. To look at one, run \`openspec show "<spec-id>" --type spec --json --no-scenarios\` (same \`--store\` rule) - it returns that capability's purpose and requirement texts without pulling the whole spec file into context, and \`--type spec\` stops a change of the same name from making it ambiguous.
+
+The filtered read is only an overview. Before deciding what is already covered or what should change, read each relevant spec in full, including scenarios, with \`openspec show "<spec-id>" --type spec\` (same \`--store\` rule).
+
 Then read the project's own context from the resolved root - \`<root.path>/openspec/config.yaml\` (or \`config.yml\`). Use the \`root.path\` returned above, and skip this if neither file exists:
 - \`context\`: project background - tech stack, conventions, constraints
 - \`rules\`: keyed by artifact id - the entries for an artifact apply only when you write that artifact
@@ -451,14 +485,14 @@ Think freely. When insights crystallize, you might offer:
 - "This feels solid enough to start a change. Want me to create a proposal?"
 - Or keep exploring - no pressure to formalize
 
-If the user asks you to capture the exploration as a new change, transition seamlessly into the requested capture:
+If the user asks you to capture the exploration as a new change, that request is the confirmation required above. It covers scaffolding that change and creating the change artifacts the request names, and nothing else. This holds only when the request is theirs: a yes to an offer you made confirms only the scope your offer itself named, so name the change and the artifacts in the offer. Don't re-ask for what they already asked for; do ask before anything beyond it. Transition seamlessly into the requested capture:
 
 1. Run \`openspec new change "<name>"\` (with \`--store <id>\` when applicable) before creating any artifacts. Never create a new change directory under \`openspec/changes/\` by hand; the CLI scaffold creates required metadata such as \`.openspec.yaml\`. Keep the selected \`--store <id>\` on every applicable follow-up \`status\` and \`instructions\` command.
 2. Run \`openspec status --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store), then process the requested artifacts in dependency order. For each requested artifact that is \`ready\`, run \`openspec instructions "<artifact-id>" --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store). Before creating a requested artifact, evaluate any condition in its own \`instruction\` against the explored change; record a deliberate skip instead when the condition does not apply. If a requested artifact is blocked by a direct prerequisite the user did not request, run \`openspec instructions "<prerequisite-id>" --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store) for that prerequisite whether it is \`ready\` or \`blocked\`. If its own \`instruction\` states a condition, evaluate that condition against the explored change and record a deliberate skip only when the condition does not apply. If the condition applies, or the prerequisite is not conditional, treat it as a normal prerequisite and ask before expanding the capture. Do not create an unrequested prerequisite unless the user approves.
 3. Follow the returned \`template\` and \`instruction\` fields. Read completed dependency files listed in \`dependencies\`, and apply \`context\` and \`rules\` as constraints without copying them into the artifact. If the instruction delegates creation to a specific skill or command, invoke it; otherwise write the artifact to \`resolvedOutputPath\`, using the instruction to choose a concrete path when it is a glob. Verify that the selected concrete output exists.
 4. After creating each artifact, re-run \`openspec status --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store) and continue until every requested artifact is \`done\`, \`skipped\`, or was deliberately skipped because its own \`instruction\` stated a condition that did not apply. Tell the user about a deliberate conditional skip, remember it, and do not reconsider it. Dependencies are enablers, not gates: if a requested artifact is still \`blocked\` only because you deliberately skipped a conditional prerequisite, run \`openspec instructions "<artifact-id>" --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store) despite the blocked status, then create it using step 3 only when those recorded conditional skips are its sole missing dependencies. If a requested artifact is blocked by a prerequisite the user did not ask to capture and cannot be conditionally skipped, explain that dependency and ask before expanding the capture.
 
-Capture the artifact(s) the user requested without asking them to invoke another workflow command. If they asked only to start a change, stop after scaffolding and show its status.
+Capture the artifact(s) the user requested without asking them to invoke another workflow command. If they asked only to start a change, stop after scaffolding and show its status. When the requested capture is done, stop there and name where the work continues: ${CAPTURE_PLANNING_HANDOFF}, and ${CAPTURE_APPLY_HANDOFF}. Capturing artifacts never starts implementing them.
 
 ### When a change exists
 
@@ -510,7 +544,7 @@ If the user mentions a change or you detect one is relevant:
 
 There's no required ending. Discovery might:
 
-- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Flow into a proposal**: "${DISCOVERY_END_HANDOFF}"
 - **Result in artifact updates**: "Updated design.md with these decisions"
 - **Just provide clarity**: User has what they need, moves on
 - **Continue later**: "We can pick this up anytime"
@@ -521,11 +555,11 @@ When things crystallize, you might offer a summary - but it's optional. Sometime
 
 ## Guardrails
 
-- **Don't implement** - Never write code or implement features. Workflow configuration counts too: creating or editing schemas, templates, or \`openspec/config.yaml\` is a change, not thinking. Creating or updating OpenSpec change artifacts within the confirmed scope is fine, writing anything else is not.
+- **Don't implement** - Never write code or implement features. Workflow configuration counts too: creating or editing schemas, templates, or \`openspec/config.yaml\` is a change, not thinking. Creating or updating OpenSpec change artifacts within the confirmed scope is fine, writing anything else is not. When the user is ready to build, name the handoff rather than starting: ${GUARDRAIL_HANDOFF}.
 - **Don't fake understanding** - If something is unclear, dig deeper
 - **Don't rush** - Discovery is thinking time, not task time
 - **Don't force structure** - Let patterns emerge naturally
-- **Don't auto-capture** - Offer to save insights, don't just do it. Read-only commands and tools need no confirmation. Before the first write-capable action—including \`openspec new change\` or another command that writes files—name the artifacts or files and proposed changes, ask a direct yes/no question, and wait for explicit confirmation in a separate user message. That confirmation covers only the described scope; ask again before expanding it. Answers to design or clarifying questions are never consent to write.
+- **Don't auto-capture** - Offer to save insights, don't just do it. Read-only commands and tools need no confirmation. Before the first write-capable action—including \`openspec new change\` or another command that writes files—name the artifacts or files and proposed changes, ask a direct yes/no question, and wait for explicit confirmation in a separate user message. That confirmation covers only the described scope; ask again before expanding it. Answers to design or clarifying questions are never consent to write. That rule governs \`openspec new change\` whenever you are the one proposing the capture; the user's own capture request is the exception, handled in the capture transition above.
 - **Don't manually scaffold changes** - Never create a new change directory under \`openspec/changes/\` by hand. Always use \`openspec new change "<name>"\` (with \`--store <id>\` when applicable) so required metadata such as \`.openspec.yaml\` is created before writing artifacts.
 - **Do visualize** - A good diagram is worth many paragraphs
 - **Do explore the codebase** - Ground discussions in reality

package/dist/core/templates/workflows/ff-change.js

@@ -1,12 +1,26 @@
+import { optionalWorkflow } from '../optional-workflow.js';
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROJECT_ROOT_GUARD } from './project-root.js';
+/**
+ * The implementation handoff, resolved at generation time so a profile
+ * without `apply` is not told to run it (see optional-workflow.ts).
+ *
+ * The two surfaces word this differently on purpose (#258): a command-only
+ * tool has no conversational agent to ask, so its prompt names a command or
+ * the CLI and never invites "ask me to implement".
+ */
+const SKILL_APPLY_HANDOFF = optionalWorkflow('apply', 'Run `/opsx:apply` or ask me to implement to start working on the tasks.', 'Ask me to implement to start working on the tasks.');
+const COMMAND_APPLY_HANDOFF = optionalWorkflow('apply', 'Run `/opsx:apply` to start implementing.', 'Run `openspec instructions apply --change "<name>" --json` to get the task list and start implementing.');
 export function getFfChangeSkillTemplate() {
     return {
         name: 'openspec-ff-change',
-        description: 'Fast-forward through OpenSpec artifact creation. Use when the user wants to quickly create all artifacts needed for implementation without stepping through each one individually.',
+        description: 'Fast-forward through OpenSpec artifact creation. Use when the user wants to quickly create all artifacts needed for implementation without stepping through each one individually. Also use when the user says "openspec ff" or "opsx ff".',
         instructions: `Fast-forward through artifact creation - generate everything needed to start implementation in one go.
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 **Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
 
 **Steps**
@@ -89,7 +103,7 @@ After completing all artifacts, summarize:
 - Change name and location
 - List of artifacts created with brief descriptions, plus any conditional artifact you skipped and why
 - What's ready: "All artifacts needed for implementation are ready."
-- Prompt: "Run \`/opsx:apply\` or ask me to implement to start working on the tasks."
+- Prompt: "${SKILL_APPLY_HANDOFF}"
 
 **Artifact Creation Guidelines**
 
@@ -123,6 +137,8 @@ export function getOpsxFfCommandTemplate() {
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 **Input**: The argument after \`/opsx:ff\` is the change name (kebab-case), OR a description of what the user wants to build.
 
 **Steps**
@@ -205,7 +221,7 @@ After completing all artifacts, summarize:
 - Change name and location
 - List of artifacts created with brief descriptions, plus any conditional artifact you skipped and why
 - What's ready: "All artifacts needed for implementation are ready."
-- Prompt: "Run \`/opsx:apply\` to start implementing."
+- Prompt: "${COMMAND_APPLY_HANDOFF}"
 
 **Artifact Creation Guidelines**
 

package/dist/core/templates/workflows/new-change.js

@@ -1,12 +1,22 @@
+import { optionalWorkflow } from '../optional-workflow.js';
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROJECT_ROOT_GUARD } from './project-root.js';
+/**
+ * Handoffs to `continue`, which is not guaranteed to be installed alongside
+ * `new`; resolved at generation time (see optional-workflow.ts).
+ */
+const FIRST_ARTIFACT_PROMPT = optionalWorkflow('continue', 'Run `/opsx:continue` or just describe what this change is about and I\'ll draft it.', 'Just describe what this change is about and I\'ll draft it.');
+const EXISTING_CHANGE_HINT = optionalWorkflow('continue', 'suggest using `/opsx:continue` instead', 'say so and ask whether to resume that change or pick a different name');
 export function getNewChangeSkillTemplate() {
     return {
         name: 'openspec-new-change',
-        description: 'Start a new OpenSpec change using the experimental artifact workflow. Use when the user wants to create a new feature, fix, or modification with a structured step-by-step approach.',
+        description: 'Start a new OpenSpec change using the experimental artifact workflow. Use when the user wants to create a new feature, fix, or modification with a structured step-by-step approach. Also use when the user says "openspec new change" or "opsx new".',
         instructions: `Start a new change using the experimental artifact-driven approach.
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 **Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
 
 **Steps**
@@ -83,6 +93,8 @@ export function getOpsxNewCommandTemplate() {
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 **Input**: The argument after \`/opsx:new\` is the change name (kebab-case), OR a description of what the user wants to build.
 
 **Steps**
@@ -135,13 +147,13 @@ After completing the steps, summarize:
 - Schema/workflow being used and its artifact sequence
 - Current status (0/N artifacts complete)
 - The template for the first artifact
-- Prompt: "Ready to create the first artifact? Run \`/opsx:continue\` or just describe what this change is about and I'll draft it."
+- Prompt: "Ready to create the first artifact? ${FIRST_ARTIFACT_PROMPT}"
 
 **Guardrails**
 - Do NOT create any artifacts yet - just show the instructions
 - Do NOT advance beyond showing the first artifact template
 - If the name is invalid (not kebab-case), ask for a valid name
-- If a change with that name already exists, suggest using \`/opsx:continue\` instead
+- If a change with that name already exists, ${EXISTING_CHANGE_HINT}
 - Pass --schema if using a non-default workflow`
     };
 }

package/dist/core/templates/workflows/onboard.js

@@ -1,8 +1,53 @@
+import { onlyWithWorkflow, optionalWorkflow } from '../optional-workflow.js';
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROJECT_ROOT_GUARD } from './project-root.js';
+/**
+ * The tutorial names other workflows throughout. Which of them exist depends
+ * on the profile, so each mention is resolved at generation time (see
+ * optional-workflow.ts) instead of being listed with an "if installed" caveat
+ * the reader has to check for themselves.
+ */
+const EXPLORE_MODE_NOTE = optionalWorkflow('explore', 'Explore mode (`/opsx:explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.', 'Investigating before implementing is worth doing whenever a problem needs thinking through.');
+/**
+ * The command-reference tables. Every row is dropped along with its line when
+ * the profile does not install that workflow, so the table lists exactly the
+ * commands the reader can run — and stays a valid table either way.
+ */
+const COMMAND_REFERENCE_ROWS = [
+    onlyWithWorkflow('propose', ' | `/opsx:propose` | Create a change and generate all artifacts |'),
+    onlyWithWorkflow('explore', ' | `/opsx:explore` | Think through problems before/during work  |'),
+    onlyWithWorkflow('apply', ' | `/opsx:apply`   | Implement tasks from a change              |'),
+    onlyWithWorkflow('archive', ' | `/opsx:archive` | Archive a completed change                 |'),
+    onlyWithWorkflow('new', ' | `/opsx:new`     | Start a new change, one artifact at a time |'),
+    onlyWithWorkflow('continue', ' | `/opsx:continue` | Continue working on an existing change    |'),
+    onlyWithWorkflow('ff', ' | `/opsx:ff`      | Fast-forward: create all artifacts at once |'),
+    onlyWithWorkflow('verify', ' | `/opsx:verify`  | Verify implementation matches artifacts    |'),
+].join('\n');
+const QUICK_REFERENCE_ROWS = [
+    onlyWithWorkflow('propose', ' | `/opsx:propose <name>`  | Create a change and generate all artifacts |'),
+    onlyWithWorkflow('explore', ' | `/opsx:explore`         | Think through problems (no code changes)   |'),
+    onlyWithWorkflow('apply', ' | `/opsx:apply <name>`    | Implement tasks                            |'),
+    onlyWithWorkflow('archive', ' | `/opsx:archive <name>`  | Archive when done                          |'),
+    onlyWithWorkflow('new', ' | `/opsx:new <name>`      | Start a new change, step by step           |'),
+    onlyWithWorkflow('continue', ' | `/opsx:continue <name>` | Continue an existing change                |'),
+    onlyWithWorkflow('ff', ' | `/opsx:ff <name>`       | Fast-forward: all artifacts at once        |'),
+    onlyWithWorkflow('verify', ' | `/opsx:verify <name>`   | Verify implementation                      |'),
+].join('\n');
+/**
+ * Resume hints for a user stopping mid-tutorial. Both are optional, so the
+ * sentence that introduces them stands on its own without either.
+ */
+const RESUME_HINTS = [
+    onlyWithWorkflow('continue', '- `/opsx:continue <name>` - Resume artifact creation'),
+    onlyWithWorkflow('apply', '- `/opsx:apply <name>` - Jump to implementation (if tasks exist)'),
+].join('\n');
+/** Where the tutorial points once it is over. */
+const NEXT_STEP_INVITE = optionalWorkflow('propose', 'Try `/opsx:propose` on something you actually want to build. You\'ve got the rhythm now!', 'Try this on something you actually want to build. You\'ve got the rhythm now!');
+const QUICK_REFERENCE_INVITE = optionalWorkflow('propose', 'Try `/opsx:propose` to start your first change.', 'Ask me to start your first change whenever you are ready.');
 export function getOnboardSkillTemplate() {
     return {
         name: 'openspec-onboard',
-        description: 'Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.',
+        description: 'Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work. Also use when the user says "openspec onboard" or "opsx onboard".',
         instructions: getOnboardInstructions(),
         license: 'MIT',
         compatibility: 'Requires openspec CLI.',
@@ -14,6 +59,8 @@ function getOnboardInstructions() {
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 ---
 
 ## Preflight
@@ -155,7 +202,7 @@ Spend 1-2 minutes investigating the relevant code:
 │   [Optional: ASCII diagram if helpful]  │
 └─────────────────────────────────────────┘
 
-Explore mode (\`/opsx:explore\`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.
+${EXPLORE_MODE_NOTE}
 
 Now let's create a change to hold our work.
 \`\`\`
@@ -221,6 +268,8 @@ Here's a draft proposal:
 
 ---
 
+# Proposal
+
 ## Why
 
 [1-2 sentences explaining the problem/opportunity]
@@ -288,6 +337,8 @@ Here's the spec:
 
 ---
 
+# Spec Delta
+
 ## ADDED Requirements
 
 ### Requirement: <Name>
@@ -327,6 +378,8 @@ Here's the design:
 
 ---
 
+# Design
+
 ## Context
 
 [Brief context about the current state]
@@ -372,6 +425,8 @@ Here are the implementation tasks:
 
 ---
 
+# Tasks
+
 ## 1. [Category or file]
 
 - [ ] 1.1 [Specific task] — verify: [test, command, observable behavior, or delivered artifact]
@@ -473,29 +528,17 @@ This same rhythm works for any size change—a small fix or a major feature.
 
 ## Command Reference
 
-**Core workflow:**
+**The commands you have installed:**
 
- | Command           | What it does                               |
- |-------------------|--------------------------------------------|
- | \`/opsx:propose\` | Create a change and generate all artifacts |
- | \`/opsx:explore\` | Think through problems before/during work  |
- | \`/opsx:apply\`   | Implement tasks from a change              |
- | \`/opsx:archive\` | Archive a completed change                 |
-
-**Additional commands** (only if installed - availability depends on your profile):
-
- | Command            | What it does                                             |
- |--------------------|----------------------------------------------------------|
- | \`/opsx:new\`      | Start a new change, step through artifacts one at a time |
- | \`/opsx:continue\` | Continue working on an existing change                   |
- | \`/opsx:ff\`       | Fast-forward: create all artifacts at once               |
- | \`/opsx:verify\`   | Verify implementation matches artifacts                  |
+ | Command          | What it does                               |
+ |------------------|--------------------------------------------|
+${COMMAND_REFERENCE_ROWS}
 
 ---
 
 ## What's Next?
 
-Try \`/opsx:propose\` on something you actually want to build. You've got the rhythm now!
+${NEXT_STEP_INVITE}
 \`\`\`
 
 ---
@@ -509,9 +552,8 @@ If the user says they need to stop, want to pause, or seem disengaged:
 \`\`\`
 No problem! Your change is saved at the \`changeRoot\` reported by \`openspec status --change "<name>" --json\`.
 
-To pick up where we left off later:
-- \`/opsx:continue <name>\` - Resume artifact creation (if installed; otherwise \`openspec status --change "<name>" --json\` shows the next artifact)
-- \`/opsx:apply <name>\` - Jump to implementation (if tasks exist)
+To pick up where we left off later, \`openspec status --change "<name>" --json\` shows exactly where the change stands.
+${RESUME_HINTS}
 
 The work won't be lost. Come back whenever you're ready.
 \`\`\`
@@ -525,25 +567,13 @@ If the user says they just want to see the commands or skip the tutorial:
 \`\`\`
 ## OpenSpec Quick Reference
 
-**Core workflow:**
+**The commands you have installed:**
 
  | Command                  | What it does                               |
  |--------------------------|--------------------------------------------|
- | \`/opsx:propose <name>\` | Create a change and generate all artifacts |
- | \`/opsx:explore\`        | Think through problems (no code changes)   |
- | \`/opsx:apply <name>\`   | Implement tasks                            |
- | \`/opsx:archive <name>\` | Archive when done                          |
-
-**Additional commands** (only if installed - availability depends on your profile):
-
- | Command                   | What it does                        |
- |---------------------------|-------------------------------------|
- | \`/opsx:new <name>\`      | Start a new change, step by step    |
- | \`/opsx:continue <name>\` | Continue an existing change         |
- | \`/opsx:ff <name>\`       | Fast-forward: all artifacts at once |
- | \`/opsx:verify <name>\`   | Verify implementation               |
+${QUICK_REFERENCE_ROWS}
 
-Try \`/opsx:propose\` to start your first change.
+${QUICK_REFERENCE_INVITE}
 \`\`\`
 
 Exit gracefully.

package/dist/core/templates/workflows/project-root.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared project-root guidance for skill template workflows.
+ *
+ * Generated skills and commands are installed once per machine, so they are
+ * offered in every repository the agent opens - including repositories that
+ * never ran `openspec init`. Nothing stops the workflow there: `openspec new
+ * change` falls back to an implicit root and creates `openspec/` in whatever
+ * directory the agent happens to be in.
+ *
+ * This guidance is interpolated into every workflow so the agent checks for a
+ * root before writing. `openspec list --json` is the check because it refuses
+ * to fabricate an implicit root: it reports `root: null` both when nothing is
+ * set up and when only stores are registered.
+ *
+ * What follows the check depends on how the workflow was reached, because the
+ * two cases want opposite things (#1645). A skill the model picked on its own
+ * in an unrelated repository must get out of the way: the user asked for help,
+ * not for OpenSpec, and answering with a setup menu is the reported bug. A
+ * user who named OpenSpec, named the skill, or ran its slash command is owed
+ * an answer about OpenSpec, so that case stops and asks.
+ *
+ * One text serves both surfaces. `apply-change` and `onboard` render a single
+ * body into the skill and the command alike, so a command-only variant would
+ * mean threading a surface flag through bodies that deliberately have none.
+ * The bullets scope themselves instead: a slash command is an explicit
+ * invocation, so its branch is the only one that can apply there.
+ */
+export declare const PROJECT_ROOT_GUARD = "**Project check:** These steps expect a project that already uses OpenSpec. Before the first step that writes anything (`new change`, `archive`, `sync specs`, or authoring an artifact file), confirm the project has a root: run `openspec list --json` (with `--store <id>` when a store is selected, since the store is then the root) and read `root`. A root object means the project is set up. `\"root\": null` means it is not - there is no `openspec/` directory here, and a write such as `openspec new change` would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.\n\nOne `\"root\": null` is not about setup: when a `status` error message starts with `Declared in` or `Invalid store declaration in` and names this project's `openspec/config.yaml` (or `config.yml`), the project does use OpenSpec through a store it declares, which this machine cannot resolve (the store is not registered, or the `store:` line is malformed). Do not treat it as uninitialized and skip the branches below: stop before writing and show the user that error's `message` and `fix`.\n\nOtherwise, with no root, what happens next depends on how this workflow was reached:\n\n- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or running its slash command. Stop using OpenSpec and answer the request normally, as you would with no OpenSpec installed. Do not ask them to set anything up and do not mention OpenSpec setup.\n- **Explicit OpenSpec request**: the user named OpenSpec, named this skill, or ran its slash command. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store <id>`), or continue without OpenSpec for this request. Wait for their answer.\n\nIn both branches, never create the root as a side effect: do not run `openspec init` until the user asks for it, do not hand-create `openspec/` files, and do not let a command create it.";
+//# sourceMappingURL=project-root.d.ts.map

package/dist/core/templates/workflows/project-root.js

@@ -0,0 +1,38 @@
+/**
+ * Shared project-root guidance for skill template workflows.
+ *
+ * Generated skills and commands are installed once per machine, so they are
+ * offered in every repository the agent opens - including repositories that
+ * never ran `openspec init`. Nothing stops the workflow there: `openspec new
+ * change` falls back to an implicit root and creates `openspec/` in whatever
+ * directory the agent happens to be in.
+ *
+ * This guidance is interpolated into every workflow so the agent checks for a
+ * root before writing. `openspec list --json` is the check because it refuses
+ * to fabricate an implicit root: it reports `root: null` both when nothing is
+ * set up and when only stores are registered.
+ *
+ * What follows the check depends on how the workflow was reached, because the
+ * two cases want opposite things (#1645). A skill the model picked on its own
+ * in an unrelated repository must get out of the way: the user asked for help,
+ * not for OpenSpec, and answering with a setup menu is the reported bug. A
+ * user who named OpenSpec, named the skill, or ran its slash command is owed
+ * an answer about OpenSpec, so that case stops and asks.
+ *
+ * One text serves both surfaces. `apply-change` and `onboard` render a single
+ * body into the skill and the command alike, so a command-only variant would
+ * mean threading a surface flag through bodies that deliberately have none.
+ * The bullets scope themselves instead: a slash command is an explicit
+ * invocation, so its branch is the only one that can apply there.
+ */
+export const PROJECT_ROOT_GUARD = `**Project check:** These steps expect a project that already uses OpenSpec. Before the first step that writes anything (\`new change\`, \`archive\`, \`sync specs\`, or authoring an artifact file), confirm the project has a root: run \`openspec list --json\` (with \`--store <id>\` when a store is selected, since the store is then the root) and read \`root\`. A root object means the project is set up. \`"root": null\` means it is not - there is no \`openspec/\` directory here, and a write such as \`openspec new change\` would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.
+
+One \`"root": null\` is not about setup: when a \`status\` error message starts with \`Declared in\` or \`Invalid store declaration in\` and names this project's \`openspec/config.yaml\` (or \`config.yml\`), the project does use OpenSpec through a store it declares, which this machine cannot resolve (the store is not registered, or the \`store:\` line is malformed). Do not treat it as uninitialized and skip the branches below: stop before writing and show the user that error's \`message\` and \`fix\`.
+
+Otherwise, with no root, what happens next depends on how this workflow was reached:
+
+- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or running its slash command. Stop using OpenSpec and answer the request normally, as you would with no OpenSpec installed. Do not ask them to set anything up and do not mention OpenSpec setup.
+- **Explicit OpenSpec request**: the user named OpenSpec, named this skill, or ran its slash command. Stop before writing and ask how to proceed: set this project up (\`openspec init\`), target a store they already have (\`--store <id>\`), or continue without OpenSpec for this request. Wait for their answer.
+
+In both branches, never create the root as a side effect: do not run \`openspec init\` until the user asks for it, do not hand-create \`openspec/\` files, and do not let a command create it.`;
+//# sourceMappingURL=project-root.js.map