@atlashub/smartstack-cli 4.18.0 → 4.20.0

package/templates/skills/{business-analyse → derive-prd}/templates/tpl-progress.md

@@ -1,172 +1,172 @@
-# Progress Tracker Template (templates/tpl-progress.md)
-
-> **Used by:** step-05b-deploy (section 2: Initialize Progress Tracker)
-> **Purpose:** Template structure for .ralph/progress.txt - populate with module-specific data
-
-## Template
-
-```
-═════════════════════════════════════════════════════════════════
-  SMARTSTACK RALPH LOOP - PROGRESS TRACKER
-  Project: {project_name} | Application: {app_name}
-  Modules: {count} ({moduleOrder.join(', ')})
-  Strategy: {implementation_strategy}
-  Created: {timestamp}
-  Status: HANDED-OFF
-═════════════════════════════════════════════════════════════════
-
-{For each module in topological order:}
-[MODULE: {module_name}] ({complexity})
-  Status: NOT STARTED
-  Dependencies: {list of module dependencies or "FOUNDATION"}
-
-  [DOMAIN] Entity & Value Object Definitions
-    □ Define {Entity1} entity with properties and validation
-    □ Define {Entity2} entity with relationships
-    □ Define {ValueObject1} value object
-    □ Define domain exceptions
-    □ Total: X tasks
-
-  [SEEDDATA-CORE] Core Configuration (MANDATORY)
-    □ NavigationApplicationSeedData - Application navigation entry (once per app)
-    □ ApplicationRolesSeedData - Application-scoped roles (once per app)
-    □ NavigationModuleSeedData - Module navigation structure (per module)
-    □ PermissionsSeedData - RBAC permissions (per module)
-    □ RolesSeedData - Role-permission mappings (per module)
-    □ {App}SeedDataProvider - IClientSeedDataProvider (4 methods)
-    Total: 2 app-level + 3 per-module + 1 provider
-
-  [SEEDDATA] Business Reference Data
-    □ Seed {Entity1} reference data
-    □ Seed {Entity2} lookup values
-    □ Total: Y business seed tasks
-
-  [APPLICATION] Services & Business Logic
-    □ Create {ServiceName}Service for {UC1}
-    □ Create {DtoName}Dto for API contracts
-    □ Create {ValidatorName}Validator for input validation
-    □ Implement query handlers
-    Total: Z tasks
-
-  [INFRASTRUCTURE] Repositories & Persistence
-    □ Create {Entity1}Repository with CRUD + custom queries
-    □ Create {Entity2}Repository
-    □ Configure DbContext for module
-    □ Setup specifications for complex queries
-    □ Create IClientSeedDataProvider (client projects ONLY - injects core seeds at runtime)
-    □ Create DevDataSeeder + SeedConstants (if first module)
-    □ Total: A tasks
-
-  [API] REST Endpoints & Controllers
-    □ Create {ModuleNameController} GET endpoints (List, GetById)
-    □ Create {ModuleNameController} POST endpoint (Create)
-    □ Create {ModuleNameController} PUT endpoint (Update)
-    □ Create {ModuleNameController} DELETE endpoint (Delete)
-    □ Implement error handling and validation responses
-    Total: B tasks
-
-  [FRONTEND] UI Components & Pages (wireframe-driven)
-    □ Create {ModuleName}Page for listing [wireframe: {module}-list]
-    □ Create {ModuleName}DetailPage for viewing [wireframe: {module}-detail]
-    □ Create {ModuleName}Form component for creation/edit [wireframe: {module}-create]
-    □ Create custom hook use{ModuleName}
-    □ Implement pagination, filtering, sorting
-    □ Validate all pages match their wireframe layout
-    □ ⚠️ Routes MUST be INSIDE the AppLayout wrapper
-    Total: C tasks
-
-  [I18N] Internationalization Keys
-    □ Define i18n keys for {Module} UI labels
-    □ Setup translations for locales: fr, en, it, de
-    Total: D keys
-
-  [TESTS] Unit & Integration Tests
-    □ Unit tests for {Entity} domain logic
-    □ Unit tests for {ServiceName}Service
-    □ Integration tests for {ModuleNameController}
-    □ Security tests for authorization & tenant isolation
-    □ E2E tests for critical user flows
-    Total: E unit + F integration + G security = H tests
-
-  [QA] Quality Assurance
-    □ Code review against SmartStack conventions
-    □ Test coverage minimum 80%
-    □ Security scan for OWASP vulnerabilities
-    □ Performance testing under load
-    Total: 4 QA tasks
-
-  Module Total: X + 5 + Y + Z + A + B + C + D + H + 4 = {module_total} tasks
-  Estimated Effort: {simple/medium/complex} - {1-3/3-8/8-15} days
-
-{If multi-module:}
-[CROSS-MODULE] Integration Tasks
-  Status: NOT STARTED
-  Dependencies: All modules COMPLETED
-
-  □ Verify cross-module entity relationships
-  □ Test cross-module API dependencies
-  □ Validate permission matrix across modules
-  □ E2E flow tests spanning multiple modules
-  □ Cross-module data consistency checks
-  □ Integration test suite for module interactions
-  Total: 6 CROSS-MODULE tasks
-
-═════════════════════════════════════════════════════════════════
-SUMMARY
-═════════════════════════════════════════════════════════════════
-Total Modules:         {count}
-Total Tasks:           {total_count}
-  - CORE SeedData:     {count} × 5 = {total_core}
-  - Business Tasks:    {total_biz}
-  - Development:       {total_dev}
-  - Tests:             {total_tests}
-  - QA:                {total_qa}
-  - Cross-Module:      {cross_module_count or 0}
-
-Strategy:              {strategy}
-Module Order:          {topological order with dependencies noted}
-
-Complexity Distribution:
-  Simple:   {count} modules ({estimate} days each)
-  Medium:   {count} modules ({estimate} days each)
-  Complex:  {count} modules ({estimate} days each)
-
-Total Effort Estimate:  {total_days} days ({total_hours} hours)
-Per Developer (2):      {total_days / 2} days
-Parallel Potential:     {strategy_efficiency_percent}%
-
-═════════════════════════════════════════════════════════════════
-LEGEND
-═════════════════════════════════════════════════════════════════
-□ = Task not started
-✓ = Task completed
-⚠ = Task in progress
-✗ = Task failed / blocked
-
-COLORS:
-[DOMAIN]      = Domain Model & Business Logic
-[SEEDDATA-CORE] = MANDATORY core configuration (5 entries)
-[SEEDDATA]    = Business reference & lookup data
-[APPLICATION] = Services, DTOs, Validators
-[INFRASTRUCTURE] = Repositories, DbContext, ORM
-[API]         = REST controllers & endpoints
-[FRONTEND]    = React pages, components, hooks
-[I18N]        = Internationalization
-[TESTS]       = Unit, Integration, Security, E2E
-[QA]          = Code quality, coverage, security
-[CROSS-MODULE] = Multi-module integration (if applicable)
-
-═════════════════════════════════════════════════════════════════
-```
-
-## Progress Tracker Rules
-
-- One section per module, in topological order (dependencies first)
-- CORE SeedData ALWAYS 5 entries (mandatory)
-- Business SeedData varies by module
-- Hierarchical task structure (module → layer → tasks)
-- Each task is independent, assignable checkbox
-- Effort estimate per module (simple/medium/complex)
-- Summary with totals across all modules
-- Identified dependencies for parallel execution
-- Cross-module tasks only if multi-module
+# Progress Tracker Template (templates/tpl-progress.md)
+
+> **Used by:** step-05-deploy (section 4: Generate progress.txt)
+> **Purpose:** Template structure for .ralph/progress.txt - populate with module-specific data
+
+## Template
+
+```
+═════════════════════════════════════════════════════════════════
+  SMARTSTACK RALPH LOOP - PROGRESS TRACKER
+  Project: {project_name} | Application: {app_name}
+  Modules: {count} ({moduleOrder.join(', ')})
+  Strategy: {implementation_strategy}
+  Created: {timestamp}
+  Status: HANDED-OFF
+═════════════════════════════════════════════════════════════════
+
+{For each module in topological order:}
+[MODULE: {module_name}] ({complexity})
+  Status: NOT STARTED
+  Dependencies: {list of module dependencies or "FOUNDATION"}
+
+  [DOMAIN] Entity & Value Object Definitions
+    □ Define {Entity1} entity with properties and validation
+    □ Define {Entity2} entity with relationships
+    □ Define {ValueObject1} value object
+    □ Define domain exceptions
+    □ Total: X tasks
+
+  [SEEDDATA-CORE] Core Configuration (MANDATORY)
+    □ NavigationApplicationSeedData - Application navigation entry (once per app)
+    □ ApplicationRolesSeedData - Application-scoped roles (once per app)
+    □ NavigationModuleSeedData - Module navigation structure (per module)
+    □ PermissionsSeedData - RBAC permissions (per module)
+    □ RolesSeedData - Role-permission mappings (per module)
+    □ {App}SeedDataProvider - IClientSeedDataProvider (4 methods)
+    Total: 2 app-level + 3 per-module + 1 provider
+
+  [SEEDDATA] Business Reference Data
+    □ Seed {Entity1} reference data
+    □ Seed {Entity2} lookup values
+    □ Total: Y business seed tasks
+
+  [APPLICATION] Services & Business Logic
+    □ Create {ServiceName}Service for {UC1}
+    □ Create {DtoName}Dto for API contracts
+    □ Create {ValidatorName}Validator for input validation
+    □ Implement query handlers
+    Total: Z tasks
+
+  [INFRASTRUCTURE] Repositories & Persistence
+    □ Create {Entity1}Repository with CRUD + custom queries
+    □ Create {Entity2}Repository
+    □ Configure DbContext for module
+    □ Setup specifications for complex queries
+    □ Create IClientSeedDataProvider (client projects ONLY - injects core seeds at runtime)
+    □ Create DevDataSeeder + SeedConstants (if first module)
+    □ Total: A tasks
+
+  [API] REST Endpoints & Controllers
+    □ Create {ModuleNameController} GET endpoints (List, GetById)
+    □ Create {ModuleNameController} POST endpoint (Create)
+    □ Create {ModuleNameController} PUT endpoint (Update)
+    □ Create {ModuleNameController} DELETE endpoint (Delete)
+    □ Implement error handling and validation responses
+    Total: B tasks
+
+  [FRONTEND] UI Components & Pages (wireframe-driven)
+    □ Create {ModuleName}Page for listing [wireframe: {module}-list]
+    □ Create {ModuleName}DetailPage for viewing [wireframe: {module}-detail]
+    □ Create {ModuleName}Form component for creation/edit [wireframe: {module}-create]
+    □ Create custom hook use{ModuleName}
+    □ Implement pagination, filtering, sorting
+    □ Validate all pages match their wireframe layout
+    □ ⚠️ Routes MUST be INSIDE the AppLayout wrapper
+    Total: C tasks
+
+  [I18N] Internationalization Keys
+    □ Define i18n keys for {Module} UI labels
+    □ Setup translations for locales: fr, en, it, de
+    Total: D keys
+
+  [TESTS] Unit & Integration Tests
+    □ Unit tests for {Entity} domain logic
+    □ Unit tests for {ServiceName}Service
+    □ Integration tests for {ModuleNameController}
+    □ Security tests for authorization & tenant isolation
+    □ E2E tests for critical user flows
+    Total: E unit + F integration + G security = H tests
+
+  [QA] Quality Assurance
+    □ Code review against SmartStack conventions
+    □ Test coverage minimum 80%
+    □ Security scan for OWASP vulnerabilities
+    □ Performance testing under load
+    Total: 4 QA tasks
+
+  Module Total: X + 5 + Y + Z + A + B + C + D + H + 4 = {module_total} tasks
+  Estimated Effort: {simple/medium/complex} - {1-3/3-8/8-15} days
+
+{If multi-module:}
+[CROSS-MODULE] Integration Tasks
+  Status: NOT STARTED
+  Dependencies: All modules COMPLETED
+
+  □ Verify cross-module entity relationships
+  □ Test cross-module API dependencies
+  □ Validate permission matrix across modules
+  □ E2E flow tests spanning multiple modules
+  □ Cross-module data consistency checks
+  □ Integration test suite for module interactions
+  Total: 6 CROSS-MODULE tasks
+
+═════════════════════════════════════════════════════════════════
+SUMMARY
+═════════════════════════════════════════════════════════════════
+Total Modules:         {count}
+Total Tasks:           {total_count}
+  - CORE SeedData:     {count} × 5 = {total_core}
+  - Business Tasks:    {total_biz}
+  - Development:       {total_dev}
+  - Tests:             {total_tests}
+  - QA:                {total_qa}
+  - Cross-Module:      {cross_module_count or 0}
+
+Strategy:              {strategy}
+Module Order:          {topological order with dependencies noted}
+
+Complexity Distribution:
+  Simple:   {count} modules ({estimate} days each)
+  Medium:   {count} modules ({estimate} days each)
+  Complex:  {count} modules ({estimate} days each)
+
+Total Effort Estimate:  {total_days} days ({total_hours} hours)
+Per Developer (2):      {total_days / 2} days
+Parallel Potential:     {strategy_efficiency_percent}%
+
+═════════════════════════════════════════════════════════════════
+LEGEND
+═════════════════════════════════════════════════════════════════
+□ = Task not started
+✓ = Task completed
+⚠ = Task in progress
+✗ = Task failed / blocked
+
+COLORS:
+[DOMAIN]      = Domain Model & Business Logic
+[SEEDDATA-CORE] = MANDATORY core configuration (5 entries)
+[SEEDDATA]    = Business reference & lookup data
+[APPLICATION] = Services, DTOs, Validators
+[INFRASTRUCTURE] = Repositories, DbContext, ORM
+[API]         = REST controllers & endpoints
+[FRONTEND]    = React pages, components, hooks
+[I18N]        = Internationalization
+[TESTS]       = Unit, Integration, Security, E2E
+[QA]          = Code quality, coverage, security
+[CROSS-MODULE] = Multi-module integration (if applicable)
+
+═════════════════════════════════════════════════════════════════
+```
+
+## Progress Tracker Rules
+
+- One section per module, in topological order (dependencies first)
+- CORE SeedData ALWAYS 5 entries (mandatory)
+- Business SeedData varies by module
+- Hierarchical task structure (module → layer → tasks)
+- Each task is independent, assignable checkbox
+- Effort estimate per module (simple/medium/complex)
+- Summary with totals across all modules
+- Identified dependencies for parallel execution
+- Cross-module tasks only if multi-module

package/templates/skills/documentation/SKILL.md

@@ -22,10 +22,17 @@ Works in synergy with the `/documentation module` command.
 <quick_start>
 ## WHEN THIS SKILL ACTIVATES
 
+### PREREQUISITE — ONLY post-implementation
+This skill requires the feature page to already exist (generated by /ralph-loop).
+It reads real TSX pages, controllers, and entities. Without them, nothing to document.
+
+→ For reviewing/editing the analysis BEFORE implementation: use ba-interactive.html (/business-analyse step-05)
+
 Claude automatically invokes this skill when it detects:
 
 | Trigger | Example |
 |---------|---------|
+| ❌ NEVER during BA | Before /ralph-loop — feature page does not exist yet |
 | Explicit request | "Document the SLA module" |
 | Documentation mention | "We should create the doc for..." |
 | After implementation | "The feature is done, generate the doc" |

package/templates/skills/ralph-loop/SKILL.md

@@ -5,7 +5,7 @@ argument-hint: "[-m N] [-c TEXT] [-v] <task description>"
 ---
 
 <objective>
-Execute the Ralph Weegund technique — iterative module orchestration. Ralph reads PRDs from `/business-analyse`, resolves task dependencies, and delegates all code generation to `/apex -d`. Uses progress persistence and Agent Teams for multi-module parallelization.
+Execute the Ralph Weegund technique — iterative module orchestration. Ralph reads PRDs from `/derive-prd`, resolves task dependencies, and delegates all code generation to `/apex -d`. Uses progress persistence and Agent Teams for multi-module parallelization.
 
 **Key principle:** Ralph ORCHESTRATES (task selection, module sequencing, PRD state, reporting). All code generation is delegated to `/apex`.
 </objective>
@@ -15,6 +15,7 @@ Execute the Ralph Weegund technique — iterative module orchestration. Ralph re
 **From Business Analysis (RECOMMENDED):**
 ```bash
 /business-analyse MyFeature
+# Then: /derive-prd
 # Then: /ralph-loop -r
 ```
 

package/templates/skills/ralph-loop/references/init-resume-recovery.md

@@ -109,7 +109,7 @@ if (handoffStatus === 'handed-off') {
   // BA handoff NOT complete
   console.warn(`⚠ BA handoff status: "${handoffStatus}" (expected "handed-off")`);
   console.warn('Cannot auto-recover PRD files without complete handoff');
-  console.warn('Run /business-analyse to complete the handoff, then retry /ralph-loop');
+  console.warn('Run /derive-prd to generate the handoff, then retry /ralph-loop');
   STOP;
 }
 ```

package/templates/skills/ralph-loop/steps/step-01-task.md

@@ -83,13 +83,13 @@ if (!sourceFeatureJson) {
   if (handoff.status !== 'handed-off') {
     console.error(`BLOCKING: BA HANDOFF INCOMPLETE
 handoff.status = "${handoff.status || 'missing'}" (expected "handed-off")
-Run /business-analyse to complete the handoff, then re-run /ralph-loop.`);
+Run /derive-prd to generate the handoff, then re-run /ralph-loop.`);
     STOP;
   }
 
   // CHECK 2: filesToCreate must have all categories
   const filesToCreate = handoff.filesToCreate || {};
-  const requiredCategories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests'];
+  const requiredCategories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests', 'documentation'];
   const missingInHandoff = requiredCategories.filter(c => !filesToCreate[c] || filesToCreate[c].length === 0);
 
   if (missingInHandoff.length > 0) {

package/templates/skills/apex/references/agent-teams-protocol.md

@@ -1,203 +0,0 @@
-# Agent Teams Protocol — APEX
-
-> **Loaded by:** step-01 (analysis scan) and step-03 (parallel execution)
-> **Condition:** NOT economy_mode
-> **Purpose:** Reusable protocol for TeamCreate, coordination, and shutdown.
-
----
-
-## Team Creation (T08)
-
-```yaml
-TeamCreate:
-  team_name: "apex-{phase}"          # e.g., "apex-analyze", "apex-layer2", "apex-layer3"
-  description: "{phase purpose}"      # e.g., "Scan SmartStack project for existing code"
-```
-
-Always provide both `team_name` and `description`.
-
----
-
-## Teammate Spawning (T12)
-
-```yaml
-Task:
-  subagent_type: "Explore" | "general-purpose"  # See assignment table below
-  team_name: "apex-{phase}"          # Must match TeamCreate
-  name: "{teammate-name}"            # e.g., "scan-backend", "entity-employee"
-  model: "sonnet" | "opus"           # sonnet for scan, opus for dev (T02/T06)
-  mode: "bypassPermissions"
-  prompt: "{detailed task prompt}"
-```
-
-### Model & Agent Assignment (T02/T03/T06)
-
-| Task Type | subagent_type | Model | Justification |
-|-----------|---------------|-------|---------------|
-| Scan/read files | Explore | Sonnet | Read-only (Glob, Grep, Read) |
-| Read context (PRD, feature.json) | Explore | Sonnet | Read-only extraction |
-| Code development | general-purpose | Opus | Full tools via skills/MCP |
-| Fix/resolve | general-purpose | Opus | Requires reasoning + editing |
-
----
-
-## Task List Coordination (T10)
-
-### Task Creation (by team lead, BEFORE spawning teammates)
-
-Tasks MUST be created upfront for the full layer scope:
-
-```
-FOR EACH entity in layer:
-  TaskCreate(
-    subject: "Layer {N}: {Entity} {layer_type}",
-    description: "{detailed scope: files, skills, MCP tools}",
-    activeForm: "{Building/Creating} {Entity} {layer_type}"
-  )
-```
-
-### Task Assignment (by team lead, WHEN spawning)
-
-Include task ID and metadata context in teammate prompt:
-
-```
-"Your assigned task ID is {task_id}.
- Your metadata context: entities={entities}, layer={layer}, tools={tools}.
- Call TaskUpdate(taskId: '{task_id}', status: 'in_progress') before starting.
- Call TaskUpdate(taskId: '{task_id}', status: 'completed', metadata: { files_created: [...] }) after ENTITY_COMPLETE message."
-```
-
-### Task Monitoring (by team lead)
-
-```
-1. TaskList() — check progress after each teammate message
-2. All tasks completed → proceed to build gate
-3. Any task stuck → investigate, reassign if needed
-```
-
----
-
-## Communication (T09)
-
-**Default:** Direct messages (DM) between specific agents.
-
-```yaml
-SendMessage:
-  type: "message"                    # DM, not broadcast
-  recipient: "{teammate-name}"       # By name, not UUID
-  content: "{message}"
-  summary: "{5-10 word preview}"
-```
-
-**Broadcast:** ONLY for emergency (all-stop, critical blocker).
-
-```yaml
-SendMessage:
-  type: "broadcast"                  # Expensive: N teammates = N deliveries
-  content: "{urgent message}"
-  summary: "{critical issue summary}"
-```
-
----
-
-## Team Decomposition (C01)
-
-### Step-01 Analyze: Split by scan scope
-
-```
-scan-backend  : Domain/ + Infrastructure/ + Application/ + Api/
-scan-frontend : src/pages/ + src/components/ + src/locales/
-scan-context  : .ralph/ + docs/business/
-```
-
-### Step-03 Execute: Split by entity WITHIN a layer
-
-> **Cross-layer parallelism is FORBIDDEN.** Layers execute sequentially: 0 → 1 → 2 → 3 → 4.
-> Agent teams parallelize **multi-entity work within a single layer.**
-
-```
-Layer 2 (Backend) — if multiple entities:
-  entity-{name1} : Service + DTO + Controller for Entity1
-  entity-{name2} : Service + DTO + Controller for Entity2
-  ...
-
-Layer 3 (Frontend) — if multiple entities:
-  entity-{name1} : Pages + i18n + routes for Entity1
-  entity-{name2} : Pages + i18n + routes for Entity2
-  ...
-```
-
-Each teammate has an **isolated scope** (C02): handles one entity end-to-end within the layer.
-
----
-
-## Coordination (C03)
-
-### Step-01: Lead aggregates scan results
-
-```
-1. Spawn 3 scan teammates
-2. Each reports findings via DM to lead
-3. Lead merges into unified analysis
-```
-
-### Step-03: Lead verifies between ALL 5 layers
-
-```
-1. Layer 0: lead executes (domain + infra + migration)
-2. Build gate: dotnet build → MUST PASS
-3. Layer 1: lead executes (seed data — sequential, no teams)
-4. Build gate: dotnet build → MUST PASS
-5. Layer 2: spawn entity teammates (if multi-entity) OR lead executes (if single entity)
-6. Build gate: dotnet build → MUST PASS
-7. Backend tests inline (scaffold + run + fix max 3)
-8. Layer 3: spawn entity teammates (if multi-entity) OR lead executes (if single entity)
-9. Compliance gate: 5 frontend checks → MUST PASS
-10. Frontend tests inline (scaffold + run + fix max 3)
-11. Layer 4 (optional): lead executes DevData
-```
-
----
-
-## Idle Handling (T13)
-
-Teammates go idle after every turn — this is **normal**.
-- Idle does NOT mean done or unavailable
-- Sending a message to an idle teammate wakes them up
-- Do NOT treat idle as an error
-
----
-
-## Graceful Shutdown (T11)
-
-After phase completes:
-
-```yaml
-# For each teammate:
-SendMessage:
-  type: "shutdown_request"
-  recipient: "{teammate-name}"
-  content: "Phase complete, shutting down"
-
-# Teammate responds:
-SendMessage:
-  type: "shutdown_response"
-  request_id: "{from_request}"
-  approve: true
-
-# After all confirmations:
-TeamDelete
-```
-
----
-
-## Decision Matrix
-
-| Condition | Action |
-|-----------|--------|
-| economy_mode = true | NO teams, all sequential |
-| Single entity (any layer) | NO teams, agent principal handles all |
-| Multiple entities, Layer 2 | Teams: one teammate per entity (service + controller) |
-| Multiple entities, Layer 3 | Teams: one teammate per entity (pages + i18n) |
-| Layer 0, Layer 1, Layer 4 | NO teams (sequential by nature) |
-| Analysis phase (step-01) | Teams: scan-backend + scan-frontend + scan-context |