@atlashub/smartstack-cli 1.13.2 → 1.14.1

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

@@ -0,0 +1,201 @@
+---
+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 EXECUTION 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
+
+## YOUR TASK:
+
+Initialize the Ralph loop by parsing flags, verifying MCP availability, and setting up the execution environment.
+
+---
+
+<defaults>
+## Default Configuration
+
+```yaml
+max_iterations: 50
+completion_promise: null
+verbose_mode: false
+resume_mode: false
+current_iteration: 1
+```
+</defaults>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 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}
+```
+
+### 2. Verify MCP Servers (MANDATORY)
+
+**CRITICAL: Do NOT proceed without MCP verification!**
+
+**Check SmartStack MCP:**
+```
+mcp__smartstack__validate_conventions:
+  checks: ["all"]
+  (just to verify connectivity)
+```
+
+**Check Context7 MCP:**
+```
+mcp__plugin_context7_context7__resolve-library-id:
+  libraryName: "test"
+  query: "connectivity check"
+  (just to verify connectivity)
+```
+
+**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 {resume_mode} = true:**
+
+1. Check for existing `.ralph/prd.json`
+2. If found:
+   - Read prd.json to restore state
+   - Read progress.txt for context
+   - Set {current_iteration} from state
+   - Continue to step-01
+3. If not found:
+   - Error: "No active Ralph loop to resume"
+   - Ask user to start new loop
+
+### 4. Initialize .ralph/ Structure
+
+**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
+```
+
+### 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"
+```
+
+### 6. 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 ✅, Context7 ✅
+```
+
+### 7. Show Summary and Proceed
+
+**Always show COMPACT summary:**
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  RALPH LOOP INITIALIZED                                           ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Task: {task_description}                                         ║
+║  Max iterations: {max_iterations}                                 ║
+║  Completion: <promise>{completion_promise}</promise>              ║
+║  MCP: ✅ Ready                                                    ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Files:                                                           ║
+║  - .ralph/prd.json (tasks)                                        ║
+║  - .ralph/progress.txt (memory)                                   ║
+╚══════════════════════════════════════════════════════════════════╝
+
+-> 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
+- Output is COMPACT
+- Proceeded to step-01 immediately after summary
+
+## NEXT STEP:
+
+After showing initialization summary, always proceed directly to `./step-01-task.md`

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`