super-engineer-workflow 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+- 增加 `se` / `super-engineer` npm CLI 入口。
+- 增加交互式初始化向导。
+- 增加 `se doctor`、`se install`、`se sync`、`se version`。
+- 增加 npm 打包白名单和临时产物排除规则。
+- 增加 OpenSpec + todo 桥接工作流文档。

package/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+## 开发环境
+
+需要：
+
+- Node.js 18+
+- npm 9+
+- Python 3.10+
+
+## 本地检查
+
+```bash
+npm run check
+npm run smoke
+npm run pack:check
+node bin/super-engineer.js --help
+node bin/super-engineer.js doctor --workspace .
+```
+
+## 修改原则
+
+- `super-engineer-workflow/SKILL.md` 是 skill 主入口，修改命令语义时必须同步更新。
+- `super-engineer-workflow/references/se-commands.md` 是 `/se:*` 协议说明，修改命令流程时必须同步更新。
+- `scripts/` 下脚本是受控执行入口，不要让 AI 通过手写状态文件绕过流程。
+- 发布前必须检查 npm 包内容，确认没有本地工作区产物、缓存文件、密钥或个人路径。
+
+## 发布流程
+
+1. 更新 `package.json.version`。
+2. 更新 `CHANGELOG.md`。
+3. 执行 `npm run check`。
+4. 执行 `npm run pack:check`。
+5. 执行 `npm publish --access public`。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gary-Coding
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,300 @@
+# super-engineer
+
+`super-engineer` 是一个面向存量系统交付场景的 AI 工程工作流项目。
+
+它的目标不是让 AI 零散地写代码，而是让 AI 围绕一次真实需求，按稳定阶段推进：
+
+- 需求理解
+- 计划生成
+- 代码实现
+- 实现自查
+- 代码审查
+- 自动化验证
+- OpenSpec 回写与归档
+
+## 适用场景
+
+- 中大型存量系统
+- 多服务或多仓库工程
+- 需要计划、审查、验证门禁
+- 希望沉淀可回看、可追踪、可归档的交付过程
+- 希望把 OpenSpec 和代码交付流程接起来
+
+## 当前能力
+
+当前版本已经支持：
+
+- `discover -> plan -> implement -> self-check -> review -> verify` 执行流
+- `manual` 与 `auto` 两种执行模式
+- `todo` 与 `openspec` 两种输入模式
+- OpenSpec `tasks.md -> todo_file` 桥接
+- `/se:propose <change-name>` 优先使用 OpenSpec CLI 创建指定 change、读取 status 和 artifact instructions
+- OpenSpec 模式使用 `.super-engineer/se-state.json` 状态机约束阶段跳转
+- `/se:*` 命令可由统一路由入口解析，脚本负责校验阶段与允许命令
+- OpenSpec 执行摘要回写
+- OpenSpec task -> todo -> evidence 映射回写
+- 归档前检查与安全归档
+- 会话级 JSON / Markdown 产物归档
+- 基于 `adapters/*.yml` 的主流语言项目识别与验证命令推断：Java、Node.js / Vue / React、Go、Python，并保留 Rust、.NET、PHP、Ruby、Make / CMake 兜底识别
+- `workspace.yml.verify_commands` 覆盖默认验证命令
+- PushPlus / Feishu 通知
+
+## 工作流分层
+
+推荐把整个流程理解成三个阶段：
+
+1. 规格阶段
+   - OpenSpec change 产出 `proposal.md`、`design.md`、`tasks.md`
+2. 交付阶段
+   - `todo.md` 或 桥接 todo 进入实现工作流
+3. 归档阶段
+   - 回写执行摘要，检查归档条件，满足条件后归档
+
+在 `openspec` 模式下，桥接 todo 是规格到交付之间的桥接产物。  
+桥接 todo 的实际文件路径由 `workspace.yml` 中的 `todo_file` 决定，推荐继续使用 `todo.md`。  
+它应该先被审核，再进入自动实现阶段。
+
+OpenSpec 模式下，脚本会维护 `.super-engineer/se-state.json`。
+`/se:propose` 后只允许 `/se:bridge`，`/se:bridge` 后才允许审核后 `/se:apply`，非法跨阶段命令会被脚本拒绝。
+
+标准工作流产物由脚本写入，AI 不应手工伪造 `.super-engineer` 状态文件、`verify.json`、`notification.json` 或 output 下的标准报告。飞书通知只以 `notification.json` 中由 `run-workflow.py verify` 生成的记录为准。
+
+## `se` 专属命令
+
+这个项目建议用户通过一组发给 AI 的专属命令来使用工作流，而不是直接接触底层脚本。
+
+推荐命令：
+
+- `/se:init`
+- `/se:propose <change-name>`
+- `/se:bridge`
+- `/se:plan`
+- `/se:apply`
+- `/se:review`
+- `/se:verify`
+- `/se:archive-check`
+- `/se:archive`
+- `/se:status`
+
+这些命令的定位是：
+
+- 它们是发给 AI 的工作流指令
+- 不是给用户自己执行的 shell 命令
+- AI 收到命令后，再根据当前 `workspace.yml` 和工作流状态决定内部执行什么
+
+完整协议见：
+
+- [docs/se命令协议.md](/Users/muke/Documents/personal/codex/super-engineer/docs/se命令协议.md)
+
+## 用户如何开始
+
+先准备工作空间，再把命令发给 AI。
+
+如果通过 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   # 查看版本
+```
+
+本地源码开发时，也可以直接使用引导脚本。默认是一步一步的交互式向导：
+
+```bash
+python3 scripts/se-setup.py
+```
+
+脚本会依次完成环境检查、安装目标选择、工作区选择、代码目录配置、需求目录配置、工作流模式选择、OpenSpec 初始化确认，并在执行前展示摘要。最终会创建 `workspace.yml`、`openspec/`、`superengineer/<demand_name>/需求.md`，并可选安装 skill 到 Codex / Claude 本机目录。
+
+如果需要非交互初始化：
+
+```bash
+python3 scripts/se-setup.py \
+  --yes \
+  --install both \
+  --workspace /path/to/ai-workspace \
+  --code-path ../code \
+  --demand-name 1-your-demand \
+  --source openspec \
+  --mode auto
+```
+
+npm 包入口由 `package.json` 的 `bin` 字段提供，`super-engineer` 和 `se` 都会转发到同一个 CLI。
+
+一个真实需求示例：
+
+> 经销商用户列表接口增加手机号精确筛选，要求兼容旧查询行为，并补齐 controller / service 层测试。
+
+`todo` 模式常见起点：
+
+```text
+/se:apply
+使用当前工作空间。
+需求是：经销商用户列表接口增加手机号精确筛选，要求兼容旧查询行为，并补齐 controller / service 层测试。
+当前模式是 todo + auto。
+如果 workspace 未初始化，先初始化；如果没有硬阻塞，直接推进到实现、自查、审查和验证。
+```
+
+`openspec` 模式常见起点：
+
+```text
+/se:propose add-phone-filter
+请根据当前 workspace 的 demand_file 生成或完善 OpenSpec change。
+```
+
+然后：
+
+```text
+/se:bridge
+针对当前 OpenSpec change 生成交付阶段的桥接 todo，并总结待审核项。
+```
+
+人工确认后：
+
+```text
+/se:apply
+使用当前工作空间，当前模式是 openspec + auto。
+我已审核当前桥接 todo，可以进入交付阶段。
+如果没有硬阻塞，自动推进到 verify；verify 通过后继续检查归档条件。
+如果结果为 safe_merge，下一步再执行 /se:archive。
+```
+
+## 工作空间配置
+
+每个业务工作空间都需要有 `workspace.yml`。
+
+最小 `todo` 模式示例：
+
+```yaml
+version: 1
+mode: manual
+workflow_source: todo
+todo_file: todo.md
+reference_files: []
+code_path: ../../../code
+output_dir: output
+```
+
+如果自动识别出的验证命令不适合当前项目，可以在 `workspace.yml` 中覆盖：
+
+```yaml
+verify_commands:
+  default: pnpm test && pnpm build
+  frontend-app: pnpm test && pnpm build
+  user-service: go test ./...
+```
+
+最小 `openspec` 模式示例：
+
+```yaml
+version: 1
+mode: manual
+workflow_source: openspec
+vars:
+  demand_name: add-phone-filter
+demand_file: superengineer/${demand_name}/需求.md
+todo_file: superengineer/${demand_name}/todo.md
+reference_files: []
+code_path: ../../../code
+output_dir: superengineer/${demand_name}/output
+openspec:
+  changes_dir: ../openspec/changes
+```
+
+`demand_file` 可以是本地 Markdown，也可以是飞书/Lark 云文档 URL。使用云文档时需要先安装并授权官方 CLI：
+
+```bash
+npx @larksuite/cli@latest install
+lark-cli config init --new
+lark-cli auth login --recommend
+```
+
+如果同一个工作空间经常切换需求，可以用 `vars` 避免重复修改路径：
+
+```yaml
+version: 1
+mode: auto
+workflow_source: openspec
+vars:
+  demand_name: 7-deamnd-addition-rate
+demand_file: superengineer/${demand_name}/需求.md
+todo_file: superengineer/${demand_name}/todo.md
+reference_files:
+  - ../docs/需求分析与实现指南.md
+code_path: ../../../code
+output_dir: superengineer/${demand_name}/output
+openspec:
+  changes_dir: ../openspec/changes
+```
+
+OpenSpec change 名称不从 `demand_name` 推导。请在 `/se:propose <change-name>` 后显式指定，例如 `/se:propose demand-addition-rate`。后续 `/se:bridge`、`/se:apply` 会使用 propose 阶段记录的当前 change。
+
+skill 自身配置位于：
+
+```text
+~/.super-engineer/skill-config.yml
+```
+
+如果该文件不存在，首次初始化时会自动生成默认配置并暂停流程，等待补全。
+
+## 运行时产物
+
+给机器读取的会话产物：
+
+```text
+<workspace>/.super-engineer/current-session.json
+<workspace>/.super-engineer/sessions/<session_id>/discovery.json
+<workspace>/.super-engineer/sessions/<session_id>/plan.json
+<workspace>/.super-engineer/sessions/<session_id>/self-check.json
+<workspace>/.super-engineer/sessions/<session_id>/review.json
+<workspace>/.super-engineer/sessions/<session_id>/verify.json
+<workspace>/.super-engineer/sessions/<session_id>/status.json
+```
+
+给人查看的报告：
+
+```text
+<output_dir>/<session_id>/discovery.md
+<output_dir>/<session_id>/plan.md
+<output_dir>/<session_id>/self-check.md
+<output_dir>/<session_id>/review.md
+<output_dir>/<session_id>/verify.md
+```
+
+OpenSpec 模式额外产物：
+
+```text
+<workspace>/.super-engineer/openspec-bridge-context.json
+<change_dir>/super-engineer/execution-summary.json
+<change_dir>/super-engineer/archive-input.json
+<change_dir>/super-engineer/archive-result.json
+```
+
+## 文档入口
+
+- [docs/se命令协议.md](/Users/muke/Documents/personal/codex/super-engineer/docs/se命令协议.md)
+- [docs/中文使用手册.md](/Users/muke/Documents/personal/codex/super-engineer/docs/中文使用手册.md)
+- [docs/项目架构与设计说明.md](/Users/muke/Documents/personal/codex/super-engineer/docs/项目架构与设计说明.md)
+- [super-engineer-workflow/SKILL.md](/Users/muke/Documents/personal/codex/super-engineer/super-engineer-workflow/SKILL.md)
+- [super-engineer-workflow/references/workflow.md](/Users/muke/Documents/personal/codex/super-engineer/super-engineer-workflow/references/workflow.md)
+- [super-engineer-workflow/references/contracts.md](/Users/muke/Documents/personal/codex/super-engineer/super-engineer-workflow/references/contracts.md)
+
+## 许可证
+
+本项目使用 [MIT License](/Users/muke/Documents/personal/codex/super-engineer/LICENSE)。

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## 安全边界
+
+Super Engineer 会读取和写入本地工作区、Codex / Claude skill 目录以及配置的代码目录。使用前应确认当前工作区是可信目录。
+
+## 不应提交或发布的内容
+
+- `.super-engineer/` 会话状态与执行产物
+- `superengineer/` 需求中间产物
+- `workspace.yml` 中的个人绝对路径
+- webhook、token、cookie、账号密码
+- `__pycache__/`、`.DS_Store` 等本地缓存
+
+## 通知集成
+
+飞书、PushPlus 等通知配置应放在本机 `~/.super-engineer/skill-config.yml` 中，不应提交到仓库。
+
+## 漏洞反馈
+
+如果发现安全问题，请通过 GitHub issue 联系维护者，并避免在 issue 中公开敏感信息。

package/bin/super-engineer.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+const { spawnSync } = require('child_process')
+const path = require('path')
+
+const root = path.resolve(__dirname, '..')
+const args = process.argv.slice(2)
+
+runPython(path.join(root, 'scripts', 'se-cli.py'), args)
+
+function runPython(script, rest) {
+  const candidates = process.platform === 'win32' ? ['python', 'python3'] : ['python3', 'python']
+  for (const bin of candidates) {
+    const result = spawnSync(bin, [script, ...rest], { stdio: 'inherit' })
+    if (result.error && result.error.code === 'ENOENT') continue
+    process.exit(result.status || 0)
+  }
+  console.error('Python 3 is required but was not found in PATH.')
+  process.exit(1)
+}