@oevery/rsp 1.0.3 → 1.2.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 (5) hide show
  1. package/README.md +120 -96
  2. package/README.zh-CN.md +120 -93
  3. package/dist/cli.mjs +853 -255
  4. package/package.json +1 -1
  5. package/rules/rsp-rules.md +68 -92
package/README.md CHANGED
@@ -1,125 +1,149 @@
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
-
11
- # Or run directly with npx
12
- npx @oevery/rsp init
13
-
14
- # Scaffold a project
15
- cd my-project && rsp init
10
+ npx -y @oevery/rsp init
11
+ npx -y @oevery/rsp doctor
16
12
  ```
17
13
 
18
- Then add \`.rsp/rules/*.md\` to your AI tool's instructions. For example, in Kilo Code's \`kilo.jsonc\`:
14
+ Recommended bootstrap flow:
19
15
 
20
- ```json
21
- {
22
- "instructions": [
23
- ".rsp/rules/*.md"
24
- ]
25
- }
16
+ ```bash
17
+ npx -y @oevery/rsp init --with-project-setup
18
+ # fill .rsp/features/project-setup.md
19
+ # fill .rsp/specs/design.md
20
+ npx -y @oevery/rsp doctor
26
21
  ```
27
22
 
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).
23
+ ## Core idea
29
24
 
30
- ## Project structure
25
+ - `rules/` stores durable constraints.
26
+ - `specs/` stores project-level design docs.
27
+ - `features/` stores active work.
28
+ - `active.d/` mirrors active features with empty marker files.
29
+ - `archives/` stores completed work.
31
30
 
32
31
  ```text
33
32
  .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
33
+ ├── rules/
34
+ │ ├── rsp-rules.md
35
+ │ └── project-rules.md # optional
36
+ ├── specs/
37
+ │ ├── INDEX.md # auto-generated
38
+ │ └── design.md
39
+ ├── features/
40
+ │ └── <name>.md
41
+ ├── active.d/
42
+ │ └── <name>
43
+ └── archives/
44
+ └── INDEX.md # auto-generated
45
+ ```
46
+
47
+ ## File ownership
48
+
49
+ - `AGENTS.md`: only the `<!-- rsp:begin --> ... <!-- rsp:end -->` block is managed by RSP.
50
+ - `.rsp/specs/INDEX.md`: auto-generated. Rebuild with `rsp specs-index`.
51
+ - `.rsp/archives/INDEX.md`: auto-generated. Rebuild with `rsp archive-index`.
52
+ - `.rsp/specs/design.md`: created by `rsp init`, then owned by the project.
53
+ - `.rsp/rules/project-rules.md`: optional; create only when the project has durable local rules.
54
+ - Keep durable architecture, boundaries, and cross-cutting technical constraints in `.rsp/specs/design.md`.
55
+ - Keep stable workflow rules, validation expectations, and local operating constraints in `.rsp/rules/project-rules.md`.
56
+
57
+ ## AGENTS integration
58
+
59
+ Managed block example:
60
+
61
+ ```md
62
+ <!-- rsp:begin -->
63
+ ## RSP Entry
64
+
65
+ Read in order:
66
+ 1. .rsp/rules/*.md
67
+ 2. .rsp/specs/INDEX.md
68
+ 3. .rsp/specs/design.md
69
+ 4. .rsp/active.d/ and matching .rsp/features/*.md
70
+ <!-- rsp:end -->
56
71
  ```
57
72
 
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
- -
73
+ `rsp init --agents-mode <mode>`:
74
+
75
+ - `managed`: insert/update the managed block in `AGENTS.md`.
76
+ - `skip`: scaffold `.rsp/` only.
77
+ - `print`: scaffold `.rsp/` and print the managed block.
78
+
79
+ ## Skill
80
+
81
+ 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.
82
+
83
+ Example optional installation flow:
84
+
85
+ ```bash
86
+ npx skills add oevery/rsp --skill rsp
98
87
  ```
99
88
 
89
+ This repository publishes a skill named `rsp` under `skills/rsp/`.
90
+
91
+ Then load the installed RSP skill only when you are adopting RSP, auditing setup, or reorganizing project-level rules/specs.
92
+
93
+ ## Recommended workflow
94
+
95
+ New project:
96
+
97
+ 1. `npx -y @oevery/rsp init`
98
+ 2. Prefer `npx -y @oevery/rsp init --with-project-setup`, or run `rsp new project-setup` manually
99
+ 3. Fill `.rsp/specs/design.md`
100
+ 4. Use `rsp add spec <name>` only when a new durable project doc is needed
101
+ 5. Use `rsp add rules project-rules` only when the project has stable local rules
102
+ 6. Start work with `rsp new <name>`
103
+
104
+ Existing project with a rich `AGENTS.md`:
105
+
106
+ 1. `npx -y @oevery/rsp init --agents-mode managed`
107
+ 2. Keep the managed block thin
108
+ 3. Move durable design into `.rsp/specs/design.md`
109
+ 4. Use `rsp add spec <name>` or `rsp add rules <name>` only when needed
110
+
111
+ AI-assisted setup:
112
+
113
+ 1. `npx -y @oevery/rsp init --agents-mode print --with-project-setup`
114
+ 2. Let the AI adapt the managed block in `AGENTS.md`
115
+ 3. Have the AI review and fill `.rsp/features/project-setup.md`
116
+ 4. Have the AI fill `.rsp/specs/design.md`
117
+ 5. Run `rsp doctor`
118
+
100
119
  ## CLI
101
120
 
102
121
  ```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
122
+ rsp init --agents-mode <mode> Scaffold .rsp/ + AGENTS.md
123
+ rsp init --with-project-setup Also create .rsp/features/project-setup.md
124
+ rsp add rules <name> Create .rsp/rules/<name>.md
125
+ rsp add spec <name> Create .rsp/specs/<name>.md and rebuild specs index
126
+ rsp new <name> [summary] Create .rsp/features/<name>.md
127
+ rsp close <name> Archive to .rsp/archives/ + update archive index
128
+ rsp status [--active|--blocked|--stale <days>]
129
+ Show project status summary with optional filters
130
+ rsp check Validate feature files and dependency consistency
131
+ rsp deps [--mermaid|--focus <name>|--reverse <name>]
132
+ Show dependency summary, graph, or focused view
133
+ rsp doctor Check setup health and common issues
134
+ rsp specs-index Rebuild specs INDEX.md
135
+ rsp archive-index Rebuild archives INDEX.md
111
136
  ```
112
137
 
113
- ## Customization
138
+ ## Doctor
114
139
 
115
- Edit `.rsp/config.yaml` to customize valid statuses, priorities, and required sections.
140
+ `rsp doctor` is read-only.
116
141
 
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.
142
+ - Checks `.rsp/`, `rules/rsp-rules.md`, `specs/design.md`, `specs/INDEX.md`, `archives/INDEX.md`, and the managed `AGENTS.md` block.
143
+ - Verifies generated index signatures.
144
+ - Verifies `active.d` markers and `features/` are in sync.
145
+ - Exits non-zero when issues are found.
118
146
 
119
147
  ## Platform-agnostic
120
148
 
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
149
+ `.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,149 @@
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
-
11
- # 或用 npx 直接运行
12
- npx @oevery/rsp init
13
-
14
- # 在当前项目搭建脚手架
15
- cd my-project && rsp init
10
+ npx -y @oevery/rsp init
11
+ npx -y @oevery/rsp doctor
16
12
  ```
17
13
 
18
- 然后将 \`.rsp/rules/*.md\` 添加到 AI 工具的指令文件中。例如 Kilo Code 的 \`kilo.jsonc\`：
14
+ 推荐启动流程：
19
15
 
20
- ```json
21
- {
22
- "instructions": [
23
- ".rsp/rules/*.md"
24
- ]
25
- }
16
+ ```bash
17
+ npx -y @oevery/rsp init --with-project-setup
18
+ # 填写 .rsp/features/project-setup.md
19
+ # 填写 .rsp/specs/design.md
20
+ npx -y @oevery/rsp doctor
26
21
  ```
27
22
 
28
- 其他工具（Cursor、Claude Code、Copilot）将同一路径添加到对应配置即可。详见[工具无关](#工具无关)。
23
+ ## 核心概念
29
24
 
30
- ## 项目结构
25
+ - `rules/` 存放长期稳定的约束。
26
+ - `specs/` 存放项目级设计文档。
27
+ - `features/` 存放进行中的工作。
28
+ - `active.d/` 用空标记文件镜像活跃特性。
29
+ - `archives/` 存放已完成工作。
31
30
 
32
31
  ```text
33
32
  .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
33
+ ├── rules/
34
+ │ ├── rsp-rules.md
35
+ │ └── project-rules.md # 可选
36
+ ├── specs/
37
+ │ ├── INDEX.md # 自动生成
38
+ │ └── design.md
39
+ ├── features/
40
+ │ └── <name>.md
41
+ ├── active.d/
42
+ │ └── <name>
43
+ └── archives/
44
+ └── INDEX.md # 自动生成
45
+ ```
46
+
47
+ ## 文件所有权
48
+
49
+ - `AGENTS.md`：只有 `<!-- rsp:begin --> ... <!-- rsp:end -->` 受管块由 RSP 维护。
50
+ - `.rsp/specs/INDEX.md`：自动生成，使用 `rsp specs-index` 重建。
51
+ - `.rsp/archives/INDEX.md`：自动生成，使用 `rsp archive-index` 重建。
52
+ - `.rsp/specs/design.md`：由 `rsp init` 创建，之后由项目维护。
53
+ - `.rsp/rules/project-rules.md`：可选，仅在项目确有长期本地规则时创建。
54
+ - 将长期架构、边界和跨模块技术约束放在 `.rsp/specs/design.md`。
55
+ - 将稳定的工作流规则、验证要求和本地运行约束放在 `.rsp/rules/project-rules.md`。
56
+
57
+ ## AGENTS 接入
58
+
59
+ 受管块示例：
60
+
61
+ ```md
62
+ <!-- rsp:begin -->
63
+ ## RSP Entry
64
+
65
+ Read in order:
66
+ 1. .rsp/rules/*.md
67
+ 2. .rsp/specs/INDEX.md
68
+ 3. .rsp/specs/design.md
69
+ 4. .rsp/active.d/ and matching .rsp/features/*.md
70
+ <!-- rsp:end -->
53
71
  ```
54
72
 
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
- -
73
+ `rsp init --agents-mode <mode>`：
74
+
75
+ - `managed`：插入/更新 `AGENTS.md` 中的受管块。
76
+ - `skip`：只搭建 `.rsp/`。
77
+ - `print`：搭建 `.rsp/` 并打印受管块。
78
+
79
+ ## Skill
80
+
81
+ 更完整的接入步骤、工作流说明和审计说明见 `skills/rsp/SKILL.md`。它适合按需加载，不应替代常驻核心规则。
82
+
83
+ 可选安装示例：
84
+
85
+ ```bash
86
+ npx skills add oevery/rsp --skill rsp
95
87
  ```
96
88
 
89
+ 这个仓库发布的 skill 名称是 `rsp`，位于 `skills/rsp/`。
90
+
91
+ 然后只在接入 RSP、审计设置或整理项目级 rules/specs 时加载这个 skill。
92
+
93
+ ## 推荐工作流
94
+
95
+ 新项目：
96
+
97
+ 1. `npx -y @oevery/rsp init`
98
+ 2. 优先使用 `npx -y @oevery/rsp init --with-project-setup`，或手动执行 `rsp new project-setup`
99
+ 3. 填写 `.rsp/specs/design.md`
100
+ 4. 只有在需要长期项目文档时才用 `rsp add spec <name>`
101
+ 5. 只有在存在稳定本地规则时才用 `rsp add rules project-rules`
102
+ 6. 使用 `rsp new <name>` 开始工作
103
+
104
+ 已有复杂 `AGENTS.md` 的项目：
105
+
106
+ 1. `npx -y @oevery/rsp init --agents-mode managed`
107
+ 2. 保持受管块尽量薄
108
+ 3. 将长期设计收敛到 `.rsp/specs/design.md`
109
+ 4. 需要时再用 `rsp add spec <name>` 或 `rsp add rules <name>`
110
+
111
+ AI 协助接入：
112
+
113
+ 1. `npx -y @oevery/rsp init --agents-mode print --with-project-setup`
114
+ 2. 让 AI 处理 `AGENTS.md` 的受管块
115
+ 3. 让 AI 审阅并填写 `.rsp/features/project-setup.md`
116
+ 4. 让 AI 填写 `.rsp/specs/design.md`
117
+ 5. 运行 `rsp doctor`
118
+
97
119
  ## CLI
98
120
 
99
121
  ```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 重新生成归档索引
122
+ rsp init --agents-mode <mode> 搭建 .rsp/ + AGENTS.md
123
+ rsp init --with-project-setup 同时创建 .rsp/features/project-setup.md
124
+ rsp add rules <name> 创建 .rsp/rules/<name>.md
125
+ rsp add spec <name> 创建 .rsp/specs/<name>.md 并重建 specs 索引
126
+ rsp new <name> [summary] 创建 .rsp/features/<name>.md
127
+ rsp close <name> 归档到 .rsp/archives/ + 更新归档索引
128
+ rsp status [--active|--blocked|--stale <days>]
129
+ 查看项目状态摘要，并支持轻量筛选
130
+ rsp check 校验 feature 文件结构与依赖一致性
131
+ rsp deps [--mermaid|--focus <name>|--reverse <name>]
132
+ 查看依赖摘要、Mermaid 图或局部依赖视图
133
+ rsp doctor 检查接入健康和常见问题
134
+ rsp specs-index 重新生成 specs 索引
135
+ rsp archive-index 重新生成 archives 索引
108
136
  ```
109
137
 
110
- ## 自定义
138
+ ## Doctor
111
139
 
112
- 编辑 `.rsp/config.yaml` 可自定义 status、priority 和必要的 sections。
140
+ `rsp doctor` 是只读命令。
113
141
 
114
- > **注意：** 内置 YAML 解析器支持简单的子集：`key: value` 键值对、嵌套列表（`- item`）和 `#` 注释。不支持多行值、引号字符串、布尔值和嵌套映射。
142
+ - 检查 `.rsp/`、`rules/rsp-rules.md`、`specs/design.md`、`specs/INDEX.md`、`archives/INDEX.md` 以及 `AGENTS.md` 受管块。
143
+ - 检查自动索引签名。
144
+ - 检查 `active.d` 标记与 `features/` 是否一致。
145
+ - 发现问题会以非零退出码结束。
115
146
 
116
147
  ## 工具无关
117
148
 
118
- \`.rsp/\` 目录是一个纯文件约定 — 不绑定任何工具。适用于 Kilo Code、Cursor、Claude Code、Cline、GitHub Copilot 或任何能读取项目文件的 AI 编码助手。需要 Node.js 18+。
119
-
120
- ## License
121
-
122
- MIT
149
+ `.rsp/` 是纯文件约定，适用于 Kilo Code、Cursor、Claude Code、Cline、GitHub Copilot 或任何能读取项目文件的 AI 助手。需要 Node.js 18+。