@oevery/rsp 1.2.0 → 2.0.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@oevery/rsp",
   "type": "module",
-  "version": "1.2.0",
-  "description": "RSP (Rules, Specs, Plans) workflow for AI-assisted development",
+  "version": "2.0.0",
+  "description": "RSP (Rules, Specs, Plans) workflow for lightweight AI-assisted change management",
   "author": "oevery",
   "license": "MIT",
   "homepage": "https://github.com/oevery/rsp#readme",
@@ -26,14 +26,16 @@
   "files": [
     "bin/",
     "dist/",
-    "rules/"
+    "rules/",
+    "skills/"
   ],
   "engines": {
     "node": ">=18"
   },
   "scripts": {
     "prepare": "pnpm run build",
-    "prepublishOnly": "pnpm run test",
+    "release:check": "pnpm run build && pnpm run lint && pnpm run test && npm pack --dry-run --ignore-scripts",
+    "prepublishOnly": "pnpm run release:check",
     "build": "tsup",
     "dev": "tsup --watch",
     "lint": "eslint .",
@@ -43,7 +45,8 @@
   },
   "dependencies": {
     "citty": "^0.2.2",
-    "picocolors": "^1.1.1"
+    "picocolors": "^1.1.1",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^9.0.0",

package/rules/rsp-rules.md

@@ -5,95 +5,92 @@ description: Core RSP rules for Rules, Specs, and Plans driven development.
 
 # RSP
 
-RSP = Rules, Specs, Plans.
-
-## Core structure
-
-```text
-.rsp/
-├── rules/
-├── specs/
-├── features/
-├── active.d/
-├── archives/
-└── config.yaml
-```
-
-## Managed boundaries
-
-- `AGENTS.md` is partially managed. RSP owns only the `<!-- rsp:begin --> ... <!-- rsp:end -->` block.
-- `specs/INDEX.md` is auto-generated. Rebuild it with `rsp specs-index` instead of editing it manually.
-- `archives/INDEX.md` is auto-generated. Rebuild it with `rsp archive-index` instead of editing it manually.
-- `design.md` is created by `rsp init` and then owned by the project.
-- `project-rules.md` is optional.
-- Keep durable architecture, boundaries, and cross-cutting technical constraints in `specs/design.md`.
-- Keep stable workflow rules, validation expectations, and local operating constraints in `rules/project-rules.md`.
-
-## Reading order
-
-1. Read `AGENTS.md` for entrypoint guidance.
-2. Read `active.d/` to find active features.
-3. If `active.d/` is empty, ask the user what to work on or suggest `npx -y @oevery/rsp new <name>`.
-4. Read the referenced `features/<name>.md`.
-5. Read `rules/` for technical constraints.
-6. Read `specs/design.md` and other project-level specs only when relevant to the current task.
-
-## File creation rules
-
-- `specs/design.md`: create by default with `rsp init`.
-- `rules/project-rules.md`: create only when the project has durable local rules worth preserving.
-- `rules/<name>.md`: create only for other durable rule sets.
-- `specs/<name>.md`: create only when the new document has durable project-level value and does not duplicate `design.md`.
-- `features/<name>.md`: create only for active work that should be tracked as a feature.
-- Do not create files merely for completeness.
-
-## Command-first creation
-
-- Prefer RSP commands over direct file creation when creating new RSP-managed files.
-- Use `rsp init` to scaffold the base RSP structure.
-- Use `rsp add rules <name>` to create new durable rules files under `rules/`.
-- Use `rsp add spec <name>` to create new durable project-level spec files under `specs/`.
-- Use `rsp new <name>` to create new feature files under `features/`.
-- Use `rsp close <name>` to move completed work into `archives/`.
-- Direct file creation is acceptable only when no RSP command covers the target file.
-- After a file is created by command, edit its contents in place as needed.
-
-## Feature requirements
-
-Every feature file should contain these sections:
-
+This file is the canonical RSP rules source.
+
+## Read order
+
+1. Read `AGENTS.md`.
+2. Read `.rsp/rules/rsp-rules.md` in full.
+3. Read `focus.d/`.
+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`.
+7. Read only the relevant additional `rules/` and `specs/` files.
+
+## Core rules
+
+- Treat `rules/` as the canonical rules source.
+- Treat `focus.d/` as the only current-focus source.
+- Treat `changes/` as open work.
+- Treat `archives/` as completed history.
+- Treat each change as a single `.md` file under `changes/`. Do not create multi-file change bundles or supplementary files alongside a change.
+- RSP uses only two lifecycle states: `open` (in `changes/`) and `archived` (in `archives/`). Do not introduce intermediate states such as "in review" or "verified".
+- Keep every change file in the fixed six-section structure.
+- Use an RSP command first when an RSP command already covers the action.
+- Do not infer current work from `changes/` alone.
+- Do not treat `AGENTS.md` as the long-term rules or design store.
+- Do not redefine the core change structure through project config.
+
+## File ownership
+
+- Manage only the `<!-- rsp:begin --> ... <!-- rsp:end -->` block in `AGENTS.md`.
+- Do not modify content outside the managed AGENTS block unless the user explicitly asks for it.
+- Do not edit `specs/INDEX.md` or `archives/INDEX.md` manually; use `npx -y @oevery/rsp update`.
+- Treat `specs/design.md` as the durable design file. Prefer sections: `Purpose`, `Stable Facts`, `Boundaries`, `Constraints`.
+- Treat all `specs/<name>.md` as durable-truth documents. Use the same section structure as `specs/design.md`.
+- Treat `rules/project-rules.md` as the durable local-rules file.
+- Create `rules/project-rules.md` only when the project has stable local rules worth keeping.
+- Create or update `specs/` only for durable project-level facts that are stable, reusable, and worth rereading in later sessions.
+- Prefer updating `specs/design.md` or an existing durable file before creating a new spec file.
+- Create a new `specs/<name>.md` only when the knowledge forms a distinct durable project topic that does not fit `specs/design.md` or an existing durable file.
+- Write stable facts to the smallest correct durable file. Do not duplicate the same fact across multiple durable files without a clear long-term reason.
+
+## Command rules
+
+- Use `npx -y @oevery/rsp init` to scaffold the base RSP structure.
+- Use `npx -y @oevery/rsp add rules <name>` to create a durable rules file.
+- Use `npx -y @oevery/rsp add spec <name>` to create a durable spec file.
+- Use `npx -y @oevery/rsp create <name>` to create an open change.
+- Use `npx -y @oevery/rsp focus <name>` to foreground an existing open change.
+- Use `npx -y @oevery/rsp unfocus <name>` to remove an open change from the current focus set.
+- Use `npx -y @oevery/rsp archive <name>` to archive a completed change.
+- Use `npx -y @oevery/rsp update` to refresh bundled rules, repair the managed `AGENTS.md` block, and rebuild generated indices.
+- Use `npx -y @oevery/rsp doctor` for diagnostics only.
+- If RTK is available, you may prefix RSP commands with `rtk`.
+- Do not use `npx -y @oevery/rsp create <name>` to re-focus an existing change.
+- Do not create RSP-managed files directly when an RSP command already exists for that file type.
+
+## Change rules
+
+Every change file must contain:
+
+- an explicit `kind` field in frontmatter
+- `## Proposal`
 - `## Spec`
-- `## Plan`
-- `## Tests`
+- `## Design`
+- `## Tasks`
+- `## Verify`
 - `## Blockers`
 
-## Init constraints
+Do not leave `kind` unresolved.
 
-- `rsp init` scaffolds project structure only. It must not create a feature file.
-- `rsp init --with-project-setup` may additionally seed `features/project-setup.md` and the matching `active.d` marker for onboarding.
-- `rsp init` should create `features/`, `active.d/`, `archives/`, and `specs/design.md` up front.
-- `rsp init --agents-mode managed|skip|print` controls whether `AGENTS.md` is updated, skipped, or printed.
-- `managed` should update only the managed AGENTS block.
-- `skip` should leave `AGENTS.md` untouched.
-- `print` should scaffold `.rsp/` and print the managed AGENTS block without writing it.
+If a section does not apply, keep it and write `- none` or `- not needed: <reason>`.
 
-## Agent behavior
+## Archive gate
 
-- Read `active.d/` first.
-- Treat `AGENTS.md` as a navigation layer, not the long-term knowledge base.
-- Preserve content outside the managed AGENTS block unless explicitly asked to change it.
-- Keep project-wide design and durable context in `specs/design.md`.
-- Keep stable local rules in `rules/project-rules.md` or another durable rules file only when needed.
-- Use `rsp add rules project-rules` for the canonical optional project rules file.
-- Do not push long-lived project knowledge back into `AGENTS.md`.
-- `rsp doctor` is diagnostic only and must not mutate project files.
+- `rsp archive <name>` never blocks. It warns but always completes the move.
+- Make a durable-update decision before `npx -y @oevery/rsp archive <name>`.
+- If `Blockers` still contains a real blocker, set `Archive ready: no`.
+- If the change produced durable knowledge that has not been written to `specs/` or `rules/`, set `Archive ready: no`.
+- If `Verify` is incomplete but there is no active blocker and no missing durable update, treat archive readiness as a judgment call.
+- A durable update should contain stable facts only, not task history, debugging notes, or one-off implementation context.
+- Default to no spec writeback unless the change produced project-level durable knowledge that future work must reread.
 
 ## Prohibitions
 
-- Do not manually maintain `specs/INDEX.md` or `archives/INDEX.md`.
-- Do not create `project-rules.md` by default when the project has no durable local rules.
-- Do not use `AGENTS.md` as the long-term storage location for project design or rules.
-- Do not create `specs` files that duplicate information already stored in `design.md` or durable rules files.
 - Do not create placeholder or empty-shell files merely for completeness.
-- Do not create new files under `.rsp/rules/`, `.rsp/specs/`, or `.rsp/features/` directly when an RSP command already exists for that file type.
-- Do not create archive entries directly under `.rsp/archives/`; use `rsp close <name>`.
+- Do not create archive entries directly under `.rsp/archives/`; use `npx -y @oevery/rsp archive <name>`.
+- Do not create spec files that duplicate `specs/design.md` or another durable file.
+- Do not create a catch-all summary file like `specs/changes.md`.
+- Do not create supplementary files alongside a single change file.
+- Do not promote archive history, temporary troubleshooting notes, or task-by-task execution logs into `specs/` or `rules/`.

package/skills/rsp/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: rsp
+description: Use this skill when adopting, operating, auditing, or repairing an RSP project and its .rsp structure.
+---
+
+# RSP Skill
+
+Load this skill when you need to initialize RSP, operate an existing RSP project, audit or repair `.rsp/`, or decide whether a change needs durable updates before archive.
+
+This skill operationalizes the rules in `.rsp/rules/rsp-rules.md`. Always load and follow those rules first.
+
+Prefer exact file paths, exact commands, and exact durable facts over vague summaries.
+
+## Workflow
+
+### Adopt or initialize
+
+1. Use one of these commands:
+   - `npx -y @oevery/rsp init --agents-mode managed`
+   - `npx -y @oevery/rsp init --agents-mode print`
+   - `npx -y @oevery/rsp init --with-project-setup --agents-mode managed`
+   - `npx -y @oevery/rsp init --with-project-setup --agents-mode print`
+2. If the repository still needs an explicit bootstrap change and you did not use `--with-project-setup`, run `npx -y @oevery/rsp create project-setup`.
+3. Fill `changes/project-setup.md`.
+4. Set an explicit `kind` in the change frontmatter.
+5. Write durable architecture, boundaries, defaults, and constraints into `specs/design.md`.
+6. Write stable local workflow or validation rules into `rules/project-rules.md` only when they are long-lived.
+7. Run `npx -y @oevery/rsp doctor`.
+
+### Operate an existing project
+
+1. Follow the read order in `.rsp/rules/rsp-rules.md`.
+2. If a focused change is missing an explicit `kind`, repair the frontmatter before continuing.
+3. If an existing open change should become current work, use `npx -y @oevery/rsp focus <name>`.
+4. Do not treat unfocused files in `changes/` as current work unless the user explicitly asks for them or you first run `npx -y @oevery/rsp focus <name>`.
+
+### Audit or repair
+
+1. Check that `.rsp/` exists.
+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.
+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`.
+
+## Durable decision
+
+Before `npx -y @oevery/rsp archive <name>`:
+
+1. Read the current change.
+2. Read only the relevant `specs/` and `rules/` files.
+3. Inspect code only if needed.
+4. Return exactly one decision:
+
+- `No durable update needed`
+- `Update existing spec or rule`
+- `Create a new durable spec` only when the knowledge is truly project-level, reusable, and does not fit `specs/design.md`, an existing spec, or a rule file
+
+Write a durable update only when one of these is true:
+
+- the change altered stable system behavior
+- the change changed a project boundary, default, or constraint
+- future agents or developers would likely make mistakes without the fact
+- the fact is worth rereading in later sessions as durable project knowledge
+
+When unsure whether a fact is truly durable, prefer `No durable update needed` over speculative promotion.
+
+Default to no spec writeback unless the change produced project-level durable knowledge that future work must reread.
+
+Do not write these into `specs/` or `rules/`:
+
+- temporary debugging history
+- task-by-task execution notes
+- one-off implementation context
+- archive-only historical detail
+- a catch-all summary file like `specs/changes.md`
+
+Choose the smallest correct target:
+
+- project-wide design, boundaries, defaults, and durable context -> `specs/design.md`
+- stable local workflow or validation rules -> `rules/project-rules.md`
+- another durable rule set -> `rules/<name>.md`
+- an additional reusable project-level spec -> `specs/<name>.md`
+
+Prefer `specs/design.md` or an existing durable file before creating a new spec file.
+
+When writing the durable update:
+
+- write stable facts, not narrative history
+- prefer concrete facts and boundaries over summaries like "implemented X" or "investigated Y"
+- if you cannot identify a concrete durable target or concrete durable facts, do not invent them
+
+Set archive readiness like this:
+
+- If `Blockers` still contains a real blocker, set `Archive ready: no`.
+- If a durable update is required but not yet written, set `Archive ready: no`.
+- If no durable update is missing and the remaining `Verify` risk is consciously accepted, set `Archive ready: yes`.
+- Do not use CLI warning text as a substitute for semantic durable-update judgment.
+
+## Output template
+
+Use this exact format:
+
+```md
+## Durable Decision
+- Decision: <No durable update needed | Update existing spec or rule | Create a new durable spec>
+- Target: <path or N/A>
+- Why:
+  - <reason>
+- Facts to write:
+  - <durable fact>
+- Archive ready: <yes | no>
+```
+
+Minimal example:
+
+```md
+## Durable Decision
+- Decision: Update existing spec or rule
+- Target: .rsp/specs/design.md
+- Why:
+  - The change introduced a stable default and boundary that future work must follow.
+- Facts to write:
+  - Default API retries are capped at 3 attempts.
+  - Background sync stops retrying after a permanent authentication failure.
+- Archive ready: no
+```
+
+Rules for the output:
+
+- `Target` must be a concrete file path when the decision is not `No durable update needed`.
+- `Facts to write` must contain durable facts, not task history or debugging notes.
+- If the decision requires a durable update that is not yet written, `Archive ready` must be `no`.
+
+## Refresh guidance
+
+- After rule or skill changes, prefer a fresh session and reread `AGENTS.md` plus `.rsp/rules/*.md`.