@oevery/rsp 3.1.0-beta.1 → 3.1.0-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +76 -73
- package/README.zh-CN.md +70 -52
- package/dist/chunk-4K53353L.mjs +322 -0
- package/dist/{chunk-QLXIDVKK.mjs → chunk-EALHA3ZS.mjs} +99 -1038
- package/dist/chunk-JOMFFQRG.mjs +99 -0
- package/dist/chunk-OTJFL6XH.mjs +1022 -0
- package/dist/cli.mjs +95 -264
- package/dist/{entry-LAPR3TNI.mjs → entry-N7WLWGTI.mjs} +8 -92
- package/dist/entry-UWUX3HM7.mjs +174 -0
- package/package.json +11 -10
- package/rules/rsp-rules.md +10 -12
- package/skills/rsp/SKILL.md +45 -179
- package/skills/rsp/references/conflict-handling.md +11 -0
- package/skills/rsp/references/durable-review.md +17 -0
- package/skills/rsp/references/groups-dependencies.md +11 -0
- package/skills/rsp/references/managed-routing.md +45 -0
- package/skills/rsp/references/setup-repair.md +11 -0
- package/skills/rsp-address-review/SKILL.md +5 -5
- package/skills/rsp-codebase-audit/SKILL.md +69 -0
- package/skills/rsp-codebase-audit/references/structural-lenses.md +35 -0
- package/skills/rsp-commit/SKILL.md +42 -0
- package/skills/rsp-design/SKILL.md +14 -9
- package/skills/rsp-manage/SKILL.md +23 -26
- package/skills/rsp-release-docs/SKILL.md +36 -128
- package/skills/rsp-release-docs/references/evidence-and-surfaces.md +21 -0
- package/skills/rsp-release-docs/references/output-contracts.md +0 -18
- package/skills/rsp-release-docs/references/publication-lifecycle.md +24 -0
- package/skills/rsp-shape/SKILL.md +19 -17
- package/skills/rsp-shape/references/complex-shaping.md +2 -2
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import {
|
|
3
|
+
inspectPackagedSkillInventory
|
|
4
|
+
} from "./chunk-4K53353L.mjs";
|
|
5
|
+
import {
|
|
6
|
+
openTerminalSession,
|
|
7
|
+
truncateDisplay
|
|
8
|
+
} from "./chunk-JOMFFQRG.mjs";
|
|
9
|
+
import "./chunk-OTJFL6XH.mjs";
|
|
10
|
+
|
|
11
|
+
// src/skills-tui/entry.tsx
|
|
12
|
+
import process from "process";
|
|
13
|
+
import { render } from "ink";
|
|
14
|
+
import ReactRuntime from "react";
|
|
15
|
+
|
|
16
|
+
// src/skills-tui/app.tsx
|
|
17
|
+
import { Box, Text, useApp, useInput, useStdout } from "ink";
|
|
18
|
+
import { useMemo, useState } from "react";
|
|
19
|
+
import { jsx, jsxs } from "react/jsx-runtime";
|
|
20
|
+
function SkillsApp({ initialWidth, inventory, messages, onComplete }) {
|
|
21
|
+
const { exit } = useApp();
|
|
22
|
+
const { stdout } = useStdout();
|
|
23
|
+
const width = Math.max(40, initialWidth ?? stdout.columns ?? 80);
|
|
24
|
+
const optional = useMemo(() => inventory.skills.filter((skill) => skill.kind === "optional"), [inventory]);
|
|
25
|
+
const defaults = useMemo(() => inventory.skills.filter((skill) => skill.kind === "default"), [inventory]);
|
|
26
|
+
const [selected, setSelected] = useState(/* @__PURE__ */ new Set());
|
|
27
|
+
const [cursor, setCursor] = useState(0);
|
|
28
|
+
const [phase, setPhase] = useState("select");
|
|
29
|
+
const finish = (selection) => {
|
|
30
|
+
onComplete(selection);
|
|
31
|
+
exit();
|
|
32
|
+
};
|
|
33
|
+
const selectedNames = () => [...defaults.map((skill) => skill.name), ...optional.filter((skill) => selected.has(skill.name)).map((skill) => skill.name)].sort();
|
|
34
|
+
useInput((input, key) => {
|
|
35
|
+
if (phase === "replace") {
|
|
36
|
+
if (input.toLowerCase() === "y") {
|
|
37
|
+
finish({ kind: "confirmed", names: selectedNames(), force: true });
|
|
38
|
+
} else if (input.toLowerCase() === "n" || key.escape) {
|
|
39
|
+
finish({ kind: "cancelled" });
|
|
40
|
+
}
|
|
41
|
+
return;
|
|
42
|
+
}
|
|
43
|
+
if (key.escape || input === "q" || key.ctrl && input === "c") {
|
|
44
|
+
finish({ kind: "cancelled" });
|
|
45
|
+
return;
|
|
46
|
+
}
|
|
47
|
+
if ((key.upArrow || input === "k") && optional.length > 0) {
|
|
48
|
+
setCursor((value) => (value - 1 + optional.length) % optional.length);
|
|
49
|
+
} else if ((key.downArrow || input === "j") && optional.length > 0) {
|
|
50
|
+
setCursor((value) => (value + 1) % optional.length);
|
|
51
|
+
} else if (input === " " && optional[cursor]) {
|
|
52
|
+
const name = optional[cursor].name;
|
|
53
|
+
setSelected((current) => {
|
|
54
|
+
const next = new Set(current);
|
|
55
|
+
if (next.has(name))
|
|
56
|
+
next.delete(name);
|
|
57
|
+
else
|
|
58
|
+
next.add(name);
|
|
59
|
+
return next;
|
|
60
|
+
});
|
|
61
|
+
} else if (key.return) {
|
|
62
|
+
const names = selectedNames();
|
|
63
|
+
const divergent = inventory.skills.some((skill) => names.includes(skill.name) && skill.status === "divergent");
|
|
64
|
+
if (divergent)
|
|
65
|
+
setPhase("replace");
|
|
66
|
+
else
|
|
67
|
+
finish({ kind: "confirmed", names, force: false });
|
|
68
|
+
}
|
|
69
|
+
});
|
|
70
|
+
const status = (value) => messages[value];
|
|
71
|
+
return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", width, children: [
|
|
72
|
+
/* @__PURE__ */ jsx(Text, { bold: true, children: messages.title }),
|
|
73
|
+
/* @__PURE__ */ jsx(Text, { children: truncateDisplay(`${inventory.package.name}@${inventory.package.version}`, width) }),
|
|
74
|
+
/* @__PURE__ */ jsx(Text, { children: truncateDisplay(`${messages.target}: ${inventory.target}`, width) }),
|
|
75
|
+
/* @__PURE__ */ jsx(Text, { children: " " }),
|
|
76
|
+
/* @__PURE__ */ jsx(Text, { bold: true, children: messages.defaultHeading }),
|
|
77
|
+
defaults.map((skill) => /* @__PURE__ */ jsx(Text, { children: truncateDisplay(` [x] ${skill.name} ${messages.locked} \xB7 ${status(skill.status)}`, width) }, skill.name)),
|
|
78
|
+
/* @__PURE__ */ jsx(Text, { children: " " }),
|
|
79
|
+
/* @__PURE__ */ jsx(Text, { bold: true, children: messages.optionalHeading }),
|
|
80
|
+
optional.length === 0 && /* @__PURE__ */ jsx(Text, { dimColor: true, children: ` ${messages.none}` }),
|
|
81
|
+
optional.map((skill, index) => /* @__PURE__ */ jsx(Text, { children: truncateDisplay(`${index === cursor ? "\u203A" : " "} ${selected.has(skill.name) ? "[x]" : "[ ]"} ${skill.name} ${status(skill.status)}`, width) }, skill.name)),
|
|
82
|
+
/* @__PURE__ */ jsx(Text, { children: " " }),
|
|
83
|
+
/* @__PURE__ */ jsx(Text, { color: phase === "replace" ? "yellow" : void 0, children: phase === "replace" ? messages.replaceTitle : messages.selectHelp }),
|
|
84
|
+
phase === "replace" && /* @__PURE__ */ jsx(Text, { children: messages.replaceHelp })
|
|
85
|
+
] });
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
// src/skills-tui/messages.ts
|
|
89
|
+
var skillsCatalogs = {
|
|
90
|
+
"en": {
|
|
91
|
+
title: "RSP Skill manager",
|
|
92
|
+
target: "Target",
|
|
93
|
+
defaultHeading: "Default lifecycle Skills",
|
|
94
|
+
optionalHeading: "Optional project Skills",
|
|
95
|
+
missing: "missing",
|
|
96
|
+
unchanged: "unchanged",
|
|
97
|
+
divergent: "divergent",
|
|
98
|
+
locked: "locked",
|
|
99
|
+
none: "none",
|
|
100
|
+
selectHelp: "\u2191/\u2193 move \xB7 Space select \xB7 Enter confirm \xB7 Esc cancel",
|
|
101
|
+
replaceTitle: "Replace divergent selected Skills?",
|
|
102
|
+
replaceHelp: "y replace \xB7 n cancel"
|
|
103
|
+
},
|
|
104
|
+
"zh-CN": {
|
|
105
|
+
title: "RSP Skill \u7BA1\u7406\u5668",
|
|
106
|
+
target: "\u76EE\u6807",
|
|
107
|
+
defaultHeading: "\u9ED8\u8BA4\u751F\u547D\u5468\u671F Skills",
|
|
108
|
+
optionalHeading: "\u53EF\u9009\u9879\u76EE Skills",
|
|
109
|
+
missing: "\u672A\u5B89\u88C5",
|
|
110
|
+
unchanged: "\u4E00\u81F4",
|
|
111
|
+
divergent: "\u6709\u5DEE\u5F02",
|
|
112
|
+
locked: "\u9501\u5B9A",
|
|
113
|
+
none: "\u65E0",
|
|
114
|
+
selectHelp: "\u2191/\u2193 \u79FB\u52A8 \xB7 \u7A7A\u683C\u9009\u62E9 \xB7 \u56DE\u8F66\u786E\u8BA4 \xB7 Esc \u53D6\u6D88",
|
|
115
|
+
replaceTitle: "\u66FF\u6362\u6240\u9009\u7684\u5DEE\u5F02 Skill\uFF1F",
|
|
116
|
+
replaceHelp: "y \u66FF\u6362 \xB7 n \u53D6\u6D88"
|
|
117
|
+
}
|
|
118
|
+
};
|
|
119
|
+
|
|
120
|
+
// src/skills-tui/entry.tsx
|
|
121
|
+
var signalExitCodes = { SIGHUP: 129, SIGINT: 130, SIGTERM: 143 };
|
|
122
|
+
var defaultRuntime = {
|
|
123
|
+
inspect: inspectPackagedSkillInventory,
|
|
124
|
+
render,
|
|
125
|
+
openSession: openTerminalSession,
|
|
126
|
+
host: process,
|
|
127
|
+
reportError: (message) => console.error(message)
|
|
128
|
+
};
|
|
129
|
+
async function runSkillsTui(locale, runtime = defaultRuntime) {
|
|
130
|
+
const screenReader = runtime.host.env.INK_SCREEN_READER === "true" || runtime.host.env.INK_SCREEN_READER === "1";
|
|
131
|
+
const session = runtime.openSession(runtime.host.stdout, { screenReader });
|
|
132
|
+
let instance;
|
|
133
|
+
let selection = { kind: "cancelled" };
|
|
134
|
+
const listeners = /* @__PURE__ */ new Map();
|
|
135
|
+
let cleaned = false;
|
|
136
|
+
const cleanup = () => {
|
|
137
|
+
if (cleaned)
|
|
138
|
+
return;
|
|
139
|
+
cleaned = true;
|
|
140
|
+
for (const [signal, listener] of listeners)
|
|
141
|
+
runtime.host.off(signal, listener);
|
|
142
|
+
listeners.clear();
|
|
143
|
+
instance?.unmount();
|
|
144
|
+
session.cleanup();
|
|
145
|
+
};
|
|
146
|
+
try {
|
|
147
|
+
const inventory = await runtime.inspect();
|
|
148
|
+
instance = runtime.render(ReactRuntime.createElement(SkillsApp, {
|
|
149
|
+
inventory,
|
|
150
|
+
messages: skillsCatalogs[locale],
|
|
151
|
+
onComplete: (value) => {
|
|
152
|
+
selection = value;
|
|
153
|
+
}
|
|
154
|
+
}), { exitOnCtrlC: false, patchConsole: false });
|
|
155
|
+
for (const signal of Object.keys(signalExitCodes)) {
|
|
156
|
+
const listener = () => {
|
|
157
|
+
cleanup();
|
|
158
|
+
runtime.host.exit(signalExitCodes[signal]);
|
|
159
|
+
};
|
|
160
|
+
listeners.set(signal, listener);
|
|
161
|
+
runtime.host.once(signal, listener);
|
|
162
|
+
}
|
|
163
|
+
await instance.waitUntilExit();
|
|
164
|
+
cleanup();
|
|
165
|
+
return selection;
|
|
166
|
+
} catch (error) {
|
|
167
|
+
cleanup();
|
|
168
|
+
runtime.reportError(` Error: ${error instanceof Error ? error.message : String(error)}`);
|
|
169
|
+
return { kind: "error" };
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
export {
|
|
173
|
+
runSkillsTui
|
|
174
|
+
};
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oevery/rsp",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "3.1.0-beta.
|
|
4
|
+
"version": "3.1.0-beta.2",
|
|
5
5
|
"description": "RSP (Reliable Software Practice), a repository-native engineering workflow for humans and AI agents",
|
|
6
6
|
"author": "oevery",
|
|
7
7
|
"license": "MIT",
|
|
@@ -38,9 +38,10 @@
|
|
|
38
38
|
"scripts": {
|
|
39
39
|
"prepare": "pnpm run build",
|
|
40
40
|
"release:check": "pnpm run release:metadata-check && pnpm run build && pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run release:package-check",
|
|
41
|
+
"release:candidate-check": "node scripts/release-candidate-check.mjs && pnpm run release:check",
|
|
41
42
|
"release:metadata-check": "node scripts/release-metadata-check.mjs",
|
|
42
43
|
"release:package-check": "node scripts/clean-install-check.mjs",
|
|
43
|
-
"prepublishOnly": "pnpm run release:check",
|
|
44
|
+
"prepublishOnly": "pnpm run release:candidate-check",
|
|
44
45
|
"build": "tsup",
|
|
45
46
|
"dev": "tsup --watch",
|
|
46
47
|
"lint": "eslint .",
|
|
@@ -53,17 +54,17 @@
|
|
|
53
54
|
"citty": "^0.2.2",
|
|
54
55
|
"ink": "~7.1.1",
|
|
55
56
|
"picocolors": "^1.1.1",
|
|
56
|
-
"react": "~19.2.
|
|
57
|
+
"react": "~19.2.8",
|
|
57
58
|
"yaml": "^2.9.0"
|
|
58
59
|
},
|
|
59
60
|
"devDependencies": {
|
|
60
|
-
"@antfu/eslint-config": "^9.
|
|
61
|
-
"@types/node": "^22.
|
|
62
|
-
"@types/react": "19.2.
|
|
63
|
-
"eslint": "^10.
|
|
61
|
+
"@antfu/eslint-config": "^9.2.0",
|
|
62
|
+
"@types/node": "^22.20.1",
|
|
63
|
+
"@types/react": "19.2.17",
|
|
64
|
+
"eslint": "^10.8.0",
|
|
64
65
|
"ink-testing-library": "4.0.0",
|
|
65
|
-
"tsup": "^8.
|
|
66
|
-
"typescript": "^5.
|
|
67
|
-
"vitest": "^4.1.
|
|
66
|
+
"tsup": "^8.5.1",
|
|
67
|
+
"typescript": "^5.9.3",
|
|
68
|
+
"vitest": "^4.1.10"
|
|
68
69
|
}
|
|
69
70
|
}
|
package/rules/rsp-rules.md
CHANGED
|
@@ -18,28 +18,25 @@ This file is the minimal fallback protocol for agents that cannot load the `rsp`
|
|
|
18
18
|
|
|
19
19
|
## Core
|
|
20
20
|
|
|
21
|
-
- Choose response language and artifact language independently. Localize
|
|
21
|
+
- Choose response language and artifact language independently. Localize response prose from the explicit request, scoped instructions, then conversation language; write authorized artifacts from the explicit request, scoped instructions, existing artifact language, then conversation language. Preserve canonical headings, WorkRefs, paths, commands, identifiers, and machine values.
|
|
22
22
|
- Write persistent artifact prose in domain, system, user, or operator language. Mention AI or agents only when they are real product actors, consumers, interface participants, or constraints; agent authorship, execution narration, or convenience for a hypothetical future agent is not durable content.
|
|
23
23
|
- `changes/` stores open work; `archives/` stores completed history; `specs/` stores stable current facts; the configured Decision Record path stores lasting rationale.
|
|
24
24
|
- Every Change is one Markdown file with explicit `kind` and the fixed `Proposal`, `Spec`, `Design`, `Tasks`, `Verify`, and `Blockers` sections.
|
|
25
25
|
- A Change is a convergent current-plan and final-evidence snapshot, not an append-only execution log. Keep Tasks aligned with current delivery and Verify limited to final decisive commands or scenarios, results, proven scope, omitted or unavailable coverage, and remaining risk. Replace superseded plans and evidence; retain an earlier failure only when it still explains a current blocker, coverage gap, or risk.
|
|
26
26
|
- In a Change `Blockers` section, `- requires \`<change-work-ref>\`: <reason>` declares an exact dependency on another executable Change. Other meaningful blocker prose remains external and is never inferred as a dependency.
|
|
27
27
|
- Executable Change identities are either `<change>` or `<group>/<change>`. Recursive work paths are unsupported.
|
|
28
|
-
- A Change Group is the only composite
|
|
29
|
-
- `<group>/brief`, physically stored as `<group>/00-brief.md`, owns Goal, Scope, Shared Constraints, Slices, Completion Conditions, Durable Outcomes, and Blockers. Every direct child must be declared by `Slices`, and every declared slice must be open or archived.
|
|
30
|
-
- A Group Brief is not executable or focusable. Read it before a grouped child, archive children independently, and use `rsp group close <group>` only after derived completion passes. Archived Group identities cannot be reopened.
|
|
28
|
+
- A Change Group is the only composite shape and requires at least two independent direct children. Its non-executable, non-focusable `<group>/brief` at `<group>/00-brief.md` owns shared scope, constraints, declared Slices, completion, durable outcomes, and blockers. Read it before a child; archive children independently and close only a derived-complete Group.
|
|
31
29
|
- A file and directory cannot claim the same work identity.
|
|
32
|
-
-
|
|
33
|
-
- Initialization, repair, status inspection, Spec creation, and index generation use the same no-follow managed-path rules; recursive Specs may use only real directories and regular files.
|
|
34
|
-
- Final managed files, including the project `AGENTS.md`, focus markers, fallback/config files, indexes, and placeholders, must be regular files rather than symlinks or special entries.
|
|
30
|
+
- Managed roots, Group prefixes, recursive Spec paths, and final managed files must be real directories or regular files as applicable. Initialization, repair, inspection, Spec/index work, and mutations use shared no-follow checks; symlinks, special entries, missing roots, and incomplete inspection fail closed.
|
|
35
31
|
- `status`, `check`, and `doctor` share work-tree, Change Group, and dependency inspection. They fail visibly on unsupported structure, membership mismatches, malformed or missing dependency targets, self-dependencies, and cycles. With no focus, status uses Group Brief declaration order and derived blockers to recommend the first executable slice.
|
|
36
|
-
- `status` derives
|
|
32
|
+
- `status` derives blockers, exact edges and reasons, ready Changes, and stable waves without persisted graph or delivery state. Filtered views retain prerequisite context. Archived prerequisites resolve; invalid or incompletely inspected graphs fail closed.
|
|
37
33
|
- Parallel Changes in one Group follow the Brief `Slices` declaration order in plan output; unrelated work uses stable lexical ordering.
|
|
38
34
|
- A Group Brief blocker is inherited by its direct child Changes as an external blocker; it does not create inferred dependency edges.
|
|
39
35
|
- Persist only `open` and `archived`; readiness, blockers, verification, and next actions are derived.
|
|
40
|
-
- Ordinary implementation is the default after unexplained failures
|
|
41
|
-
-
|
|
42
|
-
- Route
|
|
36
|
+
- Ordinary implementation is the default after unexplained failures are ruled out. Use test-first only when authority requires it or a concrete risk makes pre-mutation failure materially safer. Retain a new test only when it protects observable behavior or a real boundary with distinct proportionate value; otherwise remove the temporary probe and use decisive final verification.
|
|
37
|
+
- This fallback does not emulate `rsp-manage`, even when project configuration selects automatic activation or local closeout. Invalid configuration grants nothing and remains visible. For an explicit managed request or an automatically eligible completion/continuation, resolve the smallest owner using ordinary Core rules: reuse one unambiguous selected ready Change, send tiny settled work direct without a synthetic Change, and shape only independently authorized planning artifacts for clear non-trivial work. Configuration grants no planning or product-mutation authority. Stop for material product, acceptance, interface, scope, mutation, or external-action decisions. Perform at most one ordinary Core or Discipline action, return its WorkRef and next action, and never dispatch, auto-continue successors, loop review corrections, archive, stage, commit, push, or persist controller state. Load the `rsp` and `rsp-manage` Skills when controller behavior is required.
|
|
38
|
+
- Route one explicit isolated domain, module/seam, or evidence-seeking question to `rsp-design` when available, or use a compact manual design pass. Without a selected Change, use report-only Pre-Change Design without inventing a WorkRef only when the question is already bounded; when outcome, scope, non-goals, acceptance, or decomposition remains materially unclear, route to Shape. With a selected Change, return evidence, alternatives, owner decisions, and any authorized planned-design update to the same WorkRef. Do not implement or write durable current truth from either mode.
|
|
39
|
+
- Route release documentation only for an explicit release operation with a confirmed identity or range and unfinished surfaces; no Release Change is required. Confirm identity only from explicit instruction or authoritative configuration. Until then stay version-neutral and do not mutate versioned surfaces. Keep ledgers transient; use an optional Release Change only for material decisions, coordination, recovery, blockers, or acceptance. This route grants no Git, publication, deployment, or approval authority.
|
|
43
40
|
- Do not infer current work from open Changes or filenames.
|
|
44
41
|
- Prefer RSP commands for deterministic setup, status, validation, repair, focus, index, and archive operations.
|
|
45
42
|
|
|
@@ -49,7 +46,8 @@ This file is the minimal fallback protocol for agents that cannot load the `rsp`
|
|
|
49
46
|
- Project-owned `CONTEXT.md` owns stable navigation or scoped current context, while project-owned `AGENTS.md` owns stable operating instructions. Preserve their conventions and never treat RSP as their owner.
|
|
50
47
|
- Before archive, decide independently whether current facts need a Spec or scoped-instruction update and whether lasting rationale needs a Decision Record.
|
|
51
48
|
- Before archive, compress the Change to its final outcome, current design, completed delivery tasks, final decisive verification, and unresolved risks. Keep RED/GREEN/REFACTOR cycles, temporary probes, command transcripts, and step-by-step review corrections in the response instead of the Change or Archive.
|
|
52
|
-
- After required durable updates, Core recommends explicit archive before final Git delivery.
|
|
49
|
+
- After required durable updates, Core recommends explicit archive before final Git delivery. Ordinary work requires separate Git and release authority; fallback Core never executes archive, stage, commit, push, or publication.
|
|
50
|
+
- When loaded Core or qualified Manage has already derived one authorized RSP-owned commit boundary, prefer the `rsp-commit` Skill for exact staging, repository-consistent structured message construction, one local commit, and complete post-commit observation. If that Skill alone is unavailable, loaded Core may provide its equivalent bounded manual action against the same owner; this minimal fallback still grants and executes no Git action.
|
|
53
51
|
- Decision Records are for hard-to-reverse choices with real tradeoffs; they do not duplicate current facts.
|
|
54
52
|
- Change Spec deltas are planning aids and are never promoted automatically into Specs or Decision Records.
|
|
55
53
|
- Keep task history, debugging notes, and transient execution state out of Specs and Decision Records.
|
package/skills/rsp/SKILL.md
CHANGED
|
@@ -4,225 +4,91 @@ description: Use this skill when initializing RSP, operating an existing .rsp pr
|
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
6
|
author: oevery
|
|
7
|
-
version: "2026.07.
|
|
7
|
+
version: "2026.07.26.3"
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
# RSP Skill
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Use RSP to derive one current action from project authority and durable work artifacts. This Skill is the preferred operational guide; `.rsp/rsp-rules.md` is the runtime fallback when the Skill is unavailable.
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
Nearest project instructions and relevant `CONTEXT.md` remain authoritative. Choose response and artifact languages independently: localize human-facing response prose, but preserve canonical RSP headings, WorkRefs, paths, commands, identifiers, and machine values. Write persistent artifacts in domain, system, user, or operator language; mention AI or agents only when they are actual product actors or constraints.
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
## Scope
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
Write persistent artifacts in domain, system, user, or operator language. Mention AI or agents only when they are actual product actors, consumers, interface participants, or constraints; using AI to perform the work is not itself a durable fact.
|
|
21
|
-
|
|
22
|
-
## When to use
|
|
23
|
-
|
|
24
|
-
- Use for RSP setup, repair, focused RSP work, and pre-archive durable decisions.
|
|
25
|
-
- Use when a user explicitly asks to adopt, inspect, or operate the RSP workflow.
|
|
26
|
-
|
|
27
|
-
## When not to use
|
|
28
|
-
|
|
29
|
-
- Do not load for general coding tasks unrelated to `.rsp/`.
|
|
30
|
-
- Do not load when the repository does not use RSP and the user did not ask to adopt it.
|
|
31
|
-
- Do not create an RSP change for a simple current-session task unless the user explicitly wants RSP tracking.
|
|
32
|
-
- Do not treat this skill or the fallback protocol as a replacement for nearest project `AGENTS.md` instructions or relevant module `CONTEXT.md`.
|
|
18
|
+
Use this Skill for RSP setup or repair, focused `.rsp/` work, and the durable-update decision before archive. Do not use it for unrelated coding or create a Change for a simple session task unless the user explicitly requests tracking.
|
|
33
19
|
|
|
34
20
|
## Derive one next action
|
|
35
21
|
|
|
36
|
-
|
|
22
|
+
Read user intent, nearest authority, `rsp status --json`, the selected Change and its readiness, fresh verification evidence, and blockers. Stages are derived guidance, never persisted state.
|
|
37
23
|
|
|
38
|
-
|
|
24
|
+
Apply these routes in order:
|
|
39
25
|
|
|
40
|
-
|
|
26
|
+
1. Stop for ambiguous authority or selection and return the one required input and its owner. For a material owner decision inside an explicit managed request, continue to the Shape preflight in route 2 so repository inspection precedes the single owner question; otherwise stop here.
|
|
27
|
+
2. For a requested completion or continuation that is not a report-only review or release operation, read [managed routing](references/managed-routing.md) when the request is explicitly managed or the effective status policy has `manage.activation: auto`. It owns owner preflight, qualification, successor discovery, bounded review convergence, and lifecycle/Git separation. Select `rsp-manage` only after that preflight for an eligible selected ready Change or shallow Group; otherwise return the ordinary Core or Discipline action. Automatic activation grants controller selection only; planning, product mutation, lifecycle, Git, and external authority remain separately derived.
|
|
28
|
+
3. Route an explicit report-only review with fixed scope to `rsp-review` when available, otherwise perform the same read-only review manually.
|
|
29
|
+
4. Route an explicit release-documentation, finalization, publication, or reconciliation operation through [Release operations](#release-operations) before ordinary Change routing.
|
|
30
|
+
5. Route one explicit isolated material domain, module/seam, or evidence-seeking design question to `rsp-design` when available. Without a selected Change, use report-only Pre-Change Design only when the question is already bounded; return its result to the user without inventing a WorkRef or artifact. With a selected Change, return the result to the same WorkRef. Its manual fallback inspects authority and the live path, compares credible alternatives, and separates evidence from owner choice without implementation or durable-truth mutation.
|
|
31
|
+
6. With no selected Change, name one ready WorkRef and direct focus action. For tiny settled work, return the direct engineering action. When outcome, scope, non-goals, acceptance, or decomposition is materially unclear, use `rsp-shape` when available and Change mutation is authorized; otherwise manually create or refine one Change to the same ready boundary.
|
|
32
|
+
7. If the Change is not shape-ready, route to Shape under the same authority rule.
|
|
33
|
+
8. For incomplete implementation or stale, missing, or failed verification, use [Implementation evidence](#implementation-evidence).
|
|
34
|
+
9. When Tasks and required verification pass without blockers, perform the durable decision. Do not infer a release operation from Change completion.
|
|
41
35
|
|
|
42
|
-
|
|
43
|
-
- **TDD:** there is no unexplained failure, the required or corrected behavior is clear, and test-first work is explicitly required by the user, selected Change, or project instructions, or a concrete changed risk makes an observed pre-mutation RED materially safer. Concrete risks include public APIs or protocols, persisted data, security or money, concurrency or cancellation, complex state transitions, and defects that escaped to production. Select `rsp-tdd` only when it is available; otherwise use the manual TDD fallback: observe the focused RED, make the minimum GREEN change, optionally REFACTOR while green, then rerun required checks. Behavior being testable, a test being possible, or the work being a fix is not sufficient by itself.
|
|
44
|
-
- **Ordinary implementation:** this is the default when diagnosis does not apply and no TDD gate above is met. Continue with ordinary `rsp-implement` when the required behavior, cause, or edit is sufficiently evidenced, or use the single manual implementation/verification action when that Skill is unavailable.
|
|
36
|
+
State the derived stage, one next action, required input, returned owner, and decisive evidence. Name at most one optional capability, only when it is the next action and appears in the host's loaded Skill inventory. Missing capabilities never invalidate RSP: give the manual fallback against the same owner. When Core or qualified Manage has derived one authorized RSP-owned local commit boundary, route exact staging, structured message construction, local commit execution, and post-commit observation to `rsp-commit`; if unavailable, use the bounded manual action in durable review against the same owner. Do not preload, enumerate, or recursively invoke optional capabilities.
|
|
45
37
|
|
|
46
|
-
|
|
38
|
+
### Implementation evidence
|
|
47
39
|
|
|
48
|
-
|
|
40
|
+
- **Diagnosis first:** diagnosis takes precedence over TDD for an evidenced but unexplained, conflicting, intermittent, or multi-layer failure. Use `rsp-diagnose` when available; its manual fallback reproduces, locates, and tests the smallest discriminating hypothesis. Do not encode an unexplained symptom as a guessed regression test.
|
|
41
|
+
- **TDD when justified:** use `rsp-tdd` only when test-first is explicitly required by the user, Change, or project instructions, or when a concrete changed risk makes a pre-mutation RED materially safer. Public contracts, persisted data, security or money, concurrency, complex transitions, and escaped defects qualify; mere testability or being a fix does not. Its manual fallback observes the focused RED, makes the minimum GREEN change, and refactors only while green.
|
|
42
|
+
- **Ordinary implementation by default:** use `rsp-implement`, or the equivalent bounded edit and verification, once the behavior, cause, and owner are sufficiently evidenced.
|
|
49
43
|
|
|
50
|
-
|
|
44
|
+
All branches return evidence, Tasks, Verify updates, and blockers to the same Change. Fresh verification is required, but a new test is only one option; use the cheapest decisive check that covers the changed risk.
|
|
51
45
|
|
|
52
|
-
|
|
46
|
+
### Release operations
|
|
53
47
|
|
|
54
|
-
|
|
48
|
+
Route here only when the user explicitly requests release documentation, finalization, publication, or reconciliation and the operation has a confirmed identity or range with unfinished release-surface work. A selected Change is not required, and lifecycle stage or archive readiness alone is insufficient.
|
|
55
49
|
|
|
56
|
-
|
|
50
|
+
Release identity is an owner decision confirmed only by explicit user instruction or authoritative repository release configuration. Never infer it from version order, a previous prerelease, commits, or planned prose. Until confirmation, keep ledgers version-neutral and leave manifests, target changelog headings, exact-version commands, versioned notes, and tag comparisons unchanged.
|
|
57
51
|
|
|
58
|
-
|
|
52
|
+
Select `rsp-release-docs` when available or use its manual evidence-led fallback. An explicit tag, hosted release, registry publication, or equivalent public action must pass its **Finalize for publication** branch against a clean exact candidate after implementation Change closeout. Finalize versioned shipped surfaces in a separate release commit when Git delivery is authorized. The credential-free `ready` or `not ready` handoff never executes or grants commit, tag, push, release creation, publication, deployment, or approval authority.
|
|
59
53
|
|
|
60
|
-
|
|
54
|
+
Use an optional Release Change only for material decisions, cross-stage coordination, recovery, blockers, or acceptance needing a persistent owner—never for a mechanical checklist. After observed publication, use **Reconcile published release** for unfinished verification or authorized mutable-surface corrections; preserve immutable history and assign drift to a corrective version or owner.
|
|
61
55
|
|
|
62
|
-
|
|
63
|
-
2. If the user explicitly requests managed continuation, select `rsp-manage` only when it is available. Its eligibility gate activates only for one focused ready Change with genuinely independent slices, long authorized continuation, or interruption recovery; an ineligible request returns the exact ordinary Core or Discipline next action without mutation or controller artifacts. Managed routing is never implicit and grants no lifecycle, Git, publication, deployment, approval, or human-acceptance authority.
|
|
64
|
-
3. If the user requests a report-only review against a fixed scope, select `rsp-review` only when it is available; otherwise name the manual read-only review and return its findings to the selected Change's Tasks, Verify, or Blockers.
|
|
65
|
-
4. If the user explicitly requests a tag, hosted release, registry publication, or published-release reconciliation, resolve exactly one selected or explicitly named archived release owner with the confirmed identity and range, then run the `rsp-release-docs` finalization or reconciliation branch and return its credential-free result. This gate precedes ordinary no-focus and implementation routing so a post-archive release owner is not replaced by an unrelated ready Change. Missing owner evidence returns the exact required release owner; the gate never executes or grants the external action.
|
|
66
|
-
5. If no Change is selected, use the status plan to name one ready WorkRef and the direct focus action. For tiny settled work, return the direct engineering action without creating RSP state. For unclear non-trivial work, select `rsp-shape` only when it is available and the user authorized its Change mutation; otherwise give the manual fallback of creating or refining one Change.
|
|
67
|
-
6. If the user or Shape has isolated one material domain, module/seam, or evidence-seeking design question for the selected Change, select `rsp-design` when available; otherwise return the compact manual design fallback: inspect project authority and the live path, compare credible alternatives, separate evidence from owner choice, and return the result to the same WorkRef without implementation or durable-truth mutation.
|
|
68
|
-
7. If the selected Change is not shape-ready and no bounded design question has been isolated, select `rsp-shape` under the same authority rule or give the manual fallback of completing its Proposal, Spec, Design, Tasks, Verify, and Blockers.
|
|
69
|
-
8. If a shape-ready Change has incomplete implementation tasks, or its required verification is missing, stale, or failed, apply the implementation-evidence routing above. Select only its resulting available capability when authorized; otherwise name its manual fallback owned by that Change.
|
|
70
|
-
9. If implementation Tasks and required verification pass with no blocker, and the selected Change meets both ordinary release-documentation conditions above, select `rsp-release-docs` under the same availability rule or use its manual fallback. Return its evidence and surface dispositions to the same Change.
|
|
71
|
-
10. Otherwise, when required Tasks and verification pass with no blocker, perform the Core durable decision. Archive only after required current facts and rationale are written or explicitly judged unnecessary. Recommend explicit archive as the next action before final Git delivery; Core does not execute archive or grant authority to stage, commit, push, or publish. Keep each completed Change independently reviewable. If later Git authority is granted, deliver that Change as its own logical commit before a separately owned Release Change finalizes versioned shipped surfaces in a dedicated release commit.
|
|
56
|
+
## Operate the selected Change
|
|
72
57
|
|
|
73
|
-
|
|
58
|
+
Read the focused Change, its sibling Group Brief when grouped, and only the relevant Specs and Decision Records before implementation. Run `npx -y @oevery/rsp check --focused` before treating it as ready. Only `focus.d/` markers select current work; open filenames do not. Preserve one explicit `kind` and the canonical Proposal, Spec, Design, Tasks, Verify, and Blockers sections.
|
|
74
59
|
|
|
75
|
-
|
|
60
|
+
Keep the Change a convergent snapshot of the current plan and final decisive evidence. Replace superseded content; keep routine attempts, RED/GREEN chronology, temporary probes, and command transcripts in the response. Update Tasks, Verify, and any invalidated Proposal, Spec, or Design in the same session.
|
|
76
61
|
|
|
77
|
-
|
|
62
|
+
Persist only `open` and `archived`; derive readiness, blockers, stage, and next actions. Do not infer implementation, review, Git, publication, or approval authority from focus, readiness, routing, or capability availability.
|
|
78
63
|
|
|
79
|
-
|
|
64
|
+
Load detailed procedures only when their path is active:
|
|
80
65
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
5. For safe deterministic repairs, run `npx -y @oevery/rsp doctor --fix` or `npx -y @oevery/rsp update`.
|
|
86
|
-
6. When auditing manually, verify `.rsp/`, managed roots, and nested Spec parents are real directories; the project `AGENTS.md`, managed markers, fallback/config files, indexes, and placeholders are regular files; `AGENTS.md` has the managed block; `specs/design.md` and the configured Decision Record directory exist; every group has one valid brief with matching direct children; work and archive trees are flat or one group level; and `focus.d/` markers match executable Changes.
|
|
87
|
-
7. Treat `doctor --fix` `fixed` entries as actual filesystem changes. An empty `fixed` array or `No safe fixes needed.` means the repair pass changed nothing.
|
|
88
|
-
8. Do not use repair commands for semantic decisions such as stale focus removal, durable updates, or archive readiness.
|
|
66
|
+
- Read [setup and repair](references/setup-repair.md) before initializing, auditing, migrating, or repairing RSP state.
|
|
67
|
+
- Read [groups and dependencies](references/groups-dependencies.md) before creating, focusing, planning, or closing grouped/dependent work.
|
|
68
|
+
- Read [conflict handling](references/conflict-handling.md) only when an active merge, rebase, or cherry-pick conflict intersects authorized work.
|
|
69
|
+
- Read [durable review](references/durable-review.md) only after required Tasks and verification pass, or when auditing archive readiness.
|
|
89
70
|
|
|
90
|
-
|
|
71
|
+
## Ownership and safety
|
|
91
72
|
|
|
92
|
-
|
|
93
|
-
2. Treat only `focus.d/` markers as current RSP work; do not treat unfocused files in `changes/` as current work unless the user explicitly asks or you run `npx -y @oevery/rsp focus <name>`.
|
|
94
|
-
3. Resolve executable Change names as either `<change>` or one direct `<group>/<change>` child. Require a real `changes/` root and real existing `focus.d/`, `archives/`, and group prefixes; reject symlinks, incomplete inspection, deeper paths, and file/directory identity collisions.
|
|
95
|
-
4. Use a Change Group only for at least two independently executable Changes sharing one goal or completion contract. Create it with `npx -y @oevery/rsp group create <group> [goal]`, then replace the brief placeholders and declare every direct child identity and boundary under `Slices` before creating children.
|
|
96
|
-
5. Treat logical `<group>/brief`, physically stored as `<group>/00-brief.md`, as non-executable and non-focusable. For grouped work, read it before the selected child Change. Its `Slices` declaration order guides navigation; a Brief blocker is inherited as an external blocker by every direct child without creating edges. Archive children independently, then close only the brief with `npx -y @oevery/rsp group close <group>` when all group gates pass.
|
|
97
|
-
6. Declare an exact prerequisite only as `- requires \`<change-work-ref>\`: <reason>` under the dependent Change's `Blockers`. Targets must be executable Changes, not Group Briefs. Keep external blockers as ordinary prose and never infer an edge from them.
|
|
98
|
-
7. Use `npx -y @oevery/rsp status --json` as the derived dependency view. Read `plan.nodes`, `plan.ready`, `plan.edges`, `plan.blocked`, and `plan.waves`; nodes distinguish selected Changes from prerequisite context, and each edge reads as “`change` requires `requires`” with `reason` and `state`. Filtered plans retain the transitive prerequisite closure needed to explain the selection. Human status renders the same flat graph as a dependency forest; do not infer nested JSON ownership from that presentation. Do not create or maintain a separate graph or copy live delivery state into a Group Brief. Archived prerequisites resolve without rewriting the dependent Change, while incomplete archive inspection produces no ready plan.
|
|
99
|
-
8. Read the focused change before editing code.
|
|
100
|
-
9. If a focused change is missing an explicit `kind`, repair the frontmatter before continuing.
|
|
101
|
-
10. Run `npx -y @oevery/rsp check --focused` before treating focused work as ready; resolve dependency errors, placeholders, or clarification warnings when they represent real unfinished content.
|
|
102
|
-
11. Treat `rsp check` warnings as deterministic hygiene signals, not as the durable-update decision.
|
|
103
|
-
12. Use `npx -y @oevery/rsp create <name> --lite` only when the user explicitly wants RSP tracking for a small, straightforward change.
|
|
104
|
-
13. Convert actionable `## Tasks` checkboxes into your agent-local task tracker when one is available.
|
|
105
|
-
14. Keep implementation sequential by default; parallelize only independent read-only discovery or mechanical checks.
|
|
106
|
-
15. Update `## Tasks`, `## Verify`, and any invalidated `## Proposal`, `## Spec`, or `## Design` content in the same working session as implementation facts change.
|
|
107
|
-
16. Keep the selected Change as a convergent snapshot of the current plan and final decisive evidence. Replace stale or superseded content; keep routine attempts, RED/GREEN loops, command transcripts, and correction chronology in the response, then compress any material history to final outcomes, coverage, omissions, and unresolved risks before archive.
|
|
108
|
-
17. Keep temporary debugging notes, task history, and command transcripts out of `specs/` and project-owned `AGENTS.md` instructions.
|
|
73
|
+
Route planned design to the selected Change; stable implemented facts to the smallest relevant Spec or authorized scoped instruction; lasting rationale to one exact Decision Record; stable navigation to project-owned `CONTEXT.md`; stable operating rules to project-owned `AGENTS.md`; and temporary continuation to the response. Never write planned state as current truth or duplicate facts into rationale.
|
|
109
74
|
|
|
110
|
-
|
|
75
|
+
Use RSP commands for managed setup, focus, repair, indexes, and archive. Do not directly create command-owned files, edit generated indexes or `.rsp/rsp-rules.md` as durable truth, or modify the managed RSP block. Preserve unrelated work. Core recommends explicit archive only after the durable decision; it does not execute archive or grant staging, commit, push, publication, deletion, deployment, approval, or human-acceptance authority. The qualified Manage rules in [managed routing](references/managed-routing.md) are the sole scoped exceptions.
|
|
111
76
|
|
|
112
|
-
|
|
77
|
+
When accepted work remains, return a localized continuation with these semantic fields in order: `WorkRef`, `Authority`, `Current state`, `Changed artifacts`, `Fresh verification`, `Blockers`, `Next action`. Preserve technical values. The continuation points to existing owners, is not a second state store, and must not be persisted without explicit path authority. On resume, reopen its pointers, inspect drift, and refresh decisive evidence.
|
|
113
78
|
|
|
114
|
-
|
|
115
|
-
| --- | --- | --- |
|
|
116
|
-
| Planned future design | selected Change `## Design` | Never write planned state as current truth. |
|
|
117
|
-
| Implemented stable current facts | smallest relevant Spec, usually `.rsp/specs/design.md` or an existing domain Spec | Write only observed stable facts under authority. |
|
|
118
|
-
| Lasting rationale and tradeoffs | one exact file under `durableReview.decisionRecordsPath` | Judge independently from current facts; do not duplicate them. |
|
|
119
|
-
| Stable scoped navigation or current context | project-owned `CONTEXT.md`, when that convention exists | Preserve project ownership and edit only with explicit authority. |
|
|
120
|
-
| Stable operating instructions | nearest project-owned `AGENTS.md` outside the managed RSP block | Preserve project ownership and edit only with explicit authority. |
|
|
121
|
-
| Temporary execution state | response continuation | Not durable truth; write a file only when explicitly authorized. |
|
|
79
|
+
## Durable decision output
|
|
122
80
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
```md
|
|
126
|
-
## <localized RSP Continuation heading>
|
|
127
|
-
- <localized WorkRef label>: <selected Change>
|
|
128
|
-
- <localized Authority label>: <project, Change, Spec, decision, or report pointers>
|
|
129
|
-
- <localized Current state label>: <completed, partial, failed, unavailable, or blocked plus decisive state>
|
|
130
|
-
- <localized Changed artifacts label>: <paths or none>
|
|
131
|
-
- <localized Fresh verification label>: <command and result, or pending reason>
|
|
132
|
-
- <localized Blockers label>: <exact blocker and owner, or none>
|
|
133
|
-
- <localized Next action label>: <smallest bounded action and owner>
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
Treat this continuation shape as semantic field order rather than fixed English wording. Localize its human-facing title and labels to the response language while preserving WorkRefs, paths, commands, identifiers, and machine-consumed values. A localized label may retain a technical token in parentheses but must not use that English token alone; for example, use `工作引用(WorkRef)` in a Chinese response. Do not use the response language to rewrite referenced project artifact prose.
|
|
137
|
-
|
|
138
|
-
The continuation points to existing owners; it is not a second state store. On resume, reopen every authority pointer, inspect worktree and artifact drift, and refresh any verification supporting the next action. Never create hidden handoff/controller state or persist the continuation without explicit path authority.
|
|
139
|
-
|
|
140
|
-
### Handle an active Git conflict
|
|
141
|
-
|
|
142
|
-
When a merge, rebase, or cherry-pick conflict intersects authorized implementation:
|
|
143
|
-
|
|
144
|
-
1. Inspect the exact Git operation, conflicted paths, current index/worktree, and pre-existing user changes.
|
|
145
|
-
2. Interpret base, ours, and theirs in that operation; trace the relevant behavior and authority instead of choosing a side mechanically.
|
|
146
|
-
3. Resolve only evidenced content inside the WorkRef and mutation authority. Preserve unrelated work and do not stage the resolution unless separately authorized.
|
|
147
|
-
4. Stop when the conflict includes unrelated user work, an unresolved product decision, incomplete side/base evidence, or out-of-scope content. Return the exact conflict and required owner input in the continuation.
|
|
148
|
-
5. After an authorized working-tree resolution, rerun affected checks and return their fresh result.
|
|
149
|
-
|
|
150
|
-
Do not continue or abort the Git operation, commit, push, or infer Git delivery authority from implementation or conflict-resolution authority. RSP does not need a separate merge-conflict Skill for this fallback.
|
|
151
|
-
|
|
152
|
-
### Pre-archive durable decision
|
|
153
|
-
|
|
154
|
-
1. Run `npx -y @oevery/rsp check --focused` for focused work, or `npx -y @oevery/rsp check` when reviewing all open changes.
|
|
155
|
-
2. Run `npx -y @oevery/rsp show --focused --json` or `npx -y @oevery/rsp ready <name> --json` to collect readiness, warnings, context paths, and `durableReview` guidance.
|
|
156
|
-
3. Treat `durableReview.factCandidateTargets` and `durableReview.decisionRecordsPath` as advisory routing context, not as permission to edit generated indexes or invent a Decision Record filename.
|
|
157
|
-
4. Treat `Spec` delta markers (`### ADDED`, `### MODIFIED`, `### REMOVED`) as planning aids only; do not merge them automatically.
|
|
158
|
-
5. Read only the current Change, relevant Specs and Decision Records, nearest project-owned `AGENTS.md`, and code files needed for the semantic decision.
|
|
159
|
-
6. Produce the durable decision output before archiving.
|
|
160
|
-
|
|
161
|
-
## Durable decision
|
|
162
|
-
|
|
163
|
-
Choose one current-fact decision and one rationale decision independently.
|
|
164
|
-
|
|
165
|
-
Current facts:
|
|
166
|
-
|
|
167
|
-
- `No current-fact update needed`
|
|
168
|
-
- `Update existing spec or scoped instruction`
|
|
169
|
-
- `Create a new durable spec` only when the knowledge is project-level, reusable, and does not fit `specs/design.md`, an existing spec, or a scoped project instruction
|
|
170
|
-
|
|
171
|
-
Rationale:
|
|
172
|
-
|
|
173
|
-
- `No Decision Record needed`
|
|
174
|
-
- `Create or update a Decision Record`
|
|
175
|
-
|
|
176
|
-
Prefer no update on either axis when there is no concrete stable fact or lasting rationale worth rereading.
|
|
177
|
-
|
|
178
|
-
Write a durable update only when one of these is true:
|
|
179
|
-
|
|
180
|
-
- the change altered stable system behavior
|
|
181
|
-
- the change changed a project boundary, default, or constraint
|
|
182
|
-
- future agents or developers would likely make mistakes without the fact
|
|
183
|
-
- the fact is worth rereading in later sessions as durable project knowledge
|
|
184
|
-
|
|
185
|
-
Create or update a Decision Record only when the choice is hard to reverse, would be surprising without context, and reflects a real tradeoff. Decision Records own rationale, alternatives, tradeoffs, and consequences; Specs own what is currently true.
|
|
186
|
-
|
|
187
|
-
Apply the artifact-routing matrix and choose the smallest correct target:
|
|
188
|
-
|
|
189
|
-
- project-wide design, boundaries, defaults, and durable context -> `.rsp/specs/design.md`
|
|
190
|
-
- stable project or module operating instructions -> nearest project-owned `AGENTS.md`, only with authority to edit its non-managed content
|
|
191
|
-
- stable navigation or scoped current context -> project-owned `CONTEXT.md`, only when the project uses it and authority permits the edit
|
|
192
|
-
- an additional reusable project-level spec -> `.rsp/specs/<name>.md`
|
|
193
|
-
- lasting rationale -> one exact Markdown file under `durableReview.decisionRecordsPath`
|
|
194
|
-
|
|
195
|
-
Do not choose generated indexes, `.rsp/rsp-rules.md`, or the managed RSP block in `AGENTS.md` as ordinary durable writeback targets.
|
|
196
|
-
|
|
197
|
-
Prefer `.rsp/specs/design.md` or an existing durable file before creating a new spec file.
|
|
198
|
-
|
|
199
|
-
Write stable facts or lasting rationale, not narrative history, task-by-task notes, temporary debugging history, or archive-only detail. Do not duplicate current facts into a Decision Record or rationale into a Spec. If you cannot identify concrete durable content, do not invent it.
|
|
200
|
-
|
|
201
|
-
## Output template
|
|
202
|
-
|
|
203
|
-
Use these semantic fields in this exact order. Localize the heading and human-facing labels to the response language; preserve the decision values shown in angle brackets as canonical values.
|
|
81
|
+
After loading [durable review](references/durable-review.md), choose current facts and rationale independently. Localize headings and labels, but preserve the canonical values below:
|
|
204
82
|
|
|
205
83
|
```md
|
|
206
84
|
## <localized Durable Decision heading>
|
|
207
85
|
- <localized Current facts label>: <No current-fact update needed | Update existing spec or scoped instruction | Create a new durable spec>
|
|
208
86
|
- <localized Current-fact target label>: <exact file path or N/A>
|
|
209
|
-
- <localized Facts to write label>:
|
|
210
|
-
- <durable fact or none>
|
|
87
|
+
- <localized Facts to write label>: <durable facts or none>
|
|
211
88
|
- <localized Decision Record label>: <No Decision Record needed | Create or update a Decision Record>
|
|
212
89
|
- <localized Decision Record target label>: <exact file path or N/A>
|
|
213
|
-
- <localized Rationale to write label>:
|
|
214
|
-
- <lasting rationale or none>
|
|
90
|
+
- <localized Rationale to write label>: <lasting rationale or none>
|
|
215
91
|
- <localized Archive ready label>: <yes | no>
|
|
216
92
|
```
|
|
217
93
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
Rules for the output:
|
|
221
|
-
|
|
222
|
-
- Each target must be an exact file path when its decision requires an update; `durableReview.decisionRecordsPath` is a directory, not the final target.
|
|
223
|
-
- `Facts to write` must contain durable facts, not task history or debugging notes.
|
|
224
|
-
- `Rationale to write` must contain lasting rationale, alternatives, tradeoffs, or consequences, not a duplicate of current facts.
|
|
225
|
-
- If real blockers remain or a required fact or rationale update is not yet written, `Archive ready` must be `no`.
|
|
226
|
-
- If neither axis has a missing update and remaining verify risk is consciously accepted, `Archive ready` may be `yes`.
|
|
227
|
-
- Do not use CLI warning text as a substitute for semantic durable-update judgment.
|
|
228
|
-
- CLI `archiveReady: judgment` means the skill or a human must decide; it is not automatic approval.
|
|
94
|
+
Response-only Continuation and Durable Decision labels are not canonical artifact headings. In Chinese, for example, use `## 持久化决策`, `决策记录(Decision Record)`, and `可归档(Archive ready)`, not English labels alone. A required unwritten update or real blocker makes archive readiness `no`; CLI `archiveReady: judgment` is advisory, not approval.
|