@atlashub/smartstack-cli 3.39.0 → 3.41.0

package/templates/skills/ralph-loop/steps/step-02-execute.md

@@ -1,177 +1,177 @@
----
-name: step-02-execute
-description: Delegate module execution to /apex
-next_step: steps/step-03-commit.md
----
-
-# Step 2: Delegate to /apex
-
-> **CONTEXT OPTIMIZATION:** Read ONCE (first iteration). Subsequent iterations use compact-loop.md.
-
-## YOUR TASK:
-
-Delegate the current module's tasks to `/apex -d` for code generation. Ralph handles orchestration only.
-
-**ULTRA THINK about the delegation context.**
-
----
-
-## EXECUTION RULES:
-
-1. **VERIFY DEPENDENCIES** — All task dependencies must be completed
-2. **DELEGATE TO /apex** — All code generation via `/apex -d`
-3. **TRACK RESULTS** — Verify PRD state after apex returns
-4. **NEVER GENERATE CODE** — Ralph orchestrates, apex generates
-
----
-
-## EXECUTION SEQUENCE:
-
-### 1. Verify Dependencies
-
-```javascript
-const prd = readJSON('.ralph/prd.json');
-const task = prd.tasks.find(t => t.id === {current_task_id});
-for (const depId of task.dependencies) {
-  const dep = prd.tasks.find(t => t.id === depId);
-  if (!dep || dep.status !== 'completed') {
-    task.status = 'blocked'; task.error = `Dependency ${depId} not completed`;
-    writeJSON('.ralph/prd.json', prd);
-    STOP — return to step-01
-  }
-}
-```
-
-### 2. Mark In-Progress
-
-```javascript
-task.status = 'in_progress';
-task.started_at = new Date().toISOString();
-writeJSON('.ralph/prd.json', prd);
-```
-
-### 3. Delegate to /apex
-
-#### 3a. Parallel Mode (if `-p` flag)
-
-See `references/parallel-execution.md` for complete parallel protocol:
-
-**IF `{parallel_mode}` == true:**
-
-1. Phase 0 (Ralph sequential): Generate ALL entities from ALL modules + ONE migration
-2. Phase 1-N (Teams parallel): Spawn teammates per application/module for services/controllers/frontend/tests
-3. Collect results from teammates
-4. Cleanup team, proceed to step-03
-
-**ELSE (not parallel mode):**
-
-Continue with section-split mode or standard mode below.
-
-#### 3b. Section-Split Mode
-
-```javascript
-if (prd._sectionSplit?.enabled) {
-  // Find next pending phase with dependencies met
-  const nextPhase = prd._sectionSplit.phases.find(p => p.status === 'pending');
-
-  if (!nextPhase) {
-    // All phases done — skip to step-04 completion check
-    goto STEP_04;
-  }
-
-  const depsOk = nextPhase.dependsOn.every(depIdx =>
-    prd._sectionSplit.phases[depIdx].status === 'completed'
-  );
-
-  if (!depsOk) {
-    console.warn(`Phase ${nextPhase.phase} blocked — dependencies incomplete`);
-    goto STEP_04;
-  }
-
-  const phaseLabel = nextPhase.type === 'foundation'
-    ? 'Phase 0: Foundation (all entities + migration + module seed data)'
-    : `Phase ${nextPhase.phase}: Section "${nextPhase.sectionCode}" (services + controllers + pages + tests)`;
-  console.log(`SECTION SPLIT: ${phaseLabel}`);
-
-  // INVOKE /apex -d {nextPhase.prdFile}
-  // Apex sees a normal (smaller) PRD and executes normally
-
-  // After apex returns: merge results into master PRD
-  // Read references/section-splitting.md sections 7-9 (execution, merging, failure handling)
-
-  nextPhase.status = 'completed';
-  prd._sectionSplit.currentPhase = nextPhase.phase;
-  writeJSON('.ralph/prd.json', prd);
-
-  // Continue to step-03 (commit), then step-04 loops back for next phase
-}
-```
-
-> See `references/section-splitting.md` for full detection, mapping, PRD construction, and merge logic.
-
-#### 3c. Standard Mode (no split, no parallel)
-
-**INVOKE `/apex -d .ralph/prd.json`**
-
-This delegates ALL remaining tasks for the current module to apex:
-
-- Apex reads the PRD, extracts context (`app_name`, `module_code`, `entities`, `sections`)
-- Apex executes ALL layers: domain → infrastructure → migration → application → api → seed data → frontend → tests
-- Apex runs full POST-CHECKs (50 checks from `references/post-checks.md`)
-- Apex commits per layer (atomic commits)
-- Apex validates with MCP (`validate_conventions`)
-- Apex updates task statuses in the PRD file directly
-
-> **FLAGS:** `-d` implies `-a` (auto, no user confirmation) and `-e` (economy, no nested teams).
-> Ralph manages parallelism via team orchestration, not apex.
-
-### 4. Verify Post-Apex Results
-
-```javascript
-// Re-read PRD after apex execution
-const updatedPrd = readJSON('.ralph/prd.json');
-const moduleTasks = updatedPrd.tasks.filter(t => t.module === {current_module});
-
-const completed = moduleTasks.filter(t => t.status === 'completed').length;
-const failed = moduleTasks.filter(t => t.status === 'failed').length;
-const pending = moduleTasks.filter(t => t.status === 'pending').length;
-
-if (failed > 0) {
-  console.log(`WARNING: ${failed} tasks failed during apex execution`);
-  // Failed tasks will be retried in compact loop
-}
-
-if (pending > 0) {
-  console.log(`INFO: ${pending} tasks still pending — will be handled in compact loop`);
-}
-
-console.log(`Apex completed: ${completed}/${moduleTasks.length} tasks`);
-```
-
-### 5. Update Progress
-
-```javascript
-// Append to progress file
-const progressEntry = `
-[Iteration ${prd.config.current_iteration}] Delegated to /apex
-  Module: ${prd.project.module}
-  Completed: ${completed}/${moduleTasks.length}
-  Failed: ${failed}
-  Pending: ${pending}
-`;
-appendFile('.ralph/progress.txt', progressEntry);
-```
-
----
-
-## CONSTRAINTS:
-
-- **DO:** Delegate to apex, verify results, maintain PRD state
-- **DON'T:** Generate code directly, run inline POST-CHECKs, invoke MCP tools for generation
-- **DON'T:** Stop to ask the user anything — fully autonomous
-
----
-
-## NEXT STEP:
-
-Proceed to `./step-03-commit.md`
+---
+name: step-02-execute
+description: Delegate module execution to /apex
+next_step: steps/step-03-commit.md
+---
+
+# Step 2: Delegate to /apex
+
+> **CONTEXT OPTIMIZATION:** Read ONCE (first iteration). Subsequent iterations use compact-loop.md.
+
+## YOUR TASK:
+
+Delegate the current module's tasks to `/apex -d` for code generation. Ralph handles orchestration only.
+
+**ULTRA THINK about the delegation context.**
+
+---
+
+## EXECUTION RULES:
+
+1. **VERIFY DEPENDENCIES** — All task dependencies must be completed
+2. **DELEGATE TO /apex** — All code generation via `/apex -d`
+3. **TRACK RESULTS** — Verify PRD state after apex returns
+4. **NEVER GENERATE CODE** — Ralph orchestrates, apex generates
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Verify Dependencies
+
+```javascript
+const prd = readJSON('.ralph/prd.json');
+const task = prd.tasks.find(t => t.id === {current_task_id});
+for (const depId of task.dependencies) {
+  const dep = prd.tasks.find(t => t.id === depId);
+  if (!dep || dep.status !== 'completed') {
+    task.status = 'blocked'; task.error = `Dependency ${depId} not completed`;
+    writeJSON('.ralph/prd.json', prd);
+    STOP — return to step-01
+  }
+}
+```
+
+### 2. Mark In-Progress
+
+```javascript
+task.status = 'in_progress';
+task.started_at = new Date().toISOString();
+writeJSON('.ralph/prd.json', prd);
+```
+
+### 3. Delegate to /apex
+
+#### 3a. Parallel Mode (if `-p` flag)
+
+See `references/parallel-execution.md` for complete parallel protocol:
+
+**IF `{parallel_mode}` == true:**
+
+1. Phase 0 (Ralph sequential): Generate ALL entities from ALL modules + ONE migration
+2. Phase 1-N (Teams parallel): Spawn teammates per application/module for services/controllers/frontend/tests
+3. Collect results from teammates
+4. Cleanup team, proceed to step-03
+
+**ELSE (not parallel mode):**
+
+Continue with section-split mode or standard mode below.
+
+#### 3b. Section-Split Mode
+
+```javascript
+if (prd._sectionSplit?.enabled) {
+  // Find next pending phase with dependencies met
+  const nextPhase = prd._sectionSplit.phases.find(p => p.status === 'pending');
+
+  if (!nextPhase) {
+    // All phases done — skip to step-04 completion check
+    goto STEP_04;
+  }
+
+  const depsOk = nextPhase.dependsOn.every(depIdx =>
+    prd._sectionSplit.phases[depIdx].status === 'completed'
+  );
+
+  if (!depsOk) {
+    console.warn(`Phase ${nextPhase.phase} blocked — dependencies incomplete`);
+    goto STEP_04;
+  }
+
+  const phaseLabel = nextPhase.type === 'foundation'
+    ? 'Phase 0: Foundation (all entities + migration + module seed data)'
+    : `Phase ${nextPhase.phase}: Section "${nextPhase.sectionCode}" (services + controllers + pages + tests)`;
+  console.log(`SECTION SPLIT: ${phaseLabel}`);
+
+  // INVOKE /apex -d {nextPhase.prdFile}
+  // Apex sees a normal (smaller) PRD and executes normally
+
+  // After apex returns: merge results into master PRD
+  // Read references/section-splitting.md sections 7-9 (execution, merging, failure handling)
+
+  nextPhase.status = 'completed';
+  prd._sectionSplit.currentPhase = nextPhase.phase;
+  writeJSON('.ralph/prd.json', prd);
+
+  // Continue to step-03 (commit), then step-04 loops back for next phase
+}
+```
+
+> See `references/section-splitting.md` for full detection, mapping, PRD construction, and merge logic.
+
+#### 3c. Standard Mode (no split, no parallel)
+
+**INVOKE `/apex -d .ralph/prd.json`**
+
+This delegates ALL remaining tasks for the current module to apex:
+
+- Apex reads the PRD, extracts context (`app_name`, `module_code`, `entities`, `sections`)
+- Apex executes ALL layers: domain → infrastructure → migration → application → api → seed data → frontend → tests
+- Apex runs full POST-CHECKs (50 checks from `references/post-checks.md`)
+- Apex commits per layer (atomic commits)
+- Apex validates with MCP (`validate_conventions`)
+- Apex updates task statuses in the PRD file directly
+
+> **FLAGS:** `-d` implies `-a` (auto, no user confirmation) and `-e` (economy, no nested teams).
+> Ralph manages parallelism via team orchestration, not apex.
+
+### 4. Verify Post-Apex Results
+
+```javascript
+// Re-read PRD after apex execution
+const updatedPrd = readJSON('.ralph/prd.json');
+const moduleTasks = updatedPrd.tasks.filter(t => t.module === {current_module});
+
+const completed = moduleTasks.filter(t => t.status === 'completed').length;
+const failed = moduleTasks.filter(t => t.status === 'failed').length;
+const pending = moduleTasks.filter(t => t.status === 'pending').length;
+
+if (failed > 0) {
+  console.log(`WARNING: ${failed} tasks failed during apex execution`);
+  // Failed tasks will be retried in compact loop
+}
+
+if (pending > 0) {
+  console.log(`INFO: ${pending} tasks still pending — will be handled in compact loop`);
+}
+
+console.log(`Apex completed: ${completed}/${moduleTasks.length} tasks`);
+```
+
+### 5. Update Progress
+
+```javascript
+// Append to progress file
+const progressEntry = `
+[Iteration ${prd.config.current_iteration}] Delegated to /apex
+  Module: ${prd.project.module}
+  Completed: ${completed}/${moduleTasks.length}
+  Failed: ${failed}
+  Pending: ${pending}
+`;
+appendFile('.ralph/progress.txt', progressEntry);
+```
+
+---
+
+## CONSTRAINTS:
+
+- **DO:** Delegate to apex, verify results, maintain PRD state
+- **DON'T:** Generate code directly, run inline POST-CHECKs, invoke MCP tools for generation
+- **DON'T:** Stop to ask the user anything — fully autonomous
+
+---
+
+## NEXT STEP:
+
+Proceed to `./step-03-commit.md`

package/templates/skills/ralph-loop/steps/step-03-commit.md

@@ -1,92 +1,92 @@
----
-name: step-03-commit
-description: Commit PRD state after apex delegation
-next_step: steps/step-04-check.md
----
-
-# Step 3: Commit PRD State
-
-> **CONTEXT OPTIMIZATION:** Read ONCE (first iteration). Subsequent iterations use compact-loop.md.
-
-## YOUR TASK:
-
-Commit PRD state changes after apex delegation. Apex already committed code — ralph commits orchestration state only.
-
----
-
-## EXECUTION SEQUENCE:
-
-### 1. Finalize Task in prd.json
-
-```javascript
-const prd = readJSON('.ralph/prd.json');
-const now = new Date().toISOString();
-
-// Apex updates individual task statuses. Ralph updates overall PRD state.
-const allDone = prd.tasks.every(t => t.status === 'completed' || t.status === 'skipped');
-prd.status = allDone ? 'completed' : prd.tasks.some(t => t.status === 'failed' || t.status === 'blocked') ? 'partial' : 'in_progress';
-
-prd.config.current_iteration++;
-prd.updated_at = now;
-
-writeJSON('.ralph/prd.json', prd);
-```
-
-### 2. Update progress.txt
-
-Append iteration summary (compact):
-```markdown
-## Iteration {iteration} — Delegated to /apex
-Status: {status} | Completed: {completed}/{total}
-Module: {current_module}
-```
-
-### 3. Stage and Commit (PRD state only)
-
-```bash
-git add .ralph/prd.json .ralph/progress.txt
-[ -f .ralph/modules-queue.json ] && git add .ralph/modules-queue.json
-
-git commit -m "$(cat <<'EOF'
-chore(ralph): PRD state — iteration {iteration}, {completed}/{total} tasks
-
-Module: {current_module}
-
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
-EOF
-)"
-
-COMMIT_HASH=$(git rev-parse --short HEAD)
-```
-
-### 4. Record Commit in History
-
-```javascript
-prd.history.push({
-  iteration: prd.config.current_iteration - 1,
-  action: 'iteration-completed',
-  timestamp: now,
-  commit_hash: COMMIT_HASH,
-  notes: "Delegated to /apex"
-});
-writeJSON('.ralph/prd.json', prd);
-```
-
-### 5. Verify
-
-```bash
-git log -2 --oneline
-```
-
----
-
-## ERROR HANDLING:
-
-- **Commit fails (pre-commit hook):** Fix issue, stage, create NEW commit (don't amend)
-- **Task failed in apex:** PRD already reflects failure status — commit as-is
-
----
-
-## NEXT STEP:
-
-After commit, proceed to `./step-04-check.md`
+---
+name: step-03-commit
+description: Commit PRD state after apex delegation
+next_step: steps/step-04-check.md
+---
+
+# Step 3: Commit PRD State
+
+> **CONTEXT OPTIMIZATION:** Read ONCE (first iteration). Subsequent iterations use compact-loop.md.
+
+## YOUR TASK:
+
+Commit PRD state changes after apex delegation. Apex already committed code — ralph commits orchestration state only.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Finalize Task in prd.json
+
+```javascript
+const prd = readJSON('.ralph/prd.json');
+const now = new Date().toISOString();
+
+// Apex updates individual task statuses. Ralph updates overall PRD state.
+const allDone = prd.tasks.every(t => t.status === 'completed' || t.status === 'skipped');
+prd.status = allDone ? 'completed' : prd.tasks.some(t => t.status === 'failed' || t.status === 'blocked') ? 'partial' : 'in_progress';
+
+prd.config.current_iteration++;
+prd.updated_at = now;
+
+writeJSON('.ralph/prd.json', prd);
+```
+
+### 2. Update progress.txt
+
+Append iteration summary (compact):
+```markdown
+## Iteration {iteration} — Delegated to /apex
+Status: {status} | Completed: {completed}/{total}
+Module: {current_module}
+```
+
+### 3. Stage and Commit (PRD state only)
+
+```bash
+git add .ralph/prd.json .ralph/progress.txt
+[ -f .ralph/modules-queue.json ] && git add .ralph/modules-queue.json
+
+git commit -m "$(cat <<'EOF'
+chore(ralph): PRD state — iteration {iteration}, {completed}/{total} tasks
+
+Module: {current_module}
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+EOF
+)"
+
+COMMIT_HASH=$(git rev-parse --short HEAD)
+```
+
+### 4. Record Commit in History
+
+```javascript
+prd.history.push({
+  iteration: prd.config.current_iteration - 1,
+  action: 'iteration-completed',
+  timestamp: now,
+  commit_hash: COMMIT_HASH,
+  notes: "Delegated to /apex"
+});
+writeJSON('.ralph/prd.json', prd);
+```
+
+### 5. Verify
+
+```bash
+git log -2 --oneline
+```
+
+---
+
+## ERROR HANDLING:
+
+- **Commit fails (pre-commit hook):** Fix issue, stage, create NEW commit (don't amend)
+- **Task failed in apex:** PRD already reflects failure status — commit as-is
+
+---
+
+## NEXT STEP:
+
+After commit, proceed to `./step-04-check.md`