From ba82cac4a3f10bbb845add7bb5c1bbc1b0789a93 Mon Sep 17 00:00:00 2001 From: John Lambert Date: Wed, 6 May 2026 15:35:35 -0400 Subject: [PATCH] Update openspec --- .github/prompts/opsx-apply.prompt.md | 4 +- .github/prompts/opsx-archive.prompt.md | 4 +- .github/prompts/opsx-bulk-archive.prompt.md | 4 +- .github/prompts/opsx-explore.prompt.md | 31 ++++---- .github/prompts/opsx-ff.prompt.md | 5 +- .github/prompts/opsx-onboard.prompt.md | 77 ++++++++++++------ .github/prompts/opsx-verify.prompt.md | 6 +- .github/skills/openspec-apply-change/SKILL.md | 6 +- .../skills/openspec-archive-change/SKILL.md | 4 +- .../openspec-bulk-archive-change/SKILL.md | 6 +- .../skills/openspec-continue-change/SKILL.md | 2 +- .github/skills/openspec-explore/SKILL.md | 38 +++++---- .github/skills/openspec-ff-change/SKILL.md | 2 +- .github/skills/openspec-new-change/SKILL.md | 2 +- .github/skills/openspec-onboard/SKILL.md | 79 ++++++++++++------- .github/skills/openspec-sync-specs/SKILL.md | 2 +- .../skills/openspec-verify-change/SKILL.md | 8 +- openspec/AGENTS.md | 29 ------- 18 files changed, 165 insertions(+), 144 deletions(-) delete mode 100644 openspec/AGENTS.md diff --git a/.github/prompts/opsx-apply.prompt.md b/.github/prompts/opsx-apply.prompt.md index 494e10e990..e23ec64d14 100644 --- a/.github/prompts/opsx-apply.prompt.md +++ b/.github/prompts/opsx-apply.prompt.md @@ -32,7 +32,7 @@ Implement tasks from an OpenSpec change. ``` This returns: - - Context file paths (varies by schema) + - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema) - Progress (total, complete, remaining) - Task list with status - Dynamic instruction based on current state @@ -44,7 +44,7 @@ Implement tasks from an OpenSpec change. 4. **Read context files** - Read the files listed in `contextFiles` from the apply instructions output. + 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 diff --git a/.github/prompts/opsx-archive.prompt.md b/.github/prompts/opsx-archive.prompt.md index 4e2ee18914..1163776da4 100644 --- a/.github/prompts/opsx-archive.prompt.md +++ b/.github/prompts/opsx-archive.prompt.md @@ -56,7 +56,7 @@ Archive a completed change in the experimental workflow. - If changes needed: "Sync now (recommended)", "Archive without syncing" - If already synced: "Archive now", "Sync anyway", "Cancel" - If user chooses sync, execute `/opsx:sync` logic. Proceed to archive regardless of choice. + If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change ''. Delta spec analysis: "). Proceed to archive regardless of choice. 5. **Perform the archive** @@ -150,5 +150,5 @@ Target archive directory already exists. - Don't block archive on warnings - just inform and confirm - Preserve .openspec.yaml when moving to archive (it moves with the directory) - Show clear summary of what happened -- If sync is requested, use /opsx:sync approach (agent-driven) +- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven) - If delta specs exist, always run the sync assessment and show the combined summary before prompting diff --git a/.github/prompts/opsx-bulk-archive.prompt.md b/.github/prompts/opsx-bulk-archive.prompt.md index f8e773fed0..0101c6b0df 100644 --- a/.github/prompts/opsx-bulk-archive.prompt.md +++ b/.github/prompts/opsx-bulk-archive.prompt.md @@ -77,7 +77,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig Display a table summarizing all changes: ``` - | Change | Artifacts | Tasks | Specs | Conflicts | Status | + | Change | Artifacts | Tasks | Specs | Conflicts | Status | |---------------------|-----------|-------|---------|-----------|--------| | schema-management | Done | 5/5 | 2 delta | None | Ready | | project-config | Done | 3/3 | 1 delta | None | Ready | @@ -222,7 +222,7 @@ Failed K changes: ``` ## No Changes to Archive -No active changes found. Use `/opsx:new` to create a new change. +No active changes found. Create a new change to get started. ``` **Guardrails** diff --git a/.github/prompts/opsx-explore.prompt.md b/.github/prompts/opsx-explore.prompt.md index fd588622a3..3b674ebb57 100644 --- a/.github/prompts/opsx-explore.prompt.md +++ b/.github/prompts/opsx-explore.prompt.md @@ -4,7 +4,7 @@ description: Enter explore mode - think through ideas, investigate problems, cla Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes. -**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. +**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore. @@ -56,10 +56,10 @@ Depending on what the user brings, you might: │ Use ASCII diagrams liberally │ ├─────────────────────────────────────────┤ │ │ -│ ┌────────┐ ┌────────┐ │ -│ │ State │────────▶│ State │ │ -│ │ A │ │ B │ │ -│ └────────┘ └────────┘ │ +│ ┌────────┐ ┌────────┐ │ +│ │ State │────────▶│ State │ │ +│ │ A │ │ B │ │ +│ └────────┘ └────────┘ │ │ │ │ System diagrams, state machines, │ │ data flows, architecture sketches, │ @@ -97,8 +97,7 @@ If the user mentioned a specific change name, read its artifacts for context. Think freely. When insights crystallize, you might offer: -- "This feels solid enough to start a change. Want me to create one?" - → Can transition to `/opsx:new` or `/opsx:ff` +- "This feels solid enough to start a change. Want me to create a proposal?" - Or keep exploring - no pressure to formalize ### When a change exists @@ -117,14 +116,14 @@ If the user mentions a change or you detect one is relevant: 3. **Offer to capture when decisions are made** - | Insight Type | Where to Capture | - |--------------|------------------| - | New requirement discovered | `specs//spec.md` | - | Requirement changed | `specs//spec.md` | - | Design decision made | `design.md` | - | Scope changed | `proposal.md` | - | New work identified | `tasks.md` | - | Assumption invalidated | Relevant artifact | + | Insight Type | Where to Capture | + |----------------------------|--------------------------------| + | New requirement discovered | `specs//spec.md` | + | Requirement changed | `specs//spec.md` | + | Design decision made | `design.md` | + | Scope changed | `proposal.md` | + | New work identified | `tasks.md` | + | Assumption invalidated | Relevant artifact | Example offers: - "That's a design decision. Capture it in design.md?" @@ -150,7 +149,7 @@ If the user mentions a change or you detect one is relevant: There's no required ending. Discovery might: -- **Flow into action**: "Ready to start? `/opsx:new` or `/opsx:ff`" +- **Flow into a proposal**: "Ready to start? I can create a change proposal." - **Result in artifact updates**: "Updated design.md with these decisions" - **Just provide clarity**: User has what they need, moves on - **Continue later**: "We can pick this up anytime" diff --git a/.github/prompts/opsx-ff.prompt.md b/.github/prompts/opsx-ff.prompt.md index 6b3dc00c77..06cea28020 100644 --- a/.github/prompts/opsx-ff.prompt.md +++ b/.github/prompts/opsx-ff.prompt.md @@ -81,7 +81,10 @@ After completing all artifacts, summarize: - Follow the `instruction` field from `openspec instructions` for each artifact type - The schema defines what each artifact should contain - follow it - Read dependency artifacts for context before creating new ones -- Use the `template` as a starting point, filling in based on context +- Use `template` as the structure for your output file - fill in its sections +- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file + - Do NOT copy ``, ``, `` blocks into the artifact + - These guide what you write, but should never appear in the output **Guardrails** - Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`) diff --git a/.github/prompts/opsx-onboard.prompt.md b/.github/prompts/opsx-onboard.prompt.md index 1414f1e1a7..d7b0614e86 100644 --- a/.github/prompts/opsx-onboard.prompt.md +++ b/.github/prompts/opsx-onboard.prompt.md @@ -8,16 +8,19 @@ Guide the user through their first complete OpenSpec workflow cycle. This is a t ## Preflight -Before starting, check if OpenSpec is initialized: +Before starting, check if the OpenSpec CLI is installed: ```bash -openspec status --json 2>&1 || echo "NOT_INITIALIZED" +# Unix/macOS +openspec --version 2>&1 || echo "CLI_NOT_INSTALLED" +# Windows (PowerShell) +# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" } ``` -**If not initialized:** -> OpenSpec isn't set up in this project yet. Run `openspec init` first, then come back to `/opsx:onboard`. +**If CLI not installed:** +> OpenSpec CLI is not installed. Install it first, then come back to `/opsx:onboard`. -Stop here if not initialized. +Stop here if not installed. --- @@ -60,7 +63,10 @@ Scan the codebase for small improvement opportunities. Look for: Also check recent git activity: ```bash +# Unix/macOS git log --oneline -10 2>/dev/null || echo "No git history" +# Windows (PowerShell) +# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" } ``` ### Present Suggestions @@ -255,7 +261,10 @@ For a small task like this, we might only need one spec file. **DO:** Create the spec file: ```bash +# Unix/macOS mkdir -p openspec/changes//specs/ +# Windows (PowerShell) +# New-Item -ItemType Directory -Force -Path "openspec/changes//specs/" ``` Draft the spec content: @@ -450,21 +459,29 @@ This same rhythm works for any size change—a small fix or a major feature. ## Command Reference -| Command | What it does | -|---------|--------------| -| `/opsx:explore` | Think through problems before/during work | -| `/opsx:new` | Start a new change, step through artifacts | -| `/opsx:ff` | Fast-forward: create all artifacts at once | -| `/opsx:continue` | Continue working on an existing change | -| `/opsx:apply` | Implement tasks from a change | -| `/opsx:verify` | Verify implementation matches artifacts | -| `/opsx:archive` | Archive a completed change | +**Core workflow:** + + | Command | What it does | + |-------------------|--------------------------------------------| + | `/opsx:propose` | Create a change and generate all artifacts | + | `/opsx:explore` | Think through problems before/during work | + | `/opsx:apply` | Implement tasks from a change | + | `/opsx:archive` | Archive a completed change | + +**Additional commands:** + + | Command | What it does | + |--------------------|----------------------------------------------------------| + | `/opsx:new` | Start a new change, step through artifacts one at a time | + | `/opsx:continue` | Continue working on an existing change | + | `/opsx:ff` | Fast-forward: create all artifacts at once | + | `/opsx:verify` | Verify implementation matches artifacts | --- ## What's Next? -Try `/opsx:new` or `/opsx:ff` on something you actually want to build. You've got the rhythm now! +Try `/opsx:propose` on something you actually want to build. You've got the rhythm now! ``` --- @@ -494,17 +511,25 @@ If the user says they just want to see the commands or skip the tutorial: ``` ## OpenSpec Quick Reference -| Command | What it does | -|---------|--------------| -| `/opsx:explore` | Think through problems (no code changes) | -| `/opsx:new ` | Start a new change, step by step | -| `/opsx:ff ` | Fast-forward: all artifacts at once | -| `/opsx:continue ` | Continue an existing change | -| `/opsx:apply ` | Implement tasks | -| `/opsx:verify ` | Verify implementation | -| `/opsx:archive ` | Archive when done | - -Try `/opsx:new` to start your first change, or `/opsx:ff` if you want to move fast. +**Core workflow:** + + | Command | What it does | + |--------------------------|--------------------------------------------| + | `/opsx:propose ` | Create a change and generate all artifacts | + | `/opsx:explore` | Think through problems (no code changes) | + | `/opsx:apply ` | Implement tasks | + | `/opsx:archive ` | Archive when done | + +**Additional commands:** + + | Command | What it does | + |---------------------------|-------------------------------------| + | `/opsx:new ` | Start a new change, step by step | + | `/opsx:continue ` | Continue an existing change | + | `/opsx:ff ` | Fast-forward: all artifacts at once | + | `/opsx:verify ` | Verify implementation | + +Try `/opsx:propose` to start your first change. ``` Exit gracefully. diff --git a/.github/prompts/opsx-verify.prompt.md b/.github/prompts/opsx-verify.prompt.md index 811187342e..28944894ea 100644 --- a/.github/prompts/opsx-verify.prompt.md +++ b/.github/prompts/opsx-verify.prompt.md @@ -32,7 +32,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design openspec instructions apply --change "" --json ``` - This returns the change directory and context files. Read all available artifacts from `contextFiles`. + This returns the change directory and `contextFiles` (artifact ID -> array of concrete file paths). Read all available artifacts from `contextFiles`. 4. **Initialize verification report structure** @@ -46,7 +46,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design 5. **Verify Completeness** **Task Completion**: - - If tasks.md exists in contextFiles, read it + - If `contextFiles.tasks` exists, read every file path in it - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete) - Count complete vs total tasks - If incomplete tasks exist: @@ -85,7 +85,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design 7. **Verify Coherence** **Design Adherence**: - - If design.md exists in contextFiles: + - If `contextFiles.design` exists: - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:") - Verify implementation follows those decisions - If contradiction detected: diff --git a/.github/skills/openspec-apply-change/SKILL.md b/.github/skills/openspec-apply-change/SKILL.md index 4d9b8d127c..70fbdb8569 100644 --- a/.github/skills/openspec-apply-change/SKILL.md +++ b/.github/skills/openspec-apply-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.1.0" + generatedBy: "1.3.1" --- Implement tasks from an OpenSpec change. @@ -39,7 +39,7 @@ Implement tasks from an OpenSpec change. ``` This returns: - - Context file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs) + - `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 - Dynamic instruction based on current state @@ -51,7 +51,7 @@ Implement tasks from an OpenSpec change. 4. **Read context files** - Read the files listed in `contextFiles` from the apply instructions output. + 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 diff --git a/.github/skills/openspec-archive-change/SKILL.md b/.github/skills/openspec-archive-change/SKILL.md index d17be3b1b0..12e2f70e9c 100644 --- a/.github/skills/openspec-archive-change/SKILL.md +++ b/.github/skills/openspec-archive-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.1.0" + generatedBy: "1.3.1" --- Archive a completed change in the experimental workflow. @@ -63,7 +63,7 @@ Archive a completed change in the experimental workflow. - If changes needed: "Sync now (recommended)", "Archive without syncing" - If already synced: "Archive now", "Sync anyway", "Cancel" - If user chooses sync, execute /opsx:sync logic (use the openspec-sync-specs skill). Proceed to archive regardless of choice. + If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change ''. Delta spec analysis: "). Proceed to archive regardless of choice. 5. **Perform the archive** diff --git a/.github/skills/openspec-bulk-archive-change/SKILL.md b/.github/skills/openspec-bulk-archive-change/SKILL.md index 781d9770b6..5be81af2e7 100644 --- a/.github/skills/openspec-bulk-archive-change/SKILL.md +++ b/.github/skills/openspec-bulk-archive-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.1.0" + generatedBy: "1.3.1" --- Archive multiple completed changes in a single operation. @@ -84,7 +84,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig Display a table summarizing all changes: ``` - | Change | Artifacts | Tasks | Specs | Conflicts | Status | + | Change | Artifacts | Tasks | Specs | Conflicts | Status | |---------------------|-----------|-------|---------|-----------|--------| | schema-management | Done | 5/5 | 2 delta | None | Ready | | project-config | Done | 3/3 | 1 delta | None | Ready | @@ -229,7 +229,7 @@ Failed K changes: ``` ## No Changes to Archive -No active changes found. Use `/opsx:new` to create a new change. +No active changes found. Create a new change to get started. ``` **Guardrails** diff --git a/.github/skills/openspec-continue-change/SKILL.md b/.github/skills/openspec-continue-change/SKILL.md index bf63f20b2e..4f2c3dcf4b 100644 --- a/.github/skills/openspec-continue-change/SKILL.md +++ b/.github/skills/openspec-continue-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.1.0" + generatedBy: "1.3.1" --- Continue working on a change by creating the next artifact. diff --git a/.github/skills/openspec-explore/SKILL.md b/.github/skills/openspec-explore/SKILL.md index 2f63fb9483..6858d3f693 100644 --- a/.github/skills/openspec-explore/SKILL.md +++ b/.github/skills/openspec-explore/SKILL.md @@ -6,12 +6,12 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.1.0" + generatedBy: "1.3.1" --- Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes. -**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. +**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore. @@ -56,10 +56,10 @@ Depending on what the user brings, you might: │ Use ASCII diagrams liberally │ ├─────────────────────────────────────────┤ │ │ -│ ┌────────┐ ┌────────┐ │ -│ │ State │────────▶│ State │ │ -│ │ A │ │ B │ │ -│ └────────┘ └────────┘ │ +│ ┌────────┐ ┌────────┐ │ +│ │ State │────────▶│ State │ │ +│ │ A │ │ B │ │ +│ └────────┘ └────────┘ │ │ │ │ System diagrams, state machines, │ │ data flows, architecture sketches, │ @@ -95,8 +95,7 @@ This tells you: Think freely. When insights crystallize, you might offer: -- "This feels solid enough to start a change. Want me to create one?" - → Can transition to `/opsx:new` or `/opsx:ff` +- "This feels solid enough to start a change. Want me to create a proposal?" - Or keep exploring - no pressure to formalize ### When a change exists @@ -115,14 +114,14 @@ If the user mentions a change or you detect one is relevant: 3. **Offer to capture when decisions are made** - | Insight Type | Where to Capture | - |--------------|------------------| - | New requirement discovered | `specs//spec.md` | - | Requirement changed | `specs//spec.md` | - | Design decision made | `design.md` | - | Scope changed | `proposal.md` | - | New work identified | `tasks.md` | - | Assumption invalidated | Relevant artifact | + | Insight Type | Where to Capture | + |----------------------------|--------------------------------| + | New requirement discovered | `specs//spec.md` | + | Requirement changed | `specs//spec.md` | + | Design decision made | `design.md` | + | Scope changed | `proposal.md` | + | New work identified | `tasks.md` | + | Assumption invalidated | Relevant artifact | Example offers: - "That's a design decision. Capture it in design.md?" @@ -228,7 +227,7 @@ User: A CLI tool that tracks local dev environments You: That changes everything. ┌─────────────────────────────────────────────────┐ - │ CLI TOOL DATA STORAGE │ + │ CLI TOOL DATA STORAGE │ └─────────────────────────────────────────────────┘ Key constraints: @@ -252,7 +251,7 @@ You: That changes everything. There's no required ending. Discovery might: -- **Flow into action**: "Ready to start? /opsx:new or /opsx:ff" +- **Flow into a proposal**: "Ready to start? I can create a change proposal." - **Result in artifact updates**: "Updated design.md with these decisions" - **Just provide clarity**: User has what they need, moves on - **Continue later**: "We can pick this up anytime" @@ -269,8 +268,7 @@ When it feels like things are crystallizing, you might summarize: **Open questions**: [if any remain] **Next steps** (if ready): -- Create a change: /opsx:new -- Fast-forward to tasks: /opsx:ff +- Create a change proposal - Keep exploring: just keep talking ``` diff --git a/.github/skills/openspec-ff-change/SKILL.md b/.github/skills/openspec-ff-change/SKILL.md index 8b2dbbe48f..43f2632ea4 100644 --- a/.github/skills/openspec-ff-change/SKILL.md +++ b/.github/skills/openspec-ff-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.1.0" + generatedBy: "1.3.1" --- Fast-forward through artifact creation - generate everything needed to start implementation in one go. diff --git a/.github/skills/openspec-new-change/SKILL.md b/.github/skills/openspec-new-change/SKILL.md index 195a6cdcf5..1af41c7d73 100644 --- a/.github/skills/openspec-new-change/SKILL.md +++ b/.github/skills/openspec-new-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.1.0" + generatedBy: "1.3.1" --- Start a new change using the experimental artifact-driven approach. diff --git a/.github/skills/openspec-onboard/SKILL.md b/.github/skills/openspec-onboard/SKILL.md index 0f018dbdfd..b6c734de40 100644 --- a/.github/skills/openspec-onboard/SKILL.md +++ b/.github/skills/openspec-onboard/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.1.0" + generatedBy: "1.3.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. @@ -15,16 +15,19 @@ Guide the user through their first complete OpenSpec workflow cycle. This is a t ## Preflight -Before starting, check if OpenSpec is initialized: +Before starting, check if the OpenSpec CLI is installed: ```bash -openspec status --json 2>&1 || echo "NOT_INITIALIZED" +# Unix/macOS +openspec --version 2>&1 || echo "CLI_NOT_INSTALLED" +# Windows (PowerShell) +# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" } ``` -**If not initialized:** -> OpenSpec isn't set up in this project yet. Run `openspec init` first, then come back to `/opsx:onboard`. +**If CLI not installed:** +> OpenSpec CLI is not installed. Install it first, then come back to `/opsx:onboard`. -Stop here if not initialized. +Stop here if not installed. --- @@ -67,7 +70,10 @@ Scan the codebase for small improvement opportunities. Look for: Also check recent git activity: ```bash +# Unix/macOS git log --oneline -10 2>/dev/null || echo "No git history" +# Windows (PowerShell) +# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" } ``` ### Present Suggestions @@ -262,7 +268,10 @@ For a small task like this, we might only need one spec file. **DO:** Create the spec file: ```bash +# Unix/macOS mkdir -p openspec/changes//specs/ +# Windows (PowerShell) +# New-Item -ItemType Directory -Force -Path "openspec/changes//specs/" ``` Draft the spec content: @@ -457,21 +466,29 @@ This same rhythm works for any size change—a small fix or a major feature. ## Command Reference -| Command | What it does | -|---------|--------------| -| `/opsx:explore` | Think through problems before/during work | -| `/opsx:new` | Start a new change, step through artifacts | -| `/opsx:ff` | Fast-forward: create all artifacts at once | -| `/opsx:continue` | Continue working on an existing change | -| `/opsx:apply` | Implement tasks from a change | -| `/opsx:verify` | Verify implementation matches artifacts | -| `/opsx:archive` | Archive a completed change | +**Core workflow:** + + | Command | What it does | + |-------------------|--------------------------------------------| + | `/opsx:propose` | Create a change and generate all artifacts | + | `/opsx:explore` | Think through problems before/during work | + | `/opsx:apply` | Implement tasks from a change | + | `/opsx:archive` | Archive a completed change | + +**Additional commands:** + + | Command | What it does | + |--------------------|----------------------------------------------------------| + | `/opsx:new` | Start a new change, step through artifacts one at a time | + | `/opsx:continue` | Continue working on an existing change | + | `/opsx:ff` | Fast-forward: create all artifacts at once | + | `/opsx:verify` | Verify implementation matches artifacts | --- ## What's Next? -Try `/opsx:new` or `/opsx:ff` on something you actually want to build. You've got the rhythm now! +Try `/opsx:propose` on something you actually want to build. You've got the rhythm now! ``` --- @@ -501,17 +518,25 @@ If the user says they just want to see the commands or skip the tutorial: ``` ## OpenSpec Quick Reference -| Command | What it does | -|---------|--------------| -| `/opsx:explore` | Think through problems (no code changes) | -| `/opsx:new ` | Start a new change, step by step | -| `/opsx:ff ` | Fast-forward: all artifacts at once | -| `/opsx:continue ` | Continue an existing change | -| `/opsx:apply ` | Implement tasks | -| `/opsx:verify ` | Verify implementation | -| `/opsx:archive ` | Archive when done | - -Try `/opsx:new` to start your first change, or `/opsx:ff` if you want to move fast. +**Core workflow:** + + | Command | What it does | + |--------------------------|--------------------------------------------| + | `/opsx:propose ` | Create a change and generate all artifacts | + | `/opsx:explore` | Think through problems (no code changes) | + | `/opsx:apply ` | Implement tasks | + | `/opsx:archive ` | Archive when done | + +**Additional commands:** + + | Command | What it does | + |---------------------------|-------------------------------------| + | `/opsx:new ` | Start a new change, step by step | + | `/opsx:continue ` | Continue an existing change | + | `/opsx:ff ` | Fast-forward: all artifacts at once | + | `/opsx:verify ` | Verify implementation | + +Try `/opsx:propose` to start your first change. ``` Exit gracefully. diff --git a/.github/skills/openspec-sync-specs/SKILL.md b/.github/skills/openspec-sync-specs/SKILL.md index 7e8dff16e8..f2ed9ec7bb 100644 --- a/.github/skills/openspec-sync-specs/SKILL.md +++ b/.github/skills/openspec-sync-specs/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.1.0" + generatedBy: "1.3.1" --- Sync delta specs from a change to main specs. diff --git a/.github/skills/openspec-verify-change/SKILL.md b/.github/skills/openspec-verify-change/SKILL.md index 77a0c71217..00d0532c9f 100644 --- a/.github/skills/openspec-verify-change/SKILL.md +++ b/.github/skills/openspec-verify-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.1.0" + generatedBy: "1.3.1" --- Verify that an implementation matches the change artifacts (specs, tasks, design). @@ -39,7 +39,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design openspec instructions apply --change "" --json ``` - This returns the change directory and context files. Read all available artifacts from `contextFiles`. + This returns the change directory and `contextFiles` (artifact ID -> array of concrete file paths). Read all available artifacts from `contextFiles`. 4. **Initialize verification report structure** @@ -53,7 +53,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design 5. **Verify Completeness** **Task Completion**: - - If tasks.md exists in contextFiles, read it + - If `contextFiles.tasks` exists, read every file path in it - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete) - Count complete vs total tasks - If incomplete tasks exist: @@ -92,7 +92,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design 7. **Verify Coherence** **Design Adherence**: - - If design.md exists in contextFiles: + - If `contextFiles.design` exists: - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:") - Verify implementation follows those decisions - If contradiction detected: diff --git a/openspec/AGENTS.md b/openspec/AGENTS.md deleted file mode 100644 index 902a1c800b..0000000000 --- a/openspec/AGENTS.md +++ /dev/null @@ -1,29 +0,0 @@ -# OpenSpec Instructions - -These instructions are for AI assistants working in the FieldWorks repository. - - -Always open `@/openspec/AGENTS.md` when the request: -- Mentions planning or proposals (words like proposal, spec, change, plan) -- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work -- Sounds ambiguous and you need the authoritative spec before coding - -Use `@/openspec/AGENTS.md` to learn: -- How to create and apply change proposals -- Spec format and conventions -- Project structure and guidelines - -Keep this managed block so 'openspec update' can refresh the instructions. - - -## Quick workflow - -1. For new capability or architecture changes, create an OpenSpec change first. -2. Keep specs concise, testable, and implementation-agnostic. -3. Track execution in your issue/PR workflow and keep OpenSpec tasks aligned. -4. Archive the change after implementation and verification complete. - -## References - -- [OpenSpec Index](specs/README.md) -- [Root AGENTS guidance](../AGENTS.md)