super-engineer-workflow 0.1.0

package/docs//345/205/254/345/274/200/345/217/221/345/270/203/346/243/200/346/237/245/346/270/205/345/215/225.md

@@ -0,0 +1,43 @@
+# 公开发布检查清单
+
+本文用于发布 `super-engineer-workflow` npm 包前自查。
+
+## 必须检查
+
+- `package.json` 已包含 `name`、`version`、`description`、`license`、`author`、`repository`、`homepage`、`bugs`、`engines`、`publishConfig`。
+- `README.md` 首屏说明清楚：这是什么、适合什么场景、如何 5 分钟开始。
+- `LICENSE`、`CHANGELOG.md`、`CONTRIBUTING.md`、`SECURITY.md` 已存在。
+- `npm run check` 通过。
+- `npm run smoke` 通过。
+- `npm run pack:check` 通过，并确认包内不包含本地工作区产物、缓存文件、密钥、个人绝对路径。
+- `node bin/super-engineer.js --help` 正常。
+- `node bin/super-engineer.js version` 正常。
+- `node bin/super-engineer.js init --yes --install none --workspace <tmp> ...` 正常。
+- `node bin/super-engineer.js doctor --workspace <tmp>` 正常。
+
+## CLI 能力
+
+公开包至少应提供：
+
+- `se init`：交互式初始化。
+- `se doctor`：检查本机环境和工作区配置。
+- `se install`：安装 skill 到 Codex / Claude。
+- `se sync`：强制同步当前包内 skill 到 Codex / Claude。
+- `se migrate`：补齐旧工作区缺失配置项。
+- `se version`：显示版本。
+
+## 技术规范建议
+
+- 保持 CLI 无第三方运行时依赖，降低安装失败概率。
+- 所有本地路径默认支持相对路径和绝对路径。
+- 不把通知 webhook、token、cookie 写入仓库，只放在用户本机配置。
+- 不让 AI 手写状态文件、验证报告、通知记录等标准产物。
+- npm 包只发布 skill、脚本、文档和许可证，不发布工作区中间产物。
+- 发布前用 CI 在 macOS、Windows、Linux 上跑 smoke test。
+
+## 仍可继续增强
+
+- 增加 `se templates`，列出 Java / Node / Go / Python / 通用存量系统模板。
+- 增加 `se doctor --fix`，自动创建缺失目录或提示最小修复命令。
+- 增加 E2E fixture，完整验证 `openspec + auto` 和 `todo + auto` 状态流。
+- 增加 npm provenance / signed publishing，提升供应链可信度。

package/docs//345/277/253/351/200/237/345/210/235/345/247/213/345/214/226/345/267/245/344/275/234/345/214/272.md

@@ -0,0 +1,419 @@
+# 快速初始化工作区
+
+这份文档用于从零准备一个可运行的 `super-engineer + OpenSpec` 工作区。目标是让用户只需要准备目录、配置文件和提示词，后续由 AI 根据 skill 调用受控脚本推进流程。
+
+## 1. 目录约定
+
+推荐把工作区、代码仓库和 OpenSpec 放在同一个上层目录下：
+
+```text
+ai-workspace/
+├── workspace.yml
+├── docs/
+│   ├── 需求分析与实现指南.md
+│   └── 开发规范.md
+├── openspec/
+│   ├── specs/
+│   └── changes/
+└── superengineer/
+    └── 10-your-demand/
+        └── 需求.md
+
+code/
+├── frontend-app/
+├── item-core/
+└── other-service/
+```
+
+约定：
+
+- `ai-workspace` 是每次打开给 AI 的工作区根目录。
+- `workspace.yml` 必须放在 `ai-workspace` 根目录。
+- `openspec/` 放在 `ai-workspace` 下。
+- `superengineer/<demand_name>/` 放当前需求输入、桥接 todo 和输出报告。
+- `code_path` 指向真实代码目录，可以是单仓库，也可以是多仓库聚合目录。
+
+## 2. 初始化 OpenSpec
+
+在 `ai-workspace` 根目录初始化 OpenSpec：
+
+```bash
+cd /path/to/ai-workspace
+openspec init . --tools codex,claude
+```
+
+初始化后应至少存在：
+
+```text
+ai-workspace/
+└── openspec/
+    ├── specs/
+    └── changes/
+```
+
+如果团队只用 Codex：
+
+```bash
+openspec init . --tools codex
+```
+
+如果团队只用 Claude：
+
+```bash
+openspec init . --tools claude
+```
+
+重要约束：
+
+- 不要在 `ai-workspace/openspec` 目录里再次执行 `openspec init`。
+- OpenSpec CLI 的工作目录应该是 `ai-workspace`，不是 `ai-workspace/openspec`。
+- `workspace.yml.openspec.changes_dir` 推荐写 `openspec/changes`。
+
+## 3. 安装 Skill
+
+Codex skill 目录：
+
+```text
+~/.codex/skills/super-engineer-workflow
+```
+
+Claude skill 目录：
+
+```text
+~/.claude/skills/super-engineer-workflow
+```
+
+如果是从本项目同步：
+
+```bash
+rsync -a --delete super-engineer-workflow/ ~/.codex/skills/super-engineer-workflow/
+rsync -a --delete super-engineer-workflow/ ~/.claude/skills/super-engineer-workflow/
+```
+
+同步后可以检查：
+
+```bash
+python3 -m py_compile ~/.codex/skills/super-engineer-workflow/scripts/*.py
+python3 -m py_compile ~/.claude/skills/super-engineer-workflow/scripts/*.py
+```
+
+也可以使用项目自带引导脚本安装并初始化工作区。默认是一步一步的交互式向导：
+
+```bash
+cd /path/to/super-engineer
+python3 scripts/se-setup.py
+```
+
+脚本会按 7 个步骤执行：
+
+1. 环境检查：展示 Python、skill 目录、OpenSpec CLI 是否可用。
+2. 选择安装目标：安装到 Codex、Claude、两者都安装，或暂不安装。
+3. 选择业务工作区目录。
+4. 配置代码目录 `code_path` 和当前需求目录名。
+5. 选择输入模式：`openspec` 或 `todo`。
+6. 选择是否尝试执行 `openspec init`。
+7. 展示初始化摘要，确认后再真正写入文件。
+
+如果需要非交互初始化：
+
+```bash
+python3 scripts/se-setup.py \
+  --yes \
+  --install both \
+  --workspace /path/to/ai-workspace \
+  --code-path ../code \
+  --demand-name 10-your-demand \
+  --source openspec \
+  --mode auto
+```
+
+常用参数：
+
+- `--install both`：同时安装到 Codex 和 Claude。本机只用其中一个时，可改为 `codex` 或 `claude`。
+- `--workspace`：业务工作区根目录。
+- `--code-path`：真实代码目录，写入 `workspace.yml.code_path`。
+- `--demand-name`：当前需求目录名。
+- `--source`：`openspec` 或 `todo`。
+- `--mode`：`auto` 或 `manual`。
+- `--force-skill`：安装 skill 时先删除旧目录再复制。
+
+如果发布成 npm 包，初始化入口可以变为：
+
+```bash
+npx super-engineer-workflow init
+```
+
+或全局安装后使用：
+
+```bash
+npm install -g super-engineer-workflow
+se init
+```
+
+常用 CLI：
+
+```bash
+se init      # 交互式安装 skill 并初始化工作区
+se doctor    # 检查本机环境和 workspace.yml
+se install   # 安装 skill 到 Codex / Claude
+se sync      # 强制同步最新 skill 到 Codex / Claude
+se migrate   # 补齐旧工作区缺失配置
+se version   # 查看版本
+```
+
+npm 安装的核心要求：
+
+- `package.json` 声明 `bin.super-engineer` 和 `bin.se`。
+- bin 脚本转发到 `scripts/se-setup.py`。
+- 发布前执行 `npm pack --dry-run` 检查包内容。
+- 首次发布执行 `npm publish --access public`，后续升级先更新 `package.json.version` 再发布。
+
+## 4. 安装快捷命令
+
+Claude Code 的快捷命令放在工作区：
+
+```text
+ai-workspace/.claude/commands/se/
+```
+
+Codex 的快捷命令放在全局：
+
+```text
+~/.codex/prompts/
+```
+
+如果没有快捷命令，也可以直接把 `/se:*` 提示词发给 AI。skill 仍然能识别并执行。
+
+常用命令：
+
+```text
+/se:propose <change-name>
+/se:bridge
+/se:plan
+/se:apply
+/se:status
+/se:archive-check
+/se:archive
+```
+
+## 5. 配置 workspace.yml
+
+OpenSpec + auto 推荐配置：
+
+```yaml
+version: 1
+mode: auto
+workflow_source: openspec
+
+vars:
+  demand_name: 10-your-demand
+
+demand_file: superengineer/${demand_name}/需求.md
+todo_file: superengineer/${demand_name}/todo.md
+
+reference_files:
+  - docs/需求分析与实现指南.md
+  - docs/开发规范.md
+
+code_path: ../code
+output_dir: superengineer/${demand_name}/output
+
+openspec:
+  changes_dir: openspec/changes
+```
+
+字段说明：
+
+- `mode: auto`：`/se:apply` 后自动推进实现、自查、审查、验证。
+- `workflow_source: openspec`：先走 OpenSpec change，再桥接到 todo。
+- `vars.demand_name`：当前需求目录名。
+- `demand_file`：原始需求输入。
+- `todo_file`：`/se:bridge` 生成的交付入口。
+- `reference_files`：AI 在 propose / plan / review 阶段必须读取的参考资料。
+- `code_path`：真实代码目录。
+- `openspec.changes_dir`：固定推荐 `openspec/changes`。
+
+如果需求来源是飞书云文档：
+
+```yaml
+demand_file: https://example.feishu.cn/wiki/xxxx
+```
+
+本机需要安装并授权飞书官方 `lark-cli`：
+
+```bash
+npx @larksuite/cli@latest install
+lark-cli config init --new
+lark-cli auth login --recommend
+lark-cli auth status
+```
+
+## 6. 准备需求目录
+
+创建需求目录：
+
+```text
+ai-workspace/superengineer/10-your-demand/
+└── 需求.md
+```
+
+`需求.md` 建议包含：
+
+- 背景和目标
+- 业务规则
+- 接口或页面范围
+- 涉及服务
+- 数据表或字段
+- 验收标准
+- 明确不做的范围
+
+## 7. 开始 OpenSpec 工作流
+
+第一步，生成 OpenSpec change：
+
+```text
+/se:propose your-change-name
+请根据当前 workspace 的 demand_file 生成或完善 OpenSpec change。
+不要改代码。
+过程中请使用中文。
+```
+
+这一步只允许生成或完善：
+
+```text
+openspec/changes/your-change-name/proposal.md
+openspec/changes/your-change-name/design.md
+openspec/changes/your-change-name/tasks.md
+openspec/changes/your-change-name/specs/**
+```
+
+完成后状态必须是：
+
+```text
+phase=proposed
+allowed_next=/se:bridge
+```
+
+第二步，桥接成 todo：
+
+```text
+/se:bridge
+针对当前 OpenSpec change 生成桥接 todo，并总结待审核项。
+不要改代码，不要进入实现。
+过程中请使用中文。
+```
+
+这一步会生成：
+
+```text
+superengineer/10-your-demand/todo.md
+```
+
+第三步，人工审核 `todo.md`。
+
+如果发现需求或任务有偏差，先修改 `需求.md` 或飞书文档，然后重新执行：
+
+```text
+/se:propose your-change-name
+当前需求有补充，请基于修改后的 demand_file 修正当前 OpenSpec change。
+不要创建新的 change。
+不要改代码。
+过程中请使用中文。
+```
+
+然后再次执行：
+
+```text
+/se:bridge
+```
+
+第四步，审核通过后进入交付：
+
+```text
+/se:apply
+我已审核当前桥接 todo，可以进入交付阶段。
+如果没有硬阻塞，自动推进到实现、自查、审查和验证。
+过程中请使用中文。
+```
+
+## 8. 验证初始化是否正确
+
+检查 OpenSpec 路径是否正确：
+
+```text
+正确：ai-workspace/openspec/changes/<change-name>
+错误：ai-workspace/openspec/openspec/changes/<change-name>
+```
+
+如果出现 `openspec/openspec/changes`，说明 OpenSpec CLI 的工作目录错了，应该从 `ai-workspace` 重新执行工作流。
+
+检查状态：
+
+```text
+/se:status
+请检查当前工作流状态，并说明当前阶段、允许的下一步和阻塞项。
+```
+
+正常阶段顺序：
+
+```text
+draft
+-> proposed
+-> bridged
+-> planned
+-> implementing
+-> self_checked
+-> reviewed
+-> verified
+-> archive_ready
+-> archived
+```
+
+## 9. 最小可用流程
+
+如果只想快速跑通一轮，按这个顺序：
+
+```text
+/se:propose your-change-name
+请根据当前 workspace 的 demand_file 生成或完善 OpenSpec change。
+不要改代码。
+过程中请使用中文。
+```
+
+```text
+/se:bridge
+针对当前 OpenSpec change 生成桥接 todo，并总结待审核项。
+不要改代码，不要进入实现。
+过程中请使用中文。
+```
+
+人工审核：
+
+```text
+superengineer/<demand_name>/todo.md
+```
+
+```text
+/se:apply
+我已审核当前桥接 todo，可以进入交付阶段。
+如果没有硬阻塞，自动推进到实现、自查、审查和验证。
+过程中请使用中文。
+```
+
+## 10. 常见问题
+
+### `/se:propose` 会不会自动生成 todo？
+
+不会。`/se:propose` 只能生成 OpenSpec change 文档。只有显式执行 `/se:bridge` 才允许生成或重写 `todo_file`。
+
+### `workspace.yml` 能不能让 AI 自动修改？
+
+不能。`workspace.yml` 是工作空间契约，只能由用户维护。AI 只能读取和校验。
+
+### `todo.md` 审核后发现不对怎么办？
+
+不要手工把 `tasks.md` 同步到 `todo.md`。正确做法是补充需求，重新执行 `/se:propose <change-name>`，然后重新 `/se:bridge`。
+
+### 可以跳过 `/se:bridge` 直接 `/se:apply` 吗？
+
+OpenSpec 模式下不可以。`/se:apply` 前必须先有经过人工审核的桥接 todo。