@jennie-shawn/starwork 0.1.0-alpha.2 → 0.1.0-alpha.21

package/docs/m2.6-project-init-feedback/m2.6-project-init-feedback-05-agents-guardrails-spec.md

@@ -0,0 +1,265 @@
+# M2.6 Project Init 反馈 05：AGENTS 入口规则与 Skill 防污染 SPEC
+
+## 状态
+
+- 版本：v0.1 implemented
+- 所属阶段：M2.6 既有功能优化与 A 测稳定化
+- 所属模块：StarWork Skills / CLI init blueprint / AGENTS 模板 / Core Rules
+- 反馈来源：单项目初始化 A 测
+- 问题类型：Skill 约束不足导致 AI 自我发挥
+
+## 用户反馈
+
+`AGENTS.md` 里出现了 StarWork 初始化过程和 `Folders Not Used` 等施工痕迹；同时 identity 这类 system 文件的读取时机没有写清楚，AI 一开始不会读取。
+
+## 根因
+
+当前 `starworkInit` 允许 Agent 把定制需求自由整理成规则文件，缺少两个边界：
+
+1. `AGENTS.md` 是稳定入口规则，不是初始化报告。
+2. `.starwork/rules/` 是扩展规则层，也不能承载临时施工日志。
+
+另外 AGENTS 的默认 “Read First” 只列 current-project/current-work，没有说明 identity、lessons、knowledge 的条件读取时机。AI 不知道何时读长期上下文。
+
+## 目标
+
+AGENTS 必须成为短、稳定、可执行的入口路由。
+
+它应该回答：
+
+- 开始任务先读什么。
+- 什么时候读 identity / lessons / knowledge。
+- 哪些目录是事实源。
+- 哪些内容需要确认。
+
+它不应该回答：
+
+- 这次 StarWork 初始化做了什么。
+- 哪些默认目录没创建。
+- blueprint 文件叫什么。
+- CLI dry-run 输出是什么。
+- Agent 为什么这样选择目录。
+
+## 非目标
+
+- 不把全部规则塞进 AGENTS。
+- 不让 Skill 直接写入项目事实源而不经 CLI 或用户确认。
+- 不让 AGENTS 成为项目进度文档。
+- 不禁止 `.starwork/workspace.json` 记录 customization。
+
+## AGENTS 目标结构
+
+英文：
+
+```markdown
+# Workspace Rules
+
+## Read First
+
+1. `_system/context/current-project.md`
+2. `_system/tasks/current-work.md`
+3. `.starwork/rules/index.md` when it exists
+
+## Read When Relevant
+
+- Read `_system/identity/README.md` when user preferences, communication style, domain background, or long-term context may matter.
+- Read `_system/lessons/README.md` before repeated, risky, or pattern-sensitive work.
+- Read `knowledge/README.md` when project knowledge or reusable references may matter.
+- Read Hub sync docs only if this workspace is connected to a Hub.
+
+## File Boundaries
+
+- Project status belongs in `_system/context/current-project.md`.
+- Current execution notes belong in `_system/tasks/current-work.md`.
+- Code belongs in the project-declared implementation path.
+- Approved outputs belong in the project-declared formal source.
+- StarWork mechanism state belongs in `.starwork/`.
+
+## Confirmation Required
+
+- Changing identity or stable preferences.
+- Promoting drafts to formal outputs.
+- Changing workspace structure or top-level business folders.
+- Editing Hub-shared resources.
+```
+
+中文同理。
+
+## 禁止写入 AGENTS 的内容
+
+`starworkInit`、`starworkDoctor`、`starworkSpawn` 生成 AGENTS 或规则时，都不得写入：
+
+```text
+Folders Not Used
+Initialized as
+StarWork project workspace
+blueprint path
+dry-run result
+doctor result
+npm install result
+I chose this because...
+The complete spec file was not found...
+```
+
+这些信息的归属：
+
+| 信息 | 归属 |
+|---|---|
+| CLI 执行结果 | 对话回复 / CLI stdout |
+| blueprint 来源 | `.starwork/workspace.json` |
+| 不使用的默认目录 | blueprint `removals` 或 `.starwork/rules/` 中的短规则 |
+| 目录正向边界 | AGENTS 或 `.starwork/rules/` |
+| 项目目标 | current-project |
+| 用户长期偏好 | identity |
+
+## 正向表达规则
+
+不要写：
+
+```text
+Folders Not Used
+- Do not use outputs/
+- Do not use references/
+```
+
+优先写：
+
+```text
+Canonical paths:
+- Code: `src/`
+- Product docs: `docs/`
+- Approved docs: `docs/`
+```
+
+如果确实需要防止 AI 创建旧默认目录，应放入 `.starwork/rules/workspace.file_boundaries.md`，并保持简短：
+
+```markdown
+Use `src/` for implementation and `docs/` for product/design documents.
+Do not create alternate top-level work folders unless the user asks.
+```
+
+## Skill 防发挥机制
+
+### 输出通道分离
+
+Skill 必须区分四类输出：
+
+| 类型 | 可写位置 |
+|---|---|
+| 用户可见执行汇报 | 对话回复 |
+| 机器执行状态 | `.starwork/workspace.json` |
+| 稳定入口规则 | `AGENTS.md` |
+| 扩展规则 | `.starwork/rules/*.md` |
+
+不得把对话汇报写进 AGENTS 或 current-project。
+
+### AGENTS 长度和章节限制
+
+AGENTS 默认只允许这些章节：
+
+```text
+Read First
+Read When Relevant
+File Boundaries
+Workflow
+Confirmation Required
+```
+
+如需新增章节，必须满足：
+
+- 是长期规则。
+- 与用户项目有关。
+- 不是初始化日志。
+- 不重复 `.starwork/rules/` 细节。
+
+### 规则文件限制
+
+`.starwork/rules/` 可以放定制规则，但必须：
+
+- 只写稳定规则。
+- 不写“为什么选择这个方案”的长解释。
+- 不写执行日志。
+- 不写用户没确认的项目事实。
+
+## 举一反三排查
+
+排查所有 Skill 可能污染用户入口文件的路径：
+
+- `product/skills/starworkInit/SKILL.md`
+- `product/skills/starworkDoctor/SKILL.md`
+- `product/kit-skills/starworkSpawn/SKILL.md`
+- `product/kit-skills/starworkAudit/SKILL.md`
+- `product/cli/src/cli.js` 中 AGENTS 渲染、规则注入、upgrade/spawn/init blueprint 逻辑
+- `product/core/project-rules-optimization-spec.md`
+- `product/core/kits/project/AGENTS.md`
+- `product/core/profiles/en/templates/AGENTS.md`
+
+排查关键词：
+
+```text
+why this choice
+why这样选
+Folders Not Used
+后续执行
+dry-run
+doctor
+blueprint
+spec not found
+本机路径
+初始化完成
+```
+
+这些词可出现在 SPEC 或对话模板里，但不能默认出现在生成后的 AGENTS/current-project。
+
+## 验收标准
+
+### AGENTS 文件验收
+
+执行定制初始化后：
+
+```bash
+starwork init --target <tmp> --blueprint <init-blueprint.json> --yes
+```
+
+`AGENTS.md` 必须满足：
+
+- 包含 `Read First`。
+- 包含 `Read When Relevant` 或中文等价章节。
+- 明确 identity 读取时机。
+- 明确 lessons 读取时机。
+- 明确 `.starwork/rules/index.md` 的读取时机。
+- 不包含 `Folders Not Used`。
+- 不包含 `Initialized as`。
+- 不包含 `blueprint`。
+- 不包含 `dry-run`。
+- 不包含 `spec file was not found` 或“本机路径下没找到”。
+
+### Skill 输出验收
+
+触发 `starworkInit` 创建定制工作台时，Agent 必须：
+
+1. 采访或确认目标路径。
+2. 生成 blueprint。
+3. 运行 `starwork init --blueprint --dry-run`。
+4. 汇报 dry-run 给用户确认。
+5. 用户确认后运行 `--yes`。
+6. 运行 `starwork doctor`。
+
+Agent 不得：
+
+- 只生成 blueprint 就结束。
+- 把内部 spec 缺失告诉用户。
+- 把执行过程写入 AGENTS/current-project。
+
+### Doctor / Test 验收
+
+- 新增测试读取生成后的 AGENTS，断言有 identity/lessons 读取时机。
+- 新增测试断言 AGENTS 不含污染关键词。
+- 新增测试断言 current-project 不含污染关键词。
+- `npm test` 通过。
+
+### 防复发验收
+
+- 每个生成 AGENTS 的 Skill 或 CLI path 必须有污染关键词负向测试。
+- 未来新增 Skill 时，必须声明输出通道：对话回复、CLI blueprint、`.starwork/rules/`、项目事实源。
+- 未来新增 blueprint action 时，必须声明可写目标和禁止写入目标。

package/docs/m2.7-init-github-issues-optimization-spec.md

@@ -0,0 +1,350 @@
+# M2.7 Init GitHub Issues Optimization SPEC
+
+## 状态
+
+- 版本：v0.1 draft
+- 所属模块：StarWork CLI / Skills / Core Kit
+- 来源：GitHub Issues #1、#2
+- 目标：修复 A 测中暴露的 `starwork init` 引导和自定义工作台生成问题
+- 优先级：P0
+
+## 背景
+
+GitHub 当前新增两个 open issue：
+
+1. [#1 init should confirm target directory and suggest editable project folder names](https://github.com/jennie-shawn/StarWork/issues/1)
+2. [#2 AGENTS.md generated by init should match custom workspace directories](https://github.com/jennie-shawn/StarWork/issues/2)
+
+这两个问题都发生在用户通过 `starworkInit` 或 `starwork init` 创建工作台的最早阶段。它们不是单纯的文案问题，而是会影响用户信任和 Agent 首次执行方向的问题：
+
+- 如果目标目录没有被明确确认，用户可能把 StarWork 初始化到错误位置。
+- 如果自动生成的文件夹名不好，用户会得到一个一开始就别扭的工作台。
+- 如果自定义结构后 `AGENTS.md` 仍引用默认目录，Agent 会被入口规则带偏，创建错误文件或写入不存在目录。
+
+## 一句话目标
+
+`init` 必须做到：
+
+```text
+先确认写到哪里，
+再确认目录叫什么，
+最后让 AGENTS.md 只描述真实存在、真实要用的目录。
+```
+
+## 产品原则
+
+### 1. 用户确认的是“真实落点”，不是抽象参数
+
+用户不应该只看到：
+
+```text
+type=project
+pack=general
+language=zh
+```
+
+而应该看到：
+
+```text
+将创建到：/Users/example/work/my-project
+工作台名称：my-project
+正式成果：输出/确认成果/
+日常草稿：输出/草稿/
+参考资料：参考资料/，默认只读
+```
+
+### 2. AI 可以建议，但不能替用户决定最终路径
+
+`starworkInit` 可以根据项目名建议文件夹名，但必须让用户知道这是可修改的。
+
+推荐话术：
+
+```text
+我建议文件夹名用 `product-launch-plan`，完整路径是：
+/Users/example/work/product-launch-plan
+
+你可以直接用这个，也可以改成你更喜欢的名字。
+确认后我再执行 dry-run。
+```
+
+### 3. `AGENTS.md` 必须从最终目录计划生成
+
+自定义工作台中，`AGENTS.md` 不能再从默认模板里硬套：
+
+- `输出/草稿/`
+- `输出/确认成果/`
+- `参考资料/`
+- 其他已被用户删除或改名的目录
+
+它必须从最终 blueprint / directory plan 中生成，确保：
+
+- 提到的目录都存在，或被明确标记为 planned placeholder。
+- 每个自定义业务目录都有一句用途说明。
+- 不泄漏默认 Pack、旧模板或 legacy 路径。
+
+## 影响范围
+
+| 模块 | 需要调整 |
+|---|---|
+| `product/skills/starworkInit/` | 增加目标路径确认、文件夹名建议、执行前确认链路。 |
+| `product/cli/src/cli.js` | dry-run 输出最终 target；custom blueprint 渲染 AGENTS 时从最终目录计划生成。 |
+| `product/cli/init-spec.md` | 同步 init 交互与确认规则。 |
+| `product/skills/starworkInit-spec.md` | 同步 skill 采访流程。 |
+| `product/core/kits/project/AGENTS.md` | 确认默认模板只描述默认目录，不强行覆盖 custom 结构。 |
+| `doctor` | 增加或扩展 AGENTS 引用不存在目录的检查。 |
+| tests | 增加自定义目录重命名 / 删除默认目录的回归测试。 |
+
+## Issue #1 方案：目标目录和文件夹名确认
+
+### 当前问题
+
+用户通过 AI 引导创建工作台时，可能没有清楚确认：
+
+- 文件将写入哪个目录。
+- 新建文件夹叫什么。
+- AI 自动建议的文件夹名是否符合用户习惯。
+
+### 目标行为
+
+`starworkInit` 的最终执行建议必须包含：
+
+```text
+工作台类型
+语言
+Pack
+工作台名称
+目标目录绝对路径
+是否新建目录
+正式成果目录
+日常草稿目录
+执行命令
+```
+
+并在真正执行前询问用户确认。
+
+### 文件夹名生成规则
+
+当用户只提供项目名而没有指定文件夹名时，AI 可以建议默认文件夹名。
+
+建议规则：
+
+1. 中文项目名可以生成拼音 / 英文短语 / 用户原文安全化版本，但必须可读。
+2. 英文项目名转为小写短横线。
+3. 去掉路径非法字符。
+4. 不使用过长、难懂、带内部术语的名字。
+5. 如果目标目录已存在且非空，必须提示风险，不自动写入。
+
+示例：
+
+| 用户项目名 | 可建议文件夹名 |
+|---|---|
+| 产品发布计划 | `product-launch-plan` 或 `chanpin-fabu-jihua` |
+| My Writing System | `my-writing-system` |
+| 2026 私域复盘 | `2026-private-domain-review` |
+
+### CLI dry-run 输出要求
+
+`starwork init --dry-run` 必须清楚显示：
+
+```text
+将创建工作台：
+- 类型：项目工作台
+- 语言：中文
+- Pack：general
+- 目标目录：/absolute/path/to/workspace
+- 将创建的新目录：/absolute/path/to/workspace
+```
+
+如果 `--target` 是相对路径，也要显示解析后的绝对路径。
+
+### Skill 执行链路
+
+`starworkInit` 应使用三步执行链路：
+
+```text
+1. 生成建议路径和文件夹名
+2. 请求用户确认或修改
+3. 先 dry-run，再执行 --yes
+```
+
+不能直接从“用户说可以”跳到 `--yes`，除非用户已经明确确认了最终绝对路径。
+
+## Issue #2 方案：自定义结构后的 AGENTS 一致性
+
+### 当前问题
+
+用户定制工作台目录后，`AGENTS.md` 仍出现默认目录，例如：
+
+- `输出/草稿/`
+- `参考资料/`
+
+但这些目录可能已经被用户删除、重命名或替换。这会导致 Agent 入口规则和实际工作台结构冲突。
+
+### 目标行为
+
+当使用 init blueprint 或 custom structure 时：
+
+1. `AGENTS.md` 只引用最终存在的目录。
+2. 如果某个目录是计划占位，必须明确写成“计划目录”，不能假装已经存在。
+3. `AGENTS.md` 增加“工作区目录说明”段落，列出自定义目录和使用场景。
+4. 默认 Pack 目录名不应泄漏到 custom 结构中，除非它们仍在最终目录计划里。
+
+### 推荐 AGENTS 结构
+
+自定义项目的 `AGENTS.md` 应包含：
+
+```markdown
+## 开始前先读
+
+1. `_系统/上下文/当前项目.md`
+2. `_系统/任务/当前工作.md`
+
+## 工作区目录说明
+
+| 目录 | 用途 | 写入规则 |
+|---|---|---|
+| `资料库/` | 存放用户提供的原始资料和参考信息。 | 默认只读；不要改写原始资料。 |
+| `工作稿/` | 存放 AI 生成的草稿、方案和中间版本。 | 可以写入。 |
+| `定稿/` | 存放用户确认后的最终成果。 | 写入前需要用户确认。 |
+
+## 写入边界
+
+- 原始资料不改写。
+- 草稿先进入 `工作稿/`。
+- 用户确认后的成果进入 `定稿/`。
+```
+
+### Blueprint 数据要求
+
+init blueprint 需要有足够信息生成目录说明。
+
+建议新增或稳定字段：
+
+```json
+{
+  "directories": [
+    {
+      "path": "资料库/",
+      "purpose": "存放用户提供的原始资料和参考信息",
+      "write_policy": "read_only_by_default"
+    },
+    {
+      "path": "工作稿/",
+      "purpose": "存放 AI 生成的草稿、方案和中间版本",
+      "write_policy": "writable"
+    },
+    {
+      "path": "定稿/",
+      "purpose": "存放用户确认后的最终成果",
+      "write_policy": "confirm_before_write"
+    }
+  ]
+}
+```
+
+如暂不扩展 schema，也必须从现有 `folders`、`paths`、`agent_rules` 中组装出等价信息。
+
+### 渲染规则
+
+生成 `AGENTS.md` 时，规则来源优先级：
+
+1. 用户确认后的 custom directory plan。
+2. blueprint 中的 `paths.formal_source` 和 `paths.business_work_area`。
+3. 安装后的 Pack 路径。
+4. Project Kit 默认路径。
+
+高优先级已经覆盖低优先级时，低优先级目录不应再出现在 `AGENTS.md` 中。
+
+## Doctor 检查增强
+
+doctor 应新增通用检查：
+
+```text
+agents.references.existing_paths
+```
+
+检查范围：
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `.starwork/rules/index.md`
+- `.starwork/rules/*.md`
+
+检查逻辑：
+
+1. 提取文档中的相对目录 / 文件路径。
+2. 忽略命令示例、URL、代码包名、明显不是路径的文本。
+3. 对工作台内路径做存在性检查。
+4. 如果路径不存在且未被标记为 planned placeholder，输出 warn。
+
+示例 warning：
+
+```text
+AGENTS.md 提到了 `输出/草稿/`，但当前工作台没有这个目录。
+如果这是旧模板残留，建议更新入口规则；如果这是计划目录，请在规则中标注为计划目录。
+```
+
+## 测试计划
+
+### CLI 单元 / 集成测试
+
+新增测试：
+
+1. `init --dry-run --target ./foo` 输出绝对路径。
+2. `init --blueprint custom --dry-run` 输出最终 target 和将创建目录。
+3. custom blueprint 删除 `输出/草稿/`、`参考资料/` 后，生成的 `AGENTS.md` 不包含这些目录。
+4. custom blueprint 使用 `资料库/`、`工作稿/`、`定稿/` 后，`AGENTS.md` 包含目录说明表。
+5. doctor 对引用不存在目录的 `AGENTS.md` 输出 warn。
+6. doctor 对 planned placeholder 不输出误报。
+
+### Skill 回归测试
+
+对 `starworkInit/SKILL.md` 做人工 fixture 检查：
+
+1. 用户只说项目名时，skill 会建议可编辑文件夹名。
+2. 用户没有确认目标路径时，skill 不执行 `--yes`。
+3. 用户要求自定义目录时，skill 会采访每个目录的用途和写入规则。
+4. skill 输出最终执行建议时，包含完整 target path 和 dry-run 命令。
+
+## 实施顺序
+
+### Phase 1：Skill 先收口
+
+- 更新 `starworkInit/SKILL.md`
+- 更新 `starworkInit-spec.md`
+- 要求最终建议必须确认 target path
+- 要求自定义目录采访收集用途和写入规则
+
+### Phase 2：CLI dry-run 和 folder naming
+
+- dry-run 输出绝对 target
+- 增加 folder name 建议逻辑，或在 skill 层先实现建议，CLI 只负责展示
+- 确保 `--target` override 永远优先生效
+
+### Phase 3：AGENTS custom renderer
+
+- 让 custom init 的 `AGENTS.md` 从最终 directory plan 生成
+- 清理默认目录泄漏
+- 增加目录说明段落
+
+### Phase 4：doctor 防复发
+
+- 实现 `agents.references.existing_paths`
+- 给 custom init 加回归测试
+- 给旧路径引用加 warn 测试
+
+## 验收标准
+
+- GitHub #1：用户通过 guided init 时，最终执行前能看到并确认绝对目标路径和可编辑文件夹名。
+- GitHub #2：自定义目录生成的 `AGENTS.md` 不再引用不存在的默认目录，并能解释每个自定义目录的用途。
+- `npm test` 全部通过。
+- `npm --cache /private/tmp/starwork-npm-cache pack --dry-run` 通过。
+- 新增至少 4 个覆盖 issue 场景的测试。
+
+## 非目标
+
+- 本 SPEC 不重新设计 Kit / Pack / Hub / Satellite 的产品边界。
+- 本 SPEC 不实现新的业务 Pack。
+- 本 SPEC 不把 `satellite-starter` 是否保留作为前置条件。
+- 本 SPEC 不要求 CLI 在纯命令行交互中完成所有 AI 采访；复杂采访仍由 `starworkInit` skill 承担。
+