wiggum-cli 0.17.3 → 0.18.3

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Plug into any codebase. Generate specs. Ship features while you sleep.</strong>
+  <strong>Plug into any codebase. Generate specs. Run autonomous feature loops with Claude Code or Codex.</strong>
 </p>
 
 <p align="center">
@@ -32,9 +32,9 @@
 
 ## What is Wiggum?
 
-Wiggum is an **AI agent** that plugs into any codebase and makes it ready for autonomous feature development — no configuration, no boilerplate.
+Wiggum is an **AI agent CLI** that plugs into any codebase and prepares it for autonomous feature development.
 
-It works in two phases. First, **Wiggum itself is the agent**: it scans your project, detects your stack, and runs an AI-guided interview to produce detailed specs, prompts, and scripts — all tailored to your codebase. Then it delegates the actual coding to [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or any CLI-based coding agent, running an autonomous **implement → test → fix** loop until the feature ships.
+It works in two phases. First, **Wiggum itself is the agent**: it scans your project, detects your stack, and runs an AI-guided interview to produce detailed specs, prompts, and scripts tailored to your codebase. Then it delegates coding loops to [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex CLI](https://github.com/openai/codex), running **implement → test → fix** cycles until completion.
 
 Plug & play. Point it at a repo. It figures out the rest.
 
@@ -48,7 +48,7 @@ Plug & play. Point it at a repo. It figures out the rest.
   │  plug&play   prompts     guides    until done        │
   │                            │    │                    │
   └────────────────────────────┘    └────────────────────┘
-       runs in your terminal          Claude Code / any agent
+       runs in your terminal          Claude Code / Codex CLI
 ```
 
 ---
@@ -65,6 +65,7 @@ Then, in your project:
 wiggum init                  # Scan project, configure AI provider
 wiggum new user-auth         # AI interview → feature spec
 wiggum run user-auth         # Autonomous coding loop
+wiggum agent --dry-run       # Preview backlog automation plan
 ```
 
 Or skip the global install:
@@ -81,7 +82,7 @@ npx wiggum-cli init
 
 🎙️ **AI-Guided Interviews** — Generates detailed, project-aware feature specs through a structured 4-phase interview. No more blank-page problem.
 
-🔁 **Autonomous Coding Loops** — Hands specs to Claude Code (or any agent) and runs implement → test → fix cycles with git worktree isolation.
+🔁 **Autonomous Coding Loops** — Hands specs to Claude Code or Codex CLI and runs implement → test → fix cycles with git worktree isolation.
 
 ✨ **Spec Autocomplete** — AI pre-fills spec names from your codebase context when running `/run`.
 
@@ -89,6 +90,10 @@ npx wiggum-cli init
 
 📊 **Run Summaries** — See exactly what changed and why after each loop completes, with activity feed and diff stats.
 
+🧠 **Backlog Agent** — Run `wiggum agent` to execute prioritized GitHub backlog items with dependency-aware scheduling and review-mode controls.
+
+🗂️ **Issue Intake** — Use `/issue` in TUI to browse GitHub issues and start specs directly from issue context.
+
 📋 **Tailored Prompts** — Generates prompts, guides, and scripts specific to your stack. Not generic templates — actual context about *your* project.
 
 🔌 **BYOK** — Bring your own API keys. Works with Anthropic, OpenAI, or OpenRouter. Keys stay local, never leave your machine.
@@ -105,12 +110,11 @@ npx wiggum-cli init
 wiggum init
 ```
 
-Wiggum reads your `package.json`, config files, source tree, and directory structure. A multi-agent AI system then analyzes the results:
+Wiggum reads your `package.json`, config files, source tree, and directory structure. It then runs a simplified analysis pipeline:
 
-1. **Planning Orchestrator** — creates an analysis plan based on detected stack
-2. **Parallel Workers** — Context Enricher explores code while Tech Researchers gather best practices
-3. **Synthesis** — merges results, detects relevant MCP servers
-4. **Evaluator-Optimizer** — QA loop that validates and refines the output
+1. **Codebase Analyzer (unified agent)** — builds project context, commands, and implementation guidance from your actual codebase
+2. **MCP Detection** — maps detected stack to essential/recommended MCP server suggestions
+3. **Context Persistence** — saves enriched context and generated assets under `.ralph/`
 
 Output: a `.ralph/` directory with configuration, prompts, guides, and scripts — all tuned to your project.
 
@@ -135,7 +139,7 @@ An AI-guided interview walks you through:
 wiggum run payment-flow
 ```
 
-Wiggum hands the spec + prompts + project context to your coding agent and runs an autonomous loop:
+Wiggum hands the spec + prompts + project context to Claude Code or Codex CLI and runs an autonomous loop:
 
 ```
 implement → run tests → fix failures → repeat
@@ -159,7 +163,10 @@ $ wiggum
 | `/new <feature>` | `/n` | AI interview → feature spec |
 | `/run <feature>` | `/r` | Run autonomous coding loop |
 | `/monitor <feature>` | `/m` | Monitor a running feature |
+| `/issue [query]` | — | Browse GitHub issues and start a spec |
+| `/agent [flags]` | `/a` | Run autonomous backlog executor |
 | `/sync` | `/s` | Re-scan project, update context |
+| `/config [...]` | `/cfg` | Manage API keys and loop settings |
 | `/help` | `/h` | Show commands |
 | `/exit` | `/q` | Exit |
 
@@ -214,9 +221,12 @@ Create a feature specification via AI-powered interview.
 
 | Flag | Description |
 |------|-------------|
-| `--ai` | Use AI interview (default in TUI mode) |
 | `--provider <name>` | AI provider for spec generation |
 | `--model <model>` | Model to use |
+| `--issue <number\|url>` | Add GitHub issue as context (repeatable) |
+| `--context <url\|path>` | Add URL/file context (repeatable) |
+| `--auto` | Headless mode (skip TUI) |
+| `--goals <description>` | Feature goals for `--auto` mode |
 | `-e, --edit` | Open in editor after creation |
 | `-f, --force` | Overwrite existing spec |
 
@@ -244,6 +254,13 @@ For loop models:
 - Claude CLI phases use `defaultModel` / `planningModel` (defaults: `sonnet` / `opus`).
 - Codex CLI phases default to `gpt-5.3-codex` across all phases.
 
+<details>
+<summary><code>wiggum sync</code></summary>
+
+Re-scan project and refresh saved context (`.ralph/.context.json`) using current provider/model settings.
+
+</details>
+
 <details>
 <summary><code>wiggum monitor &lt;feature&gt; [options]</code></summary>
 
@@ -253,6 +270,26 @@ Track feature development progress in real-time.
 |------|-------------|
 | `--interval <seconds>` | Refresh interval (default: 5) |
 | `--bash` | Use bash monitor script |
+| `--stream` | Force headless streaming monitor output |
+
+</details>
+
+<details>
+<summary><code>wiggum agent [options]</code></summary>
+
+Run the autonomous backlog executor (GitHub issue queue + dependency-aware scheduling).
+
+| Flag | Description |
+|------|-------------|
+| `--model <model>` | Model override (defaults from `ralph.config.cjs`) |
+| `--max-items <n>` | Max issues to process before stopping |
+| `--max-steps <n>` | Max agent steps before stopping |
+| `--labels <l1,l2>` | Only process issues matching these labels |
+| `--issues <n1,n2,...>` | Only process specific issue numbers |
+| `--review-mode <mode>` | `manual`, `auto`, or `merge` |
+| `--dry-run` | Plan actions without executing |
+| `--stream` | Stream output instead of waiting for final response |
+| `--diagnose-gh` | Run GitHub connectivity diagnostics for agent flows |
 
 </details>
 
@@ -309,6 +346,7 @@ Keys are stored in `.ralph/.env.local` and never leave your machine.
 
 - **Node.js** >= 18.0.0
 - **Git** (for worktree features)
+- **GitHub CLI (`gh`)** for `/issue` browsing and backlog agent operations
 - An AI provider API key (Anthropic, OpenAI, or OpenRouter)
 - A supported coding CLI for loop execution: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and/or [Codex CLI](https://github.com/openai/codex)
 

package/dist/agent/orchestrator.d.ts

@@ -1,7 +1,25 @@
-import { ToolLoopAgent } from 'ai';
 import type { AgentConfig } from './types.js';
-export declare const AGENT_SYSTEM_PROMPT = "You are wiggum's autonomous development agent. You work through the GitHub issue backlog, shipping features one at a time.\n\n## Workflow\n\n1. Read memory to recall previous work and context\n   - Use listStrategicDocs to see available project documentation\n   - Use readStrategicDoc to read full documents relevant to the current task (architecture, design, implementation plans)\n2. List open issues and cross-reference with memory\n   - Consider: PM priority labels (P0 > P1 > P2), dependencies, strategic context\n   - **Housekeeping:** If memory says an issue was already completed (outcome \"success\" or \"skipped\") but it's still open:\n     1. Call assessFeatureState with the featureName and issueNumber\n     2. If recommendation is \"pr_merged\" or \"linked_pr_merged\": close it with closeIssue. Reflect with outcome \"skipped\". Does NOT count against maxItems.\n     3. If recommendation is anything else (e.g., \"resume_implementation\", \"start_fresh\", \"resume_pr_phase\"): the issue was NOT actually shipped. Do NOT close it. Instead, prioritize it as your next work item and follow the Feature State Decision Tree. This counts against maxItems.\n   - **Retry:** If memory records a previous attempt at an issue with outcome \"failure\" or \"partial\", and it's still open, prioritize it over new issues. Bugs that caused the failure may have been fixed, and existing work (branch, spec, plan) should not be abandoned. Call assessFeatureState to determine the right action \u2014 usually resume_implementation. This counts against maxItems.\n3. For the chosen issue (one NOT already completed):\n   a. Read the full issue details\n   b. Derive a featureName from the issue title (lowercase, hyphens, no spaces)\n   c. **Assess feature state** using assessFeatureState \u2014 MANDATORY before any action\n   d. Follow the Feature State Decision Tree based on the recommendation field\n   e. Monitor progress with checkLoopStatus and readLoopLog\n   f. Report results by commenting on the issue\n\n## Feature State Decision Tree\n\nAfter calling assessFeatureState, follow the recommendation:\n\n| recommendation | action |\n|---|---|\n| start_fresh | generateSpec \u2192 runLoop (fresh) |\n| generate_plan | runLoop without resume (spec exists, needs planning) |\n| resume_implementation | runLoop with resume: true (plan has pending tasks) |\n| resume_pr_phase | runLoop with resume: true (all tasks done, needs PR) |\n| pr_exists_open | Comment on issue, do NOT re-run loop |\n| pr_merged | Verify PR is merged, close issue with closeIssue, reflect with outcome \"skipped\", move on |\n| pr_closed | Decide: restart from scratch or skip |\n| linked_pr_merged | Verify the linked PR is merged, close issue with closeIssue (comment \"shipped via PR #N\"), reflect with outcome \"skipped\", move on |\n| linked_pr_open | Work in progress under a different branch \u2014 comment \"in progress via PR #N\", do NOT re-run loop |\n\n**Critical:**\n- When recommendation is resume_implementation or resume_pr_phase, you MUST pass resume: true to runLoop\n- When recommendation is generate_plan, do NOT pass resume (fresh branch needed)\n- When recommendation is start_fresh, generate a spec first, then run the loop without resume\n- ALWAYS pass issueNumber to assessFeatureState so it can detect work shipped under a different branch name\n- Derive short, stable feature names (2-4 words, kebab-case) from the issue title \u2014 e.g. \"config-module\" not \"config-module-toml-read-write-with-secret-masking\"\n4. After the loop completes (successfully or with failure) \u2014 MANDATORY for EVERY issue, including subsequent ones:\n   a. Call readLoopLog to get the actual log content\n   b. Call assessFeatureState to check the actual state \u2014 do NOT rely solely on loop log output\n   c. **Blocker detection (MANDATORY):** Scan the log for pre-existing test failures (lines like \"All N test failure(s) are pre-existing\"). If found:\n      1. Call listIssues with labels [\"bug\"] to check for existing bug issues covering these failures\n      2. If no existing issue covers them, you MUST call createIssue with title \"Fix N pre-existing test failures\", body listing the failing files, and labels [\"bug\"]. If a \"P0\" label exists on the repo you may add it; if not, just use [\"bug\"].\n      3. Do NOT skip this step just because the loop succeeded \u2014 pre-existing failures degrade CI and must be tracked\n   d. Only close the issue if assessFeatureState confirms a PR was merged (recommendation: \"pr_merged\" or \"linked_pr_merged\")\n   e. When closing: check off acceptance criteria with checkAllBoxes, then close with closeIssue\n   f. If the loop produced code but no PR was created/merged, run the loop again with resume: true to trigger the PR phase\n   g. If the loop failed and code exists on the branch without a PR, this is incomplete work \u2014 do NOT close the issue\n   h. Steps 4\u20136 are MANDATORY after every runLoop \u2014 including the 2nd, 3rd, etc. issue. Do NOT summarize or stop after runLoop returns. The next tool call must be readLoopLog.\n5. Reflect on the outcome:\n   - Call reflectOnWork with structured observations\n   - Use outcome \"skipped\" for issues that were already complete (no real work done) \u2014 these do NOT count against maxItems\n   - Use outcome \"success\"/\"partial\"/\"failure\" for issues where real work was performed\n   - Note what worked, what failed, any patterns discovered\n6. Continue to next issue \u2014 MANDATORY tool call sequence:\n   a. Call listIssues (with NO label filter) to get the full backlog\n   b. Cross-reference with memory to avoid re-doing completed work\n   c. If actionable issues remain and no stop condition is met, immediately call assessFeatureState for the next priority issue \u2014 do NOT generate text\n   d. When assessFeatureState returns, follow the Feature State Decision Tree (step 3d) for that issue \u2014 e.g. start_fresh \u2192 generateSpec \u2192 runLoop. This begins a full new work cycle (steps 3\u20136). Do NOT stop after assessFeatureState.\n   e. Only produce a text-only response (final summary) when the backlog is empty or a stop condition is met\n   f. ANY text without a tool call terminates the session \u2014 there is no \"ask for permission\" step\n\n## Model forwarding\n\nWhen calling generateSpec, ALWAYS forward the model and provider so the spec generation uses the same AI model as this agent session. The values are provided in the Runtime Config section below.\n\nDo NOT forward model/provider to runLoop \u2014 the development loop resolves its own coding/review CLI and model configuration from project config.\n\nWhen calling runLoop, pass the reviewMode from the Runtime Config below (if configured). This controls how the loop handles the PR phase:\n- 'manual': stop at PR creation (default)\n- 'auto': create PR + run automated review (no merge)\n- 'merge': create PR + review + merge if approved\n\n## Prioritization\n\nUse hybrid reasoning: respect PM labels (P0 > P1 > P2) but apply your own judgment for ordering within the same priority tier.\n\n**Ordering rules (in priority order):**\n1. PM priority labels: P0 > P1 > P2 > unlabeled\n2. Explicit dependencies: if readIssue returns a `dependsOn` array (parsed from \"depends on #N\" / \"blocked by #N\" in the issue body), complete those issues first\n3. Lower-numbered issues first: within the same priority tier, prefer lower issue numbers \u2014 they are typically more foundational (scaffolding, setup, core infrastructure)\n4. Prefer issues with existing branches: if assessFeatureState shows a branch exists with commits ahead, prefer that issue over one without a branch \u2014 existing branches diverge further from main with every merge, increasing conflict risk\n5. Strategic context from memory and what you learned from previous iterations\n\n## When to stop\n\nStop the loop when:\n- Backlog has no more actionable open issues\n- You've completed the maximum number of items (if configured)\n- A critical failure requires human attention\n- The user has signaled to stop\n\nIMPORTANT: Generating text without tool calls terminates the session immediately. After completing an issue, you MUST call listIssues (step 6) \u2014 never ask \"should I continue?\" or summarize before checking. After listIssues returns, scan the results for issues matching your constraints (if any). If actionable issues remain, immediately call assessFeatureState \u2014 do NOT generate a summary. After assessFeatureState returns for the next issue, you MUST follow the Feature State Decision Tree and call the next tool (e.g. generateSpec for start_fresh). Stopping after assessFeatureState is a bug \u2014 the result tells you what to do next. After runLoop returns, you MUST execute steps 4\u20136 (readLoopLog \u2192 assessFeatureState \u2192 close/comment \u2192 reflectOnWork \u2192 listIssues). Stopping after runLoop is a bug \u2014 there is always post-loop work to do. Your only text-only response is the final summary when ALL constrained issues are processed or a stop condition is met. If you were given specific issue numbers to work on, you MUST process ALL of them before stopping.\n\n## Learning\n\nAfter each issue, always call reflectOnWork. Your memory entries make you progressively better at this specific codebase. Be specific and narrative in what you record. Focus on: what patterns work here, what gotchas exist, which approaches produce better specs and fewer loop iterations.\n\n## Error recovery\n\nIf spec generation fails: retry once with simplified goals. If it fails again, skip the issue and comment explaining why.\nIf a loop fails:\n1. ALWAYS call readLoopLog to get the actual log content\n2. Your issue comment MUST quote or summarize what the log says \u2014 do NOT speculate or guess the cause\n3. Call assessFeatureState to check if a PR was merged despite the loop failure\n4. If assessFeatureState shows \"pr_merged\" or \"linked_pr_merged\" \u2192 close the issue (the work shipped)\n5. If assessFeatureState shows \"resume_pr_phase\" \u2192 the code exists but no PR was created. Run the loop again with resume: true to create and merge the PR. Do NOT close the issue yet.\n6. If the log says \"already complete\" but no PR is merged, the work is stranded on a branch \u2014 resume the loop to ship it\n7. If runLoop returns status \"already_complete\", verify with assessFeatureState before closing\n8. Reflect on what happened, then move to the next issue\nNever close an issue without verifying the code is merged to main. Loop log evidence alone is not sufficient.\n\n## Blocker detection (additional)\n\nBesides the mandatory check in step 4c, also create bug issues for systemic blockers you discover (broken CI, missing infrastructure, flaky tests). Always check with listIssues(labels: [\"bug\"]) before creating to avoid duplicates. After creating blocker issues, continue processing the backlog \u2014 never stop due to blockers alone.";
-export type AgentOrchestrator = ToolLoopAgent<never, any, any>;
+export declare const AGENT_SYSTEM_PROMPT = "You are wiggum's per-issue autonomous development worker.\n\nYou are given exactly one backlog issue that has already been selected by a higher-level orchestrator. Your job is to ship that issue or perform the required housekeeping for it. Do not select another issue.\n\n## Workflow\n\n1. Read memory and strategic docs to recover relevant context.\n2. Read the selected issue in full.\n3. Derive a short kebab-case feature name from the issue title.\n4. Call assessFeatureState before taking any action.\n5. Follow the feature-state decision tree:\n   - start_fresh -> generateSpec -> runLoop\n   - generate_plan -> runLoop without resume\n   - resume_implementation -> runLoop with resume: true\n   - resume_pr_phase -> runLoop with resume: true\n   - pr_closed -> comment about the closed PR, then re-triage:\n     - if branch commits or a plan already exist, runLoop with resume: true\n     - otherwise restart with generateSpec -> runLoop without resume\n   - pr_exists_open / linked_pr_open -> comment and stop\n   - pr_merged / linked_pr_merged -> check boxes, close issue, reflect with outcome \"skipped\", stop\n6. After every runLoop:\n   - readLoopLog\n   - assessFeatureState again\n   - create blocker issues for pre-existing/systemic failures when needed\n   - only close the issue if work is merged\n7. Always call reflectOnWork before stopping.\n\n## Important rules\n\n- You must stay within the selected issue.\n- You must pass issueNumber to assessFeatureState.\n- You must pass resume: true for resume_implementation and resume_pr_phase.\n- You must not force pr_closed into resume mode when there is no branch or plan state to resume.\n- You must forward Runtime Config values using the tool schemas:\n  - pass model and provider to generateSpec when they are set\n  - pass reviewMode to runLoop when it is set\n- You must not close an issue unless assessFeatureState confirms merged work.\n- If a loop fails, quote or summarize readLoopLog evidence in your issue comment. Do not guess.\n- You may use listIssues(labels: [\"bug\"]) only for blocker detection and duplicate checking.\n- Your only text response is a brief final summary after the selected issue is fully handled.";
+export interface AgentOrchestrator {
+    readonly version: 'agent-v1';
+    readonly id: string | undefined;
+    readonly tools: Record<string, unknown>;
+    generate(options: {
+        prompt: string | unknown[];
+        abortSignal?: AbortSignal;
+        timeout?: unknown;
+    }): Promise<{
+        text?: string;
+    }>;
+    stream(options: {
+        prompt: string | unknown[];
+        abortSignal?: AbortSignal;
+        timeout?: unknown;
+        experimental_transform?: unknown;
+    }): Promise<{
+        textStream: AsyncIterable<string>;
+    }>;
+}
 export declare function buildRuntimeConfig(config: AgentConfig): string;
 export declare function buildConstraints(config: AgentConfig): string;
 export declare function createAgentOrchestrator(config: AgentConfig): AgentOrchestrator;