agent execution with worktree

用途

该技能用于执行 Miyabi 的 Coding Agents，并通过 Git Worktree 隔离实现安全的并行处理，目标是实现无冲突的开发流程。它适用于运行 Agent、并行处理多个 Issue、执行特定 Agent、处理 Issue 以及管理并发任务等场景。

主要能力

• 支持 Miyabi 的 7 个 Coding Agents：CoordinatorAgent、CodeGenAgent、ReviewAgent、DeploymentAgent、PRAgent、IssueAgent、RefresherAgent。
• 定义各 Agent 的并行能力与依赖关系：
  • CoordinatorAgent：仅顺序执行，无依赖，负责任务分解、DAG 构建与分配。
  • CodeGenAgent：可并行，依赖 Coordinator，负责代码生成与实现。
  • ReviewAgent：可并行，依赖 CodeGen，负责质量审查与评分。
  • DeploymentAgent：条件执行，依赖 Review 通过，负责 CI/CD 部署。
  • PRAgent：条件执行，依赖 CodeGen，负责 PR 创建与合并。
  • IssueAgent：可并行，无依赖，负责 Issue 分析与标签推断。
  • RefresherAgent：后台执行，无依赖，负责状态监控。
• 明确安全与禁止的并行组合：
  • 安全并行：CodeGenAgent + ReviewAgent（不同 Issue）、CodeGenAgent + IssueAgent、IssueAgent + IssueAgent（不同 Issue）。
  • 禁止并行：两个 CoordinatorAgent、同一 Agent 处理同一 Issue（竞态条件）。
  • 条件执行：DeploymentAgent 需 ReviewAgent 质量检查通过后；PRAgent 需 CodeGenAgent 实现完成后。

使用方式

提供三种执行模式：

1. 单 Issue 处理（推荐经 CoordinatorAgent）： cargo run --bin miyabi -- agent run coordinator --issue 270 流程：Issue → Coordinator → CodeGen → Review → 判断是否通过 → 通过则创建 PR，不通过则回到 CodeGen。

2. 多 Issue 并行处理： cargo run --bin miyabi -- agent run coordinator --issues 270,271,272 --concurrency 3 流程：多个 Issue 经 Coordinator 分配到各自 Worktree，分别执行 CodeGen，最后合并。

3. 直接 Agent 执行（开发用）： cd crates/miyabi-agents cargo run --example codegen_agent -- --issue 270

Worktree 生命周期分为四个阶段：

• 阶段 1：创建 Worktree git worktree add .worktrees/issue-270 -b issue-270-feature
• 阶段 2：设置上下文，自动生成 .agent-context.json（机器可读）与 EXECUTION_CONTEXT.md（人类可读指示书）等文件。
• 阶段 3：执行 Agent，进入 Worktree 目录，Claude Code 读取 EXECUTION_CONTEXT.md，执行 Agent 专属工作流，并使用 Conventional Commits 提交。
• 阶段 4：合并与清理 git -C .worktrees/issue-270 push -u origin issue-270-feature gh pr create --title "feat: Issue #270" --draft git worktree remove .worktrees/issue-270 git branch -d issue-270-feature

适用场景

• 需要并行处理多个 Issue 的开发任务。
• 需要隔离不同 Agent 执行环境以避免冲突。
• 需要按依赖关系编排 Coordinator、CodeGen、Review、Deployment、PR 等 Agent 的工作流。
• 需要监控 Agent 状态或分析 Issue 标签。

限制与注意事项

• CoordinatorAgent 只能顺序执行，不可并行。
• 同一 Agent 不可并行处理同一 Issue，否则会产生竞态条件。
• DeploymentAgent 与 PRAgent 为条件执行，需满足前置条件。
• 文档提供了错误处理方式：Worktree 创建失败时可使用 git worktree list、git worktree prune 后重建；合并冲突时在 Worktree 内解决并提交；Agent 执行失败时可检查上下文文件并强制重跑： cargo run --bin miyabi -- agent run codegen --issue 270 --force
• 成功标准包括：Worktree 创建成功、Agent 分配符合任务类型、生成两个上下文文件、Claude 工作流完成、使用 Conventional Commits 提交、合并/PR 成功、Worktree 清理完成。
• 文档中提及的 Agent 专属配置（如 CodeGenAgent 并行度 3-5、超时 30 分钟、重试 2 次；ReviewAgent 并行度 2-3、评分阈值 80 分等）为建议值，实际使用需结合环境调整。
• 版本为 2.0.0，最后更新于 2025-11-22。