@atlashub/smartstack-cli 3.39.0 → 3.41.0

package/templates/skills/business-analyse/references/agent-pooling-best-practices.md

@@ -1,557 +1,557 @@
-# 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
+# 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