diff --git a/.agents/skills/impeccable/reference/audit.md b/.agents/skills/impeccable/reference/audit.md index ddbda285..8fd248ad 100644 --- a/.agents/skills/impeccable/reference/audit.md +++ b/.agents/skills/impeccable/reference/audit.md @@ -130,4 +130,3 @@ After presenting the summary, tell the user: - Skip positive findings (celebrate what works) - Forget to prioritize (everything can't be P0) - Report false positives without verification - diff --git a/.agents/skills/impeccable/reference/document.md b/.agents/skills/impeccable/reference/document.md index abb0a675..8eea0e00 100644 --- a/.agents/skills/impeccable/reference/document.md +++ b/.agents/skills/impeccable/reference/document.md @@ -354,7 +354,7 @@ Group into one `AskUserQuestion` interaction. Options must be concrete. - Committed: one saturated color carries 30–60% of the surface - Full palette: 3–4 named color roles, each deliberate - Drenched: the surface IS the color - + Then: one hue family or anchor reference ("deep teal", "mustard", "Klim #ff4500 orange"). 2. **Typography direction.** Pick one (specific fonts come later): diff --git a/.agents/skills/impeccable/reference/extract.md b/.agents/skills/impeccable/reference/extract.md index 154b9d3a..e3528403 100644 --- a/.agents/skills/impeccable/reference/extract.md +++ b/.agents/skills/impeccable/reference/extract.md @@ -66,4 +66,3 @@ Update design system documentation: - Skip proper TypeScript types or prop documentation - Create tokens for every single value (tokens should have semantic meaning) - Extract things that differ in intent (two buttons that look similar but serve different purposes should stay separate) - diff --git a/.agents/skills/impeccable/reference/harden.md b/.agents/skills/impeccable/reference/harden.md index 5f816195..d96eae89 100644 --- a/.agents/skills/impeccable/reference/harden.md +++ b/.agents/skills/impeccable/reference/harden.md @@ -121,9 +121,9 @@ border-inline-end: 1px solid; /* Not border-right */ new Intl.DateTimeFormat('en-US').format(date); // 1/15/2024 new Intl.DateTimeFormat('de-DE').format(date); // 15.1.2024 -new Intl.NumberFormat('en-US', { - style: 'currency', - currency: 'USD' +new Intl.NumberFormat('en-US', { + style: 'currency', + currency: 'USD' }).format(1234.56); // $1,234.56 ``` @@ -235,7 +235,7 @@ t('items', { count }) // Handles complex plural rules **Constraint handling**: ```html -/specs/`. If none exist, proceed without sync prompt. + Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt. **If delta specs exist:** - Compare each delta spec with its corresponding main spec at `openspec/specs//spec.md` @@ -63,19 +66,19 @@ Archive a completed change in the experimental workflow. 5. **Perform the archive** - Create the archive directory if it doesn't exist: + Create an `archive` directory under `planningHome.changesDir` if it doesn't exist: ```bash - mkdir -p openspec/changes/archive + mkdir -p "/archive" ``` Generate target name using current date: `YYYY-MM-DD-` **Check if target already exists:** - If yes: Fail with error, suggest renaming existing archive or using different date - - If no: Move the change directory to archive + - If no: Move `changeRoot` to the archive directory ```bash - mv openspec/changes/ openspec/changes/archive/YYYY-MM-DD- + mv "" "/archive/YYYY-MM-DD-" ``` 6. **Display summary** @@ -94,7 +97,7 @@ Archive a completed change in the experimental workflow. **Change:** **Schema:** -**Archived to:** openspec/changes/archive/YYYY-MM-DD-/ +**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-/ **Specs:** ✓ Synced to main specs All artifacts complete. All tasks complete. @@ -107,7 +110,7 @@ All artifacts complete. All tasks complete. **Change:** **Schema:** -**Archived to:** openspec/changes/archive/YYYY-MM-DD-/ +**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-/ **Specs:** No delta specs All artifacts complete. All tasks complete. @@ -120,7 +123,7 @@ All artifacts complete. All tasks complete. **Change:** **Schema:** -**Archived to:** openspec/changes/archive/YYYY-MM-DD-/ +**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-/ **Specs:** Sync skipped (user chose to skip) **Warnings:** @@ -137,7 +140,7 @@ Review the archive if this was not intentional. ## Archive Failed **Change:** -**Target:** openspec/changes/archive/YYYY-MM-DD-/ +**Target:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-/ Target archive directory already exists. diff --git a/.claude/commands/opsx/bulk-archive.md b/.claude/commands/opsx/bulk-archive.md index 1284d3d6..cae426de 100644 --- a/.claude/commands/opsx/bulk-archive.md +++ b/.claude/commands/opsx/bulk-archive.md @@ -33,14 +33,16 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig For each selected change, collect: a. **Artifact status** - Run `openspec status --change "" --json` - - Parse `schemaName` and `artifacts` list + - Parse `schemaName`, `artifacts`, `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext` - Note which artifacts are `done` vs other states - b. **Task completion** - Read `openspec/changes//tasks.md` + If any selected change reports `actionContext.mode: "workspace-planning"`, explain that workspace bulk archive is not supported in this slice and STOP before syncing specs or moving changes. Do not fall back to repo-local paths or edit linked repos. + + b. **Task completion** - Read `artifactPaths.tasks.existingOutputPaths` from status JSON - Count `- [ ]` (incomplete) vs `- [x]` (complete) - If no tasks file exists, note as "No tasks" - c. **Delta specs** - Check `openspec/changes//specs/` directory + c. **Delta specs** - Check `artifactPaths.specs.existingOutputPaths` from status JSON - List which capability specs exist - For each, extract requirement names (lines matching `### Requirement: `) @@ -123,8 +125,8 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig b. **Perform the archive**: ```bash - mkdir -p openspec/changes/archive - mv openspec/changes/ openspec/changes/archive/YYYY-MM-DD- + mkdir -p "/archive" + mv "" "/archive/YYYY-MM-DD-" ``` c. **Track outcome** for each change: diff --git a/.claude/commands/opsx/continue.md b/.claude/commands/opsx/continue.md index af255c6f..127cba8b 100644 --- a/.claude/commands/opsx/continue.md +++ b/.claude/commands/opsx/continue.md @@ -33,6 +33,7 @@ Continue working on a change by creating the next artifact. - `schemaName`: The workflow schema being used (e.g., "spec-driven") - `artifacts`: Array of artifacts with their status ("done", "ready", "blocked") - `isComplete`: Boolean indicating if all artifacts are complete + - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths. 3. **Act based on status**: @@ -57,13 +58,13 @@ Continue working on a change by creating the next artifact. - `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 - - `outputPath`: Where to write the artifact + - `resolvedOutputPath`: Resolved path or pattern to write the artifact - `dependencies`: Completed artifacts to read for context - **Create the artifact file**: - Read any completed dependency files for context - 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 to the output path specified in instructions + - Write to the `resolvedOutputPath` specified in instructions. If it is a glob pattern, choose the concrete file path using the schema instruction and workspace planning context - Show what was created and what's now unlocked - STOP after creating ONE artifact diff --git a/.claude/commands/opsx/explore.md b/.claude/commands/opsx/explore.md index 1757907e..8655619f 100644 --- a/.claude/commands/opsx/explore.md +++ b/.claude/commands/opsx/explore.md @@ -107,11 +107,10 @@ Think freely. When insights crystallize, you might offer: If the user mentions a change or you detect one is relevant: -1. **Read existing artifacts for context** - - `openspec/changes//proposal.md` - - `openspec/changes//design.md` - - `openspec/changes//tasks.md` - - etc. +1. **Resolve and read existing artifacts for context** + - Run `openspec status --change "" --json`. + - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON. + - Read existing files from `artifactPaths..existingOutputPaths`. 2. **Reference them naturally in conversation** - "Your design mentions using Redis, but we just realized SQLite fits better..." diff --git a/.claude/commands/opsx/ff.md b/.claude/commands/opsx/ff.md index 69f749c9..d086a751 100644 --- a/.claude/commands/opsx/ff.md +++ b/.claude/commands/opsx/ff.md @@ -24,7 +24,7 @@ Fast-forward through artifact creation - generate everything needed to start imp ```bash openspec new change "" ``` - This creates a scaffolded change at `openspec/changes//`. + This creates a scaffolded change in the planning home resolved by the CLI. 3. **Get the artifact build order** ```bash @@ -33,6 +33,7 @@ Fast-forward through artifact creation - generate everything needed to start imp Parse the JSON to get: - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`) - `artifacts`: list of all artifacts with their status and dependencies + - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths. 4. **Create artifacts in sequence until apply-ready** @@ -50,10 +51,10 @@ Fast-forward through artifact creation - generate everything needed to start imp - `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 for this artifact type - - `outputPath`: Where to write the artifact + - `resolvedOutputPath`: Resolved path or pattern to write the artifact - `dependencies`: Completed artifacts to read for context - Read any completed dependency files for context - - Create the artifact file using `template` as the structure + - Create the artifact file using `template` as the structure and write it to `resolvedOutputPath` - Apply `context` and `rules` as constraints - but do NOT copy them into the file - Show brief progress: "✓ Created " diff --git a/.claude/commands/opsx/new.md b/.claude/commands/opsx/new.md index ef26cfa8..3cf5554d 100644 --- a/.claude/commands/opsx/new.md +++ b/.claude/commands/opsx/new.md @@ -35,13 +35,13 @@ Start a new change using the experimental artifact-driven approach. openspec new change "" ``` Add `--schema ` only if the user requested a specific workflow. - This creates a scaffolded change at `openspec/changes//` with the selected schema. + This creates a scaffolded change in the planning home resolved by the CLI. 4. **Show the artifact status** ```bash - openspec status --change "" + openspec status --change "" --json ``` - This shows which artifacts need to be created and which are ready (dependencies satisfied). + Use the returned `planningHome`, `changeRoot`, `artifactPaths`, and `nextSteps` instead of assuming repo-local paths. 5. **Get instructions for the first artifact** The first artifact depends on the schema. Check the status output to find the first artifact with status "ready". diff --git a/.claude/commands/opsx/onboard.md b/.claude/commands/opsx/onboard.md index 10a7eb6c..d2d7c74f 100644 --- a/.claude/commands/opsx/onboard.md +++ b/.claude/commands/opsx/onboard.md @@ -163,7 +163,7 @@ Now let's create a change to hold our work. ``` ## Creating a Change -A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives in `openspec/changes//` and holds your artifacts—proposal, specs, design, tasks. +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. ``` @@ -175,11 +175,11 @@ openspec new change "" **SHOW:** ``` -Created: `openspec/changes//` +Created: The folder structure: ``` -openspec/changes// +/ ├── proposal.md ← Why we're doing this (empty, we'll fill it) ├── design.md ← How we'll build it (empty) ├── specs/ ← Detailed requirements (empty) @@ -241,7 +241,7 @@ After approval, save the proposal: ```bash openspec instructions proposal --change "" --json ``` -Then write the content to `openspec/changes//proposal.md`. +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. @@ -262,12 +262,10 @@ Specs define **what** we're building in precise, testable terms. They use a requ For a small task like this, we might only need one spec file. ``` -**DO:** Create the spec file: +**DO:** Resolve where the spec file should be created: ```bash -# Unix/macOS -mkdir -p openspec/changes//specs/ -# Windows (PowerShell) -# New-Item -ItemType Directory -Force -Path "openspec/changes//specs/" +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 workspace planning context. ``` Draft the spec content: @@ -294,7 +292,7 @@ Here's the spec: This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases. ``` -Save to `openspec/changes//specs//spec.md`. +Save to the concrete file path chosen from `resolvedOutputPath`. --- @@ -339,7 +337,7 @@ Here's the design: For a small task, this captures the key decisions without over-engineering. ``` -Save to `openspec/changes//design.md`. +Save to the `resolvedOutputPath` from `openspec instructions design --change "" --json`. --- @@ -377,7 +375,7 @@ Each checkbox becomes a unit of work in the apply phase. Ready to implement? **PAUSE** - Wait for user to confirm they're ready to implement. -Save to `openspec/changes//tasks.md`. +Save to the `resolvedOutputPath` from `openspec instructions tasks --change "" --json`. --- @@ -421,7 +419,7 @@ The change is implemented! One more step—let's archive it. ``` ## Archiving -When a change is complete, we archive it. This moves it from `openspec/changes/` to `openspec/changes/archive/YYYY-MM-DD-/`. +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. ``` @@ -433,7 +431,7 @@ openspec archive "" **SHOW:** ``` -Archived to: `openspec/changes/archive/YYYY-MM-DD-/` +Archived to: `/archive/YYYY-MM-DD-/` The change is now part of your project's history. The code is in your codebase, the decision record is preserved. ``` @@ -496,7 +494,7 @@ Try `/opsx:propose` on something you actually want to build. You've got the rhyt If the user says they need to stop, want to pause, or seem disengaged: ``` -No problem! Your change is saved at `openspec/changes//`. +No problem! Your change is saved at the `changeRoot` reported by `openspec status --change "" --json`. To pick up where we left off later: - `/opsx:continue ` - Resume artifact creation diff --git a/.claude/commands/opsx/sync.md b/.claude/commands/opsx/sync.md index 1571610f..62bde0ca 100644 --- a/.claude/commands/opsx/sync.md +++ b/.claude/commands/opsx/sync.md @@ -21,9 +21,18 @@ This is an **agent-driven** operation - you will read delta specs and directly e **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose. -2. **Find delta specs** +2. **Resolve change context** - Look for delta spec files in `openspec/changes//specs/*/spec.md`. + Run: + ```bash + openspec status --change "" --json + ``` + + If status reports `actionContext.mode: "workspace-planning"`, explain that workspace spec sync is not supported in this slice and STOP. Do not fall back to repo-local paths or edit linked repos. + +3. **Find delta specs** + + Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the list of delta spec files. Each delta spec file contains sections like: - `## ADDED Requirements` - New requirements to add @@ -33,9 +42,9 @@ This is an **agent-driven** operation - you will read delta specs and directly e If no delta specs found, inform user and stop. -3. **For each delta spec, apply changes to main specs** +4. **For each delta spec, apply changes to main specs** - For each capability with a delta spec at `openspec/changes//specs//spec.md`: + For each repo-local capability delta spec path returned by the CLI: a. **Read the delta spec** to understand the intended changes @@ -66,7 +75,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e - Add Purpose section (can be brief, mark as TBD) - Add Requirements section with the ADDED requirements -4. **Show summary** +5. **Show summary** After applying all changes, summarize: - Which capabilities were updated diff --git a/.claude/commands/opsx/verify.md b/.claude/commands/opsx/verify.md index 7f403c1a..d6137880 100644 --- a/.claude/commands/opsx/verify.md +++ b/.claude/commands/opsx/verify.md @@ -27,9 +27,12 @@ Verify that an implementation matches the change artifacts (specs, tasks, design ``` 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 the change directory and load artifacts** + If status reports `actionContext.mode: "workspace-planning"`, explain that full workspace implementation verification is not supported in this slice and STOP. Do not infer repo-local implementation ownership or edit linked repos. + +3. **Get planning context and load artifacts** ```bash openspec instructions apply --change "" --json @@ -57,7 +60,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design - Recommendation: "Complete task: " or "Mark as done if already implemented" **Spec Coverage**: - - If delta specs exist in `openspec/changes//specs/`: + - If delta specs exist in `contextFiles.specs`: - Extract all requirements (marked with "### Requirement:") - For each requirement: - Search codebase for keywords related to the requirement diff --git a/.claude/skills/openspec-apply-change/SKILL.md b/.claude/skills/openspec-apply-change/SKILL.md index 70fbdb85..db4d8ce2 100644 --- a/.claude/skills/openspec-apply-change/SKILL.md +++ b/.claude/skills/openspec-apply-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.3.1" + generatedBy: "1.4.1" --- Implement tasks from an OpenSpec change. @@ -30,6 +30,7 @@ Implement tasks from an OpenSpec change. ``` 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** @@ -49,6 +50,8 @@ Implement tasks from an OpenSpec change. - If `state: "all_done"`: congratulate, suggest archive - Otherwise: proceed to implementation + **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files. + 4. **Read context files** Read every file path listed under `contextFiles` from the apply instructions output. diff --git a/.claude/skills/openspec-archive-change/SKILL.md b/.claude/skills/openspec-archive-change/SKILL.md index 12e2f70e..97c3e5e3 100644 --- a/.claude/skills/openspec-archive-change/SKILL.md +++ b/.claude/skills/openspec-archive-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.3.1" + generatedBy: "1.4.1" --- Archive a completed change in the experimental workflow. @@ -30,8 +30,11 @@ Archive a completed change in the experimental workflow. 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` or other) + If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos. + **If any artifacts are not `done`:** - Display warning listing incomplete artifacts - Use **AskUserQuestion tool** to confirm user wants to proceed @@ -52,7 +55,7 @@ Archive a completed change in the experimental workflow. 4. **Assess delta spec sync state** - Check for delta specs at `openspec/changes//specs/`. If none exist, proceed without sync prompt. + Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt. **If delta specs exist:** - Compare each delta spec with its corresponding main spec at `openspec/specs//spec.md` @@ -67,19 +70,19 @@ Archive a completed change in the experimental workflow. 5. **Perform the archive** - Create the archive directory if it doesn't exist: + Create an `archive` directory under `planningHome.changesDir` if it doesn't exist: ```bash - mkdir -p openspec/changes/archive + mkdir -p "/archive" ``` Generate target name using current date: `YYYY-MM-DD-` **Check if target already exists:** - If yes: Fail with error, suggest renaming existing archive or using different date - - If no: Move the change directory to archive + - If no: Move `changeRoot` to the archive directory ```bash - mv openspec/changes/ openspec/changes/archive/YYYY-MM-DD- + mv "" "/archive/YYYY-MM-DD-" ``` 6. **Display summary** @@ -98,7 +101,7 @@ Archive a completed change in the experimental workflow. **Change:** **Schema:** -**Archived to:** openspec/changes/archive/YYYY-MM-DD-/ +**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-/ **Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped") All artifacts complete. All tasks complete. diff --git a/.claude/skills/openspec-bulk-archive-change/SKILL.md b/.claude/skills/openspec-bulk-archive-change/SKILL.md index 5be81af2..dd35cb4f 100644 --- a/.claude/skills/openspec-bulk-archive-change/SKILL.md +++ b/.claude/skills/openspec-bulk-archive-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.3.1" + generatedBy: "1.4.1" --- Archive multiple completed changes in a single operation. @@ -37,14 +37,16 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig For each selected change, collect: a. **Artifact status** - Run `openspec status --change "" --json` - - Parse `schemaName` and `artifacts` list + - Parse `schemaName`, `artifacts`, `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext` - Note which artifacts are `done` vs other states - b. **Task completion** - Read `openspec/changes//tasks.md` + If any selected change reports `actionContext.mode: "workspace-planning"`, explain that workspace bulk archive is not supported in this slice and STOP before syncing specs or moving changes. Do not fall back to repo-local paths or edit linked repos. + + b. **Task completion** - Read `artifactPaths.tasks.existingOutputPaths` from status JSON - Count `- [ ]` (incomplete) vs `- [x]` (complete) - If no tasks file exists, note as "No tasks" - c. **Delta specs** - Check `openspec/changes//specs/` directory + c. **Delta specs** - Check `artifactPaths.specs.existingOutputPaths` from status JSON - List which capability specs exist - For each, extract requirement names (lines matching `### Requirement: `) @@ -127,8 +129,8 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig b. **Perform the archive**: ```bash - mkdir -p openspec/changes/archive - mv openspec/changes/ openspec/changes/archive/YYYY-MM-DD- + mkdir -p "/archive" + mv "" "/archive/YYYY-MM-DD-" ``` c. **Track outcome** for each change: diff --git a/.claude/skills/openspec-continue-change/SKILL.md b/.claude/skills/openspec-continue-change/SKILL.md index 4f2c3dcf..c43255df 100644 --- a/.claude/skills/openspec-continue-change/SKILL.md +++ b/.claude/skills/openspec-continue-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.3.1" + generatedBy: "1.4.1" --- Continue working on a change by creating the next artifact. @@ -37,6 +37,7 @@ Continue working on a change by creating the next artifact. - `schemaName`: The workflow schema being used (e.g., "spec-driven") - `artifacts`: Array of artifacts with their status ("done", "ready", "blocked") - `isComplete`: Boolean indicating if all artifacts are complete + - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths. 3. **Act based on status**: @@ -61,13 +62,13 @@ Continue working on a change by creating the next artifact. - `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 - - `outputPath`: Where to write the artifact + - `resolvedOutputPath`: Resolved path or pattern to write the artifact - `dependencies`: Completed artifacts to read for context - **Create the artifact file**: - Read any completed dependency files for context - 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 to the output path specified in instructions + - Write to the `resolvedOutputPath` specified in instructions. If it is a glob pattern, choose the concrete file path using the schema instruction and workspace planning context - Show what was created and what's now unlocked - STOP after creating ONE artifact diff --git a/.claude/skills/openspec-explore/SKILL.md b/.claude/skills/openspec-explore/SKILL.md index 6858d3f6..1e97aaa8 100644 --- a/.claude/skills/openspec-explore/SKILL.md +++ b/.claude/skills/openspec-explore/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.3.1" + generatedBy: "1.4.1" --- Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes. @@ -102,11 +102,10 @@ Think freely. When insights crystallize, you might offer: If the user mentions a change or you detect one is relevant: -1. **Read existing artifacts for context** - - `openspec/changes//proposal.md` - - `openspec/changes//design.md` - - `openspec/changes//tasks.md` - - etc. +1. **Resolve and read existing artifacts for context** + - Run `openspec status --change "" --json`. + - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON. + - Read existing files from `artifactPaths..existingOutputPaths`. 2. **Reference them naturally in conversation** - "Your design mentions using Redis, but we just realized SQLite fits better..." diff --git a/.claude/skills/openspec-ff-change/SKILL.md b/.claude/skills/openspec-ff-change/SKILL.md index 43f2632e..79337a63 100644 --- a/.claude/skills/openspec-ff-change/SKILL.md +++ b/.claude/skills/openspec-ff-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.3.1" + generatedBy: "1.4.1" --- Fast-forward through artifact creation - generate everything needed to start implementation in one go. @@ -28,7 +28,7 @@ Fast-forward through artifact creation - generate everything needed to start imp ```bash openspec new change "" ``` - This creates a scaffolded change at `openspec/changes//`. + This creates a scaffolded change in the planning home resolved by the CLI. 3. **Get the artifact build order** ```bash @@ -37,6 +37,7 @@ Fast-forward through artifact creation - generate everything needed to start imp Parse the JSON to get: - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`) - `artifacts`: list of all artifacts with their status and dependencies + - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths. 4. **Create artifacts in sequence until apply-ready** @@ -54,10 +55,10 @@ Fast-forward through artifact creation - generate everything needed to start imp - `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 for this artifact type - - `outputPath`: Where to write the artifact + - `resolvedOutputPath`: Resolved path or pattern to write the artifact - `dependencies`: Completed artifacts to read for context - Read any completed dependency files for context - - Create the artifact file using `template` as the structure + - Create the artifact file using `template` as the structure and write it to `resolvedOutputPath` - Apply `context` and `rules` as constraints - but do NOT copy them into the file - Show brief progress: "✓ Created " diff --git a/.claude/skills/openspec-new-change/SKILL.md b/.claude/skills/openspec-new-change/SKILL.md index 1af41c7d..882a7706 100644 --- a/.claude/skills/openspec-new-change/SKILL.md +++ b/.claude/skills/openspec-new-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.3.1" + generatedBy: "1.4.1" --- Start a new change using the experimental artifact-driven approach. @@ -39,13 +39,13 @@ Start a new change using the experimental artifact-driven approach. openspec new change "" ``` Add `--schema ` only if the user requested a specific workflow. - This creates a scaffolded change at `openspec/changes//` with the selected schema. + This creates a scaffolded change in the planning home resolved by the CLI. 4. **Show the artifact status** ```bash - openspec status --change "" + openspec status --change "" --json ``` - This shows which artifacts need to be created and which are ready (dependencies satisfied). + Use the returned `planningHome`, `changeRoot`, `artifactPaths`, and `nextSteps` instead of assuming repo-local paths. 5. **Get instructions for the first artifact** The first artifact depends on the schema (e.g., `proposal` for spec-driven). diff --git a/.claude/skills/openspec-onboard/SKILL.md b/.claude/skills/openspec-onboard/SKILL.md index b6c734de..97599a45 100644 --- a/.claude/skills/openspec-onboard/SKILL.md +++ b/.claude/skills/openspec-onboard/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.3.1" + generatedBy: "1.4.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. @@ -167,7 +167,7 @@ Now let's create a change to hold our work. ``` ## Creating a Change -A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives in `openspec/changes//` and holds your artifacts—proposal, specs, design, tasks. +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. ``` @@ -179,11 +179,11 @@ openspec new change "" **SHOW:** ``` -Created: `openspec/changes//` +Created: The folder structure: ``` -openspec/changes// +/ ├── proposal.md ← Why we're doing this (empty, we'll fill it) ├── design.md ← How we'll build it (empty) ├── specs/ ← Detailed requirements (empty) @@ -245,7 +245,7 @@ After approval, save the proposal: ```bash openspec instructions proposal --change "" --json ``` -Then write the content to `openspec/changes//proposal.md`. +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. @@ -266,12 +266,10 @@ Specs define **what** we're building in precise, testable terms. They use a requ For a small task like this, we might only need one spec file. ``` -**DO:** Create the spec file: +**DO:** Resolve where the spec file should be created: ```bash -# Unix/macOS -mkdir -p openspec/changes//specs/ -# Windows (PowerShell) -# New-Item -ItemType Directory -Force -Path "openspec/changes//specs/" +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 workspace planning context. ``` Draft the spec content: @@ -298,7 +296,7 @@ Here's the spec: This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases. ``` -Save to `openspec/changes//specs//spec.md`. +Save to the concrete file path chosen from `resolvedOutputPath`. --- @@ -343,7 +341,7 @@ Here's the design: For a small task, this captures the key decisions without over-engineering. ``` -Save to `openspec/changes//design.md`. +Save to the `resolvedOutputPath` from `openspec instructions design --change "" --json`. --- @@ -381,7 +379,7 @@ Each checkbox becomes a unit of work in the apply phase. Ready to implement? **PAUSE** - Wait for user to confirm they're ready to implement. -Save to `openspec/changes//tasks.md`. +Save to the `resolvedOutputPath` from `openspec instructions tasks --change "" --json`. --- @@ -425,7 +423,7 @@ The change is implemented! One more step—let's archive it. ``` ## Archiving -When a change is complete, we archive it. This moves it from `openspec/changes/` to `openspec/changes/archive/YYYY-MM-DD-/`. +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. ``` @@ -437,7 +435,7 @@ openspec archive "" **SHOW:** ``` -Archived to: `openspec/changes/archive/YYYY-MM-DD-/` +Archived to: `/archive/YYYY-MM-DD-/` The change is now part of your project's history. The code is in your codebase, the decision record is preserved. ``` @@ -500,7 +498,7 @@ Try `/opsx:propose` on something you actually want to build. You've got the rhyt If the user says they need to stop, want to pause, or seem disengaged: ``` -No problem! Your change is saved at `openspec/changes//`. +No problem! Your change is saved at the `changeRoot` reported by `openspec status --change "" --json`. To pick up where we left off later: - `/opsx:continue ` - Resume artifact creation diff --git a/.claude/skills/openspec-sync-specs/SKILL.md b/.claude/skills/openspec-sync-specs/SKILL.md index f2ed9ec7..e29bdd92 100644 --- a/.claude/skills/openspec-sync-specs/SKILL.md +++ b/.claude/skills/openspec-sync-specs/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.3.1" + generatedBy: "1.4.1" --- Sync delta specs from a change to main specs. @@ -25,9 +25,18 @@ This is an **agent-driven** operation - you will read delta specs and directly e **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose. -2. **Find delta specs** +2. **Resolve change context** - Look for delta spec files in `openspec/changes//specs/*/spec.md`. + Run: + ```bash + openspec status --change "" --json + ``` + + If status reports `actionContext.mode: "workspace-planning"`, explain that workspace spec sync is not supported in this slice and STOP. Do not fall back to repo-local paths or edit linked repos. + +3. **Find delta specs** + + Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the list of delta spec files. Each delta spec file contains sections like: - `## ADDED Requirements` - New requirements to add @@ -37,9 +46,9 @@ This is an **agent-driven** operation - you will read delta specs and directly e If no delta specs found, inform user and stop. -3. **For each delta spec, apply changes to main specs** +4. **For each delta spec, apply changes to main specs** - For each capability with a delta spec at `openspec/changes//specs//spec.md`: + For each repo-local capability delta spec path returned by the CLI: a. **Read the delta spec** to understand the intended changes @@ -70,7 +79,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e - Add Purpose section (can be brief, mark as TBD) - Add Requirements section with the ADDED requirements -4. **Show summary** +5. **Show summary** After applying all changes, summarize: - Which capabilities were updated diff --git a/.claude/skills/openspec-verify-change/SKILL.md b/.claude/skills/openspec-verify-change/SKILL.md index 00d0532c..ca8d5c41 100644 --- a/.claude/skills/openspec-verify-change/SKILL.md +++ b/.claude/skills/openspec-verify-change/SKILL.md @@ -6,7 +6,7 @@ compatibility: Requires openspec CLI. metadata: author: openspec version: "1.0" - generatedBy: "1.3.1" + generatedBy: "1.4.1" --- Verify that an implementation matches the change artifacts (specs, tasks, design). @@ -31,9 +31,12 @@ Verify that an implementation matches the change artifacts (specs, tasks, design ``` 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 the change directory and load artifacts** + If status reports `actionContext.mode: "workspace-planning"`, explain that full workspace implementation verification is not supported in this slice and STOP. Do not infer repo-local implementation ownership or edit linked repos. + +3. **Get planning context and load artifacts** ```bash openspec instructions apply --change "" --json @@ -61,7 +64,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design - Recommendation: "Complete task: " or "Mark as done if already implemented" **Spec Coverage**: - - If delta specs exist in `openspec/changes//specs/`: + - If delta specs exist in `contextFiles.specs`: - Extract all requirements (marked with "### Requirement:") - For each requirement: - Search codebase for keywords related to the requirement