npm - @atlashub/smartstack-cli - Versions diffs - 4.18.0 → 4.20.0 - Mend

@atlashub/smartstack-cli 4.18.0 → 4.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (164) hide show

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

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