@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/ralph-loop/steps/step-00-init.md

@@ -1,150 +1,150 @@
----
-name: step-00-init
-description: Initialize Ralph loop - parse args, verify MCP, setup state
-next_step: steps/step-01-task.md
----
-
-# Step 0: Initialization
-
-## MANDATORY RULES:
-
-- **FULLY AUTONOMOUS** — execute ALL tasks without stopping or asking the user
-- NEVER skip MCP verification
-- ALWAYS parse ALL flags before any action
-- ONLY check resume if -r flag is set
-- **NEVER ask the user** to choose a mode, confirm execution, or select options
-- **NEVER set max_iterations = 1** — unless the user explicitly passed `-m 1`
-- **Multi-module (2+ modules):** Use Agent Teams for parallel execution
-
-## YOUR TASK:
-
-Initialize the Ralph loop: parse flags, verify MCP, setup environment, detect multi-module.
-
----
-
-## 1. Parse Flags
-
-```yaml
-Defaults:
-  max_iterations: 50
-  completion_promise: null
-  verbose_mode: false
-  resume_mode: false
-  parallel_mode: false
-
-Flags:
-  -m N / --max-iterations N → {max_iterations} = N
-  -c TEXT / --completion-promise TEXT → {completion_promise} = TEXT
-  -v / --verbose → {verbose_mode} = true
-  -r / --resume → {resume_mode} = true
-  -p / --parallel → {parallel_mode} = true
-  Remainder → {task_description}
-```
-
-**If `-p`:** set parallel_mode = true. Ralph executes Phase 0 (entities) sequentially, then spawns parallel teammates.
-
-## 2. Verify MCP (MANDATORY)
-
-```
-mcp__smartstack__validate_conventions: checks: ["all"] → {mcp_smartstack} = true/false
-mcp__context7__resolve-library-id: libraryName: "test" → {mcp_context7} = true/false
-```
-
-If ANY fails: show error, suggest `smartstack check-mcp`, STOP.
-
-## 3. Execution Mode (FULLY AUTONOMOUS)
-
-Ralph-loop is FULLY AUTONOMOUS by default. It executes ALL tasks from start to finish WITHOUT stopping.
-
-**DO NOT** ask the user to confirm, choose a mode, or approve execution.
-**DO NOT** set max_iterations = 1 or any reduced value.
-
-The loop runs autonomously until:
-- ALL tasks are completed (success)
-- max_iterations is reached (user set via `-m N`)
-- Dead-end detected (all remaining blocked/failed)
-- User Ctrl+C (external interrupt)
-
-### Speed Warning (informational only)
-
-If tests are slow (>30s in logs), display warning but **continue execution**:
-```
-⚠ Slow tests detected. Consider disabling E2E during ralph-loop.
-```
-
-## 4. Resume or Initialize
-
-See `references/init-resume-recovery.md` for complete Resume Mode and Auto-Recovery logic.
-
-**Quick:**
-- If `-r` flag: restore state from .ralph/prd.json
-- Else if BA artifacts exist: auto-recover PRDs via `ss derive-prd`
-- Else: fresh start
-
----
-
-## 4b. Detect Multi-Module PRDs
-
-See `references/multi-module-queue.md` for queue initialization.
-
-Quick: `glob('.ralph/prd-*.json').length > 1` → create modules-queue.json
-
----
-
-## 4c. Team Orchestration (multi-module, 2+ modules)
-
-```javascript
-if (PRD_COUNT > 1) {
-  // Read references/team-orchestration.md for full protocol
-  const layers = master.metadata?.workflow?.dependencyGraph?.layers;
-
-  if (layers) {
-    // PARALLEL MODE: Use Agent Teams
-    TeamCreate({ team_name: `ralph-${appName}` });
-    // Spawn teammates per layer (see reference)
-    // STOP here — team orchestration takes over
-    return;
-  }
-  // If no layers: fall through to sequential mode
-}
-```
-
----
-
-## 5. Completion Promise (auto-set)
-
-```javascript
-if (!completion_promise) {
-  completion_promise = "COMPLETE";
-}
-// Output ONLY when ALL tasks done
-```
-
-## 6. Collect Metadata
-
-```bash
-CLI_VERSION=$(node -e "console.log(require('package.json').version)" 2>/dev/null || echo "unknown")
-CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
-PROJECT_PATH=$(pwd)
-```
-
-```javascript
-{metadata} = {
-  cli_version: CLI_VERSION,
-  branch: CURRENT_BRANCH,
-  project_path: PROJECT_PATH,
-  mcp_servers: { smartstack: {mcp_smartstack}, context7: {mcp_context7} }
-}
-```
-
-## 7. Show Summary
-
-```
-RALPH LOOP INITIALIZED
-Task: {task_description} | Max: {max_iterations} | Promise: {completion_promise}
-MCP: Ready | Branch: {branch} | Schema: v3.0.0
-{modules_queue ? `Modules: ${totalModules} (${module_codes.join(' → ')})` : 'Mode: single module'}
--> Loading tasks...
-```
-
-**Proceed directly to step-01-task.md**
+---
+name: step-00-init
+description: Initialize Ralph loop - parse args, verify MCP, setup state
+next_step: steps/step-01-task.md
+---
+
+# Step 0: Initialization
+
+## MANDATORY RULES:
+
+- **FULLY AUTONOMOUS** — execute ALL tasks without stopping or asking the user
+- NEVER skip MCP verification
+- ALWAYS parse ALL flags before any action
+- ONLY check resume if -r flag is set
+- **NEVER ask the user** to choose a mode, confirm execution, or select options
+- **NEVER set max_iterations = 1** — unless the user explicitly passed `-m 1`
+- **Multi-module (2+ modules):** Use Agent Teams for parallel execution
+
+## YOUR TASK:
+
+Initialize the Ralph loop: parse flags, verify MCP, setup environment, detect multi-module.
+
+---
+
+## 1. Parse Flags
+
+```yaml
+Defaults:
+  max_iterations: 50
+  completion_promise: null
+  verbose_mode: false
+  resume_mode: false
+  parallel_mode: false
+
+Flags:
+  -m N / --max-iterations N → {max_iterations} = N
+  -c TEXT / --completion-promise TEXT → {completion_promise} = TEXT
+  -v / --verbose → {verbose_mode} = true
+  -r / --resume → {resume_mode} = true
+  -p / --parallel → {parallel_mode} = true
+  Remainder → {task_description}
+```
+
+**If `-p`:** set parallel_mode = true. Ralph executes Phase 0 (entities) sequentially, then spawns parallel teammates.
+
+## 2. Verify MCP (MANDATORY)
+
+```
+mcp__smartstack__validate_conventions: checks: ["all"] → {mcp_smartstack} = true/false
+mcp__context7__resolve-library-id: libraryName: "test" → {mcp_context7} = true/false
+```
+
+If ANY fails: show error, suggest `smartstack check-mcp`, STOP.
+
+## 3. Execution Mode (FULLY AUTONOMOUS)
+
+Ralph-loop is FULLY AUTONOMOUS by default. It executes ALL tasks from start to finish WITHOUT stopping.
+
+**DO NOT** ask the user to confirm, choose a mode, or approve execution.
+**DO NOT** set max_iterations = 1 or any reduced value.
+
+The loop runs autonomously until:
+- ALL tasks are completed (success)
+- max_iterations is reached (user set via `-m N`)
+- Dead-end detected (all remaining blocked/failed)
+- User Ctrl+C (external interrupt)
+
+### Speed Warning (informational only)
+
+If tests are slow (>30s in logs), display warning but **continue execution**:
+```
+⚠ Slow tests detected. Consider disabling E2E during ralph-loop.
+```
+
+## 4. Resume or Initialize
+
+See `references/init-resume-recovery.md` for complete Resume Mode and Auto-Recovery logic.
+
+**Quick:**
+- If `-r` flag: restore state from .ralph/prd.json
+- Else if BA artifacts exist: auto-recover PRDs via `ss derive-prd`
+- Else: fresh start
+
+---
+
+## 4b. Detect Multi-Module PRDs
+
+See `references/multi-module-queue.md` for queue initialization.
+
+Quick: `glob('.ralph/prd-*.json').length > 1` → create modules-queue.json
+
+---
+
+## 4c. Team Orchestration (multi-module, 2+ modules)
+
+```javascript
+if (PRD_COUNT > 1) {
+  // Read references/team-orchestration.md for full protocol
+  const layers = master.metadata?.workflow?.dependencyGraph?.layers;
+
+  if (layers) {
+    // PARALLEL MODE: Use Agent Teams
+    TeamCreate({ team_name: `ralph-${appName}` });
+    // Spawn teammates per layer (see reference)
+    // STOP here — team orchestration takes over
+    return;
+  }
+  // If no layers: fall through to sequential mode
+}
+```
+
+---
+
+## 5. Completion Promise (auto-set)
+
+```javascript
+if (!completion_promise) {
+  completion_promise = "COMPLETE";
+}
+// Output ONLY when ALL tasks done
+```
+
+## 6. Collect Metadata
+
+```bash
+CLI_VERSION=$(node -e "console.log(require('package.json').version)" 2>/dev/null || echo "unknown")
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+PROJECT_PATH=$(pwd)
+```
+
+```javascript
+{metadata} = {
+  cli_version: CLI_VERSION,
+  branch: CURRENT_BRANCH,
+  project_path: PROJECT_PATH,
+  mcp_servers: { smartstack: {mcp_smartstack}, context7: {mcp_context7} }
+}
+```
+
+## 7. Show Summary
+
+```
+RALPH LOOP INITIALIZED
+Task: {task_description} | Max: {max_iterations} | Promise: {completion_promise}
+MCP: Ready | Branch: {branch} | Schema: v3.0.0
+{modules_queue ? `Modules: ${totalModules} (${module_codes.join(' → ')})` : 'Mode: single module'}
+-> Loading tasks...
+```
+
+**Proceed directly to step-01-task.md**

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

@@ -1,174 +1,174 @@
----
-name: step-01-task
-description: Load or create tasks from prd.json (v3 unified or v2 legacy)
-next_step: steps/step-02-execute.md
----
-
-# Step 1: Load Task
-
-> **MODULE TRANSITION CHECK:** Before "Only Read Once" rule, check for module transition:
-
-```javascript
-if (fileExists('.ralph/module-changed.json')) {
-  const t = readJSON('.ralph/module-changed.json');
-  console.log(`Module transition: ${t.fromModule} → ${t.toModule}`);
-  deleteFile('.ralph/module-changed.json');
-  // PROCEED (exception to "Only Read Once" rule)
-}
-```
-
-> **CONTEXT OPTIMIZATION:** Read ONCE per module (first iteration).
-> Iterations > 1 within same module → use COMPACT LOOP in step-04.
-> Re-read ONLY on module transition (module-changed.json detected above).
-
-## YOUR TASK:
-
-Load task from prd.json or create initial task breakdown with categories, dependencies, and acceptance criteria.
-
----
-
-## 0. Multi-Module Queue Check
-
-See `references/multi-module-queue.md` for full module queue initialization, detection, and loading.
-
-Quick: If `glob('.ralph/prd-*.json').length > 1` → create modules-queue.json and load first module's PRD.
-
----
-
-## PrdJson → Ralph v2 Transformation (DEPRECATED)
-
-See [references/task-transform-legacy.md](../references/task-transform-legacy.md) for the full `transformPrdJsonToRalphV2()` function including:
-- Layer-ordered task generation (domain → infra → app → api → frontend → seedData → tests)
-- Consolidated frontend + i18n tasks
-- Guardrails 1d-1j (inject missing infrastructure, API, frontend, tests, seed data, migration)
-
----
-
-## 1. Check for Existing prd.json
-
-If `.ralph/prd.json` exists:
-1. Read the PRD
-2. **v3 FAST PATH:** If `$version === "3.0.0"` AND `tasks[]` exists:
-   - Inject runtime fields if missing (status, config, feature, created, updated_at, history)
-   - Write back to `.ralph/prd.json`
-   - **Run CATEGORY COMPLETENESS CHECK (section 4b) before proceeding**
-   - Skip directly to section 5 (find next task)
-3. **v2 legacy:** If `$version === "2.0.0"` → find next eligible task (section 5)
-4. **FORMAT A (deprecated):** If `.project && .requirements && !.$version` → run `transformPrdJsonToRalphV2()` → section 5
-
-If `.ralph/prd.json` does not exist: continue to section 1b.
-
-### 1b. BA Handoff Quality Gate (BLOCKING)
-
-> **CRITICAL:** Before generating ANY tasks, verify the BA handoff is complete.
-> A missing handoff means no frontend files, no test plan, no BR-to-code mapping.
-
-```javascript
-const sourceFeatureJson = prd?.metadata?.sourceFeatureJson
-  || findFile('docs/business/**/business-analyse/**/feature.json');
-
-if (sourceFeatureJson) {
-  const feature = readJSON(sourceFeatureJson);
-  const handoff = feature.handoff || {};
-
-  // CHECK 1: Handoff status must be "handed-off"
-  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.`);
-    STOP;
-  }
-
-  // CHECK 2: filesToCreate must have all categories
-  const filesToCreate = handoff.filesToCreate || {};
-  const requiredCategories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests'];
-  const missingInHandoff = requiredCategories.filter(c => !filesToCreate[c] || filesToCreate[c].length === 0);
-
-  if (missingInHandoff.length > 0) {
-    console.warn(`⚠ Handoff has empty categories: ${missingInHandoff.join(', ')}`);
-  }
-}
-```
-
-## 2. Analyze Task Description
-
-Check for BA handoff source (priority):
-1. Per-module PRD files (handled by section 0)
-2. Single prd.json already present
-3. Markdown handoff: `find . -path "*development-handoff*" -name "*.md"`
-4. Direct task from `{task_description}`
-
-Generate **3-30 subtasks** by category (domain → infrastructure → application → api → frontend → i18n → test → validation).
-
-## 3. Create prd.json
-
-Write `.ralph/prd.json` with all tasks (every task MUST have: id, description, status, category, dependencies, acceptance_criteria, started_at, completed_at, iteration, commit_hash, files_changed, validation, error).
-
-Initialize `.ralph/progress.txt`:
-```markdown
-# Ralph Loop Progress
-## Task: {task_description}
-## Started: {timestamp}
-## Schema: v3.0.0
-```
-
-## 4. Validate Task Integrity
-
-- All tasks have required fields
-- Dependency references are valid (exist, no forward/circular)
-- Task count 3-30
-
-### 4b. Category Completeness Check (BLOCKING)
-
-See `references/category-completeness.md` for full implementation.
-
-Quick: `checkCategoryCompleteness(prd)` → inject guardrails if needed
-
----
-
-### 4c. Section Split Detection (Large Module)
-
-```javascript
-const domainTasks = prd.tasks.filter(t => t.category === 'domain');
-const sections = prd.architecture?.sections ?? [];
-
-if (domainTasks.length > 4 && sections.length > 1 && !prd._sectionSplit?.enabled) {
-  console.log(`SECTION SPLIT: ${domainTasks.length} domain tasks, ${sections.length} sections → activating`);
-  // LOAD references/section-splitting.md — execute sections 2-6
-}
-```
-
-**Activation:** `> 4 domain tasks` AND `> 1 architecture section`
-
-## 5. Find Current Task
-
-```javascript
-function findNextTask(tasks) {
-  for (const task of tasks) {
-    if (task.status !== 'pending') continue;
-    const depsBlocked = task.dependencies.some(d => {
-      const dep = tasks.find(t => t.id === d);
-      return dep && (dep.status === 'failed' || dep.status === 'blocked');
-    });
-    if (depsBlocked) { task.status = 'blocked'; task.error = 'Blocked by failed dependency'; continue; }
-    const depsOk = task.dependencies.every(d => tasks.find(t => t.id === d)?.status === 'completed');
-    if (depsOk) return task;
-  }
-  return null;
-}
-```
-
-If no eligible task: check if all completed → step-05, else STOP.
-
-## 6. Show Task Status
-
-```
-[{iteration}/{max}] {completed}/{total} done | Task [{id}] {description} ({category})
--> Executing...
-```
-
----
-
-## NEXT STEP:
-
-After task loaded, proceed to `./step-02-execute.md`
+---
+name: step-01-task
+description: Load or create tasks from prd.json (v3 unified or v2 legacy)
+next_step: steps/step-02-execute.md
+---
+
+# Step 1: Load Task
+
+> **MODULE TRANSITION CHECK:** Before "Only Read Once" rule, check for module transition:
+
+```javascript
+if (fileExists('.ralph/module-changed.json')) {
+  const t = readJSON('.ralph/module-changed.json');
+  console.log(`Module transition: ${t.fromModule} → ${t.toModule}`);
+  deleteFile('.ralph/module-changed.json');
+  // PROCEED (exception to "Only Read Once" rule)
+}
+```
+
+> **CONTEXT OPTIMIZATION:** Read ONCE per module (first iteration).
+> Iterations > 1 within same module → use COMPACT LOOP in step-04.
+> Re-read ONLY on module transition (module-changed.json detected above).
+
+## YOUR TASK:
+
+Load task from prd.json or create initial task breakdown with categories, dependencies, and acceptance criteria.
+
+---
+
+## 0. Multi-Module Queue Check
+
+See `references/multi-module-queue.md` for full module queue initialization, detection, and loading.
+
+Quick: If `glob('.ralph/prd-*.json').length > 1` → create modules-queue.json and load first module's PRD.
+
+---
+
+## PrdJson → Ralph v2 Transformation (DEPRECATED)
+
+See [references/task-transform-legacy.md](../references/task-transform-legacy.md) for the full `transformPrdJsonToRalphV2()` function including:
+- Layer-ordered task generation (domain → infra → app → api → frontend → seedData → tests)
+- Consolidated frontend + i18n tasks
+- Guardrails 1d-1j (inject missing infrastructure, API, frontend, tests, seed data, migration)
+
+---
+
+## 1. Check for Existing prd.json
+
+If `.ralph/prd.json` exists:
+1. Read the PRD
+2. **v3 FAST PATH:** If `$version === "3.0.0"` AND `tasks[]` exists:
+   - Inject runtime fields if missing (status, config, feature, created, updated_at, history)
+   - Write back to `.ralph/prd.json`
+   - **Run CATEGORY COMPLETENESS CHECK (section 4b) before proceeding**
+   - Skip directly to section 5 (find next task)
+3. **v2 legacy:** If `$version === "2.0.0"` → find next eligible task (section 5)
+4. **FORMAT A (deprecated):** If `.project && .requirements && !.$version` → run `transformPrdJsonToRalphV2()` → section 5
+
+If `.ralph/prd.json` does not exist: continue to section 1b.
+
+### 1b. BA Handoff Quality Gate (BLOCKING)
+
+> **CRITICAL:** Before generating ANY tasks, verify the BA handoff is complete.
+> A missing handoff means no frontend files, no test plan, no BR-to-code mapping.
+
+```javascript
+const sourceFeatureJson = prd?.metadata?.sourceFeatureJson
+  || findFile('docs/business/**/business-analyse/**/feature.json');
+
+if (sourceFeatureJson) {
+  const feature = readJSON(sourceFeatureJson);
+  const handoff = feature.handoff || {};
+
+  // CHECK 1: Handoff status must be "handed-off"
+  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.`);
+    STOP;
+  }
+
+  // CHECK 2: filesToCreate must have all categories
+  const filesToCreate = handoff.filesToCreate || {};
+  const requiredCategories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests'];
+  const missingInHandoff = requiredCategories.filter(c => !filesToCreate[c] || filesToCreate[c].length === 0);
+
+  if (missingInHandoff.length > 0) {
+    console.warn(`⚠ Handoff has empty categories: ${missingInHandoff.join(', ')}`);
+  }
+}
+```
+
+## 2. Analyze Task Description
+
+Check for BA handoff source (priority):
+1. Per-module PRD files (handled by section 0)
+2. Single prd.json already present
+3. Markdown handoff: `find . -path "*development-handoff*" -name "*.md"`
+4. Direct task from `{task_description}`
+
+Generate **3-30 subtasks** by category (domain → infrastructure → application → api → frontend → i18n → test → validation).
+
+## 3. Create prd.json
+
+Write `.ralph/prd.json` with all tasks (every task MUST have: id, description, status, category, dependencies, acceptance_criteria, started_at, completed_at, iteration, commit_hash, files_changed, validation, error).
+
+Initialize `.ralph/progress.txt`:
+```markdown
+# Ralph Loop Progress
+## Task: {task_description}
+## Started: {timestamp}
+## Schema: v3.0.0
+```
+
+## 4. Validate Task Integrity
+
+- All tasks have required fields
+- Dependency references are valid (exist, no forward/circular)
+- Task count 3-30
+
+### 4b. Category Completeness Check (BLOCKING)
+
+See `references/category-completeness.md` for full implementation.
+
+Quick: `checkCategoryCompleteness(prd)` → inject guardrails if needed
+
+---
+
+### 4c. Section Split Detection (Large Module)
+
+```javascript
+const domainTasks = prd.tasks.filter(t => t.category === 'domain');
+const sections = prd.architecture?.sections ?? [];
+
+if (domainTasks.length > 4 && sections.length > 1 && !prd._sectionSplit?.enabled) {
+  console.log(`SECTION SPLIT: ${domainTasks.length} domain tasks, ${sections.length} sections → activating`);
+  // LOAD references/section-splitting.md — execute sections 2-6
+}
+```
+
+**Activation:** `> 4 domain tasks` AND `> 1 architecture section`
+
+## 5. Find Current Task
+
+```javascript
+function findNextTask(tasks) {
+  for (const task of tasks) {
+    if (task.status !== 'pending') continue;
+    const depsBlocked = task.dependencies.some(d => {
+      const dep = tasks.find(t => t.id === d);
+      return dep && (dep.status === 'failed' || dep.status === 'blocked');
+    });
+    if (depsBlocked) { task.status = 'blocked'; task.error = 'Blocked by failed dependency'; continue; }
+    const depsOk = task.dependencies.every(d => tasks.find(t => t.id === d)?.status === 'completed');
+    if (depsOk) return task;
+  }
+  return null;
+}
+```
+
+If no eligible task: check if all completed → step-05, else STOP.
+
+## 6. Show Task Status
+
+```
+[{iteration}/{max}] {completed}/{total} done | Task [{id}] {description} ({category})
+-> Executing...
+```
+
+---
+
+## NEXT STEP:
+
+After task loaded, proceed to `./step-02-execute.md`