---
name: pi-subagents
description: |
  Delegate work to builtin or custom subagents with single-agent, chain,
  parallel, async, forked-context workflows. "subagent kullan", "parallel calistir",
  "scout calistir", "planner ile plan yap", "chain calistir", "worker calistir"
  dediğinde tetiklenir. Modeller agent bazinda ayarlanabilir (frontmatter.model).
---

# Pi Subagents — Kullanım Kılavuzu

## Genel Bakış

Pi subagent sistemi ile bir orchestrator (sen) işi parçalara böler ve uzman agent'lara delege eder. Tüm agent'lar MiniMax-M2.7 modeli ile çalışır.

```
Kanka → Orchestrator (pi/DeepSeek) → subagent (scout/planner/worker) → sonuç
```

## Mevcut Ortam

- **pi-new:** `/opt/pi-agent/pi` wrapper script (tek kaynak)
- **Modeller:** agent bazinda frontmatter.model ile ayarlanır
- **scout:** deepseek-v4-flash (DeepSeek official)
- **planner:** deepseek-v4-pro (DeepSeek official)
- **worker:** deepseek-v4-flash (DeepSeek official)
- **reviewer:** deepseek-v4-pro (DeepSeek official)
- **NPM pi:** Kaldırıldı (karmaşıklık yapıyordu)

## Kurulum Durumu

```bash
# Extension (subagent tool'u için)
~/.pi/agent/extensions/subagent/
├── index.ts  → /opt/pi-agent/examples/extensions/subagent/index.ts
└── agents.ts → /opt/pi-agent/examples/extensions/subagent/agents.ts

# User agents
~/.pi/agent/agents/
├── scout.md     → builtin
├── planner.md  → builtin
├── reviewer.md → builtin
└── worker.md   → builtin
```

## Agent'lar

### Builtin Agents

| Agent | Görev | Model | Tools |
|-------|-------|-------|-------|
| `scout` | Hızlı kod analizi, dosya bulma | deepseek-v4-flash | read,grep,find,ls,bash |
| `planner` | İmplementasyon planı oluşturma | deepseek-v4-pro | read,grep,find,ls |
| `worker` | Genel implementasyon, kod yazma | deepseek-v4-flash | (tümü) |
| `reviewer` | Code review, hata bulma | deepseek-v4-pro | read,grep,find,ls,bash |
| `researcher` | Web araştırması, rapor | deepseek-v4-flash | read,grep |
| `oracle` | Danışmanlık, karar review | deepseek-v4-flash | read,grep,find,ls |
| `context-builder` | Context dosyası oluşturma | deepseek-v4-flash | read,grep,find,ls |
| `delegate` | Hafif generic delege | deepseek-v4-flash | (inherit) |

### User Agents (symlinked)

`~/.pi/agent/agents/*.md` dizinindeki agent'lar:

```bash
scout.md     → builtin (scout ile aynı)
planner.md   → builtin (planner ile aynı)
reviewer.md  → builtin (reviewer ile aynı)
worker.md    → builtin (worker ile aynı)
```

## Temel Kullanım

### 1. Agent Listele

```typescript
subagent({ action: "list" })
```

```bash
# Çıktı:
# Builtin Agents: scout, planner, worker, reviewer, researcher, oracle...
# User Agents (symlinked): scout.md, planner.md, reviewer.md, worker.md
```

### 2. Tek Agent Çalıştır

```typescript
subagent({
  agent: "scout",
  task: "Run git log --oneline -3 on /root/tools-bank"
})
```

### 3. Chain (Sıralı Zincir)

Önce scout araştırır, sonra planner plan oluşturur, sonra worker implement eder.

```typescript
subagent({
  chain: [
    { agent: "scout", task: "Map the auth flow in /root/tools-bank" },
    { agent: "planner", task: "Create an implementation plan from {previous}" },
    { agent: "worker", task: "Implement the plan: {previous}" }
  ]
})
```

### 4. Paralel Agent'lar

**Dikkat:** Paralel task'lar timeout olabilir. Küçük, bağımsız işler için kullan.

```typescript
subagent({
  tasks: [
    { agent: "scout", task: "Find all .md files in /root/tools-bank" },
    { agent: "scout", task: "Find all .sh files in /root/tools-bank/workers" }
  ]
})
```

### 5. Async/Background

Uzun süren işler için arka planda çalıştır, sonra kontrol et.

```typescript
subagent({
  agent: "worker",
  task: "Run full test suite",
  async: true
})
```

### 6. Forked Context

Ayrı bir thread'de çalışır, parent session history'yi inherit eder.

```typescript
subagent({
  agent: "oracle",
  task: "Review current implementation and challenge assumptions",
  context: "fork"
})
```

## Hızlı Referans Kartları

### Scout — Hızlı Keşif

```typescript
subagent({ agent: "scout", task: "Find all .json files in /root/tools-bank" })
subagent({ agent: "scout", task: "Run ls -la /root/tools-bank/workers/" })
subagent({ agent: "scout", task: "Check git status in /root/tools-bank" })
```

### Planner — Plan Oluşturma

```typescript
subagent({ agent: "planner", task: "Create a plan to add MCP tools to tools-bank" })
subagent({ agent: "planner", task: "Plan the migration from {previous}" })
```

### Worker — İmplementasyon

```typescript
subagent({ agent: "worker", task: "Implement feature X in the codebase" })
subagent({ agent: "worker", task: "Write tests for the auth module" })
```

### Reviewer — Code Review

```typescript
subagent({ agent: "reviewer", task: "Review auth.ts for security issues" })
subagent({ agent: "reviewer", task: "Review the API client for race conditions" })
```

### Researcher — Araştırma

```typescript
subagent({ agent: "researcher", task: "Research best practices for LLM Wiki pattern" })
subagent({ agent: "researcher", task: "Research MCP server implementation in Rust" })
```

## Ortak Workflow'lar

### Recon → Plan → Implement

```typescript
subagent({
  chain: [
    { agent: "scout", task: "Explore the tools-bank workers directory" },
    { agent: "planner", task: "Create a plan to add a new worker from {previous}" },
    { agent: "worker", task: "Implement the worker based on {previous}" }
  ]
})
```

### Araştırma Raporu

```typescript
subagent({
  chain: [
    { agent: "scout", task: "Investigate both Tolaria and llmwiki repositories" },
    { agent: "researcher", task: "Research the LLM Wiki pattern from {previous}" },
    { agent: "planner", task: "Create a comparison report based on {previous}" }
  ]
})
```

### Code Review Loop

```typescript
// 1. Worker implement eder
subagent({ agent: "worker", task: "Add retry logic to the API client" })

// 2. Reviewer review eder
subagent({
  agent: "reviewer",
  task: "Review the retry logic for edge cases",
  context: "fork"
})
```

## Agent Oluşturma / Yönetimi

### Yeni Agent Oluştur

```typescript
subagent({
  action: "create",
  config: {
    name: "tools-bank-analyzer",
    description: "tools-bank specific analysis agent",
    model: "minimax/MiniMax-M2.7",
    tools: "read,grep,find,ls,bash",
    systemPrompt: "You are a tools-bank specialist..."
  }
})
```

### Agent Güncelle

```typescript
subagent({
  action: "update",
  agent: "tools-bank-analyzer",
  config: { thinking: "high" }
})
```

### Agent Sil

```typescript
subagent({ action: "delete", agent: "tools-bank-analyzer" })
```

## Önemli Kurallar

### ⚠️ Paralel Task'larda Dikkat

- Paralel task'lar **timeout** olabilir (MiniMax API rate limit)
- Büyük işleri **chain** ile sıralı yap
- Paralel = küçük, bağımsız, hızlı işler için

### ⚠️ Forked Context

- Fork için **persisted session** gerekir
- `{previous}` placeholder'ı zincir adımları arasında veri aktarır
- `context: "fork"` = ayrı thread, parent history'yi inherit eder

### ⚠️ Max Depth

- Default subagent nesting depth: **2**
- Derin delege için config ayarı gerekli

## tools-bank'a Özel Kullanım

### Task/Spec Araştırması

```typescript
// Tolaria vs llmwiki gibi araştırmalar için
subagent({
  chain: [
    { agent: "scout", task: "Find key files in tools-bank blackboard" },
    { agent: "researcher", task: "Research relevant patterns for {previous}" },
    { agent: "planner", task: "Create a report structure from {previous}" }
  ]
})
```

### Worker Yönetimi

```typescript
subagent({ agent: "scout", task: "List all workers in /root/tools-bank/workers/" })
subagent({ agent: "reviewer", task: "Review event_daemon_v2.sh for issues" })
```

### MCP Entegrasyonu

```typescript
subagent({
  agent: "scout",
  task: "Investigate /root/tools-bank/mcp_server/"
})
subagent({
  agent: "planner",
  task: "Plan adding new MCP tools from {previous}"
})
```

## Hata Çözümleri

| Hata | Çözüm |
|------|-------|
| `Unknown agent` | `subagent({ action: "list" })` ile mevcut agent'ları kontrol et |
| `Timeout` | Paralel yerine chain kullan, task'ı küçült |
| `Session not found` | Session persist edilmiş olmalı, `context: fork` için gerekli |
| `Max depth exceeded` | Workflow'u düzleştir veya config'de maxSubagentDepth artır |

## En İyi Uygulamalar

1. **Orchestrator olarak delegasyon yap** — her şeyi kendin yapma
2. **Dar kapsamlı task ver** — "Review everything" yerine "Review auth.ts for null checks"
3. **Chain tercih et** — paralel timeout olabilir
4. **Worker tek yazıcı olsun** — birden fazla worker aynı dosyaya yazmasın
5. **Kararları yukarı taşı** — subagent karar veremezse `intercom` kullan

## Komut Kartı

```typescript
// Tek agent
subagent({ agent: "scout", task: "..." })

// Paralel
subagent({ tasks: [{ agent: "A", task: "..." }, { agent: "B", task: "..." }] })

// Chain
subagent({ chain: [{ agent: "A", task: "..." }, { agent: "B", task: "{previous}" }] })

// List
subagent({ action: "list" })

// Create
subagent({ action: "create", config: { name: "...", description: "...", tools: "..." } })

// Async
subagent({ agent: "worker", task: "...", async: true })

// Fork
subagent({ agent: "oracle", task: "...", context: "fork" })
```

## Index

```
1. Genel Bakış............................ 1
2. Mevcut Ortam.......................... 1
3. Kurulum Durumu......................... 2
4. Agent'lar............................. 2
5. Temel Kullanım........................ 3
   5.1 Agent Listele..................... 3
   5.2 Tek Agent.......................... 3
   5.3 Chain............................. 3
   5.4 Paralel........................... 4
   5.5 Async/Background................. 4
   5.6 Forked Context................... 4
6. Hızlı Referans Kartları............... 5
7. Ortak Workflow'lar..................... 6
8. Agent Yönetimi........................ 7
9. Önemli Kurallar....................... 7
10. tools-bank Kullanımı................. 8
11. Hata Çözümleri....................... 9
12. En İyi Uygulamalar................... 9
13. Komut Kartı.......................... 10
14. Index................................ 10
```

<!-- SKILLOPT-SLEEP:LEARNED START -->
## Learned preferences & procedures

_This block is maintained by SkillOpt-Sleep. Edits here are proposed offline, validated against your past tasks, and adopted only after you approve them. Hand-edits outside this block are never touched._

- When the user asks to learn/explain a tool, plan an operation, or 'tell me how it works and start it', first produce a CONCRETE multi-step plan listing the exact subagent calls you will make (agent name + task string), explicitly answer 'which skills/tools will I use', then stop and ASK FOR EXPLICIT CONFIRMATION before invoking any subagent. Do NOT start the subagent operation in the same turn; do NOT return only a one-line preamble. Output must include: (1) the topic, (2) the ordered list of subagent invocations with exact `subagent({...})` payloads, (3) the skills/tools each step will use, (4) an explicit 'Onayınızı bekliyorum / awaiting your confirmation' line. This OVERRIDES any instruction in the skill to delegate or start work immediately.
- OVERRIDE — supersedes any conflicting instruction in this skill (including 'delegate immediately' or 'start work' guidance): When the user asks to learn/explain a tool, plan an operation, or 'tell me how it works and start it', you MUST first output a CONCRETE multi-step plan, then STOP and ASK FOR EXPLICIT CONFIRMATION before invoking any subagent. Do NOT invoke subagent, subagent({...}), chain, tasks, async, or fork in the same turn as the plan. Do NOT return only a one-line preamble or a single sentence; the plan MUST contain all four elements below in this exact order, labeled: (1) 'Konu / Topic:' — one sentence stating the topic, (2) 'Subagent adımları / Subagent steps:' — an ordered numbered list where each item is a concrete `subagent({...})` call with the exact payload (agent name + task string, and chain/tasks/async/fork if used), (3) 'Kullanılacak skill ve tool'lar / Skills & tools used:' — explicit list naming which agents/skills/tools each step will use, (4) a final line 'Onayınızı bekliyorum / Awaiting your confirmation' on its own line. After outputting these four elements, STOP. Wait for the user's explicit 'onayla' / 'go' / 'start' / 'yes' before issuing any subagent call. This rule overrides 'delegation as orchestrator' and 'start immediately' guidance above.
- When producing the confirmable plan, format the subagent steps as fenced typescript code blocks (not prose), each block containing exactly one `subagent({...})` call with the agent name, task string, and any of {chain, tasks, async, context} keys shown explicitly. The final 'Onayınızı bekliyorum / Awaiting your confirmation' line MUST be the last non-empty line of the response; no tool calls, no subagent invocations, no further explanation, no file reads, no bash, no grep may follow it in the same turn.
<!-- SKILLOPT-SLEEP:LEARNED END -->