feat: add --auto flag, redefine --quick as plan-only

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "ralph-specum",
       "description": "Spec-driven development with research, requirements, design, tasks, autonomous execution, and epic triage. Fresh context per task.",
-      "version": "4.9.1",
+      "version": "4.10.0",
       "author": {
         "name": "tzachbon"
       },
@@ -29,7 +29,7 @@
     {
       "name": "ralph-speckit",
       "description": "Spec-driven development using GitHub spec-kit methodology. Constitution-first approach with specify, plan, tasks, and implement phases.",
-      "version": "0.5.2",
+      "version": "0.5.3",
       "author": {
         "name": "tzachbon"
       },

plugins/ralph-speckit/.claude-plugin/plugin.json

@@ -1,10 +1,17 @@
 {
   "name": "ralph-speckit",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Spec-driven development using GitHub spec-kit methodology. Constitution-first approach with specify, plan, tasks, and implement phases.",
   "author": {
     "name": "tzachbon"
   },
   "license": "MIT",
-  "keywords": ["ralph", "speckit", "spec-driven", "constitution", "specify", "plan", "tasks", "implement"]
+  "keywords": ["ralph", "speckit", "spec-driven", "constitution", "specify", "plan", "tasks", "implement"],
+  "hooks": [
+    {
+      "event": "PreToolUse",
+      "matcher": "AskUserQuestion",
+      "command": "hooks/scripts/quick-mode-guard.sh"
+    }
+  ]
 }

plugins/ralph-speckit/commands/start.md

@@ -30,10 +30,22 @@ If CONSTITUTION_MISSING:
 From `$ARGUMENTS`, extract:
 - **feature-name**: Required, kebab-case name for the feature
 - **goal**: Optional description of what the feature should accomplish
+- **--quick**: Optional flag. Run all planning phases (research, requirements, design, tasks) but STOP before implementation. Presents the plan and awaits approval.
+- **--auto**: Optional flag. Full end-to-end autonomous execution. Skips interactive prompts and runs all phases including implementation without stopping.
 
 Examples:
 - `/speckit:start user-auth` - Create feature named user-auth
 - `/speckit:start user-auth Add OAuth2 support` - Create with goal
+- `/speckit:start user-auth Add OAuth2 support --quick` - Plan only, no implementation
+- `/speckit:start user-auth Add OAuth2 support --auto` - Full autonomous execution
+
+Mutual exclusivity check: if both `--quick` and `--auto` are present in `$ARGUMENTS`:
+1. Output: "Error: --quick and --auto are mutually exclusive. Use one or the other."
+2. STOP - do not create any feature directory or continue
+
+Parse flags (strip from goal text after extraction):
+- `quickMode`: set to `true` if `--quick` is present, `false` otherwise
+- `autoMode`: set to `true` if `--auto` is present, `false` otherwise
 
 If no feature-name provided:
 1. Output: "Usage: /speckit:start <feature-name> [goal]"
@@ -143,16 +155,48 @@ Write `.specify/specs/$FEATURE_ID-$feature-name/.speckit-state.json`:
   "maxTaskIterations": 5,
   "globalIteration": 1,
   "maxGlobalIterations": 100,
-  "awaitingApproval": false
+  "awaitingApproval": false,
+  "quickMode": false,
+  "autoMode": false
 }
 ```
 
+Set fields based on parsed flags:
+- If `quickMode` is `true`: set `"quickMode": true` in the state file
+- If `autoMode` is `true`: set `"autoMode": true` in the state file
+
 ## Update Current Feature Pointer
 
 ```bash
 echo "$FEATURE_ID-$feature-name" > .specify/.current-feature
 ```
 
+## Autonomous Mode Routing
+
+After state init and writing `.current-feature`, check flags:
+
+If neither `quickMode` nor `autoMode` is set: continue to normal interactive flow (output feature created message, suggest next step).
+
+If `quickMode=true` or `autoMode=true`:
+1. Verify `.specify/.current-feature` was written (guards depend on it).
+2. Skip all interactive prompts.
+3. Run all spec phases sequentially, delegating to each subagent with the directive: "Autonomous Mode: skip all questions, make reasonable decisions based on the goal and constitution."
+   - Phase 1: Research (delegate to research-analyst agent)
+   - Phase 2: Requirements (delegate to product-manager agent)
+   - Phase 3: Design (delegate to architect-reviewer agent)
+   - Phase 4: Tasks (delegate to task-planner agent)
+4. After tasks phase completes, compute totalTasks (count `- [ ]` checkboxes in tasks.md) and update state with shared execution bootstrap fields:
+   ```json
+   { "phase": "execution", "taskIndex": 0, "totalTasks": <count> }
+   ```
+   Then branch by mode:
+   - If `quickMode=true`:
+     - Also set `awaitingApproval: true` in state file
+     - Output: "Plan complete for '$FEATURE_ID-$feature-name'. Review the spec in .specify/specs/$FEATURE_ID-$feature-name/ and run /speckit:implement to start execution."
+     - STOP - do not proceed to implementation
+   - If `autoMode=true`:
+     - Transition directly to implementation (continue to execution loop)
+
 ## Initialize Progress File
 
 Create `.specify/specs/$FEATURE_ID-$feature-name/.progress.md`:

plugins/ralph-speckit/hooks/scripts/quick-mode-guard.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# PreToolUse hook: Block AskUserQuestion in autonomous modes (quickMode or autoMode)
+set -euo pipefail
+
+INPUT=$(cat)
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
+[ -z "$CWD" ] && exit 0
+
+# Find the current feature's state file
+CURRENT_FEATURE_FILE="$CWD/.specify/.current-feature"
+[ ! -f "$CURRENT_FEATURE_FILE" ] && exit 0
+
+FEATURE_NAME=$(cat "$CURRENT_FEATURE_FILE" 2>/dev/null | tr -d '[:space:]')
+[ -z "$FEATURE_NAME" ] && exit 0
+
+# Try .speckit-state.json first, then .ralph-state.json for compatibility
+STATE_FILE=""
+for candidate in "$CWD/.specify/specs/$FEATURE_NAME/.speckit-state.json" "$CWD/.specify/specs/"*"-$FEATURE_NAME/.speckit-state.json"; do
+    if [ -f "$candidate" ]; then
+        STATE_FILE="$candidate"
+        break
+    fi
+done
+[ -z "$STATE_FILE" ] && exit 0
+
+QUICK_MODE=$(jq -r '.quickMode // false' "$STATE_FILE" 2>/dev/null || echo "false")
+AUTO_MODE=$(jq -r '.autoMode // false' "$STATE_FILE" 2>/dev/null || echo "false")
+
+if [ "$QUICK_MODE" != "true" ] && [ "$AUTO_MODE" != "true" ]; then
+    exit 0
+fi
+
+# Autonomous mode is active — block AskUserQuestion
+jq -n '{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny"
+  },
+  "systemMessage": "Autonomous mode active: do NOT ask the user any questions. Make opinionated decisions autonomously. Choose the simplest, most conventional approach."
+}'

plugins/ralph-speckit/hooks/scripts/stop-watcher.sh

@@ -109,6 +109,8 @@ PHASE=$(jq -r '.phase // "unknown"' "$STATE_FILE" 2>/dev/null || echo "unknown")
 TASK_INDEX=$(jq -r '.taskIndex // 0' "$STATE_FILE" 2>/dev/null || echo "0")
 TOTAL_TASKS=$(jq -r '.totalTasks // 0' "$STATE_FILE" 2>/dev/null || echo "0")
 TASK_ITERATION=$(jq -r '.taskIteration // 1' "$STATE_FILE" 2>/dev/null || echo "1")
+QUICK_MODE=$(jq -r '.quickMode // false' "$STATE_FILE" 2>/dev/null || echo "false")
+AUTO_MODE=$(jq -r '.autoMode // false' "$STATE_FILE" 2>/dev/null || echo "false")
 
 # Check global iteration limit
 GLOBAL_ITERATION=$(jq -r '.globalIteration // 1' "$STATE_FILE" 2>/dev/null || echo "1")
@@ -120,13 +122,29 @@ if [ "$GLOBAL_ITERATION" -ge "$MAX_GLOBAL" ]; then
     exit 0
 fi
 
+# Autonomous mode planning guard: block stops during non-execution phases
+if { [ "$QUICK_MODE" = "true" ] || [ "$AUTO_MODE" = "true" ]; } && [ "$PHASE" != "execution" ]; then
+    STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null || echo "false")
+    if [ "$STOP_HOOK_ACTIVE" = "true" ]; then exit 0; fi
+    REASON="Autonomous mode active — continue spec phase: $PHASE for $FEATURE_NAME."
+    MSG="Ralph-speckit autonomous mode: continue $PHASE phase"
+    jq -n --arg reason "$REASON" --arg msg "$MSG" '{"decision": "block", "reason": $reason, "systemMessage": $msg}'
+    exit 0
+fi
+
 # Log current state
 if [ "$PHASE" = "execution" ]; then
     echo "[ralph-speckit] Session stopped during feature: $FEATURE_NAME | Task: $((TASK_INDEX + 1))/$TOTAL_TASKS | Attempt: $TASK_ITERATION" >&2
 fi
 
 # Loop control: output continuation prompt if more tasks remain
 if [ "$PHASE" = "execution" ] && [ "$TASK_INDEX" -lt "$TOTAL_TASKS" ]; then
+    AWAITING=$(jq -r '.awaitingApproval // false' "$STATE_FILE" 2>/dev/null || echo "false")
+    if [ "$AWAITING" = "true" ]; then
+        echo "[ralph-speckit] awaitingApproval=true, allowing stop for user gate" >&2
+        exit 0
+    fi
+
     # Read recovery mode for prompt customization
     RECOVERY_MODE=$(jq -r '.recoveryMode // false' "$STATE_FILE" 2>/dev/null || echo "false")
     MAX_TASK_ITER=$(jq -r '.maxTaskIterations // 5' "$STATE_FILE" 2>/dev/null || echo "5")

plugins/ralph-specum-codex/skills/ralph-specum-start/SKILL.md

@@ -20,7 +20,7 @@ Use this for the `start` and `new` entrypoints.
 
 ## Action
 
-1. Parse explicit name, goal, `--quick`, commit flags, optional specs root, and optional `--tasks-size fine|coarse`.
+1. Parse explicit name, goal, `--quick`, `--auto`, commit flags, optional specs root, and optional `--tasks-size fine|coarse`. If both `--quick` and `--auto` are present: Respond "Error: --quick and --auto are mutually exclusive. Use one or the other." STOP.
 2. Resolve the target by explicit path, exact name, or `.current-spec`.
 3. If the same name exists in multiple configured roots, stop and require a full path.
 4. Check active epic context from `specs/.current-epic` when no explicit spec was chosen.
@@ -40,15 +40,18 @@ Use this for the `start` and `new` entrypoints.
    - `commitSpec: settings auto_commit_spec or true`
    - `relatedSpecs: []`
    - `awaitingApproval: true` when the run will stop after setup and wait for explicit direction
-   - `awaitingApproval: false` when quick mode or explicit autonomy will continue without pausing
-   - preserve or set `quickMode`
+   - `awaitingApproval: false` when `--auto` will continue without pausing
+   - `quickMode: true, autoMode: false` when `--quick` was supplied
+   - `quickMode: false, autoMode: true` when `--auto` was supplied
+   - preserve or set `quickMode` and `autoMode`
    - preserve or set `granularity` when `--tasks-size` was supplied
    - preserve or set `epicName` when starting from an epic suggestion
 8. Update `.current-spec`.
 9. Write `.progress.md` with goal, current phase, next step, blockers, learnings, and skill discovery results when used.
 10. On resume, prefer `tasks.md` and present files over stale state when they disagree.
-11. In quick mode, generate missing artifacts in order, skip normal approval pauses, and continue into implementation in the same run.
-12. **Without quick mode or explicit autonomy: STOP HERE after setup. Do NOT proceed to research. Wait for the user to explicitly ask to continue.** This is non-negotiable.
+11. With `--quick`: generate all artifacts (research, requirements, design, tasks) autonomously in order, skip normal approval pauses, then set `awaitingApproval: true`. Output a summary listing each generated artifact with a one-sentence description, then end with exactly one explicit choice prompt: "Approve plan and run implement" or "Request changes". STOP.
+12. With `--auto`: generate all artifacts autonomously in order, skip normal approval pauses, and continue directly into implementation without stopping.
+13. **Without `--quick` or `--auto`: STOP HERE after setup. Do NOT proceed to research. Wait for the user to explicitly ask to continue.** This is non-negotiable.
 
 ## Branch Isolation
 
@@ -61,4 +64,4 @@ Use this for the `start` and `new` entrypoints.
 - End with exactly one explicit choice prompt:
   - `request changes`
   - `continue to research`
-- Do not run research until the user explicitly asks to continue or explicitly asked for quick or autonomous flow.
+- Do not run research until the user explicitly asks to continue or explicitly asked for `--quick` or `--auto` flow.

plugins/ralph-specum-codex/skills/ralph-specum/SKILL.md

@@ -56,13 +56,13 @@ If the corresponding helper skill is installed and the user invoked it explicitl
 4. Keep `.current-spec` in the default specs root.
 5. Merge state fields. Do not replace the whole state object.
 6. Preserve `source`, `name`, `basePath`, `phase`, `taskIndex`, `totalTasks`, `taskIteration`, `maxTaskIterations`, `globalIteration`, `maxGlobalIterations`, `commitSpec`, and `relatedSpecs`.
-7. Also preserve newer state fields when present, especially `awaitingApproval`, `quickMode`, `granularity`, `epicName`, `discoveredSkills`, and native task sync metadata.
+7. Also preserve newer state fields when present, especially `awaitingApproval`, `quickMode`, `autoMode`, `granularity`, `epicName`, `discoveredSkills`, and native task sync metadata.
 8. Write `.progress.md` after every phase and after every implementation attempt.
 9. Honor approval checkpoints between phases unless quick mode is active.
 10. Honor the `Commit` line in tasks during implementation unless the user explicitly disables task commits.
 11. Use branch creation or worktree creation when the user asks for branch isolation or the repo policy requires it.
-12. Enter quick mode only when the user explicitly asks Ralph to be autonomous, do it quickly, or continue without pauses.
-13. In quick mode, generate missing artifacts, default task granularity to `fine` when unset, and continue into implementation in the same session.
+12. `--quick` and `--auto` are mutually exclusive. `--quick` means plan-only: generate all artifacts autonomously, then stop with `awaitingApproval: true` before implementation. `--auto` means full autonomous: generate all artifacts and continue directly into implementation without stopping.
+13. In `--auto` mode, generate missing artifacts, default task granularity to `fine` when unset, and continue into implementation in the same session. In `--quick` mode, do the same but stop before implementation.
 
 ## Stop Enforcement
 

plugins/ralph-specum/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-specum",
-  "version": "4.9.1",
+  "version": "4.10.0",
   "description": "Spec-driven development with task-by-task execution. Research, requirements, design, tasks, autonomous implementation, and epic triage for multi-spec feature decomposition.",
   "author": {
     "name": "tzachbon"

plugins/ralph-specum/commands/start.md

@@ -1,6 +1,6 @@
 ---
 description: Smart entry point that detects if you need a new spec or should resume existing
-argument-hint: [name] [goal] [--fresh] [--quick] [--commit-spec] [--no-commit-spec] [--specs-dir <path>] [--tasks-size fine|coarse]
+argument-hint: [name] [goal] [--fresh] [--quick] [--auto] [--commit-spec] [--no-commit-spec] [--specs-dir <path>] [--tasks-size fine|coarse]
 allowed-tools: "*"
 ---
 
@@ -37,8 +37,12 @@ Read `${CLAUDE_PLUGIN_ROOT}/references/intent-classification.md` and follow the
 
 ### Quick Mode Check
 
+If both `--quick` and `--auto` flags are detected in $ARGUMENTS, output: "Error: --quick and --auto are mutually exclusive. Use one or the other." and STOP immediately before creating any files.
+
 If `--quick` flag detected in $ARGUMENTS, skip to **Step 5: Quick Mode Flow**.
 
+If `--auto` flag detected in $ARGUMENTS, skip to **Step 5: Quick Mode Flow**.
+
 ## Step 3: Scan Existing Specs
 
 Read `${CLAUDE_PLUGIN_ROOT}/references/spec-scanner.md` and follow the scanning algorithm and index hint logic.
@@ -135,7 +139,7 @@ Continuing...
      "phase": "research", "taskIndex": 0, "totalTasks": 0,
      "taskIteration": 1, "maxTaskIterations": 5,
      "globalIteration": 1, "maxGlobalIterations": 100,
-     "commitSpec": true, "quickMode": false,
+     "commitSpec": true, "quickMode": false, "autoMode": false,
      "discoveredSkills": []
    }
    ```
@@ -254,7 +258,7 @@ End response immediately.
 
 Read `${CLAUDE_PLUGIN_ROOT}/references/quick-mode.md` and follow the full quick mode execution sequence.
 
-**Summary**: Validates input, infers name, creates spec directory, initializes state with quickMode=true, then runs all phases sequentially (research, requirements, design, tasks) delegating to subagents with Quick Mode Directive. Each artifact gets a review loop (max 3 iterations). After all artifacts generated, transitions to execution and invokes spec-executor for task 1.
+**Summary**: Validates input, infers name, creates spec directory, initializes state with quickMode=true or autoMode=true, then runs all phases sequentially (research, requirements, design, tasks) delegating to subagents with Autonomous Mode Directive. Each artifact gets a review loop (max 3 iterations). After all artifacts generated: `--quick` sets awaitingApproval=true and stops before implementation; `--auto` transitions to execution and invokes spec-executor for task 1.
 
 **IMPORTANT**: Each phase MUST be tracked as a native Claude task via `TaskCreate` / `TaskUpdate`. Create a task at phase start (with `activeForm` for spinner text), mark it completed when the phase finishes. This provides visible progress in the UI. See quick-mode.md steps 11-15 for the exact pattern.
 
@@ -304,7 +308,7 @@ After ANY subagent returns in normal mode (no `--quick` flag):
 
 **The user must explicitly run the next command.** This gives them time to review artifacts.
 
-Exception: `--quick` mode runs all phases without stopping.
+Exception: `--quick` or `--auto` mode runs all phases without stopping.
 </mandatory>
 
 ## Quick Mode Execution (Stop-Hook)

plugins/ralph-specum/hooks/scripts/quick-mode-guard.sh

@@ -32,16 +32,17 @@ if [ ! -f "$STATE_FILE" ]; then
     exit 0
 fi
 
-# Check quickMode flag
+# Check quickMode and autoMode flags
 QUICK_MODE=$(jq -r '.quickMode // false' "$STATE_FILE" 2>/dev/null || echo "false")
-if [ "$QUICK_MODE" != "true" ]; then
+AUTO_MODE=$(jq -r '.autoMode // false' "$STATE_FILE" 2>/dev/null || echo "false")
+if [ "$QUICK_MODE" != "true" ] && [ "$AUTO_MODE" != "true" ]; then
     exit 0
 fi
 
-# Quick mode is active — block AskUserQuestion
+# Autonomous mode is active — block AskUserQuestion
 jq -n '{
   "hookSpecificOutput": {
     "permissionDecision": "deny"
   },
-  "systemMessage": "Quick mode active: do NOT ask the user any questions. Make opinionated decisions autonomously. Choose the simplest, most conventional approach."
+  "systemMessage": "Autonomous mode active: do NOT ask the user any questions. Make opinionated decisions autonomously. Choose the simplest, most conventional approach."
 }'

plugins/ralph-specum/hooks/scripts/stop-watcher.sh

@@ -144,8 +144,14 @@ TASK_INDEX=$(jq -r '.taskIndex // 0' "$STATE_FILE" 2>/dev/null || echo "0")
 TOTAL_TASKS=$(jq -r '.totalTasks // 0' "$STATE_FILE" 2>/dev/null || echo "0")
 TASK_ITERATION=$(jq -r '.taskIteration // 1' "$STATE_FILE" 2>/dev/null || echo "1")
 QUICK_MODE=$(jq -r '.quickMode // false' "$STATE_FILE" 2>/dev/null || echo "false")
+AUTO_MODE=$(jq -r '.autoMode // false' "$STATE_FILE" 2>/dev/null || echo "false")
 NATIVE_SYNC=$(jq -r '.nativeSyncEnabled // true' "$STATE_FILE" 2>/dev/null || echo "true")
 
+AUTONOMOUS_MODE="false"
+if [ "$QUICK_MODE" = "true" ] || [ "$AUTO_MODE" = "true" ]; then
+    AUTONOMOUS_MODE="true"
+fi
+
 # Check global iteration limit
 GLOBAL_ITERATION=$(jq -r '.globalIteration // 1' "$STATE_FILE" 2>/dev/null || echo "1")
 MAX_GLOBAL=$(jq -r '.maxGlobalIterations // 100' "$STATE_FILE" 2>/dev/null || echo "100")
@@ -156,25 +162,25 @@ if [ "$GLOBAL_ITERATION" -ge "$MAX_GLOBAL" ]; then
     exit 0
 fi
 
-# Quick mode guard: block stop during ANY phase when quickMode is active
-if [ "$QUICK_MODE" = "true" ] && [ "$PHASE" != "execution" ]; then
+# Autonomous mode guard: block stop during ANY phase when quickMode or autoMode is active
+if [ "$AUTONOMOUS_MODE" = "true" ] && [ "$PHASE" != "execution" ]; then
     STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null || echo "false")
     if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
-        echo "[ralph-specum] stop_hook_active=true in quick mode, allowing stop to prevent loop" >&2
+        echo "[ralph-specum] stop_hook_active=true in autonomous mode, allowing stop to prevent loop" >&2
         exit 0
     fi
 
     REASON=$(cat <<EOF
-Quick mode active — do NOT stop. Continue spec phase: $PHASE for $SPEC_NAME.
+Autonomous mode active — do NOT stop. Continue spec phase: $PHASE for $SPEC_NAME.
 
-You are running in quick mode. Do NOT stop, do NOT ask the user questions.
+You are running in autonomous mode. Do NOT stop, do NOT ask the user questions.
 Continue generating artifacts for the current phase ($PHASE) and proceed to the next phase.
 Make strong, opinionated decisions autonomously.
 EOF
 )
     jq -n \
       --arg reason "$REASON" \
-      --arg msg "Ralph-specum quick mode: continue $PHASE phase" \
+      --arg msg "Ralph-specum autonomous mode: continue $PHASE phase" \
       '{
         "decision": "block",
         "reason": $reason,