super-engineer-workflow 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.5
+
+- 修复重复执行 `/se:plan` 会创建多个 session 的问题：计划阶段复用当前 session，交付中重复 plan 会被拒绝。
+- 增加 E2E 测试，覆盖模板 CLI、OpenSpec 状态机与桥接、todo auto 会话、verify 长日志截断。
+- 增加 `se templates`、`se template show`、`se template copy`，支持复制内置 `workspace.yml` 模板。
+- 增加 OpenSpec、todo、Java 微服务、前端、多仓库等工作区模板。
+- 增加模板使用指南，并在 README 和快速初始化文档中补充模板入口。
+
 ## 0.1.4
 
 - Review 阶段优先读取 `plan-summary.json`，仅在缺失时回退到 `plan.json`。

package/README.md

@@ -111,12 +111,23 @@ se init
 ```bash
 se init      # 交互式安装 skill 并初始化工作区
 se doctor    # 检查本机环境和 workspace.yml
+se templates # 查看内置 workspace.yml 模板
 se install   # 安装 skill 到 Codex / Claude
 se sync      # 强制同步最新 skill 到 Codex / Claude
 se migrate   # 补齐旧工作区缺失配置
 se version   # 查看版本
 ```
 
+模板入口：
+
+```bash
+se templates
+se template show openspec-auto
+se template copy openspec-auto --workspace /path/to/ai-workspace --demand-name 13-your-demand --code-path ../code
+```
+
+模板说明见 [docs/模板使用指南.md](/Users/muke/Documents/personal/codex/super-engineer/docs/模板使用指南.md)。
+
 本地源码开发时，也可以直接使用引导脚本。默认是一步一步的交互式向导：
 
 ```bash

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

@@ -176,12 +176,25 @@ se init
 ```bash
 se init      # 交互式安装 skill 并初始化工作区
 se doctor    # 检查本机环境和 workspace.yml
+se templates # 查看内置 workspace.yml 模板
 se install   # 安装 skill 到 Codex / Claude
 se sync      # 强制同步最新 skill 到 Codex / Claude
 se migrate   # 补齐旧工作区缺失配置
 se version   # 查看版本
 ```
 
+如果你不想从零写 `workspace.yml`，可以先复制内置模板：
+
+```bash
+se templates
+se template copy openspec-auto \
+  --workspace /path/to/ai-workspace \
+  --demand-name 10-your-demand \
+  --code-path ../code
+```
+
+模板不会覆盖已有 `workspace.yml`，除非显式增加 `--force`。模板说明见 `docs/模板使用指南.md`。
+
 npm 安装的核心要求：
 
 - `package.json` 声明 `bin.super-engineer` 和 `bin.se`。

package/docs//346/250/241/346/235/277/344/275/277/347/224/250/346/214/207/345/215/227.md

@@ -0,0 +1,55 @@
+# 模板使用指南
+
+`super-engineer` 内置了一组 `workspace.yml` 模板，用于减少团队初始化成本，并让不同项目按统一结构接入工作流。
+
+## 查看模板
+
+```bash
+se templates
+se template show openspec-auto
+```
+
+## 复制模板到工作区
+
+```bash
+se template copy openspec-auto \
+  --workspace /path/to/ai-workspace \
+  --demand-name 13-your-demand \
+  --code-path ../code
+```
+
+默认不会覆盖已有 `workspace.yml`。确实需要覆盖时加：
+
+```bash
+se template copy openspec-auto --workspace /path/to/ai-workspace --force
+```
+
+## 模板选择
+
+| 模板 | 适用场景 |
+| --- | --- |
+| `openspec-auto` | 推荐默认模板。先生成 OpenSpec change，再桥接 todo，审核后自动交付。 |
+| `openspec-manual` | 高风险需求。每个关键阶段都需要人工确认。 |
+| `todo-auto` | 小需求、任务已经明确、不需要规格沉淀。 |
+| `todo-manual` | 首次接入、培训、新手熟悉工作流。 |
+| `java-microservice` | Java / Spring 微服务，默认使用 Maven 验证。 |
+| `frontend` | Vue / React 前端项目，默认使用 pnpm 验证。 |
+| `multi-repo` | 多仓库聚合目录，适合中台系统跨服务需求。 |
+
+## 初始化后需要补齐什么
+
+模板只负责生成配置骨架。使用前还需要确认：
+
+- `code_path` 指向真实代码目录。
+- `vars.demand_name` 是当前需求目录名。
+- `demand_file` 或 `todo_file` 对应文件已经存在。
+- `reference_files` 中的文档存在且与当前项目相关。
+- `verify_commands` 与团队实际构建命令一致。
+
+## 推荐实践
+
+存量中台系统优先使用 `openspec-auto` 或 `multi-repo`。
+
+小范围试点时使用 `openspec-manual`，确认流程稳定后再切换到 `openspec-auto`。
+
+如果需求本身已经拆成明确任务，不需要长期规格沉淀，可以使用 `todo-auto`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-engineer-workflow",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Super Engineer workflow skill and CLI for demand-driven AI delivery with OpenSpec bridge support.",
   "license": "MIT",
   "author": "Gary-Coding",
@@ -31,6 +31,7 @@
     "super-engineer-workflow/",
     "!super-engineer-workflow/scripts/__pycache__/",
     "!super-engineer-workflow/scripts/**/*.pyc",
+    "templates/",
     "docs/",
     "README.md",
     "LICENSE",
@@ -40,8 +41,9 @@
   ],
   "scripts": {
     "setup": "python3 scripts/se-setup.py",
-    "check": "python3 -m py_compile scripts/se-cli.py scripts/se-setup.py scripts/se-smoke-test.py super-engineer-workflow/scripts/*.py",
+    "check": "python3 -m py_compile scripts/se-cli.py scripts/se-setup.py scripts/se-smoke-test.py scripts/se-e2e-test.py super-engineer-workflow/scripts/*.py",
     "smoke": "python3 scripts/se-smoke-test.py",
+    "e2e": "python3 scripts/se-e2e-test.py",
     "pack:check": "npm pack --dry-run"
   },
   "keywords": [

package/scripts/se-cli.py

@@ -14,6 +14,18 @@ from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parents[1]
 SKILL_DIR = REPO_ROOT / "super-engineer-workflow"
 PACKAGE_JSON = REPO_ROOT / "package.json"
+TEMPLATE_DIR = REPO_ROOT / "templates" / "workspaces"
+
+
+WORKSPACE_TEMPLATES: dict[str, str] = {
+    "openspec-auto": "OpenSpec 规格先行 + 自动交付，推荐用于需求迭代主流程。",
+    "openspec-manual": "OpenSpec 规格先行 + 分阶段人工确认，推荐用于高风险变更。",
+    "todo-auto": "todo.md 直接驱动 + 自动交付，推荐用于小需求或已有明确任务清单。",
+    "todo-manual": "todo.md 直接驱动 + 分阶段人工确认，推荐用于首次接入或新手练习。",
+    "java-microservice": "Java / Spring 微服务模板，内置 Maven 验证命令示例。",
+    "frontend": "Vue / React 前端模板，内置 pnpm/npm 验证命令示例。",
+    "multi-repo": "多仓库聚合目录模板，适用于中台或跨服务需求。",
+}
 
 
 def main() -> None:
@@ -49,6 +61,19 @@ def main() -> None:
     migrate_parser.add_argument("--workspace", default=".", help="工作区目录，默认当前目录。")
     migrate_parser.add_argument("--dry-run", action="store_true", help="只展示计划，不写入文件。")
 
+    subparsers.add_parser("templates", help="列出内置 workspace.yml 模板。")
+
+    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="打印指定模板内容。")
+    template_show.add_argument("name", choices=sorted(WORKSPACE_TEMPLATES))
+    template_copy = template_subparsers.add_parser("copy", help="复制指定模板到工作区 workspace.yml。")
+    template_copy.add_argument("name", choices=sorted(WORKSPACE_TEMPLATES))
+    template_copy.add_argument("--workspace", default=".", help="工作区目录，默认当前目录。")
+    template_copy.add_argument("--demand-name", default="1-your-demand", help="写入 vars.demand_name 的需求目录名。")
+    template_copy.add_argument("--code-path", default="../code", help="写入 code_path 的代码目录。")
+    template_copy.add_argument("--force", action="store_true", help="允许覆盖已有 workspace.yml。")
+
     subparsers.add_parser("version", help="显示版本号。")
 
     args = parser.parse_args()
@@ -67,6 +92,24 @@ def main() -> None:
     if args.command == "migrate":
         exit_code = migrate(Path(args.workspace).expanduser().resolve(), dry_run=args.dry_run)
         raise SystemExit(exit_code)
+    if args.command == "templates":
+        list_templates()
+        return
+    if args.command == "template":
+        if args.template_action == "show":
+            show_template(args.name)
+            return
+        if args.template_action == "copy":
+            copy_template(
+                args.name,
+                Path(args.workspace).expanduser().resolve(),
+                demand_name=args.demand_name,
+                code_path=args.code_path,
+                force=args.force,
+            )
+            return
+        template_parser.print_help()
+        return
 
     parser.print_help()
 
@@ -119,6 +162,40 @@ def install_skill(target: Path, force: bool) -> None:
     print(f"✓ 已同步 skill: {target}")
 
 
+def template_path(name: str) -> Path:
+    path = TEMPLATE_DIR / f"{name}.yml"
+    if not path.exists():
+        raise SystemExit(f"模板不存在：{name}")
+    return path
+
+
+def list_templates() -> None:
+    print("内置 workspace.yml 模板：")
+    for name in sorted(WORKSPACE_TEMPLATES):
+        marker = "✓" if template_path(name).exists() else "!"
+        print(f"{marker} {name}: {WORKSPACE_TEMPLATES[name]}")
+
+
+def render_template(name: str, demand_name: str, code_path: str) -> str:
+    text = template_path(name).read_text(encoding="utf-8")
+    return text.replace("__DEMAND_NAME__", demand_name).replace("__CODE_PATH__", code_path)
+
+
+def show_template(name: str) -> None:
+    print(render_template(name, demand_name="1-your-demand", code_path="../code"))
+
+
+def copy_template(name: str, workspace: Path, demand_name: str, code_path: str, force: bool) -> None:
+    workspace.mkdir(parents=True, exist_ok=True)
+    target = workspace / "workspace.yml"
+    if target.exists() and not force:
+        raise SystemExit(f"workspace.yml 已存在：{target}。如需覆盖请加 --force。")
+    target.write_text(render_template(name, demand_name=demand_name, code_path=code_path), encoding="utf-8")
+    (workspace / "docs").mkdir(parents=True, exist_ok=True)
+    (workspace / "superengineer" / demand_name).mkdir(parents=True, exist_ok=True)
+    print(f"✓ 已写入模板：{target}")
+
+
 def doctor(workspace: Path, output_json: bool) -> int:
     checks: list[dict[str, str]] = []
     add_check(checks, "python", "ok", sys.version.split()[0])

package/scripts/se-e2e-test.py

@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+RUN_WORKFLOW = REPO_ROOT / "super-engineer-workflow" / "scripts" / "run-workflow.py"
+CLI = REPO_ROOT / "bin" / "super-engineer.js"
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory(prefix="se-e2e-") as tmp:
+        root = Path(tmp)
+        home = root / "home"
+        home.mkdir()
+        os.environ["HOME"] = str(home)
+        os.environ["USERPROFILE"] = str(home)
+        test_templates_cli(root)
+        test_openspec_state_and_bridge(root)
+        test_todo_auto_session_and_verify_compaction(root)
+    print("e2e_test=ok")
+
+
+def test_templates_cli(root: Path) -> None:
+    workspace = root / "template-workspace"
+    output = run(["node", str(CLI), "templates"])
+    if "openspec-auto" not in output or "todo-auto" not in output:
+        raise AssertionError("templates list did not include expected templates")
+
+    show_output = run(["node", str(CLI), "template", "show", "openspec-auto"])
+    if "workflow_source: openspec" not in show_output or "mode: auto" not in show_output:
+        raise AssertionError("template show returned unexpected content")
+
+    run(
+        [
+            "node",
+            str(CLI),
+            "template",
+            "copy",
+            "todo-auto",
+            "--workspace",
+            str(workspace),
+            "--demand-name",
+            "9-e2e-template",
+            "--code-path",
+            "../code",
+        ]
+    )
+    workspace_yml = read_text(workspace / "workspace.yml")
+    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")
+
+
+def test_openspec_state_and_bridge(root: Path) -> None:
+    workspace = root / "openspec-workspace"
+    code = root / "code" / "demo-service"
+    demand_dir = workspace / "superengineer" / "8-demo"
+    demand_dir.mkdir(parents=True)
+    code.mkdir(parents=True)
+    (code / "package.json").write_text(
+        json.dumps(
+            {
+                "name": "demo-service",
+                "version": "1.0.0",
+                "scripts": {"test": "node -e \"process.exit(0)\""},
+            },
+            ensure_ascii=False,
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+    (workspace / "docs").mkdir(parents=True)
+    (workspace / "openspec" / "changes").mkdir(parents=True)
+    (workspace / "openspec" / "specs").mkdir(parents=True)
+    (demand_dir / "需求.md").write_text(
+        "# 需求\n\n为 demo-service 增加状态查询接口。\n\n## 验收\n\n- 查询接口返回 ok。\n",
+        encoding="utf-8",
+    )
+    (workspace / "workspace.yml").write_text(
+        "\n".join(
+            [
+                "version: 1",
+                "mode: auto",
+                "workflow_source: openspec",
+                "vars:",
+                "  demand_name: 8-demo",
+                "demand_file: superengineer/${demand_name}/需求.md",
+                "todo_file: superengineer/${demand_name}/todo.md",
+                "reference_files: []",
+                "code_path: ../code/demo-service",
+                "output_dir: superengineer/${demand_name}/output",
+                "openspec:",
+                "  changes_dir: openspec/changes",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    invalid = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:bridge",
+        ],
+        check=False,
+    )
+    if invalid.returncode == 0 or "请先执行 /se:propose" not in invalid.output:
+        raise AssertionError("/se:bridge before /se:propose should be rejected")
+
+    env_without_openspec = os.environ.copy()
+    env_without_openspec["PATH"] = ""
+    propose = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:propose demo-change",
+        ],
+        env=env_without_openspec,
+    )
+    if "final_reply_must=代码未修改。下一步只能执行 /se:bridge。" not in propose:
+        raise AssertionError("/se:propose did not print strict next-step constraint")
+
+    change_dir = workspace / "openspec" / "changes" / "demo-change"
+    (change_dir / "specs").mkdir(parents=True, exist_ok=True)
+    (change_dir / "proposal.md").write_text("# Proposal\n\n增加状态查询接口。\n", encoding="utf-8")
+    (change_dir / "design.md").write_text("# Design\n\n目标服务 demo-service。\n", encoding="utf-8")
+    (change_dir / "tasks.md").write_text(
+        "# Tasks\n\n"
+        "- [ ] 修改 demo-service controller 增加状态查询接口\n"
+        "- [ ] 补充验证，确认接口返回 ok\n",
+        encoding="utf-8",
+    )
+
+    bridge = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:bridge",
+        ]
+    )
+    if "bridge_generated=true" not in bridge:
+        raise AssertionError("/se:bridge did not generate todo.md")
+    todo = read_text(workspace / "superengineer" / "8-demo" / "todo.md")
+    if "demo-change" not in todo or "demo-service" not in todo:
+        raise AssertionError("bridged todo.md missing expected OpenSpec context")
+
+    first_plan = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:plan",
+        ]
+    )
+    if "session_action=created" not in first_plan:
+        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"]
+
+    second_plan = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:plan",
+        ]
+    )
+    second_session = read_json(workspace / ".super-engineer" / "current-session.json")
+    if "session_action=reused" not in second_plan or second_session["session_id"] != first_session_id:
+        raise AssertionError("second /se:plan should reuse the existing planning session")
+    if len(list((workspace / ".super-engineer" / "sessions").iterdir())) != 1:
+        raise AssertionError("repeated /se:plan created an extra session")
+
+    apply_output = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:apply",
+        ]
+    )
+    if "apply_phase=implementing" not in apply_output:
+        raise AssertionError("/se:apply should enter implementing after planned session")
+    blocked_plan = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:plan",
+        ],
+        check=False,
+    )
+    final_session = read_json(workspace / ".super-engineer" / "current-session.json")
+    if blocked_plan.returncode == 0 or "不能重新执行 /se:plan" not in blocked_plan.output:
+        raise AssertionError("/se:plan during active delivery should be rejected")
+    if final_session["session_id"] != first_session_id or len(list((workspace / ".super-engineer" / "sessions").iterdir())) != 1:
+        raise AssertionError("rejected /se:plan should not create or switch sessions")
+
+
+def test_todo_auto_session_and_verify_compaction(root: Path) -> None:
+    workspace = root / "todo-workspace"
+    code = root / "todo-code" / "demo-service"
+    demand_dir = workspace / "superengineer" / "9-demo"
+    demand_dir.mkdir(parents=True)
+    code.mkdir(parents=True)
+    (workspace / "docs").mkdir(parents=True)
+    (code / "verify.py").write_text(
+        "print('A' * 13000)\n"
+        "import sys\n"
+        "print('B' * 13000, file=sys.stderr)\n",
+        encoding="utf-8",
+    )
+    (code / "package.json").write_text(
+        json.dumps(
+            {
+                "name": "demo-service",
+                "version": "1.0.0",
+                "scripts": {"test": "node -e \"process.exit(0)\""},
+            },
+            ensure_ascii=False,
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+    verify_command = f'"{sys.executable}" verify.py'
+    (workspace / "workspace.yml").write_text(
+        "\n".join(
+            [
+                "version: 1",
+                "mode: auto",
+                "workflow_source: todo",
+                "vars:",
+                "  demand_name: 9-demo",
+                "todo_file: superengineer/${demand_name}/todo.md",
+                "reference_files: []",
+                "code_path: ../todo-code/demo-service",
+                "output_dir: superengineer/${demand_name}/output",
+                "verify_commands:",
+                f"  default: {verify_command}",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+    (demand_dir / "todo.md").write_text(
+        "# 限制条件\n"
+        "- 修改的服务是 demo-service\n\n"
+        "# 待办事项\n\n"
+        "- [ ] 增加状态查询接口\n"
+        "1. 返回 ok\n\n"
+        "## 验收补充\n"
+        "- [ ] 执行验证命令\n",
+        encoding="utf-8",
+    )
+
+    apply_output = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:apply",
+        ]
+    )
+    if "apply_phase=implementing" not in apply_output:
+        raise AssertionError("/se:apply did not enter implementing phase")
+
+    run([sys.executable, str(RUN_WORKFLOW), "finish-implement", "--workspace", str(workspace)])
+    session = read_json(workspace / ".super-engineer" / "current-session.json")
+    data_dir = Path(session["data_dir"])
+    plan_summary = read_json(data_dir / "plan-summary.json")
+    verify = read_json(data_dir / "verify.json")
+    status = read_json(data_dir / "status.json")
+    notification = read_json(data_dir / "notification.json")
+
+    if not plan_summary.get("target_codebases"):
+        raise AssertionError("plan-summary.json missing target_codebases")
+    if verify.get("result") != "通过":
+        raise AssertionError("verify did not pass")
+    stdout = verify["sections"][0]["stdout"]
+    stderr = verify["sections"][0]["stderr"]
+    if "已省略" not in stdout or "已省略" not in stderr:
+        raise AssertionError("verify stdout/stderr were not compacted")
+    if len(stdout) > 12200 or len(stderr) > 12200:
+        raise AssertionError("verify stdout/stderr compaction exceeded expected size")
+    if status.get("phase") != "done":
+        raise AssertionError("todo auto session did not finish with done status")
+    if notification.get("status") != "skipped":
+        raise AssertionError("notification should be marked skipped when no provider is configured")
+
+
+def run(command: list[str], check: bool = True, env: dict[str, str] | None = None):
+    result = subprocess.run(
+        command,
+        cwd=REPO_ROOT,
+        env=env,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        check=False,
+    )
+    if check:
+        if result.returncode != 0:
+            print(result.stdout)
+            raise SystemExit(result.returncode)
+        return result.stdout
+    return CommandResult(result.returncode, result.stdout)
+
+
+class CommandResult:
+    def __init__(self, returncode: int, output: str) -> None:
+        self.returncode = returncode
+        self.output = output
+
+
+def read_text(path: Path) -> str:
+    if not path.is_file():
+        raise AssertionError(f"missing file: {path}")
+    return path.read_text(encoding="utf-8")
+
+
+def read_json(path: Path) -> dict:
+    if not path.is_file():
+        raise AssertionError(f"missing file: {path}")
+    with path.open(encoding="utf-8") as handle:
+        data = json.load(handle)
+    if not isinstance(data, dict):
+        raise AssertionError(f"json root is not object: {path}")
+    return data
+
+
+if __name__ == "__main__":
+    if shutil.which("node") is None:
+        raise SystemExit("node is required")
+    main()

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

@@ -319,6 +319,8 @@ AI 在 `/se:bridge` 完成后必须停止，只能提示用户审核 `todo.md`
 内部动作：
 
 - 执行 `python3 scripts/run-workflow.py plan`
+- 如果当前 session 已有标准 `plan.json` 且仍停留在计划确认阶段，脚本必须复用当前 session
+- 如果当前 session 已进入实现、自查、审查或验证阶段，脚本必须拒绝重复 `/se:plan`，不能创建第二个 session
 
 完成后汇报：
 
@@ -350,7 +352,8 @@ AI 在 `/se:bridge` 完成后必须停止，只能提示用户审核 `todo.md`
 
 内部动作：
 
-- 如果没有当前 session，先执行 `python3 scripts/run-workflow.py plan`
+- 如果没有当前 session、当前 session 失效，或当前 session 缺少标准 `plan.json`，先执行 `python3 scripts/run-workflow.py plan`
+- 如果当前 session 已有标准 `plan.json` 且未完成，必须复用当前 session
 - 执行 `python3 scripts/run-workflow.py start-implement`
 - 按当前 `plan.json` 实现代码
 - 执行 `python3 scripts/run-workflow.py finish-implement`
@@ -363,6 +366,7 @@ AI 在 `/se:bridge` 完成后必须停止，只能提示用户审核 `todo.md`
 - `todo` 模式下也必须通过当前 session 的 `status.json`、`todo-state.json` 和标准产物来源校验，不能复用旧需求 session
 - `todo` 模式的状态不能写入 OpenSpec 专用 `se-state.json`
 - `todo` 模式下如果 `current-session.json` 指向旧 `output_dir`，`/se:apply` 必须重新创建标准 session
+- AI 不得在 `/se:apply` 链路中额外手工执行第二次 `/se:plan`；脚本检测到活跃交付 session 时必须拒绝重复计划
 - AI 只能在 `start-implement` 和 `finish-implement` 之间修改业务代码
 - AI 不得直接写 `.super-engineer` 下的状态 JSON
 - AI 不得直接写 output 下的标准 Markdown 报告

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

@@ -161,7 +161,9 @@ OpenSpec change 名称必须通过 `/se:propose <change-name>` 显式指定。
 - `/se:verify` 通过后状态为 `verified`，只允许 `/se:archive-check`
 - `/se:archive-check` 通过后状态为 `archive_ready`，只允许 `/se:archive`
 - 所有阶段推进必须先通过 `run-workflow.py validate-state <command>` 等价校验，不能只依赖 AI 回复
-- 每次执行 `plan` 都必须创建新的 `session_id`
+- `plan` 只有在没有有效计划会话、当前会话已完成/归档/阻塞，或当前会话失效时才创建新的 `session_id`
+- 如果当前 session 已有 `plan.json` 且仍停留在计划确认阶段，重复执行 `plan` 必须复用当前 session，不能创建新 session
+- 如果当前 session 已进入 `implement`、`self_check`、`review`、`verify` 等交付阶段，重复执行 `plan` 必须被脚本拒绝
 - 新会话不能覆盖历史会话目录
 - `current-session.json` 只指向当前正在推进的会话
 - 后续 `start-implement`、`finish-implement`、`review`、`verify`、`status` 都基于当前会话执行

package/super-engineer-workflow/scripts/common.py

@@ -665,6 +665,47 @@ def current_session_meta(config: dict[str, Any]) -> dict[str, Any]:
     return normalized
 
 
+def current_session_status(config: dict[str, Any], session_meta: dict[str, Any] | None = None) -> dict[str, Any]:
+    meta = session_meta or current_session_meta(config)
+    status = read_json(data_artifact_path(config, "status.json", meta), {})
+    return status if isinstance(status, dict) else {}
+
+
+def active_session_for_plan(config: dict[str, Any]) -> dict[str, Any] | None:
+    if current_session_is_stale(config):
+        return None
+    try:
+        session_meta = current_session_meta(config)
+    except FileNotFoundError:
+        return None
+    if not data_artifact_path(config, "plan.json", session_meta).exists():
+        return None
+    status = current_session_status(config, session_meta)
+    status_phase = str(status.get("phase", "") or "").strip()
+    if status_phase in ("done", "archived", "blocked"):
+        return None
+    return {
+        "session": session_meta,
+        "status": status,
+        "phase": status_phase or "plan",
+    }
+
+
+def ensure_plan_can_run(config: dict[str, Any]) -> dict[str, Any] | None:
+    active = active_session_for_plan(config)
+    if not active:
+        return None
+    phase = str(active.get("phase", "")).strip()
+    session = active.get("session", {})
+    if phase in ("plan", "wait_confirm_plan"):
+        return active
+    raise RuntimeError(
+        f"当前已有活跃 session 正在交付中，禁止重新执行 /se:plan："
+        f"session_id={session.get('session_id', '')}, phase={phase}。"
+        "请继续当前 /se:apply 链路，不要创建新的 plan/session。"
+    )
+
+
 def data_artifact_path(config: dict[str, Any], name: str, session_meta: dict[str, Any] | None = None) -> Path:
     meta = _normalize_session_meta(config, session_meta or current_session_meta(config))
     return Path(meta["data_dir"]) / name
@@ -1016,6 +1057,8 @@ def validate_se_state(config: dict[str, Any], run_command: str) -> dict[str, Any
         elif run_command in ("plan", "apply"):
             if not todo_path(config).exists():
                 errors.append("缺少 todo_file，请先执行 /se:init 或补充 todo.md。")
+            if run_command == "plan" and phase in ("implementing", "self_checked", "reviewed"):
+                errors.append("当前已有活跃 session 正在交付中，不能重新执行 /se:plan。请继续当前 /se:apply、/se:review 或 /se:verify。")
         elif run_command == "start-implement":
             if phase not in ("planned", "implementing", "blocked"):
                 errors.append("当前状态不允许进入实现，请先执行 /se:plan。")
@@ -1065,7 +1108,16 @@ def validate_se_state(config: dict[str, Any], run_command: str) -> dict[str, Any
         for key in ("proposal", "design", "tasks"):
             if not _se_state_artifact_exists(str(artifacts.get(key, ""))):
                 errors.append(f"缺少 OpenSpec 产物：{key}")
-    elif se_command in ("/se:plan", "/se:apply"):
+    elif se_command == "/se:plan":
+        if phase not in ("bridged", "planned", "blocked") and se_command not in allowed_next:
+            errors.append("当前状态不允许重新计划，请先完成 /se:bridge，或继续当前活跃交付会话。")
+        if phase in ("implementing", "self_checked", "reviewed", "verified"):
+            errors.append("当前已有活跃 session 正在交付中，不能重新执行 /se:plan。请继续当前 /se:apply、/se:review 或 /se:verify。")
+        if phase == "proposed":
+            errors.append("/se:propose 后不能直接进入交付，必须先执行 /se:bridge。")
+        if not _se_state_artifact_exists(str(artifacts.get("todo", ""))):
+            errors.append("缺少桥接 todo.md，请先执行 /se:bridge。")
+    elif se_command == "/se:apply":
         if phase not in ("bridged", "planned", "implementing", "reviewed", "blocked") and se_command not in allowed_next:
             errors.append("当前状态不允许进入交付，请先完成 /se:bridge 并人工审核 todo.md。")
         if phase == "proposed":

package/super-engineer-workflow/scripts/run-workflow.py

@@ -11,6 +11,7 @@ from common import (
     current_session_is_stale,
     current_session_meta,
     data_artifact_path,
+    ensure_plan_can_run,
     ensure_status,
     load_workspace_config,
     now_iso,
@@ -287,9 +288,22 @@ def command_archive_openspec(workspace: Path | None) -> None:
 def command_plan(workspace: Path | None) -> None:
     config = load_workspace_config(workspace)
     require_se_state(config, "plan")
+    try:
+        active = ensure_plan_can_run(config)
+    except RuntimeError as error:
+        raise SystemExit(str(error))
+    if active:
+        session = active.get("session", {})
+        print("session_action=reused")
+        print(f"session_id={session.get('session_id', '')}")
+        print(f"phase={active.get('phase', '')}")
+        print("next_action=当前计划已存在，继续执行 /se:apply。")
+        return
     command_init(workspace)
     config = load_workspace_config(workspace)
-    create_session(config)
+    session_meta = create_session(config)
+    print("session_action=created")
+    print(f"session_id={session_meta.get('session_id', '')}")
     command_discover(workspace)
     args = ["--workspace", str(workspace)] if workspace else []
     run_python("generate-smart-plan.py", args)

package/templates/workspaces/frontend.yml

@@ -0,0 +1,18 @@
+version: 1
+mode: auto
+workflow_source: openspec
+vars:
+  demand_name: __DEMAND_NAME__
+demand_file: superengineer/${demand_name}/需求.md
+todo_file: superengineer/${demand_name}/todo.md
+reference_files:
+  - docs/需求分析与实现指南.md
+  - docs/前端规范.md
+code_path: __CODE_PATH__
+output_dir: superengineer/${demand_name}/output
+openspec:
+  changes_dir: openspec/changes
+verify_commands:
+  default: pnpm test && pnpm build
+
+# 如果团队使用 npm，可把 verify_commands.default 改成 npm test && npm run build。

package/templates/workspaces/java-microservice.yml

@@ -0,0 +1,19 @@
+version: 1
+mode: auto
+workflow_source: openspec
+vars:
+  demand_name: __DEMAND_NAME__
+demand_file: superengineer/${demand_name}/需求.md
+todo_file: superengineer/${demand_name}/todo.md
+reference_files:
+  - docs/需求分析与实现指南.md
+  - docs/开发规范.md
+  - docs/接口规范.md
+code_path: __CODE_PATH__
+output_dir: superengineer/${demand_name}/output
+openspec:
+  changes_dir: openspec/changes
+verify_commands:
+  default: mvn -q test
+
+# Spring Boot 多模块项目可把 code_path 指向具体服务目录，或使用 multi-repo 模板。

package/templates/workspaces/multi-repo.yml

@@ -0,0 +1,21 @@
+version: 1
+mode: auto
+workflow_source: openspec
+vars:
+  demand_name: __DEMAND_NAME__
+demand_file: superengineer/${demand_name}/需求.md
+todo_file: superengineer/${demand_name}/todo.md
+reference_files:
+  - docs/需求分析与实现指南.md
+  - docs/开发规范.md
+  - docs/系统架构.md
+code_path: __CODE_PATH__
+output_dir: superengineer/${demand_name}/output
+openspec:
+  changes_dir: openspec/changes
+verify_commands:
+  frontend-app: pnpm test && pnpm build
+  user-service: mvn -q test
+  pricing-service: go test ./...
+
+# code_path 指向多个仓库的上层目录时，工作流会结合 todo 与代码结构推断目标仓库。

package/templates/workspaces/openspec-auto.yml

@@ -0,0 +1,18 @@
+version: 1
+mode: auto
+workflow_source: openspec
+vars:
+  demand_name: __DEMAND_NAME__
+demand_file: superengineer/${demand_name}/需求.md
+todo_file: superengineer/${demand_name}/todo.md
+reference_files:
+  - docs/需求分析与实现指南.md
+  - docs/开发规范.md
+code_path: __CODE_PATH__
+output_dir: superengineer/${demand_name}/output
+openspec:
+  changes_dir: openspec/changes
+
+# 可选：自动识别不准确时覆盖验证命令
+# verify_commands:
+#   default: mvn -q test

package/templates/workspaces/openspec-manual.yml

@@ -0,0 +1,16 @@
+version: 1
+mode: manual
+workflow_source: openspec
+vars:
+  demand_name: __DEMAND_NAME__
+demand_file: superengineer/${demand_name}/需求.md
+todo_file: superengineer/${demand_name}/todo.md
+reference_files:
+  - docs/需求分析与实现指南.md
+  - docs/开发规范.md
+code_path: __CODE_PATH__
+output_dir: superengineer/${demand_name}/output
+openspec:
+  changes_dir: openspec/changes
+
+# manual 模式会在 plan、implement、review 等关键阶段停下来等待确认。

package/templates/workspaces/todo-auto.yml

@@ -0,0 +1,13 @@
+version: 1
+mode: auto
+workflow_source: todo
+vars:
+  demand_name: __DEMAND_NAME__
+todo_file: superengineer/${demand_name}/todo.md
+reference_files:
+  - docs/需求分析与实现指南.md
+  - docs/开发规范.md
+code_path: __CODE_PATH__
+output_dir: superengineer/${demand_name}/output
+
+# todo 模式不使用 OpenSpec change，适合任务已经明确的小需求。

package/templates/workspaces/todo-manual.yml

@@ -0,0 +1,13 @@
+version: 1
+mode: manual
+workflow_source: todo
+vars:
+  demand_name: __DEMAND_NAME__
+todo_file: superengineer/${demand_name}/todo.md
+reference_files:
+  - docs/需求分析与实现指南.md
+  - docs/开发规范.md
+code_path: __CODE_PATH__
+output_dir: superengineer/${demand_name}/output
+
+# manual 模式适合首次接入、复杂需求或需要逐步确认的团队。