diff --git a/.agents/skills/openspec-apply-change/SKILL.md b/.agents/skills/openspec-apply-change/SKILL.md index 3478c27..33adbe9 100644 --- a/.agents/skills/openspec-apply-change/SKILL.md +++ b/.agents/skills/openspec-apply-change/SKILL.md @@ -39,11 +39,9 @@ In both branches, never create the root as a side effect: do not run `openspec i 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 diff --git a/.agents/skills/openspec-archive-change/SKILL.md b/.agents/skills/openspec-archive-change/SKILL.md index 4fa320e..917c351 100644 --- a/.agents/skills/openspec-archive-change/SKILL.md +++ b/.agents/skills/openspec-archive-change/SKILL.md @@ -46,11 +46,9 @@ In both branches, never create the root as a side effect: do not run `openspec i **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 @@ -119,7 +117,7 @@ In both branches, never create the root as a side effect: do not run `openspec i **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: + - 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`. @@ -171,7 +169,6 @@ In both branches, never create the root as a side effect: do not run `openspec i 5. **Perform the archive** Create an `archive` directory under `planningHome.changesDir` if it doesn't exist: - ```bash mkdir -p "/archive" ``` diff --git a/.agents/skills/openspec-explore/SKILL.md b/.agents/skills/openspec-explore/SKILL.md index 4a2568b..63bfbcc 100644 --- a/.agents/skills/openspec-explore/SKILL.md +++ b/.agents/skills/openspec-explore/SKILL.md @@ -132,7 +132,7 @@ This tells you: - Their names and task status - What the user might be working on -That is the _change_ list - work in flight. It does not include the project's durable capabilities, so list those too: +That is the *change* list - work in flight. It does not include the project's durable capabilities, so list those too: ```bash openspec list --specs ``` @@ -181,14 +181,14 @@ If the user mentions a change or you detect one is relevant: The files below are the default spec-driven schema's. With another schema, capture each insight in whichever artifact from `artifactPaths` fits it, and name that artifact in your offer; never create an artifact the schema does not define. - | 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 (default schema): - "That's a design decision. Capture it in design.md?" diff --git a/.agents/skills/openspec-propose/SKILL.md b/.agents/skills/openspec-propose/SKILL.md index 53b3b18..ffb2441 100644 --- a/.agents/skills/openspec-propose/SKILL.md +++ b/.agents/skills/openspec-propose/SKILL.md @@ -79,25 +79,20 @@ In both branches, never create the root as a side effect: do not run `openspec i Choose one schema form below. If a registered store is selected, append `--store ""` to that command and each later OpenSpec command shown below that accepts `--store`. Using the configured default: - ```bash openspec new change "" ``` Using an explicitly requested schema: - ```bash openspec new change "" --schema "" ``` - This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`. 5. **Get the artifact build order** - ```bash openspec status --change "" --json ``` - Parse the JSON to get: - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`) - `artifacts`: list of all artifacts, each with its `status` and its `requires` edges (the artifact IDs it directly depends on) @@ -110,46 +105,44 @@ In both branches, never create the root as a side effect: do not run `openspec i Loop through artifacts in dependency order (artifacts with no pending dependencies first): a. **For each artifact that is `ready` (dependencies satisfied)**: - - Get instructions: - - ```bash - openspec instructions --change "" --json - ``` - - The instructions JSON includes: - - `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 for this artifact type - - `skipped`/`warning`: present when the change declares skip_specs and this artifact must NOT be created - stop and pick another artifact - - `resolvedOutputPath`: Resolved path or pattern to write the artifact - - `dependencies`: Completed artifacts to read for context - - 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) - - **Inspect the relevant project before drafting**: Read `context` and `rules` first, then inspect relevant implementation, nearby tests, configuration, and documentation outside `openspec/`. Keep inspection read-only and proportional to the change; reuse findings for later artifacts and inspect more only as needed. - - Identify the target project from the request and project context; the planning home may be separate from the code. If the target is unclear, ask. For greenfield or non-code changes, inspect the available structure and relevant documents. If source is unavailable, state the limitation and ask when it materially affects the plan. - - Ground scope, approach, and tasks in what you find. Distinguish observed behavior from assumptions and proposed additions; surface conflicts with existing specs instead of silently deciding which is correct. - - Do this discovery now, rather than leaving generic "explore the codebase" or "make a plan" tasks for implementation. Keep any necessary follow-up investigation specific to an unresolved question. - - Choose the output path before creating anything. If `resolvedOutputPath` is a glob, follow `instruction` to choose a concrete path inside `changeRoot` that matches the glob, 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. Then verify the artifact file exists at that output path - - Otherwise create the artifact file using `template` as the structure and write it to that output path - - Apply `context` and `rules` as constraints - but do NOT copy them into the file - - Show brief progress: "Created " + - Get instructions: + ```bash + openspec instructions --change "" --json + ``` + - The instructions JSON includes: + - `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 for this artifact type + - `skipped`/`warning`: present when the change declares skip_specs and this artifact must NOT be created - stop and pick another artifact + - `resolvedOutputPath`: Resolved path or pattern to write the artifact + - `dependencies`: Completed artifacts to read for context + - 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) + - **Inspect the relevant project before drafting**: Read `context` and `rules` first, then inspect relevant implementation, nearby tests, configuration, and documentation outside `openspec/`. Keep inspection read-only and proportional to the change; reuse findings for later artifacts and inspect more only as needed. + - Identify the target project from the request and project context; the planning home may be separate from the code. If the target is unclear, ask. For greenfield or non-code changes, inspect the available structure and relevant documents. If source is unavailable, state the limitation and ask when it materially affects the plan. + - Ground scope, approach, and tasks in what you find. Distinguish observed behavior from assumptions and proposed additions; surface conflicts with existing specs instead of silently deciding which is correct. + - Do this discovery now, rather than leaving generic "explore the codebase" or "make a plan" tasks for implementation. Keep any necessary follow-up investigation specific to an unresolved question. + - Choose the output path before creating anything. If `resolvedOutputPath` is a glob, follow `instruction` to choose a concrete path inside `changeRoot` that matches the glob, 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. Then verify the artifact file exists at that output path + - Otherwise create the artifact file using `template` as the structure and write it to that output path + - Apply `context` and `rules` as constraints - but do NOT copy them into the file + - Show brief progress: "Created " b. **Continue until every artifact in the required set exists (not just `apply.requires`)** - - After creating each artifact, re-run `openspec status --change "" --json` - - The required set is `applyRequires` plus every artifact reachable from those by following the `requires` edges in `status --json` - walk them transitively (spec-driven closes over proposal, specs, design, tasks). Leave artifacts outside that set alone - - `status` is file-existence only, so an `applyRequires` artifact reading `done` does NOT mean its dependencies exist - writing `tasks.md` early marks `tasks` done while `specs` was never written. Use each artifact's `requires` edges, not its `status`, to build the required set: a `done` artifact still lists what it depends on - - An artifact already reading `status: "skipped"` is satisfied: the change declares `skip_specs` in `.openspec.yaml`, so its files must NOT exist. Never try to create one - - Create every artifact in the required set that is missing, then re-check - creating one can unblock others - - Skip one only when `status` already reports it `skipped`, or when its own `instruction` says it is conditional: run `openspec instructions --change "" --json` and skip only if its `instruction` field marks it optional (e.g. "create only if..."). Spec-driven's `design.md` qualifies; `specs` qualifies only via the `skipped` status above, never by your own judgment. Tell the user, and do not reconsider it - - Dependencies are enablers, not gates: if a required artifact is still `blocked` only because you skipped a conditional dependency, write it anyway - - Stop when every artifact in the required set is `done`, `skipped`, or was deliberately skipped + - After creating each artifact, re-run `openspec status --change "" --json` + - The required set is `applyRequires` plus every artifact reachable from those by following the `requires` edges in `status --json` - walk them transitively (spec-driven closes over proposal, specs, design, tasks). Leave artifacts outside that set alone + - `status` is file-existence only, so an `applyRequires` artifact reading `done` does NOT mean its dependencies exist - writing `tasks.md` early marks `tasks` done while `specs` was never written. Use each artifact's `requires` edges, not its `status`, to build the required set: a `done` artifact still lists what it depends on + - An artifact already reading `status: "skipped"` is satisfied: the change declares `skip_specs` in `.openspec.yaml`, so its files must NOT exist. Never try to create one + - Create every artifact in the required set that is missing, then re-check - creating one can unblock others + - Skip one only when `status` already reports it `skipped`, or when its own `instruction` says it is conditional: run `openspec instructions --change "" --json` and skip only if its `instruction` field marks it optional (e.g. "create only if..."). Spec-driven's `design.md` qualifies; `specs` qualifies only via the `skipped` status above, never by your own judgment. Tell the user, and do not reconsider it + - Dependencies are enablers, not gates: if a required artifact is still `blocked` only because you skipped a conditional dependency, write it anyway + - Stop when every artifact in the required set is `done`, `skipped`, or was deliberately skipped c. **If an artifact requires user input** (unclear context): - - Ask the user to clarify - - Then continue with creation + - Ask the user to clarify + - Then continue with creation 7. **Show final status** - ```bash openspec status --change "" ``` diff --git a/.agents/skills/openspec-sync-specs/SKILL.md b/.agents/skills/openspec-sync-specs/SKILL.md index f245700..9f4c298 100644 --- a/.agents/skills/openspec-sync-specs/SKILL.md +++ b/.agents/skills/openspec-sync-specs/SKILL.md @@ -47,7 +47,6 @@ In both branches, never create the root as a side effect: do not run `openspec i 2. **Resolve change context** Run: - ```bash openspec status --change "" --json ``` @@ -108,73 +107,73 @@ In both branches, never create the root as a side effect: do not run `openspec i b. **Read the main spec** at `/openspec/specs//spec.md` (may not exist yet) - **If it does not exist yet** (a new capability), match what `openspec archive` does: - only ADDED requirements may be applied - step d creates the spec from them. - MODIFIED and RENAMED have no requirement to act on, so stop the sync for that - capability and report that its main spec does not exist and only ADDED is allowed - for a new spec; never invent the missing requirement. REMOVED has nothing to - remove - skip it and warn. + **If it does not exist yet** (a new capability), match what `openspec archive` does: + only ADDED requirements may be applied - step d creates the spec from them. + MODIFIED and RENAMED have no requirement to act on, so stop the sync for that + capability and report that its main spec does not exist and only ADDED is allowed + for a new spec; never invent the missing requirement. REMOVED has nothing to + remove - skip it and warn. c. **Apply changes intelligently**: - **ADDED Requirements:** - - If requirement doesn't exist in main spec → add it - - If requirement already exists → update it to match (treat as implicit MODIFIED) - - **MODIFIED Requirements:** - - Find the requirement in main spec - - Apply the changes - this can be: - - Adding new scenarios the main spec does not have yet - - Modifying existing scenarios - - Changing the requirement description - - Preserve scenarios/content not mentioned in the delta - - **REMOVED Requirements:** - - Remove the entire requirement block from main spec - - Retiring the capability. Delete the whole `spec.md` - and the directory once - nothing else is left in it - only when ALL of these hold: - 1. removing the requirements _this run_ left no requirement blocks; - 2. the rest of the spec is well-formed (it still has a `## Purpose`); - 3. the main spec was not already empty before this sync - if you removed - nothing, change nothing; - 4. every other nonblank line in the whole file is accounted for as the - title, Purpose, Requirements header, or a canonical requirement's - statement, scenarios, or fenced examples; - 5. the change's `.openspec.yaml` declares `retire_capabilities: true`; - 6. the `spec.md` resolves inside the real specs root (do not follow a - capability-directory symlink to delete an external file). + **ADDED Requirements:** + - If requirement doesn't exist in main spec → add it + - If requirement already exists → update it to match (treat as implicit MODIFIED) + + **MODIFIED Requirements:** + - Find the requirement in main spec + - Apply the changes - this can be: + - Adding new scenarios the main spec does not have yet + - Modifying existing scenarios + - Changing the requirement description + - Preserve scenarios/content not mentioned in the delta + + **REMOVED Requirements:** + - Remove the entire requirement block from main spec + - Retiring the capability. Delete the whole `spec.md` - and the directory once + nothing else is left in it - only when ALL of these hold: + 1. removing the requirements *this run* left no requirement blocks; + 2. the rest of the spec is well-formed (it still has a `## Purpose`); + 3. the main spec was not already empty before this sync - if you removed + nothing, change nothing; + 4. every other nonblank line in the whole file is accounted for as the + title, Purpose, Requirements header, or a canonical requirement's + statement, scenarios, or fenced examples; + 5. the change's `.openspec.yaml` declares `retire_capabilities: true`; + 6. the `spec.md` resolves inside the real specs root (do not follow a + capability-directory symlink to delete an external file). If removing the selected requirements would leave no requirement blocks and any retirement condition is not satisfied, do not modify the main spec. Stop the sync for that capability, report the blocking condition, and tell the user how to resolve it. Never write or leave an empty `## Requirements` section. When only the marker is missing, say that too - it is the one thing the user can add to make the retirement go through. - - Deleting the file also deletes its `## Purpose`; any other section blocks - retirement. Name Purpose when you report the retirement. Include a pasteable - `git checkout` only when the spec lived in the caller's checkout; - otherwise give checkout-scoped recovery guidance. + - Deleting the file also deletes its `## Purpose`; any other section blocks + retirement. Name Purpose when you report the retirement. Include a pasteable + `git checkout` only when the spec lived in the caller's checkout; + otherwise give checkout-scoped recovery guidance. - **RENAMED Requirements:** - - Find the FROM requirement, rename to TO + **RENAMED Requirements:** + - Find the FROM requirement, rename to TO - **`## Purpose` in the delta:** - - The main spec already has one and it is authoritative - leave it alone - (this is what `openspec archive` does; it warns and moves on) + **`## Purpose` in the delta:** + - The main spec already has one and it is authoritative - leave it alone + (this is what `openspec archive` does; it warns and moves on) d. **Create new main spec** if capability doesn't exist yet: - - Only when the delta has ADDED requirements to put in it and no MODIFIED or - RENAMED requirements blocked this capability in step b. Otherwise create nothing - and leave the specs directory untouched. For a REMOVED-only delta, if the change's - `.openspec.yaml` declares `retire_capabilities: true`, report it as already retired - and continue without recreating the spec. Without that marker, report the sync as blocked: - `openspec archive` rejects it with `Spec must have at least one requirement`. - An empty delta has no operations to sync; report it as blocked too. - Never write an empty `## Requirements` section. - - Create `/openspec/specs//spec.md` - - Add Purpose section: copy the delta's `## Purpose` body verbatim when it has one - (this is what `openspec archive` does); only write a brief TBD placeholder when it does not - - Add Requirements section with the ADDED requirements - - Follow the **Main Spec Format Reference** below + - Only when the delta has ADDED requirements to put in it and no MODIFIED or + RENAMED requirements blocked this capability in step b. Otherwise create nothing + and leave the specs directory untouched. For a REMOVED-only delta, if the change's + `.openspec.yaml` declares `retire_capabilities: true`, report it as already retired + and continue without recreating the spec. Without that marker, report the sync as blocked: + `openspec archive` rejects it with `Spec must have at least one requirement`. + An empty delta has no operations to sync; report it as blocked too. + Never write an empty `## Requirements` section. + - Create `/openspec/specs//spec.md` + - Add Purpose section: copy the delta's `## Purpose` body verbatim when it has one + (this is what `openspec archive` does); only write a brief TBD placeholder when it does not + - Add Requirements section with the ADDED requirements + - Follow the **Main Spec Format Reference** below 5. **Validate updated main specs** @@ -203,27 +202,22 @@ Only on a delta that introduces a brand-new capability. Seeds the new main spec. ## ADDED Requirements ### Requirement: New Feature - The system SHALL do something new. #### Scenario: Basic case - - **WHEN** user does X - **THEN** system does Y ## MODIFIED Requirements ### Requirement: Existing Feature - The system SHALL keep doing the existing thing, now also handling A. #### Scenario: Scenario the main spec already has - - **WHEN** user does X - **THEN** system does Y #### Scenario: New scenario to add - - **WHEN** user does A - **THEN** system does B @@ -245,17 +239,14 @@ Main specs are what the delta merges INTO. They must never contain delta operati # Specification ## Purpose - Short description of what this capability does and why it exists. ## Requirements ### Requirement: New Feature - The system SHALL do something new. #### Scenario: Basic case - - **WHEN** user does X - **THEN** system does Y ``` diff --git a/.agents/skills/openspec-update-change/SKILL.md b/.agents/skills/openspec-update-change/SKILL.md index 2d13674..cdf66ee 100644 --- a/.agents/skills/openspec-update-change/SKILL.md +++ b/.agents/skills/openspec-update-change/SKILL.md @@ -48,11 +48,9 @@ This workflow revises artifacts that already exist; it never creates missing one Always announce: "Using change: " and how to override (e.g., `openspec-update-change `). 2. **Get the change's artifacts** - ```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") @@ -85,7 +83,6 @@ This workflow revises artifacts that already exist; it never creates missing one - Show each proposed revision and why - including the requested edit drafted in step 4. Write only after the user confirms. - If the user rejects a revision, do not write it - leave that artifact unchanged. - When a substantial rewrite is needed, get that artifact's rules and template first: - ```bash openspec instructions "" --change "" --json ``` @@ -109,4 +106,4 @@ After each invocation, show: - 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`, creating them is a separate step, outside this workflow. 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, ask for a distinct unused change name and recommend `openspec new change ""` instead (the "Update vs. Start Fresh" heuristic). +- If the request changes the change's *intent* rather than refining it, ask for a distinct unused change name and recommend `openspec new change ""` instead (the "Update vs. Start Fresh" heuristic). diff --git a/biome.json b/biome.json index 87b5598..f420e69 100644 --- a/biome.json +++ b/biome.json @@ -67,6 +67,7 @@ "!.github/prompts", "!.github/skills", "!.opencode", + "!**/.agents", "!openspec" ] }, diff --git a/package.json b/package.json index a62d067..0608dac 100644 --- a/package.json +++ b/package.json @@ -89,6 +89,6 @@ "typescript": "6.0.3" }, "lint-staged": { - "*.{js,ts,cjs,mjs,astro,md,yml,yaml}": "biome format --fix" + "*.{js,ts,cjs,mjs,astro,md,yml,yaml}": "biome format --fix --no-errors-on-unmatched" } }