@atlashub/smartstack-cli 3.25.0 → 3.26.0

package/templates/skills/business-analyse/references/team-orchestration.md

@@ -0,0 +1,437 @@
+# Team Orchestration — Business-Analyse Propose & Review
+
+> **Loaded by:** step-02 when multi-module detected (`moduleOrder.length >= 2`)
+> **Purpose:** Delegate module specification to autonomous agents with user review.
+> **Rule:** Single module = NO team. Only create team for 2+ modules.
+
+---
+
+## 1. Team Setup
+
+After step-02 decomposition is complete and client has approved the module structure:
+
+```
+TeamCreate({ team_name: "ba-{appName}" })
+```
+
+Store team context for the session:
+```javascript
+const teamContext = {
+  teamName: "ba-{appName}",
+  moduleOrder: metadata.workflow.moduleOrder,
+  dependencyLayers: dependencyGraph.layers || null,
+  currentModuleIdx: 0,
+  completedModules: [],
+  mode: "propose-review"
+};
+```
+
+---
+
+## 2. Module Agent Spawn — Sequential by Topological Order
+
+For each module in `moduleOrder` (respecting dependency layers):
+
+### 2a. Prepare Agent Context
+
+Before spawning, gather the context the agent needs:
+
+```
+1. ba-reader.readApplicationContext({feature_id})
+   → Extract: appName, featureId, context, language
+
+2. Read module decomposition data from master feature.json:
+   → modules[currentModuleIdx]: code, name, description, featureType, entities,
+     anticipatedSections, dependencies, detailTabs
+
+3. ba-reader.getCompletedModulesSummary({feature_id})
+   → Compact summary of already-specified modules (max 100 lines)
+   → Includes: entity names, FK relationships, permission paths, shared types
+```
+
+### 2b. Spawn Agent
+
+```javascript
+Task({
+  subagent_type: "general-purpose",
+  team_name: "ba-{appName}",
+  name: "mod-{moduleCode}",
+  model: "opus",
+  mode: "bypassPermissions",
+  prompt: BUILD_PROMPT(references/agent-module-prompt.md, {
+    appName,
+    featureId,
+    moduleCode,
+    moduleDescription: module.description,
+    featureType: module.featureType,
+    entities: module.entities,
+    anticipatedSections: module.anticipatedSections,
+    dependencies: module.dependencies,
+    detailTabs: module.detailTabs,
+    completedModulesSummary,
+    language: metadata.language,
+    docsDir: "docs/business/{appName}/{moduleCode}/business-analyse/v{version}/"
+  }),
+  description: "Specify {moduleCode}"
+});
+```
+
+**BUILD_PROMPT**: Read `references/agent-module-prompt.md`, replace all `{placeholders}` with actual values, and pass as the `prompt` parameter.
+
+### 2c. Sequential Constraint
+
+- Spawn ONE module agent at a time
+- Wait for MODULE_COMPLETE before spawning the next
+- Reason: later modules may reference entities/FKs from earlier modules
+- **Future optimization**: modules in the same dependency layer with no cross-refs COULD run in parallel
+
+---
+
+## 3. Propose & Review Protocol
+
+### 3a. Team Lead Receives PROPOSAL_READY
+
+After the agent finishes specifying a module, it sends:
+
+```
+PROPOSAL_READY:{moduleCode}
+
+## Module: {moduleCode} — Specification Summary
+
+### Entities ({count})
+| Entity | Attributes | Relationships |
+|--------|-----------|---------------|
+| ... | ... | ... |
+
+### Sections ({count})
+| Section | Description | Resources |
+|---------|-------------|-----------|
+| ... | ... | ... |
+
+### Use Cases ({count})
+- UC-{PREFIX}-001: {title}
+- UC-{PREFIX}-002: {title}
+- ...
+
+### Business Rules ({count})
+- BR-{CAT}-{PREFIX}-001: {title}
+- ...
+
+### Permissions ({count})
+- {context}.{app}.{module}.{action}
+- ...
+
+### Seed Data
+- Modules: {count} | Sections: {count} | Resources: {count}
+- Translations: {count} | Permissions: {count} | Role mappings: {count}
+
+### Wireframes
+- {section}: {1-line description}
+- ...
+```
+
+### 3b. Team Lead Presents to User
+
+Format the proposal for user review:
+
+```
+═══════════════════════════════════════════════════════════
+  Proposition pour le module {moduleCode} ({idx+1}/{total})
+═══════════════════════════════════════════════════════════
+
+{structured summary from agent — displayed as-is}
+
+─────────────────────────────────────────────────────────
+```
+
+Then ask user via AskUserQuestion:
+
+```
+Validez-vous cette specification ?
+Options:
+  1. "Valider" → approve as-is
+  2. "Modifier" → provide feedback for revision
+  3. "Voir detail" → team lead reads module feature.json and displays full content
+```
+
+### 3c. Approval Flow
+
+**If user approves:**
+```
+SendMessage({
+  type: "message",
+  recipient: "mod-{moduleCode}",
+  content: "APPROVED:{moduleCode}",
+  summary: "{moduleCode} approved by user"
+})
+```
+→ Agent writes final status, sends MODULE_COMPLETE, and shuts down.
+
+**If user requests modifications:**
+```
+SendMessage({
+  type: "message",
+  recipient: "mod-{moduleCode}",
+  content: "REVISION:{moduleCode}\n{user_feedback}",
+  summary: "{moduleCode} revision requested"
+})
+```
+→ Agent applies changes, re-validates, sends new PROPOSAL_READY.
+
+**If user wants to see detail:**
+→ Team lead reads module feature.json via ba-reader.readSection({feature_id, section})
+→ Displays relevant sections in detail
+→ Re-asks validation question
+
+### 3d. Revision Limits
+
+- Max **3 revision cycles** per module
+- After 3 rejections: team lead asks user if they want to switch to **inline interactive mode** for this module
+  - If yes: team lead loads step-03a1-setup.md and executes interactively (classic mode)
+  - If no: mark module as "needs-review" and continue to next module
+
+---
+
+## 4. Module Completion & Advancement
+
+When agent sends MODULE_COMPLETE:
+
+```javascript
+// Update tracking
+teamContext.completedModules.push(moduleCode);
+teamContext.currentModuleIdx++;
+
+// Update master feature.json
+ba-writer.advanceModuleLoop({feature_id});
+ba-writer.updateModuleStatus({feature_id, moduleCode, status: "specified"});
+
+// Display progress
+Display: "✓ Module {moduleCode} specified ({completedModules.length}/{moduleOrder.length})"
+
+// Shutdown agent
+SendMessage({
+  type: "shutdown_request",
+  recipient: "mod-{moduleCode}",
+  content: "Module complete, shutting down"
+});
+```
+
+If more modules remain → spawn next module agent (go to §2).
+If all modules complete → proceed to §5 (Consolidation).
+
+---
+
+## 5. Consolidation Phase
+
+After ALL modules are specified:
+
+```
+Display: "═══ All modules specified — Starting consolidation ═══"
+```
+
+### 5a. Spawn Consolidation Agent
+
+```javascript
+Task({
+  subagent_type: "general-purpose",
+  team_name: "ba-{appName}",
+  name: "consolidation",
+  model: "opus",
+  mode: "bypassPermissions",
+  prompt: `
+You are a consolidation agent for business-analyse application "{appName}".
+
+## Your Mission
+Execute cross-module consolidation (steps 04a + 04b):
+1. Load steps/step-04a-collect.md and execute
+2. Load steps/step-04b-analyze.md and execute
+
+## Context
+- Feature ID: {featureId}
+- Modules: {moduleOrder.join(", ")}
+- All modules have status "specified"
+
+## Output
+Send CONSOLIDATION_READY with a structured report:
+- Cross-module interactions (FK references, shared entities, event flows)
+- Permission coherence (conflicts, overlaps, gaps)
+- E2E user flows validated
+- Global risks identified
+
+## Communication
+- CONSOLIDATION_READY:{appName}\n{report} → when analysis complete
+- ERROR:{appName}:{description} → on blocking issue
+  `,
+  description: "Cross-module consolidation"
+});
+```
+
+### 5b. Present Consolidation to User (04c Decision)
+
+When CONSOLIDATION_READY received:
+
+```
+═══════════════════════════════════════════════════════════
+  Consolidation cross-module — {appName}
+═══════════════════════════════════════════════════════════
+
+{consolidation report from agent}
+
+─────────────────────────────────────────────────────────
+```
+
+AskUserQuestion: "Approuvez-vous la consolidation ?"
+- "Approuver" → send APPROVED to agent → agent writes consolidation to master feature.json
+- "Reviser" → send feedback → agent adjusts
+
+After approval → shutdown consolidation agent → proceed to §6.
+
+---
+
+## 6. Handoff Phase
+
+```javascript
+Task({
+  subagent_type: "general-purpose",
+  team_name: "ba-{appName}",
+  name: "handoff",
+  model: "sonnet",
+  mode: "bypassPermissions",
+  prompt: `
+You are a handoff agent for business-analyse application "{appName}".
+
+## Your Mission
+Execute the handoff sequence (steps 05a + 05b + 05c):
+1. Load steps/step-05a-handoff.md and execute (file mapping, BR-to-code, API summary)
+2. Load steps/step-05b-deploy.md and execute (prd.json, ba-interactive.html, manifest)
+3. Load steps/step-05c-ralph-readiness.md and execute (quality gate)
+
+## Context
+- Feature ID: {featureId}
+- Modules: {moduleOrder.join(", ")}
+- All modules consolidated
+
+## Output
+Send HANDOFF_READY with:
+- PRD files generated (list)
+- HTML deployed (path)
+- Quality gate result (PASS/FAIL with details)
+
+## Communication
+- HANDOFF_READY:{appName}\n{report} → when all artifacts deployed
+- ERROR:{appName}:{description} → on blocking issue
+  `,
+  description: "Handoff & deploy"
+});
+```
+
+When HANDOFF_READY received:
+
+```
+═══════════════════════════════════════════════════════════
+  Handoff complete — {appName}
+═══════════════════════════════════════════════════════════
+
+{handoff report}
+
+─────────────────────────────────────────────────────────
+```
+
+Display final status to user. If quality gate PASS → ready for /ralph-loop.
+
+---
+
+## 7. Cleanup
+
+After handoff complete:
+
+```javascript
+// Shutdown any remaining agents
+for (const agentName of ["consolidation", "handoff"]) {
+  SendMessage({
+    type: "shutdown_request",
+    recipient: agentName,
+    content: "Workflow complete"
+  });
+}
+
+// Delete team
+TeamDelete();
+
+Display: "═══ Business-analyse complete — Team cleaned up ═══"
+```
+
+---
+
+## 8. Error Recovery
+
+### Agent Crash
+
+If an agent stops responding or sends ERROR:
+
+```javascript
+// 1. Check module status in feature.json
+const moduleStatus = ba-reader.getModuleStatus({feature_id});
+
+// 2. If module has partial data (status = "in-progress"):
+//    → Spawn new agent for same module
+//    → New agent detects partial state and continues
+//    → Include in prompt: "Resume specification — partial data exists in feature.json"
+
+// 3. Track retry count
+if (retryCount[moduleCode] >= 3) {
+  Display: "Agent failed 3 times for module {moduleCode}."
+  AskUserQuestion: "Fallback to inline interactive mode for this module?"
+  // If yes: load step-03a1-setup.md inline
+  // If no: skip module, mark as "needs-review"
+}
+```
+
+### Context Exhaustion on Team Lead
+
+The team lead should stay under 30% context usage. If approaching limits:
+
+1. **Minimize presentation**: Show only entity/section counts, not full details
+2. **Auto-approve**: If user has approved 3+ modules without changes, suggest auto-approve mode
+3. **Skip detail view**: Don't read full feature.json into team lead context
+
+### Resume After Session Crash
+
+If the entire session crashes:
+
+1. User restarts `/business-analyse`
+2. Step-00 detects existing feature.json with `status: "decomposed"` or partial modules
+3. Reads `metadata.workflow.completedModules` to know which modules are done
+4. Creates new team, spawns agent for next incomplete module
+5. Continues normally
+
+---
+
+## Decision Matrix
+
+| Condition | Action |
+|-----------|--------|
+| 1 module | NO team, classic inline execution |
+| 2+ modules | Team mode (Propose & Review) |
+| Modules in same dependency layer, no cross-refs | Sequential (future: parallel) |
+| Modules with dependencies | Strict topological order |
+| Agent error | Respawn with same module context (max 3 retries) |
+| User rejects 3 times | Offer fallback to inline interactive |
+| Context > 50% on team lead | Minimize presentation, suggest auto-approve |
+| Session crash | Resume from feature.json workflow state |
+
+---
+
+## Token Budget Estimates
+
+| Phase | Agent | Estimated Context % | Duration |
+|-------|-------|-------------------|----------|
+| Init + Cadrage + Decomposition | Team lead (inline) | 20-30% | 5-10 min |
+| Module specification (per module) | mod-{code} agent | 40-60% | 3-5 min |
+| Propose & Review (per module) | Team lead relay | +2-5% per module | 1-2 min |
+| Consolidation | consolidation agent | 30-40% | 2-3 min |
+| Handoff | handoff agent | 40-50% | 3-5 min |
+| **Total team lead** | — | **30-50%** | — |
+| **Total per module agent** | — | **40-60%** | — |
+
+**Key insight:** Team lead never exceeds 50% even with 10+ modules, because module specifications happen in separate contexts.

package/templates/skills/business-analyse/steps/step-02-decomposition.md

@@ -314,7 +314,33 @@ Create: docs/business/{app}/{module_code}/business-analyse/v1.0/
 ═══════════════════════════════════════════════════════════
 ```
 
-**AUTOCHAIN — DO NOT STOP HERE:**
+### 9-bis. Team Mode Decision
+
+After module registry is written and client has approved decomposition:
+
+**IF moduleOrder.length >= 2 (TEAM MODE):**
+
+```
+Display:
+═══════════════════════════════════════════════════════════
+  Multi-module détecté ({N} modules) — Activation du Mode Team
+═══════════════════════════════════════════════════════════
+
+  Chaque module sera spécifié par un agent dédié avec un contexte frais.
+  Vous validerez chaque proposition avant sa finalisation.
+
+  Modules : {moduleOrder.join(" → ")}
+═══════════════════════════════════════════════════════════
+```
+
+**Load: `references/team-orchestration.md`**
+→ Follow the team orchestration protocol starting at §1 (Team Setup)
+→ DO NOT load step-03a1-setup.md — agents will load it internally
+→ **STOP HERE** — the team-orchestration.md takes over the workflow
+
+**ELSE (single module — INLINE MODE):**
+
+AUTOCHAIN — DO NOT STOP HERE:
 - Do NOT ask "shall I continue?" or "voulez-vous que je continue?"
 - Do NOT summarize what's coming next
 - Do NOT wait for user input
@@ -331,13 +357,14 @@ When `workflow.mode = "module"` or only 1 scope item identified:
 2. No dependency analysis needed
 3. **Simplified checkpoint:** Quick confirmation instead of full validation
 4. Set moduleOrder = [{single module code}]
-5. Proceed to step-03
+5. Proceed to step-03 (inline, no team)
 
 ---
 
-## NEXT STEP (MANDATORY — NO PAUSE)
+## NEXT STEP (conditional)
 
-Load: `./step-03a1-setup.md`
+**If 2+ modules:** DO NOT load step-03a1. Load `references/team-orchestration.md` instead.
+**If 1 module:** Load `./step-03a1-setup.md`
 
 > **FORBIDDEN:** Asking any question between decomposition summary and step-03 load.
 > The client checkpoint was at step 6. Do NOT add another one.

package/templates/skills/business-analyse/steps/step-03a1-setup.md

@@ -42,6 +42,27 @@ next_step: steps/step-03a2-analysis.md
   Dashboard modules MUST use specification.dashboards[] (it exists in the schema).
   If truly needed, use specification.extensions: {} (additionalProperties: true).
 
+## MODE DETECTION
+
+**Check your execution context before proceeding:**
+
+**IF you are running as a TEAM AGENT** (you received a module-specifier prompt from `references/agent-module-prompt.md`):
+  → You are in **AUTONOMOUS mode** (Propose & Review)
+  → Do NOT use `AskUserQuestion` — you PROPOSE, the team lead handles user interaction
+  → Replace ALL `AskUserQuestion` calls with **ULTRATHINK autonomous decisions**
+  → Use the decomposition data + completed module summaries to make informed choices
+  → After completing all steps (03a1 → 03a2 → 03b → 03c → 03d): send `PROPOSAL_READY` to team lead
+  → See `references/agent-module-prompt.md` for autonomous decision rules
+  → See `references/team-orchestration.md` § 3 for communication protocol
+
+**IF you are running in the MAIN CONVERSATION** (classic inline mode):
+  → Normal interactive mode — use `AskUserQuestion` as documented below
+  → No `SendMessage` calls needed
+
+**How to detect:** If your prompt contains `PROPOSE & REVIEW` or `team-lead` as recipient, you are a team agent.
+
+---
+
 ## YOUR TASK
 
 Specify one module's data model and business logic: walk through sections, define entities, business rules, and validate with client before proceeding to UI specification.

package/templates/skills/business-analyse/steps/step-03d-validate.md

@@ -515,6 +515,90 @@ IF currentModuleIndex >= moduleOrder.length:
 
 ---
 
+## 12-bis. Agent Mode: Send Proposal to Team Lead
+
+**IF running as TEAM AGENT (autonomous mode — detected in step-03a1 MODE DETECTION):**
+
+After all validation checks PASS and module feature.json is written:
+
+### A. Build Structured Summary
+
+Read the written module feature.json via ba-reader and build:
+
+```
+## Module: {moduleCode} — Specification Summary
+
+### Entities ({count})
+| Entity | Key Attributes | Relationships |
+|--------|---------------|---------------|
+| {name} | {attr1} ({type}), {attr2} ({type}), ... | → {relatedEntity} (FK) |
+
+### Sections ({count})
+| Section | Description | Resources |
+|---------|-------------|-----------|
+| {code} | {description} | {resource1}, {resource2}, ... |
+
+### Use Cases ({count})
+- {UC-ID}: {title}
+
+### Business Rules ({count})
+- {BR-ID}: {title} ({category})
+
+### Permissions
+- {permission.path}: {roles with access}
+
+### Seed Data Counts
+- Modules: {n} | Sections: {n} | Resources: {n}
+- Translations: {n} | Permissions: {n} | Role mappings: {n} | Constants: {n}
+
+### Wireframes
+- {section}: {1-line description of layout and key components}
+```
+
+### B. Send Proposal
+
+```
+SendMessage({
+  type: "message",
+  recipient: "team-lead",
+  content: "PROPOSAL_READY:{moduleCode}\n\n{structured_summary}",
+  summary: "{moduleCode} specification ready for review"
+})
+```
+
+### C. Wait for Response
+
+**WAIT** for team lead to respond:
+
+- **`APPROVED:{moduleCode}`** → Proceed to step D (Module Complete)
+- **`REVISION:{moduleCode}\n{feedback}`** → Apply changes:
+  1. Read the feedback
+  2. Update the relevant sections in feature.json via ba-writer
+  3. Re-run validation checks (section 9)
+  4. Re-build summary and send new `PROPOSAL_READY`
+  5. Max **3 revision cycles** — after 3, send `ERROR:{moduleCode}:Max revisions reached` and stop
+
+### D. Module Complete
+
+After approval:
+
+```
+ba-writer.updateModuleStatus({feature_id}, {moduleCode}, "specified")
+```
+
+```
+SendMessage({
+  type: "message",
+  recipient: "team-lead",
+  content: "MODULE_COMPLETE:{moduleCode}",
+  summary: "{moduleCode} module complete"
+})
+```
+
+**STOP HERE** — do NOT loop to next module. The team lead handles module ordering and will spawn a new agent for the next module.
+
+---
+
 ## SELF-VERIFICATION (MANDATORY before loading next step)
 
 Before proceeding to step-03a (next module) or step-04 (consolidation), VERIFY: