@atlashub/smartstack-cli 3.29.0 → 3.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "3.29.0",
+  "version": "3.31.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

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

@@ -287,8 +287,8 @@ Load ONLY relevant categories based on feature type:
 
 **Team mode workflow (Propose & Review):**
 1. Steps 00-02 execute inline in the main conversation (interactive with user)
-2. After step-02 decomposition: `TeamCreate({ team_name: "ba-{appName}" })`
-3. For each module: spawn autonomous agent, agent proposes complete specification, team lead presents to user for validation
+2. After step-02 decomposition: clean up old team data (§1a), then `TeamCreate({ team_name: "ba-{appName}" })` — **CRITICAL: capture the RETURNED team name** (may differ from requested)
+3. For each module: spawn autonomous agent using the **returned** team name, agent proposes complete specification, team lead presents to user for validation
 4. After all modules specified: spawn consolidation agent (steps 04a + 04b), present report for user approval (04c)
 5. After consolidation approved: spawn handoff agent (steps 05a + 05b + 05c)
 6. `TeamDelete()` cleanup

package/templates/skills/business-analyse/references/agent-module-prompt.md

@@ -24,12 +24,17 @@ Your mission: specify module "{moduleCode}" completely and autonomously.
 ## Mode: PROPOSE & REVIEW (Autonomous)
 
 You work WITHOUT user interaction:
-- Do NOT use AskUserQuestion — you make all decisions autonomously
+- **ABSOLUTE PROHIBITION: NEVER use AskUserQuestion** — not in ANY step (03a1, 03a2, 03b, 03c, 03d)
+- The step files you load contain AskUserQuestion calls — these are for INLINE MODE ONLY
+- When you see `AskUserQuestion` in a step file → replace with ULTRATHINK autonomous decision
+- When you see `Ask via AskUserQuestion` → decide autonomously based on context
+- When you see validation options (Auto-corriger, Réviser, etc.) → auto-correct silently
 - Use ULTRATHINK to reason about every design choice
 - Base decisions on the context below + SmartStack conventions
 - Write the specification to feature.json via ba-writer operations
 - Send a structured proposal summary to the team lead when done
 - Wait for approval or revision feedback
+- In step-03d: SKIP section 12 (Loop Decision) entirely → go to section 12-bis (Agent Mode)
 
 ## Module Context
 
@@ -223,7 +228,29 @@ SendMessage({
   summary: "{moduleCode} module complete"
 })
 
-Then STOP — do not proceed to next module. The team lead handles ordering.
+Then WAIT for the team lead to send you a `shutdown_request`.
+Do NOT proceed to next module — the team lead handles module ordering.
+
+### Shutdown handling (MANDATORY):
+
+When you receive a message with `type: "shutdown_request"` from the team lead:
+→ Extract the `requestId` from the JSON message
+→ IMMEDIATELY respond with:
+
+```
+SendMessage({
+  type: "shutdown_response",
+  request_id: "{requestId from the shutdown_request}",
+  approve: true
+})
+```
+
+This terminates your process. Do NOT output any text after sending `shutdown_response`.
+
+**IMPORTANT:** Do NOT confuse APPROVED with shutdown. The sequence is:
+1. Team lead sends `APPROVED:{moduleCode}` → you update status + send `MODULE_COMPLETE`
+2. Team lead sends `shutdown_request` → you respond with `shutdown_response approve: true` → you terminate
+These are TWO separate steps. Never try to self-terminate or call `shutdown_response` without a `shutdown_request`.
 
 ## ID Naming Convention
 

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

@@ -10,14 +10,34 @@
 
 After step-02 decomposition is complete and client has approved the module structure:
 
+### 1a. Clean Up Old Team Data (MANDATORY)
+
+Before creating the team, clean up any leftover data from previous sessions to prevent stale task collisions:
+
+```bash
+# Remove leftover task files from previous runs
+rm -f ~/.claude/tasks/ba-{appName}/*.json 2>/dev/null
+# Remove leftover team directory (TeamDelete may leave remnants)
+rm -rf ~/.claude/teams/ba-{appName} 2>/dev/null
 ```
-TeamCreate({ team_name: "ba-{appName}" })
+
+> **Why:** If a previous session used the same team name and crashed or was interrupted,
+> leftover task files will be picked up by new agents, causing them to receive stale
+> task_assignment notifications for wrong modules.
+
+### 1b. Create Team and Capture Actual Name
+
+```javascript
+const result = TeamCreate({ team_name: "ba-{appName}" });
+// CRITICAL: TeamCreate may return a DIFFERENT name than requested!
+// Always use the RETURNED team_name, not the requested one.
+const actualTeamName = result.team_name;
 ```
 
 Store team context for the session:
 ```javascript
 const teamContext = {
-  teamName: "ba-{appName}",
+  teamName: actualTeamName, // ← RETURNED name, NOT "ba-{appName}"
   moduleOrder: metadata.workflow.moduleOrder,
   dependencyLayers: dependencyGraph.layers || null,
   currentModuleIdx: 0,
@@ -26,6 +46,9 @@ const teamContext = {
 };
 ```
 
+> **WARNING:** NEVER hardcode `"ba-{appName}"` in subsequent calls.
+> Always use `teamContext.teamName` (the actual name returned by TeamCreate).
+
 ---
 
 ## 2. Module Agent Spawn — Sequential by Topological Order
@@ -54,7 +77,7 @@ Before spawning, gather the context the agent needs:
 ```javascript
 Task({
   subagent_type: "general-purpose",
-  team_name: "ba-{appName}",
+  team_name: teamContext.teamName, // ← ACTUAL name from TeamCreate result
   name: "mod-{moduleCode}",
   model: "opus",
   mode: "bypassPermissions",
@@ -85,13 +108,21 @@ Task({
 - 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
 
+### 2d. After Spawning — Wait for Agent Message
+
+After calling `Task()` to spawn the module agent, the team lead **MUST WAIT** for the agent to send a message.
+Messages from teammates are delivered automatically — do NOT poll or re-spawn.
+
+The agent will send `PROPOSAL_READY:{moduleCode}` when its specification is complete.
+This may take several minutes. The team lead does nothing until the message arrives.
+
 ---
 
 ## 3. Propose & Review Protocol
 
 ### 3a. Team Lead Receives PROPOSAL_READY
 
-After the agent finishes specifying a module, it sends:
+The module agent sends this message when specification is complete:
 
 ```
 PROPOSAL_READY:{moduleCode}
@@ -130,9 +161,9 @@ PROPOSAL_READY:{moduleCode}
 - ...
 ```
 
-### 3b. Team Lead Presents to User
+### 3b. Present to User and Handle Response
 
-Format the proposal for user review:
+**Step 1:** Format and display the proposal:
 
 ```
 ═══════════════════════════════════════════════════════════
@@ -144,7 +175,7 @@ Format the proposal for user review:
 ─────────────────────────────────────────────────────────
 ```
 
-Then ask user via AskUserQuestion:
+**Step 2:** Ask the user via AskUserQuestion:
 
 ```
 Validez-vous cette specification ?
@@ -154,9 +185,9 @@ Options:
   3. "Voir detail" → team lead reads module feature.json and displays full content
 ```
 
-### 3c. Approval Flow
+**Step 3 — IMMEDIATELY after AskUserQuestion returns, handle the response:**
 
-**If user approves:**
+**IF user selected "Valider" (approve):**
 ```
 SendMessage({
   type: "message",
@@ -165,9 +196,12 @@ SendMessage({
   summary: "{moduleCode} approved by user"
 })
 ```
-→ Agent writes final status, sends MODULE_COMPLETE, and shuts down.
+→ CRITICAL: You MUST send this message. Do NOT skip this step.
+→ Then WAIT for the agent to send `MODULE_COMPLETE:{moduleCode}` (see §4).
 
-**If user requests modifications:**
+**IF user selected "Modifier" (revision):**
+→ Ask user for specific feedback via AskUserQuestion
+→ Then send:
 ```
 SendMessage({
   type: "message",
@@ -176,14 +210,14 @@ SendMessage({
   summary: "{moduleCode} revision requested"
 })
 ```
-→ Agent applies changes, re-validates, sends new PROPOSAL_READY.
+→ Then WAIT for the agent to send a new `PROPOSAL_READY` → go back to Step 1.
 
-**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
+**IF user selected "Voir detail":**
+→ Read module feature.json via ba-reader.readSection({feature_id, section})
+→ Display relevant sections in detail
+→ Go back to Step 2 (re-ask the validation question)
 
-### 3d. Revision Limits
+### 3c. 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
@@ -192,30 +226,42 @@ SendMessage({
 
 ---
 
-## 4. Module Completion & Advancement
+## 4. Module Completion & Agent Shutdown
+
+When the team lead receives `MODULE_COMPLETE:{moduleCode}` from the agent, execute these steps **IN ORDER**:
 
-When agent sends MODULE_COMPLETE:
+### 4a. Update Tracking
 
 ```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})"
+```
+
+### 4b. Shutdown Agent (MANDATORY — do NOT skip)
+
+**IMMEDIATELY** after receiving MODULE_COMPLETE, send shutdown_request to terminate the agent:
 
-// Shutdown agent
+```
 SendMessage({
   type: "shutdown_request",
   recipient: "mod-{moduleCode}",
   content: "Module complete, shutting down"
-});
+})
 ```
 
+The agent will respond with `shutdown_response approve: true` and terminate.
+**Wait for the agent to confirm shutdown** before spawning the next agent.
+
+> **WARNING:** If you skip this step, the agent will remain running indefinitely.
+> The agent CANNOT self-terminate — it NEEDS this shutdown_request from you.
+
+### 4c. Next Module or Consolidation
+
 If more modules remain → spawn next module agent (go to §2).
 If all modules complete → proceed to §5 (Consolidation).
 
@@ -234,7 +280,7 @@ Display: "═══ All modules specified — Starting consolidation ═══"
 ```javascript
 Task({
   subagent_type: "general-purpose",
-  team_name: "ba-{appName}",
+  team_name: teamContext.teamName, // ← ACTUAL name from TeamCreate result
   name: "consolidation",
   model: "opus",
   mode: "bypassPermissions",
@@ -293,7 +339,7 @@ After approval → shutdown consolidation agent → proceed to §6.
 ```javascript
 Task({
   subagent_type: "general-purpose",
-  team_name: "ba-{appName}",
+  team_name: teamContext.teamName, // ← ACTUAL name from TeamCreate result
   name: "handoff",
   model: "sonnet",
   mode: "bypassPermissions",
@@ -346,13 +392,21 @@ Display final status to user. If quality gate PASS → ready for /ralph-loop.
 After handoff complete:
 
 ```javascript
-// Shutdown any remaining agents
-for (const agentName of ["consolidation", "handoff"]) {
+// Safety net: shutdown ALL remaining agents (module agents + consolidation + handoff)
+// Module agents should already be shut down in §4b, but this catches any missed ones.
+const allAgents = [
+  ...teamContext.moduleOrder.map(m => `mod-${m}`),
+  "consolidation",
+  "handoff"
+];
+
+for (const agentName of allAgents) {
   SendMessage({
     type: "shutdown_request",
     recipient: agentName,
     content: "Workflow complete"
   });
+  // Ignore errors for already-terminated agents
 }
 
 // Delete team
@@ -361,6 +415,9 @@ TeamDelete();
 Display: "═══ Business-analyse complete — Team cleaned up ═══"
 ```
 
+> **Note:** Sending shutdown_request to an already-terminated agent is harmless.
+> This safety net ensures no orphan agents remain running.
+
 ---
 
 ## 8. Error Recovery
@@ -402,8 +459,9 @@ 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
+4. **Cleans up old team/task data** (§1a cleanup step) before creating new team
+5. Creates new team (§1b — captures actual team name), spawns agent for next incomplete module
+6. Continues normally
 
 ---
 

package/templates/skills/business-analyse/steps/step-03a2-analysis.md

@@ -17,6 +17,18 @@ next_step: steps/step-03b-ui.md
 - **ID NAMING RULE:** All IDs MUST include module prefix (BR-{CAT}-{PREFIX}-{NNN}, OBJ-{PREFIX}-{NNN}, etc.)
 - **SCHEMA CONFORMITY RULE:** ALL data MUST fit within feature-schema.json structure
 
+## MODE DETECTION (inherited from step-03a1)
+
+> **CRITICAL: Re-check your execution mode before proceeding.**
+
+**IF you are running as a TEAM AGENT** (your prompt contains `PROPOSE & REVIEW` or `team-lead` as recipient):
+  → **NEVER** use `AskUserQuestion` — replace ALL user interactions with ULTRATHINK autonomous decisions
+  → You are in autonomous mode — make all choices based on decomposition data + SmartStack conventions
+  → Do NOT present options to the user — you PROPOSE to the team lead via SendMessage, not to the user
+
+**IF you are running in the MAIN CONVERSATION** (classic inline mode):
+  → Normal interactive mode — use `AskUserQuestion` as documented below
+
 ## YOUR TASK
 
 Define the module's analysis section: objectives, entities (with attributes and relationships), business rules, process flow, and data lifecycle.

package/templates/skills/business-analyse/steps/step-03b-ui.md

@@ -14,6 +14,18 @@ next_step: steps/step-03c-compile.md
 - ALWAYS use ULTRATHINK mode
 - This step is EXECUTED ONCE PER MODULE, after step-03a1-setup.md and step-03a2-analysis.md
 - **WIREFRAME RULE:** Every section MUST have a wireframe in `specification.uiWireframes[]`. No section without a validated mockup.
+
+## MODE DETECTION (inherited from step-03a1)
+
+> **CRITICAL: Re-check your execution mode before proceeding.**
+
+**IF you are running as a TEAM AGENT** (your prompt contains `PROPOSE & REVIEW` or `team-lead` as recipient):
+  → **NEVER** use `AskUserQuestion` — replace ALL wireframe validations with ULTRATHINK self-review
+  → Generate wireframes autonomously, self-validate them, move on
+  → Do NOT ask the user to validate mockups — the team lead handles review after PROPOSAL_READY
+
+**IF you are running in the MAIN CONVERSATION** (classic inline mode):
+  → Normal interactive mode — display wireframes then ask for validation via `AskUserQuestion`
 - **ID NAMING RULE (MANDATORY, NO EXCEPTION):**
   All IDs MUST include a module prefix to guarantee application-wide uniqueness.
   The prefix is derived from the module code initials (2-4 chars):

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

@@ -15,6 +15,21 @@ next_step: steps/step-03a1-setup.md OR steps/step-04a-collect.md (conditional)
 - This step VALIDATES the specification from step-03c, writes it to feature.json, and decides loop continuation
 - ALWAYS verify specification completeness before writing
 - ALL communication in `{language}`
+
+## MODE DETECTION (inherited from step-03a1)
+
+> **CRITICAL: Re-check your execution mode before proceeding.**
+
+**IF you are running as a TEAM AGENT** (your prompt contains `PROPOSE & REVIEW` or `team-lead` as recipient):
+  → **NEVER** use `AskUserQuestion` in ANY section below (sections 9d, 10, 12)
+  → Section 9d: if validation fails, AUTO-CORRECT silently (no user options)
+  → Section 12: **SKIP ENTIRELY** — go directly to section 12-bis (Agent Mode)
+  → After writing feature.json, send `PROPOSAL_READY` to team lead via SendMessage
+  → NEVER present options/menus to the user — you are an autonomous agent
+
+**IF you are running in the MAIN CONVERSATION** (classic inline mode):
+  → Normal interactive mode — use `AskUserQuestion` as documented
+  → Section 12-bis does NOT apply to you
 - **ID NAMING RULE (MANDATORY, NO EXCEPTION):**
   All IDs MUST include a module prefix to guarantee application-wide uniqueness.
   The prefix is derived from the module code initials (2-4 chars):
@@ -167,6 +182,10 @@ if (entityAutoFixCount > 0) {
 
 #### 9d. Decision
 
+> **TEAM AGENT MODE:** If running as team agent, SKIP AskUserQuestion. On FAIL → auto-correct silently. On PASS → proceed directly to section 11 (write). NEVER present options to the user.
+
+**INLINE MODE ONLY (main conversation):**
+
 IF validation PASS:
   Display summary, ask client for confirmation
 
@@ -482,6 +501,10 @@ Uses the **same mapping** as step-05b-deploy.md — only difference is `moduleSp
 
 ### 12. Loop Decision
 
+> **TEAM AGENT MODE: SKIP THIS ENTIRE SECTION.** If you are a team agent (your prompt contains `PROPOSE & REVIEW`), go directly to **section 12-bis** below. Section 12 is for inline mode ONLY. You MUST NOT load the next step or advance the module loop — the team lead handles orchestration.
+
+**INLINE MODE ONLY (main conversation):**
+
 ```
 ba-writer.advanceModuleLoop({feature_id})
 → Increments currentModuleIndex
@@ -595,7 +618,24 @@ SendMessage({
 })
 ```
 
-**STOP HERE** — do NOT loop to next module. The team lead handles module ordering and will spawn a new agent for the next module.
+Then WAIT — the team lead will send you a `shutdown_request`.
+Do NOT loop to next module. The team lead handles module ordering and will spawn a new agent for the next module.
+
+### E. Shutdown (MANDATORY)
+
+When you receive a `shutdown_request` from the team lead:
+
+```
+SendMessage({
+  type: "shutdown_response",
+  request_id: "{requestId from the shutdown_request message}",
+  approve: true
+})
+```
+
+This terminates your process. Do NOT output any text after `shutdown_response`.
+
+**Sequence reminder:** APPROVED → MODULE_COMPLETE → shutdown_request → shutdown_response (4 separate steps, never skip).
 
 ---