self-replicating-agent-tdd

Files (1)

• SKILL.md

SKILL.md (first lines)

# TDD-PDCA: Self-Replicating Branching Agent for {{AGENT_NAME}}

## Goal
{{AGENT_NAME}} (단일 에이전트)이 복잡한 문제를 감지 → 스스로 서브에이전트를 분기 (branch) → 병렬 추론 → 결과를 부모가 수렴 → 최종 응답 형성.

---

## 현재 상태 (Baseline) — Updated 2026-05-10

Phase 1 (COMPLETE): SelfBranchDecider class with 17 passing tests.
Phase 2 (COMPLETE): Integrated into run_agent.py loop.
Phase 3 (COMPLETE): Structural bugs fixed + integration tests written. 23 tests passing.

### PDCA Progress

| Phase | Goal | Status |
|---|---|---|
| Phase 1 | score_complexity + should_branch + plan_branches + integrate_results | COMPLETE |
| Phase 2 | Hook into run_agent.py _execute_tool_calls_concurrent at api_call_count==1 | COMPLETE |
| Phase 3 | Fix structural bugs (tool_name, _already_branching, decider caching) + integration tests | COMPLETE |
| Phase 4 | End-to-end test + CLI indicator + child agent propagation | COMPLETE |

### Phase 3 — Bug Fixes (COMPLETE)

| # | Bug | Location | Fix |
|---|---|---|---|
| 1 | `tool_name` missing from tool result messages (sequential) | `run_agent.py:7719` | Added `tool_name` to `tool_msg` dict |
| 2 | `tool_name` missing from concurrent path interrupt skip | `run_agent.py:7003` | Added `tool_name` to interrupt skip_msg |
| 3 | `_already_branching` check-only (never set) | `run_agent.py:7289` | Added `self._already_branching = True` before execute |
| 4 | `SelfBranchDecider` recreated every call | `run_agent.py:7839` | Cached as `self._branch_decider` |
| 5 | `original_user_message` not passed in concurrent path | `run_agent.py:6877` | Added to `_execute_tool_calls()` signature and all call sites |

### Phase 4 — Integration (COMPLETE)

| # | Item | Location |
|---|---|---|
| A | CLI visual indicator on branching | `run_agent.py:7291-7293` — `⚡ Self-branch triggered` message |
| B | `_already_branching` propagates to child agents | `delegate_tool.py:322` — `child._already_branching = getattr(parent_agent, '_already_branching', False)` |

**Integration Tests (9 in `TestSelfBranchIntegration`):**
- `test_execute_tool_calls_sets_tool_name_in_result_messages` — sequential path tool_msg includes tool_name
- `test_should_self_branch_false_on_no_conjunction` — conjunction gate blocks simple messages
- `test_should_self_branch_false_on_simple_message` — no conjunction → no branch
- `test_should_self_branch_true_with_conjunction_and_complex_messages` — passes when both conditions met
- `test_should_self_branch_false_when_already_branching` — `_already_branching` flag blocks re-entry
- `test_should_self_branch_false_on_child_agent` — `_delegate_depth > 0` blocks branching in children
- `test_execute_self_branch_calls_decider_execute_branching` — cached decider receives correct args
- `test_decider_cached_on_agent_instance` — conjunction pass → cache set
- `test_branch_response_returned_with_branched_flag` — branching result string returned

**Test Results**: 236 passed, 7 failed (pre-existing, all Azure/max_tokens related)

### Phase 1 — Test Results (17 PASS)
- test_score_returns_float_between_0_and_1
- test_simple_question_low_score
- test_complex_debugging_high_score
- test_tool_diversity_increases_score
- test_should_branch_fires_on_complex_task
- test_should_branch_false_on_simple_task
- test_child_agent_never_branches
- test_double_branch_prevented
- test_debug_score_shows_breakdown
- test_plan_branches_returns_list
- test_plan_branches_single_task
- test_plan_branches_max_concurrent
- test_plan_branches_includes_context
- test_integrate_results_returns_string
- test_integrate_results_contains_summaries
- test_integrate_results_failed_branch_warning
- test_integrate_results_all_failed_returns_error

### Phase 2 — Changes to run_agent.py

1. `_execute_tool_calls_concurrent()` signature: added `original_user_message=""` parameter
2. Self-branch check after tool execution (line ~7276): `if api_call_count == 1 and self._should_self_branch(messages, original_user_message)`
3. New methods on AIAgent (line ~7796): `_should_self_branch()`, `_execute_self_branch()`

### Key Design Decisions

**Conjunction Gate**: Only branch when goal contains natural conjunction (" and ", " and also ", " + ", "그리고", " 또한 ", "且", "並且", "同时"). Prevents branching on every complex single task.

**Complexity Score Components (0.0 to 1.0)**:
| Component | Weight | Notes |
|---|---|---|
| tool_diversity | 0.30 | unique tools / total calls |
| tool_call_count | 0.30 | calls / 15 |
| turn_count | 0.20 | assistant turns / 8 |
| reasoning_ratio | 0.10 | thinking blocks present |
| context_compression | 0.10 | bonus if > 30 messages |

Threshold: 0.30

**Tool Name Extraction — CRITICAL FIX**: Must extract from BOTH `assistant.tool_calls[].function.name` (OpenAI format) AND `tool` role messages with `tool_name` field ({{AGENT_NAME}} format).

**Trigger**: api_call_count == 1 — after FIRST tool-call turn completes.

### Pitfalls Found and Fixed

1. tool_names NOT extracted from tool role messages ({{AGENT_NAME}} uses `{"role": "tool", "tool_name": "..."}`)
2. COMPLEXITY_THRESHOLD was 0.45 — complex debugging only scored 0.36. Lowered to 0.30.
3. Duplicate function definition left by patch tool — removed stale first def.
4. original_user_message not available in concurrent execution path — added as parameter.

### Files Created/Modified

- CREATED: `agent/self_brancher.py` — SelfBranchDecider class
- CREATED: `tests/agent/test_self_brancher.py` — 17 tests
- MODIFIED: `run_agent.py` — integration hooks + new methods

### 이미 존재하는 것
- `delegate_task` (tools/delegate_tool.py) — 병렬 서브에이전트 spawn (MAX_CONCURRENT=3, MAX_DEPTH=2)
- `_active_children` interrupt 전파 (run_agent.py)
- `MemoryManager.on_delegation()` — 자식 완료 후 메모리 동기화 hook
- `SessionDB` parent_session_id 체인 추적
- `ContextCompressor` — iterative summarization
- `_budget_caution_threshold=0.7`, `_budget_warning_threshold=0.9` — pressure injection
- `smart_model_routing` — cheap/strong model routing
- `credential_pool` — same-provider credential sharing

From humanerd-drew/opencode-drewgent, MIT.

More from humanerd-drew/opencode-drewgent