# Agent Pooling Best Practices

> **Objective:** Minimize agent proliferation and token waste by reusing agents strategically.

## Problem Statement

**Observed issue:** Business-analyse sessions create 20-24 subagents, many of which are ultra-short (4-13 lines) for trivial tasks like summaries or consolidations.

**Impact:**
- Organizational overhead (tracking 24 agents)
- Token waste (spawning + context setup for each agent)
- Complexity in debugging and monitoring
- 1540+ lines of JSONL logs for a single session

**Goal:** Reduce to 5-7 agents per session while maintaining quality and parallelism.

---

## Agent Pooling Strategy

### Core Principle

> **Reuse agents for sequential operations, spawn new agents only for genuine parallelism.**

### When to Spawn a NEW Agent

✅ **Spawn new agent when:**
1. **Parallel operations** - Multiple independent tasks can run simultaneously
   - Example: Specifying 2+ modules in parallel (step-03)
   - Example: Reading multiple PRD files concurrently (step-05)

2. **Domain separation** - Task requires fundamentally different expertise
   - Example: ba-writer for JSON writes, Explore for codebase search
   - Example: MCP healthcheck vs. code generation

3. **Long-running tasks** - Task will take multiple turns and could block main flow
   - Example: Deep codebase exploration with 10+ searches
   - Example: Complex validation requiring many file reads

### When to REUSE Existing Agent

✅ **Reuse agent when:**
1. **Sequential operations** - Tasks depend on previous results
   - Example: Read module 1 → process → read module 2 → process
   - Example: Validate → fix → re-validate

2. **Same domain** - Task uses same tools and context as previous
   - Example: Multiple ba-writer calls in step-05 module loop
   - Example: Multiple ba-reader calls for different modules

3. **Short tasks** - Task will complete in 1-2 turns
   - Example: Generate summary (inline, not separate agent)
   - Example: Format output (inline, not separate agent)

4. **Consolidation** - Aggregating results from multiple sources
   - Example: Combine module summaries into master (inline)
   - Example: Build dependency graph from module data (inline)

---

## Anti-Patterns to Avoid

### ❌ Anti-Pattern 1: Ultra-Short Summary Agents

**Bad:**
```
FOR each module:
  Spawn agent "summarize-module-{i}"
  Agent reads module → generates 4-line summary → exits
```

**Result:** 5 agents created for 20 total lines of output

**Good:**
```
Main agent reads all modules sequentially
Generates summaries inline
Returns consolidated result
```

**Result:** 1 agent, same output, 80% fewer tokens

---

### ❌ Anti-Pattern 2: Spawning for Every Step Transition

**Bad:**
```
Step 03a: Spawn agent-data
  → Agent completes → exits
Step 03b: Spawn agent-ui
  → Agent completes → exits
Step 03c: Spawn agent-compile
  → Agent completes → exits
```

**Result:** 3 agents per module, 15 agents for 5 modules

**Good:**
```
Step 03: Spawn ONE agent-module-spec
  → Agent executes 03a → 03b → 03c internally
  → Agent exits after module complete
```

**Result:** 5 agents for 5 modules (1 per module)

---

### ❌ Anti-Pattern 3: Parallel Agents for Sequential Dependency

**Bad:**
```
Spawn agent-read-master (reads master feature.json)
Spawn agent-read-module-1 (reads module 1 feature.json)
Spawn agent-consolidate (waits for both, then merges)
```

**Result:** 3 agents when 2 have sequential dependency

**Good:**
```
Spawn agent-consolidate
  → Reads master
  → Reads module 1
  → Merges inline
  → Returns result
```

**Result:** 1 agent, same output, faster execution

---

## Implementation Patterns

### Pattern 1: Module Loop with Single Agent

**Scenario:** Step 03 - Specify 5 modules sequentially

**Recommended:**
```
1. Main flow spawns ONE agent: "ba-module-orchestrator"
2. Agent receives: modules[], currentModuleIndex
3. Agent executes loop:
   FOR i = 0; i < modules.length; i++:
     Execute step-03a (data)
     Execute step-03b (ui)
     Execute step-03c (compile)
     Execute step-03d (validate)
     Write module feature.json
     Advance to next module
4. Agent exits when all modules specified
```

**Result:** 1 agent for all 5 modules (vs. 20 agents in current implementation)

**Exception:** If modules have NO dependencies and can be specified in parallel:
- Spawn 2-3 agents maximum
- Each agent handles 1-2 modules
- Results merged by main flow

---

### Pattern 2: Batch Operations with Checkpoints

**Scenario:** Step 05a - Generate handoff for 5 modules

**Recommended:**
```
1. Main flow spawns ONE agent: "ba-handoff-generator"
2. Agent receives: modules[], master feature.json
3. Agent executes batch:
   FOR each module:
     Calculate complexity
     Map files to create (7 categories)
     Map business rules to code
     Generate API endpoint summary
     Write to module feature.json
     CHECKPOINT: Display progress "✓ Module {i+1}/5 complete"
4. After ALL modules: Write master handoff
5. Agent exits
```

**Result:** 1 agent for all handoff generation (vs. 5-10 agents in current)

**Checkpoint benefits:**
- User sees progress
- Agent can be interrupted/resumed if needed
- Failures isolated to specific module

---

### Pattern 3: Parallel Domain Operations

**Scenario:** Step 00 - Initialize schemas + scan existing features + create config

**Recommended:**
```
1. Spawn agent-deploy-schemas (deploy 9 schema files)
2. Spawn agent-scan-features (glob + read existing features)
3. Main flow waits for both
4. Main flow creates config (inline)
5. Main flow creates master feature.json (inline via ba-writer)
```

**Result:** 2 agents for genuinely parallel tasks

**Why parallel:**
- Schema deployment and feature scanning are independent
- Both are I/O-bound (file operations)
- No shared state until merge

---

### Pattern 4: Layer-Based Parallel Spawn (RECOMMENDED for Step 03)

**Scenario:** Step 03 - Specify modules across dependency layers

**Recommended:**
```
FOR each layer in dependencyGraph.layers:

  1. Pre-analyze: Identify cross-module touchpoints between modules in this layer
     → Shared entities, FK overlaps, naming conventions, shared lookups
     → Build coordinationNotes per module

  2. Spawn ALL layer agents in parallel (1 Task per module, ALL in ONE message)
     → Each agent receives: module context + completedModulesSummary + coordinationNotes

  3. Handle cross-module queries during execution (team lead relays)
     → Agent sends CROSS_MODULE_QUERY → team lead routes → answer forwarded

  4. Wait for ALL PROPOSAL_READY from this layer

  5. Display cross-module interaction analysis (bird's-eye view)
     → Detected interactions, resolved queries, attention points

  6. Review each module individually with user (quality-first)
     → Approve, revise, or see detail per module

  7. Layer consistency check (FK names, permissions, i18n, seed data IDs)
     → Auto-fix if inconsistency found

  8. Shutdown ALL layer agents

  9. Rebuild completedModulesSummary for next layer

  10. Proceed to next layer
```

**Result:**
- 4 agents for 4 modules (same count as sequential)
- But wall-clock reduced by ~50-66% for apps with parallel layers
- Cross-module consistency guaranteed by pre-injection + relay + consistency check
- Each agent has fresh context (zero accumulation)

**Why this pattern works:**
- Dependency layers already computed by step-02 topological sort
- Modules in the same layer have NO direct dependencies (by definition)
- Pre-injection prevents most cross-module issues before they happen
- Runtime relay catches unexpected edge cases
- Consistency check catches anything missed by both mechanisms

---

## Metrics & Monitoring

### Target Metrics (per BA session)

| Metric | Current | Target (agent pooling) | Target (team mode) | Improvement |
|--------|---------|----------------------|-------------------|-------------|
| Total agents | 24 | 5-7 | 3-6 (1/module + consolidation + handoff) | 75-88% reduction |
| Ultra-short agents (<20 lines) | 4 | 0 | 0 | 100% elimination |
| Agents per module loop | 4-5 | 1 | 1 (autonomous, full context) | 80% reduction |
| JSONL log lines | 1540 | <500 | <300 | 68-81% reduction |
| Context exhaustion risk | HIGH (3%) | MEDIUM | **ZERO** (each agent fresh) | Eliminated |
| Max context per agent | 100% (single conv) | ~80% | ~40-60% (one module only) | 40-60% reduction |

### Agent Spawn Decision Checklist

Before spawning a new agent, ask:

1. ☐ Can this be done inline in current agent? (80% of cases: YES)
2. ☐ Can I reuse an existing agent? (10% of cases: YES)
3. ☐ Is this truly parallel? (5% of cases: YES)
4. ☐ Is this a different domain? (5% of cases: YES)

If ALL answers are NO → spawn new agent.
Otherwise → inline or reuse.

---

## Step-by-Step Migration Guide

### Step 00: Init

**Current:** 3-4 agents (schema deploy, scan, config, create)
**Target:** 1-2 agents

**Changes:**
- Inline config creation
- Inline master feature.json creation via ba-writer
- Keep schema deployment as separate agent (parallel with scan)

---

### Step 01: Cadrage

**Current:** 2-3 agents (questionnaire, suggestions, write)
**Target:** 1 agent

**Changes:**
- ONE agent executes entire cadrage
- Inline questionnaire processing
- Inline suggestion generation
- Single ba-writer call at end

---

### Step 02: Decomposition

**Current:** 3-4 agents (analysis, dependency graph, client checkpoint, write)
**Target:** 1 agent

**Changes:**
- ONE agent for decomposition
- Inline dependency graph calculation
- Inline client checkpoint (AskUserQuestion)
- Single ba-writer call for modules + dependencyGraph

---

### Step 03: Module Specification (BIGGEST IMPACT)

**Current:** 4-5 agents PER module × 5 modules = 20-25 agents
**Target:** 1 agent per module, parallel within dependency layers

**Implementation (team mode with parallel layers):**
- ONE agent PER module, each executing 03a → 03b → 03c → 03d autonomously
- Modules in the same dependency layer spawn **simultaneously** (parallel)
- Modules in different layers spawn **sequentially** (dependency order)
- Team lead pre-injects cross-module coordination notes before spawning
- Runtime cross-module queries relayed by team lead between parallel agents
- Layer consistency check after all modules in a layer are approved

**Example (4 modules, 3 layers):**
```
Layer 0: [Customers, Products] → 2 agents in parallel
Layer 1: [Orders]              → 1 agent (after layer 0 complete)
Layer 2: [Invoices]            → 1 agent (after layer 1 complete)
Total: 4 agents, but wall-clock = 3 layers (not 4 sequential)
```

---

### Step 04: Consolidation

**Current:** 2-3 agents (cross-module validation, E2E flows, write)
**Target:** 1 agent

**Changes:**
- ONE agent for consolidation
- Inline cross-module interaction detection
- Inline E2E flow generation
- Single ba-writer call

---

### Step 05: Handoff & Deploy

**Current:** 5-7 agents (handoff per module + master + PRD generation + HTML deploy)
**Target:** 2-3 agents

**Changes:**
- ONE agent for all handoff generation (modules + master)
- ONE agent for artifact deployment (PRD + HTML + manifest)
- Optional: ONE agent for validation (step-05c)

---

## Cache Warming Strategy

> **Complement to agent pooling:** Pre-load frequently-used files to reduce redundant reads.

### Step 00: Pre-Load Core Context

```
At Step-00 initialization:
1. Read + cache all 9 schemas
2. Read + cache master feature template
3. Read + cache questionnaire templates
4. Read + cache suggestion catalog

Result: 90% of Step-01 context pre-loaded, no re-reads needed
```

### Step 03: Pre-Load Module Context

```
At start of module loop:
1. Read + cache application context (from master)
2. Read + cache completed module summaries (via ba-reader)
3. Read + cache shared patterns and templates

Result: 70% of per-module context pre-loaded
```

### Benefits

- 15-20% token savings across session
- Faster agent execution (no wait for file reads)
- Reduced risk of file read failures
- Better cache hit rates (98.5% cache read in analysis → 50% reduction with warming)

---

## Rollout Plan

### Phase 1: Quick Wins (Week 1)

1. ✅ Eliminate ultra-short summary agents
   - Make summaries inline in calling agent
   - Remove dedicated "summary-request" agents

2. ✅ Consolidate Step 01 + 02 to 1 agent each
   - Combine questionnaire + suggestions + write
   - Combine decomposition + dependency + write

**Expected impact:** 30% reduction in agent count

---

### Phase 2: Module Loop Optimization (Week 2)

1. ✅ Refactor Step 03 to use 1 agent per module (or 1 for all)
   - Agent executes 03a → 03b → 03c → 03d internally
   - Display progress checkpoints
   - Single ba-writer call per module

**Expected impact:** 60% reduction in agent count

---

### Phase 3: Handoff & Deploy Optimization (Week 3)

1. ✅ Consolidate Step 05a to 1 agent for all modules
   - Batch handoff generation
   - Progress checkpoints

2. ✅ Consolidate Step 05b to 1 agent for all artifacts
   - PRD generation + HTML deploy + manifest

**Expected impact:** 70% reduction in agent count

---

### Phase 4: Cache Warming (Week 4)

1. ✅ Implement pre-loading in Step 00
2. ✅ Implement context caching in Step 03
3. ✅ Monitor cache hit rates

**Expected impact:** 15-20% token savings

---

## Monitoring & Success Criteria

### Before Optimization (Baseline)

```
Session: Business-analyse for HumanResources application
- Total agents: 24
- Ultra-short agents: 4
- JSONL lines: 1540
- Tokens (largest agent): 106,881
- Cache efficiency: 98.5% read (inefficient)
```

### After Optimization — Agent Pooling (Target)

```
Session: Business-analyse for HumanResources application
- Total agents: 5-7
- Ultra-short agents: 0
- JSONL lines: <500
- Tokens (largest agent): <80,000
- Cache efficiency: 50-60% read (optimal)
```

### After Optimization — Team Mode with Parallel Layers (Target, RECOMMENDED)

```
Session: Business-analyse for HumanResources application (4 modules, 3 layers)
- Team lead context: <50% (never exhausted)
- Module agents: 4 (1 per module, parallel within layers, each ~40-60% context)
- Consolidation agent: 1 (~30-40% context)
- Handoff agent: 1 (~40-50% context)
- Total agents: 6
- Context exhaustion: ZERO (each agent has fresh context window)
- User interaction: Propose & Review (user validates complete proposals)
- Wall-clock: ~50% reduction vs sequential (layer 0 runs 2 modules in parallel)
- Cross-module quality: pre-injection + relay + consistency check
```

### Success Metrics

- ✅ Agent count reduced by 75-88%
- ✅ Ultra-short agents eliminated
- ✅ JSONL complexity reduced by 68-81%
- ✅ **Context exhaustion eliminated** (team mode)
- ✅ Token usage distributed across parallel agents (team mode)
- ✅ **Wall-clock time reduced by ~50-66%** (parallel layer execution)
- ✅ **Cross-module consistency guaranteed** (pre-injection + relay + consistency check)
- ✅ Same or better output quality (cross-module coordination improves integration)

---

## References

- **Analysis Report:** Session 03b76b8b-ea1c-4f1e-a636-bd46b0c33e02
- **File Size Management:** See ba-writer.md § File Size Management
- **Cache Strategy:** See MEMORY.md § Cache Warming Strategy
- **Agent Types:** See Task tool documentation

---

## Quick Reference Card

### ✅ DO

- Reuse agents for sequential operations
- Spawn 1 agent per logical phase (not per sub-step)
- Spawn ALL same-layer agents in parallel (one message, multiple Task calls)
- Pre-inject coordination notes for parallel agents
- Handle cross-module queries via relay protocol
- Run layer consistency check after parallel approvals
- Do summaries/formatting inline
- Pre-load context at phase start
- Display progress checkpoints
- Use ba-writer for all JSON operations

### ❌ DON'T

- Spawn agents for trivial tasks (<20 lines output)
- Spawn new agent for each step transition
- Spawn agents for sequential dependencies
- Spawn agents from different dependency layers in parallel
- Re-read same files multiple times
- Create summary-only agents
- Spawn more than N+2 agents per BA session (N modules + consolidation + handoff)

---

**Last Updated:** 2026-02-15
**Version:** 2.0 (parallel layer execution)
**Author:** SmartStack CLI Team
