@oevery/rsp 1.0.2 → 1.1.0

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.
Files changed (6) hide show
  1. package/README.md +105 -97
  2. package/README.zh-CN.md +105 -94
  3. package/bin/rsp.mjs +5 -0
  4. package/dist/cli.mjs +808 -254
  5. package/package.json +3 -2
  6. package/rules/rsp-rules.md +67 -92
package/README.md CHANGED
@@ -1,125 +1,133 @@
1
1
  # RSP: Rules, Specs, Plans
2
2
 
3
- RSP = **Rules, Specs, Plans** — a lightweight AI-assisted development workflow.
3
+ English | [简体中文](./README.zh-CN.md)
4
+
5
+ RSP = **Rules, Specs, Plans**. A lightweight AI-assisted workflow for project rules, specs, and feature plans.
4
6
 
5
7
  ## Quick start
6
8
 
7
9
  ```bash
8
- # Install globally
9
- npm install -g @oevery/rsp
10
+ npx -y @oevery/rsp init
11
+ npx -y @oevery/rsp doctor
12
+ ```
10
13
 
11
- # Or run directly with npx
12
- npx @oevery/rsp init
14
+ ## Core idea
13
15
 
14
- # Scaffold a project
15
- cd my-project && rsp init
16
+ - `rules/` stores durable constraints.
17
+ - `specs/` stores project-level design docs.
18
+ - `features/` stores active work.
19
+ - `active.d/` mirrors active features with empty marker files.
20
+ - `archives/` stores completed work.
21
+
22
+ ```text
23
+ .rsp/
24
+ ├── rules/
25
+ │ ├── rsp-rules.md
26
+ │ └── project-rules.md # optional
27
+ ├── specs/
28
+ │ ├── INDEX.md # auto-generated
29
+ │ └── design.md
30
+ ├── features/
31
+ │ └── <name>.md
32
+ ├── active.d/
33
+ │ └── <name>
34
+ └── archives/
35
+ └── INDEX.md # auto-generated
16
36
  ```
17
37
 
18
- Then add \`.rsp/rules/*.md\` to your AI tool's instructions. For example, in Kilo Code's \`kilo.jsonc\`:
38
+ ## File ownership
19
39
 
20
- ```json
21
- {
22
- "instructions": [
23
- ".rsp/rules/*.md"
24
- ]
25
- }
26
- ```
40
+ - `AGENTS.md`: only the `<!-- rsp:begin --> ... <!-- rsp:end -->` block is managed by RSP.
41
+ - `.rsp/specs/INDEX.md`: auto-generated. Rebuild with `rsp specs-index`.
42
+ - `.rsp/archives/INDEX.md`: auto-generated. Rebuild with `rsp archive-index`.
43
+ - `.rsp/specs/design.md`: created by `rsp init`, then owned by the project.
44
+ - `.rsp/rules/project-rules.md`: optional; create only when the project has durable local rules.
27
45
 
28
- For other tools (Cursor, Claude Code, Copilot), add the path to the appropriate config file. The same file works everywhere — see [Platform-agnostic](#platform-agnostic).
46
+ ## AGENTS integration
29
47
 
30
- ## Project structure
48
+ Managed block example:
31
49
 
32
- ```text
33
- .rsp/
34
- ├── config.yaml # project config (custom statuses, priorities, sections)
35
- ├── rules/ # technical constraints, long-lived
36
- │ └── rsp-rules.md
37
- ├── specs/ # project-level architecture
38
- │ └── INDEX.md # extracted spec summaries from archived features
39
- ├── features/ # feature files (flat or nested)
40
- │ ├── login.md
41
- │ ├── auth/
42
- │ │ └── login.md
43
- │ └── payments/
44
- │ └── checkout.md
45
- ├── active.d/ # active feature markers (path = feature name)
46
- │ ├── login
47
- │ ├── auth/
48
- │ │ └── login
49
- │ └── payments/
50
- │ └── checkout
51
- ├── archive/
52
- │ ├── INDEX.md # auto-generated archive index
53
- │ ├── 2026-05-22_login.md
54
- │ └── payments/
55
- │ └── 2026-05-22_checkout.md
50
+ ```md
51
+ <!-- rsp:begin -->
52
+ ## RSP Entry
53
+
54
+ Read in order:
55
+ 1. .rsp/rules/*.md
56
+ 2. .rsp/specs/INDEX.md
57
+ 3. .rsp/specs/design.md
58
+ 4. .rsp/active.d/ and matching .rsp/features/*.md
59
+ <!-- rsp:end -->
56
60
  ```
57
61
 
58
- Each `active.d/` entry is an empty file whose path mirrors `features/`. Multiple entries mean parallel features. AI reads `active.d/` to find what's in progress. Features can be organized flat (`login.md`) or in domain subdirectories (`auth/login.md`, `payments/checkout.md`).
59
-
60
- Each feature file is self-contained, with optional delta markers and structured scenarios:
61
-
62
- ```markdown
63
- ---
64
- status: draft
65
- priority: medium
66
- tags:
67
- - backend
68
- ---
69
- # Feature: User Login
70
-
71
- ## Spec
72
- - Summary: Users can log in with email and password
73
- - Requirements:
74
- - [ ] Login form submits email + password
75
- - [ ] Backend validates credentials and returns JWT
76
- ### ADDED # optional: delta markers
77
- - OAuth 2.0 login support
78
- ### Scenario: Valid credentials
79
- - GIVEN a registered user
80
- - WHEN they submit email + password
81
- - THEN a JWT is returned
82
- - Constraints:
83
- - Passwords must be hashed with bcrypt
84
-
85
- ## Plan
86
- - [ ] Phase 1: Backend API
87
- - [ ] Create /api/auth/login endpoint
88
- - [ ] Implement password verification
89
- - [ ] Phase 2: Frontend
90
- - [ ] Design login form UI
91
-
92
- ## Tests
93
- - [ ] tests/auth/login_test.ts — successful login
94
- - [ ] tests/auth/login_test.ts — invalid credentials
95
-
96
- ## Blockers
97
- -
62
+ `rsp init --agents-mode <mode>`:
63
+
64
+ - `managed`: insert/update the managed block in `AGENTS.md`.
65
+ - `skip`: scaffold `.rsp/` only.
66
+ - `print`: scaffold `.rsp/` and print the managed block.
67
+
68
+ ## Skill
69
+
70
+ Use `skills/rsp/SKILL.md` for step-by-step setup, workflow, and auditing guidance. It is intended for on-demand loading rather than always-on core rules.
71
+
72
+ Example optional installation flow:
73
+
74
+ ```bash
75
+ npx skills add @oevery/rsp
98
76
  ```
99
77
 
78
+ Then load the installed RSP skill only when you are adopting RSP, auditing setup, or reorganizing project-level rules/specs.
79
+
80
+ ## Recommended workflow
81
+
82
+ New project:
83
+
84
+ 1. `npx -y @oevery/rsp init`
85
+ 2. Fill `.rsp/specs/design.md`
86
+ 3. Use `rsp add spec <name>` only when a new durable project doc is needed
87
+ 4. Use `rsp add rules project-rules` only when the project has stable local rules
88
+ 5. Start work with `rsp new <name>`
89
+
90
+ Existing project with a rich `AGENTS.md`:
91
+
92
+ 1. `npx -y @oevery/rsp init --agents-mode managed`
93
+ 2. Keep the managed block thin
94
+ 3. Move durable design into `.rsp/specs/design.md`
95
+ 4. Use `rsp add spec <name>` or `rsp add rules <name>` only when needed
96
+
97
+ AI-assisted setup:
98
+
99
+ 1. `npx -y @oevery/rsp init --agents-mode print`
100
+ 2. Let the AI adapt the managed block in `AGENTS.md`
101
+ 3. Have the AI fill `.rsp/specs/design.md`
102
+ 4. Run `rsp doctor`
103
+
100
104
  ## CLI
101
105
 
102
106
  ```text
103
- rsp init Scaffold .rsp/ + AGENTS.md
104
- rsp new <name> [summary] Create .rsp/features/<name>.md
105
- rsp close <name> Archive to .rsp/archive/ + update spec index
106
- rsp status Show project dashboard (age, blocked, trends)
107
- rsp check Validate features (frontmatter, sections, deps, deltas, scenarios)
108
- rsp deps Show dependency table
109
- rsp deps --mermaid Output Mermaid.js dependency graph
110
- rsp archive-index Rebuild archive INDEX.md
107
+ rsp init --agents-mode <mode> Scaffold .rsp/ + AGENTS.md
108
+ rsp add rules <name> Create .rsp/rules/<name>.md
109
+ rsp add spec <name> Create .rsp/specs/<name>.md and rebuild specs index
110
+ rsp new <name> [summary] Create .rsp/features/<name>.md
111
+ rsp close <name> Archive to .rsp/archives/ + update archive index
112
+ rsp status [--active|--blocked|--stale <days>]
113
+ Show project status summary with optional filters
114
+ rsp check Validate feature files and dependency consistency
115
+ rsp deps [--mermaid|--focus <name>|--reverse <name>]
116
+ Show dependency summary, graph, or focused view
117
+ rsp doctor Check setup health and common issues
118
+ rsp specs-index Rebuild specs INDEX.md
119
+ rsp archive-index Rebuild archives INDEX.md
111
120
  ```
112
121
 
113
- ## Customization
122
+ ## Doctor
114
123
 
115
- Edit `.rsp/config.yaml` to customize valid statuses, priorities, and required sections.
124
+ `rsp doctor` is read-only.
116
125
 
117
- > **Note:** The built-in YAML parser supports a simple subset: `key: value` pairs, nested lists (`- item`), and `#` comments. Multi-line values, quoted strings, booleans, and nested maps are not supported.
126
+ - Checks `.rsp/`, `rules/rsp-rules.md`, `specs/design.md`, `specs/INDEX.md`, `archives/INDEX.md`, and the managed `AGENTS.md` block.
127
+ - Verifies generated index signatures.
128
+ - Verifies `active.d` markers and `features/` are in sync.
129
+ - Exits non-zero when issues are found.
118
130
 
119
131
  ## Platform-agnostic
120
132
 
121
- The \`.rsp/\` directory is a plain file convention — no tool lock-in. It works with Kilo Code, Cursor, Claude Code, Cline, GitHub Copilot, or any AI coding assistant that reads project files. Requires Node.js 18+.
122
-
123
- ## License
124
-
125
- MIT
133
+ `.rsp/` is a plain file convention. It works with Kilo Code, Cursor, Claude Code, Cline, GitHub Copilot, or any assistant that reads project files. Requires Node.js 18+.
package/README.zh-CN.md CHANGED
@@ -1,122 +1,133 @@
1
1
  # RSP：Rules, Specs, Plans
2
2
 
3
- RSP = **Rules（规则）、Specs（规格）、Plans（计划）** — 轻量级 AI 辅助开发工作流。
3
+ [English](./README.md) | 简体中文
4
+
5
+ RSP = **Rules（规则）、Specs（规格）、Plans（计划）**。这是一个面向项目规则、项目级文档和特性计划的轻量级 AI 协作工作流。
4
6
 
5
7
  ## 快速开始
6
8
 
7
9
  ```bash
8
- # 全局安装
9
- npm install -g @oevery/rsp
10
+ npx -y @oevery/rsp init
11
+ npx -y @oevery/rsp doctor
12
+ ```
10
13
 
11
- # 或用 npx 直接运行
12
- npx @oevery/rsp init
14
+ ## 核心概念
13
15
 
14
- # 在当前项目搭建脚手架
15
- cd my-project && rsp init
16
+ - `rules/` 存放长期稳定的约束。
17
+ - `specs/` 存放项目级设计文档。
18
+ - `features/` 存放进行中的工作。
19
+ - `active.d/` 用空标记文件镜像活跃特性。
20
+ - `archives/` 存放已完成工作。
21
+
22
+ ```text
23
+ .rsp/
24
+ ├── rules/
25
+ │ ├── rsp-rules.md
26
+ │ └── project-rules.md # 可选
27
+ ├── specs/
28
+ │ ├── INDEX.md # 自动生成
29
+ │ └── design.md
30
+ ├── features/
31
+ │ └── <name>.md
32
+ ├── active.d/
33
+ │ └── <name>
34
+ └── archives/
35
+ └── INDEX.md # 自动生成
16
36
  ```
17
37
 
18
- 然后将 \`.rsp/rules/*.md\` 添加到 AI 工具的指令文件中。例如 Kilo Code 的 \`kilo.jsonc\`：
38
+ ## 文件所有权
19
39
 
20
- ```json
21
- {
22
- "instructions": [
23
- ".rsp/rules/*.md"
24
- ]
25
- }
26
- ```
40
+ - `AGENTS.md`：只有 `<!-- rsp:begin --> ... <!-- rsp:end -->` 受管块由 RSP 维护。
41
+ - `.rsp/specs/INDEX.md`：自动生成，使用 `rsp specs-index` 重建。
42
+ - `.rsp/archives/INDEX.md`：自动生成，使用 `rsp archive-index` 重建。
43
+ - `.rsp/specs/design.md`：由 `rsp init` 创建，之后由项目维护。
44
+ - `.rsp/rules/project-rules.md`：可选，仅在项目确有长期本地规则时创建。
27
45
 
28
- 其他工具（Cursor、Claude Code、Copilot）将同一路径添加到对应配置即可。详见[工具无关](#工具无关)。
46
+ ## AGENTS 接入
29
47
 
30
- ## 项目结构
48
+ 受管块示例：
31
49
 
32
- ```text
33
- .rsp/
34
- ├── config.yaml # 项目配置
35
- ├── rules/ # 技术约束
36
- ├── specs/ # 项目级架构
37
- │ └── INDEX.md # 从归档提取的 spec 摘要
38
- ├── features/ # 特性文件
39
- │ ├── auth/
40
- │ │ └── login.md
41
- │ └── payments/
42
- │ └── checkout.md
43
- ├── active.d/ # 活跃特性标记（路径即特性名）
44
- │ ├── auth/
45
- │ │ └── login # 空标记文件
46
- │ └── payments/
47
- │ └── checkout
48
- ├── archive/
49
- │ ├── INDEX.md # 自动生成的归档索引
50
- │ ├── 2026-05-22_login.md
51
- │ └── payments/
52
- │ └── 2026-05-22_checkout.md
50
+ ```md
51
+ <!-- rsp:begin -->
52
+ ## RSP Entry
53
+
54
+ Read in order:
55
+ 1. .rsp/rules/*.md
56
+ 2. .rsp/specs/INDEX.md
57
+ 3. .rsp/specs/design.md
58
+ 4. .rsp/active.d/ and matching .rsp/features/*.md
59
+ <!-- rsp:end -->
53
60
  ```
54
61
 
55
- \`active.d/\` 中的每个条目是一个空文件，路径与 \`features/\` 镜像。多个条目表示并行特性。AI 读取 \`active.d/\` 来确定当前进行中的工作。特性文件可以扁平放置（如 \`login.md\`），也可以按领域子目录组织（如 \`auth/login.md\`、\`payments/checkout.md\`）。
56
-
57
- 每个功能文件独立自包含，支持可选的 delta 变更标记和结构化场景：
58
-
59
- ```markdown
60
- ---
61
- status: draft
62
- priority: medium
63
- tags:
64
- - backend
65
- ---
66
- # Feature: User Login
67
-
68
- ## Spec
69
- - Summary: 用户可通过邮箱和密码登录
70
- - Requirements:
71
- - [ ] 登录表单提交邮箱 + 密码
72
- - [ ] 后端验证凭据并返回 JWT
73
- ### ADDED # 可选：delta 变更标记
74
- - OAuth 2.0 登录支持
75
- ### Scenario: 有效凭据
76
- - GIVEN 一个已注册用户
77
- - WHEN 提交邮箱 + 密码
78
- - THEN 返回 JWT
79
- - Constraints:
80
- - 密码必须用 bcrypt 哈希
81
-
82
- ## Plan
83
- - [ ] 阶段 1: 后端 API
84
- - [ ] 创建 /api/auth/login 端点
85
- - [ ] 实现密码验证
86
- - [ ] 阶段 2: 前端
87
- - [ ] 设计登录表单 UI
88
-
89
- ## Tests
90
- - [ ] tests/auth/login_test.ts — 成功登录
91
- - [ ] tests/auth/login_test.ts — 无效凭据
92
-
93
- ## Blockers
94
- -
62
+ `rsp init --agents-mode <mode>`：
63
+
64
+ - `managed`：插入/更新 `AGENTS.md` 中的受管块。
65
+ - `skip`：只搭建 `.rsp/`。
66
+ - `print`：搭建 `.rsp/` 并打印受管块。
67
+
68
+ ## Skill
69
+
70
+ 更完整的接入步骤、工作流说明和审计说明见 `skills/rsp/SKILL.md`。它适合按需加载，不应替代常驻核心规则。
71
+
72
+ 可选安装示例：
73
+
74
+ ```bash
75
+ npx skills add @oevery/rsp
95
76
  ```
96
77
 
78
+ 然后只在接入 RSP、审计设置或整理项目级 rules/specs 时加载这个 skill。
79
+
80
+ ## 推荐工作流
81
+
82
+ 新项目：
83
+
84
+ 1. `npx -y @oevery/rsp init`
85
+ 2. 填写 `.rsp/specs/design.md`
86
+ 3. 只有在需要长期项目文档时才用 `rsp add spec <name>`
87
+ 4. 只有在存在稳定本地规则时才用 `rsp add rules project-rules`
88
+ 5. 使用 `rsp new <name>` 开始工作
89
+
90
+ 已有复杂 `AGENTS.md` 的项目：
91
+
92
+ 1. `npx -y @oevery/rsp init --agents-mode managed`
93
+ 2. 保持受管块尽量薄
94
+ 3. 将长期设计收敛到 `.rsp/specs/design.md`
95
+ 4. 需要时再用 `rsp add spec <name>` 或 `rsp add rules <name>`
96
+
97
+ AI 协助接入：
98
+
99
+ 1. `npx -y @oevery/rsp init --agents-mode print`
100
+ 2. 让 AI 处理 `AGENTS.md` 的受管块
101
+ 3. 让 AI 填写 `.rsp/specs/design.md`
102
+ 4. 运行 `rsp doctor`
103
+
97
104
  ## CLI
98
105
 
99
106
  ```text
100
- rsp init 搭建 .rsp/ + AGENTS.md
101
- rsp new <name> [summary] 创建新功能
102
- rsp close <name> 归档到 archive/ + 更新 spec 索引
103
- rsp status 查看项目仪表板（年龄、受阻、趋势）
104
- rsp check 验证功能文件（frontmatter、sections、deps、deltas、scenarios）
105
- rsp deps 查看依赖关系表
106
- rsp deps --mermaid 输出 Mermaid.js 依赖图
107
- rsp archive-index 重新生成归档索引
107
+ rsp init --agents-mode <mode> 搭建 .rsp/ + AGENTS.md
108
+ rsp add rules <name> 创建 .rsp/rules/<name>.md
109
+ rsp add spec <name> 创建 .rsp/specs/<name>.md 并重建 specs 索引
110
+ rsp new <name> [summary] 创建 .rsp/features/<name>.md
111
+ rsp close <name> 归档到 .rsp/archives/ + 更新归档索引
112
+ rsp status [--active|--blocked|--stale <days>]
113
+ 查看项目状态摘要，并支持轻量筛选
114
+ rsp check 校验 feature 文件结构与依赖一致性
115
+ rsp deps [--mermaid|--focus <name>|--reverse <name>]
116
+ 查看依赖摘要、Mermaid 图或局部依赖视图
117
+ rsp doctor 检查接入健康和常见问题
118
+ rsp specs-index 重新生成 specs 索引
119
+ rsp archive-index 重新生成 archives 索引
108
120
  ```
109
121
 
110
- ## 自定义
122
+ ## Doctor
111
123
 
112
- 编辑 `.rsp/config.yaml` 可自定义 status、priority 和必要的 sections。
124
+ `rsp doctor` 是只读命令。
113
125
 
114
- > **注意：** 内置 YAML 解析器支持简单的子集：`key: value` 键值对、嵌套列表（`- item`）和 `#` 注释。不支持多行值、引号字符串、布尔值和嵌套映射。
126
+ - 检查 `.rsp/`、`rules/rsp-rules.md`、`specs/design.md`、`specs/INDEX.md`、`archives/INDEX.md` 以及 `AGENTS.md` 受管块。
127
+ - 检查自动索引签名。
128
+ - 检查 `active.d` 标记与 `features/` 是否一致。
129
+ - 发现问题会以非零退出码结束。
115
130
 
116
131
  ## 工具无关
117
132
 
118
- \`.rsp/\` 目录是一个纯文件约定 — 不绑定任何工具。适用于 Kilo Code、Cursor、Claude Code、Cline、GitHub Copilot 或任何能读取项目文件的 AI 编码助手。需要 Node.js 18+。
119
-
120
- ## License
121
-
122
- MIT
133
+ `.rsp/` 是纯文件约定，适用于 Kilo Code、Cursor、Claude Code、Cline、GitHub Copilot 或任何能读取项目文件的 AI 助手。需要 Node.js 18+。
package/bin/rsp.mjs ADDED
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { runCli } from '../dist/cli.mjs'
4
+
5
+ runCli()