cowork-flow 2.4.1 → 2.4.2

package/CHANGELOG.md

@@ -6,6 +6,16 @@
 
 ### Changed
 
+## [2.4.2] - 2026-10-23
+
+### Added
+
+- **计划骨架生成与定稿门禁**：新增 `./.cowork-flow/run plan new --title ... --slug ...`，从已安装的本地化 `.cowork-flow/templates/plan-template.md` 生成计划骨架并替换标题占位符，默认拒绝覆盖已有计划；新增 `plan finalize [task-dir]`，校验计划模板形状、目标、AC、章节内容、任务简报字段、验证命令、anchor 的 AC/目标/规范核对和 `implement.jsonl`，通过后写入 `task.json.meta.planReady` 的 plan/anchor 摘要。模板中的角括号占位内容以及示例路径/符号（如 `path/a.py`、`function_name`）不算已填充，必须替换后才能定稿。任务创建会把计划 AC 自动填入 anchor 的验收标准。新 strict 非 Tiny 任务默认带 `planReadyRequired`，start 要求快照存在且摘要未变；人验收后修改计划或 anchor 会阻断 start，需重新 finalize 并重新验收。Tiny、legacy 与未标记旧任务保持原行为。
+
+### Changed
+
+- **计划流程改为“生成骨架 → 填充 → finalize → 人验收 → start”**：`task-planning` 技能、`plan-binding.md` 契约与 `plan finalize` 检查共同约束计划完整性；start 保留结构 backstop，并把新任务的完整性主检查前移到 finalize。契约摘要同步更新，未新增第二套计划模板。
+
 ## [2.4.1] - 2026-10-23
 
 ### Added
@@ -435,7 +445,8 @@
 
 此版本未保留本地条目正文，详情见 [GitHub Release](https://github.com/fishlikewater/cowork-flow/releases/tag/v0.0.47)。
 
-[Unreleased]: https://github.com/fishlikewater/cowork-flow/compare/v2.4.1...HEAD
+[Unreleased]: https://github.com/fishlikewater/cowork-flow/compare/v2.4.2...HEAD
+[2.4.2]: https://github.com/fishlikewater/cowork-flow/compare/v2.4.1...v2.4.2
 [2.4.1]: https://github.com/fishlikewater/cowork-flow/compare/v2.4.0...v2.4.1
 [2.4.0]: https://github.com/fishlikewater/cowork-flow/compare/v2.3.0...v2.4.0
 [2.3.0]: https://github.com/fishlikewater/cowork-flow/compare/v2.2.0...v2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "keywords": [
     "ai-agent",

package/presets/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Claude Code。",
   "displayName": "Cowork Flow",
   "author": {

package/presets/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Codex。",
   "author": {
     "name": "fishlikewater",

package/presets/kimi-code/.kimi-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Kimi Code。",
   "author": {
     "name": "fishlikewater",

package/presets/qoder/.qoder-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Qoder。",
   "displayName": "Cowork Flow",
   "author": {

package/presets/zcode/.zcode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 ZCode。",
   "author": {
     "name": "fishlikewater",

package/template/.cowork-flow/.version

@@ -1 +1 @@
-2.4.1
+2.4.2

package/template/.cowork-flow/scripts/adapters/cli/plan.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Plan skeleton generation and readiness finalization CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from adapters.cli.execution_context_args import (
+    build_internal_execution_context_parser,
+    execution_context_from_namespace,
+)
+from adapters.cli.task_support import (
+    Colors,
+    colored,
+    resolve_task_dir,
+    slugify,
+)
+from infra.paths import FILE_TASK_JSON, get_repo_root
+from runtime.session_state import (
+    PROVENANCE_PROCESS_FALLBACK,
+    get_active_task,
+)
+from services.plan_readiness import PlanReadinessError, PlanReadinessService
+from services.plan_scaffold import PlanScaffoldError, PlanScaffoldService
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Generate a plan skeleton or finalize planning artifacts",
+        parents=[build_internal_execution_context_parser()],
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    new_parser = subparsers.add_parser(
+        "new",
+        help="Create a plan skeleton from the installed localized template",
+    )
+    new_parser.add_argument("--title", required=True, help="Plan title")
+    new_parser.add_argument(
+        "--slug",
+        help="ASCII plan slug; defaults to the title when it slugifies",
+    )
+    new_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing plan file",
+    )
+    new_parser.add_argument(
+        "--date",
+        help="Plan date prefix in YYYY-MM-DD form (default: today)",
+    )
+
+    finalize_parser = subparsers.add_parser(
+        "finalize",
+        help="Validate planning artifacts and record the plan-ready snapshot",
+    )
+    finalize_parser.add_argument(
+        "dir",
+        nargs="?",
+        help="Task directory or name; defaults to the active task",
+    )
+    finalize_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the plan-ready snapshot as JSON",
+    )
+    return parser
+
+
+def _resolve_task(args: argparse.Namespace, repo_root: Path) -> Path | None:
+    target = getattr(args, "dir", None)
+    if target:
+        task_dir = resolve_task_dir(target, repo_root)
+    else:
+        active = get_active_task(repo_root)
+        if not active.context_key:
+            print(
+                colored(
+                    "Error: Missing session context. Set "
+                    "COWORK_FLOW_CONTEXT_ID or pass a task dir.",
+                    Colors.RED,
+                ),
+                file=sys.stderr,
+            )
+            return None
+        if active.task_path and active.provenance == PROVENANCE_PROCESS_FALLBACK:
+            print(
+                colored(
+                    "Error: Session binding is process-fallback (shared); "
+                    "set COWORK_FLOW_CONTEXT_ID to the session value shown "
+                    "in the workflow-state header, or pass a task dir "
+                    "explicitly.",
+                    Colors.RED,
+                ),
+                file=sys.stderr,
+            )
+            return None
+        if not active.task_path:
+            print(
+                colored(
+                    "Error: No active task set for this session",
+                    Colors.RED,
+                ),
+                file=sys.stderr,
+            )
+            return None
+        task_dir = repo_root / active.task_path
+
+    if not task_dir.is_dir() or not (task_dir / FILE_TASK_JSON).is_file():
+        print(
+            colored(
+                f"Error: Task not found or task.json missing: {task_dir}",
+                Colors.RED,
+            ),
+            file=sys.stderr,
+        )
+        return None
+    return task_dir
+
+
+def _cmd_new(args: argparse.Namespace, repo_root: Path) -> int:
+    slug = args.slug or slugify(args.title)
+    if not slug:
+        print(
+            colored(
+                "Error: could not generate an ASCII slug from the title; "
+                "pass --slug <ascii-slug>",
+                Colors.RED,
+            ),
+            file=sys.stderr,
+        )
+        return 1
+    try:
+        plan_path = PlanScaffoldService(repo_root).create(
+            args.title,
+            slug,
+            force=bool(args.force),
+            date_prefix=args.date,
+        )
+    except PlanScaffoldError as error:
+        print(
+            colored(
+                f"Error: Failed to create plan skeleton [{error.code}]: "
+                f"{error.detail}",
+                Colors.RED,
+            ),
+            file=sys.stderr,
+        )
+        return 1
+    try:
+        display = plan_path.resolve().relative_to(repo_root.resolve()).as_posix()
+    except ValueError:
+        display = str(plan_path)
+    print(display)
+    return 0
+
+
+def _cmd_finalize(args: argparse.Namespace, repo_root: Path) -> int:
+    task_dir = _resolve_task(args, repo_root)
+    if task_dir is None:
+        return 1
+    try:
+        snapshot = PlanReadinessService(repo_root).finalize(task_dir)
+    except PlanReadinessError as error:
+        print(
+            colored("Error: Plan is not ready for review", Colors.RED),
+            file=sys.stderr,
+        )
+        for blocker in error.blockers:
+            print(f"  - {blocker}", file=sys.stderr)
+        print(
+            "Hint: fill the planning artifacts, then rerun "
+            "`./.cowork-flow/run plan finalize <task-dir>`.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if getattr(args, "json", False):
+        print(json.dumps(snapshot, ensure_ascii=False, indent=2))
+    else:
+        print(colored("Plan is ready for human review.", Colors.GREEN))
+        print(f"  planDigest: {snapshot['planDigest']}")
+        print(f"  anchorDigest: {snapshot['anchorDigest']}")
+        print(f"  readyAt: {snapshot['readyAt']}")
+        print(
+            "  Next: review the plan and anchor, then start the task. "
+            "Start will reject any later edit to either file."
+        )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    execution_context = execution_context_from_namespace(args)
+    if not execution_context.is_default:
+        print(
+            colored(
+                "Error: plan commands must run in the main session; "
+                "delegated contexts cannot finalize a task.",
+                Colors.RED,
+            ),
+            file=sys.stderr,
+        )
+        return 2
+
+    repo_root = get_repo_root()
+    if args.command == "new":
+        return _cmd_new(args, repo_root)
+    if args.command == "finalize":
+        return _cmd_finalize(args, repo_root)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/.cowork-flow/scripts/run.py

@@ -23,6 +23,7 @@ configure_cli_encoding()
 COMMAND_SCRIPTS = {
     "resume": "adapters/cli/resume.py",
     "task": "adapters/cli/task.py",
+    "plan": "adapters/cli/plan.py",
     "get-context": "adapters/cli/get_context.py",
     "get_context": "adapters/cli/get_context.py",
     "get-developer": "adapters/cli/get_developer.py",
@@ -35,7 +36,7 @@ COMMAND_SCRIPTS = {
 }
 RESERVED_COMMAND_NAMES = (*COMMAND_SCRIPTS, "python", "help", "-h", "--help")
 
-CONTEXT_AWARE_COMMANDS = {"resume", "task", "subagent"}
+CONTEXT_AWARE_COMMANDS = {"resume", "task", "plan", "subagent"}
 
 
 def print_usage() -> None:
@@ -49,6 +50,7 @@ def print_usage() -> None:
 Common commands:
   resume
   task
+  plan
   state
   get-context
   get-developer