@atlashub/smartstack-cli 3.9.0 → 3.12.0

package/templates/skills/application/steps/step-03-roles.md

@@ -1,23 +1,29 @@
 ---
 name: step-03-roles
-description: Generate role-permission mappings using MCP scaffold_role_permissions (with fallback)
+description: Generate application roles and role-permission mappings using MCP scaffold_role_permissions (with fallback)
 prev_step: steps/step-02-permissions.md
 next_step: steps/step-03b-provider.md
 ---
 
-# Step 3: Role-Permission Mapping
+# Step 3: Application Roles & Role-Permission Mapping
 
 ## MANDATORY EXECUTION RULES
 
+- For **client projects** (`seeding_strategy = "provider"`): Generate ApplicationRolesSeedData.cs and module role mappings
+- For **core projects** (`seeding_strategy = "hasdata"`): Use RolePermissionConfiguration.cs
 - PREFER MCP `scaffold_role_permissions` tool as the primary method
 - If MCP is unavailable or the call fails, use the FALLBACK PROCEDURE below
 - ALWAYS assign permissions to default roles
 - NEVER leave permissions without role assignments
-- ALWAYS WRITE generated code to the actual RolePermissionConfiguration.cs file
+- ALWAYS WRITE generated code to the actual files
 
 ## YOUR TASK
 
-Generate role-permission mappings:
+For **client projects**:
+1. **ApplicationRolesSeedData.cs** (once per application) — defines the 4 application-scoped roles
+2. **{Module}RolePermissionSeedData.cs** (per module) — maps permissions to roles by Code
+
+For **core projects**:
 1. RolePermissionConfiguration.cs HasData() entries
 2. Default role assignments (SuperAdmin, PlatformAdmin, TenantAdmin, StandardUser)
 3. Application-scoped role assignments (Admin, Manager, Contributor, Viewer)
@@ -131,13 +137,38 @@ If MCP call fails or `{mcp_available}` = false:
 **For core (`{seeding_strategy}` = "hasdata"):** Write in RolePermissionConfiguration.cs (existing pattern)
 
 **For client (`{seeding_strategy}` = "provider"):** DO NOT write in RolePermissionConfiguration.cs (does not exist in client projects).
-Instead, create:
-- `Infrastructure/Persistence/Seeding/Data/{Domain}/{Module}RolePermissionSeedData.cs`
+
+Instead, create TWO files:
+
+### 1. ApplicationRolesSeedData.cs (ONCE per application)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
+
+**Purpose:** Defines the 4 standard application-scoped roles (Admin, Manager, Contributor, Viewer) with valid `Code` values.
+
+**CRITICAL:** Without this file, role-permission mappings in `SeedRolePermissionsAsync()` will fail silently because `roles.FirstOrDefault(r => r.Code == mapping.RoleCode)` will return null.
+
+See [references/application-roles-template.md](../references/application-roles-template.md) for the complete template.
+
+**Key requirements:**
+- Deterministic GUIDs based on `role-{applicationId}-{roleType}`
+- 4 roles: Admin, Manager, Contributor, Viewer
+- Each role has a valid `Code` property ("admin", "manager", "contributor", "viewer")
+- `ApplicationId` references the navigation application GUID
+- `IsSystem = false` (application-scoped, not system roles)
+
+**Detection:** Check if ApplicationRolesSeedData.cs exists. If yes, skip creation (already exists from Module 1). If no, create it.
+
+### 2. {Module}RolePermissionSeedData.cs (PER module)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/{Domain}/{Module}RolePermissionSeedData.cs`
+
+**Purpose:** Maps permissions to roles by Code (e.g., "admin" → "{navRoute}.*").
 
 Content: static class with method `GetRolePermissionEntries()` that returns the role-permission mapping data.
 These entries will be consumed by the `IClientSeedDataProvider` at step 03b.
 
-**After creating RolePermission SeedData:** Proceed to step-03b-provider.md (which will skip for core projects).
+**After creating both files:** Proceed to step-03b-provider.md (which will skip for core projects).
 
 ---
 
@@ -280,6 +311,13 @@ If user selects "Custom adjustments", ask which roles/permissions to change and
 
 ## SUCCESS METRICS
 
+**For client projects:**
+- ApplicationRolesSeedData.cs created (once per application)
+- {Module}RolePermissionSeedData.cs created with role-permission mappings
+- All 4 application roles defined with valid Code values
+- Proceeded to step-03b-provider.md
+
+**For core projects:**
 - Role-permission mappings generated (via MCP or fallback)
 - RolePermissionConfiguration.cs WRITTEN with new entries
 - All default roles have appropriate access

package/templates/skills/application/steps/step-03b-provider.md

@@ -50,9 +50,10 @@ From previous steps:
 ## FILES TO GENERATE
 
 See [references/provider-template.md](../references/provider-template.md) for the complete implementation:
-- **Provider class** (`{AppPascalName}SeedDataProvider.cs`) with 3 seed methods (Navigation, Permissions, RolePermissions)
+- **ApplicationRolesSeedData.cs** (once per application) — defines application-scoped roles (Admin, Manager, Contributor, Viewer)
+- **Provider class** (`{AppPascalName}SeedDataProvider.cs`) with 4 seed methods (Navigation, Roles, Permissions, RolePermissions)
 - **DI registration** pattern for `Infrastructure/DependencyInjection.cs`
-- **6 critical rules** (factory methods, idempotence, SaveChangesAsync order, deterministic GUIDs, FK by Code, Order property)
+- **7 critical rules** (factory methods, idempotence, execution order, SaveChangesAsync order, deterministic GUIDs, FK by Code, Order property)
 
 ---
 
@@ -64,9 +65,11 @@ Identify all SeedData files created in previous steps:
 
 ```
 Glob: **/Persistence/Seeding/Data/{Domain}/*SeedData.cs
+Glob: **/Persistence/Seeding/Data/ApplicationRolesSeedData.cs
 ```
 
 Expected files:
+- `ApplicationRolesSeedData.cs` (application-level, once per app)
 - `{Module}NavigationSeedData.cs` (from step 01)
 - `{Module}NavigationTranslationSeedData.cs` (from step 01)
 - `{Module}PermissionSeedData.cs` (from step 02)
@@ -96,9 +99,11 @@ Add the `IClientSeedDataProvider` registration.
 ### 4. Verify
 
 Before proceeding to step-04, verify:
-- [ ] Provider generated with 3 methods (SeedNavigationAsync, SeedPermissionsAsync, SeedRolePermissionsAsync)
+- [ ] ApplicationRolesSeedData.cs created (once per application)
+- [ ] Provider generated with 4 methods (SeedNavigationAsync, SeedRolesAsync, SeedPermissionsAsync, SeedRolePermissionsAsync)
+- [ ] Execution order: Navigation → Roles → Permissions → RolePermissions
 - [ ] Registered in DI (`services.AddScoped<IClientSeedDataProvider, ...>()`)
-- [ ] Consumes SeedData classes from steps 01-03
+- [ ] Consumes SeedData classes from steps 01-03 + ApplicationRolesSeedData
 - [ ] Idempotent (check existence before insert)
 - [ ] Uses factory methods (no `new Entity()`)
 
@@ -106,9 +111,11 @@ Before proceeding to step-04, verify:
 
 ## SUCCESS METRICS
 
-- Provider class generated with all 3 seed methods
+- ApplicationRolesSeedData.cs created (application-level)
+- Provider class generated with all 4 seed methods (Navigation, Roles, Permissions, RolePermissions)
+- Correct execution order enforced
 - DI registration added
-- SeedData classes from steps 01-03 properly consumed
+- SeedData classes from steps 01-03 + ApplicationRolesSeedData properly consumed
 - All methods are idempotent
 - Factory methods used throughout
 - Proceeded to step-04-backend.md

package/templates/skills/business-analyse/SKILL.md

@@ -75,6 +75,52 @@ docs/business/
 **No intermediate markdown files - all state in feature.json**
 </output_structure>
 
+<navigation_hierarchy>
+**SmartStack uses a 5-level navigation structure mapped to database tables:**
+
+| Level | Entity | Table DB | Created in Step | Description |
+|-------|--------|----------|-----------------|-------------|
+| 1 | Context | `core.nav_Contexts` | N/A | Fixed ("business", "platform", "system") |
+| 2 | Application | `core.nav_Applications` | 00-01 | Top-level application (e.g., "RessourcesHumaines") |
+| 3 | Module | `core.nav_Modules` | 02 | Functional module (e.g., "Employees", "TimeManagement") |
+| 4 | **Section** | **`core.nav_Sections`** | **03a-03c** | **Page within module (e.g., "list", "detail", "create", "dashboard")** |
+| 5 | **Resource** | **`core.nav_Resources`** | **03b-03c** | **React component (SmartTable, SmartForm, Chart, KpiCard, etc.)** |
+
+**Hierarchical relationship:**
+- Context → Application → Module → **Section** → **Resource**
+- Each Section MUST have ≥1 Resource
+- Each Section corresponds to 1 React page route
+- Each Resource corresponds to 1 SmartStack UI component
+
+**SeedData generation (step-03c):**
+
+The `specification.seedDataCore` contains **7 mandatory arrays** for database seeding:
+
+| Array | Table | Source | Description |
+|-------|-------|--------|-------------|
+| `navigationModules` | `core.nav_Modules` | Manual (step-03c) | Module entry (Level 3) |
+| **`navigationSections`** | **`core.nav_Sections`** | **Derived from `specification.sections[]`** | **Section entries (Level 4)** |
+| **`navigationResources`** | **`core.nav_Resources`** | **Derived from `specification.sections[].resources[]`** | **Resource entries (Level 5)** |
+| `navigationTranslations` | `core.nav_Translations` | Manual (i18n) | Multi-language labels |
+| `permissions` | `core.Permissions` | Manual (step-03c) | Permission definitions |
+| `rolePermissions` | `core.RolePermissions` | Manual (step-03c) | Role-permission mappings |
+| `permissionConstants` | `PermissionConstants.cs` | Manual (step-03c) | C# permission constants |
+
+**Transform algorithm (step-03c section 8f-bis):**
+- `navigationSections` = transform `specification.sections[]` → flatten to { code, label, icon, route, parentCode, permission, sort }
+- `navigationResources` = transform `specification.sections[].resources[]` → flatten to { code, type, entity, parentCode, permission }
+
+**Example:**
+- Module: `Employees` (Level 3)
+  - Section: `list` (Level 4) → contains resources:
+    - Resource: `employees-grid` (SmartTable) (Level 5)
+    - Resource: `status-filter` (FilterBar) (Level 5)
+  - Section: `detail` (Level 4) → contains resources:
+    - Resource: `employee-card` (DetailCard) (Level 5)
+    - Resource: `contract-history` (SmartTable) (Level 5)
+
+</navigation_hierarchy>
+
 <resume_workflow>
 **Update mode (auto-detected):**
 
@@ -104,9 +150,12 @@ When step-00 detects that the description matches an existing application:
 - **Step 03c:** Per-module compile: actors, UCs, FRs, permissions, navigation, seed data, i18n
 - **Step 03d:** Per-module validate: completeness checks, write feature.json, incremental HTML, loop
   - Loop: 03a → 03b → 03c → 03d → 03a (next module) until all specified (specified)
-- **Step 04:** Cross-module consolidation (consolidated)
+- **Step 04a:** Collect: module summaries, cross-module interactions (FK, events, shared data)
+- **Step 04b:** Analyze: permission coherence, semantic validation, E2E flows, global risks
+- **Step 04c:** Decide: final approval, write consolidation section, proceed to handoff (consolidated)
 - **Step 05a:** Handoff: file mapping (7 categories), BR-to-code mapping, API summary, write to feature.json
 - **Step 05b:** Deploy: prd.json, progress.txt, manifest, ba-interactive.html pre-populated (handed-off)
+- **Step 05c:** Ralph Readiness Check: validation gate before /ralph-loop (optional but recommended)
 
 **Update workflow (same phases, delta focus):**
 - **Step 00:** Detection, locate existing feature, create version N+1
@@ -152,11 +201,14 @@ When step-00 detects that the description matches an existing application:
 | 02   | `steps/step-02-decomposition.md`  | Opus   | Module decomposition, dependency graph, client checkpoint |
 | 03a  | `steps/step-03a-data.md`          | Opus   | Per-module: sections, entities, BRs, questionnaires |
 | 03b  | `steps/step-03b-ui.md`            | Opus   | Per-module: state machines, wireframes, layouts, dashboards |
-| 03c  | `steps/step-03c-compile.md`       | Opus   | Per-module: actors, UCs, FRs, permissions, nav, seed data, i18n |
+| 03c  | `steps/step-03c-compile.md`       | Opus   | Per-module: actors, UCs, FRs, permissions, navigation, seedDataCore (7 arrays), i18n |
 | 03d  | `steps/step-03d-validate.md`      | Sonnet | Per-module: validation, write, incremental HTML, loop decision |
-| 04   | `steps/step-04-consolidation.md`  | Opus   | Cross-module validation, E2E flows, permissions coherence |
+| 04a  | `steps/step-04a-collect.md`       | Opus   | Collect module summaries & cross-module interactions |
+| 04b  | `steps/step-04b-analyze.md`       | Opus   | Analyze permission coherence, semantic validation, E2E flows |
+| 04c  | `steps/step-04c-decide.md`        | Opus   | Final approval, write consolidation, proceed to handoff |
 | 05a  | `steps/step-05a-handoff.md`       | Sonnet | Handoff: file mapping (7 categories), BR-to-code mapping, API summary, write handoff |
-| 05b  | `steps/step-05b-deploy.md`        | Sonnet | Deploy: prd.json, progress.txt, manifest, ba-interactive.html, auto-launch ralph-loop |
+| 05b  | `steps/step-05b-deploy.md`        | Sonnet | Deploy: prd.json, progress.txt, manifest, ba-interactive.html |
+| 05c  | `steps/step-05c-ralph-readiness.md` | Sonnet | Ralph readiness validation gate (optional but recommended) |
 | 06   | `steps/step-06-review.md`         | Opus   | Apply review corrections, create new version, regenerate all artifacts |
 
 </step_files>

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

@@ -0,0 +1,477 @@
+# 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
+
+---
+
+## Metrics & Monitoring
+
+### Target Metrics (per BA session)
+
+| Metric | Current | Target | Improvement |
+|--------|---------|--------|-------------|
+| Total agents | 24 | 5-7 | 71-79% reduction |
+| Ultra-short agents (<20 lines) | 4 | 0 | 100% elimination |
+| Agents per module loop | 4-5 | 1 | 80% reduction |
+| JSONL log lines | 1540 | <500 | 68% 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 (5 total) OR 1 agent for all modules (1 total)
+
+**Changes:**
+- **Option A:** ONE agent for ALL modules (sequential)
+  - Agent loops through modules
+  - Executes 03a → 03b → 03c → 03d internally
+  - Displays progress checkpoints
+
+- **Option B:** ONE agent PER module (if parallel possible)
+  - Max 2-3 modules in parallel
+  - Each agent handles 1 module end-to-end
+
+**Recommended:** Option A (sequential) for most cases, Option B only if modules truly independent
+
+---
+
+### 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 (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)
+```
+
+### Success Metrics
+
+- ✅ Agent count reduced by 70-79%
+- ✅ Ultra-short agents eliminated
+- ✅ JSONL complexity reduced by 68%
+- ✅ Token usage reduced by 15-20%
+- ✅ Same output quality (no regressions)
+
+---
+
+## 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)
+- 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
+- Re-read same files multiple times
+- Create summary-only agents
+- Spawn more than 7 agents per BA session
+
+---
+
+**Last Updated:** 2026-02-08
+**Version:** 1.0
+**Author:** SmartStack CLI Team