cowork-flow 0.0.4 → 0.0.7

package/README.md

@@ -28,6 +28,7 @@ cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它
     └── .cowork-flow/
         ├── config.yaml
         ├── workflow.md
+        ├── agent-team/
         ├── scripts/
         ├── spec/
         ├── changes/
@@ -56,6 +57,9 @@ cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它
 `template/.cowork-flow/plans/`
 保存可执行步骤、验证方式和执行状态。
 
+`template/.cowork-flow/agent-team/`
+保存 agent team 的项目级 registry、适配器和策略。默认适配器是 `codex`，由主 agent 调度 Codex 子 agent；没有子 agent 能力时可退回 `manual` 提示词模式。
+
 ## 快速开始
 
 使用 CLI 把模板内容安装到目标项目根目录：
@@ -172,6 +176,19 @@ cowork-flow sync . --dry-run
 ./.cowork-flow/run task start <task-dir>
 ```
 
+执行 plan 时准备 agent team：
+
+默认 `agent_team.enabled: false`。运行 `agent-team prepare/status/next/record-result/record-review/retry/complete` 前，先在 `.cowork-flow/config.yaml` 中设置 `agent_team.enabled: true`。
+
+```bash
+./.cowork-flow/run agent-team init
+./.cowork-flow/run agent-team prepare <task-dir> --plan <plan-file>
+./.cowork-flow/run agent-team next <task-dir>
+./.cowork-flow/run agent-team complete <task-dir>
+```
+
+`agent-team` 命令会生成任务目录内的 dispatch plan、assignments、状态、审阅和 metrics 工件。默认 `codex` 适配器采用主 agent 调度型：脚本生成 Codex-ready 分派文件，主 agent 负责调用子 agent、协调并回写结果。
+
 记录 session：
 
 ```bash
@@ -202,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.4",
+  "version": "0.0.7",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {
@@ -10,13 +10,16 @@
     "bin",
     "src",
     "template",
-    "README.md"
+    "README.md",
+    "!template/**/__pycache__/**",
+    "!template/**/*.pyc"
   ],
   "scripts": {
     "test": "node --test",
-    "test:template": "./template/.cowork-flow/run python -m unittest discover tests -v",
-    "pack:check": "npm_config_cache=/tmp/cowork-flow-npm-cache npm pack --dry-run --json",
-    "test:all": "npm test && npm run test:template && npm run pack:check"
+    "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",
+    "release": "sh scripts/release.sh"
   },
   "engines": {
     "node": ">=20"

package/src/lib/copy-template.js

@@ -90,9 +90,7 @@ export async function buildSuperpowersPlan(targetDir, options = {}) {
 }
 
 const PROTECTED_SYNC_FILES = new Set([
-  'AGENTS.md',
-  '.cowork-flow/config.yaml',
-  '.cowork-flow/workflow.md'
+  '.cowork-flow/config.yaml'
 ]);
 
 const PROTECTED_SYNC_PREFIXES = [
@@ -105,7 +103,7 @@ const PROTECTED_SYNC_PREFIXES = [
 
 const SAFE_SYNC_PREFIXES = [
   '.agent/skills/',
-  '.cowork-flow/scripts/'
+  '.cowork-flow/'
 ];
 
 const SAFE_SYNC_FILES = new Set([
@@ -119,14 +117,16 @@ const COWORK_FLOW_START = '<!-- COWORK-FLOW:START -->';
 const COWORK_FLOW_END = '<!-- COWORK-FLOW:END -->';
 
 function isProtectedSyncFile(relativePath) {
-  return PROTECTED_SYNC_FILES.has(relativePath)
-    || PROTECTED_SYNC_PREFIXES.some((prefix) => relativePath.startsWith(prefix));
+  const templatePath = toTemplatePath(relativePath);
+  return PROTECTED_SYNC_FILES.has(templatePath)
+    || PROTECTED_SYNC_PREFIXES.some((prefix) => templatePath.startsWith(prefix));
 }
 
 function isSafeSyncFile(relativePath) {
-  return SAFE_SYNC_FILES.has(relativePath)
-    || SAFE_SYNC_PREFIXES.some((prefix) => relativePath.startsWith(prefix))
-    || relativePath.endsWith('/.gitkeep');
+  const templatePath = toTemplatePath(relativePath);
+  return SAFE_SYNC_FILES.has(templatePath)
+    || SAFE_SYNC_PREFIXES.some((prefix) => templatePath.startsWith(prefix))
+    || templatePath.endsWith('/.gitkeep');
 }
 
 function replaceManagedBlock(targetContent, templateContent) {

package/src/lib/package-info.js

@@ -31,9 +31,14 @@ export function compareVersions(left, right) {
   return 0;
 }
 
+export function npmCommandOptions(platform = process.platform) {
+  return platform === 'win32' ? { shell: true } : {};
+}
+
 export async function fetchLatestVersion(packageName = 'cowork-flow') {
   const result = await execFileAsync('npm', ['view', packageName, 'version'], {
-    encoding: 'utf8'
+    encoding: 'utf8',
+    ...npmCommandOptions()
   });
   return result.stdout.trim();
 }
@@ -41,7 +46,8 @@ export async function fetchLatestVersion(packageName = 'cowork-flow') {
 export async function runGlobalInstall(packageSpec = 'cowork-flow@latest') {
   return new Promise((resolvePromise, rejectPromise) => {
     const child = spawn('npm', ['install', '-g', packageSpec], {
-      stdio: 'inherit'
+      stdio: 'inherit',
+      ...npmCommandOptions()
     });
     child.on('error', rejectPromise);
     child.on('close', (code) => resolvePromise(code ?? 1));

package/template/.agent/skills/agent-team-execution/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: agent-team-execution
+description: Use when executing an approved implementation plan with independent tasks, multiple agents, or an explicit request to use agent team execution
+---
+
+# Agent Team Execution
+
+Use this skill after a task is active and an approved `.cowork-flow/plans/*.md` file is in task context.
+
+## Process
+
+1. Run `./.cowork-flow/run agent-team prepare <task-dir> --plan <plan-file>`.
+2. Review `agent-team/dispatch-plan.yaml` for unsafe parallelism, file conflicts, missing context, or weak agent matches.
+3. Run `./.cowork-flow/run agent-team next <task-dir>` to get ready assignments.
+4. In Codex, dispatch the ready assignments to the recommended agent types. Tell each worker it is not alone in the codebase, must respect the write boundary, must not revert others' edits, and must list changed files.
+5. While workers run, coordinate: answer questions, unblock context gaps, and integrate non-conflicting results.
+6. Record outputs with `record-result` and reviews with `record-review`.
+7. Use `retry` only after adding missing context, changing agent choice, or splitting an oversized assignment.
+8. Run `complete` before claiming the agent team work is done.
+
+## Rules
+
+- The script suggests; the main agent decides.
+- Do not parallelize assignments with overlapping write files.
+- Do not skip spec review or quality review.
+- Do not rely on chat history for state; write results through `agent-team` commands.

package/template/.agent/skills/start/SKILL.md

@@ -336,6 +336,7 @@ Implement the task described in `prd.md`.
 - Follow all specs injected into implement context
 - Keep changes scoped to requirements
 - Run the project verification commands from `AGENTS.md` or `.cowork-flow/config.yaml` before finishing
+- If executing an approved plan with independent work, use `agent-team-execution`: run `agent-team prepare`, review the dispatch plan, use `agent-team next` for ready assignments, and finish with `agent-team complete`.
 
 **Step 9: Check Quality** `[AI]`
 

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.4
+0.0.7

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

@@ -0,0 +1,15 @@
+# Agent Team Adapters
+
+default: codex
+fallback: manual
+
+adapters:
+  codex:
+    mode: coordinator-dispatched
+    description: 主 agent 使用 Codex 子 agent 工具执行脚本生成的 assignments。
+    output_file: adapters/codex.json
+
+  manual:
+    mode: prompt-only
+    description: 生成可复制的 assignment prompt，由人或其他宿主执行并回写结果。
+    output_file: adapters/manual.json

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

@@ -0,0 +1,142 @@
+# Agent Team Registry
+# Project teams may customize this file after initialization.
+
+default_adapter: codex
+
+agents:
+  implementer:
+    agent_type: worker
+    capabilities:
+      - implementation
+      - test-writing
+    preferred_task_types:
+      - code
+      - test
+    file_patterns:
+      - "src/**"
+      - "template/**"
+      - "tests/**"
+      - "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:
+    agent_type: default
+    capabilities:
+      - spec-review
+      - acceptance-check
+    preferred_task_types:
+      - review
+      - documentation
+    file_patterns:
+      - ".cowork-flow/changes/**"
+      - ".cowork-flow/plans/**"
+      - "README.md"
+      - "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:
+    agent_type: default
+    capabilities:
+      - code-quality-review
+      - test-review
+      - verification
+    preferred_task_types:
+      - review
+      - verification
+    file_patterns:
+      - "src/**"
+      - "template/**"
+      - "tests/**"
+      - "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:
+    agent_type: worker
+    capabilities:
+      - documentation
+      - workflow-writing
+    preferred_task_types:
+      - docs
+      - documentation
+    file_patterns:
+      - "README.md"
+      - "AGENTS.md"
+      - ".cowork-flow/**/*.md"
+      - ".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/agent-team/policy.yaml

@@ -0,0 +1,23 @@
+# Agent Team Policy
+
+parallel:
+  allow_parallel_batches: true
+  disallow_file_write_conflicts: true
+  require_coordinator_review: true
+
+reviews:
+  require_spec_review: true
+  require_quality_review: true
+  chain:
+    - implementer
+    - spec-reviewer
+    - quality-reviewer
+
+retry:
+  max_attempts: 3
+  retry_on:
+    - needs_context
+    - failed_verification
+    - review_rejected
+    - adapter_failed
+  escalation: needs-coordinator-decision

package/template/.cowork-flow/config.yaml

@@ -14,6 +14,15 @@ session_commit_message: "chore: record journal"
 # Maximum lines per journal file before rotating to a new one
 max_journal_lines: 2000
 
+#-------------------------------------------------------------------------------
+# Agent Team Runtime
+#-------------------------------------------------------------------------------
+
+# Disabled by default. Set to true before using agent-team runtime commands such
+# as prepare/status/next/record-result/record-review/retry/complete.
+agent_team:
+  enabled: false
+
 #-------------------------------------------------------------------------------
 # Task Lifecycle Hooks
 #-------------------------------------------------------------------------------

package/template/.cowork-flow/run

@@ -3,29 +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
-
-解释器选择顺序：
-  COWORK_FLOW_PYTHON -> PYTHON -> python3 -> python -> py -3
-EOF
-}
+RUNNER_SCRIPT="$WORKFLOW_DIR/scripts/run.py"
 
 candidate_is_valid() {
   candidate_cmd=$1
@@ -50,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
 }
 
@@ -85,78 +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" "$@"
-    ;;
-  *)
-    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" "$@"