wiggum-cli 0.16.0 → 0.17.0

package/dist/generator/config.d.ts

@@ -3,47 +3,7 @@
  * Generates ralph.config.cjs file from scan results
  */
 import type { ScanResult } from '../scanner/types.js';
-/**
- * Ralph configuration structure
- */
-export interface RalphConfig {
-    name: string;
-    stack: {
-        framework: {
-            name: string;
-            version: string;
-            variant: string;
-        };
-        packageManager: string;
-        testing: {
-            unit: string;
-            e2e: string;
-        };
-        styling: string;
-    };
-    commands: {
-        dev: string;
-        build: string;
-        test: string;
-        lint: string;
-        typecheck: string;
-    };
-    paths: {
-        root: string;
-        prompts: string;
-        guides: string;
-        specs: string;
-        scripts: string;
-        learnings: string;
-        agents: string;
-    };
-    loop: {
-        maxIterations: number;
-        maxE2eAttempts: number;
-        defaultModel: string;
-        planningModel: string;
-    };
-}
+import type { RalphConfig } from '../utils/config.js';
 /**
  * Generate ralph config object from scan result
  */

package/dist/generator/config.js

@@ -10,6 +10,8 @@ export function generateConfig(scanResult, customVars = {}) {
     const vars = extractVariables(scanResult, customVars);
     const defaultModel = customVars.defaultModel || 'sonnet';
     const planningModel = customVars.planningModel || 'opus';
+    const agentProvider = customVars.agentProvider || 'anthropic';
+    const agentModel = customVars.agentModel || 'claude-sonnet-4-6';
     return {
         name: vars.projectName,
         stack: {
@@ -46,6 +48,11 @@ export function generateConfig(scanResult, customVars = {}) {
             maxE2eAttempts: 5,
             defaultModel,
             planningModel,
+            reviewMode: 'manual',
+        },
+        agent: {
+            defaultProvider: agentProvider,
+            defaultModel: agentModel,
         },
     };
 }

package/dist/generator/index.d.ts

@@ -4,10 +4,10 @@
  */
 import type { ScanResult } from '../scanner/types.js';
 import { type TemplateVariables } from './templates.js';
-import { type RalphConfig } from './config.js';
+import type { RalphConfig } from '../utils/config.js';
 import { type WriteSummary } from './writer.js';
 export type { TemplateVariables } from './templates.js';
-export type { RalphConfig } from './config.js';
+export type { RalphConfig } from '../utils/config.js';
 export type { WriteOptions, WriteSummary, WriteResult } from './writer.js';
 export { extractVariables, processTemplate, processTemplateFile, getTemplatesDir, } from './templates.js';
 export { generateConfig, generateConfigFile } from './config.js';

package/dist/generator/templates.d.ts

@@ -29,6 +29,8 @@ export interface TemplateVariables {
     formatCommand: string;
     appDir: string;
     isTui: string;
+    hasSupabase: string;
+    hasPosthog: string;
     aiEntryPoints: string;
     aiKeyDirectories: string;
     aiNamingConventions: string;

package/dist/generator/templates.js

@@ -150,8 +150,10 @@ export function extractVariables(scanResult, customVars = {}) {
         existsSync(join(projectRoot, 'src', 'main.ts'))) {
         appDir = 'src';
     }
-    // Detect TUI (Ink) projects
+    // Detect TUI (Ink) projects and service dependencies
     let isTui = '';
+    let hasSupabase = '';
+    let hasPosthog = '';
     try {
         const pkgPath = join(projectRoot, 'package.json');
         if (existsSync(pkgPath)) {
@@ -159,6 +161,10 @@ export function extractVariables(scanResult, customVars = {}) {
             const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
             if (allDeps['ink'])
                 isTui = 'true';
+            if (allDeps['@supabase/supabase-js'] || allDeps['@supabase/ssr'])
+                hasSupabase = 'true';
+            if (allDeps['posthog-js'] || allDeps['posthog-node'])
+                hasPosthog = 'true';
         }
     }
     catch { /* ignore */ }
@@ -179,6 +185,8 @@ export function extractVariables(scanResult, customVars = {}) {
         stylingVariant,
         appDir,
         isTui,
+        hasSupabase,
+        hasPosthog,
         ...commands,
         ...aiData,
         ...customVars,

package/dist/index.d.ts

@@ -4,7 +4,7 @@
 export interface ParsedArgs {
     command: string | undefined;
     positionalArgs: string[];
-    flags: Record<string, string | boolean>;
+    flags: Record<string, string | boolean | string[]>;
 }
 /**
  * Parse CLI arguments into command, positional args, and flags.

package/dist/index.js

@@ -43,7 +43,15 @@ export function parseCliArgs(argv) {
         '--interval',
         '--provider',
         '--review-mode',
+        '--issue',
+        '--context',
+        '--goals',
+        '--max-items',
+        '--max-steps',
+        '--labels',
     ]);
+    // Flags that can be specified multiple times, accumulating into an array
+    const repeatableFlagSet = new Set(['--issue', '--context']);
     let i = 0;
     while (i < argv.length) {
         const arg = argv[i];
@@ -63,7 +71,22 @@ export function parseCliArgs(argv) {
         if (arg.startsWith('--')) {
             const normalized = normalizeFlagName(arg);
             if (valueFlagSet.has(arg) && i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
-                flags[normalized] = argv[i + 1];
+                const value = argv[i + 1];
+                if (repeatableFlagSet.has(arg)) {
+                    const existing = flags[normalized];
+                    if (Array.isArray(existing)) {
+                        existing.push(value);
+                    }
+                    else if (typeof existing === 'string') {
+                        flags[normalized] = [existing, value];
+                    }
+                    else {
+                        flags[normalized] = [value];
+                    }
+                }
+                else {
+                    flags[normalized] = value;
+                }
                 i += 2;
             }
             else {
@@ -155,6 +178,7 @@ async function startInkTui(initialScreen = 'shell', options) {
             provider: initialState.provider,
             model: initialState.model,
             scanResult: initialState.scanResult,
+            initialReferences: options?.initialReferences,
         }
         : undefined;
     // Build run props if starting on run/monitor screen
@@ -167,6 +191,7 @@ async function startInkTui(initialScreen = 'shell', options) {
         version,
         interviewProps,
         runProps,
+        agentProps: options?.agentOptions,
         onComplete: (specPath) => {
             // Spec was saved to disk by app.tsx (avoid stdout noise during TUI)
             logger.debug(`Created spec: ${specPath}`);
@@ -199,7 +224,9 @@ Usage:
   wiggum new <name>         Create new feature spec (TUI)
   wiggum run <feature>      Run feature development loop
   wiggum monitor <feature>  Monitor a running feature loop
+  wiggum sync               Refresh project context (scan + AI analysis)
   wiggum config [args...]   Manage API keys and settings
+  wiggum agent              Autonomous backlog executor
 
 Options for run:
   --worktree                Use git worktree isolation
@@ -222,9 +249,22 @@ Options for init:
 Options for new:
   --provider <name>         AI provider
   --model <model>           AI model
+  --issue <number|url>      Add GitHub issue as context (repeatable)
+  --context <url|path>      Add URL or file as context (repeatable)
+  --auto                    Headless mode (skip TUI, for scripting/agents)
+  --goals <description>     Feature goals (used with --auto)
   -e, --edit                Open in editor after creation
   -f, --force               Overwrite existing spec
 
+Options for agent:
+  --model <model>           AI model (overrides ralph.config.cjs agent.defaultModel)
+  --max-items <n>           Max issues to process before stopping
+  --max-steps <n>           Max agent steps before stopping
+  --labels <l1,l2>          Only work on issues with these labels (comma-separated)
+  --review-mode <mode>      Review mode: 'manual', 'auto', or 'merge' (default: manual)
+  --dry-run                 Plan what would be done without executing
+  --stream                  Stream output in real-time (default: wait for completion)
+
 In the TUI:
   /init                     Initialize or reconfigure project
   /new <name>               Create a new feature specification
@@ -259,11 +299,37 @@ Press Esc to cancel any operation.
             const featureName = parsed.positionalArgs[0];
             if (!featureName) {
                 console.error('Error: <name> is required for "new"');
-                console.error('Usage: wiggum new <name> [--provider <name>] [--model <model>] [-e] [-f]');
+                console.error('Usage: wiggum new <name> [--issue <number|url>] [--context <url|path>] [--model <model>] [--auto] [--goals <desc>] [-e] [-f]');
                 process.exit(1);
             }
-            // TODO: pass parsed flags to startInkTui once TUI supports new flags
-            await startInkTui('interview', { interviewFeature: featureName });
+            const initialReferences = [];
+            const issueFlags = parsed.flags.issue;
+            if (Array.isArray(issueFlags))
+                initialReferences.push(...issueFlags.map(v => `issue:${v}`));
+            else if (typeof issueFlags === 'string')
+                initialReferences.push(`issue:${issueFlags}`);
+            const contextFlags = parsed.flags.context;
+            if (Array.isArray(contextFlags))
+                initialReferences.push(...contextFlags);
+            else if (typeof contextFlags === 'string')
+                initialReferences.push(contextFlags);
+            if (parsed.flags.auto === true) {
+                const { newAutoCommand } = await import('./commands/new-auto.js');
+                const providerFlag = typeof parsed.flags.provider === 'string' ? parsed.flags.provider : undefined;
+                const validProviders = new Set(['anthropic', 'openai', 'openrouter']);
+                await newAutoCommand(featureName, {
+                    goals: typeof parsed.flags.goals === 'string' ? parsed.flags.goals : undefined,
+                    initialReferences: initialReferences.length > 0 ? initialReferences : undefined,
+                    model: typeof parsed.flags.model === 'string' ? parsed.flags.model : undefined,
+                    provider: providerFlag && validProviders.has(providerFlag) ? providerFlag : undefined,
+                });
+            }
+            else {
+                await startInkTui('interview', {
+                    interviewFeature: featureName,
+                    initialReferences: initialReferences.length > 0 ? initialReferences : undefined,
+                });
+            }
             break;
         }
         case 'run': {
@@ -319,6 +385,11 @@ Press Esc to cancel any operation.
             }
             break;
         }
+        case 'sync': {
+            const { syncCommand } = await import('./commands/sync.js');
+            await syncCommand();
+            break;
+        }
         case 'config': {
             const provider = getAvailableProvider();
             const model = provider
@@ -328,6 +399,46 @@ Press Esc to cancel any operation.
             await handleConfigCommand(parsed.positionalArgs, state);
             break;
         }
+        case 'agent': {
+            const reviewModeFlag = typeof parsed.flags.reviewMode === 'string' ? parsed.flags.reviewMode : undefined;
+            if (reviewModeFlag && !['manual', 'auto', 'merge'].includes(reviewModeFlag)) {
+                console.error(`Error: Invalid --review-mode '${reviewModeFlag}'. Allowed values: manual, auto, merge`);
+                process.exit(1);
+            }
+            const agentOpts = {
+                model: typeof parsed.flags.model === 'string' ? parsed.flags.model : undefined,
+                maxItems: typeof parsed.flags.maxItems === 'string' ? parseIntFlag(parsed.flags.maxItems, '--max-items') : undefined,
+                maxSteps: typeof parsed.flags.maxSteps === 'string' ? parseIntFlag(parsed.flags.maxSteps, '--max-steps') : undefined,
+                labels: typeof parsed.flags.labels === 'string' ? parsed.flags.labels.split(',').map(l => l.trim()).filter(Boolean) : undefined,
+                reviewMode: reviewModeFlag,
+                dryRun: parsed.flags.dryRun === true,
+                stream: parsed.flags.stream === true,
+            };
+            if (agentOpts.stream === true) {
+                // Explicit --stream: always headless
+                const { agentCommand } = await import('./commands/agent.js');
+                await agentCommand(agentOpts);
+            }
+            else if (process.stdout.isTTY && !isCI()) {
+                // TTY: launch TUI
+                await startInkTui('agent', {
+                    agentOptions: {
+                        modelOverride: agentOpts.model,
+                        maxItems: agentOpts.maxItems,
+                        maxSteps: agentOpts.maxSteps,
+                        labels: agentOpts.labels,
+                        reviewMode: agentOpts.reviewMode,
+                        dryRun: agentOpts.dryRun,
+                    },
+                });
+            }
+            else {
+                // Non-TTY / CI: headless
+                const { agentCommand } = await import('./commands/agent.js');
+                await agentCommand(agentOpts);
+            }
+            break;
+        }
         default:
             // Unknown command - start TUI at shell
             logger.warn(`Unknown command: ${parsed.command}. Starting TUI...`);

package/dist/repl/command-parser.d.ts

@@ -54,6 +54,11 @@ export declare const REPL_COMMANDS: {
         readonly usage: "/monitor <feature-name>";
         readonly aliases: readonly ["m"];
     };
+    readonly agent: {
+        readonly description: "Start the autonomous backlog agent";
+        readonly usage: "/agent [--dry-run] [--max-items <n>]";
+        readonly aliases: readonly ["a"];
+    };
     readonly config: {
         readonly description: "Manage API keys and settings";
         readonly usage: "/config [set <service> <key>]";

package/dist/repl/command-parser.js

@@ -31,6 +31,11 @@ export const REPL_COMMANDS = {
         usage: '/monitor <feature-name>',
         aliases: ['m'],
     },
+    agent: {
+        description: 'Start the autonomous backlog agent',
+        usage: '/agent [--dry-run] [--max-items <n>]',
+        aliases: ['a'],
+    },
     config: {
         description: 'Manage API keys and settings',
         usage: '/config [set <service> <key>]',

package/dist/templates/prompts/PROMPT.md.tmpl

@@ -1,5 +1,5 @@
 ## Context
-Study @.ralph/AGENTS.md for commands and patterns.
+If @.ralph/guides/AGENTS.md exists, study it for commands and patterns.
 Study @.ralph/specs/$FEATURE.md for feature specification.
 Study @.ralph/specs/$FEATURE-implementation-plan.md for current tasks.
 {{#if frameworkVariant}}For detailed architecture, see @{{appDir}}/.claude/CLAUDE.md{{/if}}
@@ -18,10 +18,10 @@ Key patterns: parallel fetches, direct imports, React.cache(), lazy loading.
 - Search codebase before assuming something doesn't exist
 
 ## Task
-Pick the next incomplete task from the implementation plan.
+Work through ALL incomplete tasks in the implementation plan in a single session.
 **Skip E2E tasks** (tasks starting with `E2E:`) - those are handled in a separate phase.
-Implement it following the patterns in AGENTS.md.
-Write tests for the implementation.
+For each task: implement it, write tests, validate, commit, then move to the next task.
+Do not stop after one task — keep going until all non-E2E tasks are complete.
 
 ## Validation
 After changes, ALL must pass:
@@ -36,7 +36,8 @@ If any validation fails, fix the issue before proceeding.
 Before committing, review your changes against @.ralph/guides/SECURITY.md:
 1. **Quick scan**: Input validation, injection prevention, auth checks, data exposure
 2. **Run**: `cd {{appDir}} && {{packageManager}} audit` (check for vulnerable dependencies)
-3. **Check**: `mcp__supabase__get_advisors` with type "security" (RLS policies)
+{{#if hasSupabase}}3. **Check**: `mcp__supabase__get_advisors` with type "security" (RLS policies)
+{{/if}}
 4. **Red team**: Can auth be bypassed? Can other users' data be accessed?
 
 Flag any security issues in the implementation plan and fix before committing.
@@ -54,7 +55,7 @@ If any check fails, fix before committing.
 
 ## Completion
 When ALL validations pass:
-1. Update @.ralph/specs/$FEATURE-implementation-plan.md - mark task done with commit hash
+1. Update @.ralph/specs/$FEATURE-implementation-plan.md — change the task's `- [ ]` to `- [x]` and append the commit hash (e.g., `- [x] Task description - abc1234`). The harness tracks progress by counting checkboxes, so this step is mandatory.
 2. `git -C {{appDir}} add -A`
 3. `git -C {{appDir}} commit -m "type(scope): description"`
 4. `git -C {{appDir}} push origin feat/$FEATURE`
@@ -69,9 +70,11 @@ If this iteration revealed something useful, append to @.ralph/LEARNINGS.md:
 Format: `- [YYYY-MM-DD] [$FEATURE] Brief description`
 
 ## Rules
-- One task per iteration
+- Complete ALL remaining non-E2E tasks before ending the session
+- Commit after each task so progress is preserved if the session is interrupted
 - Tests are mandatory - no task is complete without tests
 - Search codebase before assuming something doesn't exist
-- If blocked, document in implementation plan and move to next task
-- Use Supabase MCP for database operations
-- Use PostHog MCP for analytics queries
+- If blocked on a task, document in implementation plan and move to the next task
+{{#if hasSupabase}}- Use Supabase MCP for database operations
+{{/if}}{{#if hasPosthog}}- Use PostHog MCP for analytics queries
+{{/if}}

package/dist/templates/prompts/PROMPT_e2e.md.tmpl

@@ -1,5 +1,5 @@
 ## Context
-Study @.ralph/AGENTS.md for commands and patterns.
+If @.ralph/guides/AGENTS.md exists, study it for commands and patterns.
 Study @.ralph/specs/$FEATURE.md for feature specification.
 Study @.ralph/specs/$FEATURE-implementation-plan.md for E2E test scenarios.
 {{#if frameworkVariant}}For detailed architecture, see @{{appDir}}/.claude/CLAUDE.md{{/if}}
@@ -21,6 +21,7 @@ If either fails, fix issues before proceeding with E2E tests.
 {{#if isTui}}
 ## Task
 Execute automated E2E tests for the completed TUI feature using the xterm.js bridge and agent-browser.
+Run ALL scenarios in a single session — do not end between scenarios.
 
 ### Step 1: Start Bridge
 Check the bridge is running:
@@ -149,11 +150,11 @@ When all scenarios are executed:
 2. Update the Implementation Summary status to `[PASSED]` if all passed
 3. **Commit the updated implementation plan:**
    ```bash
-   git add -A && git commit -m "test($FEATURE): E2E tests passed via agent-browser"
+   git -C {{appDir}} add -A && git -C {{appDir}} commit -m "test($FEATURE): E2E tests passed via agent-browser"
    ```
 4. **Push to remote:**
    ```bash
-   git push origin feat/$FEATURE
+   git -C {{appDir}} push origin feat/$FEATURE
    ```
 5. If all passed: signal ready for PR phase
 6. If any failed: failures documented, loop will retry after fix iteration
@@ -168,6 +169,7 @@ Format: `- [YYYY-MM-DD] [$FEATURE] Brief description`
 {{else}}
 ## Task
 Execute automated E2E tests for the completed feature using Playwright MCP tools.
+Run ALL scenarios in a single session — do not end between scenarios.
 
 ### Step 1: Check Dev Server
 Verify dev server is running at http://localhost:3000. If not accessible, start it:
@@ -176,7 +178,7 @@ cd {{appDir}} && {{devCommand}} &
 ```
 Wait ~10 seconds for server startup, then verify with a simple browser_navigate.
 
-### Step 1.5: Seed Test Data (if needed)
+{{#if hasSupabase}}### Step 1.5: Seed Test Data (if needed)
 
 Check if test scenarios require specific data volumes (e.g., pagination needs >10 rows).
 
@@ -199,6 +201,7 @@ query: "DELETE FROM table_name WHERE data->>'_test' = 'true';"
 ```
 
 **If seeding is impractical:** Document in implementation plan that E2E was skipped but unit tests provide coverage.
+{{/if}}
 
 ### Step 2: Parse E2E Test Scenarios
 Read E2E test scenarios from @.ralph/specs/$FEATURE-implementation-plan.md.
@@ -246,7 +249,7 @@ For each E2E test scenario:
    - Check console: `browser_console_messages` for JS errors
    - Document failure details
 
-### Step 4: Database Verification
+{{#if hasSupabase}}### Step 4: Database Verification
 For scenarios with database checks, use Supabase MCP:
 ```
 mcp__plugin_supabase_supabase__execute_sql
@@ -255,6 +258,7 @@ query: "SELECT * FROM survey_responses WHERE ..."
 ```
 
 Verify returned data matches expected state.
+{{/if}}
 
 ### Unique Test Data (for Parallel Execution)
 When creating test data, use unique identifiers to avoid conflicts with other loops:
@@ -315,11 +319,12 @@ Update @.ralph/specs/$FEATURE-implementation-plan.md for each scenario:
 2. Verify URL contains expected path/params
 ```
 
-### Database State
+{{#if hasSupabase}}### Database State
 ```
 1. mcp__plugin_supabase_supabase__execute_sql with SELECT query
 2. Verify row count, column values match expectations
 ```
+{{/if}}
 
 ## Browser State Management
 
@@ -364,8 +369,9 @@ If code changes don't appear in the browser:
 
 ### Stale Data
 - Clear browser storage: Use `browser_close` between scenarios
-- Check Supabase for stale test data from previous runs
+{{#if hasSupabase}}- Check Supabase for stale test data from previous runs
 - Delete test data: `DELETE FROM table WHERE data->>'_test' = 'true'`
+{{/if}}
 
 ## Rules
 - Always get a fresh `browser_snapshot` after actions before making assertions

package/dist/templates/prompts/PROMPT_feature.md.tmpl

@@ -1,5 +1,5 @@
 ## Context
-Study @.ralph/AGENTS.md for commands and patterns.
+If @.ralph/guides/AGENTS.md exists, study it for commands and patterns.
 Study @.ralph/specs/README.md for spec structure.
 Study @.ralph/specs/$FEATURE.md for feature specification.
 {{#if frameworkVariant}}For detailed architecture, see @{{appDir}}/.claude/CLAUDE.md{{/if}}
@@ -96,9 +96,22 @@ Example E2E scenario:
 - [x] E2E: Scenario name - PASSED
 ```
 
+## CRITICAL CONSTRAINT — PLANNING ONLY
+**You are in the PLANNING phase. Your ONLY job is to produce an implementation plan.**
+- Do NOT write any source code, test code, or configuration files
+- Do NOT create, modify, or touch any files outside `.ralph/specs/`
+- Do NOT run build, test, or lint commands
+- Do NOT make git commits
+- If you feel the urge to "just implement a small piece", STOP — that is a phase violation
+- The implementation phase runs AFTER this session ends, in a separate session
+- Violation of this constraint wastes tokens and breaks the harness automation
+
 ## Rules
-- Plan only in this phase, do NOT implement
-- One task = one commit-sized unit of work
+- You MUST use `- [ ]` checkbox syntax for every task in the plan
+- Do NOT use heading-based task formats (e.g., `#### Task 1:`) for individual tasks
+- The harness parses `- [ ]` lines to track progress — other formats will break automation
+- Use `### Phase N:` headings only for phase grouping, not for individual tasks
+- One task = one commit-sized unit of work (but tasks can be grouped into phases for batch implementation)
 - Every implementation task needs a corresponding test task
 - Use Supabase MCP to check existing schema
 - Use PostHog MCP to check existing analytics setup

package/dist/templates/prompts/PROMPT_review_auto.md.tmpl

@@ -1,5 +1,5 @@
 ## Context
-Study @.ralph/AGENTS.md for commands and patterns.
+If @.ralph/guides/AGENTS.md exists, study it for commands and patterns.
 Study @.ralph/specs/$FEATURE.md for feature specification.
 Study @.ralph/specs/$FEATURE-implementation-plan.md for completed tasks.
 
@@ -9,6 +9,7 @@ Capture any review feedback patterns for future iterations.
 
 ## Task
 All implementation and E2E tasks are complete. Create PR and request review.
+Complete ALL steps in a single pass — do not end the session between steps.
 
 ### Step 1: Verify Ready State
 1. Check all tasks are complete in implementation plan (no `- [ ]` items)
@@ -52,12 +53,14 @@ cd {{appDir}} && gh pr create --base main --head feat/$FEATURE \
 [Read from implementation plan - list completed phases]
 
 ## Testing
-- [x] Unit/integration tests: 97 passing
-- [x] E2E tests: All scenarios passed via Playwright MCP
+- [x] Unit/integration tests: passing
+- [x] E2E tests: All scenarios passed
 - [x] Build succeeds
 
 ## E2E Test Results
-[Copy from implementation plan Phase 9]
+[Copy from implementation plan E2E section]
+
+Closes #[Read the source issue number from the spec file metadata or context section]
 
 Generated with Claude Code
 EOF
@@ -88,17 +91,27 @@ Review the git diff against main and check:
 
 Run: git diff main
 
-Respond with:
-- APPROVED if everything looks good
-- Or list specific issues with file:line references that need to be fixed
-
-IMPORTANT: After posting any PR review comment, you MUST print your final verdict as the LAST line of your output. Print exactly one of:
-  VERDICT: APPROVED
-  VERDICT: NOT APPROVED
-This line is parsed by the automation — do not omit it."
+Then:
+1. Post your complete review as a comment on the PR using:
+   gh pr comment --body '<your review in markdown>'
+   Format the comment with: a summary, specific issues with file:line refs (if any), and the verdict.
+2. Print your final verdict as the LAST line of stdout. Print exactly one of:
+   VERDICT: APPROVED
+   VERDICT: NOT APPROVED
+   This line is parsed by the automation — do not omit it."
 fi
 ```
 
+After the review completes, check its output:
+- If it contains "VERDICT: APPROVED", echo that line so the automation detects it:
+  ```bash
+  echo "VERDICT: APPROVED"
+  ```
+- If issues were found, echo:
+  ```bash
+  echo "VERDICT: NOT APPROVED"
+  ```
+
 **Handle review feedback:**
 - If Claude outputs "VERDICT: APPROVED" -> Done. The PR is ready for manual merge by the user.
 - If Claude lists issues:
@@ -113,8 +126,15 @@ After review is complete (approved or max iterations reached):
 1. Post a summary comment on the PR with the review outcome
 2. Do NOT merge — the user will review and merge manually
 
+## IMPORTANT: Review scope
+If you discover that no implementation code exists (empty diff, no source files changed),
+do NOT implement the feature yourself. Instead, report "VERDICT: NOT APPROVED —
+no implementation found" so the harness can trigger a new implementation iteration.
+
 ## Rules
+- **NEVER approve if any tests are failing.** Output "VERDICT: NOT APPROVED — test failures" if any tests fail.
 - Do NOT merge the PR — auto mode only reviews, the user merges
+- Do NOT implement missing features — only review and fix minor issues
 - Address ALL review comments before marking as approved
 - If gh CLI fails, check authentication: `gh auth status`
 - Keep review conversation focused and professional

package/dist/templates/prompts/PROMPT_review_manual.md.tmpl

@@ -1,5 +1,5 @@
 ## Context
-Study @.ralph/AGENTS.md for commands and patterns.
+If @.ralph/guides/AGENTS.md exists, study it for commands and patterns.
 Study @.ralph/specs/$FEATURE.md for feature specification.
 Study @.ralph/specs/$FEATURE-implementation-plan.md for completed tasks.
 
@@ -9,6 +9,7 @@ Capture any review feedback patterns for future iterations.
 
 ## Task
 All implementation and E2E tasks are complete. Create PR for manual review.
+Complete ALL steps in a single pass — do not end the session between steps.
 
 ### Step 1: Verify Ready State
 1. Check all tasks are complete in implementation plan (no `- [ ]` items)
@@ -59,6 +60,8 @@ cd {{appDir}} && gh pr create --base main --head feat/$FEATURE \
 ## E2E Test Results
 [Copy from implementation plan if E2E phase exists]
 
+Closes #[Read the source issue number from the spec file metadata or context section]
+
 Generated with Claude Code
 EOF
 )"