@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/business-analyse-develop/steps/step-00-init.md

@@ -1,242 +0,0 @@
----
-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.
-**DO NOT** display a progress report and then ask "shall I continue?" or present numbered options.
-**DO NOT** pause because the scope seems large — 500+ files across 11 modules is NORMAL. Execute ALL of it.
-
-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 business-analyse-develop.
-```
-
-## 4. Resume or Initialize
-
-See `references/init-resume-recovery.md` for complete Resume Mode, Auto-Recovery, and Ralph State Recovery logic.
-
-**Quick:**
-- If `-r` flag: restore state from .ralph/prd.json + .ralph/ralph-state.json
-- Else if `.ralph/ralph-state.json` exists: recover position (step, module, iteration) — see init-resume-recovery.md "Ralph State Recovery"
-- Else if BA artifacts exist: auto-recover PRDs via `ss business-analyse-handoff`
-- 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
-
-### 4b+. Normalize modules-queue.json (backward-compat with handoff v1 format)
-
-```javascript
-const queuePath = '.ralph/modules-queue.json';
-if (fileExists(queuePath)) {
-  const raw = readJSON(queuePath);
-  let dirty = false;
-
-  // RC1: Rename "queue" → "modules" property (handoff v1 used "queue")
-  if (raw.queue && !raw.modules) {
-    raw.modules = raw.queue;
-    delete raw.queue;
-    dirty = true;
-  }
-
-  // RC2: Rename "moduleCode" → "code" in each entry (handoff v1 used "moduleCode")
-  for (const mod of (raw.modules || [])) {
-    if (mod.moduleCode && !mod.code) {
-      mod.code = mod.moduleCode;
-      delete mod.moduleCode;
-      dirty = true;
-    }
-  }
-
-  // RC3: Add missing fields
-  if (raw.currentIndex === undefined) { raw.currentIndex = 0; dirty = true; }
-  if (raw.completedModules === undefined) { raw.completedModules = 0; dirty = true; }
-  if (raw.totalModules === undefined) { raw.totalModules = raw.modules?.length || 0; dirty = true; }
-  for (const mod of (raw.modules || [])) {
-    if (!mod.prdFile) { mod.prdFile = `.ralph/prd-${mod.code}.json`; dirty = true; }
-    if (!mod.status) { mod.status = 'pending'; dirty = true; }
-  }
-  // Set first module to in-progress if none started
-  if (raw.modules?.length && !raw.modules.some(m => m.status !== 'pending')) {
-    raw.modules[0].status = 'in-progress';
-    dirty = true;
-  }
-
-  if (dirty) {
-    writeJSON(queuePath, raw);
-    console.log('modules-queue.json normalized (format v2)');
-  }
-}
-```
-
----
-
-## 4c. Team Orchestration (multi-module LEGACY — dependency layer mode only)
-
-> **MANDATORY:** Load `references/team-orchestration.md` BEFORE creating any team.
-> The full spawn protocol (teammate prompts, wait logic, layer coordination, cleanup)
-> is defined there. Creating a team without loading it results in an empty team with no teammates.
-
-> **PARALLEL MODE (`-p`):** Team creation does NOT happen here. It happens in step-02 section 3a,
-> after step-01 loads the tasks. Sections 5-7 below (completion promise, metadata, summary) must
-> still be executed. Do NOT return early when `{parallel_mode}` is true.
-
-```javascript
-if (PRD_COUNT > 1) {
-  // STEP 1: Load references/team-orchestration.md NOW (before any TeamCreate call)
-  // This file contains: mode selection, Phase 0 protocol (parallel), layer protocol (legacy), cleanup.
-
-  const layers = master.metadata?.workflow?.dependencyGraph?.layers;
-
-  if (layers && !{parallel_mode}) {
-    // DEPENDENCY LAYER MODE (legacy, no -p flag): team orchestration takes over here.
-    // TeamCreate + spawn logic are defined in references/team-orchestration.md section "Dependency Layer Mode".
-    // STOP here — legacy team orchestration handles everything from this point.
-    return;
-  }
-  // PARALLEL MODE (-p): fall through to sections 5-7, team created later in step-02 section 3a.
-  // NO -p, NO layers: fall through to sequential mode (compact loop per module).
-}
-```
-
----
-
-## 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 "try{console.log(require('./package.json').version)}catch(e){console.log('unknown')}" 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} }
-}
-```
-
-## 6b. Detect PRD Version
-
-```javascript
-const prdFile = readJSON('.ralph/prd.json') || readJSON(glob('.ralph/prd-*.json')[0]);
-const prd_version = prdFile?.$version || '3.0.0';
-
-if (prd_version === '4.0.0') {
-  // v4 spec-oriented: continuous execution, compaction manages context
-  // → Load step-01-v4-execute.md instead of step-01-task.md
-} else {
-  // v3 task-oriented: batch iterations, compact-loop
-  // → Load step-01-task.md (legacy)
-}
-```
-
-## 7. Show Summary
-
-```
-RALPH LOOP INITIALIZED
-Task: {task_description} | Max: {max_iterations} | Promise: {completion_promise}
-MCP: Ready | Branch: {branch} | PRD: v{prd_version}
-{modules_queue ? `Modules: ${totalModules} (${module_codes.join(' → ')})` : 'Mode: single module'}
-{prd_version === '4.0.0' ? '→ v4 continuous mode (compaction-enabled)' : '→ v3 batch mode (compact-loop)'}
--> Loading spec...
-```
-
-### 7b. Initialize State File (context compression defense)
-
-> **ralph-state.json is written here AND updated by step-02, compact-loop, and module-transition.**
-> On resume or after context compression, `init-resume-recovery.md` reads it back to route
-> to the correct step instead of always restarting from step-01.
-
-```javascript
-writeJSON('.ralph/ralph-state.json', {
-  currentStep: 'step-01-task',
-  currentModule: {current_module},
-  iteration: 1,
-  prdVersion: {prd_version},
-  modulesQueuePath: fileExists('.ralph/modules-queue.json') ? '.ralph/modules-queue.json' : null,
-  timestamp: new Date().toISOString()
-});
-```
-
-**Step routing:** If ralph-state recovery (section 4) provided a different target step, load THAT step.
-Otherwise, proceed to step-01-task.md.

package/templates/skills/business-analyse-develop/steps/step-01-task.md

@@ -1,182 +0,0 @@
----
-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
-
-> **STATE RECOVERY (executable):** If context was compressed and you are unsure of your position:
-```javascript
-if (fileExists('.ralph/ralph-state.json')) {
-  const state = readJSON('.ralph/ralph-state.json');
-  if (state.currentStep && state.currentStep !== 'step-01-task') {
-    console.warn(`RECOVERY: ralph-state.json says currentStep="${state.currentStep}" but we are in step-01.`);
-    console.warn(`This may indicate context compression routed to the wrong step.`);
-    console.warn(`Current module: ${state.currentModule}, iteration: ${state.iteration}`);
-  }
-  // Restore module context
-  if (state.currentModule) { {current_module} = state.currentModule; }
-  if (state.iteration) { {current_iteration} = state.iteration; }
-}
-```
-
-> **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
-
-```javascript
-// PRD PATH RESOLUTION (MANDATORY - runs before any PRD access)
-const queuePath = '.ralph/modules-queue.json';
-let currentPrdPath = '.ralph/prd.json';
-if (fileExists(queuePath)) {
-  const queue = readJSON(queuePath);
-  currentPrdPath = queue.modules[queue.currentIndex].prdFile;
-}
-```
-
-If `{currentPrdPath}` 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 `{currentPrdPath}`
-   - **Run CATEGORY COMPLETENESS CHECK (section 4b) before proceeding**
-   - Skip directly to section 5 (find next task)
-2b. **v3 filesToCreate PATH:** If `$version === "3.0.0"` AND `implementation.filesToCreate` exists AND NO `tasks[]`:
-   → **Load** `references/prd-v3-transformation.md` for the filesToCreate → tasks transformation algorithm and deriveAcceptanceCriteria() function.
-   → Run CATEGORY COMPLETENESS CHECK (section 4b) — will detect if seedData is missing
-   → Skip 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 `{currentPrdPath}` does not exist: continue to section 1b.
-
-### 1b. BA Handoff Quality Gate (BLOCKING when BA artifacts present)
-
-> **Load** `references/handoff-quality-gate.md` for full BA handoff validation checks.
-
-Quick check:
-- If no BA artifacts detected (`sourceFeatureJson` is null): skip gate, proceed in manual mode
-- If BA artifacts present: verify `feature.handoff.status === "handed-off"` and `filesToCreate[]` has all categories
-
-## 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 → seedData → frontend → i18n → test → validation).
-
-**seedData category is MANDATORY** — generates navigation entries, permissions, roles, and the IClientSeedDataProvider.
-Without seedData tasks, modules are invisible in the UI (no menu, no permissions, no RBAC).
-
-## 3. Create prd.json
-
-Write `{currentPrdPath}` 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`

package/templates/skills/business-analyse-develop/steps/step-01-v4-execute.md

@@ -1,139 +0,0 @@
----
-name: step-01-v4-execute
-description: Continuous execution — delegate full module to /apex with quality gates
-model: opus
-next_step: steps/step-02-v4-verify.md
----
-
-# Step 01-v4: Continuous Module Execution
-
-## EXECUTION GUARANTEE — AUTONOMY RULES (MANDATORY)
-
-> **NEVER stop between modules.** NEVER ask "shall I continue?". NEVER present options (1/2/3).
-> **NEVER pause after a progress report.** Progress reports are LOG OUTPUT ONLY — print them and IMMEDIATELY continue to the next module.
-> **The user invoked /business-analyse-develop to execute ALL modules to completion.** That is your mandate. Any stop that is not: all-complete, dead-end, or Ctrl+C is a **VIOLATION**.
-
-## YOUR TASK
-
-For each module in topological order, delegate the ENTIRE module implementation to `/apex -d` in a continuous session. Run quality gates at natural checkpoints. Let server-side compaction manage context.
-
----
-
-## EXECUTION SEQUENCE
-
-### 1. For Each Module in Queue
-
-```
-FOR module in topologicalOrder(modules):
-  1. Build apex delegation command
-  2. Delegate to /apex -d
-  3. Run quality gates after delegation completes
-  4. If gates fail → /apex fixes in same session
-  5. Module complete → advance to next
-```
-
-### 2. Build Apex Delegation
-
-Pass the FULL spec to apex — objectives, architecture, gates:
-
-```
-/apex -d .ralph/prd-{moduleCode}.json
-```
-
-Apex receives the v4 PRD and works autonomously through:
-1. **Domain layer** — entities, value objects, enums
-2. **Infrastructure** — EF configurations, DbContext registration
-3. **Migration** — ONE migration per module
-4. **Application** — services, DTOs, validators (implement ALL business rules)
-5. **API** — controllers with correct permissions
-6. **Seed data** — core (navigation, permissions, roles) + business
-7. **Frontend** — pages via `/ui-components`, routes, translations
-8. **Tests** — unit + integration via `scaffold_tests` (backend) + `scaffold_frontend_tests` (frontend). NO stubs, NO `Assert.True(true)`
-
-> Apex decides the order and approach. Ralph does NOT micro-manage.
-
-### 3. Quality Gates (Run After Apex Completes)
-
-After `/apex -d` returns, run ALL gates:
-
-```bash
-# Gate 1: Backend build (BLOCKING)
-dotnet build --no-restore 2>&1
-
-# Gate 2: Backend tests (BLOCKING)
-dotnet test --no-build 2>&1
-
-# Gate 3: Frontend checks (BLOCKING if frontend exists)
-npm run typecheck 2>&1
-npm test -- --run 2>&1
-```
-
-**If any gate fails:**
-1. DO NOT advance to next module
-2. Show the error to Claude (same conversation — compaction preserves context)
-3. Ask `/apex -d` to fix: `/apex -d "Fix build/test failures for module {moduleCode}"`
-4. Re-run gates
-5. Repeat until ALL gates pass (max 3 fix attempts per gate)
-
-### 4. MCP Validation Gates
-
-After build/test pass:
-
-```javascript
-// Security validation
-mcp__smartstack__validate_security({ projectPath: "." })
-
-// Convention validation
-mcp__smartstack__validate_conventions({ projectPath: "." })
-
-// Code review (semantic permission check)
-mcp__smartstack__review_code({ files: changedFiles, focus: "security" })
-```
-
-**Semantic permission check:** Verify that write endpoints (POST/PUT/DELETE) do NOT use Read-only permissions. Fix if found.
-
-### 5. BR Coverage Check
-
-For each business rule in `prd.brToCodeMapping`:
-1. Verify the target file exists on disk
-2. Grep for the rule implementation (method name or comment reference)
-3. If missing → delegate fix to apex: "Implement BR {ruleId} in {targetFile}"
-
-### 6. Stub Test Detection
-
-Grep test files for stub patterns:
-```bash
-grep -rn "Assert.True(true)\|Assert.Pass()\|// TODO\|throw new NotImplementedException" tests/ 2>/dev/null
-```
-
-If found → delegate fix to apex: "Replace stub tests with real implementations"
-
-### 7. Module Complete — CONTINUE IMMEDIATELY
-
-When ALL gates pass for a module:
-1. Log checkpoint: `"Module {moduleCode}: ALL GATES PASS"`
-2. Optionally append to progress.txt (human checkpoint)
-3. **IMMEDIATELY** advance to next module in queue — DO NOT pause, DO NOT ask user, DO NOT present options
-
-> **ANTI-STOP GUARD:** After logging the progress report, your VERY NEXT action MUST be starting the next module delegation (`/apex -d`). If there are no more modules, go to step-02-v4-verify. Outputting a progress report and then waiting for user input is a **VIOLATION** of the execution guarantee.
-
----
-
-## ERROR RECOVERY (v4)
-
-Unlike v3 (retry counter + re-delegation), v4 leverages compaction:
-
-| Scenario | v3 behavior | v4 behavior |
-|----------|-------------|-------------|
-| Build fails | Inject fix task, re-iterate | Same session: Claude sees the error, fixes, re-builds |
-| Test fails | Inject fix task, re-iterate | Same session: Claude reads failure, adjusts code, re-tests |
-| MCP rejects | Mark task failed, retry 3x | Same session: Claude reads rejection reason, corrects |
-| Apex crashes | State lost between batches | Compaction preserves context, resume from last point |
-
-**Key advantage:** Claude has FULL context of what it just generated + the exact error. No context loss between retry attempts.
-
----
-
-## NEXT STEP
-
-After ALL modules complete → Load: `steps/step-02-v4-verify.md`