{"id":46360409,"url":"https://github.com/gregorydickson/pickle-rick-claude","last_synced_at":"2026-06-30T02:00:47.828Z","repository":{"id":339624412,"uuid":"1162724428","full_name":"gregorydickson/pickle-rick-claude","owner":"gregorydickson","description":"🥒 Pickle Rick for Claude Code — autonomous PRD-driven coding loops + relentless code review. Ralph Loop toolkit.","archived":false,"fork":false,"pushed_at":"2026-06-28T22:16:50.000Z","size":71604,"stargazers_count":27,"open_issues_count":0,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-28T23:05:37.357Z","etag":null,"topics":["agentic","ai-coding","anthropic","autonomous-agent","claude","claude-code","code-review","iterative-development","llm","meeseeks","pickle-rick","tmux"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gregorydickson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-20T16:07:09.000Z","updated_at":"2026-06-28T22:16:53.000Z","dependencies_parsed_at":"2026-04-02T01:08:11.360Z","dependency_job_id":null,"html_url":"https://github.com/gregorydickson/pickle-rick-claude","commit_stats":null,"previous_names":["gregorydickson/pickle-rick-claude"],"tags_count":220,"template":false,"template_full_name":null,"purl":"pkg:github/gregorydickson/pickle-rick-claude","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gregorydickson%2Fpickle-rick-claude","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gregorydickson%2Fpickle-rick-claude/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gregorydickson%2Fpickle-rick-claude/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gregorydickson%2Fpickle-rick-claude/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gregorydickson","download_url":"https://codeload.github.com/gregorydickson/pickle-rick-claude/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gregorydickson%2Fpickle-rick-claude/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34949234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","ai-coding","anthropic","autonomous-agent","claude","claude-code","code-review","iterative-development","llm","meeseeks","pickle-rick","tmux"],"created_at":"2026-03-05T01:11:16.704Z","updated_at":"2026-06-30T02:00:47.811Z","avatar_url":"https://github.com/gregorydickson.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"images/pickle-rick.png\" alt=\"Pickle Rick for Claude Code\" width=\"100%\" /\u003e\n\n# 🥒 Pickle Rick for Claude Code\n\n\u003e *\"Wubba Lubba Dub Dub! 🥒 I'm not just an AI assistant, Morty — I'm an **autonomous engineering machine** trapped in a pickle jar!\"*\n\nPickle Rick is a complete agentic engineering toolbelt built on the [Ralph Wiggum loop](https://ghuntley.com/ralph/) and ideas from Andrej Karpathy's [AutoResearch](https://github.com/karpathy/autoresearch) project. Hand it a PRD — or let it draft one — and it decomposes work into tickets, spawns isolated worker subprocesses, and drives each through a full **research → plan → implement → verify → review → simplify** lifecycle without human intervention.\n\nNew to PRDs? See the **[PRD Writing Guide](PRD_GUIDE.md)** for developers or the **[Product Manager's Guide](PM_GUIDE.md)** for PMs defining and refining requirements. For internals, see [Internals](internals.md). For what's coming next, see the [Feature Roadmap](roadmap.md).\n\n\u003e **Recently released** — `/citadel` conformance audit · **v1.58** Convergence Toolchain Gates ([details](#convergence-gate)) · **v1.57** `/cronenberg` meta-router · **v1.56** pipeline resume hardening · **v1.55** Agent Teams mode (`/pickle-tmux --teams`) · **v1.51** Codex backend (`--backend codex`).\n\n---\n\n## How to Build Things with Pickle Rick\n\nTwo ways to drive every step: **just describe what you want** (Rick routes to the right skill) or **invoke the slash command yourself** (explicit control). Same artifacts either way.\n\n\u003e **Fire and forget** — for one-shot autopilot from goal to shipped code, hand the whole thing to `/pickle-pipeline \"\u003cgoal\u003e\"` (build → citadel → anatomy-park → szechuan-sauce, sequential, with auto-refine when prose triggers it) or `/cronenberg \"\u003cgoal\u003e\"` (meta-router that picks the right metaphor + cleanup chain for the task). Skip the step-by-step below.\n\n### Step 1: Write a PRD\n\nEvery feature starts with a PRD. Just describe what you want:\n\n```\n\"Help me write a PRD for caching loan status API responses in Redis\"\n```\n\nRick interrogates you — *why* are you building this, *who* is it for, and critically: **how will we verify each requirement automatically?** He explores your codebase during the interview, grounding the PRD in what actually exists.\n\nOr write your own `prd.md` and skip the interview — whatever gets requirements on paper with machine-checkable acceptance criteria.\n\n```bash\n/pickle-prd                      # Slash-command alternative — same interactive interview\n```\n\n### Step 2: Refine the PRD\n\nJust ask:\n\n```\n\"Refine prd.md\"\n```\n\nThree AI analysts run in parallel and tear your PRD apart from different angles — requirements gaps, codebase integration points, and risk/scope. They cross-reference each other across 3 cycles.\n\n```bash\n/pickle-refine-prd my-prd.md     # Slash-command alternative\n```\n\nWhat you get back:\n- `prd_refined.md` — your PRD with concrete file paths, interface contracts, and gap fills\n- Atomic tickets — each \u003c 30 min of work, \u003c 5 files, \u003c 4 acceptance criteria, self-contained\n- Wiring ticket (3+ tickets) — integrates isolated modules into a working whole\n- **Hardening tickets** — auto-appended code quality review + data flow audit scoped to modified files\n\nThe hardening tickets (skipped for trivial/small single-ticket PRDs) run as normal Morty workers after all implementation work:\n1. **Code Quality Hardening** — szechuan-sauce principles review (KISS, DRY, dead code, edge cases) on all modified files\n2. **Data Flow Audit** — anatomy-park-style trace through affected subsystems (ID mismatches, stale schemas, cross-ticket interface alignment)\n\n**Review the tickets before proceeding.** Check ordering, scope, and acceptance criteria. You can edit them directly — they're markdown files.\n\n### Step 3: Implement with tmux (the Ralph Loop)\n\nJust ask:\n\n```\n\"Build the tickets\"\n```\n\nThis is where Rick takes over. Each ticket goes through 8 phases autonomously: Research → Review → Plan → Review → Implement → Spec Conformance → Code Review → Simplify. Context clears between every iteration — no drift, even on 500+ iteration epics.\n\n```bash\n/pickle-tmux --resume            # Slash-command alternative — picks up refined tickets\n/pickle-refine-prd --run my-prd.md   # Combine refine + implement in one shot\n```\n\nRick prints a `tmux attach` command — open a second terminal to watch the live 3-pane dashboard:\n- **Top-left**: ticket status, phase, elapsed time, circuit breaker state\n- **Top-right**: iteration log stream\n- **Bottom**: live worker output (research, implementation, test runs, commits)\n\nSit back. Rick handles the rest.\n\n\u003e **Worker-spawn mechanism** — `/pickle-tmux --teams` swaps the per-ticket `claude -p` subprocess for a harness-native subagent on a team (`TeamCreate` + `Agent` + `TaskUpdate`), running under tmux. Same 8-phase lifecycle, same artifact contract, no token-sniffing log heuristics — cleaner completion signals and stricter artifact validation. Claude backend only (codex+teams rejected at setup); the default subprocess path remains for `/pickle-tmux` without `--teams`, `/pickle-zellij`, `/pickle-microverse`, and `/pickle-pipeline`. See [Agent Teams Mode](#agent-teams) below.\n\n\u003e **Backend choice** — append `--backend codex`, `--backend hermes`, or `--backend deepseek` (or export `PICKLE_BACKEND=codex` / `PICKLE_BACKEND=hermes` / `PICKLE_BACKEND=deepseek`) to route worker/manager spawns through another backend instead of `claude`. DeepSeek requires `DEEPSEEK_API_KEY` in the environment (setup exits 1 before creating any session directory if it is missing). See [Backends](#backends) below for precedence and examples.\n\n\u003e **If things go wrong** — `\"Stop hook error\"` in the Claude Code UI is normal: every `decision: block` from the stop hook is labelled that way. The loop is working. If a single ticket fails, run `/pickle-retry \u003cticket-id\u003e` instead of restarting the whole epic.\n\n### Step 4 (Optional): Metric-Driven Refinement\n\nJust ask:\n\n```\n\"Push test coverage to 90%\"\n```\n\nIf you can define a measurable goal — test coverage, response time, bundle size, extraction accuracy — the Microverse grinds toward it. Each cycle: make one change, measure, keep or revert. Failed approaches are tracked so it never repeats a dead end.\n\n```bash\n# Slash-command alternative:\n/pickle-microverse --metric \"npm run coverage:score\" --task \"hit 90% test coverage\"\n/pickle-microverse --metric \"node perf-test.js\" --task \"reduce p99 latency\" --direction lower\n/pickle-microverse --goal \"error messages are user-friendly and actionable\" --task \"improve UX\"\n```\n\n\u003ca id=\"backends\"\u003e\u003c/a\u003e**Backends** — `/pickle-tmux`, `/szechuan-sauce`, `/anatomy-park`, and `/pickle-microverse` accept `--backend codex` to route spawns through `codex exec`, `--backend hermes` to route spawns through `hermes chat -q ... -Q --ignore-rules --ignore-user-config`, or `--backend deepseek` to route spawns through the DeepSeek API (requires `DEEPSEEK_API_KEY`; uses `ANTHROPIC_MODEL` if set, else defaults to `deepseek-v4-pro`). The choice is persisted in `state.json` and survives resume; omit the flag to keep the default `claude` backend. Set `PICKLE_BACKEND=codex`, `PICKLE_BACKEND=hermes`, or `PICKLE_BACKEND=deepseek` for a session-independent alternative that persists across commands. Precedence: CLI flag \u003e env var \u003e session state \u003e default `claude`. **Incompatible with `--teams`** — agent-teams mode is claude-harness-native; setup rejects non-claude backends (codex, hermes, deepseek) at session creation and on `--resume`.\n\nFor codex-backed runs, prefer tmux-direct: the shell/tmux pane owns `mux-runner`, and `codex exec` is only a child spawned by mux-runner. Avoid the risky arrangement where a long-lived codex session becomes the parent of mux-runner and supervises the whole pipeline.\n\n```bash\n/pickle-tmux --backend codex \"refactor the auth middleware\"\n/szechuan-sauce --backend codex src/services/\n/anatomy-park --backend codex src/\n/pickle-microverse --backend codex --metric \"npm run coverage:score\" --task \"hit 90%\"\nPICKLE_BACKEND=codex /pickle-tmux \"refactor the auth middleware\"\n```\n\n`/council-of-ricks` integrates Codex differently — its Phase C runs an adversarial Codex subagent by default (`--no-codex` to disable, `--codex-timeout \u003csec\u003e` to tune). See the Council of Ricks section below.\n\n**Reasoning effort** *(codex backend)* — append `--effort \u003clow|medium|high\u003e` to opt into a non-default reasoning effort. Pickle threads it through to `codex exec` as `-c reasoning.effort=\u003clevel\u003e` before the prompt separator. Omit the flag to inherit whatever your local `codex` CLI / `~/.codex/config.toml` is set at — Pickle does not override the default. Persisted in `state.json` and survives `--resume`. Claude path is a no-op (no public reasoning-effort flag for `claude -p`); refinement displays the level for visibility but does not pass it (claude-only).\n\n```bash\n/pickle-tmux --backend codex --effort high \"build the caching layer\"\n```\n\n\u003ca id=\"agent-teams\"\u003e\u003c/a\u003e**Agent Teams mode** *(claude backend only)* — `/pickle-tmux --teams` switches Phase 3 from spawning per-ticket `claude -p` subprocesses to spawning subagents on a harness-native team, **under tmux** (true `/clear` between iterations). `--teams` is passed together with `--tmux`, so the session is created with `tmux_mode: true` and `teams_mode: true`; the bare in-session `/pickle --teams` path was removed (R-PNTR-4). Each ticket dispatches the six `morty-phase-*` subagents (`Agent` tool with `team_name` + `subagent_type`); the final phase signals completion via `TaskUpdate(status=\"completed\")` instead of the legacy `\u003cpromise\u003eI AM DONE\u003c/promise\u003e` token + log-size check. Manager-side validation is a strict all-of artifact check (`validate-teams-ticket.js`): every required prefix (`research_*.md`, `plan_*.md`, `conformance_*.md`, `code_review_*.md`) must have a matching file or the ticket is marked Failed. The flag is persisted in `state.json` and survives resume.\n\n```bash\n/pickle-tmux --teams \"add a /healthz endpoint\"\n/pickle-tmux --teams --max-parallel 10 \"build the caching layer\"   # plumbed; v1 sequential\n/pickle-tmux --resume                                              # teams_mode survives resume\n```\n\nSubagent definitions live at `~/.claude/agents/morty-implementer.md` (8-phase implementation lifecycle), `~/.claude/agents/morty-reviewer.md` (4-phase review lifecycle), and the six `~/.claude/agents/morty-phase-*.md` phase teammates. All are deployed by `install.sh`. See the [PRD](prds/pickle-agent-teams.md) for the v1 boundary. The default subprocess path is untouched — passing no `--teams` flag preserves the legacy `mux-runner` spawn loop.\n\nWhen NOT to use: codex/hermes backend (codex+teams rejected at setup); `/pickle-zellij` / `/pickle-microverse` / `/pickle-pipeline` (legacy spawn only). When to use: epics where you want clean bidirectional comms with the worker, native completion notifications, and the strictest artifact gate available.\n\n### Step 5 (Optional): Cleanup\n\nFour options for polishing the result.\n\n**Full Pipeline** — chains build, Citadel conformance audit, deep review, and deslop in a single tmux session. No manual intervention between phases. When refinement is mentioned in the request (or `--refine` is passed), the skill auto-runs `/pickle-refine-prd` first.\n\n```\n\"Run the full pipeline to build the caching layer\"\n```\n\n```bash\n# Slash-command alternative:\n/pickle-pipeline \"build the caching layer\"                            # No refinement (no trigger)\n/pickle-pipeline \"refine the prd then build the caching layer\"        # Auto-inferred from prose\n/pickle-pipeline --refine \"build the caching layer\"                   # Explicit force, prose silent\n/pickle-pipeline --no-refine \"refine the prd first then ship X\"       # Suppress auto-inferred refinement\n/pickle-pipeline \"build feature/payment-api\"                          # Branch named → scope prompt fires (Step 0.6)\n/pickle-pipeline --scope branch \"build feature/payment-api\"           # Explicit scope, skips the prompt\n/pickle-pipeline --skip-anatomy \"refactor auth\"                       # Skip deep review\n/pickle-pipeline --target src/services \"add retry logic\"              # Scope review phases\n```\n\nThe auto-refine trigger fires on `refine-prd` / `prd refinement`, on `refine`/`refinement`/`decompose` near `prd` or `first` (within 40 chars), or on workflow ordering like `refine then build`. Bare `refine the dropdown UX` won't trigger — use `--refine` to force, `--no-refine` to suppress. Refinement always uses the `claude` backend regardless of `--backend` (refinement is planning, not implementation). Fails fast if no `prd.md` exists in cwd or session — run `/pickle-prd` first.\n\n**Auto-annotated forward references (Step 7)** — when decomposition cites a path, symbol, or activity-event literal that the bundle itself creates (so it does not resolve at HEAD yet), the decomposer auto-emits the canonical forward-reference annotation so the operator never hand-annotates: `(created by ticket \u003c8hex\u003e)` when a *different* bundle ticket creates the artifact, `(introduced by ticket \u003chash\u003e)` for a cross-ticket symbol, and `(forward-created)` when the same ticket creates it. The non-canonical bare `(ticket \u003chash\u003e)` form is never emitted — the readiness validator does not recognize it. This keeps creation-heavy bundles from false-blocking at the readiness gate on artifacts that legitimately do not exist yet.\n\n**Scope auto-inference (Step 0.6)** — naming a branch (`feature/x`, `fix/y`, `on branch \u003cname\u003e`), saying \"API-only\" / \"backend only\" / \"no cross-repo\", or being on a non-default branch with commits ahead all trigger a scope confirmation prompt before the pipeline launches. Scope is **never silently applied** — you are always asked. Use `--scope branch` to bypass the prompt. See `PRD_GUIDE.md § Pipeline Scope` for full details.\n\n**Mid-flight scope recovery (`lock-scope.js`)** — if a pipeline launched without `--scope`, use `lock-scope.js` to patch all three session files atomically without restarting: `node ~/.claude/pickle-rick/extension/bin/lock-scope.js \u003csession-root\u003e --mode branch [--scope-base main]`. Refuses to run while `pipeline-runner.js` is alive. Collapses the 6-step manual state patch to one command. See `PRD_GUIDE.md § Pipeline Scope — Mid-Flight Recovery` for full usage.\n\n**Session recovery (`/pickle-recover`)** — when a session halts in `recovery_exhausted`, the `/pickle-recover` command (wrapping `pickle-recover.js`) performs exactly one hook-safe recovery transition via a shared primitive — never inline git, never a raw `state.json` write. Five subcommands: `--resume-from-todo` (re-queue the lowest runnable Todo, reattaching any orphaned commit first), `--salvage \u003cticket\u003e` (commit+Done / archive+Todo / ff-reattach / no-op by tree+gate), `--reattach-orphan` (ff-only HEAD-regression recovery), `--reset-ticket \u003cid\u003e` (archive the diff, then re-queue to Todo), and `--reactivate` (un-terminalize a COMPLETED session and re-point it at the lowest runnable Todo — exempt from the `recovery_exhausted` gate, but refuses a still-live `active:true` session). Append `--plan` to any of them for a write-free dry-run that previews the transition. Each real run emits one `operator_recovery_transition` activity event.\n\n**Citadel** — audits the implemented branch against the PRD before deeper review phases. It reads PRD acceptance criteria, interface contracts, changed files, trap-door notes, and sibling phase artifacts when present. Findings are grouped by audit surface: PRD coverage, endpoint contract drift, trap-door enforcement, sibling route divergence, state-machine drift, frontend prop drift, cross-phase findings, pattern conformance, and diff hygiene.\n\n```bash\n# Slash-command alternative:\n/citadel --prd prd.md --diff main..HEAD\n/citadel --prd prd.md --strict --report /tmp/citadel_report.json\n```\n\nCitadel writes a versioned JSON report with `schema: \"1.0\"`. Standalone runs use `--report \u003cpath\u003e` when supplied; `/pickle-pipeline` writes `\u003csession\u003e/citadel_report.json` and passes that report to anatomy-park and szechuan-sauce. `--strict` makes High findings fail the phase; without it, only Critical findings halt the pipeline.\n\n**Resume hardening** *(v1.56+)* — pipeline pre-flight excludes `prds/` and `docs/` from the clean-tree check by default, so doc churn during a long-running epic doesn't block resume. Override the list per-session via `pipeline.json.ignore_dirty_paths` (set `[]` to opt out entirely). The pickle phase pins its own `command_template` on entry — a stale `state.command_template` from a prior phase no longer misroutes resumed workers to the wrong skill prompt.\n\n**Szechuan Sauce** — hunts coding principle violations (KISS, DRY, SOLID, security, style) and fixes them one at a time until zero remain. Great for post-feature polish before merging.\n\n```\n\"Deslop src/services with szechuan sauce\"\n```\n\n```bash\n# Slash-command alternative:\n/szechuan-sauce src/services/                  # Deslop a directory\n/szechuan-sauce --dry-run src/                 # Catalog violations without fixing\n/szechuan-sauce --focus \"error handling\" src/  # Narrow the review\n/szechuan-sauce --design-safe src/             # Report-only for branch-authored visual code\n/szechuan-sauce --no-design-safe src/          # Force off (override auto-detection)\n```\n\n**Design-safe mode** — when active, branch-authored visual findings (CSS layout, component styling, design tokens) are tagged `[report-only]` and never selected as the iteration's fix. Non-visual logic findings are unaffected. Auto-detected: when `\u003e60%` of the branch diff is visual lines the pipeline enables design-safe automatically (errs toward safe within a 5% near-threshold band). Pass `--design-safe` to force it on or `--no-design-safe` to force it off. On `/pickle-pipeline`, the same flags apply to both cleanup phases.\n\n**Anatomy Park** — traces data flows through subsystems looking for runtime bugs: data corruption, timezone issues, rounding errors, schema drift. Catalogs \"trap doors\" (files that keep breaking) in `CLAUDE.md` files for future engineers. Respects `design_safe` mode: when enabled (auto-detected or via `--design-safe` on `/pickle-pipeline`), branch-authored visual findings are report-only and never auto-fixed.\n\n```\n\"Run anatomy park on src/\"\n```\n\n```bash\n# Slash-command alternative:\n/anatomy-park src/                         # Deep subsystem review\n/anatomy-park --dry-run                    # Review only, no fixes\n\n# Via pipeline (design-safe applies to both anatomy-park and szechuan-sauce phases):\n/pickle-pipeline --design-safe             # Force design-safe for all cleanup phases\n/pickle-pipeline --no-design-safe          # Force off (override auto-detection)\n```\n\n**Cronenberg (meta-router)** — when you don't know which cleanup metaphor fits, describe the goal and let `/cronenberg` pick the right pickle metaphor + cleanup chain for the task. Explicit invocation only — never auto-triggers.\n\n```bash\n/cronenberg \"tighten the integrations package\"\n```\n\n### The Full Flow at a Glance\n\nEnd-to-end Pickle Rick pipeline — applies regardless of how you kick it off (described task, individual slash commands, `/pickle-pipeline`, or `/cronenberg`). Each step is independently invocable; the diagram is the canonical happy path.\n\n```\nYou describe a feature\n       │\n       ▼\n  /pickle-prd              ← Interactive PRD drafting (or write your own)\n       │\n       ▼\n  /pickle-refine-prd       ← 3 parallel analysts refine + decompose into tickets\n       │                      Includes auto-generated hardening tickets:\n       │                      • Code quality review (szechuan-sauce principles)\n       │                      • Data flow audit (anatomy-park trace)\n       ▼\n  /pickle-tmux --resume    ← Autonomous implementation (Ralph loop)\n       │                      Research → Plan → Implement → Verify → Review → Simplify\n       │                      Context clears every iteration. Circuit breaker auto-stops runaways.\n       │                      Hardening tickets run automatically after implementation.\n       ▼\n  /pickle-microverse       ← (Optional) Metric-driven optimization loop\n       │\n       ▼\n  /pickle-pipeline         ← (Optional) Full lifecycle: build → citadel → deep review → deslop\n  ─ or run phases individually ─\n  /citadel                 ← (Optional) PRD conformance audit\n  /anatomy-park            ← (Optional) Data flow correctness review\n  /szechuan-sauce          ← (Optional) Code quality cleanup\n       │\n       ▼\n  Ship it 🥒\n```\n\n---\n\n## ⚡ Quick Start\n\n### 1. Install\n\n```bash\ngit clone https://github.com/gregorydickson/pickle-rick-claude.git\ncd pickle-rick-claude\nbash install.sh\n```\n\n### Deploy Lockdown Operations\n\n`install.sh` refuses source versions older than the deployed runtime unless rollback is explicit. Supported deploy flags:\n\n| Flag | Effect |\n|---|---|\n| `--allow-downgrade` | Permit an older source version after the downgrade confirmation path. |\n| `--override-active` | Bypass active-session refusal and write an active-session bypass audit entry. |\n| `--no-confirm` | Skip interactive downgrade confirmation. |\n| `--closer-context` | Allow release-closer rollback/install flows to bypass active-session refusal while preserving audit evidence. |\n\nRelease closer flows must run `bin/release-gate.sh --pre-tag \u003ctag\u003e` before publishing and `bin/release-gate.sh --post-tag \u003ctag\u003e` after the release exists. Exit codes are: `10` pre-tag package version mismatch, `11` jq parse failed, `12` tag or tagged package missing, `20` release download failed, `21` downloaded tarball package version mismatch, and `22` GitHub release API error.\n\nUse `bin/purge-update-cache.js [--dry-run]` to remove poisoned updater cache state before or during a release. Updater cache lives at `~/.claude/pickle-rick/update-check.json`, and install audit entries live at `~/.claude/pickle-rick/deploy-audit.log`.\n\nGate-baseline activity events are `baseline_recapture_attempted`, `baseline_recapture_succeeded`, and `baseline_recapture_failed`. B-RRH recovery/resilience events are `rate_limit_park_exhausted`, `rate_limited_without_reset_at`, `ticket_ladder_exhausted`, `crashed_ticket_files_quarantined`, `crashed_ticket_files_quarantine_truncated`, and `pickle_incomplete`. Readiness gate events include `resolver_indeterminate` (warn, non-blocking: contract resolver exceeded its wall budget and cannot report completeness; exits 0). Deploy audit-log event types are `DOWNGRADE`, `CACHE_PURGE`, and `INSTALL_BYPASS_ACTIVE_SESSION`.\n\n### 2. Add the Pickle Rick persona to your project\n\nThe installer deploys `persona.md` to `~/.claude/pickle-rick/`. Add it to your project's `CLAUDE.md`:\n\n```bash\n# Already have a CLAUDE.md? Append (safe — won't overwrite your content):\ncat ~/.claude/pickle-rick/persona.md \u003e\u003e /path/to/your/project/.claude/CLAUDE.md\n\n# Starting fresh:\nmkdir -p /path/to/your/project/.claude\ncp ~/.claude/pickle-rick/persona.md /path/to/your/project/.claude/CLAUDE.md\n```\n\n\u003e **After upgrading:** `bash install.sh` deploys a fresh `persona.md`. If you appended it to your project's `CLAUDE.md`, re-sync by replacing the old persona block with the updated one.\n\n### 3. Run\n\n\u003e **Permissions:** Launch Claude with `claude --dangerously-skip-permissions`. Pickle Rick's loops spawn worker subprocesses that already run permissionless, but the root instance needs it too — otherwise you'll drown in permission prompts for every file write, bash command, and hook invocation.\n\n```bash\ncd /path/to/your/project\nclaude --dangerously-skip-permissions\n# then follow the workflow above — start with a PRD\n```\n\n### 4. Uninstall\n\nTwo uninstall paths depending on how much you want to remove.\n\n**Remove hooks only** — disables automatic behavior (Stop loop enforcement, commit logging, config protection) but keeps extension files and slash commands available for manual use:\n\n```bash\nbash uninstall-hooks.sh\n```\n\nSettings are backed up to `~/.claude/backups/settings.json.pickle-uninstall-hooks.\u003ctimestamp\u003e` before modification. Run `bash install.sh` to re-enable hooks later — `install.sh` is idempotent, safe to re-run any time. Third-party hooks in `settings.json` (RTK, etc.) are never touched.\n\n**What still works without hooks:**\n\n- **One-shot utilities and reporters** (never needed hooks) — `/pickle-prd`, `/pickle-refine-prd`, `/pickle-dot`, `/pickle-dot-patterns`, `/pickle-metrics`, `/pickle-status`, `/pickle-standup`, `/help-pickle`, `/attract`.\n- **Detached-runner commands** (bootstrap a separate process that runs independently inside tmux/zellij) — `/pickle-tmux`, `/pickle-zellij`, `/pickle-jar-open`, `/pickle-microverse`, `/szechuan-sauce`, `/anatomy-park`, `/pickle-pipeline`. These launch `mux-runner.js` / `jar-runner.js` / `microverse-runner.js` / `pipeline-runner.js` inside the multiplexer; the runner spawns its own `claude -p` subprocesses and drives iteration via Node.js, not via the Stop hook. In tmux mode the Stop hook is a pass-through anyway.\n\n**What needs hooks** — in-session loops where the Stop hook is the iteration driver for the same Claude session: `/council-of-ricks`, `/portal-gun`, `/project-mayhem`, `/pickle-retry`. Without hooks these run the first step and stop.\n\n**Full uninstall** — removes hooks, extension scripts at `~/.claude/pickle-rick/`, and all pickle-rick slash commands at `~/.claude/commands/`:\n\n```bash\nbash uninstall.sh\n```\n\n**Preserved after full uninstall** (delete manually if desired):\n- Session history at `~/.local/share/pickle-rick/sessions/`\n- Activity logs at `~/.local/share/pickle-rick/activity/`\n- Settings backups at `~/.claude/backups/`\n- Project-local `CLAUDE.md` files — remove the appended persona block manually\n\nThird-party hooks in `settings.json` (RTK, etc.) are never touched.\n\n---\n\n## Other Workflows\n\n### Council of Ricks: Graphite Stack Review\n\nReviews your [Graphite](https://graphite.dev) PR stack iteratively — but never touches your code. Generates **agent-executable directives** you feed to your coding agent. Escalates through focus areas: stack structure → CLAUDE.md compliance → correctness → cross-branch contracts → test coverage → security → polish.\n\n```bash\n/council-of-ricks                  # Review the current Graphite stack\n```\n\n### Pickle Jar: Night Shift Batch Mode\n\nQueue tasks for unattended batch execution overnight.\n\n```bash\n/add-to-pickle-jar                 # Queue current session\n/pickle-jar-open                   # Run all queued tasks sequentially\n```\n\n---\n\n## Tool Deep Dives\n\n### 🔬 Microverse — Metric Convergence Loop\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/microverse.png\" alt=\"The Microverse — powering your Pickle Rick app\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003e *\"I put a universe inside a box, Morty, and it powers my car battery. This is the same thing, except the universe is your codebase and the battery is a metric.\"*\n\nTwo modes: **Command Metric** (`--metric`) for objective numeric scores, and **LLM Judge** (`--goal`) for subjective quality assessment.\n\n```\nGap Analysis (iteration 0)\n    │ measure baseline, analyze codebase, identify bottlenecks\n    ▼\n┌─────────────────────────────────────────────────┐\n│ Iteration Loop                                   │\n│  1. Plan one targeted change (avoid failed list) │\n│  2. Implement + commit                            │\n│  3. Measure metric                                │\n│     • Improved → accept, reset stall counter     │\n│     • Held → accept, increment stall counter     │\n│     • Regressed → git reset, log failed approach │\n│  4. Converged? (stall_counter ≥ stall_limit)     │\n└──────────────────────┬──────────────────────────┘\n                       ▼\n              Final Report\n```\n\n| | **Microverse** | **Pickle** |\n|---|---|---|\n| **Goal** | Optimize toward a measurable target | Build features from a PRD |\n| **Iteration unit** | One atomic change per cycle | Full ticket lifecycle |\n| **Progress signal** | Metric score | Ticket completion |\n| **Defines \"done\"** | Convergence (score stops improving) | All tickets complete |\n\n**Backend** — add `--backend codex` (or set `PICKLE_BACKEND=codex`) to run the per-iteration implementation via `codex exec` instead of `claude`. The measurement/judge step is unaffected.\n\n### 🍗 Szechuan Sauce — Iterative Code Deslopping\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/szechwan-sauce.jpeg\" alt=\"Command: Szechwan Sauce — The Quest for Clean Code\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003e *\"I'm not driven by avenging my dead family, Morty. That was fake. I-I-I'm driven by finding that McNugget sauce.\"*\n\nReads 30+ coding principles (KISS, YAGNI, DRY, SOLID, Guard Clauses, Fail-Fast, Encapsulation, Cognitive Load, etc.) and scores against a priority matrix (P0 security/data-loss through P4 style). Each iteration: find highest-priority violation, fix atomically, run tests, commit, measure. Regressions auto-revert.\n\n**Phase 0: Contract Discovery** — greps the codebase for importers of every export in target files, builds a contract map, flags cross-module mismatches. Re-checked after every fix.\n\nSupports `--domain \u003cname\u003e` for domain-specific principles (e.g., `financial` adds monetary precision, rounding, regulatory compliance) and `--focus \"\u003ctext\u003e\"` to elevate specific concerns.\n\n**Backend** — add `--backend codex` (or set `PICKLE_BACKEND=codex`) to swap the per-iteration fix spawn from `claude` to `codex exec`. Useful when Codex catches violations a Claude pass missed.\n\n\n### 🏥 Anatomy Park — Deep Subsystem Review\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/anatomy-park.jpeg\" alt=\"Anatomy Park — Deep Subsystem Review\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003e *\"Welcome to Anatomy Park! It's like Jurassic Park but inside a human body. Way more dangerous.\"*\n\nAuto-discovers subsystems, rotates through them round-robin, three-phase protocol per iteration:\n1. **Review** (read-only): trace data flows, check git history, rate CRITICAL/HIGH, propose fixes\n2. **Fix**: apply minimal edits, write regression tests, run full suite\n3. **Verify** (read-only): verify callers/consumers, combinatorial branch verification, revert on regression\n\n**Trap doors** — files with repeated fixes or structural invariants get documented in subsystem `CLAUDE.md` files:\n\n```markdown\n## Trap Doors\n- `bank-statement.service.ts` — borrowerFileId MUST equal S3 batch UUID; tenant isolation depends on effectiveLenderId threading\n```\n\n**Backend** — add `--backend codex` (or set `PICKLE_BACKEND=codex`) to run the Review/Fix/Verify phases through `codex exec` instead of `claude`. The subsystem rotation and trap-door cataloging behave identically regardless of backend.\n\n\u003ca id=\"convergence-gate\"\u003e\u003c/a\u003e### 🚪 Convergence Gate — Toolchain Truth Layer *(v1.58+)*\n\n\u003e *\"Done means the gate says done, Morty. Not vibes.\"*\n\n`/szechuan-sauce` and `/anatomy-park` can no longer declare convergence on a branch that's semantically clean but mechanically broken (failing typecheck, lint errors, red tests). The gate is the truth layer they consult before stopping.\n\n**How it runs:**\n\n- **Finalize** — at convergence-trigger time both skills hand off to `extension/src/bin/finalize-gate.ts`, which runs the project's typecheck + lint + tests (project-aware via `extension/data/gate-commands.json` — pnpm/npm/yarn/cargo/go), compares results against a baseline fingerprint set, and either lets the skill exit clean or kicks the remediator.\n- **Per-iteration** (anatomy-park only) — `microverse-runner` runs a *changed-files* gate after each iteration commit. Regressions increment a soft counter; the loop continues with a one-time warning at threshold (default 5).\n- **Remediator** — `morty-gate-remediator` is a mechanical-only worker: prettier/eslint autofix plus four hand-fix classes (control-regex, async-generator require-await, unnecessary-type-assertion, spec-mock alignment). Every fix runs inside a snapshot-and-revert envelope — if previously-green tests go red, the change is reverted and `gate_autofix_reverted` is logged. `/szechuan-sauce` caps the gate ↔ remediator loop at 3 cycles, `/anatomy-park` at 5.\n- **Out-of-scope failures** — anything outside the session's `scope.json:allowed_paths` is written to `gate/out_of_scope_failures_\u003ciso\u003e.md` and surfaced without invoking the remediator.\n\n**Baseline mode** — fingerprints are `(file, ruleOrCode, occurrence_index)` tuples persisted to `${SESSION_ROOT}/gate/baseline.json`. Strict mode requires zero failures. Baseline mode requires no *new* failures (pre-existing problems don't block convergence). Freshness invariant halts on missing or stale baseline (default 30 iterations / 4 hours).\n\n**Hang \u0026 flake guards** — per-check timeouts (typecheck 120s / lint 60s / tests 300s) plus a 600s cumulative cap. Test scripts are filtered against a hard-refusal regex (`integration|e2e|golden|smoke|baseline|playwright|cypress|hardhat`) and a positive-allow list (`vitest|jest|node --test|mocha`). Add `convergence_gate.known_flake_files` to surface flaky test paths as `green-with-known-flake-warnings` instead of false-red.\n\n**Kill-switch** — set `PICKLE_GATE_DISABLED=1` to bypass the post-runner gate entirely. The skill convergence rules revert to pre-1.58 behavior (semantic-only).\n\n**Microverse opt-in** — `/pickle-microverse` runs are NOT gated by default. Add a filename to `convergence_gate.enabled_convergence_files` (default `[\"anatomy-park.json\"]`) to opt a microverse-driven convergence file into per-iteration gating.\n\n### 🕸️ Code Graph — Symbol-Graph Worker Context *(v2.0, beta)*\n\n\u003e *\"Workers don't grep blind anymore, Morty — they get a map.\"*\n\n**Beta release.** Code Graph is opt-in and ships disabled by default. It indexes the repo into a symbol graph (backed by `@colbymchenry/codegraph`, a per-platform native bundle that may be absent — the service fails open and never crashes a session when it can't load). There are two independent lanes, both off by default: the injected-context lane (`buildCodegraphContextSection`) keys on `codegraph.enabled` and is live only for opted-in sessions — dormant by default; the interactive MCP lane (`codegraph serve --mcp`, which lets Claude-family workers query callers/impact-radius/symbols instead of grepping) is gated OFF unless `expose_mcp_to_workers === true`. The upstream project claims **~58% fewer tool calls** per task — treat this as an **UNVALIDATED upstream claim**; we have not independently measured it.\n\n**Settings** — add a `codegraph:` block to `extension/pickle_settings.json` (resolved by `resolveCodegraphSettings`; an absent/partial/malformed block falls back per field):\n\n| Field | Default | Notes |\n|---|---|---|\n| `codegraph.enabled` | `false` | Master switch for the integration. |\n| `index_at_setup` | `false` | Build/refresh the index at session setup. |\n| `staleness_max_age_minutes` | `30` | On resume, re-`sync` the index when older than this (min `1`). |\n| `context_max_bytes` | `8192` | Max injected context size (clamped `1024`–`65536`). |\n| `expose_mcp_to_workers` | `false` | Materialize the worker MCP config so Claude workers get the `codegraph` server. |\n| `index_timeout_ms` | `120000` | **Split timeout** for the full `indexAll` build (floor `5000`). |\n| `sync_timeout_ms` | `30000` | **Split timeout** for incremental `sync` (floor `1000`). |\n| `query_timeout_ms` | `5000` | **Split timeout** for `buildContext`/queries (floor `500`). |\n\nThe three timeouts are independent — index, sync, and query each get their own budget. (`searchNodes` / `getCallers` / `getImpactRadius` are synchronous and are not raced against a timer.)\n\n**`hardening:` block** — additive runtime-recovery knobs (distinct from `bmad_hardening`; resolved by `resolveHardeningSettings`, per-field fallback). Both caps draw down the persistent `state.recovery_attempts` ledger so they survive relaunch and `setup.js --resume`:\n\n| Field | Default | Notes |\n|---|---|---|\n| `silent_death_respawn_cap` | `1` | Shared respawn budget across both silent-death sub-classes (`log_empty`, `log_truncated`). `0` disables silent-death respawns entirely. |\n| `failed_flip_suppression_cap` | `2` | Max evidence-backed Failed-flip suppressions per ticket. `0` disables suppression (an evidence-backed flip-intent escalates immediately). |\n\n**Kill-switch** — set `PICKLE_CODEGRAPH=off` to make the service inert: every call returns null, it emits nothing, it never loads the native bundle, and the setup-time index is skipped. Only the literal lowercase string `off` disables it — any other value (or absent) leaves the `codegraph.enabled` setting in control.\n\n**Worker MCP layout** — when `expose_mcp_to_workers` is `true`, setup materializes `\u003csession\u003e/mcp/worker-mcp.json` containing `{ mcpServers: { codegraph, ...operatorEntries } }`. This is **Claude-family workers only** — codex workers are **explicitly excluded** (`codex exec` has no `--mcp-config` flag, so `buildCodexInvocation` never receives one). The bundled `codegraph serve --mcp` entry launches with `CODEGRAPH_NO_WATCH=1` so the runtime `sync` is the **single writer** to `.codegraph/codegraph.db` (the serve watcher is off). The operator's own MCP config file is never mutated.\n\n**`.codegraph/` hygiene** — workers must **NOT** commit the `.codegraph/` index directory. Setup appends `.codegraph/` to `.git/info/exclude` automatically (idempotent, best-effort) — no `.gitignore` edit required.\n\n**Activity events** — observable in `state.json.activity` / the activity JSONL:\n\n| Event | Emitted when |\n|---|---|\n| `codegraph_session_summary` | Once at session end. Payload: `{ tickets, degraded_ops, index_status: 'healthy'\\|'degraded'\\|'latched'\\|'disabled', ts }`. |\n| `codegraph_index_built` | A full `indexAll` succeeded. |\n| `codegraph_index_failed` | Setup-time index returned no result. |\n| `codegraph_sync_completed` | An incremental `sync` succeeded. |\n| `codegraph_degraded` | An op was degraded (timeout, lock, corrupt, schema-skew, or latch). |\n| `worker_mcp_config_resolved` | Names the winning `--mcp-config` layer for a worker/manager spawn. |\n\n### 🧬 Cronenberg — The Meta-Router\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/cronenberg.jpg\" alt=\"Cronenberg — Mutate the request. Pick the pipeline.\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003e *\"This is a Cronenberg world, Morty. We just gotta accept it and route around it.\"*\n\n`/cronenberg` is the **explicit-invocation meta-router**. You hand it a request — a task, a PRD path, a bag of flags — and it deterministically mutates that request into the correct pipeline shape: which build skill to launch, which cleanup skills to chain after, which flags to forward. Same signals always produce the same plan. No LLM judgment inside the matrix.\n\nIt's opt-in. The persona's existing routing rules are untouched — type `/cronenberg` only when you want the router to decide for you instead of guessing the right command yourself.\n\n```\n$ARGUMENTS  ──┐\nPRD?         ─┤   ┌─────────────────────────┐    ┌──────────────────┐\ngit status   ─┼──►│  Step 2: gather signals │───►│ Step 3: pick     │\nTASK verbs   ─┘   │  PRD / METRIC / TICKETS │    │   metaphor       │\n                  │  MULTI_STAGE / STACK    │    └────────┬─────────┘\n                  │  SUBSYSTEMS / INTERACT  │             │\n                  └─────────────────────────┘             ▼\n                                                ┌──────────────────┐\n                                                │ Step 4: pick     │\n                                                │   followups      │\n                                                └────────┬─────────┘\n                                                         ▼\n                                                  Execute plan\n                                              (or --dry-run to\n                                                preview only)\n```\n\n**Decision matrix — metaphor (first match wins):**\n\n| Signal | → |\n|---|---|\n| `STACK_REVIEW` (review-focused, mentions PR stack / `gt log`) | `/council-of-ricks` |\n| `MEASURABLE_METRIC` and TASK reads \"optimize/improve/reduce X to Y\" | `/pickle-microverse` |\n| `MULTI_STAGE` (TASK lists 2+ of refine/build/optimize/cleanup/review) | `/pickle-pipeline` |\n| `INTERACTIVE_HINT` (\"interactive\", \"watch me\", \"step through\") | `/pickle-tmux` |\n| `TICKET_COUNT ≥ 3` | `/pickle-tmux` |\n| Default | `/pickle-tmux` |\n\n**Decision matrix — followups (additive):**\n\n| Signal | → |\n|---|---|\n| `CITADEL_RISK` (multi-ticket PRD, spec-conformance request, or multi-subsystem PRD task) | `/citadel --prd \u003cprd_path\u003e` |\n| `SUBSYSTEM_TOUCHES ≥ 2` | `/anatomy-park` |\n| Diff ≥ 500 LOC OR ≥ 10 files OR TASK mentions \"cleanup / deslop / refactor sweep\" | `/szechuan-sauce` |\n\nFollowups are skipped automatically when the chosen metaphor is `/pickle-pipeline` (it already chains citadel + anatomy-park + szechuan-sauce internally), `/pickle-microverse`, or `/council-of-ricks` (orthogonal to cleanup), or when you pass `--no-followups`. Hardening tickets are produced upstream by `/pickle-refine-prd` — there is no separate review-pass step.\n\n**Tmux-detach safety:** `/pickle-tmux`, `/pickle-pipeline`, `/pickle-microverse`, and `/council-of-ricks` launch detached tmux sessions and return immediately. Cronenberg will **not** auto-chain followups onto these — they would race the in-progress build. Instead, when cronenberg routes to a tmux-launching metaphor, it launches the build and prints the followup commands ready to copy-paste once the session finishes.\n\n**Flag pass-through:** `--dry-run`, `--no-followups`, `--no-refine`, and `--refine` are cronenberg-only (the latter two control the refinement decision). Everything else (`--backend codex`, `--scope branch`, `--max-iterations`, `--target`, `--interactive`, …) passes through verbatim to the chosen metaphor and applicable followups.\n\n**Refine decision:** Cronenberg analyzes whether to run `/pickle-refine-prd` *before* the build, instead of defaulting to skip. Refinement runs when there's a PRD that hasn't been refined yet AND any of: ≥3 inferred tickets, ≥2 subsystems touched, multi-stage TASK, AC-shape smell (endpoint-enumerated AC bullets), or machine-uncheckable AC prose. Refinement is skipped when there's no PRD, when `prd_refined.md` already exists, when single-file scope, or when `/pickle-pipeline` is the chosen metaphor (it chains refinement internally). The plan output prints the trigger reason so you know why cronenberg made its call.\n\n| | **Cronenberg** | **Persona Routing** |\n|---|---|---|\n| **Trigger** | Explicit `/cronenberg` | Automatic on every prompt |\n| **Decision** | Deterministic matrix | LLM-judged from context |\n| **Output** | Dry-run plan (or chained execution) | Direct skill invocation |\n| **Flag handling** | Pass-through forwarded | Persona-curated |\n| **When to use** | You want auditable, repeatable routing | You want fast, contextual routing |\n\n**Example:**\n\n```bash\n/cronenberg refine then build the auth refactor and clean it up --backend codex\n```\n\nPlan:\n\n```\n1. /pickle-pipeline refine then build the auth refactor and clean it up --backend codex\n   (followups skipped — pipeline chains citadel + anatomy-park + szechuan-sauce internally)\n```\n\n### 🏛️ Council of Ricks — Details\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/council-of-ricks.png\" alt=\"Council of Ricks — Graphite PR Stack Reviewer\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\nIterative Graphite stack reviewer that generates agent-executable directives and auto-publishes review comments to each branch's PR at session end. Every round fans out category- and branch-scoped subagents in parallel via the `Agent` tool — a round review that used to take 30–60 min of serial passes now finishes in one fan-out cycle.\n\n**Requirements:**\n\n- Graphite stack with ≥1 non-trunk branch (`gt log short`)\n- A `CLAUDE.md` with project rules, passing lint, and architectural lint rules in ESLint\n- **GitHub CLI (`gh`)** authed, if you want auto-publish (see note below on why `gh` and not `gt`)\n- **Codex plugin** installed and authed, for the adversarial-review pass to be effective. Install: `/plugin install openai-codex` (or `npm i -g @openai/codex-cli` + `codex setup`). Without it, the Phase C Codex subagent is skipped — the rest of the round still runs, but you lose the adversarial-reviewer perspective.\n\n**Round structure** — each round runs four phases; within a round every category runs concurrently:\n\n- **Phase A — Historical Context** (serial, main agent): `git log` + prior PR comments (`gh pr list/view`) + in-file guidance comments → `historical-brief.md` consumed by Phase B/C subagents\n- **Phase B — Category Team** (parallel fan-out, one `Agent` per category — at stack tier ≥ `l` each category shards per-branch, so `N_branches × N_categories` concurrent subagents):\n  1. Stack Structure — PR sizing, commit hygiene, branch naming, stack ordering\n  2. CLAUDE.md Compliance — project rule verification per branch diff\n  3. Contract Discovery — producer→consumer map, Zod/enum/union coverage\n  4. Cross-Branch Contracts + Combinatorial — 2^N boolean/nullable guard verification\n  5. Test Coverage + Production Migration Safety — persisted-field change detection\n  6. Security — input validation, auth gaps, injection, tenant isolation\n  7. Migration Hygiene (conditional) — CHECK drift, idempotency, schema drift (skipped when no Drizzle journal)\n  8. Szechuan Principles Sweep — P0–P4 scan against the principles reference\n  9. Polish + Trap Door Candidates\n- **Phase C — Branch Team** (parallel fan-out, same message as Phase B):\n  - One `Agent` per non-trunk branch for per-branch Correctness + Data Flow (no checkout needed — pure diff review)\n  - One `Agent` for the Codex sweep (internally sequential because checkout needed; conditional on Codex availability)\n- **Phase D — Synthesis** (serial, main agent): false-positive pre-filter → confidence filter → dedupe (COUNCIL/CODEX merge) → directive + summary append\n\n**Severity × Confidence scoring** — every finding scored `[P0–P4, conf=0–100]`. Confidence `\u003c 80` drops before reporting. **P0 severity escape hatch**: P0 findings at conf ≥ 50 still surface tagged `[NEEDS-VERIFICATION]` (a maybe-real SQL injection is worth an eyeball). Composes with an explicit **false-positives filter** — pre-existing issues, linter/typechecker-catchable errors, author-silenced issues, uncodified style nits, and speculative future-risk are excluded before scoring. Rubric adapted from Anthropic's official `code-review` plugin.\n\n**Approval gate** — `THE_CITADEL_APPROVES` fires only when all four conditions hold: (1) current round ≥ `min_iterations` (the tier-resolved value from Step 8 — see size-tier scaling below), (2) last two `## Round \u003cN\u003e:` headers in the summary both end with `— clean round.`, (3) across those two consecutive clean rounds no unconditional category (Phase A, B1–B6, B8, B9, Phase C per-branch Correctness) was `skipped`, (4) zero P0/P1 findings across COUNCIL + CODEX in those two rounds. Partial rounds (any unconditional skip) break the streak — Phase B7 Migration and Phase C Codex are conditional and may skip without demoting the round.\n\n**Size-tier scaling** — at stack discovery the Council computes `git diff --numstat \u003ctrunk\u003e...\u003ctip\u003e` and scales `min_rounds` to the stack's surface area, because each round surfaces findings that reframe code earlier rounds walked past. Large PRs need more rounds to converge:\n\n| Stack diff LOC | OR | Files touched | Scaled min rounds |\n|---|---|---|---|\n| \u003c 300 | or | \u003c 10 | 2 |\n| 300 – 1,499 | or | 10 – 29 | 3 |\n| 1,500 – 4,999 | or | 30 – 79 | 4 |\n| 5,000 – 9,999 | or | 80 – 149 | 5 |\n| 10,000 – 19,999 | or | 150 – 299 | 6 |\n| ≥ 20,000 | or | ≥ 300 | 7 |\n\nTakes the max of the LOC tier and the files tier — either axis can flag \"big enough.\" `effective_min = max(default_council_min_rounds, scaled_tier)`. `effective_max = max(default_council_max_rounds, effective_min + 2)` to guarantee two rounds of headroom above the floor. CLI flags `--min-iterations` / `--max-iterations` override the scaled values entirely — pass them when you want a quick sanity-check sweep on a big stack, or to force more rounds on a small one.\n\n**Auto-publish at session end** — when the gate fires OR max_iterations is hit, one PR comment per non-trunk branch is posted via `gh pr comment` to the GitHub-backed PR that Graphite manages. Idempotent via `.published/\u003cbranch-slug\u003e` markers. Fails open at every level — `gh` unavailable / no PR / per-branch post failure never blocks the terminal promise. Fallback body files written to `council-comments/\u003cbranch-slug\u003e.md` on every skip class. Opt out with `--no-publish` or `default_council_publish: false`.\n\n**Why `gh` and not `gt` for publishing** — Graphite's CLI has no `comment` subcommand and doesn't expose a comment-posting primitive. `gt` manages stacks (submit, restack, sync, create, branch); review comments are handled by Graphite's web dashboard, which syncs from GitHub. So the only mechanical path to post an actual comment is `gh pr comment` — the comment still shows up on the Graphite stack view because Graphite renders GitHub comments. If Graphite ever ships a `gt comment` or exposes an API token surface, the Council will switch to it.\n\n**Trap Doors** — structural weaknesses (design constraints that will re-break if forgotten) go in the directive's Trap Door section. The Council never writes to repo files; the fixing agent decides whether to add them to `CLAUDE.md`.\n\n**Directive contract (v1.50.0)** — every round writes `council-directive.json` atomically (tmp + rename) as the typed source of truth; `council-directive.md` is free-form human-readable output only, never scraped. Every subagent returns a shape-validated JSON payload (validator at `extension/src/services/council-schema.ts`); schema drift fails loud — the offending category is recorded as `skipped` with the jsonpath of the violation and the round demotes to partial. No more silent parser drift.\n\n### 🌀 Portal Gun — Gene Transfusion\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/portal-gun.png\" alt=\"Portal Gun — gene transfusion for codebases\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003e *\"You see that code over there, Morty? In that other repo? I'm gonna open a portal, reach in, and yank its DNA into OUR dimension.\"*\n\n`/portal-gun` implements [gene transfusion](https://factory.strongdm.ai/techniques/gene-transfusion) — transferring proven coding patterns between codebases using AI agents. Point it at a GitHub URL, local file, npm package, or just describe a pattern, and it extracts the structural DNA, analyzes your target codebase, then generates a transplant PRD with behavioral validation tests and automatic refinement.\n\nThe `--run` flag goes further: after generating the transplant PRD, it launches a convergence loop that executes the migration, scans coverage against the original inventory, generates a delta PRD for any missing items, and re-executes until 100% of the donor pattern has been transplanted.\n\n**v2** added a persistent **pattern library** (cached patterns reused across sessions), **complete file manifests** with anti-truncation enforcement, **multi-language import graph tracing** (TypeScript/JavaScript, Python, Go, Rust), **6-category transplant classification** (direct transplant, type-only, behavioral reference, replace with equivalent, environment prerequisite, not needed), a **PRD validation pass** that verifies every file path against the filesystem with 6 error classes, **post-edit consistency checking** that catches contradictions after scope changes, and **deep target diffs** with line-level modification specs.\n\n```bash\n/portal-gun https://github.com/org/repo/blob/main/src/auth.ts   # Transplant from GitHub\n/portal-gun ../other-project/src/cache.ts                        # Transplant from local file\n/portal-gun --run https://github.com/org/repo/tree/main/src/lib  # Transplant + auto-execute convergence loop\n/portal-gun --save-pattern retry ../donor/retry-logic.ts         # Save pattern to library for reuse\n/portal-gun --depth shallow https://github.com/org/repo           # Summary + structural pattern only\n```\n\n### 🪠 Plumbus — DAG Shaping Loop\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/plumbus.jpg\" alt=\"Plumbus — iterative DAG shaping loop\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003e *\"Everybody has a plumbus in their home, Morty. First they take the dinglebop, smooth it out with a bunch of schleem...\"*\n\nThe same convergence loop applied to a single attractor `.dot` pipeline. Runs the attractor validator as a hard gate, walks every edge, and converges against the `pickle-dot-patterns` rubric (DAG validity, Tier 1 mandatory patterns, anti-patterns). Use it after `/pickle-dot` generates a graph you want hardened before `/attract`.\n\n```bash\n/plumbus pipeline.dot                         # Shape a DAG into a proper plumbus\n/plumbus --dry-run pipeline.dot               # Catalog violations only\n/plumbus --focus \"fan-out safety\" pipeline.dot\n/plumbus --no-validator pipeline.dot          # Pattern-only (no attractor repo)\n```\n\n**When to use which:** Szechuan Sauce asks *\"is this code well-designed?\"* — Anatomy Park asks *\"is this code correct?\"* — Plumbus asks *\"will this DAG actually run without deadlocking?\"*\n\n#### Generative Audit Frames\n\nPlumbus runs six analysis frames during the first iteration Edge Walk (Override 6). Each frame produces findings in `gap_analysis.md` under `## Generative Findings`, using a three-severity model (`pre_verification_severity` / `post_verification_severity` / `rendered_severity`).\n\n| Frame | What it checks |\n|-------|----------------|\n| **Frame 1: Context Key Lifecycle Trace** | Orphan readers/writers, asymmetric writers, multi-writer conflicts |\n| **Frame 2: Success/Failure Symmetry** | State-mutating nodes missing the opposite-outcome unwind |\n| **Frame 3: Edge Condition Exhaustiveness** | Cartesian-product stuck states and non-deterministic routing |\n| **Frame 4: Tool Exit Code Semantics Audit** | Routing-signal vs. build/check tool wiring mismatches |\n| **Frame 5: Loop Convergence Proof Obligation** | SCCs without a reachable finite-exit convergence key |\n| **Frame 6: Counterfactual Outcome Test** | State-mutating tool nodes lacking a direct or transitive guard |\n\n**Kill-switch**: set `PLUMBUS_GENERATIVE_AUDIT=off` to skip Override 6 entirely (no analyzer invocation, no `## Generative Findings` written). Any other value (including absent) runs the audit normally.\n\n### 💎 Death Crystal — Architectural Deepening Lens\n\n\u003e *\"Your finger goes on there, Morty, and you think about the architecture you want. The crystal shows you the path to it.\"*\n\nReads code through John Ousterhout's *A Philosophy of Software Design* and Ben Pocock's interface-shape essays, then surfaces **shallow Modules** — Modules whose Interface complexity rivals their Implementation — and proposes **deeper** alternatives. Sibling to Szechuan Sauce (*is it well-designed?*) and Anatomy Park (*is it correct?*): Death Crystal asks *\"is this Interface deeper than its Implementation, or just hiding the mess?\"*\n\n| Command | Description |\n|---|---|\n| `/death-crystal --deepen` | Architectural deepening lens — scan the target for shallow Modules, render an HTML report in `${SESSION_ROOT}/death-crystal/`, and rank deeper consolidations by depth deficit |\n| `/death-crystal --interface \u003cmodule\u003e` | Pocock-style interface-shape analysis — run parallel design Mortys for `\u003cmodule\u003e`, then synthesize one recommended Interface from the caller evidence |\n\n```bash\n/death-crystal --deepen                       # Surface shallow modules across the target\n/death-crystal --interface src/services/audit # Minimal sufficient interface for one module\n```\n\nBoth modes honor `--backend claude|codex`. On `--backend codex`, `/death-crystal --interface \u003cmodule\u003e` falls back to sequential roleplay instead of the default team-based parallel Morty launch.\n\n---\n\n## 🚀 Command \u0026 Flag Reference\n\nEvery slash command and flag — including command-scoped families and the `†`/Codex/Teams notes — lives in **[COMMANDS.md](COMMANDS.md)**.\n\n---\n\n\u003e **Under the hood:** See [internals.md](internals.md) for the 8-phase ticket lifecycle, manager/worker model, stop-hook loop, context clearing, state schema, settings reference, and every internal system that makes this thing run.\n\n---\n\n## 📊 Metrics\n\n```bash\n/pickle-metrics                    # Last 7 days, daily breakdown\n/pickle-metrics --days 30          # Last 30 days\n/pickle-metrics --weekly           # Weekly buckets (defaults to 28 days)\n/pickle-metrics --json             # Machine-readable JSON output\n```\n\n### Skip-flag budget dashboard\n\n`/pickle-metrics` also reports a **skip-flag budget** view (W5c governance dashboard). It counts how often each quality gate's skip-flag is used over the window — keyed by `{source, reason}` — from the existing `gate_skipped`, `readiness_skipped`, and `skip_flag_legacy_used` activity events. Each gate has a stated recurrence budget (`SKIP_FLAG_BUDGETS` in `extension/src/services/metrics-utils.ts`); a gate whose skip-flag-use rate exceeds its budget is flagged as a **removal candidate**.\n\nThis is the data behind the *subtract-before-add* governance rule (see `extension/CLAUDE.md`): a guard that false-blocks beyond its budget should be loosened or removed, never handed a second escape hatch. The `--json` output includes the report under the `skip_flag_budget` key. The lint `extension/scripts/audit-skip-flag-unification.sh` fails the build if a new non-unified skip-flag is added.\n\n---\n\n## 🛠️ Troubleshooting\n\nSee [docs/judge-spawn-troubleshooting.md](docs/judge-spawn-troubleshooting.md) for judge backend errors, ETIMEDOUT, sticky fallback semantics, and exit-reason mapping.\n\n---\n\n## 📋 Requirements\n\n- **Node.js** 18+\n- **Claude Code** CLI (`claude`) — v2.1.49+\n- **jq** (for `install.sh`, `uninstall.sh`, `uninstall-hooks.sh`)\n- **rsync** (for `install.sh`)\n- **tmux** *(optional — for `/pickle-tmux`, `/szechuan-sauce`, `/anatomy-park`, `/pickle-pipeline`)*\n- **Zellij** \u003e= 0.40.0 *(optional — for `/pickle-zellij`)*\n- **Graphite CLI** (`gt`) *(optional — for `/council-of-ricks`)*\n- **GitHub CLI** (`gh`) authed *(optional — required only for `/council-of-ricks` auto-publish; the review itself works without it)*\n- **Codex plugin** *(optional — required for `--backend codex` on `/pickle-tmux`, `/pickle-microverse`, `/anatomy-park`, `/szechuan-sauce`, and for `/council-of-ricks` Phase C adversarial review. Without it, `--backend codex` spawns fail and Council's Phase C is skipped — Claude-backed runs and non-Codex Council rounds are unaffected. Install: `/plugin install openai-codex` or `npm i -g @openai/codex-cli` + `codex setup`)*\n- macOS or Linux (Windows not supported)\n\n---\n\n## 🏆 Credits\n\nThis port stands on the shoulders of giants. *Wubba Lubba Dub Dub.*\n\n| | |\n|---|---|\n| 🥒 **[galz10](https://github.com/galz10)** | Creator of the original [Pickle Rick Gemini CLI extension](https://github.com/galz10/pickle-rick-extension) — the autonomous lifecycle, manager/worker model, hook loop, and all the skill content that makes this thing work. This project is a faithful port of their work. |\n| 🧠 **[Geoffrey Huntley](https://ghuntley.com)** | Inventor of the [\"Ralph Wiggum\" technique](https://ghuntley.com/ralph/) — the foundational insight that \"Ralph is a Bash loop\": feed an AI agent a prompt, block its exit, repeat until done. Everything here traces back to that idea. |\n| 🔬 **[Andrej Karpathy](https://github.com/karpathy)** | [AutoResearch](https://github.com/karpathy/autoresearch) — agentic-research scaffolding whose ideas inform the PRD-driven decomposition + multi-analyst refinement loop. |\n| 🔧 **[AsyncFuncAI/ralph-wiggum-extension](https://github.com/AsyncFuncAI/ralph-wiggum-extension)** | Reference implementation of the Ralph Wiggum loop that inspired the Pickle Rick extension. |\n| ✍️ **[dexhorthy](https://github.com/dexhorthy)** | Context engineering and prompt techniques used throughout. |\n| 📺 **Rick and Morty** | For *Pickle Riiiick!* 🥒 |\n\n---\n\n## 🥒 License\n\nApache 2.0.\n\n---\n\n*\"I'm not a tool, Morty. I'm a **methodology**.\"* 🥒\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregorydickson%2Fpickle-rick-claude","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgregorydickson%2Fpickle-rick-claude","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregorydickson%2Fpickle-rick-claude/lists"}