@oevery/rsp 2.0.0 → 2.0.3

package/README.md

@@ -55,11 +55,12 @@ npx -y @oevery/rsp doctor
 ## File ownership
 
 - `AGENTS.md`: only the `<!-- rsp:begin --> ... <!-- rsp:end -->` block is managed by RSP.
-- `.rsp/specs/INDEX.md`: auto-generated. Rebuild with `rsp update`.
+- `.rsp/specs/INDEX.md`: auto-generated index of additional spec files beyond `design.md`. Rebuild with `rsp update`.
 - `.rsp/archives/INDEX.md`: auto-generated. Rebuild with `rsp update`.
 - `.rsp/specs/design.md`: created by `rsp init`, then owned by the project.
 - `.rsp/rules/project-rules.md`: optional; create only when the project has durable local rules.
 - Keep durable architecture, boundaries, and cross-cutting technical constraints in `.rsp/specs/design.md`.
+- Treat `.rsp/specs/INDEX.md` as a directory for additional spec files; it does not list `design.md`.
 - Keep stable workflow rules, validation expectations, and local operating constraints in `.rsp/rules/project-rules.md`.
 
 ## AGENTS integration
@@ -70,6 +71,9 @@ Managed block example:
 <!-- rsp:begin -->
 ## RSP Entry
 
+RSP keeps durable rules, specs, and current work under `.rsp/`.
+Treat AGENTS.md as navigation only; keep durable rules and design in `.rsp/`.
+
 Read in order:
 1. .rsp/rules/rsp-rules.md
 2. .rsp/focus.d/
@@ -77,6 +81,9 @@ Read in order:
 4. .rsp/specs/design.md
 5. .rsp/specs/INDEX.md
 6. only the relevant additional .rsp/rules/*.md and .rsp/specs/*.md files
+
+If `.rsp/focus.d/` is empty, ask what to work on or suggest `npx -y @oevery/rsp create <name>`.
+If your agent supports Agent Skills, load `rsp` for setup, repair, and durable-decision tasks.
 <!-- rsp:end -->
 ```
 
@@ -111,11 +118,17 @@ When this README shows `rsp <command>`, it assumes the command is already availa
 Example optional installation flow:
 
 ```bash
-npx skills add oevery/rsp --skill rsp
+npx skills add oevery/rsp
 ```
 
 This repository publishes a skill named `rsp` under `skills/rsp/`.
 
+`rsp update` refreshes project-local RSP files only. If you use the published RSP skill, refresh it separately after upgrading:
+
+```bash
+npx skills add oevery/rsp
+```
+
 ## Work Model
 
 ```text

package/README.zh-CN.md

@@ -55,11 +55,12 @@ npx -y @oevery/rsp doctor
 ## 文件所有权
 
 - `AGENTS.md`：只有 `<!-- rsp:begin --> ... <!-- rsp:end -->` 受管块由 RSP 维护。
-- `.rsp/specs/INDEX.md`：自动生成，使用 `rsp update` 重建。
+- `.rsp/specs/INDEX.md`：自动生成，用于索引 `design.md` 之外的附加 spec 文件；使用 `rsp update` 重建。
 - `.rsp/archives/INDEX.md`：自动生成，使用 `rsp update` 重建。
 - `.rsp/specs/design.md`：由 `rsp init` 创建，之后由项目维护。
 - `.rsp/rules/project-rules.md`：可选，仅在项目确有长期本地规则时创建。
 - 将长期架构、边界和跨模块技术约束放在 `.rsp/specs/design.md`。
+- 将 `.rsp/specs/INDEX.md` 视为附加 spec 的目录；它不列出 `design.md`。
 - 将稳定的工作流规则、验证要求和本地运行约束放在 `.rsp/rules/project-rules.md`。
 
 ## AGENTS 接入
@@ -70,6 +71,9 @@ npx -y @oevery/rsp doctor
 <!-- rsp:begin -->
 ## RSP Entry
 
+RSP keeps durable rules, specs, and current work under `.rsp/`.
+Treat AGENTS.md as navigation only; keep durable rules and design in `.rsp/`.
+
 Read in order:
 1. .rsp/rules/rsp-rules.md
 2. .rsp/focus.d/
@@ -77,6 +81,9 @@ Read in order:
 4. .rsp/specs/design.md
 5. .rsp/specs/INDEX.md
 6. only the relevant additional .rsp/rules/*.md and .rsp/specs/*.md files
+
+If `.rsp/focus.d/` is empty, ask what to work on or suggest `npx -y @oevery/rsp create <name>`.
+If your agent supports Agent Skills, load `rsp` for setup, repair, and durable-decision tasks.
 <!-- rsp:end -->
 ```
 
@@ -105,11 +112,17 @@ Read in order:
 可选安装示例：
 
 ```bash
-npx skills add oevery/rsp --skill rsp
+npx skills add oevery/rsp
 ```
 
 本仓库发布了一个名为 `rsp` 的 skill，位于 `skills/rsp/`。
 
+`rsp update` 只会刷新项目内的 RSP 文件。如果你在使用发布出来的 RSP skill，升级后还需要单独刷新一次：
+
+```bash
+npx skills add oevery/rsp
+```
+
 ## 工作模型
 
 ```text

package/dist/cli.mjs

@@ -19,7 +19,7 @@ import pc from "picocolors";
 
 // src/core/helpers.ts
 import { existsSync } from "fs";
-import { readdir, readFile, rmdir, stat } from "fs/promises";
+import { readdir, readFile, rmdir } from "fs/promises";
 import { basename, dirname, join, relative, sep } from "path";
 import { parse } from "yaml";
 
@@ -166,6 +166,7 @@ kind: ops
 
 ## Tasks
 - [ ] Review the repository structure, entrypoints, and primary outputs
+- [ ] Review AGENTS.md and confirm the RSP entry points to the right project files
 - [ ] Fill .rsp/specs/design.md with durable architecture facts
 - [ ] Add .rsp/rules/project-rules.md if stable local rules or validation steps exist
 
@@ -209,12 +210,15 @@ ${template.acceptanceSection}
 - Approach:
   - ${template.approach}
 - Affected areas:
-  - ${template.affectedAreas}
+  - ${template.affectedArea1}
+  - ${template.affectedArea2}
 - Constraints:
   - ${template.constraints}
 
 ## Tasks
+- [ ] Finalize the proposal, spec, and design details for this change
 - [ ] ${template.task}
+- [ ] Verify the result and update any required durable docs or rules
 
 ## Verify
 - Automated:
@@ -231,6 +235,51 @@ ${template.acceptanceSection}
 }
 function getChangeTemplateByKind(kind) {
   switch (kind) {
+    case "feature":
+      return {
+        why: "<what user need or capability gap this addresses>",
+        scope: "<what new behavior or capability will be delivered>",
+        nonGoals: "<what related capabilities are explicitly out of scope>",
+        specSection: "### ADDED\n- Requirement: <new user-facing behavior>\n  - <verifiable requirement for the new capability>",
+        acceptanceSection: "#### Scenario: user exercises the new capability\n- GIVEN <context>\n- WHEN <user action>\n- THEN <expected new behavior>",
+        approach: "<how the new capability will be implemented>",
+        affectedArea1: "<concrete file path, directory, module, or subsystem 1>",
+        affectedArea2: "<concrete file path, directory, module, or subsystem 2 if needed>",
+        constraints: "<behavior, compatibility, performance, safety, or scope constraint that must hold>",
+        task: "<implement the new behavior and its acceptance scenario in the affected areas>",
+        automatedVerify: "<exact test, lint, build, or check command for the new behavior>",
+        manualVerify: "<exact end-to-end user scenario to validate the new capability>"
+      };
+    case "fix":
+      return {
+        why: "<what current behavior is wrong or broken>",
+        scope: "<what specific defect is being corrected>",
+        nonGoals: "<what related but separate issues are out of scope>",
+        specSection: "### MODIFIED\n- Requirement: correct behavior\n  - <expected correct behavior after the fix>",
+        acceptanceSection: "#### Scenario: defect is resolved\n- GIVEN <conditions that trigger the defect>\n- WHEN <action that previously failed>\n- THEN <expected correct outcome>\n- AND the original broken outcome no longer occurs",
+        approach: "<root cause analysis and fix strategy>",
+        affectedArea1: "<concrete file path, directory, module, or subsystem containing the defect>",
+        affectedArea2: "<secondary path, dependency, or test file if needed>",
+        constraints: "<regression, backward-compatibility, safety, or scope constraint that must hold>",
+        task: "<identify the root cause and apply the minimal fix>",
+        automatedVerify: "<exact regression test, lint, build, or check command that proves the fix>",
+        manualVerify: "<exact steps to reproduce the original issue and confirm it no longer occurs>"
+      };
+    case "refactor":
+      return {
+        why: "<what maintainability, readability, or structural issue motivates this>",
+        scope: "<what code areas are being restructured>",
+        nonGoals: "<no behavior change is expected or intended>",
+        specSection: "### MODIFIED\n- Requirement: internal structure improvement\n  - <desired structural outcome without observable behavior change>",
+        acceptanceSection: "#### Scenario: behavior is preserved after restructuring\n- GIVEN the existing codebase before the refactor\n- WHEN the refactored code runs against existing tests\n- THEN all existing tests pass unchanged",
+        approach: "<how the code will be restructured (rename, extract, move, etc.)>",
+        affectedArea1: "<concrete file path, directory, module, or subsystem being refactored>",
+        affectedArea2: "<secondary path, dependency, or test file if needed>",
+        constraints: "<observable behavior must remain unchanged; compatibility, performance, and safety constraints must still hold>",
+        task: "<restructure the code while keeping behavior identical>",
+        automatedVerify: "<exact existing test, lint, build, or check command that must continue to pass>",
+        manualVerify: "<exact scenario to spot-check that behavior is unchanged after the refactor>"
+      };
     case "docs":
       return {
         why: "<why the documentation change matters>",
@@ -239,11 +288,12 @@ function getChangeTemplateByKind(kind) {
         specSection: "### MODIFIED\n- Requirement: documentation accuracy\n  - <what durable reader-facing behavior or explanation changes>",
         acceptanceSection: "#### Scenario: reader follows the updated guidance\n- GIVEN the updated documentation\n- WHEN a reader follows the documented workflow\n- THEN the steps are accurate and sufficient",
         approach: "<how the documentation will be updated and organized>",
-        affectedAreas: "<doc path or documentation area>",
-        constraints: "<durable wording, consistency, or scope constraint>",
+        affectedArea1: "<concrete doc path, directory, module doc, or documentation surface 1>",
+        affectedArea2: "<secondary doc path or reference file if needed>",
+        constraints: "<durable wording, consistency, scope, or audience constraint that must hold>",
         task: "<update the target documentation and supporting references>",
-        automatedVerify: "<run markdown, docs, or link checks if applicable>",
-        manualVerify: "<review the updated doc as a reader and confirm it is accurate>"
+        automatedVerify: "<exact markdown, docs, link, lint, build, or check command if applicable>",
+        manualVerify: "<exact reader or operator scenario to confirm the updated guidance is accurate>"
       };
     case "research":
       return {
@@ -253,11 +303,12 @@ function getChangeTemplateByKind(kind) {
         specSection: "### ADDED\n- Requirement: research outcome recording\n  - <what finding, option, or decision must be captured clearly>",
         acceptanceSection: "#### Scenario: research question is resolved\n- GIVEN the current uncertainty or open question\n- WHEN the investigation is completed\n- THEN the result is recorded clearly enough to guide follow-up work",
         approach: "<how the investigation will be performed and what evidence will be gathered>",
-        affectedAreas: "<code path, subsystem, or source being investigated>",
-        constraints: "<time, evidence, or scope constraint for the investigation>",
-        task: "<gather evidence and record the resulting recommendation or finding>",
-        automatedVerify: "<run any command needed to confirm the observed behavior>",
-        manualVerify: "<review the findings and confirm they answer the original question>"
+        affectedArea1: "<concrete file path, directory, module, subsystem, or source under investigation>",
+        affectedArea2: "<secondary path, dependency, environment, or evidence source if needed>",
+        constraints: "<time, evidence, safety, or scope constraint for the investigation>",
+        task: "<gather evidence, record the recommendation or finding, and note any follow-up implementation work if needed>",
+        automatedVerify: "<exact command, script, query, or check used to confirm the observed behavior>",
+        manualVerify: "<exact review of the findings to confirm they answer the original question and identify follow-up work if needed>"
       };
     case "ops":
       return {
@@ -267,11 +318,12 @@ function getChangeTemplateByKind(kind) {
         specSection: "### MODIFIED\n- Requirement: operational behavior\n  - <what reliable operational outcome should change or stay true>",
         acceptanceSection: "#### Scenario: operational path succeeds\n- GIVEN the target environment or workflow\n- WHEN the operational change is applied\n- THEN the expected operational outcome is reliable",
         approach: "<how the operational change will be applied safely>",
-        affectedAreas: "<script, config, workflow, or environment path>",
-        constraints: "<rollback, safety, or environment constraint>",
+        affectedArea1: "<concrete script, config path, workflow, environment path, or operational surface 1>",
+        affectedArea2: "<secondary script, config path, dependency, or environment surface if needed>",
+        constraints: "<rollback, safety, reliability, environment, or scope constraint that must hold>",
         task: "<apply and verify the operational change>",
-        automatedVerify: "<run the relevant operational validation command>",
-        manualVerify: "<exercise the target workflow and confirm the operational result>"
+        automatedVerify: "<exact operational validation, lint, build, deploy, or check command>",
+        manualVerify: "<exact operator workflow or environment scenario to confirm the operational result>"
       };
     default:
       return {
@@ -281,11 +333,12 @@ function getChangeTemplateByKind(kind) {
         specSection: "### ADDED\n- Requirement: <new or updated behavior>\n  - <verifiable requirement>",
         acceptanceSection: "#### Scenario: <name>\n- GIVEN <context>\n- WHEN <action>\n- THEN <expected outcome>",
         approach: "<how the change will be implemented>",
-        affectedAreas: "<path or subsystem>",
-        constraints: "<binding technical or product constraint>",
-        task: "<implementation task>",
-        automatedVerify: "<test command or automated check>",
-        manualVerify: "<manual scenario to validate>"
+        affectedArea1: "<concrete file path, directory, module, or subsystem 1>",
+        affectedArea2: "<concrete file path, directory, module, or subsystem 2 if needed>",
+        constraints: "<behavior, compatibility, performance, safety, or scope constraint that must hold>",
+        task: "<implement the core change in the affected areas>",
+        automatedVerify: "<exact test, lint, build, or check command>",
+        manualVerify: "<exact end-to-end scenario to validate>"
       };
   }
 }
@@ -293,6 +346,9 @@ function renderRspAgentsBlock() {
   return `${RSP_AGENTS_BEGIN}
 ## RSP Entry
 
+RSP keeps durable rules, specs, and current work under \`.rsp/\`.
+Treat AGENTS.md as navigation only; keep durable rules and design in \`.rsp/\`.
+
 Read in order:
 1. .rsp/rules/rsp-rules.md
 2. .rsp/focus.d/
@@ -300,6 +356,9 @@ Read in order:
 4. .rsp/specs/design.md
 5. .rsp/specs/INDEX.md
 6. only the relevant additional .rsp/rules/*.md and .rsp/specs/*.md files
+
+If \`.rsp/focus.d/\` is empty, ask what to work on or suggest \`npx -y @oevery/rsp create <name>\`.
+If your agent supports Agent Skills, load \`rsp\` for setup, repair, and durable-decision tasks.
 ${RSP_AGENTS_END}`;
 }
 function upsertRspAgentsBlock(content) {
@@ -332,6 +391,16 @@ function guardRspInitialized() {
     process.exit(1);
   }
 }
+async function getFocusedChangeNames(options = {}) {
+  const names = /* @__PURE__ */ new Set();
+  const focusDir = join(RSP_DIR, "focus.d");
+  if (!existsSync(focusDir))
+    return names;
+  const entries = await walkFiles(focusDir, options);
+  for (const entryPath of entries)
+    names.add(normalizeLogicalPath(relative(focusDir, entryPath)));
+  return names;
+}
 function getOpenCheckboxes(sectionText) {
   return sectionText.split("\n").map((line) => line.trim()).filter((line) => /^- \[[ /]\]/.test(line));
 }
@@ -632,14 +701,17 @@ async function buildSpecsIndex({ acquireLock = true } = {}) {
 `);
     return;
   }
-  const specFiles = (await walkMarkdownFiles(specsDir)).filter((fp) => basename2(fp) !== "INDEX.md").sort();
+  const specFiles = (await walkMarkdownFiles(specsDir)).filter((fp) => {
+    const name = basename2(fp);
+    return name !== "INDEX.md" && name !== "design.md";
+  }).sort();
   const lines = [];
   lines.push("# Specs Index");
   lines.push("");
-  lines.push("_Project-level specs and design notes._");
+  lines.push("_Additional project-level specs beyond `design.md`._");
   lines.push("");
   if (specFiles.length === 0) {
-    lines.push("_No project-level specs yet._");
+    lines.push("_No additional project-level specs yet._");
   } else {
     lines.push("| File | Title | Summary |");
     lines.push("|------|-------|---------|");
@@ -782,6 +854,7 @@ async function archiveChange(name) {
     console.error(`  ${pc.red("Error:")} change name must be kebab-case with optional subdirectory (lowercase, digits, hyphens, slashes)`);
     process.exit(1);
   }
+  guardRspInitialized();
   const srcPath = join7(CHANGES_DIR, `${name}.md`);
   if (!existsSync7(srcPath)) {
     console.error(`  ${pc.red("Change not found:")} .rsp/changes/${name}.md`);
@@ -1185,7 +1258,7 @@ async function createChange(name, summary = "", kind) {
       console.log(`  ${pc.dim("Unchanged focus.")} Run: rsp focus ${name}`);
     else
       console.log(`  ${pc.dim("focused via focus.d")} \u2192 ${name}`);
-    console.log(`  ${pc.cyan("Next:")} edit the change file and complete the tasks
+    console.log(`  ${pc.cyan("Next:")} fill proposal/spec/design first, then implement and complete the tasks
 `);
   });
 }
@@ -1387,8 +1460,7 @@ function reportConfigListField(checks, parsed, key) {
 async function checkActiveChangeConsistency(checks, reportRuntime) {
   const changeFiles = existsSync10(CHANGES_DIR) ? await walkMarkdownFiles(CHANGES_DIR, { onError: reportRuntime }) : [];
   const changeNames = new Set(changeFiles.map((fp) => changeNameFromPath(CHANGES_DIR, fp)));
-  const focusEntries = existsSync10(FOCUS_DIR) ? await walkFiles(FOCUS_DIR, { onError: reportRuntime }) : [];
-  const focusNames = new Set(focusEntries.map((fp) => normalizeLogicalPath(relative5(FOCUS_DIR, fp))));
+  const focusNames = await getFocusedChangeNames({ onError: reportRuntime });
   const missingChangeFiles = [...focusNames].filter((name) => !changeNames.has(name));
   const unfocusedChangeFiles = [...changeNames].filter((name) => !focusNames.has(name));
   if (missingChangeFiles.length === 0) {
@@ -1515,7 +1587,7 @@ async function initProject(args = {}) {
     const bundledRules = await readFile9(join12(PKG_ROOT, "rules", "rsp-rules.md"), "utf-8");
     created = await ensureFile(join12(RSP_DIR, "rules", "rsp-rules.md"), bundledRules) || created;
     created = await ensureFile(join12(RSP_DIR, "config.yaml"), generateConfigTemplate()) || created;
-    const createdSpecsIndex = await ensureFile(join12(RSP_DIR, "specs", "INDEX.md"), "# Specs Index\n\n_Project-level specs and design notes._\n");
+    const createdSpecsIndex = await ensureFile(join12(RSP_DIR, "specs", "INDEX.md"), "# Specs Index\n\n_Additional project-level specs beyond `design.md`._\n");
     created = createdSpecsIndex || created;
     const createdDesign = await ensureFile(join12(RSP_DIR, "specs", "design.md"), generateDesignContent(projectName));
     created = createdDesign || created;
@@ -1595,21 +1667,16 @@ ${managed}
 
 // src/commands/status.ts
 import { existsSync as existsSync13 } from "fs";
-import { readFile as readFile10, stat as stat2 } from "fs/promises";
-import { join as join13, relative as relative6 } from "path";
+import { readFile as readFile10, stat } from "fs/promises";
+import { join as join13 } from "path";
 var COL_CHANGE = 32;
 var COL_KIND = 10;
 var COL_AGE = 7;
 var COL_PROGRESS = 10;
 async function showStatus(options = {}, runOptions = {}) {
-  const focusedSet = /* @__PURE__ */ new Set();
   const runtime = [];
   const reportRuntime = (diagnostic) => recordRuntimeDiagnostic(runtime, diagnostic, Boolean(runOptions.verbose) && !runOptions.json);
-  if (existsSync13(FOCUS_DIR)) {
-    const entries = await walkFiles(FOCUS_DIR, { onError: reportRuntime });
-    for (const entryPath of entries)
-      focusedSet.add(normalizeLogicalPath(relative6(FOCUS_DIR, entryPath)));
-  }
+  const focusedSet = await getFocusedChangeNames({ onError: reportRuntime });
   const changeFiles = existsSync13(CHANGES_DIR) ? await walkMarkdownFiles(CHANGES_DIR, { onError: reportRuntime }) : [];
   const changeMap = {};
   for (const fp of changeFiles)
@@ -1655,7 +1722,7 @@ async function showStatus(options = {}, runOptions = {}) {
         });
       }
       try {
-        const s = await stat2(fp);
+        const s = await stat(fp);
         ageDays = Math.floor((Date.now() - s.mtime.getTime()) / (1e3 * 60 * 60 * 24));
       } catch (error) {
         reportRuntime({
@@ -1816,9 +1883,11 @@ function printArchiveTrend(trend) {
 import { existsSync as existsSync14 } from "fs";
 import { mkdir as mkdir8, readFile as readFile11, writeFile as writeFile9 } from "fs/promises";
 import { join as join14 } from "path";
+var SKILL_REFRESH_HINT = "  Note: if you use the published RSP skill, refresh it too:\n    npx skills add oevery/rsp\n";
 async function updateProject() {
   if (!existsSync14(RSP_DIR)) {
-    console.log(`  ${pc.red("Error:")} RSP is not initialized. Run: rsp init`);
+    console.error(`  ${pc.red("Error:")} RSP is not initialized in this project`);
+    console.error(`  ${pc.dim("Run: rsp init")}`);
     process.exit(1);
   }
   return withRspLock("update", async () => {
@@ -1845,12 +1914,15 @@ async function updateProject() {
     }
     await buildSpecsIndex({ acquireLock: false });
     await buildArchiveIndex({ acquireLock: false });
-    if (!updated)
+    if (!updated) {
       console.log(`  ${pc.dim("Already up to date.")}
 `);
-    else
+      console.log(SKILL_REFRESH_HINT);
+    } else {
       console.log(`  ${pc.green("Update complete.")}
 `);
+      console.log(SKILL_REFRESH_HINT);
+    }
   });
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oevery/rsp",
   "type": "module",
-  "version": "2.0.0",
+  "version": "2.0.3",
   "description": "RSP (Rules, Specs, Plans) workflow for lightweight AI-assisted change management",
   "author": "oevery",
   "license": "MIT",

package/rules/rsp-rules.md

@@ -7,6 +7,12 @@ description: Core RSP rules for Rules, Specs, and Plans driven development.
 
 This file is the canonical RSP rules source.
 
+## Scope
+
+- Paths in this file are relative to the project root unless stated otherwise.
+- These rules are tool-agnostic and apply even when the agent does not support skills.
+- If the agent supports Agent Skills, load the `rsp` skill for initialization, audit or repair, and durable-decision tasks.
+
 ## Read order
 
 1. Read `AGENTS.md`.
@@ -15,6 +21,7 @@ This file is the canonical RSP rules source.
 4. If `focus.d/` is empty, ask the user what to work on or suggest `npx -y @oevery/rsp create <name>`.
 5. Read each `changes/<name>.md` file marked in `focus.d/`.
 6. Read `specs/design.md` and `specs/INDEX.md`.
+   `specs/INDEX.md` lists only additional spec files beyond `specs/design.md`.
 7. Read only the relevant additional `rules/` and `specs/` files.
 
 ## Core rules

package/skills/rsp/SKILL.md

@@ -1,6 +1,18 @@
 ---
 name: rsp
-description: Use this skill when adopting, operating, auditing, or repairing an RSP project and its .rsp structure.
+description: Use this skill when initializing RSP in a repository, operating an existing .rsp project, auditing or repairing .rsp state, or deciding whether a change needs durable updates before archive.
+compatibility:
+  agents:
+    - any agent that supports the Agent Skills format
+  requirements:
+    - Node.js 18+
+    - local filesystem read/write access
+    - shell access for `rsp` or `npx -y @oevery/rsp`
+  optional_requirements:
+    - network access for first-run `npx` installation or skill refresh
+metadata:
+  author: oevery
+  version: 2.0.3
 ---
 
 # RSP Skill
@@ -11,6 +23,19 @@ This skill operationalizes the rules in `.rsp/rules/rsp-rules.md`. Always load a
 
 Prefer exact file paths, exact commands, and exact durable facts over vague summaries.
 
+## When to use
+
+- Use this skill when a repository already contains `.rsp/` and the task is to operate within that workflow.
+- Use this skill when adopting RSP in a repository that does not yet have `.rsp/`.
+- Use this skill when the task is to audit or repair `.rsp/`, `AGENTS.md`, generated indices, or focus markers.
+- Use this skill when deciding whether a completed change needs durable updates before archive.
+
+## When not to use
+
+- Do not load this skill for general coding tasks unrelated to `.rsp/`.
+- Do not use this skill as a substitute for reading `.rsp/rules/rsp-rules.md` during a focused RSP task.
+- Do not use this skill when the repository does not use RSP and the user did not ask to adopt it.
+
 ## Workflow
 
 ### Adopt or initialize
@@ -40,9 +65,23 @@ Prefer exact file paths, exact commands, and exact durable facts over vague summ
 2. Check that `AGENTS.md` contains the managed RSP block.
 3. Check that `specs/design.md` exists.
 4. Check that `specs/INDEX.md` and `archives/INDEX.md` are still generated files.
+   `specs/INDEX.md` should list only additional spec files beyond `specs/design.md`.
 5. Check that `focus.d/` markers and `changes/` files are in sync.
 6. If generated indices or the managed AGENTS block drift, run `npx -y @oevery/rsp update`.
 
+## Expected outputs
+
+- exact file paths to read or update
+- exact RSP commands to run
+- a single durable-decision result in the required template when evaluating archive readiness
+
+## Trigger examples
+
+- "Set up RSP in this repository."
+- "Repair the broken .rsp state in this project."
+- "Check whether this change needs spec or rule writeback before archive."
+- "Audit the RSP setup and tell me what is missing."
+
 ## Durable decision
 
 Before `npx -y @oevery/rsp archive <name>`: