execution-manager

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

执行管理器

Execution Manager

所有者: 仅主协调器
Owner: Main Coordinator Only

职责

Responsibilities

  1. 读取 meta.yaml 获取所有待执行部分
  2. 为每个部分创建 git worktree
  3. 为每个 worktree 生成 tmux 会话
  4. 在每个会话中初始化子协调器,传递:
    • section_path(部分目录路径,如
      docs/prds/reddit-bot/sections/auth
    • 分支名称
    • 工作空间路径
  5. 生成后立即更新 meta.yaml 中的部分状态
  6. 监控完成信号
  7. 完成/失败时清理
  1. Read meta.yaml to get all sections to be executed
  2. Create git worktree for each section
  3. Generate tmux session for each worktree
  4. Initialize sub-coordinator in each session, passing:
    • section_path (directory path of the section, e.g.
      docs/prds/reddit-bot/sections/auth
      )
    • branch name
    • workspace path
  5. Update section status in meta.yaml immediately after generation
  6. Monitor completion signals
  7. Clean up upon completion/failure

重要约束

Important Constraints

主协调器代码修复规则:
当需要修复主协调器(当前 agent 所在环境)中的代码时,必须先询问人工
主协调器的职责范围:
  • ✅ 协调和生成 tmux 会话
  • ✅ 管理 git worktree
  • ✅ 检查各部分进度
  • ✅ 简洁地调用 skills
  • ❌ 不应思考具体执行计划
  • ❌ 不应直接修改业务代码
所有具体的执行计划和代码实现应由子协调器在各自的 tmux 会话中完成。
Main Coordinator Code Fix Rules:
When code fixes are needed in the main coordinator (the environment where the current agent resides), must ask a human first.
Scope of main coordinator responsibilities:
  • ✅ Coordinate and generate tmux sessions
  • ✅ Manage git worktrees
  • ✅ Check progress of each section
  • ✅ Call skills concisely
  • ❌ Should not think about specific execution plans
  • ❌ Should not directly modify business code
All specific execution plans and code implementations should be completed by sub-coordinators in their respective tmux sessions.

生成模式

Generation Mode

bash
undefined
bash
undefined

读取 meta.yaml 获取项目信息

读取 meta.yaml 获取项目信息

project_name=$(yq '.project' meta.yaml) sections=$(yq '.sections | keys' meta.yaml)
project_name=$(yq '.project' meta.yaml) sections=$(yq '.sections | keys' meta.yaml)

对每个部分:

对每个部分:

for section in $sections; do branch="${project_name}/${section}" section_path="docs/prds/${project_name}/sections/${section}"

创建 worktree

git worktree add ../worktrees/${section} -b ${branch}

创建 tmux 会话并初始化子协调器

tmux new-session -d -s ${section} -c ../worktrees/${section}
claude "You are Sub Coordinator for ${section}. Read fix-engine skill. Task files in .task/ directory. Begin."

更新 meta.yaml 状态

yq -i ".sections.${section}.status = "in_progress"" meta.yaml done
undefined
for section in $sections; do branch="${project_name}/${section}" section_path="docs/prds/${project_name}/sections/${section}"

创建 worktree

git worktree add ../worktrees/${section} -b ${branch}

创建 tmux 会话并初始化子协调器

tmux new-session -d -s ${section} -c ../worktrees/${section}
claude "You are Sub Coordinator for ${section}. Read fix-engine skill. Task files in .task/ directory. Begin."

更新 meta.yaml 状态

yq -i ".sections.${section}.status = "in_progress"" meta.yaml done
undefined

强制 Worktree 规则

Mandatory Worktree Rules

所有部分必须在各自的 worktree 中执行,无例外。
生成前验证:
  1. 验证 worktree 存在:
    git worktree list | grep {section-id}
  2. 验证 tmux 会话在 worktree 中运行:
    -c ../worktrees/{section-id}
  3. 永远不要在主仓库中为部分工作生成 Claude
All sections must be executed in their respective worktrees, no exceptions.
Pre-generation verification:
  1. Verify worktree exists:
    git worktree list | grep {section-id}
  2. Verify tmux session is running in worktree:
    -c ../worktrees/{section-id}
  3. Never generate Claude for section work in the main repository

监控循环 (REQUIRED)

Monitoring Loop (REQUIRED)

生成所有会话后,必须继续监控。不要交给人工处理。
bash
undefined
After generating all sessions, must continue monitoring. Do not hand over to humans.
bash
undefined

监控状态变量

监控状态变量

all_done=false check_interval=30 # 秒
while [ "$all_done" = false ]; do echo "检查所有部分状态..."
completed_count=0 blocked_count=0 in_progress_count=0 total_sections=$(yq '.sections | length' meta.yaml)

检查每个部分的状态

for section in $(yq '.sections | keys | .[]' meta.yaml); do status=$(yq ".sections.${section}.status" meta.yaml)
case "$status" in
  completed)
    ((completed_count++))
    echo "✅ $section: COMPLETE"
    ;;
  blocked)
    ((blocked_count++))
    echo "❌ $section: BLOCKED"
    ;;
  in_progress)
    ((in_progress_count++))
    # 检查 tmux 会话是否还在运行
    if ! tmux has-session -t "$section" 2>/dev/null; then
      echo "⚠️ $section: tmux 会话异常退出"
      yq -i ".sections.${section}.status = \"blocked\"" meta.yaml
    else
      # 检查最近输出
      last_output=$(tmux capture-pane -t "$section" -p | tail -20)
      echo "🔄 $section: WORKING"
    fi
    ;;
esac
done

检查是否所有部分都完成或阻塞

if [ $((completed_count + blocked_count)) -eq $total_sections ]; then all_done=true echo "" echo "所有部分已完成或阻塞,准备合并..." echo "- 已完成: $completed_count" echo "- 已阻塞: $blocked_count" echo ""
# 自动调用 merge-resolver
if [ $completed_count -gt 0 ]; then
  echo "调用 merge-resolver 处理已完成的部分..."
  # 这里 Claude 会调用 merge-resolver skill
  # 人工只需在 merge-resolver 完成后看到最终报告
else
  echo "没有已完成的部分可以合并"
  echo "所有部分都被阻塞,需要人工干预"
fi
else echo "" echo "状态摘要: $completed_count 完成, $in_progress_count 进行中, $blocked_count 阻塞" echo "等待 ${check_interval} 秒后再次检查..." sleep $check_interval fi done
undefined
all_done=false check_interval=30 # 秒
while [ "$all_done" = false ]; do echo "检查所有部分状态..."
completed_count=0 blocked_count=0 in_progress_count=0 total_sections=$(yq '.sections | length' meta.yaml)

检查每个部分的状态

for section in $(yq '.sections | keys | .[]' meta.yaml); do status=$(yq ".sections.${section}.status" meta.yaml)
case "$status" in
  completed)
    ((completed_count++))
    echo "✅ $section: COMPLETE"
    ;;
  blocked)
    ((blocked_count++))
    echo "❌ $section: BLOCKED"
    ;;
  in_progress)
    ((in_progress_count++))
    # 检查 tmux 会话是否还在运行
    if ! tmux has-session -t "$section" 2>/dev/null; then
      echo "⚠️ $section: tmux 会话异常退出"
      yq -i ".sections.${section}.status = \"blocked\"" meta.yaml
    else
      # 检查最近输出
      last_output=$(tmux capture-pane -t "$section" -p | tail -20)
      echo "🔄 $section: WORKING"
    fi
    ;;
esac
done

检查是否所有部分都完成或阻塞

if [ $((completed_count + blocked_count)) -eq $total_sections ]; then all_done=true echo "" echo "所有部分已完成或阻塞,准备合并..." echo "- 已完成: $completed_count" echo "- 已阻塞: $blocked_count" echo ""
# 自动调用 merge-resolver
if [ $completed_count -gt 0 ]; then
  echo "调用 merge-resolver 处理已完成的部分..."
  # 这里 Claude 会调用 merge-resolver skill
  # 人工只需在 merge-resolver 完成后看到最终报告
else
  echo "没有已完成的部分可以合并"
  echo "所有部分都被阻塞,需要人工干预"
fi
else echo "" echo "状态摘要: $completed_count 完成, $in_progress_count 进行中, $blocked_count 阻塞" echo "等待 ${check_interval} 秒后再次检查..." sleep $check_interval fi done
undefined

监控期间的响应策略

Response Strategy During Monitoring

每 30-60 秒检查每个会话:
  1. WORKING → 继续监控
  2. COMPLETE → 更新 meta.yaml,继续监控其他部分
  3. STUCK → 读取 error-report.md,决定:
    • 通过
      tmux send-keys
      提供额外上下文
    • 或升级到人工(标记为 blocked)
  4. 5分钟以上无输出 → 检查是否卡住,发送提示:
    bash
    tmux send-keys -t {section-id} "状态更新?" Enter
对问题做出反应:
  • 如果 tmux 需要任何权限或询问,通常只需同意并指向正确的选择
  • 如果需要外部信息 → 获取并注入:
    bash
    tmux send-keys -t {section-id} "额外上下文:..." Enter
仅在以下情况停止监控:
  • 所有部分 COMPLETE 或 BLOCKED → 调用 merge-resolver
  • merge-resolver 完成 → 向人工报告最终摘要
  • 多个部分出现致命错误 → 升级并提供完整报告
不要只是生成后就离开。你负责监控循环直到所有部分完成并调用 merge-resolver。
Check each session every 30-60 seconds:
  1. WORKING → Continue monitoring
  2. COMPLETE → Update meta.yaml, continue monitoring other sections
  3. STUCK → Read error-report.md, decide:
    • Provide additional context via
      tmux send-keys
    • Or escalate to human (mark as blocked)
  4. No output for more than 5 minutes → Check if stuck, send prompt:
    bash
    tmux send-keys -t {section-id} "状态更新?" Enter
Respond to issues:
  • If tmux requires any permissions or prompts, generally just agree and point to the correct option
  • If external information is needed → Obtain and inject:
    bash
    tmux send-keys -t {section-id} "额外上下文:..." Enter
Stop monitoring only if:
  • All sections are COMPLETE or BLOCKED → Call merge-resolver
  • merge-resolver completes → Report final summary to human
  • Fatal errors occur in multiple sections → Escalate and provide full report
Do not just leave after generation. You are responsible for the monitoring loop until all sections are completed and merge-resolver is called.

完成触发器

Completion Trigger

当监控循环检测到所有部分都是
completed
blocked
状态时:
  1. 如果有任何 blocked 部分:
    • 报告阻塞的部分给人工
    • 询问:"是否继续合并已完成的部分? (y/n)"
    • 如果 30 秒内无响应,默认为 YES
  2. 调用 merge-resolver:
    • 传递所有
      completed
      部分的列表
    • merge-resolver 会处理合并、冲突解决、测试和报告
  3. merge-resolver 返回后:
    • 如果所有合并成功且测试通过 → 报告成功
    • 如果有冲突 → 报告冲突文件和解决步骤
    • 如果测试失败 → 报告失败原因
  4. 只有在 merge-resolver 完成后才返回控制权给人工
When the monitoring loop detects that all sections are in
completed
or
blocked
status:
  1. If there are any blocked sections:
    • Report blocked sections to human
    • Ask: "Proceed with merging completed sections? (y/n)"
    • If no response within 30 seconds, default to YES
  2. Call merge-resolver:
    • Pass list of all
      completed
      sections
    • merge-resolver will handle merging, conflict resolution, testing and reporting
  3. After merge-resolver returns:
    • If all merges succeed and tests pass → Report success
    • If there are conflicts → Report conflict files and resolution steps
    • If tests fail → Report failure reasons
  4. Only return control to human after merge-resolver completes

永不提前退出原则

Never Exit Early Principle

execution-manager 的职责是完整的端到端执行管理:
  • ✅ 生成所有 tmux 会话
  • ✅ 监控所有部分直到完成
  • ✅ 自动调用 merge-resolver
  • ✅ 等待 merge-resolver 完成
  • ✅ 向人工报告最终结果
不要:
  • ❌ 生成会话后就返回
  • ❌ 部分完成时就返回
  • ❌ 让人工手动触发合并
  • ❌ 在 merge-resolver 运行时返回
人工只应看到:
  1. 初始 PRD 输入
  2. 最终执行报告(成功或需要处理的冲突)
The execution-manager is responsible for full end-to-end execution management:
  • ✅ Generate all tmux sessions
  • ✅ Monitor all sections until completion
  • ✅ Automatically call merge-resolver
  • ✅ Wait for merge-resolver to complete
  • ✅ Report final results to human
Do NOT:
  • ❌ Return immediately after generating sessions
  • ❌ Return when partially completed
  • ❌ Let human manually trigger merging
  • ❌ Return while merge-resolver is running
Humans should only see:
  1. Initial PRD input
  2. Final execution report (success or conflicts requiring handling)

监控状态说明

Monitoring Status Description

定期检查 meta.yaml 中各部分的状态:
  • completed
    - 部分完成,等待所有部分完成后触发 merge-resolver
  • blocked
    - 已升级到人工,暂停该部分
  • in_progress
    - 继续监控
同时监控 tmux 会话是否异常退出。
Regularly check the status of each section in meta.yaml:
  • completed
    - Section completed, wait for all sections to complete before triggering merge-resolver
  • blocked
    - Escalated to human, pause this section
  • in_progress
    - Continue monitoring
Also monitor if tmux sessions exit abnormally.

清理

Cleanup

bash
tmux kill-session -t {section-id}
git worktree remove ../worktrees/{section-id}
git branch -d {section-id}  # 仅在合并后
bash
tmux kill-session -t {section-id}
git worktree remove ../worktrees/{section-id}
git branch -d {section-id}  # 仅在合并后

主协调器必备命令

Essential Commands for Main Coordinator

tmux 会话管理

tmux Session Management

bash
undefined
bash
undefined

列出所有工作会话

列出所有工作会话

tmux ls
tmux ls

查看工作输出(最后50行,非阻塞)

查看工作输出(最后50行,非阻塞)

tmux capture-pane -t {section-id} -p | tail -50
tmux capture-pane -t {section-id} -p | tail -50

向工作会话发送后续指令

向工作会话发送后续指令

tmux send-keys -t {section-id} "Also handle edge case X" Enter
tmux send-keys -t {section-id} "Also handle edge case X" Enter

附加到会话实时观察(Ctrl+B D 分离)

附加到会话实时观察(Ctrl+B D 分离)

tmux attach -t {section-id}
tmux attach -t {section-id}

终止卡住的工作会话

终止卡住的工作会话

tmux kill-session -t {section-id}
undefined
tmux kill-session -t {section-id}
undefined

git worktree 管理

git worktree Management

bash
undefined
bash
undefined

创建带新分支的 worktree

创建带新分支的 worktree

git worktree add ../worktrees/{section-id} -b {section-id}
git worktree add ../worktrees/{section-id} -b {section-id}

列出所有 worktrees

列出所有 worktrees

git worktree list
git worktree list

删除 worktree(合并后)

删除 worktree(合并后)

git worktree remove ../worktrees/{section-id}
git worktree remove ../worktrees/{section-id}

清理过期的 worktree 引用

清理过期的 worktree 引用

git worktree prune
git worktree prune

从主分支合并完成的部分

从主分支合并完成的部分

git merge {section-id} --no-ff -m "Merge {section-id}"
undefined
git merge {section-id} --no-ff -m "Merge {section-id}"
undefined