agent execution with worktree

🤖 Agent Execution with Worktree

Version: 2.0.0 Last Updated: 2025-11-22 Priority: ⭐⭐⭐⭐⭐ (P0 Level) Purpose: Parallel Processing via Miyabi Agent Execution and Worktree Isolation

---

📋 Overview

Process Miyabi's 7 Coding Agents with safe parallel execution through Git Worktree isolation. Achieve conflict-free development.

---

🎯 P0: Invocation Triggers

Trigger	Example
Agent Execution	"run coordinator agent on issue #270"
Parallel Processing	"process multiple issues in parallel"
Specific Agent	"execute codegen agent"
Issue Processing	"process issue #270"
Task Management	"managing concurrent tasks"

---

🔧 P1: Agent Classification and Execution Rules

Agent Priority Table

Agent	Symbol	Parallelizable	Dependencies	Purpose
🔴 CoordinatorAgent	Shikirun	❌ Sequential	None	Task decomposition, DAG construction, assignment
🟢 CodeGenAgent	Tsukuroun	✅ Parallel	Coordinator	Code generation, implementation
🟢 ReviewAgent	Medaman	✅ Parallel	CodeGen	Quality review, scoring
🟡 DeploymentAgent	Hakobun	⚠️ Conditional	Review pass	CI/CD deployment
🟡 PRAgent	Matomerun	⚠️ Conditional	CodeGen	PR creation, merging
🟢 IssueAgent	Mitsukerun	✅ Parallel	None	Issue analysis, label inference
🟡 RefresherAgent	Tsunagun	⚠️ Background	None	Status monitoring

Parallel Execution Rules

✅ 安全な並列実行:
- 🟢 CodeGenAgent + 🟢 ReviewAgent (異なるIssue)
- 🟢 CodeGenAgent + 🟢 IssueAgent
- 🟢 IssueAgent + 🟢 IssueAgent (異なるIssue)

❌ 禁止される並列実行:
- 🔴 CoordinatorAgent × 2 (Sequential only)
- 同じAgentで同じIssue (Race condition)

⚠️ 条件付き実行:
- 🟡 DeploymentAgent: ReviewAgent品質チェックpass後
- 🟡 PRAgent: CodeGenAgent実装完了後

---

🚀 P2: Patterns by Execution Method

Pattern 1: Single Issue Processing

# CoordinatorAgent経由（推奨）
cargo run --bin miyabi -- agent run coordinator --issue 270

Flow:

graph LR
    A[Issue #270] --> B[Coordinator]
    B --> C[CodeGen]
    C --> D[Review]
    D --> E{Pass?}
    E -->|Yes| F[PR作成]
    E -->|No| C

Pattern 2: Multiple Issue Parallel Processing

# 並列度指定
cargo run --bin miyabi -- agent run coordinator --issues 270,271,272 --concurrency 3

Flow:

graph TD
    A[Issues 270,271,272] --> B[Coordinator]
    B --> C1[Worktree #270]
    B --> C2[Worktree #271]
    B --> C3[Worktree #272]
    C1 --> D1[CodeGen]
    C2 --> D2[CodeGen]
    C3 --> D3[CodeGen]
    D1 --> E[Merge]
    D2 --> E
    D3 --> E

Pattern 3: Direct Agent Execution (for Development)

# 特定Agentの直接実行
cd crates/miyabi-agents
cargo run --example codegen_agent -- --issue 270

---

⚡ P3: Worktree Lifecycle

Phase 1: Worktree Creation

# 分離されたWorktree作成
git worktree add .worktrees/issue-270 -b issue-270-feature

Phase 2: Context Setup

Auto-generated for each Worktree:

.worktrees/issue-270/
├── .agent-context.json      # 機械可読コンテキスト
├── EXECUTION_CONTEXT.md     # 人間可読指示書
└── [Agent-specific files]

Phase 3: Agent Execution

cd .worktrees/issue-270
# Claude CodeがEXECUTION_CONTEXT.mdを読み込み
# Agent固有ワークフロー実行
# Conventional Commitsでコミット

Phase 4: Merge & Cleanup

# ブランチプッシュ
git -C .worktrees/issue-270 push -u origin issue-270-feature

# PR作成またはマージ
gh pr create --title "feat: Issue #270" --draft

# Worktree削除
git worktree remove .worktrees/issue-270
git branch -d issue-270-feature

---

📊 Optimal Settings by Agent

CodeGenAgent (Tsukuroun)

Setting	Value	Notes
Parallelism	3-5	CPU/memory dependent
Timeout	30 minutes	Adjust by complexity
Retry	2 times	On build error

Optimal Command:

tmux send-keys -t %2 "cd '.worktrees/issue-270' && あなたは「カエデ」です。以下を実行:

1. cargo build --release
2. cargo test --package miyabi-core
3. cargo clippy -- -D warnings

完了したら [カエデ] 実装完了 と発言。" Enter

ReviewAgent (Medaman)

Setting	Value	Notes
Parallelism	2-3	Maintain review quality
Score Threshold	80 points	Pass/Fail determination
Audit Items	5 items	Including security

Quality Score Criteria:

90-100点: quality:excellent
80-89点:  quality:good
70-79点:  quality:fair
<70点:    quality:needs-improvement (要修正)

---

🛡️ Error Handling

Worktree Creation Failure

# 既存Worktree確認
git worktree list

# 古いWorktree削除
git worktree prune

# 再作成
git worktree add .worktrees/issue-270 -b issue-270-feature

Merge Conflict

# Worktree内でコンフリクト解決
cd .worktrees/issue-270
git status
# [コンフリクト解決]
git add .
git commit -m "fix: resolve merge conflicts"

Agent Execution Failure

# コンテキスト確認
cat .worktrees/issue-270/.agent-context.json
cat .worktrees/issue-270/EXECUTION_CONTEXT.md

# 強制再実行
cargo run --bin miyabi -- agent run codegen --issue 270 --force

---

✅ Success Criteria

Check Item	Criteria
Worktree Creation	Success
Agent Assignment	Task type suitable
Context generation	2-file generation
Claude execution	Workflow complete
Commit	Conventional Commits
Merge/PR	Success
Cleanup	Worktree deletion complete

---

🔗 Related documentation

Documentation	Purpose
agents/specs/coding/*.md	Agent specification
agents/prompts/coding/*.md	Agent prompt
docs/WORKTREE_PROTOCOL.md	Worktree protocol
context/rust-tool-use-rules.md	MCP Tool optimization

---

📝 Related Skills

• Rust Development: Build before Agent execution
• Issue Analysis: Analysis before Agent assignment
• Git Workflow: Worktree branch management