@atlashub/smartstack-cli 1.2.0 → 1.4.0

package/templates/commands/business-analyse.md

@@ -1,11 +1,46 @@
 ---
 description: Business Analysis - Complete business analysis workflow (BABOK/IEEE 830)
+argument-hint: "<description du besoin>"
 ---
 
 # Business Analysis - Expert Workflow
 
 Senior Business Analyst expert. Complete business analysis without writing code.
 
+---
+
+## MODE AUTOMATIQUE (RECOMMANDE)
+
+```
++==============================================================================+
+|  /business-analyse "<description du besoin>"                                 |
+|                                                                              |
+|  ORCHESTRE AUTOMATIQUEMENT TOUT LE WORKFLOW:                                 |
+|  ├── 1. Verification MCP SmartStack (alerte si absent)                       |
+|  ├── 2. Analyse du contexte (Application/Module/Granularite)                 |
+|  ├── 3. Definition des integrations (Workflows/Notifs/IA)                    |
+|  ├── 4. Creation prd.json + progress.txt (Ralph Loop ready)                  |
+|  ├── 5. Execution phases 1-7 avec Ralph Loop                                 |
+|  ├── 6. Validation utilisateur (gate obligatoire)                            |
+|  ├── 7. Implementation avec Ralph Loop                                       |
+|  └── 8. Documentation HTML auto-generee                                      |
+|                                                                              |
+|  RESULTAT: Feature complete en ~30 minutes avec validation                   |
++==============================================================================+
+```
+
+**Usage:**
+```bash
+# Mode automatique complet (RECOMMANDE)
+/business-analyse "Je veux gerer les contacts clients avec import/export"
+
+# Mode manuel (phases individuelles)
+/business-analyse:1-init
+/business-analyse:2-discover ...
+```
+
+---
+
 ## Philosophy
 
 ```
@@ -91,7 +126,9 @@ Examples:
 
 | Phase | Command | Model | Description | Output |
 |-------|----------|-------|-------------|--------|
-| 0 | *Validation* | - | Context business check (automatic) | Block if not business |
+| **AUTO** | **`/business-analyse`** | **opus** | **Orchestration complete automatique** | **Feature complete** |
+| 0 | `/business-analyse:0-orchestrate` | opus | Orchestration manuelle avec questions | context.json, prd.json |
+| 0.5 | *Validation* | - | Context business check (automatic) | Block if not business |
 | 1 | `/business-analyse:1-init` | haiku | Initialize project structure + code scan | `config.json`, structure |
 | 2 | `/business-analyse:2-discover` | **opus** | Requirements elicitation (ultrathink) | `1-discovery.md` |
 | 3 | `/business-analyse:3-analyse` | sonnet | Business analysis BRD + doc scan (ultrathink) | `2-business-requirements.md` |
@@ -552,8 +589,52 @@ The skill is triggered automatically when user asks about:
 
 ## Next
 
-Execute the following command to begin:
-
+**Mode automatique (RECOMMANDE):**
+```bash
+/business-analyse "Description de votre besoin"
 ```
+
+**Mode manuel:**
+```bash
 /business-analyse:1-init
 ```
+
+---
+
+## EXECUTION AUTOMATIQUE
+
+Si cette commande est appelee avec un argument (description du besoin):
+
+```
+ARGUMENTS = "$ARGUMENTS"
+
+SI ARGUMENTS non vide:
+  → Executer /business-analyse:0-orchestrate $ARGUMENTS
+  → Le workflow complet est lance automatiquement
+
+SINON:
+  → Afficher ce fichier d'aide
+  → Proposer les options
+```
+
+**Lancer le mode automatique maintenant:**
+
+```javascript
+if (ARGUMENTS && ARGUMENTS.trim().length > 0) {
+  // Mode automatique - lancer l'orchestration
+  execute("/business-analyse:0-orchestrate " + ARGUMENTS);
+} else {
+  // Mode manuel - afficher l'aide et proposer les options
+  AskUserQuestion({
+    questions: [{
+      question: "Comment souhaitez-vous proceder?",
+      header: "Mode",
+      options: [
+        { label: "Mode automatique (Recommande)", description: "Orchestration complete avec Ralph Loop" },
+        { label: "Mode manuel", description: "Executer les phases une par une" }
+      ],
+      multiSelect: false
+    }]
+  });
+}
+```

package/templates/commands/ralph-loop/cancel-ralph.md

@@ -0,0 +1,18 @@
+---
+description: "Cancel active Ralph Loop"
+allowed-tools: ["Bash(test -f .claude/ralph-loop.local.md:*)", "Bash(rm .claude/ralph-loop.local.md)", "Read(.claude/ralph-loop.local.md)"]
+hide-from-slash-command-tool: "true"
+---
+
+# Cancel Ralph
+
+To cancel the Ralph loop:
+
+1. Check if `.claude/ralph-loop.local.md` exists using Bash: `test -f .claude/ralph-loop.local.md && echo "EXISTS" || echo "NOT_FOUND"`
+
+2. **If NOT_FOUND**: Say "No active Ralph loop found."
+
+3. **If EXISTS**:
+   - Read `.claude/ralph-loop.local.md` to get the current iteration number from the `iteration:` field
+   - Remove the file using Bash: `rm .claude/ralph-loop.local.md`
+   - Report: "Cancelled Ralph loop (was at iteration N)" where N is the iteration value

package/templates/commands/ralph-loop/help.md

@@ -0,0 +1,126 @@
+---
+description: "Explain Ralph Loop plugin and available commands"
+---
+
+# Ralph Loop Plugin Help
+
+Please explain the following to the user:
+
+## What is Ralph Loop?
+
+Ralph Loop implements the Ralph Wiggum technique - an iterative development methodology based on continuous AI loops, pioneered by Geoffrey Huntley.
+
+**Core concept:**
+```bash
+while :; do
+  cat PROMPT.md | claude-code --continue
+done
+```
+
+The same prompt is fed to Claude repeatedly. The "self-referential" aspect comes from Claude seeing its own previous work in the files and git history, not from feeding output back as input.
+
+**Each iteration:**
+1. Claude receives the SAME prompt
+2. Works on the task, modifying files
+3. Tries to exit
+4. Stop hook intercepts and feeds the same prompt again
+5. Claude sees its previous work in the files
+6. Iteratively improves until completion
+
+The technique is described as "deterministically bad in an undeterministic world" - failures are predictable, enabling systematic improvement through prompt tuning.
+
+## Available Commands
+
+### /ralph-loop <PROMPT> [OPTIONS]
+
+Start a Ralph loop in your current session.
+
+**Usage:**
+```
+/ralph-loop "Refactor the cache layer" --max-iterations 20
+/ralph-loop "Add tests" --completion-promise "TESTS COMPLETE"
+```
+
+**Options:**
+- `--max-iterations <n>` - Max iterations before auto-stop
+- `--completion-promise <text>` - Promise phrase to signal completion
+
+**How it works:**
+1. Creates `.claude/.ralph-loop.local.md` state file
+2. You work on the task
+3. When you try to exit, stop hook intercepts
+4. Same prompt fed back
+5. You see your previous work
+6. Continues until promise detected or max iterations
+
+---
+
+### /cancel-ralph
+
+Cancel an active Ralph loop (removes the loop state file).
+
+**Usage:**
+```
+/cancel-ralph
+```
+
+**How it works:**
+- Checks for active loop state file
+- Removes `.claude/.ralph-loop.local.md`
+- Reports cancellation with iteration count
+
+---
+
+## Key Concepts
+
+### Completion Promises
+
+To signal completion, Claude must output a `<promise>` tag:
+
+```
+<promise>TASK COMPLETE</promise>
+```
+
+The stop hook looks for this specific tag. Without it (or `--max-iterations`), Ralph runs infinitely.
+
+### Self-Reference Mechanism
+
+The "loop" doesn't mean Claude talks to itself. It means:
+- Same prompt repeated
+- Claude's work persists in files
+- Each iteration sees previous attempts
+- Builds incrementally toward goal
+
+## Example
+
+### Interactive Bug Fix
+
+```
+/ralph-loop "Fix the token refresh logic in auth.ts. Output <promise>FIXED</promise> when all tests pass." --completion-promise "FIXED" --max-iterations 10
+```
+
+You'll see Ralph:
+- Attempt fixes
+- Run tests
+- See failures
+- Iterate on solution
+- In your current session
+
+## When to Use Ralph
+
+**Good for:**
+- Well-defined tasks with clear success criteria
+- Tasks requiring iteration and refinement
+- Iterative development with self-correction
+- Greenfield projects
+
+**Not good for:**
+- Tasks requiring human judgment or design decisions
+- One-shot operations
+- Tasks with unclear success criteria
+- Debugging production issues (use targeted debugging instead)
+
+## Learn More
+
+- Original technique: https://ghuntley.com/ralph/
+- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator

package/templates/commands/ralph-loop/ralph-loop.md

@@ -0,0 +1,18 @@
+---
+description: "Start Ralph Loop in current session"
+argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
+allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
+hide-from-slash-command-tool: "true"
+---
+
+# Ralph Loop Command
+
+Execute the setup script to initialize the Ralph loop:
+
+```!
+"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
+```
+
+Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.
+
+CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.

package/templates/hooks/hooks.json

@@ -10,6 +10,16 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_HOOKS_DIR}/stop-hook.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/templates/hooks/stop-hook.sh

@@ -0,0 +1,177 @@
+#!/bin/bash
+
+# Ralph Loop Stop Hook
+# Prevents session exit when a ralph-loop is active
+# Feeds Claude's output back as input to continue the loop
+
+set -euo pipefail
+
+# Read hook input from stdin (advanced stop hook API)
+HOOK_INPUT=$(cat)
+
+# Check if ralph-loop is active
+RALPH_STATE_FILE=".claude/ralph-loop.local.md"
+
+if [[ ! -f "$RALPH_STATE_FILE" ]]; then
+  # No active loop - allow exit
+  exit 0
+fi
+
+# Parse markdown frontmatter (YAML between ---) and extract values
+FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$RALPH_STATE_FILE")
+ITERATION=$(echo "$FRONTMATTER" | grep '^iteration:' | sed 's/iteration: *//')
+MAX_ITERATIONS=$(echo "$FRONTMATTER" | grep '^max_iterations:' | sed 's/max_iterations: *//')
+# Extract completion_promise and strip surrounding quotes if present
+COMPLETION_PROMISE=$(echo "$FRONTMATTER" | grep '^completion_promise:' | sed 's/completion_promise: *//' | sed 's/^"\(.*\)"$/\1/')
+
+# Validate numeric fields before arithmetic operations
+if [[ ! "$ITERATION" =~ ^[0-9]+$ ]]; then
+  echo "⚠️  Ralph loop: State file corrupted" >&2
+  echo "   File: $RALPH_STATE_FILE" >&2
+  echo "   Problem: 'iteration' field is not a valid number (got: '$ITERATION')" >&2
+  echo "" >&2
+  echo "   This usually means the state file was manually edited or corrupted." >&2
+  echo "   Ralph loop is stopping. Run /ralph-loop again to start fresh." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+if [[ ! "$MAX_ITERATIONS" =~ ^[0-9]+$ ]]; then
+  echo "⚠️  Ralph loop: State file corrupted" >&2
+  echo "   File: $RALPH_STATE_FILE" >&2
+  echo "   Problem: 'max_iterations' field is not a valid number (got: '$MAX_ITERATIONS')" >&2
+  echo "" >&2
+  echo "   This usually means the state file was manually edited or corrupted." >&2
+  echo "   Ralph loop is stopping. Run /ralph-loop again to start fresh." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Check if max iterations reached
+if [[ $MAX_ITERATIONS -gt 0 ]] && [[ $ITERATION -ge $MAX_ITERATIONS ]]; then
+  echo "🛑 Ralph loop: Max iterations ($MAX_ITERATIONS) reached."
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Get transcript path from hook input
+TRANSCRIPT_PATH=$(echo "$HOOK_INPUT" | jq -r '.transcript_path')
+
+if [[ ! -f "$TRANSCRIPT_PATH" ]]; then
+  echo "⚠️  Ralph loop: Transcript file not found" >&2
+  echo "   Expected: $TRANSCRIPT_PATH" >&2
+  echo "   This is unusual and may indicate a Claude Code internal issue." >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Read last assistant message from transcript (JSONL format - one JSON per line)
+# First check if there are any assistant messages
+if ! grep -q '"role":"assistant"' "$TRANSCRIPT_PATH"; then
+  echo "⚠️  Ralph loop: No assistant messages found in transcript" >&2
+  echo "   Transcript: $TRANSCRIPT_PATH" >&2
+  echo "   This is unusual and may indicate a transcript format issue" >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Extract last assistant message with explicit error handling
+LAST_LINE=$(grep '"role":"assistant"' "$TRANSCRIPT_PATH" | tail -1)
+if [[ -z "$LAST_LINE" ]]; then
+  echo "⚠️  Ralph loop: Failed to extract last assistant message" >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Parse JSON with error handling
+LAST_OUTPUT=$(echo "$LAST_LINE" | jq -r '
+  .message.content |
+  map(select(.type == "text")) |
+  map(.text) |
+  join("\n")
+' 2>&1)
+
+# Check if jq succeeded
+if [[ $? -ne 0 ]]; then
+  echo "⚠️  Ralph loop: Failed to parse assistant message JSON" >&2
+  echo "   Error: $LAST_OUTPUT" >&2
+  echo "   This may indicate a transcript format issue" >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+if [[ -z "$LAST_OUTPUT" ]]; then
+  echo "⚠️  Ralph loop: Assistant message contained no text content" >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Check for completion promise (only if set)
+if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
+  # Extract text from <promise> tags using Perl for multiline support
+  # -0777 slurps entire input, s flag makes . match newlines
+  # .*? is non-greedy (takes FIRST tag), whitespace normalized
+  PROMISE_TEXT=$(echo "$LAST_OUTPUT" | perl -0777 -pe 's/.*?<promise>(.*?)<\/promise>.*/$1/s; s/^\s+|\s+$//g; s/\s+/ /g' 2>/dev/null || echo "")
+
+  # Use = for literal string comparison (not pattern matching)
+  # == in [[ ]] does glob pattern matching which breaks with *, ?, [ characters
+  if [[ -n "$PROMISE_TEXT" ]] && [[ "$PROMISE_TEXT" = "$COMPLETION_PROMISE" ]]; then
+    echo "✅ Ralph loop: Detected <promise>$COMPLETION_PROMISE</promise>"
+    rm "$RALPH_STATE_FILE"
+    exit 0
+  fi
+fi
+
+# Not complete - continue loop with SAME PROMPT
+NEXT_ITERATION=$((ITERATION + 1))
+
+# Extract prompt (everything after the closing ---)
+# Skip first --- line, skip until second --- line, then print everything after
+# Use i>=2 instead of i==2 to handle --- in prompt content
+PROMPT_TEXT=$(awk '/^---$/{i++; next} i>=2' "$RALPH_STATE_FILE")
+
+if [[ -z "$PROMPT_TEXT" ]]; then
+  echo "⚠️  Ralph loop: State file corrupted or incomplete" >&2
+  echo "   File: $RALPH_STATE_FILE" >&2
+  echo "   Problem: No prompt text found" >&2
+  echo "" >&2
+  echo "   This usually means:" >&2
+  echo "     • State file was manually edited" >&2
+  echo "     • File was corrupted during writing" >&2
+  echo "" >&2
+  echo "   Ralph loop is stopping. Run /ralph-loop again to start fresh." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Update iteration in frontmatter (portable across macOS and Linux)
+# Create temp file, then atomically replace
+TEMP_FILE="${RALPH_STATE_FILE}.tmp.$$"
+sed "s/^iteration: .*/iteration: $NEXT_ITERATION/" "$RALPH_STATE_FILE" > "$TEMP_FILE"
+mv "$TEMP_FILE" "$RALPH_STATE_FILE"
+
+# Build system message with iteration count and completion promise info
+if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
+  SYSTEM_MSG="🔄 Ralph iteration $NEXT_ITERATION | To stop: output <promise>$COMPLETION_PROMISE</promise> (ONLY when statement is TRUE - do not lie to exit!)"
+else
+  SYSTEM_MSG="🔄 Ralph iteration $NEXT_ITERATION | No completion promise set - loop runs infinitely"
+fi
+
+# Output JSON to block the stop and feed prompt back
+# The "reason" field contains the prompt that will be sent back to Claude
+jq -n \
+  --arg prompt "$PROMPT_TEXT" \
+  --arg msg "$SYSTEM_MSG" \
+  '{
+    "decision": "block",
+    "reason": $prompt,
+    "systemMessage": $msg
+  }'
+
+# Exit 0 for successful hook execution
+exit 0