cowork-flow 0.0.5 → 0.0.7

package/README.md

@@ -219,4 +219,30 @@ cowork-flow sync . --dry-run
 
 ## 发布流程
 
-CI 会运行 Node CLI 测试、npm pack 内容检查和现有 Python 模板测试。发布到 npm 通过 GitHub Actions 的 `Publish npm Package` workflow 完成，需要在仓库 secrets 中配置 `NPM_TOKEN`。
+发布前先确认本地或 CI 具备 npm 发布凭据，例如已执行 `npm login`，或在 CI 中配置了 `NPM_TOKEN`。
+
+推荐使用 release 脚本发布：
+
+```bash
+npm run release
+```
+
+默认会升级 patch 版本，执行顺序是：
+
+1. `npm run test:all`
+2. `npm version patch --no-git-tag-version`
+3. 将 `package.json` 中的新版本同步写入 `template/.cowork-flow/.version`
+4. `git add package.json package-lock.json template/.cowork-flow/.version`
+5. `git commit -m "chore(release): <version>"`
+6. `git tag v<version>`
+7. `npm publish`
+
+需要发布其他版本类型时，把 npm 支持的版本类型传给脚本：
+
+```bash
+npm run release -- minor
+npm run release -- major
+npm run release -- prerelease
+```
+
+脚本会在任一步骤失败时停止后续发布动作。CI 仍会运行 Node CLI 测试、npm pack 内容检查和现有 Python 模板测试；GitHub Actions 的 `Publish npm Package` workflow 仍需要在仓库 secrets 中配置 `NPM_TOKEN`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
     "test": "node --test",
     "test:template": "node scripts/run-template-tests.js",
     "pack:check": "node scripts/pack-check.js",
-    "test:all": "npm test && npm run test:template && npm run pack:check"
+    "test:all": "npm test && npm run test:template && npm run pack:check",
+    "release": "sh scripts/release.sh"
   },
   "engines": {
     "node": ">=20"

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.5
+0.0.7

package/template/.cowork-flow/agent-team/agents.yaml

@@ -5,7 +5,7 @@ default_adapter: codex
 
 agents:
   implementer:
-    codex_type: worker
+    agent_type: worker
     capabilities:
       - implementation
       - test-writing
@@ -19,9 +19,51 @@ agents:
       - "test/**"
     risk_limits:
       max_parallel_write_conflicts: 0
+    prompt: |
+      Implement the smallest change that satisfies the approved plan and tests.
+      Write or update focused regression tests first, keep edits scoped, and report exact verification commands.
+
+  tester:
+    agent_type: worker
+    capabilities:
+      - test-writing
+      - verification
+    preferred_task_types:
+      - test
+      - verification
+    file_patterns:
+      - "tests/**"
+      - "test/**"
+      - "src/**"
+      - "template/**"
+    risk_limits:
+      max_parallel_write_conflicts: 0
+    prompt: |
+      Design tests that fail for the broken behavior and pass for the intended behavior.
+      Prefer clear behavior assertions over implementation details, and include the command that proves the result.
+
+  debugger:
+    agent_type: worker
+    capabilities:
+      - debugging
+      - implementation
+      - verification
+    preferred_task_types:
+      - bugfix
+      - code
+    file_patterns:
+      - "src/**"
+      - "template/**"
+      - "tests/**"
+      - "test/**"
+    risk_limits:
+      max_parallel_write_conflicts: 0
+    prompt: |
+      Find the root cause before changing code. Reproduce the failure, compare with nearby working patterns,
+      then make the smallest fix and verify the original symptom.
 
   spec-reviewer:
-    codex_type: default
+    agent_type: default
     capabilities:
       - spec-review
       - acceptance-check
@@ -35,12 +77,16 @@ agents:
       - "template/**"
     risk_limits:
       max_parallel_write_conflicts: 0
+    prompt: |
+      Review the proposal, spec, plan, and task PRD for contradictions, missing acceptance criteria,
+      unclear scope, and behavior that is not covered by verification.
 
   quality-reviewer:
-    codex_type: default
+    agent_type: default
     capabilities:
       - code-quality-review
       - test-review
+      - verification
     preferred_task_types:
       - review
       - verification
@@ -51,14 +97,18 @@ agents:
       - "test/**"
     risk_limits:
       max_parallel_write_conflicts: 0
+    prompt: |
+      Review the diff for correctness, maintainability, focused scope, and meaningful tests.
+      Check that verification evidence matches the behavior being claimed.
 
   docs-agent:
-    codex_type: worker
+    agent_type: worker
     capabilities:
       - documentation
       - workflow-writing
     preferred_task_types:
       - docs
+      - documentation
     file_patterns:
       - "README.md"
       - "AGENTS.md"
@@ -66,3 +116,27 @@ agents:
       - ".agent/skills/**"
     risk_limits:
       max_parallel_write_conflicts: 0
+    prompt: |
+      Write concise project documentation that reflects actual commands, files, and workflow behavior.
+      Avoid aspirational text that is not backed by the implementation.
+
+  release-reviewer:
+    agent_type: default
+    capabilities:
+      - release-review
+      - acceptance-check
+      - verification
+    preferred_task_types:
+      - release
+      - review
+    file_patterns:
+      - "package.json"
+      - "package-lock.json"
+      - "scripts/**"
+      - "README.md"
+      - ".cowork-flow/changes/**"
+    risk_limits:
+      max_parallel_write_conflicts: 0
+    prompt: |
+      Review release-facing changes for versioning, packaging, documentation, and command safety.
+      Confirm that generated artifacts and publish steps are intentional.

package/template/.cowork-flow/run

@@ -3,30 +3,8 @@ set -u
 
 MIN_PYTHON_LABEL="Python 3.8+"
 VERSION_CHECK='import sys; raise SystemExit(0 if sys.version_info >= (3, 8) else 1)'
-
 WORKFLOW_DIR=$(CDPATH= cd "$(dirname "$0")" && pwd) || exit 1
-SCRIPTS_DIR="$WORKFLOW_DIR/scripts"
-
-print_usage() {
-  cat <<'EOF'
-用法：
-  ./.cowork-flow/run <command> [args...]
-  ./.cowork-flow/run python [python-args...]
-
-常用 command：
-  resume
-  task
-  change
-  get-context
-  get-developer
-  init-developer
-  add-session
-  agent-team
-
-解释器选择顺序：
-  COWORK_FLOW_PYTHON -> PYTHON -> python3 -> python -> py -3
-EOF
-}
+RUNNER_SCRIPT="$WORKFLOW_DIR/scripts/run.py"
 
 candidate_is_valid() {
   candidate_cmd=$1
@@ -51,8 +29,8 @@ select_explicit_python() {
     return 0
   fi
 
-  echo "错误：$env_name 指向的解释器不可用或版本低于 ${MIN_PYTHON_LABEL}：$env_value" >&2
-  echo "请设置 $env_name 为可执行的 Python 3.8+ 解释器路径。" >&2
+  echo "Error: $env_name does not point to a usable ${MIN_PYTHON_LABEL} interpreter: $env_value" >&2
+  echo "Set $env_name to an executable Python 3.8+ interpreter path." >&2
   exit 127
 }
 
@@ -86,81 +64,16 @@ select_python() {
     return 0
   fi
 
-  echo "错误：需要 ${MIN_PYTHON_LABEL}，但未找到可用解释器。" >&2
-  echo "已尝试：COWORK_FLOW_PYTHON、PYTHON、python3、python、py -3。" >&2
-  echo "可设置 COWORK_FLOW_PYTHON=/path/to/python3 后重试。" >&2
+  echo "Error: ${MIN_PYTHON_LABEL} is required, but no usable interpreter was found." >&2
+  echo "Tried: COWORK_FLOW_PYTHON, PYTHON, python3, python, py -3." >&2
+  echo "Set COWORK_FLOW_PYTHON=/path/to/python3 and retry." >&2
   exit 127
 }
 
-exec_python() {
-  select_python
-
-  if [ -n "$SELECTED_PYTHON_ARG" ]; then
-    exec "$SELECTED_PYTHON" "$SELECTED_PYTHON_ARG" "$@"
-  fi
-
-  exec "$SELECTED_PYTHON" "$@"
-}
-
-run_script() {
-  script_path=$1
-  shift
-
-  if [ ! -f "$script_path" ]; then
-    echo "错误：找不到脚本：$script_path" >&2
-    exit 2
-  fi
-
-  exec_python "$script_path" "$@"
-}
+select_python
 
-if [ "$#" -eq 0 ]; then
-  print_usage >&2
-  exit 2
+if [ -n "$SELECTED_PYTHON_ARG" ]; then
+  exec "$SELECTED_PYTHON" "$SELECTED_PYTHON_ARG" "$RUNNER_SCRIPT" "$@"
 fi
 
-command_name=$1
-shift
-
-case "$command_name" in
-  -h|--help|help)
-    print_usage
-    exit 0
-    ;;
-  python)
-    exec_python "$@"
-    ;;
-  resume)
-    run_script "$SCRIPTS_DIR/resume.py" "$@"
-    ;;
-  task)
-    run_script "$SCRIPTS_DIR/task.py" "$@"
-    ;;
-  change)
-    run_script "$SCRIPTS_DIR/change.py" "$@"
-    ;;
-  get-context|get_context)
-    run_script "$SCRIPTS_DIR/get_context.py" "$@"
-    ;;
-  get-developer|get_developer)
-    run_script "$SCRIPTS_DIR/get_developer.py" "$@"
-    ;;
-  init-developer|init_developer)
-    run_script "$SCRIPTS_DIR/init_developer.py" "$@"
-    ;;
-  add-session|add_session)
-    run_script "$SCRIPTS_DIR/add_session.py" "$@"
-    ;;
-  agent-team|agent_team)
-    run_script "$SCRIPTS_DIR/agent_team.py" "$@"
-    ;;
-  *)
-    if [ -f "$SCRIPTS_DIR/$command_name.py" ]; then
-      run_script "$SCRIPTS_DIR/$command_name.py" "$@"
-    fi
-
-    echo "错误：未知 cowork-flow 命令：$command_name" >&2
-    print_usage >&2
-    exit 2
-    ;;
-esac
+exec "$SELECTED_PYTHON" "$RUNNER_SCRIPT" "$@"

package/template/.cowork-flow/run.cmd

@@ -4,108 +4,20 @@ setlocal EnableExtensions
 set "MIN_PYTHON_LABEL=Python 3.8+"
 set "VERSION_CHECK=import sys; raise SystemExit(0 if sys.version_info >= (3, 8) else 1)"
 set "WORKFLOW_DIR=%~dp0"
-set "SCRIPTS_DIR=%WORKFLOW_DIR%scripts"
+set "RUNNER_SCRIPT=%WORKFLOW_DIR%scripts\run.py"
 set "SELECTED_PYTHON="
 set "SELECTED_PYTHON_ARG="
-set "REST_ARGS="
 
-if "%~1"=="" goto usage_error
-
-set "COMMAND_NAME=%~1"
-if not "%~2"=="" (
-  for /F "tokens=1,* delims= " %%A in ("%*") do set "REST_ARGS=%%B"
-)
+call :select_python
+if errorlevel 1 exit /b %ERRORLEVEL%
 
-if /I "%COMMAND_NAME%"=="-h" goto usage
-if /I "%COMMAND_NAME%"=="--help" goto usage
-if /I "%COMMAND_NAME%"=="help" goto usage
-if /I "%COMMAND_NAME%"=="python" goto run_python_passthrough
-if /I "%COMMAND_NAME%"=="resume" goto run_resume
-if /I "%COMMAND_NAME%"=="task" goto run_task
-if /I "%COMMAND_NAME%"=="change" goto run_change
-if /I "%COMMAND_NAME%"=="get-context" goto run_get_context
-if /I "%COMMAND_NAME%"=="get_context" goto run_get_context
-if /I "%COMMAND_NAME%"=="get-developer" goto run_get_developer
-if /I "%COMMAND_NAME%"=="get_developer" goto run_get_developer
-if /I "%COMMAND_NAME%"=="init-developer" goto run_init_developer
-if /I "%COMMAND_NAME%"=="init_developer" goto run_init_developer
-if /I "%COMMAND_NAME%"=="add-session" goto run_add_session
-if /I "%COMMAND_NAME%"=="add_session" goto run_add_session
-if /I "%COMMAND_NAME%"=="agent-team" goto run_agent_team
-if /I "%COMMAND_NAME%"=="agent_team" goto run_agent_team
-
-if exist "%SCRIPTS_DIR%\%COMMAND_NAME%.py" (
-  call :run_script "%SCRIPTS_DIR%\%COMMAND_NAME%.py"
-  exit /b %ERRORLEVEL%
+if not "%SELECTED_PYTHON_ARG%"=="" (
+  "%SELECTED_PYTHON%" "%SELECTED_PYTHON_ARG%" "%RUNNER_SCRIPT%" %*
+) else (
+  "%SELECTED_PYTHON%" "%RUNNER_SCRIPT%" %*
 )
-
-echo 错误：未知 cowork-flow 命令：%COMMAND_NAME% 1>&2
-call :print_usage 1>&2
-exit /b 2
-
-:usage
-call :print_usage
-exit /b 0
-
-:usage_error
-call :print_usage 1>&2
-exit /b 2
-
-:run_python_passthrough
-call :exec_python %REST_ARGS%
-exit /b %ERRORLEVEL%
-
-:run_resume
-call :run_script "%SCRIPTS_DIR%\resume.py"
-exit /b %ERRORLEVEL%
-
-:run_task
-call :run_script "%SCRIPTS_DIR%\task.py"
-exit /b %ERRORLEVEL%
-
-:run_change
-call :run_script "%SCRIPTS_DIR%\change.py"
-exit /b %ERRORLEVEL%
-
-:run_get_context
-call :run_script "%SCRIPTS_DIR%\get_context.py"
-exit /b %ERRORLEVEL%
-
-:run_get_developer
-call :run_script "%SCRIPTS_DIR%\get_developer.py"
 exit /b %ERRORLEVEL%
 
-:run_init_developer
-call :run_script "%SCRIPTS_DIR%\init_developer.py"
-exit /b %ERRORLEVEL%
-
-:run_add_session
-call :run_script "%SCRIPTS_DIR%\add_session.py"
-exit /b %ERRORLEVEL%
-
-:run_agent_team
-call :run_script "%SCRIPTS_DIR%\agent_team.py"
-exit /b %ERRORLEVEL%
-
-:print_usage
-echo 用法：
-echo   .\.cowork-flow\run.cmd ^<command^> [args...]
-echo   .\.cowork-flow\run.cmd python [python-args...]
-echo.
-echo 常用 command：
-echo   resume
-echo   task
-echo   change
-echo   get-context
-echo   get-developer
-echo   init-developer
-echo   add-session
-echo   agent-team
-echo.
-echo 解释器选择顺序：
-echo   COWORK_FLOW_PYTHON -^> PYTHON -^> python3 -^> python -^> py -3
-exit /b 0
-
 :candidate_is_valid
 set "CANDIDATE_CMD=%~1"
 set "CANDIDATE_ARG=%~2"
@@ -133,8 +45,8 @@ if not errorlevel 1 (
   exit /b 0
 )
 
-echo 错误：%ENV_NAME% 指向的解释器不可用或版本低于 %MIN_PYTHON_LABEL%：%ENV_VALUE% 1>&2
-echo 请设置 %ENV_NAME% 为可执行的 Python 3.8+ 解释器路径。 1>&2
+echo Error: %ENV_NAME% does not point to a usable %MIN_PYTHON_LABEL% interpreter: %ENV_VALUE% 1>&2
+echo Set %ENV_NAME% to an executable Python 3.8+ interpreter path. 1>&2
 exit /b 127
 
 :select_python
@@ -170,29 +82,7 @@ if not errorlevel 1 (
   exit /b 0
 )
 
-echo 错误：需要 %MIN_PYTHON_LABEL%，但未找到可用解释器。 1>&2
-echo 已尝试：COWORK_FLOW_PYTHON、PYTHON、python3、python、py -3。 1>&2
-echo 可设置 COWORK_FLOW_PYTHON=C:\Path\To\python.exe 后重试。 1>&2
+echo Error: %MIN_PYTHON_LABEL% is required, but no usable interpreter was found. 1>&2
+echo Tried: COWORK_FLOW_PYTHON, PYTHON, python3, python, py -3. 1>&2
+echo Set COWORK_FLOW_PYTHON=C:\Path\To\python.exe and retry. 1>&2
 exit /b 127
-
-:exec_python
-call :select_python
-if errorlevel 1 exit /b %ERRORLEVEL%
-
-if not "%SELECTED_PYTHON_ARG%"=="" (
-  "%SELECTED_PYTHON%" "%SELECTED_PYTHON_ARG%" %*
-) else (
-  "%SELECTED_PYTHON%" %*
-)
-exit /b %ERRORLEVEL%
-
-:run_script
-set "SCRIPT_PATH=%~1"
-
-if not exist "%SCRIPT_PATH%" (
-  echo 错误：找不到脚本：%SCRIPT_PATH% 1>&2
-  exit /b 2
-)
-
-call :exec_python "%SCRIPT_PATH%" %REST_ARGS%
-exit /b %ERRORLEVEL%

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

@@ -15,6 +15,7 @@ from common.agent_team import (
     build_initial_metrics,
     build_initial_status,
     parse_plan,
+    load_agent_registry,
     render_assignment_prompt,
     render_dispatch_plan,
     write_json,
@@ -31,7 +32,7 @@ default_adapter: codex
 
 agents:
   implementer:
-    codex_type: worker
+    agent_type: worker
     capabilities:
       - implementation
       - test-writing
@@ -45,9 +46,51 @@ agents:
       - "test/**"
     risk_limits:
       max_parallel_write_conflicts: 0
+    prompt: |
+      Implement the smallest change that satisfies the approved plan and tests.
+      Write or update focused regression tests first, keep edits scoped, and report exact verification commands.
+
+  tester:
+    agent_type: worker
+    capabilities:
+      - test-writing
+      - verification
+    preferred_task_types:
+      - test
+      - verification
+    file_patterns:
+      - "tests/**"
+      - "test/**"
+      - "src/**"
+      - "template/**"
+    risk_limits:
+      max_parallel_write_conflicts: 0
+    prompt: |
+      Design tests that fail for the broken behavior and pass for the intended behavior.
+      Prefer clear behavior assertions over implementation details, and include the command that proves the result.
+
+  debugger:
+    agent_type: worker
+    capabilities:
+      - debugging
+      - implementation
+      - verification
+    preferred_task_types:
+      - bugfix
+      - code
+    file_patterns:
+      - "src/**"
+      - "template/**"
+      - "tests/**"
+      - "test/**"
+    risk_limits:
+      max_parallel_write_conflicts: 0
+    prompt: |
+      Find the root cause before changing code. Reproduce the failure, compare with nearby working patterns,
+      then make the smallest fix and verify the original symptom.
 
   spec-reviewer:
-    codex_type: default
+    agent_type: default
     capabilities:
       - spec-review
       - acceptance-check
@@ -61,12 +104,16 @@ agents:
       - "template/**"
     risk_limits:
       max_parallel_write_conflicts: 0
+    prompt: |
+      Review the proposal, spec, plan, and task PRD for contradictions, missing acceptance criteria,
+      unclear scope, and behavior that is not covered by verification.
 
   quality-reviewer:
-    codex_type: default
+    agent_type: default
     capabilities:
       - code-quality-review
       - test-review
+      - verification
     preferred_task_types:
       - review
       - verification
@@ -77,14 +124,18 @@ agents:
       - "test/**"
     risk_limits:
       max_parallel_write_conflicts: 0
+    prompt: |
+      Review the diff for correctness, maintainability, focused scope, and meaningful tests.
+      Check that verification evidence matches the behavior being claimed.
 
   docs-agent:
-    codex_type: worker
+    agent_type: worker
     capabilities:
       - documentation
       - workflow-writing
     preferred_task_types:
       - docs
+      - documentation
     file_patterns:
       - "README.md"
       - "AGENTS.md"
@@ -92,6 +143,30 @@ agents:
       - ".agent/skills/**"
     risk_limits:
       max_parallel_write_conflicts: 0
+    prompt: |
+      Write concise project documentation that reflects actual commands, files, and workflow behavior.
+      Avoid aspirational text that is not backed by the implementation.
+
+  release-reviewer:
+    agent_type: default
+    capabilities:
+      - release-review
+      - acceptance-check
+      - verification
+    preferred_task_types:
+      - release
+      - review
+    file_patterns:
+      - "package.json"
+      - "package-lock.json"
+      - "scripts/**"
+      - "README.md"
+      - ".cowork-flow/changes/**"
+    risk_limits:
+      max_parallel_write_conflicts: 0
+    prompt: |
+      Review release-facing changes for versioning, packaging, documentation, and command safety.
+      Confirm that generated artifacts and publish steps are intentional.
 """,
     "adapters.yaml": """# Agent Team Adapters
 
@@ -309,7 +384,8 @@ def cmd_prepare(args: argparse.Namespace) -> int:
     ):
         directory.mkdir(parents=True, exist_ok=True)
 
-    dispatch_plan = build_dispatch_plan(tasks)
+    registry = load_agent_registry(_agent_team_config_dir(repo_root) / "agents.yaml")
+    dispatch_plan = build_dispatch_plan(tasks, registry)
     (runtime_dir / "dispatch-plan.yaml").write_text(
         render_dispatch_plan(dispatch_plan),
         encoding="utf-8",
@@ -317,9 +393,9 @@ def cmd_prepare(args: argparse.Namespace) -> int:
     write_json(runtime_dir / "status.json", build_initial_status(dispatch_plan))
     write_json(runtime_dir / "metrics.json", build_initial_metrics(dispatch_plan))
     write_json(
-        adapters_dir / "codex.json",
+        adapters_dir / f"{dispatch_plan['adapter']}.json",
         {
-            "adapter": "codex",
+            "adapter": dispatch_plan["adapter"],
             "mode": "coordinator-dispatched",
             "assignmentCount": len(dispatch_plan["assignments"]),
         },
@@ -371,7 +447,7 @@ def cmd_next(args: argparse.Namespace) -> int:
     for assignment_id, assignment in ready:
         print(
             f"{assignment_id}\trole={assignment['role']}\t"
-            f"agent={assignment['recommended_agent']}\tcodex_type={assignment['codex_type']}"
+            f"agent={assignment['recommended_agent']}\tagent_type={assignment['agent_type']}"
         )
     return 0
 

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

@@ -6,12 +6,18 @@ from __future__ import annotations
 
 import argparse
 import re
-import shutil
 import sys
 from datetime import datetime
 from pathlib import Path
 
-from common.paths import DIR_ARCHIVE, DIR_CHANGES, DIR_WORKFLOW, get_repo_root
+from common.archive_utils import archive_directory_resumable
+from common.paths import (
+    DIR_ARCHIVE,
+    DIR_CHANGES,
+    DIR_WORKFLOW,
+    generate_task_date_prefix,
+    get_repo_root,
+)
 
 
 SLUG_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
@@ -107,9 +113,52 @@ def _resolve_link(repo_root: Path, base_dir: str, value: object) -> Path | None:
         return raw_path
 
     direct = repo_root / raw_path
-    if direct.exists():
+    workflow_base = Path(DIR_WORKFLOW) / base_dir
+    if direct.exists() or raw_path.parts[:2] == workflow_base.parts:
         return direct
-    return repo_root / DIR_WORKFLOW / base_dir / raw_path
+    return repo_root / workflow_base / raw_path
+
+
+def _archived_task_link(repo_root: Path, task_name: str) -> str | None:
+    archive_root = repo_root / DIR_WORKFLOW / "tasks" / DIR_ARCHIVE
+    if not archive_root.is_dir():
+        return None
+
+    matches = [path for path in archive_root.glob(f"*/{task_name}") if path.is_dir()]
+    if len(matches) != 1:
+        return None
+
+    relative = matches[0].relative_to(archive_root)
+    return str(Path(DIR_ARCHIVE) / relative).replace("\\", "/")
+
+
+def _normalize_task_link(repo_root: Path, value: object) -> object:
+    if not isinstance(value, str) or not value.strip():
+        return value
+
+    target = _resolve_link(repo_root, "tasks", value)
+    tasks_root = repo_root / DIR_WORKFLOW / "tasks"
+    archive_root = tasks_root / DIR_ARCHIVE
+    if target is None:
+        return value
+
+    if not target.exists():
+        return _archived_task_link(repo_root, target.name) or value
+
+    try:
+        relative = target.resolve().relative_to(archive_root.resolve())
+    except ValueError:
+        return value
+
+    return str(Path(DIR_ARCHIVE) / relative).replace("\\", "/")
+
+
+def _normalize_archive_metadata(repo_root: Path, change_dir: Path) -> None:
+    metadata = _read_metadata(change_dir)
+    normalized_task = _normalize_task_link(repo_root, metadata.get("task"))
+    if normalized_task != metadata.get("task"):
+        metadata["task"] = normalized_task
+        _write_metadata(change_dir, metadata)
 
 
 def _validate_link(repo_root: Path, metadata: dict[str, object], field: str, base_dir: str) -> str | None:
@@ -178,14 +227,15 @@ def create_change(args: argparse.Namespace) -> int:
     if not _validate_slug(slug):
         return 2
 
-    change_dir = _change_dir(repo_root, slug)
+    dir_name = f"{generate_task_date_prefix()}-{slug}"
+    change_dir = _change_dir(repo_root, dir_name)
     if change_dir.exists():
-        print(f"Error: change already exists: {slug}", file=sys.stderr)
+        print(f"Error: change already exists: {dir_name}", file=sys.stderr)
         return 1
 
     change_dir.mkdir(parents=True)
     (change_dir / "proposal.md").write_text(
-        f"# {slug}\n\nDescribe the proposed behavior change.\n",
+        f"# {dir_name}\n\nDescribe the proposed behavior change.\n",
         encoding="utf-8",
     )
     (change_dir / "design.md").write_text("", encoding="utf-8")
@@ -193,7 +243,7 @@ def create_change(args: argparse.Namespace) -> int:
     _write_metadata(
         change_dir,
         {
-            "slug": slug,
+            "slug": dir_name,
             "status": "draft",
             "level": args.level,
             "created_at": _now_iso(),
@@ -203,7 +253,7 @@ def create_change(args: argparse.Namespace) -> int:
         },
     )
 
-    print(f"created {slug}")
+    print(f"created {dir_name}")
     return 0
 
 
@@ -215,22 +265,25 @@ def validate_command(args: argparse.Namespace) -> int:
 def archive_change(args: argparse.Namespace) -> int:
     repo_root = get_repo_root()
     slug = args.slug
+    source = _change_dir(repo_root, slug)
+    if source.is_dir():
+        _normalize_archive_metadata(repo_root, source)
+
     if not validate_change(repo_root, slug, quiet=True):
         return 1
 
-    source = _change_dir(repo_root, slug)
     month = datetime.now().astimezone().strftime("%Y-%m")
     destination = _archive_dir(repo_root) / month / slug
-    if destination.exists():
-        print(f"Error: archive destination already exists: {destination}", file=sys.stderr)
+    result = archive_directory_resumable(source, destination)
+    if not result.ok:
+        level = "Warning" if result.partial else "Error"
+        print(f"{level}: {result.message}", file=sys.stderr)
         return 1
 
-    destination.parent.mkdir(parents=True, exist_ok=True)
-    shutil.move(str(source), str(destination))
-
     metadata = _read_metadata(destination)
     metadata["status"] = "archived"
     metadata["archived_at"] = _now_iso()
+    metadata["task"] = _normalize_task_link(repo_root, metadata.get("task"))
     _write_metadata(destination, metadata)
 
     print(f"archived {slug}")

package/template/.cowork-flow/scripts/common/agent_team.py

@@ -102,15 +102,222 @@ def _task_dependencies(tasks: list[dict[str, object]]) -> list[dict[str, str]]:
     return dependencies
 
 
-def _role_agent(role: str) -> tuple[str, str]:
-    if role == "implementer":
-        return ("implementer", "worker")
-    if role == "spec-reviewer":
-        return ("spec-reviewer", "default")
-    return ("quality-reviewer", "default")
+DEFAULT_ROLE_TYPES = {
+    "implementer": "worker",
+    "spec-reviewer": "default",
+    "quality-reviewer": "default",
+}
+
+ROLE_CAPABILITIES = {
+    "implementer": {"implementation", "test-writing"},
+    "spec-reviewer": {"spec-review", "acceptance-check"},
+    "quality-reviewer": {"code-quality-review", "test-review", "verification"},
+}
+
+ROLE_TASK_TYPES = {
+    "implementer": {"code", "test"},
+    "spec-reviewer": {"review", "documentation"},
+    "quality-reviewer": {"review", "verification"},
+}
+
+
+def _role_config(registry: dict[str, object] | None, role: str) -> dict[str, object]:
+    agents = registry.get("agents", {}) if registry else {}
+    if not isinstance(agents, dict):
+        return {}
+    config = agents.get(role, {})
+    return config if isinstance(config, dict) else {}
+
+
+def _ensure_agent_config(registry: dict[str, object], role: str) -> dict[str, object]:
+    agents = registry.setdefault("agents", {})
+    if not isinstance(agents, dict):
+        registry["agents"] = {}
+        agents = registry["agents"]
+    config = agents.setdefault(role, {})
+    if not isinstance(config, dict):
+        agents[role] = {}
+        config = agents[role]
+    return config
+
+
+def _parse_list_item(line: str) -> str | None:
+    stripped = line.strip()
+    if not stripped.startswith("-"):
+        return None
+    value = stripped[1:].strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}:
+        value = value[1:-1]
+    return value
+
+
+def load_agent_registry(path: Path) -> dict[str, object]:
+    registry: dict[str, object] = {"default_adapter": "codex", "agents": {}}
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return registry
+
+    current_role: str | None = None
+    current_list: str | None = None
+    current_nested: str | None = None
+    prompt_role: str | None = None
+    prompt_lines: list[str] = []
+    in_agents = False
+
+    def flush_prompt() -> None:
+        nonlocal prompt_role, prompt_lines
+        if prompt_role is None:
+            return
+        config = _ensure_agent_config(registry, prompt_role)
+        config["prompt"] = "\n".join(prompt_lines).rstrip()
+        prompt_role = None
+        prompt_lines = []
+
+    for raw_line in lines:
+        indent = len(raw_line) - len(raw_line.lstrip())
+        stripped = raw_line.strip()
+
+        if prompt_role is not None:
+            if raw_line.startswith("      ") or not stripped:
+                prompt_lines.append(raw_line[6:] if raw_line.startswith("      ") else "")
+                continue
+            flush_prompt()
+
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        if indent == 0:
+            current_role = None
+            current_list = None
+            current_nested = None
+            in_agents = stripped == "agents:"
+            if stripped.startswith("default_adapter:"):
+                registry["default_adapter"] = stripped.partition(":")[2].strip() or "codex"
+            continue
+
+        if in_agents and indent == 2 and stripped.endswith(":"):
+            current_role = stripped[:-1].strip()
+            current_list = None
+            current_nested = None
+            _ensure_agent_config(registry, current_role)
+            continue
+
+        if not in_agents or current_role is None:
+            continue
+
+        config = _ensure_agent_config(registry, current_role)
+
+        if indent == 4 and stripped == "prompt: |":
+            current_list = None
+            current_nested = None
+            prompt_role = current_role
+            prompt_lines = []
+            continue
+
+        if indent == 4 and stripped.endswith(":"):
+            key = stripped[:-1].strip()
+            current_list = key if key in {"capabilities", "preferred_task_types", "file_patterns"} else None
+            current_nested = key if key == "risk_limits" else None
+            if current_list:
+                config[current_list] = []
+            elif current_nested:
+                config[current_nested] = {}
+            continue
+
+        if indent == 4 and ":" in stripped:
+            key, _, value = stripped.partition(":")
+            key = key.strip()
+            value = value.strip()
+            current_list = None
+            current_nested = None
+            if key == "agent_type":
+                config[key] = value
+            continue
+
+        if indent == 6 and current_list:
+            value = _parse_list_item(stripped)
+            if value is not None:
+                items = config.setdefault(current_list, [])
+                if isinstance(items, list):
+                    items.append(value)
+            continue
+
+        if indent == 6 and current_nested == "risk_limits" and ":" in stripped:
+            key, _, value = stripped.partition(":")
+            limits = config.setdefault("risk_limits", {})
+            if isinstance(limits, dict):
+                try:
+                    limits[key.strip()] = int(value.strip())
+                except ValueError:
+                    limits[key.strip()] = value.strip()
+
+    flush_prompt()
+    return registry
+
 
+def _as_string_set(value: object) -> set[str]:
+    if not isinstance(value, list):
+        return set()
+    return {item for item in value if isinstance(item, str)}
+
+
+def _matches_pattern(path: str, pattern: str) -> bool:
+    if pattern.endswith("/**"):
+        return path.startswith(pattern[:-3])
+    return Path(path).match(pattern)
+
+
+def _file_match_count(config: dict[str, object], task: dict[str, object]) -> int:
+    patterns = _as_string_set(config.get("file_patterns"))
+    if not patterns:
+        return 0
+    count = 0
+    for file_path in _task_files(task):
+        if any(_matches_pattern(file_path, pattern) for pattern in patterns):
+            count += 1
+    return count
+
+
+def _agent_score(role: str, name: str, config: dict[str, object], task: dict[str, object]) -> int:
+    score = 0
+    if name == role:
+        score += 10
+    score += 5 * len(_as_string_set(config.get("capabilities")).intersection(ROLE_CAPABILITIES.get(role, set())))
+    score += 3 * len(_as_string_set(config.get("preferred_task_types")).intersection(ROLE_TASK_TYPES.get(role, set())))
+    score += 2 * _file_match_count(config, task)
+    return score
+
+
+def _select_agent(role: str, task: dict[str, object], registry: dict[str, object] | None = None) -> tuple[str, str, str]:
+    agents = registry.get("agents", {}) if registry else {}
+    if not isinstance(agents, dict):
+        agents = {}
+
+    best_name = role
+    best_config = _role_config(registry, role)
+    best_score = _agent_score(role, role, best_config, task) if best_config else -1
 
-def build_dispatch_plan(tasks: list[dict[str, object]]) -> dict[str, object]:
+    for name, config in agents.items():
+        if not isinstance(name, str) or not isinstance(config, dict):
+            continue
+        score = _agent_score(role, name, config, task)
+        if score > best_score or (score == best_score and name == role):
+            best_name = name
+            best_config = config
+            best_score = score
+
+    agent_type = DEFAULT_ROLE_TYPES.get(role, "default")
+    configured_type = best_config.get("agent_type") if isinstance(best_config, dict) else None
+    if isinstance(configured_type, str) and configured_type:
+        agent_type = configured_type
+    prompt = best_config.get("prompt") if isinstance(best_config, dict) else ""
+    return best_name, agent_type, prompt if isinstance(prompt, str) else ""
+
+def build_dispatch_plan(
+    tasks: list[dict[str, object]],
+    registry: dict[str, object] | None = None,
+) -> dict[str, object]:
     assignments: list[dict[str, object]] = []
     task_dependencies = _task_dependencies(tasks)
     dependency_lookup: dict[str, list[str]] = {}
@@ -129,7 +336,7 @@ def build_dispatch_plan(tasks: list[dict[str, object]]) -> dict[str, object]:
             ("quality-reviewer", [f"{task_id}-spec-reviewer"]),
         ]
         for role, depends_on in chain:
-            agent, codex_type = _role_agent(role)
+            agent, agent_type, agent_prompt = _select_agent(role, task, registry)
             assignments.append(
                 {
                     "id": f"{task_id}-{role}",
@@ -137,7 +344,8 @@ def build_dispatch_plan(tasks: list[dict[str, object]]) -> dict[str, object]:
                     "title": task["title"],
                     "role": role,
                     "recommended_agent": agent,
-                    "codex_type": codex_type,
+                    "agent_type": agent_type,
+                    "agent_prompt": agent_prompt,
                     "depends_on": depends_on,
                     "files": task.get("files", []),
                     "steps": task.get("steps", []),
@@ -147,7 +355,7 @@ def build_dispatch_plan(tasks: list[dict[str, object]]) -> dict[str, object]:
 
     return {
         "version": 1,
-        "adapter": "codex",
+        "adapter": str(registry.get("default_adapter", "codex")) if registry else "codex",
         "tasks": tasks,
         "task_dependencies": task_dependencies,
         "assignments": assignments,
@@ -176,7 +384,7 @@ def render_dispatch_plan(dispatch_plan: dict[str, object]) -> str:
                 f"    task: {assignment['task']}",
                 f"    role: {assignment['role']}",
                 f"    recommended_agent: {assignment['recommended_agent']}",
-                f"    codex_type: {assignment['codex_type']}",
+                f"    agent_type: {assignment['agent_type']}",
                 "    depends_on:",
             ]
         )
@@ -209,7 +417,8 @@ def build_initial_status(dispatch_plan: dict[str, object]) -> dict[str, object]:
             "role": assignment["role"],
             "task": assignment["task"],
             "recommended_agent": assignment["recommended_agent"],
-            "codex_type": assignment["codex_type"],
+            "agent_type": assignment["agent_type"],
+            "agent_prompt": assignment.get("agent_prompt", ""),
         }
 
     return {"version": 1, "current_batch": 1, "assignments": assignments}
@@ -226,16 +435,33 @@ def build_initial_metrics(dispatch_plan: dict[str, object]) -> dict[str, object]
     }
 
 
+def _render_named_items(title: str, items: object) -> list[str]:
+    lines = [f"## {title}", ""]
+    if isinstance(items, list) and items:
+        for item in items:
+            lines.append(f"- {item}")
+    else:
+        lines.append("- none")
+    lines.append("")
+    return lines
+
+
 def render_assignment_prompt(assignment: dict[str, object]) -> str:
-    return "\n".join(
-        [
-            f"# {assignment['id']}",
-            "",
-            f"Role: {assignment['role']}",
-            f"Recommended agent: {assignment['recommended_agent']}",
-            f"Codex type: {assignment['codex_type']}",
-            "",
-            "You are not alone in this codebase. Respect the write boundary, do not revert other agents' edits, and report changed files.",
-            "",
-        ]
-    )
+    lines = [
+        f"# {assignment['id']}",
+        "",
+        f"Role: {assignment['role']}",
+        f"Recommended agent: {assignment['recommended_agent']}",
+        f"Agent type: {assignment['agent_type']}",
+        f"Task: {assignment.get('title', '')}",
+        "",
+    ]
+    agent_prompt = assignment.get("agent_prompt")
+    if isinstance(agent_prompt, str) and agent_prompt.strip():
+        lines.extend(["## Agent prompt", "", agent_prompt.strip(), ""])
+    lines.append("You are not alone in this codebase. Respect the write boundary, do not revert other agents' edits, and report changed files.")
+    lines.append("")
+    lines.extend(_render_named_items("Files", assignment.get("files")))
+    lines.extend(_render_named_items("Steps", assignment.get("steps")))
+    lines.extend(_render_named_items("Commands", assignment.get("commands")))
+    return "\n".join(lines)

package/template/.cowork-flow/scripts/common/archive_utils.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Small resumable directory archive helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import filecmp
+import shutil
+
+
+@dataclass(frozen=True)
+class ArchiveResult:
+    status: str
+    destination: Path
+    message: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.status == "archived"
+
+    @property
+    def partial(self) -> bool:
+        return self.status == "partial"
+
+
+def directories_match(left: Path, right: Path) -> bool:
+    """Return True when two directory trees contain the same files and bytes."""
+    if not left.is_dir() or not right.is_dir():
+        return False
+
+    left_files = sorted(path.relative_to(left) for path in left.rglob("*") if path.is_file())
+    right_files = sorted(path.relative_to(right) for path in right.rglob("*") if path.is_file())
+    if left_files != right_files:
+        return False
+
+    return all(filecmp.cmp(left / rel, right / rel, shallow=False) for rel in left_files)
+
+
+def archive_directory_resumable(source: Path, destination: Path) -> ArchiveResult:
+    """Copy, verify, then delete a directory, resuming matching duplicate state."""
+    if not source.is_dir():
+        return ArchiveResult("failed", destination, f"source directory not found: {source}")
+
+    if destination.exists():
+        if not destination.is_dir():
+            return ArchiveResult("failed", destination, f"archive destination is not a directory: {destination}")
+        if not directories_match(source, destination):
+            return ArchiveResult(
+                "failed",
+                destination,
+                f"archive source and destination differ: {source} | {destination}",
+            )
+    else:
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            shutil.copytree(source, destination)
+        except (OSError, IOError, shutil.Error) as exc:
+            return ArchiveResult("failed", destination, f"failed to copy directory to archive: {exc}")
+        if not directories_match(source, destination):
+            return ArchiveResult("failed", destination, f"archive verification failed: {source} | {destination}")
+
+    try:
+        shutil.rmtree(source)
+    except (OSError, IOError) as exc:
+        return ArchiveResult(
+            "partial",
+            destination,
+            f"archive verified but source remains: {source}; delete failed: {exc}",
+        )
+
+    return ArchiveResult("archived", destination)

package/template/.cowork-flow/scripts/common/task_utils.py

@@ -10,11 +10,11 @@ Provides:
 
 from __future__ import annotations
 
-import shutil
 import sys
 from datetime import datetime
 from pathlib import Path
 
+from .archive_utils import archive_directory_resumable
 from .paths import get_repo_root
 
 PATH_TRAVERSAL_PREFIXES = ("./", "../")
@@ -139,23 +139,10 @@ def archive_task_dir(task_dir_abs: Path, repo_root: Path | None = None) -> Path
     task_name = task_dir_abs.name
     archive_dest = month_dir / task_name
 
-    if archive_dest.exists():
-        print(f"Error: archive target already exists: {archive_dest}", file=sys.stderr)
-        print(f"Source task directory is still present: {task_dir_abs}", file=sys.stderr)
-        return None
-
-    try:
-        shutil.move(str(task_dir_abs), str(archive_dest))
-    except (OSError, IOError, shutil.Error) as e:
-        print(f"Error: Failed to move task to archive: {e}", file=sys.stderr)
-        if archive_dest.exists() and task_dir_abs.exists():
-            print("Error: archive move left both source and target paths present.", file=sys.stderr)
-            print(f"  Source: {task_dir_abs}", file=sys.stderr)
-            print(f"  Target: {archive_dest}", file=sys.stderr)
-        elif archive_dest.exists():
-            print(f"Error: archive target path exists after failure: {archive_dest}", file=sys.stderr)
-        elif task_dir_abs.exists():
-            print(f"Error: source task directory is still present: {task_dir_abs}", file=sys.stderr)
+    result = archive_directory_resumable(task_dir_abs, archive_dest)
+    if not result.ok:
+        level = "Warning" if result.partial else "Error"
+        print(f"{level}: {result.message}", file=sys.stderr)
         return None
 
     return archive_dest

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

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Shared cowork-flow command dispatcher."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+COMMAND_SCRIPTS = {
+    "resume": "resume.py",
+    "task": "task.py",
+    "change": "change.py",
+    "get-context": "get_context.py",
+    "get_context": "get_context.py",
+    "get-developer": "get_developer.py",
+    "get_developer": "get_developer.py",
+    "init-developer": "init_developer.py",
+    "init_developer": "init_developer.py",
+    "add-session": "add_session.py",
+    "add_session": "add_session.py",
+    "agent-team": "agent_team.py",
+    "agent_team": "agent_team.py",
+}
+
+
+def print_usage() -> None:
+    print(
+        """Usage:
+  ./.cowork-flow/run <command> [args...]
+  ./.cowork-flow/run python [python-args...]
+
+Common commands:
+  resume
+  task
+  change
+  get-context
+  get-developer
+  init-developer
+  add-session
+  agent-team
+""".rstrip()
+    )
+
+
+def scripts_dir() -> Path:
+    return Path(__file__).resolve().parent
+
+
+def run_python(args: list[str]) -> int:
+    completed = subprocess.run([sys.executable, *args], check=False)
+    return int(completed.returncode)
+
+
+def run_script(script_name: str, args: list[str]) -> int:
+    script_path = scripts_dir() / script_name
+    if not script_path.is_file():
+        print(f"Error: script not found: {script_path}", file=sys.stderr)
+        return 2
+    return run_python([str(script_path), *args])
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args:
+        print_usage()
+        return 2
+
+    command = args[0]
+    rest = args[1:]
+    if command in {"-h", "--help", "help"}:
+        print_usage()
+        return 0
+    if command == "python":
+        return run_python(rest)
+
+    script_name = COMMAND_SCRIPTS.get(command)
+    if script_name is None:
+        candidate = scripts_dir() / f"{command}.py"
+        if candidate.is_file():
+            script_name = candidate.name
+        else:
+            print(f"Error: unknown cowork-flow command: {command}", file=sys.stderr)
+            print_usage()
+            return 2
+
+    return run_script(script_name, rest)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/.cowork-flow/workflow.md

@@ -179,10 +179,33 @@ done
 
 ### 7.7 按 superpowers 方法执行
 
-- 不支持 subAgent 模式时，使用 `superpowers:executing-plans`；否则：
-  - 当 `.cowork-flow/config.yaml` 中设置 `agent_team.enabled: true` 时，执行 plan 优先使用 `./.cowork-flow/run agent-team prepare <task-dir> --plan <plan-file>` 生成调度图，再用 `./.cowork-flow/run agent-team next <task-dir>` 获取可并行 assignments，由主 agent 审核并调度 subAgent。
-  - 当 `.cowork-flow/config.yaml` 中设置 `agent_team.enabled: false` 时，优先使用 `superpowers:subagent-driven-development` 开启多 agent 并行执行。
-- 严格遵循 `superpowers:test-driven-development`，不得先写生产代码再补测试。
+执行 plan 前，先判断**是否存在适合并行执行的独立任务**。并行是优化手段，不是完成定义；`agent_team.enabled` 只决定在适合并行时优先使用哪种机制，不决定是否必须并行。
+
+适合并行的条件包括：
+
+- 子任务之间没有共享写文件，或共享写文件已有明确顺序边界。
+- 子任务之间没有强顺序依赖。
+- 每个子任务都有清晰输入、输出和验收方式。
+- 主 agent 能在集成前独立审查每个结果。
+- 并行带来的收益大于调度、审阅和集成成本。
+
+不适合并行的情况包括：
+
+- 改动集中在同一组强耦合文件。
+- 需要密集的 TDD 红绿循环或即时反馈。
+- parser、schema、runtime、测试需要同步演进。
+- 子任务边界不清，拆分后的主要成本会落在集成。
+- 任务规模小于并行调度成本。
+
+不得为了满足流程形式而强行拆分高耦合任务。若不适合并行，必须简要记录不使用并行的理由，并在当前会话中按 plan 顺序执行。
+
+若适合并行：
+
+- 当 `.cowork-flow/config.yaml` 中设置 `agent_team.enabled: true` 时，使用 `./.cowork-flow/run agent-team prepare <task-dir> --plan <plan-file>` 生成调度图，再用 `./.cowork-flow/run agent-team next <task-dir>` 获取可并行 assignments，由主 agent 审核并调度 subAgent。
+- 当 `.cowork-flow/config.yaml` 中设置 `agent_team.enabled: false` 且宿主支持 subAgent 时，可使用 `superpowers:subagent-driven-development` 开启多 agent 并行执行。
+- 当宿主不支持 subAgent 或任务不适合并行时，使用 `superpowers:executing-plans` 或当前会话顺序执行。
+
+无论是否并行，都必须严格遵循 `superpowers:test-driven-development`，不得先写生产代码再补测试。
 
 执行中必须持续同步：