docs: update openspec skills (#461)

2026-05-24 12:30:34 +00:00 · 2026-05-24 12:17:17 +02:00
parent f81107fe7b
commit 40855b7abf
12 changed files with 8 additions and 205 deletions
@@ -1,5 +1,5 @@
 ---
-model: sonnet
+model: claude-sonnet-4-6
 name: "OPSX: Apply"
 description: Implement tasks from an OpenSpec change (Experimental)
 category: Workflow
@@ -158,7 +158,3 @@ This skill supports the "actions on a change" model:
 - **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
 - **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
 <!-- patch:model-sonnet -->
 <!-- patch:git-commit-apply -->
@@ -1,5 +1,5 @@
 ---
-model: sonnet
+model: claude-sonnet-4-6
 name: "OPSX: Archive"
 description: Archive a completed change in the experimental workflow
 category: Workflow
@@ -93,6 +93,7 @@ Archive a completed change in the experimental workflow.
   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
   ```
 <!-- opsx-git-commit-patch -->
 7. **Git: Commit, push, and create PR**
@@ -130,8 +131,6 @@ Archive a completed change in the experimental workflow.
   **If all checks pass:** notify the user and continue to summary.
 9. **Display summary**
   ```
   Show archive completion summary including:
   - Change name
@@ -208,11 +207,3 @@ Target archive directory already exists.
 - Show clear summary of what happened
 - 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
 <!-- patch:model-sonnet -->
 <!-- patch:verify-scoring -->
 <!-- patch:always-sync-specs -->
 <!-- patch:git-commit-archive -->
@@ -143,11 +143,7 @@ If a related change exists, read its artifacts (`proposal.md`, `design.md`, `tas
 ## Guardrails
 - **No implementation** — Never write application code. Creating OpenSpec artifacts is fine if the user approves.
- **No premature questions** — Exhaust web search and codebase investigation before asking anything. If you ask, state what you tried.
+- **No premature questions** — Whether asking the user or writing an "Open Question" in the report, exhaust the codebase and web first. If you can name a concrete next step (grep, file read, fetch) that would answer it, take that step instead.
 - **Cite sources** — Every finding must reference where it came from (URL for web, `file:line` for code). No unsourced claims.
 - **Stay grounded** — Prefer concrete evidence (code, docs, examples) over speculation. Label uncertain findings as such.
 - **Offer next steps, don't auto-proceed** — End with a recommendation for what to do next, but let the user decide.
 <!-- patch:explore-research -->
 <!-- patch:model-opus -->
@@ -1,11 +0,0 @@
 ---
 model: opus
 name: "OPSX: Init"
 description: Generate or refresh openspec/config.yaml for a project
 category: Workflow
 tags: [workflow, openspec, config]
 ---
 Generate or refresh `openspec/config.yaml` for the current project.
 Invoke the `openspec-init` skill.
@@ -127,9 +127,3 @@ git diff --cached --quiet || git commit -m "docs(openspec): propose <n>"
 - If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
 - If a change with that name already exists, ask if user wants to continue it or create a new one
 - Verify each artifact file exists after writing before proceeding to next
 <!-- patch:model-opus -->
 <!-- patch:design-guidance -->
 <!-- patch:git-commit-propose -->
@@ -163,5 +163,3 @@ Use clear markdown with:
 - Code references in format: `file.ts:123`
 - Specific, actionable recommendations
 - No vague suggestions like "consider reviewing"
 <!-- patch:model-opus -->
@@ -1,5 +1,5 @@
 ---
-model: sonnet
+model: claude-sonnet-4-6
 name: openspec-apply-change
 description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
 license: MIT
@@ -162,7 +162,3 @@ This skill supports the "actions on a change" model:
 - **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
 - **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
 <!-- patch:model-sonnet -->
 <!-- patch:git-commit-apply -->
@@ -1,5 +1,5 @@
 ---
-model: sonnet
+model: claude-sonnet-4-6
 name: openspec-archive-change
 description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
 license: MIT
@@ -97,6 +97,7 @@ Archive a completed change in the experimental workflow.
   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
   ```
 <!-- opsx-git-commit-patch -->
 7. **Git: Commit, push, and create PR**
@@ -134,8 +135,6 @@ Archive a completed change in the experimental workflow.
   **If all checks pass:** notify the user and continue to summary.
 9. **Display summary**
   ```
   Show archive completion summary including:
   - Change name
@@ -165,11 +164,3 @@ All artifacts complete. All tasks complete.
 - Show clear summary of what happened
 - If sync is requested, use openspec-sync-specs approach (agent-driven)
 - If delta specs exist, always run the sync assessment and show the combined summary before prompting
 <!-- patch:model-sonnet -->
 <!-- patch:verify-scoring -->
 <!-- patch:always-sync-specs -->
 <!-- patch:git-commit-archive -->
@@ -147,11 +147,7 @@ If a related change exists, read its artifacts (`proposal.md`, `design.md`, `tas
 ## Guardrails
 - **No implementation** — Never write application code. Creating OpenSpec artifacts is fine if the user approves.
- **No premature questions** — Exhaust web search and codebase investigation before asking anything. If you ask, state what you tried.
+- **No premature questions** — Whether asking the user or writing an "Open Question" in the report, exhaust the codebase and web first. If you can name a concrete next step (grep, file read, fetch) that would answer it, take that step instead.
 - **Cite sources** — Every finding must reference where it came from (URL for web, `file:line` for code). No unsourced claims.
 - **Stay grounded** — Prefer concrete evidence (code, docs, examples) over speculation. Label uncertain findings as such.
 - **Offer next steps, don't auto-proceed** — End with a recommendation for what to do next, but let the user decide.
 <!-- patch:explore-research -->
 <!-- patch:model-opus -->
@@ -1,136 +0,0 @@
 ---
 model: opus
 name: openspec-init
 description: Generate or refresh openspec/config.yaml for a project. Use when bootstrapping openspec in a new project or when updating a drifted config.
 license: MIT
 compatibility: Requires openspec CLI.
 metadata:
  author: agent-skills
  version: "1.1"
 ---
 Generate, refresh, or review `openspec/config.yaml` for the current project.
 ### Mode selection (run before Step 1)
 If `openspec/config.yaml` already exists, decide intent from the invocation argument:
 - Argument contains `review` (or no argument and the file exists) → **review mode**: read the file, judge whether it is well-tailored to the project, report strengths/observations, and stop. Do not propose a regeneration; do not flatten a project-tailored config back to generic template wording. Skip Steps 1, 2, and 5.
  Even in review mode, validate the file against the structural constraints defined in Step 3 (field shape, length limits, what belongs in which section) and flag any violation with a targeted fix rather than a full regeneration.
 - Argument contains `refresh`, `regenerate`, `rewrite`, or the file is missing → **generate mode**: continue with Step 1.
 ---
 ## Step 1 — Detect project name and description
 Check the following sources in order, stopping at the first hit:
 1. `package.json` — `name` + `description`
 2. `pubspec.yaml` — `name` + `description`
 3. `Cargo.toml` — `[package].name` + `description`
 4. `pyproject.toml` — `[project].name` + `description`
 5. `README.md` — H1 title + first non-empty paragraph after it
 6. `AGENTS.md` or `CLAUDE.md` — first paragraph
 Tell the developer which source you used. If no source yields a description, ask the developer (warning, not hard failure). Do not write a placeholder.
 ---
 ## Step 2 — Identify persona and scope
 Ask two questions (developer can override either suggestion):
 1. **"Who notices changes to this project?"** → `<persona>`
 2. **"What's the unit of scope a spec describes?"** → `<scope-noun>`
 Suggest a framing as a starting point:
 | Framing | When to suggest | Default persona | Default scope-noun |
 |---|---|---|---|
 | `product` | CLI tools, libraries, mobile/web apps with end-users | `user` (or named role like `shopper`, `reader`) | `user capabilities` or `<role> workflows` |
 | `environment` | Dotfiles, system setup, agent skills, developer tooling | `desktop user` or `developer or their agent` | `experience contexts` |
 For `product` with a named role, also ask: **"What is the role name?"** That name replaces `user` throughout the config.
 ---
 ## Step 3 — Compose the config
 Build the candidate `openspec/config.yaml`. **The `context:` field must be at most two sentences**: one that identifies the project, one that names the scope of what specs cover. No gate items, no bullet lists, no rationale — those belong under `rules.proposal`.
 ```yaml
 schema: spec-driven
 context: |
  <project-name> is <one-paragraph description from Step 1>. Specs cover changes that affect <scope-noun>.
 rules:
  proposal:
    <gate items — see template below>
    <skip items — see baseline below>
    - Justify why this change requires a spec (reference the gate items above)
  specs:
    <canonical specs block, with <persona> and <scope-noun> substituted>
 ```
 ### Gate template (used by both framings)
 Always include these two:
 ```yaml
    - "Spec required: adds, removes, or changes <persona>-visible behavior"
    - "Spec required: introduces a domain concept that changes <scope-noun>"
 ```
 `environment` adds one more, phrased to match the project (packages/services for system setups, skills/workflows for agent tooling):
 ```yaml
    - "Spec required: adds or removes <packages, services, skills> that alter the available experience"
 ```
 ### Skip baseline (single source of truth)
 ```yaml
    - "Skip spec: internal refactoring with no <persona>-visible change"
    - "Skip spec: tooling, packaging, dependency, or documentation-only changes"
    - "Skip spec: bug fix with obvious solution"
    - "Skip spec: would duplicate an existing spec"
 ```
 `environment` adds one more (only when relevant — system-style projects):
 ```yaml
    - "Skip spec: single package add/remove or preference tweak (keybinding, alias, color)"
 ```
 ### Canonical specs block (substitute `<persona>` and `<scope-noun>`)
 ```yaml
    - Every spec must trace to something the <persona> would notice or care about
    - Name the experience context where the change is noticed
    - Use GIVEN/WHEN/THEN format for behavioral scenarios
    - Architectural guardrails are constraints on how value is delivered to the <persona> — they must be load-bearing (violating one would degrade the <persona>'s experience)
    - Error classification determines whether the <persona> sees a warning or hard failure
    - On archive, sync the spec to reflect the shipped behavior
    - "CRITICAL: Reject if spec has no traceable impact on the <persona>'s experience"
    - "CRITICAL: Reject if spec describes implementation without connection to what the <persona> would notice"
    - "CRITICAL: Reject if change contradicts or duplicates an existing spec's experience impact"
    - "WARNING: Guardrail not justified as load-bearing"
    - "WARNING: Missing GIVEN/WHEN/THEN for claimed behaviors"
    - "WARNING: Scope too broad — multiple unrelated <scope-noun>"
 ```
 ---
 ## Step 4 — Preview and confirm
 Check that the existing file (if any) is valid YAML — if parsing fails, print the error and exit without modifying any file (hard failure). Then show a unified diff for update mode, or the full candidate for create mode.
 Ask: "Ready to write `openspec/config.yaml`. Confirm? (y/n)". If declined, exit and print the candidate for copy-paste.
 ---
 ## Step 5 — Write the file
 Create `openspec/` if needed (`mkdir -p openspec`) and write the confirmed candidate to `openspec/config.yaml`. Do not run any `openspec` CLI commands — those are the developer's next steps. Print: `"Written: openspec/config.yaml"`
@@ -131,9 +131,3 @@ git diff --cached --quiet || git commit -m "docs(openspec): propose <n>"
 - If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
 - If a change with that name already exists, ask if user wants to continue it or create a new one
 - Verify each artifact file exists after writing before proceeding to next
 <!-- patch:model-opus -->
 <!-- patch:design-guidance -->
 <!-- patch:git-commit-propose -->
@@ -167,5 +167,3 @@ Use clear markdown with:
 - Code references in format: `file.ts:123`
 - Specific, actionable recommendations
 - No vague suggestions like "consider reviewing"
 <!-- patch:model-opus -->