diff --git a/.agents/skills/.openspec-target b/.agents/skills/.openspec-target new file mode 100644 index 0000000..fbccf77 --- /dev/null +++ b/.agents/skills/.openspec-target @@ -0,0 +1,2 @@ +claude own-files +kiro own-files diff --git a/.claude/skills/openspec-apply-change/SKILL.md b/.agents/skills/openspec-apply-change/SKILL.md similarity index 91% rename from .claude/skills/openspec-apply-change/SKILL.md rename to .agents/skills/openspec-apply-change/SKILL.md index 1b17ef8..936d073 100644 --- a/.claude/skills/openspec-apply-change/SKILL.md +++ b/.agents/skills/openspec-apply-change/SKILL.md @@ -7,7 +7,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.16.1" + generatedBy: "2.0.0" --- Implement tasks from an OpenSpec change. @@ -20,12 +20,12 @@ One `"root": null` is not about setup: when a `status` error message starts with 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 `), or continue without OpenSpec for this request. Wait for their answer. +- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or invoking this skill by name. 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 invoked this skill by name. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store `), 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. -**Input**: Optionally specify a change name (e.g., `/openspec-apply-change add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes. +**Input**: Optionally specify a change name (e.g., `openspec-apply-change add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes. **Steps** @@ -36,7 +36,7 @@ In both branches, never create the root as a side effect: do not run `openspec i - Auto-select if only one active change exists - If ambiguous, run `openspec list --json` to get available changes and ask the user to select one - Always announce: "Using change: " and how to override (e.g., `/openspec-apply-change `). + Always announce: "Using change: " and how to override (e.g., `openspec-apply-change `). 2. **Check status to understand the schema** ```bash @@ -64,7 +64,7 @@ In both branches, never create the root as a side effect: do not run `openspec i **Handle states:** - If `state: "blocked"`: show the message and pause implementation. - - If `missingArtifacts` is non-empty: suggest using `/openspec-continue-change` to create them. + - If `missingArtifacts` is non-empty: suggest using `openspec-continue-change` to create them. - Otherwise, follow the CLI instruction to create or repair the schema-configured tracking file from existing planning artifacts. Do not assume another artifact is ready or start implementation while blocked. - If `state: "all_done"`: report that all tracked tasks are complete and suggest review or verification as appropriate before archiving - Otherwise: proceed to implementation @@ -157,7 +157,7 @@ Working on task 4/7: ... All tracked tasks are complete. Review or verify the change as appropriate -before archiving. You can archive this change with `/openspec-archive-change`. +before archiving. You can archive this change with `openspec-archive-change`. ``` **Output On Pause (Issue Encountered)** diff --git a/.kiro/skills/openspec-archive-change/SKILL.md b/.agents/skills/openspec-archive-change/SKILL.md similarity index 96% rename from .kiro/skills/openspec-archive-change/SKILL.md rename to .agents/skills/openspec-archive-change/SKILL.md index 62e5227..917c351 100644 --- a/.kiro/skills/openspec-archive-change/SKILL.md +++ b/.agents/skills/openspec-archive-change/SKILL.md @@ -7,7 +7,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.16.1" + generatedBy: "2.0.0" --- Archive a completed change in the experimental workflow. @@ -20,8 +20,8 @@ One `"root": null` is not about setup: when a `status` error message starts with 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 `), or continue without OpenSpec for this request. Wait for their answer. +- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or invoking this skill by name. 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 invoked this skill by name. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store `), 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. @@ -41,7 +41,7 @@ In both branches, never create the root as a side effect: do not run `openspec i When prompting, show only active changes (not already archived). Include the schema used for each change if available. - Always announce: "Using change: " and how to override (e.g., `/openspec-archive-change `). + Always announce: "Using change: " and how to override (e.g., `openspec-archive-change `). **Load current archive inputs before the existing archive checks:** diff --git a/.claude/skills/openspec-bulk-archive-change/SKILL.md b/.agents/skills/openspec-bulk-archive-change/SKILL.md similarity index 97% rename from .claude/skills/openspec-bulk-archive-change/SKILL.md rename to .agents/skills/openspec-bulk-archive-change/SKILL.md index a96ecc4..0104efe 100644 --- a/.claude/skills/openspec-bulk-archive-change/SKILL.md +++ b/.agents/skills/openspec-bulk-archive-change/SKILL.md @@ -7,7 +7,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.16.1" + generatedBy: "2.0.0" --- Archive multiple completed changes in a single operation. @@ -22,8 +22,8 @@ One `"root": null` is not about setup: when a `status` error message starts with 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 `), or continue without OpenSpec for this request. Wait for their answer. +- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or invoking this skill by name. 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 invoked this skill by name. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store `), 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. diff --git a/.kiro/skills/openspec-continue-change/SKILL.md b/.agents/skills/openspec-continue-change/SKILL.md similarity index 94% rename from .kiro/skills/openspec-continue-change/SKILL.md rename to .agents/skills/openspec-continue-change/SKILL.md index 4997649..66cd38f 100644 --- a/.kiro/skills/openspec-continue-change/SKILL.md +++ b/.agents/skills/openspec-continue-change/SKILL.md @@ -7,7 +7,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.16.1" + generatedBy: "2.0.0" --- Continue working on a change by creating the next artifact. @@ -20,8 +20,8 @@ One `"root": null` is not about setup: when a `status` error message starts with 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 `), or continue without OpenSpec for this request. Wait for their answer. +- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or invoking this skill by name. 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 invoked this skill by name. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store `), 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. @@ -43,7 +43,7 @@ In both branches, never create the root as a side effect: do not run `openspec i Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to continue. - Always announce: "Using change: " and how to override (e.g., `/openspec-continue-change `). + Always announce: "Using change: " and how to override (e.g., `openspec-continue-change `). 2. **Check current status** ```bash diff --git a/.claude/skills/openspec-explore/SKILL.md b/.agents/skills/openspec-explore/SKILL.md similarity index 91% rename from .claude/skills/openspec-explore/SKILL.md rename to .agents/skills/openspec-explore/SKILL.md index ee6f689..63bfbcc 100644 --- a/.claude/skills/openspec-explore/SKILL.md +++ b/.agents/skills/openspec-explore/SKILL.md @@ -7,12 +7,12 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.16.1" + generatedBy: "2.0.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, 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 point them at `/openspec-propose`, which turns the discussion into a change. 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. +**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 point them at `openspec-propose`, which turns the discussion into a change. 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. @@ -24,8 +24,8 @@ One `"root": null` is not about setup: when a `status` error message starts with 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 `), or continue without OpenSpec for this request. Wait for their answer. +- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or invoking this skill by name. 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 invoked this skill by name. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store `), 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. @@ -160,7 +160,7 @@ If the user asks you to capture the exploration as a new change, that request is 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. Choose the output path before creating anything: when `resolvedOutputPath` is a glob, use the instruction to choose a concrete path inside `changeRoot` and verify it remains inside `changeRoot` after resolving symlinks, both in its parent directories and in the file itself if it already exists; if it does not, stop and tell the user. Otherwise the output path is `resolvedOutputPath`. If the instruction delegates creation to a specific skill or command, invoke it only if it can write the artifact to that output path; otherwise stop and tell the user. Otherwise write the artifact to that output path. Verify that the selected concrete output exists at that output path. 4. After creating each artifact, re-run `openspec status --change "" --json` (append the confirmed `--store ""` 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 "" --change "" --json` (append the confirmed `--store ""` 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. When the requested capture is done, stop there and name where the work continues: `/openspec-propose` writes the remaining planning artifacts, and `/openspec-apply-change` implements the change once tasks exist. Capturing artifacts never starts implementing them. +Capture the artifact(s) the user requested without asking them to invoke another workflow. 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: `openspec-propose` writes the remaining planning artifacts, and `openspec-apply-change` implements the change once tasks exist. Capturing artifacts never starts implementing them. ### When a change exists @@ -268,7 +268,7 @@ You: [reads codebase] **User is stuck mid-implementation:** ``` -User: /openspec-explore add-auth-system +User: openspec-explore add-auth-system The OAuth integration is more complex than expected You: [reads change artifacts] @@ -318,7 +318,7 @@ You: That changes everything. There's no required ending. Discovery might: -- **Flow into a proposal**: "Ready to start? Run `/openspec-propose` and this becomes a change." +- **Flow into a proposal**: "Ready to start? Use the `openspec-propose` skill and this becomes a change." - **Result in artifact updates**: "Updated the design with these decisions" - **Just provide clarity**: User has what they need, moves on - **Continue later**: "We can pick this up anytime" @@ -335,7 +335,7 @@ When it feels like things are crystallizing, you might summarize: **Open questions**: [if any remain] **Next steps** (if ready): -- Turn this into a change: `/openspec-propose` +- Turn this into a change: `openspec-propose` - Keep exploring: just keep talking ``` @@ -345,7 +345,7 @@ 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. When the user is ready to build, name the handoff rather than starting: `/openspec-propose` turns the discussion into a change, and the work happens there. +- **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: `openspec-propose` turns the discussion into a change, and the work happens there. - **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 diff --git a/.claude/skills/openspec-ff-change/SKILL.md b/.agents/skills/openspec-ff-change/SKILL.md similarity index 94% rename from .claude/skills/openspec-ff-change/SKILL.md rename to .agents/skills/openspec-ff-change/SKILL.md index b4bf2d1..5701c54 100644 --- a/.claude/skills/openspec-ff-change/SKILL.md +++ b/.agents/skills/openspec-ff-change/SKILL.md @@ -7,7 +7,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.16.1" + generatedBy: "2.0.0" --- Fast-forward through artifact creation - generate everything needed to start implementation in one go. @@ -20,8 +20,8 @@ One `"root": null` is not about setup: when a `status` error message starts with 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 `), or continue without OpenSpec for this request. Wait for their answer. +- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or invoking this skill by name. 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 invoked this skill by name. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store `), 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. @@ -108,7 +108,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 `/openspec-apply-change` or ask me to implement to start working on the tasks." +- Prompt: "Use the `openspec-apply-change` skill or ask me to implement to start working on the tasks." **Artifact Creation Guidelines** diff --git a/.claude/skills/openspec-new-change/SKILL.md b/.agents/skills/openspec-new-change/SKILL.md similarity index 91% rename from .claude/skills/openspec-new-change/SKILL.md rename to .agents/skills/openspec-new-change/SKILL.md index 574f5a3..2dc1a5d 100644 --- a/.claude/skills/openspec-new-change/SKILL.md +++ b/.agents/skills/openspec-new-change/SKILL.md @@ -7,7 +7,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.16.1" + generatedBy: "2.0.0" --- Start a new change using the experimental artifact-driven approach. @@ -20,8 +20,8 @@ One `"root": null` is not about setup: when a `status` error message starts with 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 `), or continue without OpenSpec for this request. Wait for their answer. +- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or invoking this skill by name. 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 invoked this skill by name. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store `), 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. diff --git a/.kiro/skills/openspec-onboard/SKILL.md b/.agents/skills/openspec-onboard/SKILL.md similarity index 86% rename from .kiro/skills/openspec-onboard/SKILL.md rename to .agents/skills/openspec-onboard/SKILL.md index 91c1690..cbc0c4c 100644 --- a/.kiro/skills/openspec-onboard/SKILL.md +++ b/.agents/skills/openspec-onboard/SKILL.md @@ -7,7 +7,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.16.1" + generatedBy: "2.0.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. @@ -20,8 +20,8 @@ One `"root": null` is not about setup: when a `status` error message starts with 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 `), or continue without OpenSpec for this request. Wait for their answer. +- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or invoking this skill by name. 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 invoked this skill by name. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store `), 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. @@ -39,7 +39,7 @@ openspec --version 2>&1 || echo "CLI_NOT_INSTALLED" ``` **If CLI not installed:** -> OpenSpec CLI is not installed. Install it first, then come back to `/openspec-onboard`. +> OpenSpec CLI is not installed. Install it first, then come back to `openspec-onboard`. Stop here if not installed. @@ -166,7 +166,7 @@ Spend 1-2 minutes investigating the relevant code: │ [Optional: ASCII diagram if helpful] │ └─────────────────────────────────────────┘ -Explore mode (`/openspec-explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem. +Explore mode (`openspec-explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem. Now let's create a change to hold our work. ``` @@ -495,26 +495,26 @@ This same rhythm works for any size change—a small fix or a major feature. --- -## Command Reference +## Skill Reference -**The commands you have installed:** +**The skills you have installed:** - | Command | What it does | + | Skill | What it does | |------------------|--------------------------------------------| - | `/openspec-propose` | Create a change and generate all artifacts | - | `/openspec-explore` | Think through problems before/during work | - | `/openspec-apply-change` | Implement tasks from a change | - | `/openspec-archive-change` | Archive a completed change | - | `/openspec-new-change` | Start a new change, one artifact at a time | - | `/openspec-continue-change` | Continue working on an existing change | - | `/openspec-ff-change` | Fast-forward: create all artifacts at once | - | `/openspec-verify-change` | Verify implementation matches artifacts | + | `openspec-propose` | Create a change and generate all artifacts | + | `openspec-explore` | Think through problems before/during work | + | `openspec-apply-change` | Implement tasks from a change | + | `openspec-archive-change` | Archive a completed change | + | `openspec-new-change` | Start a new change, one artifact at a time | + | `openspec-continue-change` | Continue working on an existing change | + | `openspec-ff-change` | Fast-forward: create all artifacts at once | + | `openspec-verify-change` | Verify implementation matches artifacts | --- ## What's Next? -Try `/openspec-propose` on something you actually want to build. You've got the rhythm now! +Try `openspec-propose` on something you actually want to build. You've got the rhythm now! ``` --- @@ -529,35 +529,35 @@ 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 "" --json`. To pick up where we left off later, `openspec status --change "" --json` shows exactly where the change stands. -- `/openspec-continue-change ` - Resume artifact creation -- `/openspec-apply-change ` - Jump to implementation (if tasks exist) +- `openspec-continue-change ` - Resume artifact creation +- `openspec-apply-change ` - Jump to implementation (if tasks exist) The work won't be lost. Come back whenever you're ready. ``` Exit gracefully without pressure. -### User just wants command reference +### User just wants skill reference -If the user says they just want to see the commands or skip the tutorial: +If the user says they just want to see the skills or skip the tutorial: ``` ## OpenSpec Quick Reference -**The commands you have installed:** +**The skills you have installed:** - | Command | What it does | + | Skill | What it does | |--------------------------|--------------------------------------------| - | `/openspec-propose ` | Create a change and generate all artifacts | - | `/openspec-explore` | Think through problems (no code changes) | - | `/openspec-apply-change ` | Implement tasks | - | `/openspec-archive-change ` | Archive when done | - | `/openspec-new-change ` | Start a new change, step by step | - | `/openspec-continue-change ` | Continue an existing change | - | `/openspec-ff-change ` | Fast-forward: all artifacts at once | - | `/openspec-verify-change ` | Verify implementation | - -Try `/openspec-propose` to start your first change. + | `openspec-propose ` | Create a change and generate all artifacts | + | `openspec-explore` | Think through problems (no code changes) | + | `openspec-apply-change ` | Implement tasks | + | `openspec-archive-change ` | Archive when done | + | `openspec-new-change ` | Start a new change, step by step | + | `openspec-continue-change ` | Continue an existing change | + | `openspec-ff-change ` | Fast-forward: all artifacts at once | + | `openspec-verify-change ` | Verify implementation | + +Try `openspec-propose` to start your first change. ``` Exit gracefully. diff --git a/.claude/skills/openspec-propose/SKILL.md b/.agents/skills/openspec-propose/SKILL.md similarity index 96% rename from .claude/skills/openspec-propose/SKILL.md rename to .agents/skills/openspec-propose/SKILL.md index c0e4930..ffb2441 100644 --- a/.claude/skills/openspec-propose/SKILL.md +++ b/.agents/skills/openspec-propose/SKILL.md @@ -7,7 +7,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.16.1" + generatedBy: "2.0.0" --- Propose a new change - create the change and generate all artifacts in one step. @@ -34,8 +34,8 @@ One `"root": null` is not about setup: when a `status` error message starts with 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 `), or continue without OpenSpec for this request. Wait for their answer. +- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or invoking this skill by name. 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 invoked this skill by name. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store `), 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. @@ -153,7 +153,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: "The artifacts are ready for review. When you are ready, run `/openspec-apply-change` or ask me to apply this change." +- Prompt: "The artifacts are ready for review. When you are ready, use the `openspec-apply-change` skill or ask me to apply this change." **Artifact Creation Guidelines** diff --git a/.claude/skills/openspec-sync-specs/SKILL.md b/.agents/skills/openspec-sync-specs/SKILL.md similarity index 96% rename from .claude/skills/openspec-sync-specs/SKILL.md rename to .agents/skills/openspec-sync-specs/SKILL.md index fdbfa3a..9f4c298 100644 --- a/.claude/skills/openspec-sync-specs/SKILL.md +++ b/.agents/skills/openspec-sync-specs/SKILL.md @@ -7,7 +7,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.16.1" + generatedBy: "2.0.0" --- Sync delta specs from a change to main specs. @@ -22,8 +22,8 @@ One `"root": null` is not about setup: when a `status` error message starts with 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 `), or continue without OpenSpec for this request. Wait for their answer. +- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or invoking this skill by name. 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 invoked this skill by name. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store `), 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. @@ -42,7 +42,7 @@ In both branches, never create the root as a side effect: do not run `openspec i When prompting, show changes that have delta specs (under `specs/` directory). - Always announce: "Using change: " and how to override (e.g., `/openspec-sync-specs `). + Always announce: "Using change: " and how to override (e.g., `openspec-sync-specs `). 2. **Resolve change context** diff --git a/.claude/skills/openspec-update-change/SKILL.md b/.agents/skills/openspec-update-change/SKILL.md similarity index 84% rename from .claude/skills/openspec-update-change/SKILL.md rename to .agents/skills/openspec-update-change/SKILL.md index a4ed63a..c13c29b 100644 --- a/.claude/skills/openspec-update-change/SKILL.md +++ b/.agents/skills/openspec-update-change/SKILL.md @@ -7,7 +7,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.16.1" + generatedBy: "2.0.0" --- Revise a change's existing planning artifacts and keep them coherent. Never edit code. @@ -20,14 +20,14 @@ One `"root": null` is not about setup: when a `status` error message starts with 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 `), or continue without OpenSpec for this request. Wait for their answer. +- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or invoking this skill by name. 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 invoked this skill by name. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store `), 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. **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. -This workflow revises artifacts that already exist; `/openspec-continue-change` is what creates the ones that do not. +This workflow revises artifacts that already exist; `openspec-continue-change` is what creates the ones that do not. **Steps** @@ -45,7 +45,7 @@ This workflow revises artifacts that already exist; `/openspec-continue-change` Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update. - Always announce: "Using change: " and how to override (e.g., `/openspec-update-change `). + Always announce: "Using change: " and how to override (e.g., `openspec-update-change `). 2. **Get the change's artifacts** ```bash @@ -69,7 +69,7 @@ This workflow revises artifacts that already exist; `/openspec-continue-change` - Read the artifact(s) the request touches and the change's other existing artifacts. - Draft the requested edit in the conversation, not in files. Work out exactly what it changes; step 5 owns every write. Then check every other existing artifact against the drafted edit - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised. - Note everything that is now inconsistent, missing, or contradictory. - - Propose revisions to files that already exist (`existingOutputPaths`). If an artifact has no existing output files and status `ready` or `blocked`, note it and point the user to `/openspec-continue-change` to create them. Leave `skipped` artifacts untouched; do not treat them as missing or defer them to the continue workflow. + - Propose revisions to files that already exist (`existingOutputPaths`). If an artifact has no existing output files and status `ready` or `blocked`, note it and point the user to `openspec-continue-change` to create them. Leave `skipped` artifacts untouched; do not treat them as missing or defer them to the continue workflow. - A glob artifact (e.g. `specs/**/*.md`) is marked `done` after at least one file matches, and the continue workflow only handles `ready` artifacts. When reconciliation identifies a missing file for a glob artifact whose `existingOutputPaths` is non-empty: 1. Run `openspec instructions "" --change "" --json` and use its `instruction` and `template`. Treat `context` and `rules` as constraints; do not copy them into the file. If instructions report `skipped: true`, do not create the file. Read current dependency files from disk; if a required non-skipped dependency is missing, stop and ask the user to restore it first. 2. Choose a concrete path inside `changeRoot` that matches `artifactPaths..outputPath` and does not already exist. Verify it remains inside `changeRoot` after resolving any symlinked parent directories. The glob `resolvedOutputPath` is not a valid target. @@ -88,22 +88,22 @@ This workflow revises artifacts that already exist; `/openspec-continue-change` ``` 6. **Point to the next step (guidance only - NEVER act on it)** - - Artifacts with empty `existingOutputPaths` and status `ready` or `blocked` -> suggest `/openspec-continue-change` to create them. - - Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; suggest `/openspec-apply-change` to carry the delta into code. - - Everything done and implemented -> suggest `/openspec-archive-change`. + - Artifacts with empty `existingOutputPaths` and status `ready` or `blocked` -> suggest `openspec-continue-change` to create them. + - Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; suggest `openspec-apply-change` to carry the delta into code. + - Everything done and implemented -> suggest `openspec-archive-change`. **Output** After each invocation, show: - Which artifacts were revised (and which proposed revisions were rejected) - Any file created under a glob artifact that was already partially populated -- Anything deferred to `/openspec-continue-change` (artifacts with no files yet and status `ready` or `blocked`, never `skipped` artifacts) -- Where the change stands and the recommended next command +- Anything deferred to `openspec-continue-change` (artifacts with no files yet and status `ready` or `blocked`, never `skipped` artifacts) +- Where the change stands and the recommended next skill **Guardrails** -- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to `/openspec-apply-change`. +- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to `openspec-apply-change`. - Use the artifact ids and paths reported by `openspec status`; never branch on hardcoded artifact names. - Edit only the concrete files in `existingOutputPaths`, plus any confirmed concrete path allowed under a partly populated glob artifact (step 4); never write to a glob `resolvedOutputPath`. -- Do not advance the build frontier: if an artifact has empty `existingOutputPaths` and status `ready` or `blocked`, that is `/openspec-continue-change`'s job. Leave `skipped` artifacts untouched. The only new-file scope is a confirmed concrete path under a glob artifact whose `existingOutputPaths` is non-empty. +- Do not advance the build frontier: if an artifact has empty `existingOutputPaths` and status `ready` or `blocked`, that is `openspec-continue-change`'s job. Leave `skipped` artifacts untouched. The only new-file scope is a confirmed concrete path under a glob artifact whose `existingOutputPaths` is non-empty. - Confirm every edit with the user before writing. -- If the request changes the change's *intent* rather than refining it, recommend starting fresh with `/openspec-new-change` (the "Update vs. Start Fresh" heuristic). +- If the request changes the change's *intent* rather than refining it, recommend starting fresh with `openspec-new-change` (the "Update vs. Start Fresh" heuristic). diff --git a/.kiro/skills/openspec-verify-change/SKILL.md b/.agents/skills/openspec-verify-change/SKILL.md similarity index 97% rename from .kiro/skills/openspec-verify-change/SKILL.md rename to .agents/skills/openspec-verify-change/SKILL.md index c767d1e..c993236 100644 --- a/.kiro/skills/openspec-verify-change/SKILL.md +++ b/.agents/skills/openspec-verify-change/SKILL.md @@ -7,7 +7,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.16.1" + generatedBy: "2.0.0" --- Verify that an implementation matches the change artifacts (specs, tasks, design). @@ -20,8 +20,8 @@ One `"root": null` is not about setup: when a `status` error message starts with 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 `), or continue without OpenSpec for this request. Wait for their answer. +- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or invoking this skill by name. 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 invoked this skill by name. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store `), 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. @@ -40,7 +40,7 @@ In both branches, never create the root as a side effect: do not run `openspec i Include the schema used for each change if available. Mark changes with incomplete tasks as "(In Progress)". - Always announce: "Using change: " and how to override (e.g., `/openspec-verify-change `). + Always announce: "Using change: " and how to override (e.g., `openspec-verify-change `). 2. **Check status to understand the schema** ```bash diff --git a/.claude/skills/openspec-apply-change b/.claude/skills/openspec-apply-change new file mode 120000 index 0000000..86591ac --- /dev/null +++ b/.claude/skills/openspec-apply-change @@ -0,0 +1 @@ +../../.agents/skills/openspec-apply-change \ No newline at end of file diff --git a/.claude/skills/openspec-archive-change b/.claude/skills/openspec-archive-change new file mode 120000 index 0000000..e8b7861 --- /dev/null +++ b/.claude/skills/openspec-archive-change @@ -0,0 +1 @@ +../../.agents/skills/openspec-archive-change \ No newline at end of file diff --git a/.claude/skills/openspec-archive-change/SKILL.md b/.claude/skills/openspec-archive-change/SKILL.md deleted file mode 100644 index 62e5227..0000000 --- a/.claude/skills/openspec-archive-change/SKILL.md +++ /dev/null @@ -1,221 +0,0 @@ ---- -name: openspec-archive-change -description: Archive a completed OpenSpec change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete. Also use when the user says "openspec archive" or "opsx archive". -allowed-tools: Bash(openspec:*) -license: MIT -compatibility: Requires openspec CLI. -metadata: - author: openspec - version: "1.0" - generatedBy: "1.16.1" ---- - -Archive a completed change in the experimental workflow. - -**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store ` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `schemas`, `view`). Once selected, treat `--store ` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "" --json --store ""`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root. - -**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 ` 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 `), 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. - -`` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec. - -**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** - -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 ask the user to select one - - When prompting, show only active changes (not already archived). - Include the schema used for each change if available. - - Always announce: "Using change: " and how to override (e.g., `/openspec-archive-change `). - - **Load current archive inputs before the existing archive checks:** - - After resolving the selected change and planning root, run: - ```bash - openspec instructions archive --change "" --json - ``` - Keep the same selected-root flags on this command. This lookup is advisory and - optional: it only supplies extra prompt inputs, so it must never block archiving. - If it exits non-zero or returns invalid JSON — for example on an older CLI that - does not support this command yet — continue the archive workflow with no - context and no operation guidance. Do not report an error and do not stop. - - A successful response may omit both optional fields. Treat `context` as a - required prompt-level input: read and consider it, and apply relevant project - facts, conventions, and constraints. Treat `operationGuidance` as optional - additive advice: read and consider every entry, and follow entries that are - applicable and compatible with the built-in archive workflow. - - Keep both fields separate from built-in steps, explicit user choices, resolved - paths, CLI checks, and command contracts. If context conflicts with one of those - controlling inputs, report the conflict and preserve the controlling value. If - guidance is inapplicable or conflicts with a controlling input, do not follow it - and explain why. Do not infer replacement paths, skipped prompts, or flags from - either field, and do not copy their text verbatim into specs, change artifacts, - or archive summaries unless the user separately asks for it. These are - prompt-level behavior contracts, not enforceable checks. - -2. **Check artifact completion status** - - Run `openspec status --change "" --json` to check artifact completion. - - Parse the JSON to understand: - - `schemaName`: The workflow being used - - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context - - `artifacts`: List of artifacts with their status (`done`, `skipped`, or other) - - **If any artifacts are neither `done` nor `skipped`** (skipped artifacts satisfy the requirement - the change declares skip_specs): - - Display warning listing incomplete artifacts - - Ask the user to confirm they want to proceed - - Proceed if user confirms - -3. **Check task completion status** - - Run `openspec list --json` with the same selected-root flags and find the - entry in `changes` whose `name` exactly matches the selected change. - Require exactly one match and nonnegative integer `totalTasks` and - `completedTasks`, with `completedTasks <= totalTasks`. The CLI resolves - the schema's tracked task files, including custom artifact names, output - paths, and globs. - Incomplete tasks = `totalTasks - completedTasks`. - - Do not infer task completion from artifact status or the absence of a - top-level `tasks.md`. If the lookup fails, returns invalid JSON, omits or - duplicates the selected change, or returns invalid counts, report the problem - and stop before syncing or archiving. - The CLI counts only `x`/`X` checkbox markers as complete; - other markers, including unfamiliar ones, remain incomplete. - - **If incomplete tasks found:** - - Display warning showing count of incomplete tasks - - Ask the user to confirm they want to proceed - - Proceed if user confirms - - **If `totalTasks` is zero:** Proceed without a task-related warning. - -4. **Assess delta spec sync state** - - Use `artifactPaths.specs.existingOutputPaths` from status JSON as the only - delta-spec source. If the `specs` entry is missing or - `existingOutputPaths` is empty, proceed without a sync prompt and do not infer - delta specs from other artifacts. - - **If delta specs exist:** - - Compare each delta spec with its corresponding main spec at `/openspec/specs//spec.md` (use the store-aware `planningHome.root` from step 2, not a hardcoded repo path) - - A missing main spec is **not automatically** "already synced". For a new capability, the main spec is an *output* of the sync, not an input: - - If the delta has MODIFIED or RENAMED requirements, report that only ADDED requirements can create a new main spec and mark that capability as sync-blocked. Never invent a requirement that has no current version. - - Otherwise, if the delta has only REMOVED requirements and the change's `.openspec.yaml` declares `retire_capabilities: true`, the capability is already retired: count it as already synced, warn that there is nothing left to remove, and do not recreate the main spec. Apply this rule both now and when verifying a completed sync. - - Otherwise, if the delta has no ADDED requirements, report that no sync is possible and mark that capability as sync-blocked. For a REMOVED-only delta, warn that there is no main spec to remove from and leave the main-spec tree unchanged. `openspec archive` refuses the unmarked REMOVED-only case with `Spec must have at least one requirement`. - - Otherwise, count the capability as needing sync and name it in the summary (`: new main spec will be created`). If the delta also has REMOVED requirements, warn that they will be ignored because there is no main spec to remove from. The sync creates the main spec from only the delta's ADDED requirements, exactly as `openspec archive` does. - - Determine what changes would be applied (adds, modifications, removals, renames) - - Continue assessing the remaining capabilities even when one is sync-blocked. Show a combined summary before prompting. - - **Prompt options:** - - If any capability is sync-blocked: explain why and offer only "Archive without syncing", "Cancel" - - Otherwise, if changes needed: "Sync now (recommended)", "Archive without syncing" - - Otherwise, if already synced: "Archive now", "Sync anyway", "Cancel" - - Route on the answer: - - "Cancel" — stop, do not archive - - "Archive without syncing" or "Archive now" — proceed to archive - - "Sync now" or "Sync anyway" — sync, then verify (below). Do not start any sync while a capability is sync-blocked; explain the blocker and repeat the available choices. - - Anything else — ask again rather than archiving - - Before a selected sync writes any main spec, run - `openspec instructions specs --change "" --json` once with the same - selected-root flags. Require a zero exit status and valid artifact-instruction - JSON. If the lookup fails or returns invalid JSON, report the error and stop - before writing any main spec or moving the change. A valid response with omitted - `rules` is the no-rules case. Apply returned `rules` only to the content and - form of main specs produced by this merge; do not use them as archive guidance, - change CLI behavior, or copy the rule text into any output file. - - Then run the `openspec-sync-specs` workflow inline (agent-driven intelligent merge) for change '', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching `specs` instructions again. Do not delegate it to a background task — step 5 would move `changeRoot` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result. - - If the sync reports any stop or blocking condition, treat the sync as failed. - Stop the archive immediately. Do not perform the post-sync content comparison and do not move its `changeRoot`. - Nothing has moved, so the user can fix the blocking condition or re-run the sync. - - After the sync writes each main spec, verify its structure against the canonical sync contract: - - A new main spec starts with a `# Specification` title. An existing main spec keeps its title exactly as it is. - - Preserve existing `## Purpose` sections completely untouched for established main specs. - - For a new main spec, copy the delta `## Purpose` verbatim. Warn only if the purpose text is shorter than standard validation expects. Do not regenerate or rewrite existing authored purpose. If no usable `## Purpose` is provided, use the existing TBD Purpose behavior and warning. - - Verify that no delta-style section headers (`## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`, `## RENAMED Requirements`) remain in the main spec, adhering strictly to the sync workflow formatting rules. - - Requirement blocks the sync wrote or changed use `### Requirement:` headings, and their scenarios use `#### Scenario:` headings, under the spec's `## Requirements` section. Leave content the delta does not mention exactly as it is. - - Then re-run the comparison from the top of this step, including the explicitly retired, missing-spec case, against every capability that has a delta spec in `artifactPaths.specs.existingOutputPaths` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced: - - ADDED requirements present - - MODIFIED requirements carrying the scenario and description changes named in the delta, with their other scenarios intact - - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving `## Requirements` empty), its main spec deleted rather than left empty. - - RENAMED requirements present under the new name and absent under the old one - - If the sync failed, or any capability does not match, report what differs and stop — do not archive. Nothing has moved and `changeRoot` is intact, so the user can fix the mismatch or re-run the sync and start the archive again. - -5. **Perform the archive** - - Create an `archive` directory under `planningHome.changesDir` if it doesn't exist: - ```bash - mkdir -p "/archive" - ``` - - Generate the target name: use the change name as-is when it already starts with a `YYYY-MM-DD-` prefix; otherwise prepend the current date as `YYYY-MM-DD-`. Never stack a second date (same rule as `openspec archive`). - - **Check if target already exists:** - - If yes: Fail with error, suggest renaming existing archive or using different date - - If no: Move `changeRoot` to the archive directory - - ```bash - mv "" "/archive/" - ``` - -6. **Display summary** - - Show archive completion summary including: - - Change name - - Schema that was used - - Archive location - - Whether specs were synced (if applicable) - - Note about any warnings (incomplete artifacts/tasks) - -**Output On Success** - -```markdown -## Archive Complete - -**Change:** -**Schema:** -**Archived to:** the archive path derived from `planningHome.changesDir`// -**Specs:** <"✓ Synced to main specs" only if the step 4 verification passed; otherwise "No delta specs" or "Sync skipped"> - -<"All artifacts complete. All tasks complete." — or, if archived with warnings, list them instead (e.g. "Archived with 2 incomplete tasks")> -``` - -**Guardrails** -- Announce the selected change; prompt for selection when it is ambiguous -- Use artifact graph (openspec status --json) for completion checking -- 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, run the `openspec-sync-specs` workflow inline (agent-driven) -- Never archive while a spec sync is still in flight — run the sync inline and verify the main specs before moving `changeRoot` -- If delta specs exist, always run the sync assessment and show the combined summary before prompting -- Apply relevant runtime context and report conflicts; operation guidance remains advisory -- Consider every guidance entry and explain any inapplicable or conflicting advice -- Existing CLI checks, resolved paths, prompts, and command contracts are unchanged -- Artifact rules constrain only the specs being written and are never operation guidance -- Never copy runtime context, operation guidance, or artifact-rule text verbatim into output files diff --git a/.claude/skills/openspec-bulk-archive-change b/.claude/skills/openspec-bulk-archive-change new file mode 120000 index 0000000..5ae5fb5 --- /dev/null +++ b/.claude/skills/openspec-bulk-archive-change @@ -0,0 +1 @@ +../../.agents/skills/openspec-bulk-archive-change \ No newline at end of file diff --git a/.claude/skills/openspec-continue-change b/.claude/skills/openspec-continue-change new file mode 120000 index 0000000..55fc48b --- /dev/null +++ b/.claude/skills/openspec-continue-change @@ -0,0 +1 @@ +../../.agents/skills/openspec-continue-change \ No newline at end of file diff --git a/.claude/skills/openspec-continue-change/SKILL.md b/.claude/skills/openspec-continue-change/SKILL.md deleted file mode 100644 index 4997649..0000000 --- a/.claude/skills/openspec-continue-change/SKILL.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -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. Also use when the user says "openspec continue" or "opsx continue". -allowed-tools: Bash(openspec:*) -license: MIT -compatibility: Requires openspec CLI. -metadata: - author: openspec - version: "1.0" - generatedBy: "1.16.1" ---- - -Continue working on a change by creating the next artifact. - -**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store ` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `schemas`, `view`). Once selected, treat `--store ` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "" --json --store ""`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root. - -**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 ` 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 `), 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. - -**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** - -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 sorted by most recently modified, and ask the user to select one - - When prompting, present the top 3-4 most recently modified changes as options, showing: - - Change name - - Status (e.g., "0/5 tasks", "complete", "no tasks") - - How recently it was modified (from `lastModified` field) - - Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to continue. - - Always announce: "Using change: " and how to override (e.g., `/openspec-continue-change `). - -2. **Check current status** - ```bash - openspec status --change "" --json - ``` - Parse the JSON to understand current state. The response includes: - - `schemaName`: The workflow schema being used (e.g., "spec-driven") - - `artifacts`: Array of artifacts with their status ("done", "skipped", "ready", "blocked") - - `isPlanningComplete`: Boolean indicating if all planning artifacts are complete. Older CLI versions expose the same value as `isComplete`. - - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths. - -3. **Act based on status**: - - --- - - **Before anything else, finish a partly written artifact**: - - An artifact whose output is a glob pattern (e.g. `specs/**/*.md`) reads `done` as soon as one matching file exists, so a run interrupted while writing its files leaves it `done` with some still missing - - For each such `done` artifact, first get its instructions and read any completed dependencies needed to determine the expected files. Then compare those files with `artifactPaths..existingOutputPaths`. For spec-driven's `specs`, read the proposal and check for one `specs//spec.md` per capability it lists; resolve each expected path against `changeRoot` before comparing path identity, and verify each one remains inside `changeRoot` after resolving symlinks, both in its parent directories and in the file itself if it already exists - - Never write an expected path that fails that check; stop and tell the user. If any are missing, write only the missing files, each at its checked path - when the `instruction` field delegates creation to a skill or command, invoke it only if it can write each file to its checked path; otherwise stop and tell the user - and STOP - that counts as this invocation's ONE artifact. If you cannot tell whether a file was left out on purpose, ask the user - - --- - - **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. Once implementation and any tracked work are complete, archive it." - - STOP - - --- - - **If artifacts are ready to create** (status shows artifacts with `status: "ready"`): - - Pick the FIRST artifact with `status: "ready"` from the status output - - Get its instructions: - ```bash - openspec instructions --change "" --json - ``` - - Parse the JSON. The key fields are: - - `context`: Project background (constraints for you - do NOT include in output) - - `rules`: Artifact-specific rules (constraints for you - do NOT include in output) - - `template`: The structure to use for your output file - - `instruction`: Schema-specific guidance - - `resolvedOutputPath`: Resolved path or pattern to write the artifact - - `dependencies`: Completed artifacts to read for context (entries with `skipped: true` have no files - do not look for them) - - `skipped`/`warning`: present when the change declares skip_specs and this artifact must NOT be created - pick another artifact - - **Create the artifact file**: - - Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them) - - Choose the output path before creating anything. If the `resolvedOutputPath` specified in instructions is a glob pattern, choose a concrete path inside `changeRoot` using the schema instruction and the change's context, and verify it remains inside `changeRoot` after resolving symlinks, both in its parent directories and in the file itself if it already exists; if it does not, stop and tell the user. Otherwise the output path is `resolvedOutputPath` - - If the `instruction` field delegates creation to a specific skill or command, invoke it only if it can write the artifact to that output path; otherwise stop and tell the user - - Otherwise, write it yourself: - - Use `template` as the structure - fill in its sections - - Apply `context` and `rules` as constraints when writing - but do NOT copy them into the file - - Write the file to that output path - - Either way, verify the artifact file exists at that output path - - Show what was created and what's now unlocked - - STOP after creating ONE artifact - - --- - - **If no artifacts are ready (all blocked)**: - - This shouldn't happen with a valid schema - - Show status and suggest checking for issues - -4. **After creating an artifact, show progress** - ```bash - openspec status --change "" - ``` - -**Output** - -After each invocation, show: -- Which artifact was created -- Schema workflow being used -- Current progress (N/M complete) -- What artifacts are now unlocked -- Prompt: "Want to continue? Just ask me to continue or tell me what to do next." - -**Artifact Creation Guidelines** - -The artifact types and their purpose depend on the schema. The `instruction` field from the instructions output is the authoritative guidance for each artifact - follow it even when the artifact has a familiar name (proposal.md, tasks.md, etc.), since custom schemas may define different content or a different process for the same file names. - -If the `instruction` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly - but only once you have chosen and checked the output path, and only if it can write there. - -**Guardrails** -- Create ONE artifact per invocation -- Always read dependency artifacts before creating a new one - re-read from disk, not from conversation memory (files may have changed since you last saw them) -- Never skip artifacts or create out of order -- If context is unclear, ask the user before creating -- Verify the artifact file exists after writing before marking progress -- Use the schema's artifact sequence, don't assume specific artifact names -- **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 diff --git a/.claude/skills/openspec-explore b/.claude/skills/openspec-explore new file mode 120000 index 0000000..8bc10d1 --- /dev/null +++ b/.claude/skills/openspec-explore @@ -0,0 +1 @@ +../../.agents/skills/openspec-explore \ No newline at end of file diff --git a/.claude/skills/openspec-ff-change b/.claude/skills/openspec-ff-change new file mode 120000 index 0000000..9593649 --- /dev/null +++ b/.claude/skills/openspec-ff-change @@ -0,0 +1 @@ +../../.agents/skills/openspec-ff-change \ No newline at end of file diff --git a/.claude/skills/openspec-new-change b/.claude/skills/openspec-new-change new file mode 120000 index 0000000..23e014c --- /dev/null +++ b/.claude/skills/openspec-new-change @@ -0,0 +1 @@ +../../.agents/skills/openspec-new-change \ No newline at end of file diff --git a/.claude/skills/openspec-onboard b/.claude/skills/openspec-onboard new file mode 120000 index 0000000..b0b735b --- /dev/null +++ b/.claude/skills/openspec-onboard @@ -0,0 +1 @@ +../../.agents/skills/openspec-onboard \ No newline at end of file diff --git a/.claude/skills/openspec-onboard/SKILL.md b/.claude/skills/openspec-onboard/SKILL.md deleted file mode 100644 index 91c1690..0000000 --- a/.claude/skills/openspec-onboard/SKILL.md +++ /dev/null @@ -1,575 +0,0 @@ ---- -name: openspec-onboard -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". -allowed-tools: Bash(openspec:*) -license: MIT -compatibility: Requires openspec CLI. -metadata: - author: openspec - version: "1.0" - generatedBy: "1.16.1" ---- - -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. - -**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store ` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `schemas`, `view`). Once selected, treat `--store ` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "" --json --store ""`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root. - -**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 ` 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 `), 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. - ---- - -## Preflight - -Before starting, check if the OpenSpec CLI is installed: - -```bash -# 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 CLI not installed:** -> OpenSpec CLI is not installed. Install it first, then come back to `/openspec-onboard`. - -Stop here if not installed. - ---- - -## Phase 1: Welcome - -Display: - -``` -## Welcome to OpenSpec! - -I'll walk you through a complete change cycle—from idea to implementation—using a real task in your codebase. Along the way, you'll learn the workflow by doing it. - -**What we'll do:** -1. Pick a small, real task in your codebase -2. Explore the problem briefly -3. Create a change (the container for our work) -4. Build the artifacts: proposal → specs → design → tasks -5. Implement the tasks -6. Archive the completed change - -**Time:** ~15-20 minutes - -Let's start by finding something to work on. -``` - ---- - -## Phase 2: Task Selection - -### Codebase Analysis - -Scan the codebase for small improvement opportunities. Look for: - -1. **TODO/FIXME comments** - Search for `TODO`, `FIXME`, `HACK`, `XXX` in code files -2. **Missing error handling** - `catch` blocks that swallow errors, risky operations without try-catch -3. **Functions without tests** - Cross-reference `src/` with test directories -4. **Type issues** - `any` types in TypeScript files (`: any`, `as any`) -5. **Debug artifacts** - `console.log`, `console.debug`, `debugger` statements in non-debug code -6. **Missing validation** - User input handlers without validation - -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 - -From your analysis, present 3-4 specific suggestions: - -``` -## Task Suggestions - -Based on scanning your codebase, here are some good starter tasks: - -**1. [Most promising task]** - Location: `src/path/to/file.ts:42` - Scope: ~1-2 files, ~20-30 lines - Why it's good: [brief reason] - -**2. [Second task]** - Location: `src/another/file.ts` - Scope: ~1 file, ~15 lines - Why it's good: [brief reason] - -**3. [Third task]** - Location: [location] - Scope: [estimate] - Why it's good: [brief reason] - -**4. Something else?** - Tell me what you'd like to work on. - -Which task interests you? (Pick a number or describe your own) -``` - -**If nothing found:** Fall back to asking what the user wants to build: -> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix? - -### Scope Guardrail - -If the user picks or describes something too large (major feature, multi-day work): - -``` -That's a valuable task, but it's probably larger than ideal for your first OpenSpec run-through. - -For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details. - -**Options:** -1. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]? -2. **Pick something else** - One of the other suggestions, or a different small task? -3. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer. - -What would you prefer? -``` - -Let the user override if they insist—this is a soft guardrail. - ---- - -## Phase 3: Explore Demo - -Once a task is selected, briefly demonstrate explore mode: - -``` -Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction. -``` - -Spend 1-2 minutes investigating the relevant code: -- Read the file(s) involved -- Draw a quick ASCII diagram if it helps -- Note any considerations - -``` -## Quick Exploration - -[Your brief analysis—what you found, any considerations] - -┌─────────────────────────────────────────┐ -│ [Optional: ASCII diagram if helpful] │ -└─────────────────────────────────────────┘ - -Explore mode (`/openspec-explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem. - -Now let's create a change to hold our work. -``` - -**PAUSE** - Wait for user acknowledgment before proceeding. - ---- - -## Phase 4: Create the Change - -**EXPLAIN:** -``` -## Creating a Change - -A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives at the `changeRoot` reported by `openspec status --change "" --json` and holds your artifacts—proposal, specs, design, tasks. - -Let me create one for our task. -``` - -**DO:** Create the change with a derived kebab-case name: -```bash -openspec new change "" -``` - -**SHOW:** -``` -Created: - -The folder structure: -``` -/ -├── proposal.md ← Why we're doing this (empty, we'll fill it) -├── design.md ← How we'll build it (empty) -├── specs/ ← Detailed requirements (empty) -└── tasks.md ← Implementation checklist (empty) -``` - -Now let's fill in the first artifact—the proposal. -``` - ---- - -## Phase 5: Proposal - -**EXPLAIN:** -``` -## The Proposal - -The proposal captures **why** we're making this change and **what** it involves at a high level. It's the "elevator pitch" for the work. - -I'll draft one based on our task. -``` - -**DO:** Draft the proposal content (don't save yet): - -`` is the spec directory relative to `specs/` (for example, -`user-auth` or `identity/user-auth`). Use the exact existing path for modified -capabilities. For new capabilities, follow the project's established spec -organization. - -``` -Here's a draft proposal: - ---- - -# Proposal - -## Why - -[1-2 sentences explaining the problem/opportunity] - -## What Changes - -[Bullet points of what will be different] - -## Capabilities - -### New Capabilities -- ``: [brief description] - -### Modified Capabilities - -- ``: [brief description] - -## Impact - -- `src/path/to/file.ts`: [what changes] -- [other files if applicable] - ---- - -Does this capture the intent? I can adjust before we save it. -``` - -**PAUSE** - Wait for user approval/feedback. - -After approval, save the proposal: -```bash -openspec instructions proposal --change "" --json -``` -Then write the content to the `resolvedOutputPath` from `openspec instructions proposal --change "" --json`. - -``` -Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves. - -Next up: specs. -``` - ---- - -## Phase 6: Specs - -**EXPLAIN:** -``` -## Specs - -Specs define **what** we're building in precise, testable terms. They use a requirement/scenario format that makes expected behavior crystal clear. - -For a small task like this, we might only need one spec file. -``` - -**DO:** Resolve where the spec file should be created: -```bash -openspec instructions specs --change "" --json -# Use resolvedOutputPath from the JSON. If it is a glob, choose the concrete file path using the schema instruction and the change's context. -``` - -Draft the spec content: - -``` -Here's the spec: - ---- - -# Spec Delta - -## ADDED Requirements - -### Requirement: - - - -#### Scenario: - -- **WHEN** -- **THEN** -- **AND** - ---- - -This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases. -``` - -Save to the concrete file path chosen from `resolvedOutputPath`. - ---- - -## Phase 7: Design - -**EXPLAIN:** -``` -## Design - -The design captures **how** we'll build it—technical decisions, tradeoffs, approach. - -For small changes, this might be brief. That's fine—not every change needs deep design discussion. -``` - -**DO:** Draft design.md: - -``` -Here's the design: - ---- - -# Design - -## Context - -[Brief context about the current state] - -## Goals / Non-Goals - -**Goals:** -- [What we're trying to achieve] - -**Non-Goals:** -- [What's explicitly out of scope] - -## Decisions - -### Decision 1: [Key decision] - -[Explanation of approach and rationale] - ---- - -For a small task, this captures the key decisions without over-engineering. -``` - -Save to the `resolvedOutputPath` from `openspec instructions design --change "" --json`. - ---- - -## Phase 8: Tasks - -**EXPLAIN:** -``` -## Tasks - -Finally, we break the work into implementation tasks—checkboxes that drive the apply phase. - -These should be small, clear, and in logical order. Each group carries the tests and documentation for its own work - the last group is only for integration checks. -``` - -**DO:** Generate tasks based on specs and design: - -``` -Here are the implementation tasks: - ---- - -# Tasks - -## 1. [Category or file] - -- [ ] 1.1 [Specific task] — verify: [test, command, observable behavior, or delivered artifact] -- [ ] 1.2 [Specific task] — verify: [test, command, observable behavior, or delivered artifact] - -## 2. Integration Verification - -- [ ] 2.1 Verify [broader integration or system behavior] with [end-to-end test or observable result] - ---- - -Each checkbox becomes a unit of work in the apply phase. Does this task breakdown look right? -``` - -**PAUSE** - Wait for user approval/feedback. - -After approval, save to the `resolvedOutputPath` from `openspec instructions tasks --change "" --json`. - -Then ask: -> "Tasks are saved. Ready to implement?" - -**PAUSE** - Wait for user to confirm before implementation. - ---- - -## Phase 9: Apply (Implementation) - -**EXPLAIN:** -``` -## Implementation - -Now we implement each task, checking them off as we go. I'll announce each one and occasionally note how the specs/design informed the approach. -``` - -**DO:** For each task: - -1. Announce: "Working on task N: [description]" -2. Implement the change in the codebase -3. Reference specs/design naturally: "The spec says X, so I'm doing Y" -4. Mark complete in tasks.md: `- [ ]` → `- [x]` -5. Brief status: "✓ Task N complete" - -Keep narration light—don't over-explain every line of code. - -After all tasks: - -``` -## Implementation Complete - -All tasks done: -- [x] Task 1 -- [x] Task 2 -- [x] ... - -The change is implemented! One more step—let's archive it. -``` - ---- - -## Phase 10: Archive - -**EXPLAIN:** -``` -## Archiving - -When a change is complete, we archive it. The archive path is derived from `planningHome.changesDir` and the date. - -Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way. -``` - -**DO:** Archive the change (`--yes` answers the confirmation prompts, which you cannot answer from a tool call): -```bash -openspec archive "" --yes -``` - -**SHOW:** -``` -Archived to: `/archive//` (the target name prepends today's date, unless the name already starts with a `YYYY-MM-DD-` prefix — then it is kept as-is, no second date) - -The change is now part of your project's history. The code is in your codebase, the decision record is preserved. -``` - ---- - -## Phase 11: Recap & Next Steps - -``` -## Congratulations! - -You just completed a full OpenSpec cycle: - -1. **Explore** - Thought through the problem -2. **New** - Created a change container -3. **Proposal** - Captured WHY -4. **Specs** - Defined WHAT in detail -5. **Design** - Decided HOW -6. **Tasks** - Broke it into steps -7. **Apply** - Implemented the work -8. **Archive** - Preserved the record - -This same rhythm works for any size change—a small fix or a major feature. - ---- - -## Command Reference - -**The commands you have installed:** - - | Command | What it does | - |------------------|--------------------------------------------| - | `/openspec-propose` | Create a change and generate all artifacts | - | `/openspec-explore` | Think through problems before/during work | - | `/openspec-apply-change` | Implement tasks from a change | - | `/openspec-archive-change` | Archive a completed change | - | `/openspec-new-change` | Start a new change, one artifact at a time | - | `/openspec-continue-change` | Continue working on an existing change | - | `/openspec-ff-change` | Fast-forward: create all artifacts at once | - | `/openspec-verify-change` | Verify implementation matches artifacts | - ---- - -## What's Next? - -Try `/openspec-propose` on something you actually want to build. You've got the rhythm now! -``` - ---- - -## Graceful Exit Handling - -### User wants to stop mid-way - -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 "" --json`. - -To pick up where we left off later, `openspec status --change "" --json` shows exactly where the change stands. -- `/openspec-continue-change ` - Resume artifact creation -- `/openspec-apply-change ` - Jump to implementation (if tasks exist) - -The work won't be lost. Come back whenever you're ready. -``` - -Exit gracefully without pressure. - -### User just wants command reference - -If the user says they just want to see the commands or skip the tutorial: - -``` -## OpenSpec Quick Reference - -**The commands you have installed:** - - | Command | What it does | - |--------------------------|--------------------------------------------| - | `/openspec-propose ` | Create a change and generate all artifacts | - | `/openspec-explore` | Think through problems (no code changes) | - | `/openspec-apply-change ` | Implement tasks | - | `/openspec-archive-change ` | Archive when done | - | `/openspec-new-change ` | Start a new change, step by step | - | `/openspec-continue-change ` | Continue an existing change | - | `/openspec-ff-change ` | Fast-forward: all artifacts at once | - | `/openspec-verify-change ` | Verify implementation | - -Try `/openspec-propose` to start your first change. -``` - -Exit gracefully. - ---- - -## Guardrails - -- **Follow the EXPLAIN → DO → SHOW → PAUSE pattern** at key transitions (after explore, after proposal draft, after tasks, after archive) -- **Keep narration light** during implementation—teach without lecturing -- **Don't skip phases** even if the change is small—the goal is teaching the workflow -- **Pause for acknowledgment** at marked points, but don't over-pause -- **Handle exits gracefully**—never pressure the user to continue -- **Use real codebase tasks**—don't simulate or use fake examples -- **Adjust scope gently**—guide toward smaller tasks but respect user choice diff --git a/.claude/skills/openspec-propose b/.claude/skills/openspec-propose new file mode 120000 index 0000000..ec9a563 --- /dev/null +++ b/.claude/skills/openspec-propose @@ -0,0 +1 @@ +../../.agents/skills/openspec-propose \ No newline at end of file diff --git a/.claude/skills/openspec-sync-specs b/.claude/skills/openspec-sync-specs new file mode 120000 index 0000000..4038d10 --- /dev/null +++ b/.claude/skills/openspec-sync-specs @@ -0,0 +1 @@ +../../.agents/skills/openspec-sync-specs \ No newline at end of file diff --git a/.claude/skills/openspec-update-change b/.claude/skills/openspec-update-change new file mode 120000 index 0000000..8f17ee6 --- /dev/null +++ b/.claude/skills/openspec-update-change @@ -0,0 +1 @@ +../../.agents/skills/openspec-update-change \ No newline at end of file diff --git a/.claude/skills/openspec-verify-change b/.claude/skills/openspec-verify-change new file mode 120000 index 0000000..cac7425 --- /dev/null +++ b/.claude/skills/openspec-verify-change @@ -0,0 +1 @@ +../../.agents/skills/openspec-verify-change \ No newline at end of file diff --git a/.claude/skills/openspec-verify-change/SKILL.md b/.claude/skills/openspec-verify-change/SKILL.md deleted file mode 100644 index c767d1e..0000000 --- a/.claude/skills/openspec-verify-change/SKILL.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -name: openspec-verify-change -description: Verify implementation matches OpenSpec change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving. Also use when the user says "openspec verify" or "opsx verify". -allowed-tools: Bash(openspec:*) -license: MIT -compatibility: Requires openspec CLI. -metadata: - author: openspec - version: "1.0" - generatedBy: "1.16.1" ---- - -Verify that an implementation matches the change artifacts (specs, tasks, design). - -**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store ` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `schemas`, `view`). Once selected, treat `--store ` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "" --json --store ""`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root. - -**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 ` 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 `), 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. - -**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** - -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 ask the user to select one - - When prompting, show all active changes returned by the list, including changes with `status: "no-tasks"`. - Include the schema used for each change if available. - Mark changes with incomplete tasks as "(In Progress)". - - Always announce: "Using change: " and how to override (e.g., `/openspec-verify-change `). - -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") - - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context - - Which artifacts exist for this change - -3. **Get planning context and load artifacts** - - ```bash - openspec instructions apply --change "" --json - ``` - - This returns the change directory, `contextFiles` (artifact ID -> array of concrete file paths), `taskTrackingConfigured`, and top-level `tasks` and `progress` aggregated from every concrete file matched by the schema's `apply.tracks` configuration that could be read. Read all available artifacts from `contextFiles`. - - Treat apply `state` and `instruction` as context, not a verification verdict. Do not implement tasks or archive the change during verification. - -4. **Initialize verification report structure** - - Create a report structure with three dimensions: - - **Completeness**: Track tasks and spec coverage - - **Correctness**: Track requirement implementation and scenario coverage - - **Coherence**: Track design adherence and pattern consistency - - Each dimension can have CRITICAL, WARNING, or SUGGESTION issues. - - Verification is advisory. Respect intentional omissions such as `skip_specs: true`, optional design documents, and schemas without task tracking. Do not require or invent optional or intentionally omitted artifacts to obtain a clean report. `Not verified` describes a limit of this report, not a new archive prerequisite. Archive retains its own checks and user-confirmation behavior. - - Mark checks the schema does not define, or artifacts the status reports as intentionally skipped, as **Not applicable**. The correctness checks of a change whose readable delta specs contain REMOVED or RENAMED requirements but no ADDED or MODIFIED requirements are also **Not applicable** (see step 6). Exclude them from skipped-check counts and the archive-readiness assessment. Reserve **Not verified** for applicable checks whose evidence is missing or unusable. - - If only task evidence is available for applicable checks, verify task completion only and mark the remaining applicable checks, including **Code Pattern Consistency**, as not verified with the reason "Only task evidence available". - - If artifacts cannot be read or contain no usable requirements, scenarios, or design decisions, mark the affected checks as not verified with the specific reason. Continue checks supported by the remaining evidence, but a partially checked input set is not a fully verified check. Missing requirements affect Spec Coverage and Requirement Implementation Mapping; missing scenarios affect Scenario Coverage; missing design decisions affect Design Adherence. - -5. **Verify Completeness** - - **Task Completion**: - - If `taskTrackingConfigured` is false, report **Task Completion** as not applicable. Do not treat empty `tasks` as missing evidence. - - Otherwise, use the top-level `tasks` and `progress` fields. They already aggregate every readable concrete file matched by `apply.tracks`, regardless of the tracked artifact's ID; do not infer tracking from a `contextFiles` key. - - If `unavailableTrackingFiles` is nonempty, mark **Task Completion** as not verified and include every unavailable path and reason. Continue using any readable task evidence, but do not infer completion from the partial `tasks` and `progress` fields. - - If `taskTrackingConfigured` is true and `tasks` is empty, mark **Task Completion** as not verified and record the reason from apply `state` and `instruction`. Nonzero totals alone do not establish evaluable task descriptions. - - Report complete vs total tasks from `progress`. - - If `progress.remaining` is greater than 0: - - Add CRITICAL issue for each listed incomplete task. If the remaining count exceeds the listed incomplete tasks, also report the incomplete checkboxes without descriptions and recommend adding descriptions and completing them. Do not infer completion from the listed tasks alone. - - Recommendation: "Complete task: " or "Mark as done if already implemented" - - **Spec Coverage**: - - If status marks the spec artifact skipped by `skip_specs: true`, or the schema defines no spec artifact (no artifact whose `artifactPaths..outputPath` is under `specs/`), report the spec-dependent checks as not applicable. - - Otherwise, `contextFiles` is keyed by artifact id, and artifact ids come from the active schema, so do not assume an id such as `specs`. The spec artifacts are those whose `artifactPaths..outputPath` is under `specs/`; read their files from `contextFiles.`. If those spec files are absent or empty, mark **Spec Coverage**, **Requirement Implementation Mapping**, and **Scenario Coverage** as not verified; do not treat any of them as clean. - - If delta specs exist in those spec files: - - Extract all requirements (marked with "### Requirement:", or listed as `FROM:`/`TO:` pairs under `## RENAMED Requirements`) and note the delta section each one sits under: `## ADDED`, `## MODIFIED`, `## REMOVED`, or `## RENAMED Requirements`. The section decides what the check looks for. - - For each ADDED or MODIFIED requirement (for MODIFIED, check the text in the delta, not the old wording): - - Search codebase for keywords related to the requirement - - Assess if implementation likely exists - - If ADDED or MODIFIED requirements appear unimplemented: - - Add CRITICAL issue: "Requirement not found: " - - Recommendation: "Implement requirement X: " - - For each REMOVED requirement, the change asks for the behavior to be gone, so invert the check: - - A REMOVED block carries only the requirement name and any `**Reason**`/`**Migration**` notes, so the delta does not describe the behavior itself. Before searching, read the baseline requirement in the main spec at `/openspec/specs//spec.md`, using the same capability path as the delta spec. Match it by exact normalized name, the rule OpenSpec uses when it applies REMOVED blocks: the heading text after `Requirement:`, trimmed, with a closing `#` run dropped only when a space or tab precedes it (so `C#` keeps its `#`), compared case-sensitively. A similarly worded heading is not a match; a rename belongs under RENAMED. Its body and scenarios are the evidence for the behavior that must be gone; never search from the requirement name alone. - - If that file holds no requirement with that exact normalized name - for example because an earlier sync already applied the removal, or a similarly named ADDED requirement replaced it - recover the baseline from the same file's history, in the planning repository rather than the current directory: `git -C "" log -p -- openspec/specs//spec.md`, or `git -C "" show ^:./openspec/specs//spec.md` once you have identified the commit that applied the removal. Empty output means the pathspec matched nothing, not that there is no baseline: `git log` reports an unmatched path as success, so re-check the path before drawing any conclusion from silence. - - A baseline that adds nothing to its own title - no body beyond a restatement of the name, no scenarios - is unusable evidence, the same as a missing one. If no usable baseline is available in either place, mark **Spec Coverage** as not verified for that entry with the reason and stop there: do not search, and never count an unsearched removal as passing. - - Search codebase for that behavior. Matches in `openspec/` artifacts or docs, or in code that serves only the Migration note or an ADDED requirement, are not evidence by themselves. Report any code path that still delivers the removed behavior, including one shared with an ADDED requirement. - - Finding no implementation is the expected result, but only once the baseline behavior was the thing you searched for. Never report a REMOVED requirement as "Requirement not found" or recommend implementing it. - - If the behavior is still present: - - Add CRITICAL issue: "Removed requirement still implemented: " - - Recommendation: "Remove the remaining implementation at :, following the requirement's Migration note if it has one" - - For each RENAMED entry (`FROM:`/`TO:`), the name changes but the behavior stays, so check the TO requirement for that unchanged behavior: - - Do not report the FROM name as missing, and do not require code symbols, identifiers, or file names to be renamed. - - If the TO name also appears under MODIFIED, its behavior is checked there against the MODIFIED text; skip it here. - - Otherwise, read the baseline requirement in the main spec at `/openspec/specs//spec.md`, using the same capability path as the delta spec: the requirement under the FROM name, or under the TO name only when the FROM name is absent because the main spec is already synced. Its body and scenarios are the evidence for the behavior the TO requirement keeps. - - Search codebase for that behavior and assess if it is still implemented. - - If it appears unimplemented: - - Add CRITICAL issue: "Renamed requirement not found: " - - Recommendation: "Restore the behavior of (renamed from ); a rename must not change behavior" - - If the baseline requirement cannot be found or read, mark **Spec Coverage** as not verified for that entry with the reason. Never count an unchecked rename as passing. - -6. **Verify Correctness** - - If the delta specs are readable and contain at least one REMOVED or RENAMED requirement but no ADDED or MODIFIED requirements (the change only removes or renames requirements), report **Requirement Implementation Mapping** and **Scenario Coverage** as **Not applicable**. The REMOVED and RENAMED checks under Spec Coverage are the evidence for such a change (each REMOVED and RENAMED entry with a usable baseline is checked there against its baseline behavior, and an entry already marked not verified there stays not verified), so do not mark these two checks as not verified. A delta spec with no parseable requirements at all is unusable evidence, not a removal-only change: mark these checks as not verified. - - **Requirement Implementation Mapping**: - - For each ADDED or MODIFIED requirement from delta specs (REMOVED entries, and RENAMED entries without a MODIFIED block, were settled under Spec Coverage): - - Search codebase for implementation evidence - - If found, note file paths and line ranges - - Assess if implementation matches requirement intent - - If divergence detected: - - Add WARNING: "Implementation may diverge from spec:
" - - Recommendation: "Review : against requirement X" - - **Scenario Coverage**: - - For each scenario under an ADDED or MODIFIED requirement in delta specs (marked with "#### Scenario:"): - - Check if conditions are handled in code - - Check if tests exist covering the scenario - - If scenario appears uncovered: - - Add WARNING: "Scenario not covered: " - - Recommendation: "Add test or implementation for scenario: " - - Skip scenarios under a REMOVED requirement; that behavior is meant to be gone. - -7. **Verify Coherence** - - **Design Adherence**: - - If the schema defines no design artifact (no artifact with id `design`, and none whose `artifactPaths..outputPath` is or ends in `design.md`), report **Design Adherence** as not applicable. - - If the design artifact's `contextFiles.` file exists: - - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:") - - Verify implementation follows those decisions - - If contradiction detected: - - Add WARNING: "Design decision not followed: " - - Recommendation: "Update implementation or revise design.md to match reality" - - Otherwise, if the design artifact's `contextFiles.` file is absent or empty: mark **Design Adherence** as not verified. With other supporting artifacts, **Code Pattern Consistency** still runs; the task-only case remains limited to task completion. - - **Code Pattern Consistency**: - - If implementation changes cannot be identified, mark **Code Pattern Consistency** as not verified and explain the missing evidence. - - Otherwise, review new code for consistency with project patterns - - Check file naming, directory structure, coding style - - If significant deviations found: - - Add SUGGESTION: "Code pattern deviation:
" - - Recommendation: "Consider following project pattern: " - -8. **Generate Verification Report** - - **Summary Scorecard**: - ```markdown - ## Verification Report: - - ### Summary - | Dimension | Status | - |--------------|------------------| - | Completeness | X/Y tasks, N reqs| - | Correctness | M/N reqs covered | - | Coherence | Followed/Issues | - ``` - - In each Status cell, report the results of checks that ran and `Not verified ()` for every skipped check. If all checks in a dimension were skipped, start the cell with `Not verified`. Never score a skipped check as passing. Treat every not verified or partially verified check as skipped in the final assessment. Count only ADDED and MODIFIED requirements in N, and report REMOVED and RENAMED requirements separately (for example, "1 removal confirmed, 1 rename verified", or "1 removal not verified (baseline unavailable)"). For a change that only removes or renames requirements, the Correctness cell reads `Not applicable (no ADDED or MODIFIED requirements)`. - - **Issues by Priority**: - - 1. **CRITICAL** (Must fix before archive): - - Incomplete tasks - - Missing requirement implementations - - Removed requirements still implemented - - Renamed requirements whose behavior is no longer implemented - - Each with specific, actionable recommendation - - 2. **WARNING** (Should fix): - - Spec/design divergences - - Missing scenario coverage - - Each with specific recommendation - - 3. **SUGGESTION** (Nice to fix): - - Pattern inconsistencies - - Minor improvements - - Each with specific recommendation - - **Final Assessment**: - - If CRITICAL issues: "X critical issue(s) found. Fix before archiving." If any check was skipped, also name every skipped check and its reason. - - If no CRITICAL issues, one or more warnings, and no checks were skipped: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)." - - If only suggestions and no checks were skipped: "No critical issues or warnings. Z suggestion(s) to consider. Ready for archive (with noted improvements)." - - If no issues and no checks were skipped: "All checks passed. Ready for archive." - - If any check was skipped and there are no CRITICAL issues: do not claim readiness. Say "No critical issues found in the checks that ran. not verified: ." Include the warning count when nonzero. - - Include the suggestion count when nonzero in every final assessment. - -**Verification Heuristics** - -- **Completeness**: Focus on objective checklist items (checkboxes, requirements list) -- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty -- **Coherence**: Look for glaring inconsistencies, don't nitpick style -- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL -- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable - -**Output Format** - -Use clear markdown with: -- Table for summary scorecard -- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION) -- Code references in format: `file.ts:123` -- Specific, actionable recommendations -- No vague suggestions like "consider reviewing" diff --git a/.kiro/skills/openspec-apply-change b/.kiro/skills/openspec-apply-change new file mode 120000 index 0000000..86591ac --- /dev/null +++ b/.kiro/skills/openspec-apply-change @@ -0,0 +1 @@ +../../.agents/skills/openspec-apply-change \ No newline at end of file diff --git a/.kiro/skills/openspec-apply-change/SKILL.md b/.kiro/skills/openspec-apply-change/SKILL.md deleted file mode 100644 index 1b17ef8..0000000 --- a/.kiro/skills/openspec-apply-change/SKILL.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -name: openspec-apply-change -description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. Also use when the user says "openspec apply", "opsx apply", or "openspec implement". -allowed-tools: Bash(openspec:*) -license: MIT -compatibility: Requires openspec CLI. -metadata: - author: openspec - version: "1.0" - generatedBy: "1.16.1" ---- - -Implement tasks from an OpenSpec change. - -**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store ` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `schemas`, `view`). Once selected, treat `--store ` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "" --json --store ""`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root. - -**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 ` 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 `), 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. - -**Input**: Optionally specify a change name (e.g., `/openspec-apply-change 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 ask the user to select one - - Always announce: "Using change: " and how to override (e.g., `/openspec-apply-change `). - -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") - - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints - - 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: - - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs) - - Progress (total, complete, remaining) - - Task list with status, source path, and source line - - Dynamic instruction based on current state - - Optional `context`: current required project instruction input from the selected root - - Optional `operationGuidance`: current advisory guidance for apply - - `missingArtifacts` (when present): required artifact ids with no output - - **Handle states:** - - If `state: "blocked"`: show the message and pause implementation. - - If `missingArtifacts` is non-empty: suggest using `/openspec-continue-change` to create them. - - Otherwise, follow the CLI instruction to create or repair the schema-configured tracking file from existing planning artifacts. Do not assume another artifact is ready or start implementation while blocked. - - If `state: "all_done"`: report that all tracked tasks are complete and suggest review or verification as appropriate before archiving - - Otherwise: proceed to implementation - - Treat `context` as a required prompt-level input. Read and consider it, and - apply relevant project facts, conventions, and constraints while implementing. - Treat `operationGuidance` as optional additive advice. Read and consider every - entry, and follow entries that are applicable and compatible with the built-in - workflow. - - Keep both fields separate from CLI-returned state, missing artifacts, tasks, - progress, `contextFiles`, and the built-in `instruction`. They are not - evidence of task completion, do not replace the built-in instruction, and do - not permit bypassing a blocked state. If context conflicts with the built-in - instruction, an explicit user choice, or a CLI-controlled value, report the - conflict and preserve the controlling value. If guidance is inapplicable or - conflicts with those controlling inputs, do not follow it and explain why. - These are prompt-level behavior contracts, not enforceable checks. - -4. **Read context files** - - Read every file path listed under `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 - - Do not copy `context` or `operationGuidance` verbatim into implementation - files or planning artifacts unless the user separately asks for that content. - -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 - - Before editing, confirm the checkbox at the returned `sourcePath` and `line` still matches the task description; if it does not, rerun the apply instructions and use the refreshed location - - Mark the task complete at its returned `sourcePath` and `line`: `- [ ]` → `- [x]` - - Rerun the apply instructions and confirm that task is now done and progress changed - - Continue to next task - - **Pause if:** - - Task is unclear → ask for clarification - - Implementation reveals a design issue → suggest updating artifacts - - A task needs work beyond what the spec and tasks describe, or you are tempted to drop, narrow, defer, or accept exceptions to specified behavior to make it fit → surface the added scope and ask; do not absorb it silently - - 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: report that tracked tasks are complete and suggest review or verification as appropriate before archiving - - 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 tracked tasks are complete. Review or verify the change as appropriate -before archiving. You can archive this change with `/openspec-archive-change`. -``` - -**Output On Pause (Issue Encountered)** - -``` -## Implementation Paused - -**Change:** -**Schema:** -**Progress:** 4/7 tasks complete - -### Issue Encountered - - -**Options:** -1.