diff --git a/.claude/commands/opsx/apply.md b/.claude/commands/opsx/apply.md index 645bbdb8..bf23721d 100644 --- a/.claude/commands/opsx/apply.md +++ b/.claude/commands/opsx/apply.md @@ -111,7 +111,7 @@ Working on task 4/7: - [x] Task 2 ... -All tasks complete! Ready to archive this change. +All tasks complete! You can archive this change with `/opsx:archive`. ``` **Output On Pause (Issue Encountered)** diff --git a/.claude/commands/opsx/archive.md b/.claude/commands/opsx/archive.md index 7275c854..5e916083 100644 --- a/.claude/commands/opsx/archive.md +++ b/.claude/commands/opsx/archive.md @@ -59,7 +59,7 @@ Archive a completed change in the experimental workflow. - If changes needed: "Sync now (recommended)", "Archive without syncing" - If already synced: "Archive now", "Sync anyway", "Cancel" - If user chooses sync, execute `/opsx:sync` logic. Proceed to archive regardless of choice. + If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change ''. Delta spec analysis: "). Proceed to archive regardless of choice. 5. **Perform the archive** @@ -153,5 +153,5 @@ Target archive directory already exists. - Don't block archive on warnings - just inform and confirm - Preserve .openspec.yaml when moving to archive (it moves with the directory) - Show clear summary of what happened -- If sync is requested, use /opsx:sync approach (agent-driven) +- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven) - If delta specs exist, always run the sync assessment and show the combined summary before prompting diff --git a/.claude/commands/opsx/bulk-archive.md b/.claude/commands/opsx/bulk-archive.md index b700261c..a1514105 100644 --- a/.claude/commands/opsx/bulk-archive.md +++ b/.claude/commands/opsx/bulk-archive.md @@ -225,7 +225,7 @@ Failed K changes: ``` ## No Changes to Archive -No active changes found. Use `/opsx:new` to create a new change. +No active changes found. Create a new change to get started. ``` **Guardrails** diff --git a/.claude/commands/opsx/continue.md b/.claude/commands/opsx/continue.md index 49daaa7a..af255c6f 100644 --- a/.claude/commands/opsx/continue.md +++ b/.claude/commands/opsx/continue.md @@ -41,7 +41,7 @@ Continue working on a change by creating the next artifact. **If all artifacts are complete (`isComplete: true`)**: - Congratulate the user - Show final status including the schema used - - Suggest: "All artifacts created! You can now implement this change or archive it." + - Suggest: "All artifacts created! You can now implement this change with `/opsx:apply` or archive it with `/opsx:archive`." - STOP --- diff --git a/.claude/commands/opsx/explore.md b/.claude/commands/opsx/explore.md index 202566bd..30d9c57a 100644 --- a/.claude/commands/opsx/explore.md +++ b/.claude/commands/opsx/explore.md @@ -7,7 +7,7 @@ tags: [workflow, explore, experimental, thinking] 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, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. +**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, 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 OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. **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. @@ -100,8 +100,7 @@ If the user mentioned a specific change name, read its artifacts for context. Think freely. When insights crystallize, you might offer: -- "This feels solid enough to start a change. Want me to create one?" - → Can transition to `/opsx:new` or `/opsx:ff` +- "This feels solid enough to start a change. Want me to create a proposal?" - Or keep exploring - no pressure to formalize ### When a change exists @@ -153,7 +152,7 @@ If the user mentions a change or you detect one is relevant: There's no required ending. Discovery might: -- **Flow into action**: "Ready to start? `/opsx:new` or `/opsx:ff`" +- **Flow into a proposal**: "Ready to start? I can create a change proposal." - **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" diff --git a/.claude/commands/opsx/ff.md b/.claude/commands/opsx/ff.md index bea9d610..69f749c9 100644 --- a/.claude/commands/opsx/ff.md +++ b/.claude/commands/opsx/ff.md @@ -84,7 +84,10 @@ After completing all artifacts, summarize: - Follow the `instruction` field from `openspec instructions` for each artifact type - The schema defines what each artifact should contain - follow it - Read dependency artifacts for context before creating new ones -- Use the `template` as a starting point, filling in based on context +- Use `template` as the structure for your output file - fill in its sections +- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file + - Do NOT copy ``, ``, `` blocks into the artifact + - These guide what you write, but should never appear in the output **Guardrails** - Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`) diff --git a/.claude/commands/opsx/onboard.md b/.claude/commands/opsx/onboard.md index e15790e5..7df677c4 100644 --- a/.claude/commands/opsx/onboard.md +++ b/.claude/commands/opsx/onboard.md @@ -11,16 +11,19 @@ Guide the user through their first complete OpenSpec workflow cycle. This is a t ## Preflight -Before starting, check if OpenSpec is initialized: +Before starting, check if the OpenSpec CLI is installed: ```bash -openspec status --json 2>&1 || echo "NOT_INITIALIZED" +# Unix/macOS +openspec --version 2>&1 || echo "CLI_NOT_INSTALLED" +# Windows (PowerShell) +# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" } ``` -**If not initialized:** -> OpenSpec isn't set up in this project yet. Run `openspec init` first, then come back to `/opsx:onboard`. +**If CLI not installed:** +> OpenSpec CLI is not installed. Install it first, then come back to `/opsx:onboard`. -Stop here if not initialized. +Stop here if not installed. --- @@ -63,7 +66,10 @@ Scan the codebase for small improvement opportunities. Look for: Also check recent git activity: ```bash +# Unix/macOS git log --oneline -10 2>/dev/null || echo "No git history" +# Windows (PowerShell) +# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" } ``` ### Present Suggestions @@ -258,7 +264,10 @@ For a small task like this, we might only need one spec file. **DO:** Create the spec file: ```bash +# Unix/macOS mkdir -p openspec/changes//specs/ +# Windows (PowerShell) +# New-Item -ItemType Directory -Force -Path "openspec/changes//specs/" ``` Draft the spec content: @@ -453,21 +462,29 @@ This same rhythm works for any size change—a small fix or a major feature. ## Command Reference +**Core workflow:** + | Command | What it does | |---------|--------------| +| `/opsx:propose` | Create a change and generate all artifacts | | `/opsx:explore` | Think through problems before/during work | -| `/opsx:new` | Start a new change, step through artifacts | -| `/opsx:ff` | Fast-forward: create all artifacts at once | -| `/opsx:continue` | Continue working on an existing change | | `/opsx:apply` | Implement tasks from a change | -| `/opsx:verify` | Verify implementation matches artifacts | | `/opsx:archive` | Archive a completed change | +**Additional commands:** + +| 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 | + --- ## What's Next? -Try `/opsx:new` or `/opsx:ff` on something you actually want to build. You've got the rhythm now! +Try `/opsx:propose` on something you actually want to build. You've got the rhythm now! ``` --- @@ -497,17 +514,25 @@ If the user says they just want to see the commands or skip the tutorial: ``` ## OpenSpec Quick Reference +**Core workflow:** + | Command | What it does | |---------|--------------| +| `/opsx:propose ` | Create a change and generate all artifacts | | `/opsx:explore` | Think through problems (no code changes) | +| `/opsx:apply ` | Implement tasks | +| `/opsx:archive ` | Archive when done | + +**Additional commands:** + +| Command | What it does | +|---------|--------------| | `/opsx:new ` | Start a new change, step by step | -| `/opsx:ff ` | Fast-forward: all artifacts at once | | `/opsx:continue ` | Continue an existing change | -| `/opsx:apply ` | Implement tasks | +| `/opsx:ff ` | Fast-forward: all artifacts at once | | `/opsx:verify ` | Verify implementation | -| `/opsx:archive ` | Archive when done | -Try `/opsx:new` to start your first change, or `/opsx:ff` if you want to move fast. +Try `/opsx:propose` to start your first change. ``` Exit gracefully. diff --git a/.claude/skills/openspec-apply-change/SKILL.md b/.claude/skills/openspec-apply-change/SKILL.md index bc95df43..d474dc13 100644 --- a/.claude/skills/openspec-apply-change/SKILL.md +++ b/.claude/skills/openspec-apply-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Implement tasks from an OpenSpec change. diff --git a/.claude/skills/openspec-archive-change/SKILL.md b/.claude/skills/openspec-archive-change/SKILL.md index 9ea63e8a..9b1f851a 100644 --- a/.claude/skills/openspec-archive-change/SKILL.md +++ b/.claude/skills/openspec-archive-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Archive a completed change in the experimental workflow. @@ -63,7 +63,7 @@ Archive a completed change in the experimental workflow. - If changes needed: "Sync now (recommended)", "Archive without syncing" - If already synced: "Archive now", "Sync anyway", "Cancel" - If user chooses sync, execute /opsx:sync logic (use the openspec-sync-specs skill). Proceed to archive regardless of choice. + If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change ''. Delta spec analysis: "). Proceed to archive regardless of choice. 5. **Perform the archive** diff --git a/.claude/skills/openspec-bulk-archive-change/SKILL.md b/.claude/skills/openspec-bulk-archive-change/SKILL.md index 5ce056a9..d2f199af 100644 --- a/.claude/skills/openspec-bulk-archive-change/SKILL.md +++ b/.claude/skills/openspec-bulk-archive-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Archive multiple completed changes in a single operation. @@ -229,7 +229,7 @@ Failed K changes: ``` ## No Changes to Archive -No active changes found. Use `/opsx:new` to create a new change. +No active changes found. Create a new change to get started. ``` **Guardrails** diff --git a/.claude/skills/openspec-continue-change/SKILL.md b/.claude/skills/openspec-continue-change/SKILL.md index 79aaac48..a2856f04 100644 --- a/.claude/skills/openspec-continue-change/SKILL.md +++ b/.claude/skills/openspec-continue-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Continue working on a change by creating the next artifact. diff --git a/.claude/skills/openspec-explore/SKILL.md b/.claude/skills/openspec-explore/SKILL.md index 49d051da..ffa10cad 100644 --- a/.claude/skills/openspec-explore/SKILL.md +++ b/.claude/skills/openspec-explore/SKILL.md @@ -6,12 +6,12 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- 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, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. +**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, 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 OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. **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. @@ -95,8 +95,7 @@ This tells you: Think freely. When insights crystallize, you might offer: -- "This feels solid enough to start a change. Want me to create one?" - → Can transition to `/opsx:new` or `/opsx:ff` +- "This feels solid enough to start a change. Want me to create a proposal?" - Or keep exploring - no pressure to formalize ### When a change exists @@ -252,7 +251,7 @@ You: That changes everything. There's no required ending. Discovery might: -- **Flow into action**: "Ready to start? /opsx:new or /opsx:ff" +- **Flow into a proposal**: "Ready to start? I can create a change proposal." - **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" @@ -269,8 +268,7 @@ When it feels like things are crystallizing, you might summarize: **Open questions**: [if any remain] **Next steps** (if ready): -- Create a change: /opsx:new -- Fast-forward to tasks: /opsx:ff +- Create a change proposal - Keep exploring: just keep talking ``` diff --git a/.claude/skills/openspec-ff-change/SKILL.md b/.claude/skills/openspec-ff-change/SKILL.md index 64f058ca..d5f12043 100644 --- a/.claude/skills/openspec-ff-change/SKILL.md +++ b/.claude/skills/openspec-ff-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Fast-forward through artifact creation - generate everything needed to start implementation in one go. diff --git a/.claude/skills/openspec-new-change/SKILL.md b/.claude/skills/openspec-new-change/SKILL.md index 53d96b99..607391aa 100644 --- a/.claude/skills/openspec-new-change/SKILL.md +++ b/.claude/skills/openspec-new-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Start a new change using the experimental artifact-driven approach. diff --git a/.claude/skills/openspec-onboard/SKILL.md b/.claude/skills/openspec-onboard/SKILL.md index 40080aa1..9076b5d8 100644 --- a/.claude/skills/openspec-onboard/SKILL.md +++ b/.claude/skills/openspec-onboard/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step. @@ -15,16 +15,19 @@ Guide the user through their first complete OpenSpec workflow cycle. This is a t ## Preflight -Before starting, check if OpenSpec is initialized: +Before starting, check if the OpenSpec CLI is installed: ```bash -openspec status --json 2>&1 || echo "NOT_INITIALIZED" +# Unix/macOS +openspec --version 2>&1 || echo "CLI_NOT_INSTALLED" +# Windows (PowerShell) +# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" } ``` -**If not initialized:** -> OpenSpec isn't set up in this project yet. Run `openspec init` first, then come back to `/opsx:onboard`. +**If CLI not installed:** +> OpenSpec CLI is not installed. Install it first, then come back to `/opsx:onboard`. -Stop here if not initialized. +Stop here if not installed. --- @@ -67,7 +70,10 @@ Scan the codebase for small improvement opportunities. Look for: Also check recent git activity: ```bash +# Unix/macOS git log --oneline -10 2>/dev/null || echo "No git history" +# Windows (PowerShell) +# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" } ``` ### Present Suggestions @@ -262,7 +268,10 @@ For a small task like this, we might only need one spec file. **DO:** Create the spec file: ```bash +# Unix/macOS mkdir -p openspec/changes//specs/ +# Windows (PowerShell) +# New-Item -ItemType Directory -Force -Path "openspec/changes//specs/" ``` Draft the spec content: @@ -457,21 +466,29 @@ This same rhythm works for any size change—a small fix or a major feature. ## Command Reference +**Core workflow:** + | Command | What it does | |---------|--------------| +| `/opsx:propose` | Create a change and generate all artifacts | | `/opsx:explore` | Think through problems before/during work | -| `/opsx:new` | Start a new change, step through artifacts | -| `/opsx:ff` | Fast-forward: create all artifacts at once | -| `/opsx:continue` | Continue working on an existing change | | `/opsx:apply` | Implement tasks from a change | -| `/opsx:verify` | Verify implementation matches artifacts | | `/opsx:archive` | Archive a completed change | +**Additional commands:** + +| 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 | + --- ## What's Next? -Try `/opsx:new` or `/opsx:ff` on something you actually want to build. You've got the rhythm now! +Try `/opsx:propose` on something you actually want to build. You've got the rhythm now! ``` --- @@ -501,17 +518,25 @@ If the user says they just want to see the commands or skip the tutorial: ``` ## OpenSpec Quick Reference +**Core workflow:** + | Command | What it does | |---------|--------------| +| `/opsx:propose ` | Create a change and generate all artifacts | | `/opsx:explore` | Think through problems (no code changes) | +| `/opsx:apply ` | Implement tasks | +| `/opsx:archive ` | Archive when done | + +**Additional commands:** + +| Command | What it does | +|---------|--------------| | `/opsx:new ` | Start a new change, step by step | -| `/opsx:ff ` | Fast-forward: all artifacts at once | | `/opsx:continue ` | Continue an existing change | -| `/opsx:apply ` | Implement tasks | +| `/opsx:ff ` | Fast-forward: all artifacts at once | | `/opsx:verify ` | Verify implementation | -| `/opsx:archive ` | Archive when done | -Try `/opsx:new` to start your first change, or `/opsx:ff` if you want to move fast. +Try `/opsx:propose` to start your first change. ``` Exit gracefully. diff --git a/.claude/skills/openspec-sync-specs/SKILL.md b/.claude/skills/openspec-sync-specs/SKILL.md index 632681c7..353bfac9 100644 --- a/.claude/skills/openspec-sync-specs/SKILL.md +++ b/.claude/skills/openspec-sync-specs/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Sync delta specs from a change to main specs. diff --git a/.claude/skills/openspec-verify-change/SKILL.md b/.claude/skills/openspec-verify-change/SKILL.md index 21cbc508..744a0883 100644 --- a/.claude/skills/openspec-verify-change/SKILL.md +++ b/.claude/skills/openspec-verify-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Verify that an implementation matches the change artifacts (specs, tasks, design). diff --git a/.github/prompts/opsx-apply.prompt.md b/.github/prompts/opsx-apply.prompt.md index 89fb9ed4..494e10e9 100644 --- a/.github/prompts/opsx-apply.prompt.md +++ b/.github/prompts/opsx-apply.prompt.md @@ -108,7 +108,7 @@ Working on task 4/7: - [x] Task 2 ... -All tasks complete! Ready to archive this change. +All tasks complete! You can archive this change with `/opsx:archive`. ``` **Output On Pause (Issue Encountered)** diff --git a/.github/prompts/opsx-archive.prompt.md b/.github/prompts/opsx-archive.prompt.md index 4e2ee189..1163776d 100644 --- a/.github/prompts/opsx-archive.prompt.md +++ b/.github/prompts/opsx-archive.prompt.md @@ -56,7 +56,7 @@ Archive a completed change in the experimental workflow. - If changes needed: "Sync now (recommended)", "Archive without syncing" - If already synced: "Archive now", "Sync anyway", "Cancel" - If user chooses sync, execute `/opsx:sync` logic. Proceed to archive regardless of choice. + If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change ''. Delta spec analysis: "). Proceed to archive regardless of choice. 5. **Perform the archive** @@ -150,5 +150,5 @@ Target archive directory already exists. - Don't block archive on warnings - just inform and confirm - Preserve .openspec.yaml when moving to archive (it moves with the directory) - Show clear summary of what happened -- If sync is requested, use /opsx:sync approach (agent-driven) +- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven) - If delta specs exist, always run the sync assessment and show the combined summary before prompting diff --git a/.github/prompts/opsx-bulk-archive.prompt.md b/.github/prompts/opsx-bulk-archive.prompt.md index f8e773fe..be3f9019 100644 --- a/.github/prompts/opsx-bulk-archive.prompt.md +++ b/.github/prompts/opsx-bulk-archive.prompt.md @@ -222,7 +222,7 @@ Failed K changes: ``` ## No Changes to Archive -No active changes found. Use `/opsx:new` to create a new change. +No active changes found. Create a new change to get started. ``` **Guardrails** diff --git a/.github/prompts/opsx-continue.prompt.md b/.github/prompts/opsx-continue.prompt.md index f91ec4bc..24b480d7 100644 --- a/.github/prompts/opsx-continue.prompt.md +++ b/.github/prompts/opsx-continue.prompt.md @@ -38,7 +38,7 @@ Continue working on a change by creating the next artifact. **If all artifacts are complete (`isComplete: true`)**: - Congratulate the user - Show final status including the schema used - - Suggest: "All artifacts created! You can now implement this change or archive it." + - Suggest: "All artifacts created! You can now implement this change with `/opsx:apply` or archive it with `/opsx:archive`." - STOP --- diff --git a/.github/prompts/opsx-explore.prompt.md b/.github/prompts/opsx-explore.prompt.md index fd588622..b21a2266 100644 --- a/.github/prompts/opsx-explore.prompt.md +++ b/.github/prompts/opsx-explore.prompt.md @@ -4,7 +4,7 @@ description: Enter explore mode - think through ideas, investigate problems, cla 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, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. +**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, 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 OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. **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. @@ -97,8 +97,7 @@ If the user mentioned a specific change name, read its artifacts for context. Think freely. When insights crystallize, you might offer: -- "This feels solid enough to start a change. Want me to create one?" - → Can transition to `/opsx:new` or `/opsx:ff` +- "This feels solid enough to start a change. Want me to create a proposal?" - Or keep exploring - no pressure to formalize ### When a change exists @@ -150,7 +149,7 @@ If the user mentions a change or you detect one is relevant: There's no required ending. Discovery might: -- **Flow into action**: "Ready to start? `/opsx:new` or `/opsx:ff`" +- **Flow into a proposal**: "Ready to start? I can create a change proposal." - **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" diff --git a/.github/prompts/opsx-ff.prompt.md b/.github/prompts/opsx-ff.prompt.md index 6b3dc00c..06cea280 100644 --- a/.github/prompts/opsx-ff.prompt.md +++ b/.github/prompts/opsx-ff.prompt.md @@ -81,7 +81,10 @@ After completing all artifacts, summarize: - Follow the `instruction` field from `openspec instructions` for each artifact type - The schema defines what each artifact should contain - follow it - Read dependency artifacts for context before creating new ones -- Use the `template` as a starting point, filling in based on context +- Use `template` as the structure for your output file - fill in its sections +- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file + - Do NOT copy ``, ``, `` blocks into the artifact + - These guide what you write, but should never appear in the output **Guardrails** - Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`) diff --git a/.github/prompts/opsx-onboard.prompt.md b/.github/prompts/opsx-onboard.prompt.md index 1414f1e1..8100b390 100644 --- a/.github/prompts/opsx-onboard.prompt.md +++ b/.github/prompts/opsx-onboard.prompt.md @@ -8,16 +8,19 @@ Guide the user through their first complete OpenSpec workflow cycle. This is a t ## Preflight -Before starting, check if OpenSpec is initialized: +Before starting, check if the OpenSpec CLI is installed: ```bash -openspec status --json 2>&1 || echo "NOT_INITIALIZED" +# Unix/macOS +openspec --version 2>&1 || echo "CLI_NOT_INSTALLED" +# Windows (PowerShell) +# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" } ``` -**If not initialized:** -> OpenSpec isn't set up in this project yet. Run `openspec init` first, then come back to `/opsx:onboard`. +**If CLI not installed:** +> OpenSpec CLI is not installed. Install it first, then come back to `/opsx:onboard`. -Stop here if not initialized. +Stop here if not installed. --- @@ -60,7 +63,10 @@ Scan the codebase for small improvement opportunities. Look for: Also check recent git activity: ```bash +# Unix/macOS git log --oneline -10 2>/dev/null || echo "No git history" +# Windows (PowerShell) +# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" } ``` ### Present Suggestions @@ -255,7 +261,10 @@ For a small task like this, we might only need one spec file. **DO:** Create the spec file: ```bash +# Unix/macOS mkdir -p openspec/changes//specs/ +# Windows (PowerShell) +# New-Item -ItemType Directory -Force -Path "openspec/changes//specs/" ``` Draft the spec content: @@ -450,21 +459,29 @@ This same rhythm works for any size change—a small fix or a major feature. ## Command Reference +**Core workflow:** + | Command | What it does | |---------|--------------| +| `/opsx:propose` | Create a change and generate all artifacts | | `/opsx:explore` | Think through problems before/during work | -| `/opsx:new` | Start a new change, step through artifacts | -| `/opsx:ff` | Fast-forward: create all artifacts at once | -| `/opsx:continue` | Continue working on an existing change | | `/opsx:apply` | Implement tasks from a change | -| `/opsx:verify` | Verify implementation matches artifacts | | `/opsx:archive` | Archive a completed change | +**Additional commands:** + +| 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 | + --- ## What's Next? -Try `/opsx:new` or `/opsx:ff` on something you actually want to build. You've got the rhythm now! +Try `/opsx:propose` on something you actually want to build. You've got the rhythm now! ``` --- @@ -494,17 +511,25 @@ If the user says they just want to see the commands or skip the tutorial: ``` ## OpenSpec Quick Reference +**Core workflow:** + | Command | What it does | |---------|--------------| +| `/opsx:propose ` | Create a change and generate all artifacts | | `/opsx:explore` | Think through problems (no code changes) | +| `/opsx:apply ` | Implement tasks | +| `/opsx:archive ` | Archive when done | + +**Additional commands:** + +| Command | What it does | +|---------|--------------| | `/opsx:new ` | Start a new change, step by step | -| `/opsx:ff ` | Fast-forward: all artifacts at once | | `/opsx:continue ` | Continue an existing change | -| `/opsx:apply ` | Implement tasks | +| `/opsx:ff ` | Fast-forward: all artifacts at once | | `/opsx:verify ` | Verify implementation | -| `/opsx:archive ` | Archive when done | -Try `/opsx:new` to start your first change, or `/opsx:ff` if you want to move fast. +Try `/opsx:propose` to start your first change. ``` Exit gracefully. diff --git a/.github/skills/openspec-apply-change/SKILL.md b/.github/skills/openspec-apply-change/SKILL.md index bc95df43..d474dc13 100644 --- a/.github/skills/openspec-apply-change/SKILL.md +++ b/.github/skills/openspec-apply-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Implement tasks from an OpenSpec change. diff --git a/.github/skills/openspec-archive-change/SKILL.md b/.github/skills/openspec-archive-change/SKILL.md index 9ea63e8a..9b1f851a 100644 --- a/.github/skills/openspec-archive-change/SKILL.md +++ b/.github/skills/openspec-archive-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Archive a completed change in the experimental workflow. @@ -63,7 +63,7 @@ Archive a completed change in the experimental workflow. - If changes needed: "Sync now (recommended)", "Archive without syncing" - If already synced: "Archive now", "Sync anyway", "Cancel" - If user chooses sync, execute /opsx:sync logic (use the openspec-sync-specs skill). Proceed to archive regardless of choice. + If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change ''. Delta spec analysis: "). Proceed to archive regardless of choice. 5. **Perform the archive** diff --git a/.github/skills/openspec-bulk-archive-change/SKILL.md b/.github/skills/openspec-bulk-archive-change/SKILL.md index 5ce056a9..d2f199af 100644 --- a/.github/skills/openspec-bulk-archive-change/SKILL.md +++ b/.github/skills/openspec-bulk-archive-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Archive multiple completed changes in a single operation. @@ -229,7 +229,7 @@ Failed K changes: ``` ## No Changes to Archive -No active changes found. Use `/opsx:new` to create a new change. +No active changes found. Create a new change to get started. ``` **Guardrails** diff --git a/.github/skills/openspec-continue-change/SKILL.md b/.github/skills/openspec-continue-change/SKILL.md index 79aaac48..a2856f04 100644 --- a/.github/skills/openspec-continue-change/SKILL.md +++ b/.github/skills/openspec-continue-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Continue working on a change by creating the next artifact. diff --git a/.github/skills/openspec-explore/SKILL.md b/.github/skills/openspec-explore/SKILL.md index 49d051da..ffa10cad 100644 --- a/.github/skills/openspec-explore/SKILL.md +++ b/.github/skills/openspec-explore/SKILL.md @@ -6,12 +6,12 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- 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, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. +**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, 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 OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. **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. @@ -95,8 +95,7 @@ This tells you: Think freely. When insights crystallize, you might offer: -- "This feels solid enough to start a change. Want me to create one?" - → Can transition to `/opsx:new` or `/opsx:ff` +- "This feels solid enough to start a change. Want me to create a proposal?" - Or keep exploring - no pressure to formalize ### When a change exists @@ -252,7 +251,7 @@ You: That changes everything. There's no required ending. Discovery might: -- **Flow into action**: "Ready to start? /opsx:new or /opsx:ff" +- **Flow into a proposal**: "Ready to start? I can create a change proposal." - **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" @@ -269,8 +268,7 @@ When it feels like things are crystallizing, you might summarize: **Open questions**: [if any remain] **Next steps** (if ready): -- Create a change: /opsx:new -- Fast-forward to tasks: /opsx:ff +- Create a change proposal - Keep exploring: just keep talking ``` diff --git a/.github/skills/openspec-ff-change/SKILL.md b/.github/skills/openspec-ff-change/SKILL.md index 64f058ca..d5f12043 100644 --- a/.github/skills/openspec-ff-change/SKILL.md +++ b/.github/skills/openspec-ff-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Fast-forward through artifact creation - generate everything needed to start implementation in one go. diff --git a/.github/skills/openspec-new-change/SKILL.md b/.github/skills/openspec-new-change/SKILL.md index 53d96b99..607391aa 100644 --- a/.github/skills/openspec-new-change/SKILL.md +++ b/.github/skills/openspec-new-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Start a new change using the experimental artifact-driven approach. diff --git a/.github/skills/openspec-onboard/SKILL.md b/.github/skills/openspec-onboard/SKILL.md index 40080aa1..9076b5d8 100644 --- a/.github/skills/openspec-onboard/SKILL.md +++ b/.github/skills/openspec-onboard/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step. @@ -15,16 +15,19 @@ Guide the user through their first complete OpenSpec workflow cycle. This is a t ## Preflight -Before starting, check if OpenSpec is initialized: +Before starting, check if the OpenSpec CLI is installed: ```bash -openspec status --json 2>&1 || echo "NOT_INITIALIZED" +# Unix/macOS +openspec --version 2>&1 || echo "CLI_NOT_INSTALLED" +# Windows (PowerShell) +# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" } ``` -**If not initialized:** -> OpenSpec isn't set up in this project yet. Run `openspec init` first, then come back to `/opsx:onboard`. +**If CLI not installed:** +> OpenSpec CLI is not installed. Install it first, then come back to `/opsx:onboard`. -Stop here if not initialized. +Stop here if not installed. --- @@ -67,7 +70,10 @@ Scan the codebase for small improvement opportunities. Look for: Also check recent git activity: ```bash +# Unix/macOS git log --oneline -10 2>/dev/null || echo "No git history" +# Windows (PowerShell) +# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" } ``` ### Present Suggestions @@ -262,7 +268,10 @@ For a small task like this, we might only need one spec file. **DO:** Create the spec file: ```bash +# Unix/macOS mkdir -p openspec/changes//specs/ +# Windows (PowerShell) +# New-Item -ItemType Directory -Force -Path "openspec/changes//specs/" ``` Draft the spec content: @@ -457,21 +466,29 @@ This same rhythm works for any size change—a small fix or a major feature. ## Command Reference +**Core workflow:** + | Command | What it does | |---------|--------------| +| `/opsx:propose` | Create a change and generate all artifacts | | `/opsx:explore` | Think through problems before/during work | -| `/opsx:new` | Start a new change, step through artifacts | -| `/opsx:ff` | Fast-forward: create all artifacts at once | -| `/opsx:continue` | Continue working on an existing change | | `/opsx:apply` | Implement tasks from a change | -| `/opsx:verify` | Verify implementation matches artifacts | | `/opsx:archive` | Archive a completed change | +**Additional commands:** + +| 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 | + --- ## What's Next? -Try `/opsx:new` or `/opsx:ff` on something you actually want to build. You've got the rhythm now! +Try `/opsx:propose` on something you actually want to build. You've got the rhythm now! ``` --- @@ -501,17 +518,25 @@ If the user says they just want to see the commands or skip the tutorial: ``` ## OpenSpec Quick Reference +**Core workflow:** + | Command | What it does | |---------|--------------| +| `/opsx:propose ` | Create a change and generate all artifacts | | `/opsx:explore` | Think through problems (no code changes) | +| `/opsx:apply ` | Implement tasks | +| `/opsx:archive ` | Archive when done | + +**Additional commands:** + +| Command | What it does | +|---------|--------------| | `/opsx:new ` | Start a new change, step by step | -| `/opsx:ff ` | Fast-forward: all artifacts at once | | `/opsx:continue ` | Continue an existing change | -| `/opsx:apply ` | Implement tasks | +| `/opsx:ff ` | Fast-forward: all artifacts at once | | `/opsx:verify ` | Verify implementation | -| `/opsx:archive ` | Archive when done | -Try `/opsx:new` to start your first change, or `/opsx:ff` if you want to move fast. +Try `/opsx:propose` to start your first change. ``` Exit gracefully. diff --git a/.github/skills/openspec-sync-specs/SKILL.md b/.github/skills/openspec-sync-specs/SKILL.md index 632681c7..353bfac9 100644 --- a/.github/skills/openspec-sync-specs/SKILL.md +++ b/.github/skills/openspec-sync-specs/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Sync delta specs from a change to main specs. diff --git a/.github/skills/openspec-verify-change/SKILL.md b/.github/skills/openspec-verify-change/SKILL.md index 21cbc508..744a0883 100644 --- a/.github/skills/openspec-verify-change/SKILL.md +++ b/.github/skills/openspec-verify-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.0.2" + generatedBy: "1.2.0" --- Verify that an implementation matches the change artifacts (specs, tasks, design). diff --git a/.gitignore b/.gitignore index 4cbb8f87..4cad133b 100644 --- a/.gitignore +++ b/.gitignore @@ -126,3 +126,7 @@ Loading complete # Artifacts packages/theming/tests/e2e/*.css packages/theming/tests/e2e/*.css.map + +# Agents and related files +.opencode +.pi diff --git a/.opencode/command/opsx-apply.md b/.opencode/command/opsx-apply.md deleted file mode 100644 index 89fb9ed4..00000000 --- a/.opencode/command/opsx-apply.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -description: Implement tasks from an OpenSpec change (Experimental) ---- - -Implement tasks from an OpenSpec change. - -**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes. - -**Steps** - -1. **Select the change** - - If a name is provided, use it. Otherwise: - - Infer from conversation context if the user mentioned a change - - Auto-select if only one active change exists - - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select - - Always announce: "Using change: " and how to override (e.g., `/opsx:apply `). - -2. **Check status to understand the schema** - ```bash - openspec status --change "" --json - ``` - Parse the JSON to understand: - - `schemaName`: The workflow being used (e.g., "spec-driven") - - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others) - -3. **Get apply instructions** - - ```bash - openspec instructions apply --change "" --json - ``` - - This returns: - - Context file paths (varies by schema) - - Progress (total, complete, remaining) - - Task list with status - - Dynamic instruction based on current state - - **Handle states:** - - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue` - - If `state: "all_done"`: congratulate, suggest archive - - Otherwise: proceed to implementation - -4. **Read context files** - - Read the files listed in `contextFiles` from the apply instructions output. - The files depend on the schema being used: - - **spec-driven**: proposal, specs, design, tasks - - Other schemas: follow the contextFiles from CLI output - -5. **Show current progress** - - Display: - - Schema being used - - Progress: "N/M tasks complete" - - Remaining tasks overview - - Dynamic instruction from CLI - -6. **Implement tasks (loop until done or blocked)** - - For each pending task: - - Show which task is being worked on - - Make the code changes required - - Keep changes minimal and focused - - Mark task complete in the tasks file: `- [ ]` → `- [x]` - - Continue to next task - - **Pause if:** - - Task is unclear → ask for clarification - - Implementation reveals a design issue → suggest updating artifacts - - Error or blocker encountered → report and wait for guidance - - User interrupts - -7. **On completion or pause, show status** - - Display: - - Tasks completed this session - - Overall progress: "N/M tasks complete" - - If all done: suggest archive - - If paused: explain why and wait for guidance - -**Output During Implementation** - -``` -## Implementing: (schema: ) - -Working on task 3/7: -[...implementation happening...] -✓ Task complete - -Working on task 4/7: -[...implementation happening...] -✓ Task complete -``` - -**Output On Completion** - -``` -## Implementation Complete - -**Change:** -**Schema:** -**Progress:** 7/7 tasks complete ✓ - -### Completed This Session -- [x] Task 1 -- [x] Task 2 -... - -All tasks complete! Ready to archive this change. -``` - -**Output On Pause (Issue Encountered)** - -``` -## Implementation Paused - -**Change:** -**Schema:** -**Progress:** 4/7 tasks complete - -### Issue Encountered - - -**Options:** -1.