@oevery/rsp 1.1.0 → 1.2.0

package/README.md

@@ -11,6 +11,15 @@ npx -y @oevery/rsp init
 npx -y @oevery/rsp doctor
 ```
 
+Recommended bootstrap flow:
+
+```bash
+npx -y @oevery/rsp init --with-project-setup
+# fill .rsp/features/project-setup.md
+# fill .rsp/specs/design.md
+npx -y @oevery/rsp doctor
+```
+
 ## Core idea
 
 - `rules/` stores durable constraints.
@@ -42,6 +51,8 @@ npx -y @oevery/rsp doctor
 - `.rsp/archives/INDEX.md`: auto-generated. Rebuild with `rsp archive-index`.
 - `.rsp/specs/design.md`: created by `rsp init`, then owned by the project.
 - `.rsp/rules/project-rules.md`: optional; create only when the project has durable local rules.
+- Keep durable architecture, boundaries, and cross-cutting technical constraints in `.rsp/specs/design.md`.
+- Keep stable workflow rules, validation expectations, and local operating constraints in `.rsp/rules/project-rules.md`.
 
 ## AGENTS integration
 
@@ -72,9 +83,11 @@ Use `skills/rsp/SKILL.md` for step-by-step setup, workflow, and auditing guidanc
 Example optional installation flow:
 
 ```bash
-npx skills add @oevery/rsp
+npx skills add oevery/rsp --skill rsp
 ```
 
+This repository publishes a skill named `rsp` under `skills/rsp/`.
+
 Then load the installed RSP skill only when you are adopting RSP, auditing setup, or reorganizing project-level rules/specs.
 
 ## Recommended workflow
@@ -82,10 +95,11 @@ Then load the installed RSP skill only when you are adopting RSP, auditing setup
 New project:
 
 1. `npx -y @oevery/rsp init`
-2. Fill `.rsp/specs/design.md`
-3. Use `rsp add spec <name>` only when a new durable project doc is needed
-4. Use `rsp add rules project-rules` only when the project has stable local rules
-5. Start work with `rsp new <name>`
+2. Prefer `npx -y @oevery/rsp init --with-project-setup`, or run `rsp new project-setup` manually
+3. Fill `.rsp/specs/design.md`
+4. Use `rsp add spec <name>` only when a new durable project doc is needed
+5. Use `rsp add rules project-rules` only when the project has stable local rules
+6. Start work with `rsp new <name>`
 
 Existing project with a rich `AGENTS.md`:
 
@@ -96,15 +110,17 @@ Existing project with a rich `AGENTS.md`:
 
 AI-assisted setup:
 
-1. `npx -y @oevery/rsp init --agents-mode print`
+1. `npx -y @oevery/rsp init --agents-mode print --with-project-setup`
 2. Let the AI adapt the managed block in `AGENTS.md`
-3. Have the AI fill `.rsp/specs/design.md`
-4. Run `rsp doctor`
+3. Have the AI review and fill `.rsp/features/project-setup.md`
+4. Have the AI fill `.rsp/specs/design.md`
+5. Run `rsp doctor`
 
 ## CLI
 
 ```text
 rsp init --agents-mode <mode>   Scaffold .rsp/ + AGENTS.md
+rsp init --with-project-setup   Also create .rsp/features/project-setup.md
 rsp add rules <name>            Create .rsp/rules/<name>.md
 rsp add spec <name>             Create .rsp/specs/<name>.md and rebuild specs index
 rsp new <name> [summary]        Create .rsp/features/<name>.md

package/README.zh-CN.md

@@ -11,6 +11,15 @@ npx -y @oevery/rsp init
 npx -y @oevery/rsp doctor
 ```
 
+推荐启动流程：
+
+```bash
+npx -y @oevery/rsp init --with-project-setup
+# 填写 .rsp/features/project-setup.md
+# 填写 .rsp/specs/design.md
+npx -y @oevery/rsp doctor
+```
+
 ## 核心概念
 
 - `rules/` 存放长期稳定的约束。
@@ -42,6 +51,8 @@ npx -y @oevery/rsp doctor
 - `.rsp/archives/INDEX.md`：自动生成，使用 `rsp archive-index` 重建。
 - `.rsp/specs/design.md`：由 `rsp init` 创建，之后由项目维护。
 - `.rsp/rules/project-rules.md`：可选，仅在项目确有长期本地规则时创建。
+- 将长期架构、边界和跨模块技术约束放在 `.rsp/specs/design.md`。
+- 将稳定的工作流规则、验证要求和本地运行约束放在 `.rsp/rules/project-rules.md`。
 
 ## AGENTS 接入
 
@@ -72,9 +83,11 @@ Read in order:
 可选安装示例：
 
 ```bash
-npx skills add @oevery/rsp
+npx skills add oevery/rsp --skill rsp
 ```
 
+这个仓库发布的 skill 名称是 `rsp`，位于 `skills/rsp/`。
+
 然后只在接入 RSP、审计设置或整理项目级 rules/specs 时加载这个 skill。
 
 ## 推荐工作流
@@ -82,10 +95,11 @@ npx skills add @oevery/rsp
 新项目：
 
 1. `npx -y @oevery/rsp init`
-2. 填写 `.rsp/specs/design.md`
-3. 只有在需要长期项目文档时才用 `rsp add spec <name>`
-4. 只有在存在稳定本地规则时才用 `rsp add rules project-rules`
-5. 使用 `rsp new <name>` 开始工作
+2. 优先使用 `npx -y @oevery/rsp init --with-project-setup`，或手动执行 `rsp new project-setup`
+3. 填写 `.rsp/specs/design.md`
+4. 只有在需要长期项目文档时才用 `rsp add spec <name>`
+5. 只有在存在稳定本地规则时才用 `rsp add rules project-rules`
+6. 使用 `rsp new <name>` 开始工作
 
 已有复杂 `AGENTS.md` 的项目：
 
@@ -96,15 +110,17 @@ npx skills add @oevery/rsp
 
 AI 协助接入：
 
-1. `npx -y @oevery/rsp init --agents-mode print`
+1. `npx -y @oevery/rsp init --agents-mode print --with-project-setup`
 2. 让 AI 处理 `AGENTS.md` 的受管块
-3. 让 AI 填写 `.rsp/specs/design.md`
-4. 运行 `rsp doctor`
+3. 让 AI 审阅并填写 `.rsp/features/project-setup.md`
+4. 让 AI 填写 `.rsp/specs/design.md`
+5. 运行 `rsp doctor`
 
 ## CLI
 
 ```text
 rsp init --agents-mode <mode>   搭建 .rsp/ + AGENTS.md
+rsp init --with-project-setup   同时创建 .rsp/features/project-setup.md
 rsp add rules <name>            创建 .rsp/rules/<name>.md
 rsp add spec <name>             创建 .rsp/specs/<name>.md 并重建 specs 索引
 rsp new <name> [summary]        创建 .rsp/features/<name>.md

package/dist/cli.mjs

@@ -112,17 +112,51 @@ function featureNameFromPath(featuresDir, filePath) {
   return rel.replace(/\.md$/, "");
 }
 function generateFeatureContent(name, summary = "") {
+  if (name === "project-setup") {
+    return `---
+status: draft
+priority: medium
+tags:
+---
+
+# Feature: project-setup
+
+## Spec
+- Summary: ${summary || "Capture the project model, boundaries, and stable local constraints"}
+- Requirements:
+  - Project purpose, scope, and structure are reflected in .rsp/specs/design.md
+  - Stable validation or workflow constraints are reflected in .rsp/rules/project-rules.md when needed
+- Constraints:
+  - Avoid duplicating durable project facts across feature notes, specs, and rules
+
+## Plan
+- [ ] Review the repository structure, entrypoints, and primary outputs
+- [ ] Fill .rsp/specs/design.md with durable architecture facts
+- [ ] Add .rsp/rules/project-rules.md if stable local rules or validation steps exist
+
+## Tests
+- [ ] Run rsp doctor
+- [ ] Run project-native validation if available
+
+## Notes (optional)
+- <facts discovered during project setup>
+
+## Blockers
+-
+`;
+  }
   return `---
 status: draft
 priority: medium
 tags:
 ---
+
 # Feature: ${name}
 
 ## Spec
 - Summary: ${summary || "<one-line summary>"}
 - Requirements:
-  - [ ] <verifiable requirement>
+  - <verifiable requirement>
 - Constraints:
   -
 
@@ -155,7 +189,6 @@ Guidelines:
 - .rsp/rules/project-rules.md is optional
 - Keep project design in .rsp/specs/
 - Add extra spec files only when they have durable value
-- Do not create a feature named 'init'
 ${RSP_AGENTS_END}`;
 }
 function upsertRspAgentsBlock(content) {
@@ -192,7 +225,7 @@ function generateDesignContent(projectName) {
 - <important directory or subsystem> \u2014 <responsibility>
 
 ## Constraints
-- <cross-cutting technical or operational constraint>
+- <cross-cutting technical or operational constraint, when it affects architecture>
 `;
 }
 function generateProjectRulesContent(projectName) {
@@ -204,10 +237,10 @@ description: Project-specific rules for ${projectName}
 # Project Rules
 
 ## Scope
-- <rules that apply across the project>
+- <stable local rules, workflow constraints, or validation expectations>
 
 ## Validation
-- <preferred validation commands>
+- <preferred stable validation commands, not temporary troubleshooting steps>
 
 ## Conventions
 - <project-specific conventions>
@@ -1197,6 +1230,12 @@ async function initProject(args = {}) {
     created = await ensureFile(join11(RSP_DIR, ".gitignore"), "# Transient files that should not be committed\n.lock\n") || created;
     if (args.withProjectRules)
       created = await ensureFile(join11(RSP_DIR, "rules", "project-rules.md"), generateProjectRulesContent(projectName)) || created;
+    if (args.withProjectSetup) {
+      const featurePath = join11(RSP_DIR, "features", "project-setup.md");
+      const activeMarker = join11(RSP_DIR, "active.d", "project-setup");
+      created = await ensureFile(featurePath, generateFeatureContent("project-setup")) || created;
+      created = await ensureFile(activeMarker, "") || created;
+    }
     if (createdSpecsIndex || createdDesign)
       await buildSpecsIndex({ acquireLock: false });
     if (createdArchivesIndex)
@@ -1230,6 +1269,8 @@ ${managed}
 `);
     }
     if (isNew) {
+      const createdProjectSetup = args.withProjectSetup ? "\n           .rsp/features/project-setup.md\n           .rsp/active.d/project-setup" : "";
+      const next = args.withProjectSetup ? "fill .rsp/features/project-setup.md" : "rsp new project-setup";
       console.log(`
   ${pc.green("RSP scaffolded.")}
 `);
@@ -1240,10 +1281,11 @@ ${managed}
            .rsp/archives/
            .rsp/.gitignore
            .rsp/config.yaml
-           .rsp/specs/design.md
+           .rsp/specs/design.md${createdProjectSetup}
            AGENTS.md
 `);
-      console.log(`  ${pc.cyan("Next:")} rsp new <name>
+      console.log(`  ${pc.cyan("Next:")} ${next}
+  ${pc.dim("Then:")} fill .rsp/specs/design.md
   ${pc.dim("Also:")} rsp status  rsp deps
 `);
     } else if (created) {
@@ -1271,10 +1313,6 @@ async function newFeature(name, summary = "") {
     console.error(`  ${pc.red("Error:")} feature name must be kebab-case with optional subdirectory (lowercase, digits, hyphens, slashes)`);
     process.exit(1);
   }
-  if (name === "init") {
-    console.error(`  ${pc.red("Error:")} "init" is a reserved workflow name, not a feature name`);
-    process.exit(1);
-  }
   const rspRulesPath = join12(RSP_DIR, "rules", "rsp-rules.md");
   const designPath = join12(RSP_DIR, "specs", "design.md");
   if (!existsSync12(rspRulesPath) || !existsSync12(designPath)) {
@@ -1470,12 +1508,18 @@ var initCommand = defineCommand({
       type: "boolean",
       description: "Create .rsp/rules/project-rules.md",
       default: false
+    },
+    "with-project-setup": {
+      type: "boolean",
+      description: "Create .rsp/features/project-setup.md and mark it active",
+      default: false
     }
   },
   async run({ args }) {
     await initProject({
       agentsMode: args["agents-mode"] === "skip" || args["agents-mode"] === "print" ? args["agents-mode"] : "managed",
-      withProjectRules: Boolean(args["with-project-rules"])
+      withProjectRules: Boolean(args["with-project-rules"]),
+      withProjectSetup: Boolean(args["with-project-setup"])
     });
   }
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oevery/rsp",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "RSP (Rules, Specs, Plans) workflow for AI-assisted development",
   "author": "oevery",
   "license": "MIT",

package/rules/rsp-rules.md

@@ -26,6 +26,8 @@ RSP = Rules, Specs, Plans.
 - `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
 
@@ -68,12 +70,12 @@ Every feature file should contain these sections:
 ## Init constraints
 
 - `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.
-- `init` is a reserved workflow name. Do not create a feature named `init`.
 
 ## Agent behavior
 
@@ -89,7 +91,6 @@ Every feature file should contain these sections:
 ## Prohibitions
 
 - Do not manually maintain `specs/INDEX.md` or `archives/INDEX.md`.
-- Do not create a feature named `init`.
 - 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.