@atlashub/smartstack-cli 1.13.2 → 1.14.0

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

@@ -0,0 +1,169 @@
+---
+name: step-01-task
+description: Load or create tasks from prd.json
+next_step: steps/step-02-execute.md
+---
+
+# Step 1: Load Task
+
+## YOUR TASK:
+
+Load the current task from prd.json or create initial task breakdown.
+
+**ULTRA THINK about task decomposition.**
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Check for Existing prd.json
+
+**If `.ralph/prd.json` exists:**
+- Read and parse the file
+- Find the next task with `passes: false`
+- Load into state
+- Skip to step 4
+
+**If `.ralph/prd.json` does NOT exist:**
+- Continue to step 2 (create tasks)
+
+### 2. Analyze Task Description
+
+**ULTRA THINK about the task:**
+
+- What are the logical subtasks?
+- What order should they be executed?
+- What are the success criteria for each?
+- What files will be modified?
+
+**Generate task breakdown:**
+
+For `{task_description}`, identify 3-10 subtasks.
+
+**Example for "implement user authentication":**
+```json
+{
+  "tasks": [
+    { "id": 1, "description": "Create User entity in Domain layer", "passes": false },
+    { "id": 2, "description": "Add User DbSet to ApplicationDbContext", "passes": false },
+    { "id": 3, "description": "Create EF Core migration", "passes": false },
+    { "id": 4, "description": "Implement IPasswordService", "passes": false },
+    { "id": 5, "description": "Implement IJwtService", "passes": false },
+    { "id": 6, "description": "Create AuthController with login endpoint", "passes": false },
+    { "id": 7, "description": "Add authentication middleware", "passes": false },
+    { "id": 8, "description": "Write integration tests", "passes": false }
+  ]
+}
+```
+
+### 3. Create prd.json
+
+**Write `.ralph/prd.json`:**
+
+```json
+{
+  "feature": "{task_description}",
+  "created": "{timestamp}",
+  "max_iterations": {max_iterations},
+  "completion_promise": "{completion_promise}",
+  "current_iteration": 1,
+  "tasks": [
+    { "id": 1, "description": "...", "passes": false },
+    { "id": 2, "description": "...", "passes": false }
+  ]
+}
+```
+
+**Initialize `.ralph/progress.txt`:**
+
+```markdown
+# Ralph Loop Progress
+
+## Task: {task_description}
+## Started: {timestamp}
+
+---
+
+## Iteration 1
+
+### Context
+Starting fresh implementation.
+
+### Learnings
+(To be updated after each iteration)
+```
+
+### 4. Find Current Task
+
+**Find the next task with `passes: false`:**
+
+```javascript
+const currentTask = tasks.find(t => !t.passes);
+```
+
+**If all tasks are `passes: true`:**
+- This shouldn't happen in step-01
+- If it does, skip to step-05 (report)
+
+**Store in state:**
+```
+{current_task_id}          = currentTask.id
+{current_task_description} = currentTask.description
+{tasks_completed}          = tasks.filter(t => t.passes).length
+{tasks_total}              = tasks.length
+```
+
+### 5. Read Previous Progress
+
+**If iteration > 1:**
+
+Read `.ralph/progress.txt` to understand:
+- What was done in previous iterations
+- Key learnings and context
+- Files that were modified
+- Issues encountered
+
+**This provides context for the current iteration.**
+
+### 6. Show Task Status
+
+**Display current state:**
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  ITERATION {current_iteration} / {max_iterations}                 ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Progress: {tasks_completed} / {tasks_total} tasks complete       ║
+║                                                                    ║
+║  Current Task:                                                     ║
+║  [{current_task_id}] {current_task_description}                   ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Previous Learnings:                                               ║
+║  {summary from progress.txt}                                       ║
+╚══════════════════════════════════════════════════════════════════╝
+
+-> Executing task...
+```
+
+---
+
+## OUTPUT FORMAT:
+
+```
+Task Loaded:
+
+| Field | Value |
+|-------|-------|
+| Iteration | {current_iteration} / {max_iterations} |
+| Task ID | {current_task_id} |
+| Task | {current_task_description} |
+| Progress | {tasks_completed} / {tasks_total} |
+
+-> Executing...
+```
+
+---
+
+## NEXT STEP:
+
+After task loaded, proceed to `./step-02-execute.md`

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

@@ -0,0 +1,173 @@
+---
+name: step-02-execute
+description: Execute ONE task from the task list
+next_step: steps/step-03-commit.md
+---
+
+# Step 2: Execute Task
+
+## YOUR TASK:
+
+Execute exactly ONE task from prd.json. Do NOT batch multiple tasks.
+
+**ULTRA THINK about the implementation.**
+
+---
+
+## EXECUTION RULES:
+
+1. **ONE TASK ONLY** - Execute only `{current_task_description}`
+2. **ATOMIC CHANGES** - Changes should be complete and working
+3. **USE MCP** - Validate with SmartStack MCP as needed
+4. **DOCUMENT** - Track what you're doing
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Understand the Task
+
+**ULTRA THINK:**
+
+- What exactly needs to be done?
+- What files need to be created/modified?
+- What are the success criteria?
+- What patterns should be followed?
+
+### 2. Explore Context (if needed)
+
+**Use subagents sparingly:**
+
+```
+If exploration needed:
+  - Use explore-codebase agent for file discovery
+  - Use explore-docs agent for library docs
+  - Use Context7 MCP for documentation
+```
+
+**Prefer direct tool usage:**
+- Glob for file patterns
+- Grep for code search
+- Read for file contents
+
+### 3. Execute Implementation
+
+**Implement the task:**
+
+- Create/modify files as needed
+- Follow existing patterns in codebase
+- Use SmartStack conventions
+- Add appropriate logging
+- Handle errors properly
+
+**Use TodoWrite to track sub-steps:**
+
+```
+If task has multiple parts:
+  1. Create TodoWrite entries for each part
+  2. Mark in_progress as you work
+  3. Mark completed when done
+```
+
+### 4. Validate with MCP
+
+**After implementation, validate:**
+
+```
+mcp__smartstack__validate_conventions:
+  checks: ["all"]
+```
+
+**If validation fails:**
+- Fix the issues
+- Re-validate
+- Do NOT proceed until valid
+
+### 5. Run Quick Tests
+
+**If applicable:**
+
+```bash
+# For backend changes
+dotnet build src/SmartStack.Api/SmartStack.Api.csproj --no-restore
+
+# For frontend changes
+npm run lint && npm run typecheck
+
+# For specific tests
+dotnet test --filter "FullyQualifiedName~{relevant_test}"
+```
+
+**If tests fail:**
+- Fix the failing tests
+- Re-run until passing
+- Document what was fixed
+
+### 6. Track Progress
+
+**Update internal state:**
+
+```
+{files_created}  = ["path/to/file1.cs", "path/to/file2.ts"]
+{files_modified} = ["path/to/existing.cs"]
+{tests_run}      = true/false
+{validation}     = "passed" / "failed"
+```
+
+---
+
+## IMPORTANT CONSTRAINTS:
+
+### What TO DO:
+- Implement exactly what the task describes
+- Follow existing patterns
+- Validate changes
+- Write minimal, clean code
+
+### What NOT TO DO:
+- Don't implement other tasks
+- Don't refactor unrelated code
+- Don't add "nice to have" features
+- Don't skip validation
+
+---
+
+## OUTPUT FORMAT:
+
+```
+Task Executed:
+
+| Action | Details |
+|--------|---------|
+| Task | [{current_task_id}] {current_task_description} |
+| Files Created | {files_created} |
+| Files Modified | {files_modified} |
+| Validation | ✅ Passed |
+| Tests | ✅ Passed |
+
+-> Committing changes...
+```
+
+---
+
+## ERROR HANDLING:
+
+**If task cannot be completed:**
+
+1. Document the blocker
+2. Update progress.txt with learnings
+3. Mark task with a note (don't mark passes: true)
+4. Proceed to step-03 to save progress
+
+**If build fails:**
+
+1. Analyze error messages
+2. Fix the issues
+3. Re-build until success
+4. Then proceed
+
+---
+
+## NEXT STEP:
+
+After task executed and validated, proceed to `./step-03-commit.md`

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

@@ -0,0 +1,170 @@
+---
+name: step-03-commit
+description: Commit changes, update prd.json and progress.txt
+next_step: steps/step-04-check.md
+---
+
+# Step 3: Commit Changes
+
+## YOUR TASK:
+
+Commit the changes from the executed task, update prd.json and progress.txt.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Stage Changes
+
+**Add modified files:**
+
+```bash
+git add {files_created} {files_modified}
+```
+
+**Verify staged changes:**
+
+```bash
+git status
+```
+
+### 2. Create Commit
+
+**Commit with descriptive message:**
+
+```bash
+git commit -m "$(cat <<'EOF'
+feat(ralph): {current_task_description}
+
+Task {current_task_id}/{tasks_total} - Iteration {current_iteration}
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+EOF
+)"
+```
+
+**Commit message format:**
+- Type: `feat`, `fix`, `refactor`, `test`, `docs`
+- Scope: `ralph` or specific module
+- Description: Task description
+- Footer: Iteration info
+
+### 3. Update prd.json
+
+**Mark current task as complete:**
+
+```json
+{
+  "feature": "{task_description}",
+  "current_iteration": {current_iteration + 1},
+  "tasks": [
+    { "id": 1, "description": "...", "passes": true },   // was false
+    { "id": 2, "description": "...", "passes": false }   // next task
+  ]
+}
+```
+
+**Write updated prd.json:**
+
+```javascript
+const prd = readJSON('.ralph/prd.json');
+const task = prd.tasks.find(t => t.id === currentTaskId);
+task.passes = true;
+prd.current_iteration++;
+writeJSON('.ralph/prd.json', prd);
+```
+
+### 4. Update progress.txt
+
+**Append learnings to progress.txt:**
+
+```markdown
+---
+
+## Iteration {current_iteration}
+
+### Task Completed
+[{current_task_id}] {current_task_description}
+
+### Files Changed
+- Created: {files_created}
+- Modified: {files_modified}
+
+### Learnings
+{What was learned during this task}
+{Any issues encountered and how they were resolved}
+{Patterns discovered that might help future tasks}
+
+### Context for Next Task
+{What the next iteration should know}
+```
+
+### 5. Verify Commit
+
+**Check commit was created:**
+
+```bash
+git log -1 --oneline
+```
+
+**Expected output:**
+```
+abc1234 feat(ralph): {current_task_description}
+```
+
+### 6. Log Activity (if verbose)
+
+**If {verbose_mode} = true:**
+
+Append to `.ralph/logs/{date}.log`:
+```
+[{timestamp}] TASK COMPLETED
+  Task: [{current_task_id}] {current_task_description}
+  Commit: {commit_hash}
+  Files: {file_count} changed
+  Iteration: {current_iteration}
+```
+
+---
+
+## OUTPUT FORMAT:
+
+```
+Changes Committed:
+
+| Field | Value |
+|-------|-------|
+| Commit | {commit_hash} |
+| Task | [{current_task_id}] ✅ |
+| Iteration | {current_iteration} |
+| Files | {file_count} changed |
+
+prd.json: Updated task {current_task_id} to passes: true
+progress.txt: Added iteration {current_iteration} learnings
+
+-> Checking completion...
+```
+
+---
+
+## ERROR HANDLING:
+
+**If commit fails (pre-commit hook):**
+
+1. Read hook error message
+2. Fix the issue (lint, format, etc.)
+3. Stage fixes
+4. Create NEW commit (don't amend)
+5. Proceed to step-04
+
+**If prd.json write fails:**
+
+1. Log error
+2. Retry write
+3. If still fails, output error and stop
+
+---
+
+## NEXT STEP:
+
+After commit and updates complete, proceed to `./step-04-check.md`

package/templates/skills/ralph-loop/steps/step-04-check.md

@@ -0,0 +1,162 @@
+---
+name: step-04-check
+description: Check completion criteria and decide next action
+next_step: steps/step-05-report.md OR steps/step-01-task.md
+---
+
+# Step 4: Check Completion
+
+## YOUR TASK:
+
+Check if all tasks are complete and decide whether to output completion promise or continue to next task.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Read Current State
+
+**Load prd.json:**
+
+```javascript
+const prd = readJSON('.ralph/prd.json');
+const tasksCompleted = prd.tasks.filter(t => t.passes).length;
+const tasksTotal = prd.tasks.length;
+const allComplete = tasksCompleted === tasksTotal;
+```
+
+### 2. Check Iteration Limit
+
+**If {current_iteration} >= {max_iterations}:**
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  ⚠️ MAX ITERATIONS REACHED                                        ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Iterations: {current_iteration} / {max_iterations}               ║
+║  Tasks: {tasksCompleted} / {tasksTotal} complete                  ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Ralph loop stopped due to iteration limit.                       ║
+║  Remaining tasks:                                                  ║
+║  {list of tasks with passes: false}                               ║
+╚══════════════════════════════════════════════════════════════════╝
+
+-> Generating partial report...
+```
+
+**Proceed to step-05-report.md**
+
+### 3. Check All Tasks Complete
+
+**If allComplete = true:**
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  ✅ ALL TASKS COMPLETE                                            ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Iterations: {current_iteration}                                  ║
+║  Tasks: {tasksTotal} / {tasksTotal} complete                      ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Output completion promise:                                        ║
+║  <promise>{completion_promise}</promise>                          ║
+╚══════════════════════════════════════════════════════════════════╝
+
+<promise>{completion_promise}</promise>
+```
+
+**CRITICAL: Output the promise tag exactly as shown:**
+```
+<promise>{completion_promise}</promise>
+```
+
+**Proceed to step-05-report.md**
+
+### 4. More Tasks Remaining
+
+**If allComplete = false AND iteration < max_iterations:**
+
+```
+Progress: {tasksCompleted} / {tasksTotal} tasks
+
+Next task:
+[{next_task_id}] {next_task_description}
+
+Continuing to next iteration...
+```
+
+**Loop back to step-01-task.md**
+
+---
+
+## DECISION TREE:
+
+```
+                    ┌─────────────────────┐
+                    │  Check Completion   │
+                    └──────────┬──────────┘
+                               │
+              ┌────────────────┼────────────────┐
+              │                │                │
+              ▼                ▼                ▼
+      ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+      │ Max Iters    │ │ All Tasks    │ │ Tasks        │
+      │ Reached      │ │ Complete     │ │ Remaining    │
+      └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
+             │                │                │
+             ▼                ▼                ▼
+      ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+      │ Partial      │ │ Output       │ │ Loop to      │
+      │ Report       │ │ Promise      │ │ step-01      │
+      │ step-05      │ │ step-05      │ │              │
+      └──────────────┘ └──────────────┘ └──────────────┘
+```
+
+---
+
+## OUTPUT FORMAT:
+
+**If continuing:**
+```
+Completion Check:
+
+| Field | Value |
+|-------|-------|
+| Iteration | {current_iteration} / {max_iterations} |
+| Tasks | {tasksCompleted} / {tasksTotal} |
+| Status | Continuing |
+| Next | [{next_task_id}] {next_task_description} |
+
+-> Loading next task...
+```
+
+**If complete:**
+```
+Completion Check:
+
+| Field | Value |
+|-------|-------|
+| Iteration | {current_iteration} |
+| Tasks | {tasksTotal} / {tasksTotal} |
+| Status | COMPLETE |
+
+<promise>{completion_promise}</promise>
+
+-> Generating report...
+```
+
+---
+
+## CRITICAL RULE:
+
+**NEVER output the completion promise unless:**
+1. ALL tasks have `passes: true`
+2. The statement is genuinely true
+
+**False promises to escape the loop are FORBIDDEN.**
+
+---
+
+## NEXT STEP:
+
+- If complete or max iterations: `./step-05-report.md`
+- If tasks remaining: `./step-01-task.md`