@atlashub/smartstack-cli 4.40.0 → 4.42.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/.documentation/apex.html +2 -2
  2. package/.documentation/business-analyse.html +26 -27
  3. package/.documentation/commands.html +6 -6
  4. package/dist/index.js +24 -13
  5. package/dist/index.js.map +1 -1
  6. package/package.json +2 -2
  7. package/templates/agents/ba-reader.md +2 -2
  8. package/templates/agents/ba-writer.md +44 -9
  9. package/templates/hooks/stop-hook.sh +6 -6
  10. package/templates/ralph/README.md +1 -1
  11. package/templates/scripts/setup-ralph-loop.sh +2 -2
  12. package/templates/skills/_resources/context-digest-template.md +1 -1
  13. package/templates/skills/_shared.md +13 -13
  14. package/templates/skills/apex/SKILL.md +15 -7
  15. package/templates/skills/apex/_shared.md +1 -1
  16. package/templates/skills/apex/references/analysis-methods.md +24 -0
  17. package/templates/skills/apex/references/challenge-questions.md +46 -13
  18. package/templates/skills/apex/references/core-seed-data.md +4 -4
  19. package/templates/skills/apex/references/error-classification.md +3 -3
  20. package/templates/skills/apex/references/smartstack-api.md +1 -1
  21. package/templates/skills/apex/references/smartstack-layers.md +1 -1
  22. package/templates/skills/apex/steps/step-00-init.md +48 -8
  23. package/templates/skills/apex/steps/step-01-analyze.md +42 -2
  24. package/templates/skills/apex/steps/step-02-plan.md +3 -1
  25. package/templates/skills/apex/steps/step-03-execute.md +3 -1
  26. package/templates/skills/apex/steps/step-03a-layer0-domain.md +2 -0
  27. package/templates/skills/apex/steps/step-03b-layer1-seed.md +111 -3
  28. package/templates/skills/apex/steps/step-03c-layer2-backend.md +2 -0
  29. package/templates/skills/apex/steps/step-03d-layer3-frontend.md +2 -0
  30. package/templates/skills/apex/steps/step-03e-layer4-devdata.md +2 -0
  31. package/templates/skills/apex/steps/step-04-examine.md +18 -0
  32. package/templates/skills/business-analyse/SKILL.md +83 -22
  33. package/templates/skills/business-analyse/_shared.md +12 -9
  34. package/templates/skills/business-analyse/questionnaire/02-stakeholders-scope.md +13 -0
  35. package/templates/skills/business-analyse/questionnaire/03-data-ui.md +33 -0
  36. package/templates/skills/business-analyse/questionnaire/04-risks-metrics.md +1 -1
  37. package/templates/skills/business-analyse/react/components.md +1 -1
  38. package/templates/skills/business-analyse/react/schema.md +1 -1
  39. package/templates/skills/business-analyse/references/acceptance-criteria.md +3 -3
  40. package/templates/skills/business-analyse/references/consolidation-structural-checks.md +1 -1
  41. package/templates/skills/business-analyse/references/detection-strategies.md +2 -2
  42. package/templates/skills/business-analyse/references/entity-architecture-decision.md +1 -1
  43. package/templates/skills/business-analyse/references/naming-conventions.md +6 -6
  44. package/templates/skills/business-analyse/references/robustness-checks.md +4 -4
  45. package/templates/skills/business-analyse/references/spec-auto-inference.md +2 -2
  46. package/templates/skills/business-analyse/references/validation-checklist.md +3 -3
  47. package/templates/skills/business-analyse/schemas/feature-schema.json +1 -1
  48. package/templates/skills/business-analyse/schemas/sections/handoff-schema.json +2 -2
  49. package/templates/skills/business-analyse/schemas/sections/specification-schema.json +3 -2
  50. package/templates/skills/business-analyse/steps/step-00-init.md +15 -5
  51. package/templates/skills/business-analyse/steps/step-01-cadrage.md +14 -5
  52. package/templates/skills/business-analyse/steps/step-02-structure.md +17 -1
  53. package/templates/skills/business-analyse/steps/step-03-specify.md +136 -26
  54. package/templates/skills/business-analyse/steps/step-04-consolidate.md +44 -8
  55. package/templates/skills/business-analyse/templates/tpl-handoff.md +5 -5
  56. package/templates/skills/business-analyse/templates/tpl-launch-displays.md +4 -4
  57. package/templates/skills/business-analyse/templates-frd.md +4 -4
  58. package/templates/skills/{ba-design-ui → business-analyse-design}/SKILL.md +9 -9
  59. package/templates/skills/{ba-design-ui → business-analyse-design}/steps/step-01-screens.md +9 -0
  60. package/templates/skills/{ba-design-ui → business-analyse-design}/steps/step-03-navigation.md +9 -2
  61. package/templates/skills/business-analyse-develop/SKILL.md +248 -0
  62. package/templates/skills/{ralph-loop → business-analyse-develop}/references/category-completeness.md +1 -1
  63. package/templates/skills/{ralph-loop → business-analyse-develop}/references/init-resume-recovery.md +8 -8
  64. package/templates/skills/{ralph-loop → business-analyse-develop}/references/multi-module-queue.md +1 -1
  65. package/templates/skills/business-analyse-develop/references/quality-gates.md +70 -0
  66. package/templates/skills/{ralph-loop → business-analyse-develop}/references/task-transform-legacy.md +1 -1
  67. package/templates/skills/{ralph-loop → business-analyse-develop}/steps/step-00-init.md +20 -4
  68. package/templates/skills/{ralph-loop → business-analyse-develop}/steps/step-01-task.md +3 -2
  69. package/templates/skills/business-analyse-develop/steps/step-01-v4-execute.md +131 -0
  70. package/templates/skills/business-analyse-develop/steps/step-02-v4-verify.md +156 -0
  71. package/templates/skills/{ralph-loop → business-analyse-develop}/steps/step-04-check.md +1 -1
  72. package/templates/skills/{ralph-loop → business-analyse-develop}/steps/step-05-report.md +1 -1
  73. package/templates/skills/{derive-prd → business-analyse-handoff}/SKILL.md +7 -7
  74. package/templates/skills/{derive-prd → business-analyse-handoff}/references/acceptance-criteria.md +5 -5
  75. package/templates/skills/{derive-prd → business-analyse-handoff}/references/handoff-file-templates.md +1 -1
  76. package/templates/skills/{derive-prd → business-analyse-handoff}/references/handoff-mappings.md +1 -1
  77. package/templates/skills/{derive-prd → business-analyse-handoff}/references/handoff-seeddata-generation.md +2 -2
  78. package/templates/skills/{derive-prd → business-analyse-handoff}/references/prd-generation.md +14 -14
  79. package/templates/skills/{derive-prd → business-analyse-handoff}/schemas/handoff-schema.json +2 -2
  80. package/templates/skills/{derive-prd → business-analyse-handoff}/steps/step-00-validate.md +6 -6
  81. package/templates/skills/{derive-prd → business-analyse-handoff}/steps/step-01-transform.md +46 -7
  82. package/templates/skills/{derive-prd → business-analyse-handoff}/steps/step-02-export.md +34 -14
  83. package/templates/skills/{ba-generate-html → business-analyse-html}/SKILL.md +4 -4
  84. package/templates/skills/{ba-generate-html → business-analyse-html}/html/ba-interactive.html +709 -277
  85. package/templates/skills/{ba-generate-html → business-analyse-html}/html/build-html.js +25 -3
  86. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/scripts/01-data-init.js +54 -0
  87. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/scripts/02-navigation.js +97 -3
  88. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/scripts/03-render-cadrage.js +8 -7
  89. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/scripts/04-render-modules.js +7 -7
  90. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/scripts/05-render-specs.js +188 -85
  91. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/scripts/06-render-consolidation.js +15 -14
  92. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/scripts/06-render-mockups.js +19 -19
  93. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/scripts/07-render-handoff.js +24 -4
  94. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/scripts/08-editing.js +6 -2
  95. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/scripts/09-export.js +27 -57
  96. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/scripts/10-comments.js +67 -45
  97. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/scripts/11-review-panel.js +15 -13
  98. package/templates/skills/business-analyse-html/html/src/styles/02-layout.css +216 -0
  99. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/styles/05-modules.css +36 -0
  100. package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/template.html +22 -12
  101. package/templates/skills/{ba-generate-html → business-analyse-html}/references/data-build.md +1 -1
  102. package/templates/skills/{ba-generate-html → business-analyse-html}/references/data-mapping.md +5 -1
  103. package/templates/skills/{ba-generate-html → business-analyse-html}/references/output-modes.md +7 -7
  104. package/templates/skills/{ba-generate-html → business-analyse-html}/steps/step-01-collect.md +25 -1
  105. package/templates/skills/{ba-generate-html → business-analyse-html}/steps/step-02-build-data.md +33 -5
  106. package/templates/skills/{ba-generate-html → business-analyse-html}/steps/step-03-render.md +2 -2
  107. package/templates/skills/{ba-generate-html → business-analyse-html}/steps/step-04-verify.md +2 -2
  108. package/templates/skills/{ba-review → business-analyse-review}/SKILL.md +11 -10
  109. package/templates/skills/{ba-review → business-analyse-review}/references/review-data-mapping.md +2 -2
  110. package/templates/skills/business-analyse-review/steps/step-00-init.md +107 -0
  111. package/templates/skills/{ba-review → business-analyse-review}/steps/step-01-apply.md +19 -11
  112. package/templates/skills/business-analyse-status/SKILL.md +118 -0
  113. package/templates/skills/documentation/SKILL.md +2 -2
  114. package/templates/skills/sketch/SKILL.md +172 -0
  115. package/templates/skills/sketch/references/domain-heuristics.md +116 -0
  116. package/templates/skills/ba-generate-html/html/src/styles/02-layout.css +0 -101
  117. package/templates/skills/ralph-loop/SKILL.md +0 -240
  118. /package/templates/skills/{ba-design-ui → business-analyse-design}/steps/step-02-wireframes.md +0 -0
  119. /package/templates/skills/{ralph-loop → business-analyse-develop}/references/category-rules.md +0 -0
  120. /package/templates/skills/{ralph-loop → business-analyse-develop}/references/compact-loop.md +0 -0
  121. /package/templates/skills/{ralph-loop → business-analyse-develop}/references/module-transition.md +0 -0
  122. /package/templates/skills/{ralph-loop → business-analyse-develop}/references/parallel-execution.md +0 -0
  123. /package/templates/skills/{ralph-loop → business-analyse-develop}/references/section-splitting.md +0 -0
  124. /package/templates/skills/{ralph-loop → business-analyse-develop}/references/team-orchestration.md +0 -0
  125. /package/templates/skills/{ralph-loop → business-analyse-develop}/steps/step-02-execute.md +0 -0
  126. /package/templates/skills/{ralph-loop → business-analyse-develop}/steps/step-03-commit.md +0 -0
  127. /package/templates/skills/{derive-prd → business-analyse-handoff}/references/entity-domain-mapping.md +0 -0
  128. /package/templates/skills/{derive-prd → business-analyse-handoff}/references/readiness-scoring.md +0 -0
  129. /package/templates/skills/{derive-prd → business-analyse-handoff}/templates/tpl-progress.md +0 -0
  130. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/partials/cadrage-context.html +0 -0
  131. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/partials/cadrage-scope.html +0 -0
  132. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/partials/cadrage-stakeholders.html +0 -0
  133. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/partials/cadrage-success.html +0 -0
  134. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/partials/consol-datamodel.html +0 -0
  135. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/partials/consol-flows.html +0 -0
  136. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/partials/consol-interactions.html +0 -0
  137. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/partials/consol-permissions.html +0 -0
  138. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/partials/decomp-dependencies.html +0 -0
  139. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/partials/decomp-modules.html +0 -0
  140. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/partials/handoff-summary.html +0 -0
  141. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/partials/module-spec-container.html +0 -0
  142. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/styles/01-variables.css +0 -0
  143. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/styles/03-navigation.css +0 -0
  144. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/styles/04-cards.css +0 -0
  145. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/styles/06-wireframes.css +0 -0
  146. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/styles/07-comments.css +0 -0
  147. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/styles/08-review-panel.css +0 -0
  148. /package/templates/skills/{ba-generate-html → business-analyse-html}/html/src/styles/09-mockups-html.css +0 -0
  149. /package/templates/skills/{ba-generate-html → business-analyse-html}/references/wireframe-svg-style-guide.md +0 -0
@@ -1,101 +0,0 @@
1
- /* ============================================
2
- LAYOUT
3
- ============================================ */
4
- .app { display: flex; flex-direction: column; min-height: 100vh; }
5
-
6
- .header {
7
- background: var(--bg-card);
8
- border-bottom: 1px solid var(--border);
9
- height: var(--header-height);
10
- display: flex;
11
- align-items: center;
12
- padding: 0 1.5rem;
13
- gap: 1rem;
14
- position: sticky;
15
- top: 0;
16
- z-index: 100;
17
- }
18
-
19
- .header-logo {
20
- width: 32px; height: 32px;
21
- background: linear-gradient(135deg, var(--primary), var(--secondary));
22
- border-radius: 6px;
23
- display: flex; align-items: center; justify-content: center;
24
- font-weight: 700; font-size: 0.85rem; color: #fff;
25
- flex-shrink: 0;
26
- }
27
-
28
- .header-title { font-size: 1rem; font-weight: 600; color: var(--text-bright); }
29
- .header-sep { width: 1px; height: 24px; background: var(--border); }
30
- .header-app-name { font-size: 0.9rem; color: var(--primary-light); font-weight: 500; }
31
- .header-spacer { flex: 1; }
32
-
33
- .header-actions { display: flex; gap: 0.5rem; }
34
-
35
- .body { display: flex; flex: 1; }
36
-
37
- /* ============================================
38
- SIDEBAR - Container
39
- ============================================ */
40
- .sidebar {
41
- width: var(--sidebar-width);
42
- background: var(--bg-card);
43
- border-right: 1px solid var(--border);
44
- overflow-y: auto;
45
- height: calc(100vh - var(--header-height));
46
- position: sticky;
47
- top: var(--header-height);
48
- flex-shrink: 0;
49
- }
50
-
51
- .sidebar::-webkit-scrollbar { width: 4px; }
52
- .sidebar::-webkit-scrollbar-thumb { background: var(--border); border-radius: 4px; }
53
-
54
- /* ============================================
55
- MAIN CONTENT - FULL WIDTH
56
- ============================================ */
57
- .main {
58
- flex: 1;
59
- padding: 2rem 3rem;
60
- overflow-y: auto;
61
- height: calc(100vh - var(--header-height));
62
- }
63
-
64
- .section { margin-bottom: 4rem; }
65
- .section-title {
66
- font-size: 1.4rem;
67
- color: var(--text-bright);
68
- font-weight: 600;
69
- margin-bottom: 0.5rem;
70
- padding-bottom: 0.5rem;
71
- border-bottom: 2px solid var(--primary);
72
- }
73
- .section-subtitle {
74
- font-size: 0.9rem;
75
- color: var(--text-muted);
76
- margin-bottom: 1.5rem;
77
- }
78
-
79
- /* ============================================
80
- RESPONSIVE
81
- ============================================ */
82
- @media (max-width: 768px) {
83
- .sidebar { display: none; }
84
- .main { padding: 1rem; }
85
- .form-row { grid-template-columns: 1fr; }
86
- .stakeholder-grid { grid-template-columns: 1fr; }
87
- }
88
-
89
- /* ============================================
90
- PRINT
91
- ============================================ */
92
- @media print {
93
- .sidebar, .header-actions, .add-btn, .uc-actions, .inline-form, .module-card-remove { display: none !important; }
94
- .main { max-width: 100%; padding: 0; }
95
- .section { display: block !important; page-break-inside: avoid; }
96
- body { background: #fff; color: #1a1a1a; }
97
- .card, .uc-item, .br-item, .module-card, .entity-block, .interaction-item { border-color: #ddd; }
98
- .tab-panel { display: block !important; }
99
- .tab-bar { display: none; }
100
- .review-panel, .comment-btn-container { display: none !important; }
101
- }
@@ -1,240 +0,0 @@
1
- ---
2
- name: ralph-loop
3
- description: Iterative AI development loop with MCP validation, progress tracking, and completion promises.
4
- argument-hint: "[-m N] [-c TEXT] [-v] <task description>"
5
- ---
6
-
7
- <objective>
8
- 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.
9
-
10
- **Key principle:** Ralph ORCHESTRATES (task selection, module sequencing, PRD state, reporting). All code generation is delegated to `/apex`.
11
- </objective>
12
-
13
- <quick_start>
14
-
15
- **From Business Analysis (RECOMMENDED):**
16
- ```bash
17
- /business-analyse MyFeature
18
- # Then: /derive-prd
19
- # Then: /ralph-loop -r
20
- ```
21
-
22
- **Manual start:**
23
- ```bash
24
- /ralph-loop implement user authentication
25
- /ralph-loop -c "COMPLETE" -m 20 refactor cache layer
26
- /ralph-loop -r # Resume previous
27
- ```
28
-
29
- **Flags:** `-m N` (max iterations), `-c TEXT` (completion promise), `-v` (verbose), `-r` (resume)
30
-
31
- </quick_start>
32
-
33
- <parameters>
34
- | Short | Long | Description |
35
- |-------|------|-------------|
36
- | `-m N` | `--max-iterations N` | Max iterations (default: 50) |
37
- | `-c TEXT` | `--completion-promise TEXT` | Completion signal text |
38
- | `-v` | `--verbose` | Detailed logging |
39
- | `-r` | `--resume` | Resume from previous state |
40
- | `-p` | `--parallel` | Teams mode: Phase 0 (entities) sequential, then spawn parallel teammates per application/module |
41
- </parameters>
42
-
43
- <workflow>
44
-
45
- **Single module:**
46
- 1. Init: parse flags, verify MCP, setup .ralph/ (step-00)
47
- 2. Load tasks from prd.json — unified v3 has pre-computed tasks (step-01, step FILE read once)
48
- 3. Execute first task (step-02, step FILE read once)
49
- 4. Commit + update progress (step-03, step FILE read once)
50
- 5. Check completion → enter COMPACT LOOP (step-04)
51
- 6. **COMPACT LOOP** (step-04 → references/compact-loop.md):
52
- - Find eligible → batch by category (max 5) → execute → test → commit → loop
53
- 7. Report (step-05)
54
-
55
- **Multi-module (2+ modules) with `-p` (parallel mode):**
56
- 1. Init: detect prd-*.json, parse `-p` flag (step-00)
57
- 2. **Phase 0 (Ralph sequential):**
58
- - Ralph generates ALL entities from ALL modules via `/apex --foundation`
59
- - Creates ONE migration with all entities
60
- - Commits: `chore(foundation): entities for all modules`
61
- 3. **Phase 1-N (Teams parallel):**
62
- ```
63
- Team Lead → TeamCreate("smartstack-{project}")
64
- Spawn teammates (1 per application OR 1 per module if app > 3 modules):
65
- - Task(subagent_type: "apex", name: "apex-hr")
66
- - Task(subagent_type: "apex", name: "apex-crm")
67
- - Task(subagent_type: "apex", name: "apex-pm")
68
- Each teammate generates:
69
- - Services + Controllers + Seed data + Frontend + Tests
70
- - NO entities (already done in Phase 0)
71
- - NO migrations (ModelSnapshot already complete)
72
- → Teammates work in parallel → Ralph collects results → TeamDelete
73
- ```
74
- 4. Report with per-module aggregation (step-05)
75
-
76
- **Multi-module (2+ modules) WITHOUT `-p` (sequential mode — legacy):**
77
- 1. Init: detect prd-*.json, read dependency layers (step-00)
78
- 2. **IF dependency graph available:** Agent Teams (parallel, legacy)
79
- ```
80
- Team Lead → TeamCreate("ralph-{app}")
81
- Layer 0: Spawn "mod-employees" (foundation) → wait LAYER_READY
82
- Layer 1: Spawn "mod-timetracking" + "mod-leavemanagement" (parallel)
83
- Layer 2: Spawn "mod-reporting"
84
- → Cross-module verify → Report → TeamDelete
85
- ```
86
- 3. **IF no dependency graph:** Sequential (compact loop per module)
87
- 4. Report with per-module aggregation (step-05)
88
-
89
- **Task execution cycle:**
90
- ```
91
- LOAD → DELEGATE TO /apex -d → VERIFY PRD STATE → COMMIT PRD → NEXT MODULE
92
- ```
93
-
94
- </workflow>
95
-
96
- <state_variables>
97
- | Variable | Type | Description |
98
- |----------|------|-------------|
99
- | `{task_description}` | string | The task to execute |
100
- | `{max_iterations}` | number | Max iterations |
101
- | `{completion_promise}` | string | Completion signal |
102
- | `{current_iteration}` | number | Current iteration |
103
- | `{current_module}` | string\|null | Current module (multi-module) |
104
- | `{modules_queue}` | object\|null | Module queue (multi-module) |
105
- | `{section_split_mode}` | boolean | Section splitting active for current module (>4 entities + >1 section) |
106
- | `{section_phases}` | SectionPhase[] | Phase execution plan (Phase 0: foundation, Phase 1..N: per-section) |
107
- | `{parallel_mode}` | boolean | Teams mode enabled via `-p` flag. Ralph generates Phase 0 (entities) sequentially, then spawns parallel teammates. |
108
- | `{team_name}` | string\|null | Team name for parallel mode (e.g., "smartstack-hr") |
109
- | `{team_active}` | boolean | True after `TeamCreate`, false after `TeamDelete`. Used in step-04 section 3a to send `MODULE_COMPLETE` to team-lead instead of advancing the module queue locally. |
110
- </state_variables>
111
-
112
- <mcp_requirements>
113
- **MANDATORY before any work:**
114
- 1. `mcp__smartstack__validate_conventions` — verify connectivity
115
- 2. `mcp__context7__resolve-library-id` — verify connectivity
116
-
117
- **During work:** All MCP tool calls are handled by `/apex` during delegation. Ralph only uses `validate_conventions` for initial connectivity check.
118
- </mcp_requirements>
119
-
120
- <execution_guarantee>
121
-
122
- ## EXECUTION GUARANTEE — READ THIS FIRST
123
-
124
- **Ralph-loop executes ALL tasks from start to finish. No exceptions.**
125
-
126
- When the user invokes `/ralph-loop`, they are giving you the instruction to:
127
- 1. Initialize the loop (step-00)
128
- 2. Load ALL tasks (step-01)
129
- 3. Execute the FIRST task (step-02)
130
- 4. Commit (step-03)
131
- 5. Enter the COMPACT LOOP (step-04 → compact-loop.md)
132
- 6. **Execute ALL remaining tasks autonomously** (compact loop repeats)
133
- 7. Generate the final report (step-05)
134
-
135
- **You MUST NOT:**
136
- - Stop after the first task to "ask for confirmation"
137
- - Set `max_iterations = 1` or any reduced value
138
- - Ask the user to choose between supervised/autonomous mode
139
- - Ask the user to choose a completion promise
140
- - Wait for user input between iterations
141
- - Delegate the loop to sub-agents (except team mode and /apex delegation)
142
-
143
- **The ONLY valid stop conditions are:**
144
- - ALL tasks completed (→ step-05 report)
145
- - `max_iterations` reached (user set via `-m N`)
146
- - Dead-end (all remaining blocked/failed)
147
- - User Ctrl+C
148
-
149
- **If you stop for any other reason, you have VIOLATED this guarantee.**
150
-
151
- </execution_guarantee>
152
-
153
- <entry_point>
154
- **FIRST ACTION:** Load `steps/step-00-init.md` — then execute ALL steps through to step-05 without stopping.
155
- </entry_point>
156
-
157
- <step_files>
158
- | Step | File | Purpose | Target Lines |
159
- |------|------|---------|-------------|
160
- | 00 | `steps/step-00-init.md` | Parse args, verify MCP, init state, team setup | ~150 |
161
- | 01 | `steps/step-01-task.md` | Load/create tasks from prd.json | ~365 |
162
- | 02 | `steps/step-02-execute.md` | Delegate module to /apex -d | ~120 |
163
- | 03 | `steps/step-03-commit.md` | Commit, update prd.json/progress.txt | ~135 |
164
- | 04 | `steps/step-04-check.md` | Check completion, compact loop entry | ~185 |
165
- | 05 | `steps/step-05-report.md` | Generate final report | ~150 |
166
-
167
- > **"Read Once" rule:** Each **step file** (step-01 to step-04) is loaded only once at the start of the first iteration. From iteration 2 onward, `compact-loop.md` drives the loop inline — step files are NOT re-read. This reduces context consumption. **Exception:** prd.json is re-read every iteration (it changes); step files are not.
168
-
169
- > **Distinction:** `/apex -d prd.json` is invoked every iteration (B2 of compact-loop) — that is normal and expected. "Read Once" applies only to the step instruction files, not to data files or apex delegations.
170
-
171
- **Reference files (loaded conditionally):**
172
- | File | Loaded when |
173
- |------|-------------|
174
- | `references/category-rules.md` | Step-01 and compact loop (category ordering and dependency rules) |
175
- | `references/category-completeness.md` | Step-01 section 4b and step-04 section 1.7 (guardrail injection) |
176
- | `references/compact-loop.md` | Step-04 section 5 (module loop with /apex delegation) |
177
- | `references/init-resume-recovery.md` | Step-00 section 4 (resume mode and auto-recovery) |
178
- | `references/multi-module-queue.md` | Step-00 and step-01 section 0 (multi-module initialization) |
179
- | `references/module-transition.md` | Step-04 section 3b (multi-module advancement) |
180
- | `references/parallel-execution.md` | Step-02 section 3a (Agent Teams for multi-module) |
181
- | `references/section-splitting.md` | Step-01 section 4c when module has >4 entities + >1 section |
182
- | `references/task-transform-legacy.md` | Step-01 (legacy FORMAT A PRD transformation) |
183
- | `references/team-orchestration.md` | Step-00 when multi-module detected (2+ PRDs) |
184
- </step_files>
185
-
186
- <file_structure>
187
- ```
188
- .ralph/
189
- ├── prd.json # Active task list (unified v3: reference data + pre-computed tasks)
190
- ├── progress.txt # Persistent memory
191
- ├── modules-queue.json # Multi-module tracking (if applicable)
192
- ├── prd-{module}.json # Per-module PRDs (from ss derive-prd, unified v3 format)
193
- ├── prd-{module}-phase0.json # Section split: Foundation (domain+infra+migration)
194
- ├── prd-{module}-section-{code}.json # Section split: Per-section (app+api+seed+frontend+tests)
195
- ├── logs/
196
- └── reports/
197
- └── {feature}.md
198
- ```
199
- </file_structure>
200
-
201
- <execution_rules>
202
-
203
- ### NON-NEGOTIABLE — Autonomous Full Execution
204
- - **EXECUTE ALL TASKS** — from first to last, no user interaction, no pause, no confirmation
205
- - **NEVER ask the user** — no mode selection, no completion promise choice, no "shall I continue?"
206
- - **NEVER stop after first task** — the first task is just the beginning, NOT the end
207
- - **NEVER set max_iterations = 1** — unless the user explicitly passed `-m 1`
208
-
209
- ### Loop Mechanics
210
- - **Single module:** Main agent runs compact loop (NEVER delegate to sub-agent)
211
- - **Multi-module (2+):** Team lead + module workers via TeamCreate (see references/team-orchestration.md)
212
- - **Load step files ONCE** — after first iteration, use compact-loop.md
213
- - **VERIFY MCP FIRST** — never skip
214
- - **BATCH** same-category tasks (max 5 per iteration)
215
- - **COMMIT** after each batch (not per task)
216
- - **NEVER fake completion** — only output promise when truly done
217
- - **NEVER stop the loop** — autonomous until complete, max iterations, or dead-end
218
- - **CONTEXT BUDGET** — compact output during loop (1-2 lines per task)
219
- - **MODULE COMPLETENESS** — all layers (domain, infra, app, api, frontend, test) before advancing
220
- - **MIGRATION MANDATORY** — after EF configs, before tests (no DB = no tests)
221
- - **TESTS BLOCKING** — 100% pass before proceeding to next task
222
-
223
- </execution_rules>
224
-
225
- <success_criteria>
226
- - All tasks completed (or skipped) in prd.json
227
- - MCP validations pass
228
- - Git commits atomic with commit_hash tracked
229
- - Tests pass (dotnet test + npm test)
230
- - Migrations created and applied
231
- - Seed data complete (navigation, permissions, roles via MCP)
232
- - Frontend in correct hierarchy (Context/App/Module)
233
- - Report generated in .ralph/reports/
234
- - Multi-module: all modules processed, cross-module report
235
- </success_criteria>
236
-
237
- <available_commands>
238
- - `/ralph-loop:cancel-ralph` — Cancel active loop
239
- - `/ralph-loop:help` — Show documentation
240
- </available_commands>