@atlashub/smartstack-cli 3.8.0 → 3.9.0

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

@@ -6,373 +6,155 @@ next_step: steps/step-01-task.md
 
 # Step 0: Initialization
 
-## MANDATORY EXECUTION RULES:
+## MANDATORY RULES:
 
 - NEVER skip MCP verification
-- ALWAYS parse ALL flags before any other action
-- ONLY check for resume if -r flag is set
-- YOU ARE AN INITIALIZER, not an executor
-- FORBIDDEN to load step-01 until init is complete
-- ALWAYS check prd.json version is v2
-- **CONTEXT BUDGET**: Keep init output COMPACT. Do NOT dump verbose MCP responses or long file listings. Every token saved here = more tokens for actual code generation in the COMPACT LOOP.
-- **NEVER DELEGATE**: Do NOT use the Task tool to delegate the Ralph loop to a sub-agent. The loop MUST run in the main agent context. Sub-agents lose skill context and stop prematurely.
+- ALWAYS parse ALL flags before any action
+- ONLY check resume if -r flag is set
+- CONTEXT BUDGET: Keep output COMPACT
+- **NEVER DELEGATE** the main Ralph loop to a sub-agent (single module)
+- **Multi-module (2+ modules):** Use Agent Teams for parallel execution
 
 ## YOUR TASK:
 
-Initialize the Ralph loop by parsing flags, verifying MCP availability, setting up the execution environment, and validating integrity on resume.
+Initialize the Ralph loop: parse flags, verify MCP, setup environment, detect multi-module.
 
 ---
 
-<defaults>
-## Default Configuration
+## 1. Parse Flags
 
 ```yaml
-max_iterations: 50
-completion_promise: null
-verbose_mode: false
-resume_mode: false
-current_iteration: 1
-```
-</defaults>
-
----
-
-## EXECUTION SEQUENCE:
+Defaults:
+  max_iterations: 50
+  completion_promise: null
+  verbose_mode: false
+  resume_mode: false
+  current_iteration: 1
 
-### 1. Parse Flags and Input
-
-**Step 1: Load defaults from config above**
-
-```
-{max_iterations}     = 50
-{completion_promise} = null
-{verbose_mode}       = false
-{resume_mode}        = false
-{current_iteration}  = 1
-```
-
-**Step 2: Parse user input and override defaults:**
-
-```
 Flags:
-  -m N or --max-iterations N     -> {max_iterations} = N
-  -c TEXT or --completion-promise TEXT -> {completion_promise} = TEXT
-  -v or --verbose                -> {verbose_mode} = true
-  -r or --resume                 -> {resume_mode} = true
-
-Remainder -> {task_description}
+  -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
+  Remainder → {task_description}
 ```
 
-### 2. Verify MCP Servers (MANDATORY)
-
-**CRITICAL: Do NOT proceed without MCP verification!**
+## 2. Verify MCP (MANDATORY)
 
-**Check SmartStack MCP:**
 ```
-mcp__smartstack__validate_conventions:
-  checks: ["all"]
-  (just to verify connectivity)
+mcp__smartstack__validate_conventions: checks: ["all"]  → {mcp_smartstack} = true/false
+mcp__context7__resolve-library-id: libraryName: "test"  → {mcp_context7} = true/false
 ```
 
-**Check Context7 MCP:**
-```
-mcp__context7__resolve-library-id:
-  libraryName: "test"
-  query: "connectivity check"
-  (just to verify connectivity)
-```
-
-**Record MCP status for metadata:**
-```
-{mcp_smartstack} = true/false
-{mcp_context7}   = true/false
-```
-
-**If ANY MCP fails:**
-```
-╔══════════════════════════════════════════════════════════════════╗
-║  ❌ MCP SERVER UNAVAILABLE                                      ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Server: {failed_server}                                        ║
-║  Status: Connection failed                                      ║
-╠══════════════════════════════════════════════════════════════════╣
-║  RALPH CANNOT PROCEED WITHOUT MCP                               ║
-║                                                                  ║
-║  Troubleshooting:                                                ║
-║  1. Run: smartstack check-mcp                                    ║
-║  2. Restart Claude Code                                          ║
-║  3. Check MCP server configuration                               ║
-╚══════════════════════════════════════════════════════════════════╝
-
-STOP - Do not proceed.
-```
-
-### 3. Check Resume Mode
+If ANY fails: show error, suggest `smartstack check-mcp`, STOP.
 
-**If {resume_mode} = true:**
+## 3. Resume Mode
 
-1. Check for existing `.ralph/prd.json`
-2. If not found:
-   - Error: "No active Ralph loop to resume"
-   - Ask user to start new loop
-   - STOP
+If `{resume_mode} = true`:
 
-3. If found, **validate schema version:**
+1. Check `.ralph/prd.json` exists → error if not
+2. Detect format:
+   - `$version === "3.0.0"` → **v3 unified** (native, preferred)
+   - `$version === "2.0.0"` → **v2 legacy** (OK, continue)
+   - `.project && .requirements && !.$version` → **FORMAT A (DEPRECATED)** — warn and transform via step-01
+   - Other → error
+3. Check branch consistency: current branch vs `prd.metadata.branch`
+4. Restore state: `current_iteration`, `completion_promise`, `max_iterations`
+5. If `modules-queue.json` exists: restore multi-module state
+6. Continue to step-01
 
-```javascript
-const prd = readJSON('.ralph/prd.json');
-
-if (prd.$version !== "2.0.0") {
-  echo "❌ prd.json schema version unsupported: ${prd.$version || 'missing'}";
-  echo "   Expected: 2.0.0";
-  echo "   Re-run /business-analyse to generate a fresh prd.json";
-  STOP;
-}
-```
-
-4. **Validate integrity (v2 resume):**
-
-```bash
-# Check branch consistency
-CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
-PRD_BRANCH={prd.metadata.branch}
-
-if [ "$CURRENT_BRANCH" != "$PRD_BRANCH" ]; then
-  echo "⚠️ Branch mismatch: prd.json was created on '$PRD_BRANCH', now on '$CURRENT_BRANCH'"
-  # Ask user: continue on current branch or switch
-  AskUserQuestion:
-    header: "Branch"
-    question: "prd.json was created on '$PRD_BRANCH' but you're on '$CURRENT_BRANCH'. Continue?"
-    options:
-      - label: "Continue on $CURRENT_BRANCH"
-        description: "Update metadata and continue"
-      - label: "Cancel"
-        description: "Switch branch manually first"
-fi
-
-# Check for external commits since last update
-LAST_UPDATED={prd.updated_at}
-EXTERNAL_COMMITS=$(git log --since="$LAST_UPDATED" --oneline --not --author="Co-Authored-By: Claude" | wc -l)
-
-if [ "$EXTERNAL_COMMITS" -gt 0 ]; then
-  echo "⚠️ $EXTERNAL_COMMITS external commits detected since last Ralph iteration"
-  echo "   prd.json state may not reflect current code state"
-fi
-```
-
-5. **Restore state from prd.json:**
-   - Read `prd.config.current_iteration` → `{current_iteration}`
-   - Read `prd.config.completion_promise` → `{completion_promise}`
-   - Read `prd.config.max_iterations` → `{max_iterations}`
-   - Read progress.txt for context
-
-6. **Restore multi-module state (if applicable):**
-   ```javascript
-   if (fileExists('.ralph/modules-queue.json')) {
-     const queue = readJSON('.ralph/modules-queue.json');
-     const currentModule = queue.modules[queue.currentIndex];
-
-     // Restore module state
-     {modules_queue} = queue;
-     {current_module} = currentModule.code;
-
-     console.log(`Resuming multi-module: ${currentModule.code} (${queue.currentIndex + 1}/${queue.totalModules})`);
-     console.log(`Modules completed: ${queue.completedModules}/${queue.totalModules}`);
-   }
-   ```
-
-   - Continue to step-01
-
-### 4. Initialize .ralph/ Structure (new loop)
-
-**Create directory structure:**
-
-```
-.ralph/
-├── prd.json          # Will be created in step-01
-├── progress.txt      # Will be created in step-01
-├── logs/
-└── reports/
-```
-
-**Commands:**
-```bash
-mkdir -p .ralph/logs
-mkdir -p .ralph/reports
-```
-
-### 4a. Auto-Recovery: Detect BA Artifacts Without PRD (NEW)
-
-> **Scenario:** Business-analyse completed (feature.json with status="handed-off") but step-05b
-> didn't generate PRD files (context exhaustion). Ralph-loop auto-recovers by running `ss derive-prd`.
-
-**Check for BA artifacts when no PRD files exist:**
+## 4. Initialize .ralph/ (new loop)
 
 ```bash
-PRD_EXISTS=$(ls .ralph/prd-*.json 2>/dev/null | head -1)
-SINGLE_PRD_EXISTS=$(test -f .ralph/prd.json && echo "yes" || echo "no")
+mkdir -p .ralph/logs .ralph/reports
 ```
 
-**IF no PRD files found (neither prd-*.json nor prd.json):**
-
-```bash
-# Search for handed-off master feature.json
-MASTER_FEATURE=$(find docs/business -maxdepth 4 -name "feature.json" -path "*/business-analyse/*" 2>/dev/null | head -1)
-```
+### 4a. Auto-Recovery: BA Artifacts Without PRD
 
-**IF master feature.json found:**
+If no PRD files exist (neither `prd-*.json` nor `prd.json`):
 
 ```javascript
-const master = readJSON(MASTER_FEATURE);
-
-if (master.status === "handed-off" || master.handoff?.status === "handed-off") {
-  // BA completed but PRD files are missing — auto-recover
-  console.log("BA artifacts detected without PRD files — auto-recovering...");
-
-  // Display validation table
-  console.log(`
-╔══════════════════════════════════════════════════════════════════╗
-║  BA ARTIFACT VALIDATION                                          ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Master feature.json: ✅ Found (status: ${master.status})        ║
-║  Application: ${master.metadata?.application || 'unknown'}       ║
-║  Modules: ${master.modules?.length || 0}                         ║
-║  PRD files: ❌ Missing — will auto-generate                      ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Running: ss derive-prd --application ${MASTER_FEATURE}          ║
-╚══════════════════════════════════════════════════════════════════╝
-  `);
-
-  // Execute ss derive-prd to generate missing PRD files
-  // This is a deterministic CLI command (no LLM), safe to auto-run
-  exec(`ss derive-prd --application ${MASTER_FEATURE}`);
-
-  // Verify PRD files were generated
-  const newPrdFiles = glob('.ralph/prd-*.json');
-  if (newPrdFiles.length === 0) {
-    console.log("❌ ss derive-prd failed to generate PRD files");
-    console.log("   Verify: ss derive-prd is installed (npm list -g @atlashub/smartstack-cli)");
-    console.log("   Manual: ss derive-prd --application " + MASTER_FEATURE);
-    STOP;
+const masterFeature = findFile('docs/business/**/business-analyse/**/feature.json');
+if (masterFeature) {
+  const master = readJSON(masterFeature);
+  if (master.status === 'handed-off' || master.handoff?.status === 'handed-off') {
+    console.log('BA artifacts detected without PRD — auto-recovering...');
+    exec(`ss derive-prd --application ${masterFeature}`);
+    const newPrds = glob('.ralph/prd-*.json');
+    if (newPrds.length === 0) { console.log('ss derive-prd failed'); STOP; }
+    console.log(`Auto-recovered ${newPrds.length} PRD files`);
   }
-
-  console.log(`✅ Auto-recovered ${newPrdFiles.length} PRD files`);
-  // Continue to section 4b which will detect and queue them
 }
 ```
 
-**IF master feature.json NOT found OR status ≠ "handed-off":**
-- No BA artifacts → proceed normally (step-01 will create prd.json from task description)
-
-**IF PRD files already exist:**
-- Skip auto-recovery entirely → proceed to section 4b
-
-### 4b. Detect Multi-Module PRDs (from BA Handoff or Auto-Recovery)
+### 4b. Detect Multi-Module PRDs
 
-**After creating `.ralph/` directory, check for per-module PRD files:**
-
-```bash
-# Count prd-*.json files (generated by BA handoff via ss derive-prd)
-PRD_FILES=$(ls .ralph/prd-*.json 2>/dev/null)
-PRD_COUNT=$(echo "$PRD_FILES" | grep -c "prd-" 2>/dev/null || echo "0")
-```
-
-**If multiple prd-*.json files found (PRD_COUNT > 0):**
-
-1. **Read module order from master feature.json (if available):**
-```bash
-# Look for master feature.json that references modules
-MASTER_FEATURE=$(find docs/business -maxdepth 4 -name "feature.json" -path "*/business-analyse/*" | head -1)
-```
-
-2. **Build module queue:**
 ```javascript
-const modules = [];
-
-if (MASTER_FEATURE && masterJson.metadata?.workflow?.moduleOrder) {
-  // Use order from BA master feature.json
-  for (const mod of masterJson.metadata.workflow.moduleOrder) {
-    const prdFile = `.ralph/prd-${mod.code}.json`;
-    if (fileExists(prdFile)) {
-      modules.push({ code: mod.code, prdFile, status: "pending" });
+const prdFiles = glob('.ralph/prd-*.json');
+const PRD_COUNT = prdFiles.length;
+
+if (PRD_COUNT > 0) {
+  // Build module queue (from master feature.json order or alphabetical)
+  const modules = [];
+  const masterFeature = findFile('docs/business/**/business-analyse/**/feature.json');
+  if (masterFeature) {
+    const master = readJSON(masterFeature);
+    const moduleOrder = master.metadata?.workflow?.moduleOrder || [];
+    for (const mod of moduleOrder) {
+      if (fileExists(`.ralph/prd-${mod.code}.json`)) {
+        modules.push({ code: mod.code, prdFile: `.ralph/prd-${mod.code}.json`, status: 'pending' });
+      }
     }
   }
-} else {
-  // Fallback: alphabetical order from prd-*.json filenames
-  for (const file of prdFiles) {
-    const code = file.match(/prd-(.+)\.json$/)[1];
-    modules.push({ code, prdFile: `.ralph/${file}`, status: "pending" });
+  // Fallback: alphabetical
+  if (modules.length === 0) {
+    for (const file of prdFiles) {
+      const code = file.match(/prd-(.+)\.json$/)[1];
+      modules.push({ code, prdFile: `.ralph/${file}`, status: 'pending' });
+    }
   }
-}
-```
-
-3. **Create modules-queue.json:**
-```json
-{
-  "modules": [
-    { "code": "mod1", "prdFile": ".ralph/prd-mod1.json", "status": "pending" },
-    { "code": "mod2", "prdFile": ".ralph/prd-mod2.json", "status": "pending" }
-  ],
-  "currentIndex": 0,
-  "totalModules": 2,
-  "completedModules": 0
-}
-```
-
-4. **Set first module as active:**
-```javascript
-modules[0].status = "in-progress";
-```
 
-5. **Log detection:**
-```
-Multi-module detected: {PRD_COUNT} modules
-Queue: {module codes joined by " → "}
-Starting with: {modules[0].code}
-```
+  // Create modules-queue.json
+  modules[0].status = 'in-progress';
+  const queue = { modules, currentIndex: 0, totalModules: modules.length, completedModules: 0 };
+  writeJSON('.ralph/modules-queue.json', queue);
+  console.log(`Multi-module: ${modules.length} modules → ${modules.map(m => m.code).join(' → ')}`);
 
-6. **Display BA artifact validation (if from BA handoff):**
-```
-[CHECK] BA Artifact Validation:
-  ✓ Master feature.json: {MASTER_FEATURE} (status: handed-off)
-  ✓ Module feature.json: {module_count} modules (all handed-off)
-  ✓ PRD files: {PRD_COUNT} modules (.ralph/prd-*.json)
-  ✓ progress.txt: {exists ? "present" : "will be created"}
-  [PASS] All BA artifacts valid. Multi-module development ready.
+  {modules_queue} = queue;
+  {current_module} = modules[0].code;
+}
 ```
 
-**If only `.ralph/prd.json` exists (single module):**
-- Skip queue creation (backward compatible)
-- Proceed normally
+### 4c. Team Orchestration (multi-module, 2+ modules)
 
-**Store:**
-```
-{modules_queue} = queue object or null
-{current_module} = first module code or null
+```javascript
+if (PRD_COUNT > 1) {
+  // Read references/team-orchestration.md for full protocol
+  // Detect dependency layers from master feature.json
+  const layers = master.metadata?.workflow?.dependencyGraph?.layers;
+
+  if (layers) {
+    // PARALLEL MODE: Use Agent Teams
+    TeamCreate({ team_name: `ralph-${appName}` });
+
+    // For each layer, spawn teammates in parallel
+    // Layer 0: foundation modules (spawn, wait for LAYER_READY)
+    // Layer 1+: dependent modules (spawn after previous layer completes)
+    // See references/team-orchestration.md for teammate prompt template
+
+    // After all layers: cross-module verify → step-05 → TeamDelete
+    // STOP here — team orchestration takes over
+    return;
+  }
+  // If no layers: fall through to sequential mode (classic compact loop)
+}
 ```
 
-### 5. Validate Completion Promise
-
-**If {completion_promise} is null:**
-
-```yaml
-AskUserQuestion:
-  header: "Promise"
-  question: "What text should signal completion?"
-  options:
-    - label: "COMPLETE"
-      description: "Standard completion signal"
-    - label: "ALL TESTS PASS"
-      description: "For test-focused tasks"
-    - label: "DONE"
-      description: "Simple completion"
-    - label: "Custom..."
-      description: "Specify custom text"
-```
+## 5. Completion Promise
 
-### 6. Collect Metadata
+If `{completion_promise}` is null: ask user to choose (COMPLETE, ALL TESTS PASS, DONE, or custom).
 
-**Gather execution context:**
+## 6. Collect Metadata
 
 ```bash
 CLI_VERSION=$(node -e "console.log(require('package.json').version)" 2>/dev/null || echo "unknown")
@@ -380,73 +162,19 @@ CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
 PROJECT_PATH=$(pwd)
 ```
 
-**Store metadata for prd.json creation (step-01):**
-```
-{metadata} = {
-  cli_version: CLI_VERSION,
-  branch: CURRENT_BRANCH,
-  project_path: PROJECT_PATH,
-  mcp_servers: { smartstack: {mcp_smartstack}, context7: {mcp_context7} }
-}
-```
-
-### 7. Log Initialization
-
-**If {verbose_mode} = true:**
-
-Write to `.ralph/logs/{timestamp}.log`:
-```
-[{timestamp}] RALPH LOOP INITIALIZED
-Task: {task_description}
-Max iterations: {max_iterations}
-Completion promise: {completion_promise}
-MCP Status: SmartStack {mcp_smartstack ? "✅" : "❌"}, Context7 {mcp_context7 ? "✅" : "❌"}
-Schema: v2.0.0
-Branch: {CURRENT_BRANCH}
+```javascript
+{metadata} = { cli_version: CLI_VERSION, branch: CURRENT_BRANCH, project_path: PROJECT_PATH,
+  mcp_servers: { smartstack: {mcp_smartstack}, context7: {mcp_context7} } }
 ```
 
-### 8. Show Summary and Proceed
-
-**Always show COMPACT summary:**
+## 7. Show Summary
 
 ```
-╔══════════════════════════════════════════════════════════════════╗
-║  RALPH LOOP INITIALIZED                                         ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Task: {task_description}                                       ║
-║  Max iterations: {max_iterations}                               ║
-║  Completion: <promise>{completion_promise}</promise>             ║
-║  MCP: ✅ Ready                                                  ║
-║  Schema: v2.0.0                                                 ║
-║  Branch: {CURRENT_BRANCH}                                       ║
-║  {modules_queue ? "Modules: " + totalModules + " (" + module_codes.join(" → ") + ")" : "Mode: single module"} ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Files:                                                          ║
-║  - .ralph/prd.json (tasks)                                       ║
-║  - .ralph/progress.txt (memory)                                  ║
-║  {modules_queue ? "- .ralph/modules-queue.json (module tracking)" : ""} ║
-╚══════════════════════════════════════════════════════════════════╝
-
+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...
 ```
 
-**Then proceed directly to step-01-task.md**
-
----
-
-## SUCCESS METRICS:
-
-- All flags correctly parsed
-- MCP servers verified and available
-- .ralph/ directory structure created
-- Completion promise defined
-- Metadata collected (branch, version, MCP status)
-- prd.json v2 schema validated (if resume)
-- Branch integrity validated (if resume)
-- Multi-module prd files detected and modules-queue.json created (if applicable)
-- Output is COMPACT
-- Proceeded to step-01 immediately after summary
-
-## NEXT STEP:
-
-After showing initialization summary, always proceed directly to `./step-01-task.md`
+**Proceed directly to step-01-task.md**