@oevery/rsp 2.0.2 → 2.0.3

package/README.md

@@ -71,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/
@@ -78,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 -->
 ```
 

package/README.zh-CN.md

@@ -71,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/
@@ -78,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 -->
 ```
 

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));
 }
@@ -785,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`);
@@ -1188,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
 `);
   });
 }
@@ -1390,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) {
@@ -1598,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)
@@ -1658,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({
@@ -1822,7 +1886,8 @@ 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 () => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oevery/rsp",
   "type": "module",
-  "version": "2.0.2",
+  "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`.

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
@@ -44,6 +69,19 @@ Prefer exact file paths, exact commands, and exact durable facts over vague summ
 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>`: