super-engineer-workflow 0.1.5 → 0.1.7

package/scripts/se-cli.py

@@ -5,6 +5,7 @@ import argparse
 import importlib.util
 import json
 import os
+import platform
 import shutil
 import subprocess
 import sys
@@ -28,6 +29,65 @@ WORKSPACE_TEMPLATES: dict[str, str] = {
 }
 
 
+SE_COMMANDS: dict[str, str] = {
+    "propose.md": """---
+description: Super Engineer：生成或完善 OpenSpec change
+argument-hint: <change-name>
+---
+
+请使用 super-engineer-workflow skill 执行：`/se:propose $ARGUMENTS`。
+如果 `$ARGUMENTS` 为空，请先询问用户提供 OpenSpec change 名称。
+""",
+    "propose-fix.md": """---
+description: Super Engineer：需求补充后修正当前 OpenSpec change
+argument-hint: <change-name>
+---
+
+请使用 super-engineer-workflow skill 执行：`/se:propose $ARGUMENTS`。
+当前需求有补充，请修正当前 OpenSpec change；不要创建新的 change，不要改代码。
+""",
+    "bridge.md": """---
+description: Super Engineer：生成桥接 todo
+---
+
+请使用 super-engineer-workflow skill 执行：`/se:bridge`。
+生成桥接 todo 并总结待审核项，不要改代码，不要进入实现。
+""",
+    "plan.md": """---
+description: Super Engineer：只生成实施计划
+---
+
+请使用 super-engineer-workflow skill 执行：`/se:plan`。
+只生成计划，不要改代码。
+""",
+    "apply.md": """---
+description: Super Engineer：审核 todo 后进入交付阶段
+---
+
+请使用 super-engineer-workflow skill 执行：`/se:apply`。
+我已审核当前桥接 todo，可以进入交付阶段。
+""",
+    "archive-check.md": """---
+description: Super Engineer：检查 OpenSpec 归档条件
+---
+
+请使用 super-engineer-workflow skill 执行：`/se:archive-check`。
+""",
+    "archive.md": """---
+description: Super Engineer：归档 OpenSpec change
+---
+
+请使用 super-engineer-workflow skill 执行：`/se:archive`。
+""",
+    "status.md": """---
+description: Super Engineer：查看工作流状态
+---
+
+请使用 super-engineer-workflow skill 执行：`/se:status`。
+""",
+}
+
+
 def main() -> None:
     if len(sys.argv) == 1:
         run_setup([])
@@ -56,6 +116,7 @@ def main() -> None:
     doctor_parser = subparsers.add_parser("doctor", help="检查本机环境和工作区配置。")
     doctor_parser.add_argument("--workspace", default=".", help="工作区目录，默认当前目录。")
     doctor_parser.add_argument("--json", action="store_true", help="输出 JSON。")
+    doctor_parser.add_argument("--fix", action="store_true", help="尽量自动补齐 skill 和快捷命令。")
 
     migrate_parser = subparsers.add_parser("migrate", help="补齐旧工作区缺失的 workspace.yml 配置项。")
     migrate_parser.add_argument("--workspace", default=".", help="工作区目录，默认当前目录。")
@@ -63,6 +124,17 @@ def main() -> None:
 
     subparsers.add_parser("templates", help="列出内置 workspace.yml 模板。")
 
+    commands_parser = subparsers.add_parser("commands", help="安装 AI 编码工具快捷命令模板。")
+    commands_subparsers = commands_parser.add_subparsers(dest="commands_action")
+    commands_install = commands_subparsers.add_parser("install", help="安装 /se:* 快捷命令模板。")
+    commands_install.add_argument("--workspace", default=".", help="工作区目录，默认当前目录。")
+    commands_install.add_argument(
+        "--target",
+        choices=["claude", "codex", "cursor", "trae", "kimi", "all"],
+        default="claude",
+        help="目标 AI 编码工具。",
+    )
+
     template_parser = subparsers.add_parser("template", help="查看或复制内置 workspace.yml 模板。")
     template_subparsers = template_parser.add_subparsers(dest="template_action")
     template_show = template_subparsers.add_parser("show", help="打印指定模板内容。")
@@ -87,7 +159,7 @@ def main() -> None:
         install_targets(args.target, force=True)
         return
     if args.command == "doctor":
-        exit_code = doctor(Path(args.workspace).expanduser().resolve(), output_json=args.json)
+        exit_code = doctor(Path(args.workspace).expanduser().resolve(), output_json=args.json, fix=args.fix)
         raise SystemExit(exit_code)
     if args.command == "migrate":
         exit_code = migrate(Path(args.workspace).expanduser().resolve(), dry_run=args.dry_run)
@@ -95,6 +167,12 @@ def main() -> None:
     if args.command == "templates":
         list_templates()
         return
+    if args.command == "commands":
+        if args.commands_action == "install":
+            install_commands(Path(args.workspace).expanduser().resolve(), args.target)
+            return
+        commands_parser.print_help()
+        return
     if args.command == "template":
         if args.template_action == "show":
             show_template(args.name)
@@ -196,14 +274,23 @@ def copy_template(name: str, workspace: Path, demand_name: str, code_path: str,
     print(f"✓ 已写入模板：{target}")
 
 
-def doctor(workspace: Path, output_json: bool) -> int:
+def doctor(workspace: Path, output_json: bool, fix: bool = False) -> int:
+    if fix:
+        install_targets("both", force=True)
+        install_commands(workspace, "all")
+
     checks: list[dict[str, str]] = []
+    add_check(checks, "platform", "ok", f"{platform.system()} {platform.release()}")
     add_check(checks, "python", "ok", sys.version.split()[0])
+    add_check(checks, "node", "ok" if shutil.which("node") else "fail", shutil.which("node") or "未安装")
+    add_check(checks, "npm", "ok" if shutil.which("npm") else "fail", shutil.which("npm") or "未安装")
     add_check(checks, "skill_source", "ok" if SKILL_DIR.exists() else "fail", str(SKILL_DIR))
     add_check(checks, "codex_skill", "ok" if skill_target("codex").exists() else "warn", str(skill_target("codex")))
     add_check(checks, "claude_skill", "ok" if skill_target("claude").exists() else "warn", str(skill_target("claude")))
     add_check(checks, "openspec_cli", "ok" if shutil.which("openspec") else "warn", shutil.which("openspec") or "未安装")
     add_check(checks, "workspace", "ok" if workspace.exists() else "fail", str(workspace))
+    add_check(checks, "workspace.commands.se", "ok" if workspace_commands_ready(workspace) else "warn", str(workspace / ".claude" / "commands" / "se"))
+    add_check(checks, "workspace.openspec.root", "ok" if (workspace / "openspec").exists() else "warn", str(workspace / "openspec"))
 
     workspace_yml = workspace / "workspace.yml"
     add_check(checks, "workspace_yml", "ok" if workspace_yml.exists() else "fail", str(workspace_yml))
@@ -223,10 +310,67 @@ def doctor(workspace: Path, output_json: bool) -> int:
         for check in checks:
             mark = {"ok": "✓", "warn": "!", "fail": "✗"}[check["status"]]
             print(f"{mark} {check['name']}: {check['message']}")
+        suggestions = doctor_suggestions(checks)
+        if suggestions:
+            print("\n建议：")
+            for item in suggestions:
+                print(f"- {item}")
 
     return 1 if any(item["status"] == "fail" for item in checks) else 0
 
 
+def workspace_commands_ready(workspace: Path) -> bool:
+    commands_dir = workspace / ".claude" / "commands" / "se"
+    required = ["propose.md", "bridge.md", "plan.md", "apply.md", "status.md"]
+    return all((commands_dir / name).exists() for name in required)
+
+
+def ensure_workspace_commands(workspace: Path) -> None:
+    install_commands(workspace, "claude")
+
+
+def command_target_dirs(workspace: Path, target: str) -> list[tuple[str, Path]]:
+    home = Path.home()
+    mapping: dict[str, Path] = {
+        "claude": workspace / ".claude" / "commands" / "se",
+        "codex": Path(os.environ.get("CODEX_HOME", str(home / ".codex"))).expanduser() / "prompts",
+        "cursor": workspace / ".cursor" / "commands" / "se",
+        "trae": workspace / ".trae" / "commands" / "se",
+        "kimi": workspace / ".kimi" / "commands" / "se",
+    }
+    if target == "all":
+        return list(mapping.items())
+    return [(target, mapping[target])]
+
+
+def install_commands(workspace: Path, target: str) -> None:
+    workspace.mkdir(parents=True, exist_ok=True)
+    for name, directory in command_target_dirs(workspace, target):
+        directory.mkdir(parents=True, exist_ok=True)
+        for filename, content in SE_COMMANDS.items():
+            output_name = f"se-{filename}" if name == "codex" else filename
+            (directory / output_name).write_text(content, encoding="utf-8")
+        print(f"✓ 已补齐 {name} 快捷命令: {directory}")
+
+
+def doctor_suggestions(checks: list[dict[str, str]]) -> list[str]:
+    by_name = {item["name"]: item for item in checks}
+    suggestions: list[str] = []
+    if by_name.get("codex_skill", {}).get("status") != "ok" or by_name.get("claude_skill", {}).get("status") != "ok":
+        suggestions.append("执行 `se sync --target both` 同步最新 skill。")
+    if by_name.get("workspace.commands.se", {}).get("status") != "ok":
+        suggestions.append("执行 `se doctor --fix` 补齐工作区 `.claude/commands/se/*` 快捷命令。")
+    if by_name.get("workspace_yml", {}).get("status") != "ok":
+        suggestions.append("执行 `se init` 初始化工作区，或用 `se template copy <模板名>` 生成 workspace.yml。")
+    if by_name.get("openspec_cli", {}).get("status") != "ok":
+        suggestions.append("OpenSpec 模式建议先安装并初始化 OpenSpec；todo 模式可忽略。")
+    if by_name.get("workspace.openspec.root", {}).get("status") != "ok":
+        suggestions.append("OpenSpec 模式请在工作区执行 OpenSpec 初始化；todo 模式可忽略。")
+    if by_name.get("node", {}).get("status") != "ok" or by_name.get("npm", {}).get("status") != "ok":
+        suggestions.append("请先安装 Node.js/npm。")
+    return suggestions
+
+
 def add_check(checks: list[dict[str, str]], name: str, status: str, message: str) -> None:
     checks.append({"name": name, "status": status, "message": message})
 

package/scripts/se-e2e-test.py

@@ -24,6 +24,7 @@ def main() -> None:
         os.environ["USERPROFILE"] = str(home)
         test_templates_cli(root)
         test_openspec_state_and_bridge(root)
+        test_incomplete_plan_session_is_reused(root)
         test_todo_auto_session_and_verify_compaction(root)
     print("e2e_test=ok")
 
@@ -57,6 +58,22 @@ def test_templates_cli(root: Path) -> None:
     if "workflow_source: todo" not in workspace_yml or "9-e2e-template" not in workspace_yml:
         raise AssertionError("template copy did not render workspace.yml")
 
+    doctor_before = run(["node", str(CLI), "doctor", "--workspace", str(workspace)], check=False)
+    if "workspace.commands.se" not in doctor_before.output:
+        raise AssertionError("doctor should report workspace command status")
+    run(["node", str(CLI), "doctor", "--workspace", str(workspace), "--fix"], check=False)
+    if not (workspace / ".claude" / "commands" / "se" / "apply.md").exists():
+        raise AssertionError("doctor --fix should create se command templates")
+    run(["node", str(CLI), "commands", "install", "--workspace", str(workspace), "--target", "all"])
+    for command_path in [
+        workspace / ".cursor" / "commands" / "se" / "apply.md",
+        workspace / ".trae" / "commands" / "se" / "apply.md",
+        workspace / ".kimi" / "commands" / "se" / "apply.md",
+        home_prompt(root) / "se-apply.md",
+    ]:
+        if not command_path.exists():
+            raise AssertionError(f"commands install all missing {command_path}")
+
 
 def test_openspec_state_and_bridge(root: Path) -> None:
     workspace = root / "openspec-workspace"
@@ -164,6 +181,57 @@ def test_openspec_state_and_bridge(root: Path) -> None:
     if "demo-change" not in todo or "demo-service" not in todo:
         raise AssertionError("bridged todo.md missing expected OpenSpec context")
 
+    route_check = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-check",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:apply",
+        ]
+    )
+    route_payload = json.loads(route_check)
+    if not route_payload.get("allowed") or route_payload.get("run_command") != "apply":
+        raise AssertionError("route-check should return allowed JSON for bridged /se:apply")
+
+    (change_dir / "tasks.md").write_text(
+        "# Tasks\n\n"
+        "- [ ] 修改 demo-service controller 增加状态查询接口\n"
+        "- [ ] 补充验证，确认接口返回 ok\n"
+        "- [ ] 追加变更后必须重新桥接\n",
+        encoding="utf-8",
+    )
+    stale_apply = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:apply",
+        ],
+        check=False,
+    )
+    if stale_apply.returncode == 0 or "tasks.md 已变化" not in stale_apply.output:
+        raise AssertionError("changed tasks.md should require /se:bridge before /se:apply")
+
+    bridge_again = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:bridge",
+        ]
+    )
+    if "tasks_sha256=" not in bridge_again:
+        raise AssertionError("second /se:bridge should record tasks hash")
+
     first_plan = run(
         [
             sys.executable,
@@ -179,6 +247,9 @@ def test_openspec_state_and_bridge(root: Path) -> None:
         raise AssertionError("first /se:plan should create a session")
     first_session = read_json(workspace / ".super-engineer" / "current-session.json")
     first_session_id = first_session["session_id"]
+    data_dir = Path(first_session["data_dir"])
+    if not (data_dir / "discovery-summary.json").exists():
+        raise AssertionError("plan should create discovery-summary.json")
 
     second_plan = run(
         [
@@ -210,6 +281,21 @@ def test_openspec_state_and_bridge(root: Path) -> None:
     )
     if "apply_phase=implementing" not in apply_output:
         raise AssertionError("/se:apply should enter implementing after planned session")
+    apply_json_output = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:apply",
+            "--json",
+        ],
+        check=False,
+    )
+    if "route_result_json_begin" not in apply_json_output.output and "当前状态不允许进入实现" not in apply_json_output.output:
+        raise AssertionError("route-se --json should emit JSON summary or a state guard")
     blocked_plan = run(
         [
             sys.executable,
@@ -323,6 +409,84 @@ def test_todo_auto_session_and_verify_compaction(root: Path) -> None:
         raise AssertionError("notification should be marked skipped when no provider is configured")
 
 
+def test_incomplete_plan_session_is_reused(root: Path) -> None:
+    workspace = root / "incomplete-plan-workspace"
+    code = root / "broken-code" / "not-a-project"
+    demand_dir = workspace / "superengineer" / "10-broken"
+    demand_dir.mkdir(parents=True)
+    code.mkdir(parents=True)
+    (workspace / "docs").mkdir(parents=True)
+    (workspace / "workspace.yml").write_text(
+        "\n".join(
+            [
+                "version: 1",
+                "mode: auto",
+                "workflow_source: todo",
+                "vars:",
+                "  demand_name: 10-broken",
+                "todo_file: superengineer/${demand_name}/todo.md",
+                "reference_files: []",
+                "code_path: ../broken-code/not-a-project",
+                "output_dir: superengineer/${demand_name}/output",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+    (demand_dir / "todo.md").write_text(
+        "# 限制条件\n"
+        "- 修改的服务是 broken-service\n\n"
+        "# 待办事项\n\n"
+        "- [ ] 增加一个测试接口\n",
+        encoding="utf-8",
+    )
+
+    first_apply = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:apply",
+        ],
+        check=False,
+    )
+    if first_apply.returncode == 0 or "未找到可识别的项目目录" not in first_apply.output:
+        raise AssertionError("first /se:apply should fail before plan is generated")
+    current = read_json(workspace / ".super-engineer" / "current-session.json")
+    first_session_id = current["session_id"]
+    sessions_dir = workspace / ".super-engineer" / "sessions"
+    output_dir = workspace / "superengineer" / "10-broken" / "output"
+    if len(list(sessions_dir.iterdir())) != 1:
+        raise AssertionError("first failed /se:apply should create exactly one reusable data session")
+    if output_dir.exists() and list(output_dir.iterdir()):
+        raise AssertionError("failed plan should not create an empty output report session")
+
+    second_apply = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:apply",
+        ],
+        check=False,
+    )
+    if second_apply.returncode == 0 or "session_action=reused_incomplete" not in second_apply.output:
+        raise AssertionError("second /se:apply should reuse the incomplete planning session")
+    current = read_json(workspace / ".super-engineer" / "current-session.json")
+    if current["session_id"] != first_session_id:
+        raise AssertionError("incomplete planning session should remain current")
+    if len(list(sessions_dir.iterdir())) != 1:
+        raise AssertionError("repeated failed /se:apply should not create another data session")
+    if output_dir.exists() and list(output_dir.iterdir()):
+        raise AssertionError("repeated failed /se:apply should not create output report sessions")
+
+
 def run(command: list[str], check: bool = True, env: dict[str, str] | None = None):
     result = subprocess.run(
         command,
@@ -341,6 +505,10 @@ def run(command: list[str], check: bool = True, env: dict[str, str] | None = Non
     return CommandResult(result.returncode, result.stdout)
 
 
+def home_prompt(root: Path) -> Path:
+    return root / "home" / ".codex" / "prompts"
+
+
 class CommandResult:
     def __init__(self, returncode: int, output: str) -> None:
         self.returncode = returncode

package/scripts/se-setup.py

@@ -423,14 +423,25 @@ def print_summary(workspace: Path, demand_name: str, source: str, mode: str) ->
     print(f"mode={mode}")
     print("")
     if source == "openspec":
-        print("下一步提示词：")
+        print("推荐使用流程：")
         print(f"/se:propose <change-name>")
         print("请根据当前 workspace 的 demand_file 生成或完善 OpenSpec change。")
         print("不要改代码。过程中请使用中文。")
+        print("")
+        print("/se:bridge")
+        print("把 OpenSpec tasks.md 桥接为待审核 todo.md，不要改代码。")
+        print("")
+        print("人工审核 todo.md 后：")
+        print("/se:apply")
+        print("我已审核当前桥接 todo，可以进入交付阶段。")
     else:
-        print("下一步提示词：")
+        print("推荐使用流程：")
+        print("先编辑 todo_file，确认任务和验收标准。")
+        print("")
         print("/se:apply")
         print("请根据当前 workspace 的 todo_file 推进交付工作流。过程中请使用中文。")
+    print("")
+    print("诊断命令：se doctor --workspace <workspace>")
 
 
 if __name__ == "__main__":

package/super-engineer-workflow/SKILL.md

@@ -24,16 +24,27 @@ Supported commands:
 - `/se:archive`
 - `/se:status`
 
-For command details, read only the relevant section in [references/se-commands.md](references/se-commands.md).
+For command details, read [references/commands/common.md](references/commands/common.md) plus only the matching command file:
+
+- `/se:propose`: [references/commands/propose.md](references/commands/propose.md)
+- `/se:bridge`: [references/commands/bridge.md](references/commands/bridge.md)
+- `/se:plan`: [references/commands/plan.md](references/commands/plan.md)
+- `/se:apply`: [references/commands/apply.md](references/commands/apply.md)
+- `/se:review`: [references/commands/review.md](references/commands/review.md)
+- `/se:verify`: [references/commands/verify.md](references/commands/verify.md)
+- `/se:archive-check` and `/se:archive`: [references/commands/archive.md](references/commands/archive.md)
+- `/se:status`: [references/commands/status.md](references/commands/status.md)
+
 For mode and artifact details, use [references/workflow.md](references/workflow.md) and [references/execution-modes.md](references/execution-modes.md) only when needed.
 
 ## Minimal Required Steps
 
 1. Read `<workspace>/workspace.yml`.
 2. Identify `workflow_source`, `mode`, `todo_file`, `demand_file`, `reference_files`, `code_path`, `output_dir`, and optional `openspec` fields.
-3. Route the current command through `python3 scripts/run-workflow.py route-se --command-text "<command>"` when possible.
-4. Obey script state validation and script reply constraints.
-5. Report compactly: result, blockers, allowed next command, and key artifact paths.
+3. Preflight with `python3 scripts/run-workflow.py route-check --command-text "<command>"` when possible.
+4. Route the current command through `python3 scripts/run-workflow.py route-se --command-text "<command>"` when preflight passes.
+5. Obey script state validation and script reply constraints.
+6. Report compactly: result, blockers, allowed next command, and key artifact paths.
 
 ## Hard Constraints
 
@@ -59,6 +70,8 @@ For mode and artifact details, use [references/workflow.md](references/workflow.
 - `reference_files` are strong context, but scripts summarize large files by default; read full files only when necessary for the current command.
 - In OpenSpec mode, avoid rereading `proposal.md`, `design.md`, and `specs/**/*.md` unless the current stage needs them.
 - Prefer `plan-summary.json` for downstream context; use `plan.json` only when detailed planning data is required.
+- Prefer `discovery-summary.json` over `discovery.json`; read full discovery only for detailed code evidence.
+- Prefer `route-se --json` when a machine-readable execution summary is useful.
 - Final replies should be compact. Detailed reports belong in `output_dir/<session_id>/`.
 
 ## State Summary
@@ -75,10 +88,12 @@ Todo mode uses current session `status.json` and `todo-state.json`; do not write
 
 ## Script Entry Points
 
+- Preflight router: `python3 scripts/run-workflow.py route-check --command-text "<command>"`
 - Main router: `python3 scripts/run-workflow.py route-se --command-text "<command>"`
+- JSON router summary: `python3 scripts/run-workflow.py route-se --command-text "<command>" --json`
 - Status: `python3 scripts/run-workflow.py status`
 - Plan: `python3 scripts/run-workflow.py plan`
 - Review: `python3 scripts/run-workflow.py review`
 - Verify: `python3 scripts/run-workflow.py verify`
 
-OpenSpec-specific internal commands are listed in [references/se-commands.md](references/se-commands.md).
+OpenSpec-specific execution details are enforced by the command files under [references/commands/](references/commands/).

package/super-engineer-workflow/references/commands/apply.md

@@ -0,0 +1,28 @@
+# `/se:apply`
+
+用途：进入交付阶段，按计划实现、生成自查，并在 auto 模式继续 review/verify。
+
+## 前置
+
+- todo 模式：存在有效 `todo.md`。
+- openspec 模式：已经 `/se:bridge`，且用户已审核 `todo.md`。
+- 如无计划，脚本可创建或复用标准 session 并生成计划。
+- OpenSpec `tasks.md` hash 必须与最近 bridge 记录一致。
+
+## 执行
+
+1. 先执行公共 `route-check`。
+2. 再执行：
+   `python3 scripts/run-workflow.py route-se --command-text "/se:apply"`
+3. AI 按当前 `plan-summary.json` / `plan.json` 修改目标代码。
+4. 修改完成后调用 `finish-implement`，由脚本生成 self-check。
+5. auto 模式继续由标准脚本推进 review、verify 和通知。
+
+## 禁止
+
+- 禁止第二次手工执行 `/se:plan` 创建新 session。
+- 禁止手写状态文件或 output 报告。
+- 禁止直接发飞书/PushPlus 通知。
+- verify 通过前禁止提示 archive。
+
+最终回复汇报改动、review、verify、通知和允许的下一步。

package/super-engineer-workflow/references/commands/archive.md

@@ -0,0 +1,23 @@
+# `/se:archive-check` 与 `/se:archive`
+
+## `/se:archive-check`
+
+用途：检查 OpenSpec change 是否可以安全归档。
+
+前置：`/se:verify` 已通过。
+
+执行：
+`python3 scripts/run-workflow.py route-se --command-text "/se:archive-check"`
+
+只有 `archive_ready=true`、`merge_mode=safe_merge` 且无 spec 冲突时，才允许提示 `/se:archive`。
+
+## `/se:archive`
+
+用途：归档当前 OpenSpec change，沉淀长期 specs。
+
+前置：已完成 `/se:archive-check` 且结果为 safe merge。
+
+执行：
+`python3 scripts/run-workflow.py route-se --command-text "/se:archive"`
+
+禁止跳过 archive-check 直接归档。

package/super-engineer-workflow/references/commands/bridge.md

@@ -0,0 +1,25 @@
+# `/se:bridge`
+
+用途：把当前 OpenSpec change 的 `tasks.md` 转成待审核 `todo.md`。
+
+## 前置
+
+- 已有 active OpenSpec change。
+- 已存在 `proposal.md`、`design.md`、`tasks.md`。
+- 当前阶段为 `proposed` 或允许重新 bridge 的 `bridged`。
+
+## 执行
+
+1. 先执行公共 `route-check`。
+2. 再执行：
+   `python3 scripts/run-workflow.py route-se --command-text "/se:bridge"`
+3. 脚本生成 `todo.md`，并记录 `tasks.md` hash。
+4. 停在 `bridged` 阶段。
+
+## 禁止
+
+- 禁止手工同步 `tasks.md` 到 `todo.md`。
+- 禁止自动进入 `/se:plan` 或 `/se:apply`。
+- 如果审核后发现需求或 todo 有偏差，先修正需求或重新 `/se:propose <change-name>`，再重新 `/se:bridge`。
+
+最终回复只能提示：请人工审核 `todo.md`，审核通过后发送 `/se:apply`。

package/super-engineer-workflow/references/commands/common.md

@@ -0,0 +1,32 @@
+# `/se:*` 公共协议
+
+`/se:*` 是 Super Engineer Workflow 的 AI 阶段命令，不是 shell 命令，也不是 OpenSpec `/opsx:*`。
+
+## 必做
+
+1. 读取当前工作区 `workspace.yml`。
+2. 通过 `python3 scripts/run-workflow.py route-check --command-text "<用户命令>"` 做状态预检。
+3. 预检通过后，再执行 `python3 scripts/run-workflow.py route-se --command-text "<用户命令>"`。
+4. 遵守脚本输出的 `final_reply_must` 或 `se_reply_constraint_begin/end`。
+5. 最终回复只汇报结果、阻塞点、允许的下一步和关键相对路径。
+
+## 硬约束
+
+- 禁止编辑 `workspace.yml`。
+- 禁止手写 `.super-engineer/**/status.json`、`se-state.json`、`current-session.json`、`plan.json`、`review.json`、`verify.json`、`notification.json`。
+- 标准状态、报告、通知只能由脚本生成。
+- 一次只执行用户当前明确请求的一个 `/se:*` 命令。
+- `/se:propose` 之后只能提示 `/se:bridge`。
+- `/se:bridge` 之后只能提示人工审核 `todo.md`，审核后 `/se:apply`。
+- `/se:apply` 之前必须已经完成 bridge 且用户已审核 todo。
+- 通知只能由 `run-workflow.py verify` 发送，AI 禁止直接调用飞书或 PushPlus webhook。
+
+## 最小上下文
+
+- `/se:propose`：`workspace.yml`、`demand_file`、必要 `reference_files` 摘要。
+- `/se:bridge`：`tasks.md`、bridge context、`todo_file`。
+- `/se:plan`：`todo.md`、`discovery-summary` 或脚本生成的 plan 产物。
+- `/se:apply`：优先 `todo.md`、`plan-summary.json`、目标代码文件。
+- `/se:review` / `/se:verify`：优先读取 summary 和脚本报告，不展开长 diff 或长日志。
+
+命令细节只允许读取 `references/commands/` 下的对应命令文件。

package/super-engineer-workflow/references/commands/plan.md

@@ -0,0 +1,25 @@
+# `/se:plan`
+
+用途：只生成实施计划，不改代码。
+
+## 前置
+
+- todo 模式：存在有效 `todo.md`。
+- openspec 模式：已经 `/se:bridge`，且用户已审核 `todo.md`。
+- 当前不存在已进入实现、review、verify 的活跃 session。
+
+## 执行
+
+1. 先执行公共 `route-check`。
+2. 再执行：
+   `python3 scripts/run-workflow.py route-se --command-text "/se:plan"`
+3. 脚本生成 `discovery.json`、`plan.json`、`plan-summary.json`、`plan.md`。
+4. 如果已有可复用计划 session，必须复用，不能新建空 session。
+
+## 禁止
+
+- 禁止改代码。
+- 禁止继续 review/verify。
+- OpenSpec `tasks.md` hash 与 bridge 记录不一致时，必须停止并要求重新 `/se:bridge`。
+
+最终回复提示下一步 `/se:apply`。