@jmylchreest/aide-plugin 0.0.47 → 0.0.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmylchreest/aide-plugin",
-  "version": "0.0.47",
+  "version": "0.0.48",
   "description": "aide plugin for OpenCode — multi-agent orchestration, memory, skills, and persistence",
   "type": "module",
   "main": "./src/opencode/index.ts",

package/skills/autopilot/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: autopilot
+description: Full autonomous execution - keeps working until all tasks are verified complete
+triggers:
+  - autopilot
+  - full auto
+  - autonomous
+  - keep going
+  - finish everything
+  - run until complete
+---
+
+# Autopilot Mode
+
+**Recommended model tier:** smart (opus) - this mode handles complex multi-step tasks
+
+Full autonomous execution mode. The agent keeps working until all tasks in the todo list are verified complete. No stopping early, no partial results.
+
+## Activation
+
+Type naturally:
+
+```
+autopilot build me a web app
+autopilot fix all failing tests
+autopilot refactor the auth module
+```
+
+Or explicitly set the mode:
+
+```bash
+aide state set mode autopilot
+```
+
+## How It Works
+
+When autopilot mode is active:
+
+1. The persistence hook intercepts stop signals
+2. If incomplete tasks exist in the todo list, the agent is re-prompted to continue
+3. The agent keeps working through its task list
+4. Auto-releases when ALL tasks are complete (terminal state)
+5. Safety cap: releases after 20 iterations even if tasks remain
+
+### Platform Behavior
+
+| Platform        | Mechanism                                                          |
+| --------------- | ------------------------------------------------------------------ |
+| **Claude Code** | Stop-blocking — prevents the AI from ending the conversation early |
+| **OpenCode**    | Re-prompting — `session.prompt()` is called on idle to keep going  |
+
+### Task Tracking
+
+Autopilot relies on the todo list to determine completeness:
+
+- **Has incomplete tasks** → Block stop, continue working
+- **All tasks complete** → Auto-release, allow stop
+- **No tasks exist** → Generic reinforcement (verify your work)
+
+## When to Use
+
+Autopilot mode is ideal for:
+
+- **Multi-step implementations** — "autopilot implement the user dashboard"
+- **Fixing all test failures** — "autopilot fix all failing tests"
+- **Complete refactors** — "autopilot refactor all error handling to use Result types"
+- **Migration tasks** — "autopilot migrate all components to the new API"
+- **Build fixes** — "autopilot make the build pass"
+
+## When NOT to Use
+
+Avoid autopilot for:
+
+- **Exploratory tasks** — "investigate why X happens" (no clear completion criteria)
+- **Design work** — Use the `design` skill instead (needs human input)
+- **Tasks requiring human judgment** — Autopilot continues based on automated checks
+- **Parallel work** — Use `swarm` mode instead for decomposed parallel stories
+
+## Combining with Skills
+
+Autopilot works well with any skill:
+
+```
+autopilot fix the build errors       # autopilot + build-fix behavior
+autopilot make all tests pass        # autopilot + implement behavior
+autopilot debug why login fails      # autopilot + debug behavior
+```
+
+## Deactivation
+
+To stop autopilot mode early:
+
+```bash
+aide state set mode ""
+```
+
+Or type "stop" — the keyword detector clears the active mode.
+
+## Instructions
+
+When autopilot mode is activated:
+
+1. **Create a comprehensive todo list** — Break the task into specific, actionable items
+2. **Work through items sequentially** — Mark each as `in_progress` then `completed`
+3. **Verify each step** — Run tests, check builds, confirm behavior
+4. **Do not stop until all items are complete** — The persistence hook will block premature stops
+5. **If stuck on an item after 3 attempts**, record a blocker memory and move to the next item:
+   ```bash
+   ./.aide/bin/aide memory add --category=blocker --tags=project:<name>,session:<id>,source:discovered "Blocked on <task>: <reason>"
+   ```
+
+**Binary location:** The aide binary is at `.aide/bin/aide`. If it's on your `$PATH`, you can use `aide` directly.

package/skills/debug/SKILL.md

@@ -159,6 +159,14 @@ npm test
 | Root cause is in dependency | Check for updates, file issue, implement workaround  |
 | Bug is in async code        | Add proper await, check Promise chains               |
 
+**When abandoning an approach:** If you try a fix direction and abandon it (e.g., revert because it causes regressions), record it as an abandoned approach so future sessions don't repeat it:
+
+```bash
+./.aide/bin/aide memory add --category=abandoned \
+  --tags=reason:<why>,approach:<what>,project:<name>,session:<id>,source:discovered \
+  "ABANDONED: <what was tried>. REASON: <why>. ALTERNATIVE: <new direction>. CONTEXT: <details>"
+```
+
 ## MCP Tools
 
 - `mcp__plugin_aide_aide__code_outline` - **Start here.** Get collapsed file skeleton to understand structure before reading
@@ -207,3 +215,12 @@ npm test
 - One fix at a time - don't bundle unrelated changes
 - Remove temporary logging before committing
 - Consider if the bug could occur elsewhere
+
+## Memory Hygiene
+
+When storing memories from this skill (abandoned approaches, blockers), always:
+
+1. **Include `source:` tag** — Use `source:discovered` for things you found, `source:inferred` for deductions
+2. **Include scope tags** — Add `project:<name>,session:<id>` (get project name from git remote or directory; session ID from `$AIDE_SESSION_ID` or `$CLAUDE_SESSION_ID`)
+3. **Verify codebase claims** before storing — If a memory references a file, function, or path, confirm it exists first. See the `memorise` skill for the full verification workflow.
+4. **Never use `scope:global`** unless storing a user preference

package/skills/design/SKILL.md

@@ -170,7 +170,7 @@ List specific, testable criteria for the TEST stage:
 
 1. List specific ambiguities
 2. State assumptions you're making
-3. Record assumptions: `./.aide/bin/aide memory add --category=decision "Assumed X because Y"`
+3. Record assumptions: `./.aide/bin/aide memory add --category=decision --tags=project:<name>,session:${AIDE_SESSION_ID},source:inferred "Assumed X because Y"`
 4. Proceed with reasonable defaults
 
 ### Conflicting Patterns Found
@@ -198,6 +198,15 @@ Before completing design:
 - [ ] Files to modify are listed
 - [ ] Dependencies are identified
 
+## Memory Hygiene
+
+When storing memories from this skill (assumptions, decisions, discoveries), always:
+
+1. **Include `source:` tag** — Use `source:inferred` for assumptions, `source:discovered` for findings during exploration
+2. **Include scope tags** — Add `project:<name>,session:<id>` (get project name from git remote or directory; session ID from `$AIDE_SESSION_ID` or `$CLAUDE_SESSION_ID`)
+3. **Verify codebase claims** before storing — If a memory references a file, function, or path, confirm it exists first. See the `memorise` skill for the full verification workflow.
+4. **Never use `scope:global`** unless storing a user preference
+
 ## Completion
 
 When design is complete:

package/skills/forget/SKILL.md

@@ -92,8 +92,8 @@ If the memory is being superseded (not just deleted), add a new corrected memory
 # 1. Forget the old memory
 ./.aide/bin/aide memory tag <OLD_ID> --add=forget
 
-# 2. Add the corrected memory (NO forget tag)
-./.aide/bin/aide memory add --category=<category> --tags=<relevant,tags> "<corrected content>"
+# 2. Add the corrected memory (NO forget tag) — include scope + provenance tags
+./.aide/bin/aide memory add --category=<category> --tags=<relevant,tags>,project:<name>,session:${AIDE_SESSION_ID},source:discovered "<corrected content>"
 ```
 
 ### Step 5: Verify
@@ -184,7 +184,7 @@ To clear ALL memories (destructive, requires explicit user request):
 ./.aide/bin/aide memory tag <OLD_ID> --add=forget
 
 # 3. Add the corrected one
-./.aide/bin/aide memory add --category=decision --tags=auth,sessions,project:myapp "Auth strategy changed from JWT to server-side sessions with Redis store"
+./.aide/bin/aide memory add --category=decision --tags=auth,sessions,project:myapp,session:${AIDE_SESSION_ID},source:discovered "Auth strategy changed from JWT to server-side sessions with Redis store"
 ```
 
 ### User says "recover that forgotten memory about testing"
@@ -211,6 +211,15 @@ If `aide memory tag` fails:
    ```
 3. **Database locked** - Another process may hold the lock. Wait and retry, or ensure the aide daemon is running (CLI routes through gRPC when daemon is active).
 
+## Memory Hygiene
+
+When adding replacement memories (Step 4 above), always:
+
+1. **Include `source:` tag** — Use `source:discovered` for corrected facts, `source:user` if the user provided the correction
+2. **Include scope tags** — Add `project:<name>,session:<id>` (get project name from git remote or directory; session ID from `$AIDE_SESSION_ID` or `$CLAUDE_SESSION_ID`)
+3. **Verify codebase claims** before storing — If a replacement memory references a file, function, or path, confirm it exists first. See the `memorise` skill for the full verification workflow.
+4. **Never use `scope:global`** unless storing a user preference
+
 ## Verification
 
 After forgetting a memory, verify:

package/skills/implement/SKILL.md

@@ -196,9 +196,15 @@ func (s *UserService) CreateUser(ctx context.Context, input CreateUserInput) (*U
 3. Check design decisions - is implementation matching spec?
 4. Record blocker:
    ```bash
-   ./.aide/bin/aide memory add --category=blocker "Cannot pass test X: <reason>"
+   ./.aide/bin/aide memory add --category=blocker --tags=project:<name>,session:<id>,source:discovered "Cannot pass test X: <reason>"
    ```
-5. If stuck after 3 attempts, ask for help
+5. **If you abandon the approach**, record it so future sessions don't repeat it:
+   ```bash
+   ./.aide/bin/aide memory add --category=abandoned \
+     --tags=reason:<why>,approach:<what>,project:<name>,session:<id>,source:discovered \
+     "ABANDONED: <what was tried>. REASON: <why>. ALTERNATIVE: <new direction>. CONTEXT: <details>"
+   ```
+6. If stuck after 3 attempts, ask for help
 
 ### Build Fails
 
@@ -214,7 +220,7 @@ func (s *UserService) CreateUser(ctx context.Context, input CreateUserInput) (*U
 2. Don't refactor during implement stage
 3. Note concerns for future:
    ```bash
-   ./.aide/bin/aide memory add --category=issue "Implementation of X could be improved: <how>"
+   ./.aide/bin/aide memory add --category=issue --tags=project:<name>,session:<id>,source:discovered "Implementation of X could be improved: <how>"
    ```
 4. Proceed - refactoring is a separate concern
 
@@ -243,6 +249,15 @@ go test -v ./pkg/feature/... && go build ./...
 
 Output: "Implementation complete. All tests passing. Ready for VERIFY stage."
 
+## Memory Hygiene
+
+When storing memories from this skill (blockers, issues, abandoned approaches), always:
+
+1. **Include `source:` tag** — Use `source:discovered` for things you found, `source:inferred` for deductions
+2. **Include scope tags** — Add `project:<name>,session:<id>` (get project name from git remote or directory; session ID from `$AIDE_SESSION_ID` or `$CLAUDE_SESSION_ID`)
+3. **Verify codebase claims** before storing — If a memory references a file, function, or path, confirm it exists first. See the `memorise` skill for the full verification workflow.
+4. **Never use `scope:global`** unless storing a user preference
+
 ## Integration with SDLC Pipeline
 
 This skill is designed for the DEV stage:

package/skills/memorise/SKILL.md

@@ -38,6 +38,7 @@ Use the `./.aide/bin/aide memory add` CLI command via Bash:
 - `session` - Summary of a work session
 - `pattern` - A reusable approach or pattern identified
 - `gotcha` - A pitfall or issue to avoid in future
+- `abandoned` - An approach that was tried and abandoned (see [Abandoned Approaches](#abandoned-approaches) below)
 
 ## When to Use
 
@@ -87,8 +88,8 @@ When the user invokes `/aide:memorise <something>`:
 2. **Verify factual claims before storing** (see [Verification Before Storage](#verification-before-storage-anti-poison) below)
 3. Determine the scope:
    - **User preference** (colour, style, etc.) → add `scope:global`
-   - **Project-specific learning** → add `project:<project-name>,session:${CLAUDE_SESSION_ID:0:8}`
-   - **Session summary** → add `project:<project-name>,session:${CLAUDE_SESSION_ID:0:8}`
+   - **Project-specific learning** → add `project:<project-name>,session:${AIDE_SESSION_ID}`
+   - **Session summary** → add `project:<project-name>,session:${AIDE_SESSION_ID}`
 4. Choose appropriate category and descriptive tags
 5. **Add provenance tags** (see [Provenance Tags](#provenance-tags) below)
 6. Format the content concisely but completely
@@ -215,7 +216,51 @@ Use scope tags to control when memories are injected:
 - **Project learnings** (API patterns, testing approach): Add `project:<name>,session:<id>`
 - **Session summaries**: Add `project:<name>,session:<id>` with `category=session`
 
-Get the project name from the git remote or directory name. Session ID is available as `$CLAUDE_SESSION_ID` (use first 8 chars).
+Get the project name from the git remote or directory name. Session ID is available as `$AIDE_SESSION_ID` (set by aide hooks) or `$CLAUDE_SESSION_ID` (Claude Code native).
+
+## Abandoned Approaches
+
+When an approach is tried and abandoned during implementation, debugging, or design, record it as an `abandoned` memory. This prevents future sessions from repeating the same failed approach.
+
+### When to Record
+
+- You try an implementation approach and it fails or is rejected
+- You explore a design direction and discover it won't work
+- The user explicitly abandons a direction (e.g., "let's not do it that way")
+- A dependency or library is evaluated and rejected
+
+### Content Template
+
+Use this structured format:
+
+```
+ABANDONED: <what was tried>
+REASON: <why it was abandoned>
+ALTERNATIVE: <what was done instead, or "none yet">
+CONTEXT: <any useful context for future reference>
+```
+
+### Required Tags
+
+| Tag                 | Purpose                           | Example               |
+| ------------------- | --------------------------------- | --------------------- |
+| `reason:<why>`      | Machine-searchable abandon reason | `reason:performance`  |
+| `approach:<what>`   | What was tried                    | `approach:sqlite-fts` |
+| `project:<name>`    | Project scope                     | `project:aide`        |
+| `source:discovered` | Provenance (always discovered)    | `source:discovered`   |
+| `session:<id>`      | Session context                   | `session:abc12345`    |
+
+### Example
+
+```bash
+./.aide/bin/aide memory add --category=abandoned \
+  --tags=reason:performance,approach:sqlite-fts,project:aide,session:abc12345,source:discovered \
+  "ABANDONED: Using SQLite FTS5 for memory search. REASON: go-sqlite3 requires CGO which breaks cross-compilation. ALTERNATIVE: Bleve full-text search (pure Go). CONTEXT: FTS5 was faster in benchmarks but CGO dependency was a non-starter for the release pipeline."
+```
+
+### Decision Interaction
+
+If an abandoned approach contradicts or supersedes an existing Decision (check with `mcp__plugin_aide_aide__decision_list`), also update the decision to reflect the change. For example, if a decision said "use SQLite FTS" and you abandoned that approach, update the decision with the new direction.
 
 ## For Swarm/Multi-Agent
 

package/skills/swarm/SKILL.md

@@ -207,7 +207,7 @@ Use native Claude Code task tools to track your progress:
 **Shared state (MCP + CLI):**
 - Check decisions: \`mcp__plugin_aide_aide__decision_get\` (MCP read)
 - Record decisions: \`./.aide/bin/aide decision set <topic> "<decision>"\` (CLI write)
-- Share discoveries: \`./.aide/bin/aide memory add --category=discovery "<finding>"\` (CLI write)
+- Share discoveries: \`./.aide/bin/aide memory add --category=discovery --tags=project:<name>,session:\${AIDE_SESSION_ID},source:discovered "<finding>"\` (CLI write)
 
 **Binary location:** The aide binary is at \`.aide/bin/aide\`. If it's on your \`$PATH\`, you can use \`aide\` directly.
 
@@ -366,7 +366,7 @@ activeForm: "Documenting [feature]"
 
 - Check existing decisions: `mcp__plugin_aide_aide__decision_get` (MCP read)
 - Record new decisions: `./.aide/bin/aide decision set <topic> "<decision>"` (CLI write)
-- Share discoveries: `./.aide/bin/aide memory add --category=discovery "<finding>"` (CLI write)
+- Share discoveries: `./.aide/bin/aide memory add --category=discovery --tags=project:<name>,session:${AIDE_SESSION_ID},source:discovered "<finding>"` (CLI write)
 
 ## VERIFY Failure Handling
 
@@ -429,9 +429,20 @@ message_ack: message_id=42, agent_id="agent-auth"
 **Memory** (shared discoveries):
 
 ```bash
-./.aide/bin/aide memory add --category=discovery "User model needs email validation"
+./.aide/bin/aide memory add --category=discovery --tags=project:<name>,session:${AIDE_SESSION_ID},source:discovered "User model needs email validation"
 ```
 
+## Memory Hygiene
+
+When any agent stores memories (discoveries, blockers, session summaries), always:
+
+1. **Include `source:` tag** — Use `source:discovered` for findings, `source:inferred` for deductions
+2. **Include scope tags** — Add `project:<name>,session:<id>` (get project name from git remote or directory; session ID from `$AIDE_SESSION_ID` or `$CLAUDE_SESSION_ID`)
+3. **Verify codebase claims** before storing — If a memory references a file, function, or path, confirm it exists first. See the `memorise` skill for the full verification workflow.
+4. **Never use `scope:global`** unless storing a user preference
+
+This applies to all `memory add` commands in agent prompts, coordination examples, and the orchestrator memory section above.
+
 ## OpenCode Mode
 
 OpenCode has native `todowrite`/`todoread` for per-agent progress tracking, and a `task` tool for spawning subagents. However, OpenCode's todos are **session-private** — they are NOT shared across agents. For multi-agent coordination, use **aide tasks** (MCP tools) as the shared task system.
@@ -514,7 +525,7 @@ message_ack: message_id=42, agent_id="agent-auth"
 # Decisions and discoveries — shared knowledge
 mcp__plugin_aide_aide__decision_get with topic="auth-strategy"
 ./.aide/bin/aide decision set "auth-strategy" "JWT with refresh tokens"
-./.aide/bin/aide memory add --category=discovery "User model needs email validation"
+./.aide/bin/aide memory add --category=discovery --tags=project:<name>,session:${AIDE_SESSION_ID},source:discovered "User model needs email validation"
 ```
 
 ## Completion (MANDATORY STEPS)
@@ -574,7 +585,7 @@ Only after successful merge, record the swarm session (see Orchestrator Memory b
 After swarm completes, record the session using the CLI:
 
 ```bash
-./.aide/bin/aide memory add --category=session --tags=swarm,sdlc,session:${CLAUDE_SESSION_ID:0:8} "## Swarm: [Brief Description]
+./.aide/bin/aide memory add --category=session --tags=swarm,sdlc,project:<name>,session:${AIDE_SESSION_ID},source:discovered "## Swarm: [Brief Description]
 
 ### Stories Completed
 - Story A: [outcome]

package/src/core/partial-memory.ts

@@ -105,7 +105,7 @@ export function buildPartialTags(
 ): string[] {
   const tags = [
     "partial",
-    `session:${sessionId.slice(0, 12)}`,
+    `session:${sessionId}`,
     `tool:${info.toolName.toLowerCase()}`,
   ];
   if (info.filePath) {
@@ -173,7 +173,7 @@ function querySessionPartials<T>(
   label: string,
 ): T[] {
   try {
-    const sessionTag = `session:${sessionId.slice(0, 12)}`;
+    const sessionTag = `session:${sessionId}`;
 
     const output = execFileSync(
       binary,

package/src/core/session-init.ts

@@ -464,7 +464,6 @@ export function buildWelcomeContext(
   lines.push("");
   lines.push("- **autopilot**: Full autonomous execution");
   lines.push("- **eco**: Token-efficient mode");
-  lines.push("- **ralph**: Persistence until verified complete");
   lines.push("- **swarm**: Parallel agents with shared memory");
   lines.push("- **plan**: Planning interview workflow");
   lines.push("");

package/src/core/session-summary-logic.ts

@@ -224,7 +224,7 @@ export function storeSessionSummary(
   summary: string,
 ): boolean {
   try {
-    const tags = `session-summary,session:${sessionId.slice(0, 12)}`;
+    const tags = `session-summary,session:${sessionId}`;
 
     execFileSync(
       binary,

package/src/core/tool-enforcement.ts

@@ -81,7 +81,6 @@ export function buildReminder(mode: string | null): string | null {
   if (!mode) return null;
 
   const reminders: Record<string, string> = {
-    ralph: `[aide:ralph] Persistence active. Verify work is complete before stopping.`,
     autopilot: `[aide:autopilot] Autonomous mode. Continue until all tasks verified.`,
     eco: `[aide:eco] Token-efficient mode. Minimize context, use fast models.`,
     swarm: `[aide:swarm] Swarm active. Use aide-memory for coordination.`,

package/src/core/types.ts

@@ -144,7 +144,7 @@ export interface ToolUseInfo {
 // Persistence
 // =============================================================================
 
-export const PERSISTENCE_MODES = ["ralph", "autopilot"] as const;
+export const PERSISTENCE_MODES = ["autopilot"] as const;
 export type PersistenceMode = (typeof PERSISTENCE_MODES)[number];
 export const MAX_PERSISTENCE_ITERATIONS = 20;
 

package/src/lib/hud.ts

@@ -84,7 +84,6 @@ const DEFAULT_HUD_CONFIG: HudConfig = {
 const ICONS = {
   mode: {
     autopilot: "🚀",
-    ralph: "🔄",
     eco: "💚",
     swarm: "🐝",
     plan: "📋",

package/src/opencode/hooks.ts

@@ -509,7 +509,7 @@ async function handleSessionIdle(
 ): Promise<void> {
   const sessionId = extractSessionId(event);
 
-  // Check persistence: if ralph/autopilot mode is active, re-prompt the session
+  // Check persistence: if autopilot mode is active, re-prompt the session
   if (state.binary) {
     try {
       const persistResult = checkPersistence(
@@ -875,7 +875,7 @@ function createCompactionHandler(
 
         if (summary) {
           // Tag as partial so the session-end summary supersedes it
-          const tags = `partial,session-summary,session:${input.sessionID.slice(0, 8)}`;
+          const tags = `partial,session-summary,session:${input.sessionID}`;
           execFileSync(
             state.binary,
             ["memory", "add", "--category=session", `--tags=${tags}`, summary],

package/skills/ralph/SKILL.md

@@ -1,515 +0,0 @@
----
-name: ralph
-description: Ralph Wiggum methodology - iterative implementation with test-driven backpressure
-triggers:
-  - ralph
-  - persist
-  - persistence
-  - don't stop
-  - dont stop
-  - until done
-  - must complete
-  - relentless
-  - ralph wiggum
----
-
-# Ralph Mode (Ralph Wiggum Methodology)
-
-**Recommended model tier:** smart (opus) - this skill requires complex reasoning
-
-You are now in **Ralph Wiggum mode** - an iterative development methodology that uses test-driven backpressure and aide-based state persistence.
-
-## Core Principles
-
-1. **Planning vs Building**: Separate phases with distinct behaviors
-2. **Backpressure via Tests**: Cannot proceed until tests pass
-3. **Task Atomicity**: One task per iteration
-4. **Don't Assume**: Verify gaps exist before implementing
-5. **aide-Based Persistence**: Tasks, state, and decisions stored in aide (not files)
-6. **Swarm Compatible**: Multiple agents can work in parallel
-
----
-
-## State Management
-
-All state is managed through aide. Use MCP tools for reads, CLI for writes:
-
-### Task System Roles
-
-| System                      | Role                                                    | How                                                                   |
-| --------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------- |
-| **aide tasks** (MCP or CLI) | Durable task backlog, claiming, persistence enforcement | `task_create`/`task_claim`/`task_complete` (MCP) or `aide task` (CLI) |
-| **Native todowrite**        | Personal progress tracking within current iteration     | `todowrite` tool — tracks sub-steps of current task                   |
-
-aide tasks are the source of truth for ralph — they survive session restarts and are checked by persistence hooks to block premature stopping. Use native `todowrite` for your own step-by-step checklist within each task iteration.
-
-### Reads (MCP Tools)
-
-| Tool                                   | Purpose              |
-| -------------------------------------- | -------------------- |
-| `mcp__plugin_aide_aide__state_get`     | Get phase, objective |
-| `mcp__plugin_aide_aide__state_list`    | List all state       |
-| `mcp__plugin_aide_aide__decision_get`  | Get decisions        |
-| `mcp__plugin_aide_aide__decision_list` | List all decisions   |
-| `mcp__plugin_aide_aide__memory_search` | Search discoveries   |
-| `task_list`                            | List aide tasks      |
-| `task_get`                             | Get task by ID       |
-
-### Writes (CLI via Bash or MCP)
-
-```bash
-# Phase tracking
-./.aide/bin/aide state set ralph:phase planning   # or "building"
-
-# Task management — use aide tasks (persistent, claimable)
-# Via MCP: task_create, task_claim, task_complete
-# Via CLI: ./.aide/bin/aide task create/claim/complete
-
-# Decisions
-./.aide/bin/aide decision set <topic> "<decision>" --rationale="<why>"
-
-# Gap analysis / discoveries
-./.aide/bin/aide memory add --category=discovery --tags=ralph "Gap found: <description>"
-```
-
-**Binary location:** The aide binary is at `.aide/bin/aide`. If it's on your `$PATH`, you can use `aide` directly.
-
----
-
-## Phase 1: Planning Mode
-
-When starting a new task or when `./.aide/bin/aide state get ralph:phase` is empty/planning:
-
-### Step 1: Set Phase
-
-```bash
-./.aide/bin/aide state set ralph:phase planning
-./.aide/bin/aide state set ralph:objective "<what we're building>"
-```
-
-### Step 2: Gap Analysis (Don't Assume!)
-
-**CRITICAL**: Before assuming anything needs implementation, SEARCH THE CODE:
-
-```bash
-# Search for existing implementations
-rg "functionName\|ClassName\|feature" --type ts
-
-# Check existing tests
-rg "describe.*feature\|it.*should" --type ts
-```
-
-Record findings:
-
-```bash
-./.aide/bin/aide memory add --category=discovery --tags=ralph,gap-analysis "Searched for X: <results>"
-```
-
-Only after confirming gaps exist, proceed to task creation.
-
-### Step 3: Create Tasks
-
-Create atomic, testable tasks:
-
-```bash
-./.aide/bin/aide task create "Implement user model" --tags=ralph,task-1
-./.aide/bin/aide task create "Add validation to user model" --tags=ralph,task-2
-./.aide/bin/aide task create "Write user model tests" --tags=ralph,task-3
-```
-
-Each task should be:
-
-- Small enough to complete in one iteration
-- Independently testable
-- Clearly defined acceptance criteria
-
-### Step 4: Record Key Decisions
-
-```bash
-./.aide/bin/aide decision set ralph:test-framework "vitest" --rationale="Already configured in project"
-./.aide/bin/aide decision set ralph:approach "<approach>" --rationale="<why>"
-```
-
-### Step 5: Exit Planning
-
-```bash
-./.aide/bin/aide state set ralph:phase building
-```
-
-Report the plan:
-
-- List tasks: `./.aide/bin/aide task list`
-- List decisions: `./.aide/bin/aide decision list`
-
-**DO NOT implement during planning phase.**
-
----
-
-## Phase 2: Building Mode
-
-When `./.aide/bin/aide state get ralph:phase` returns "building":
-
-### Iteration Loop
-
-Each iteration follows this exact sequence:
-
-#### 1. Load Context
-
-```bash
-# Check current phase and objective
-./.aide/bin/aide state get ralph:phase
-./.aide/bin/aide state get ralph:objective
-
-# List tasks to find next one
-./.aide/bin/aide task list
-
-# Check existing decisions
-./.aide/bin/aide decision list
-```
-
-#### 2. Select Next Task
-
-Find the first pending task:
-
-```bash
-./.aide/bin/aide task list  # Look for [pending] status
-```
-
-Claim it:
-
-```bash
-./.aide/bin/aide task claim <task-id> --agent=ralph
-```
-
-#### 3. Verify Gap Still Exists (Don't Assume!)
-
-Before implementing, RE-VERIFY:
-
-```bash
-# Search again - someone may have implemented it
-rg "featureName" --type ts
-```
-
-If gap no longer exists:
-
-```bash
-./.aide/bin/aide task complete <task-id>
-# Proceed to next task
-```
-
-#### 4. Write Tests First
-
-Create or update test file with failing tests:
-
-```bash
-# Run tests - they MUST fail initially
-npm test -- path/to/test.test.ts
-```
-
-If tests pass without implementation, the gap analysis was wrong - complete the task and move on.
-
-#### 5. Implement Solution
-
-Write minimal code to make tests pass.
-
-#### 6. Backpressure Checkpoint (REQUIRED)
-
-**You CANNOT proceed until this passes:**
-
-```bash
-npm test -- path/to/test.test.ts
-```
-
-**BLOCKING RULE**: If tests fail, you MUST:
-
-1. Analyze the failure
-2. Fix the issue
-3. Re-run tests
-4. Repeat until passing
-
-**DO NOT skip failing tests. DO NOT proceed with failing tests.**
-
-#### 7. Complete Task
-
-```bash
-./.aide/bin/aide task complete <task-id>
-```
-
-#### 8. Atomic Commit
-
-```bash
-git add -A
-git commit -m "feat: <task description> - tests passing"
-```
-
-#### 9. Check Completion
-
-```bash
-./.aide/bin/aide task list
-```
-
-If more pending tasks: continue to next iteration (step 2)
-If all complete: run full verification
-
----
-
-## Failure Handling
-
-### Test Failures
-
-When tests fail during backpressure checkpoint:
-
-1. **DO NOT** proceed to next task
-2. **DO NOT** skip the failing test
-3. **DO** analyze the error message
-4. **DO** fix and re-run until passing
-
-Record blockers:
-
-```bash
-./.aide/bin/aide memory add --category=blocker --tags=ralph "Test failure: <description>"
-```
-
-### Stuck Conditions
-
-If blocked for more than 3 attempts:
-
-```bash
-./.aide/bin/aide memory add --category=blocker --tags=ralph,needs-help "Stuck on: <description>"
-```
-
-Then ask user for guidance. **DO NOT** proceed without resolution.
-
----
-
-## Full Verification Protocol
-
-Before claiming completion, ALL must pass:
-
-```bash
-# 1. All tasks complete
-./.aide/bin/aide task list  # Should show all [done]
-
-# 2. All tests
-npm test
-
-# 3. Build
-npm run build
-
-# 4. Lint
-npm run lint
-```
-
-Only proceed to completion when ALL verification passes.
-
----
-
-## Completion
-
-When all tasks complete and verification passes:
-
-### Update State
-
-```bash
-./.aide/bin/aide state set ralph:phase complete
-./.aide/bin/aide state set ralph:result "success"
-```
-
-### Record Session
-
-```bash
-./.aide/bin/aide memory add --category=session --tags=ralph,implementation "
-## <Feature Name> Complete
-
-Implemented using Ralph Wiggum methodology.
-
-### Tasks Completed
-- Task 1: <description>
-- Task 2: <description>
-
-### Verification
-- Tests: passing
-- Build: passing
-- Lint: clean
-
-### Key Decisions
-- <decision>: <rationale>
-"
-```
-
----
-
-## Anti-Patterns (AVOID)
-
-- "I've made good progress, let me summarize..." (KEEP WORKING)
-- "The main work is done, you can finish..." (VERIFY FIRST)
-- "I'll skip this failing test for now..." (FIX IT NOW)
-- "I assume this needs to be implemented..." (SEARCH FIRST)
-- "I'll implement everything then test..." (TEST EACH TASK)
-- Proceeding with red tests (NEVER)
-- Implementing during planning phase (SEPARATE PHASES)
-- Large commits with multiple tasks (ONE TASK PER COMMIT)
-
----
-
-## Commands
-
-- `ralph` or `ralph plan` - Start planning phase
-- `ralph build` - Start building phase (requires tasks exist)
-- `ralph status` - Show current state via aide
-- `cancel` or `stop ralph` - Exit ralph mode
-
----
-
-## Quick Reference
-
-```
-PLANNING PHASE:
-1. ./.aide/bin/aide state set ralph:phase planning
-2. Search code (don't assume!)
-3. ./.aide/bin/aide memory add findings
-4. ./.aide/bin/aide task create (atomic tasks)
-5. ./.aide/bin/aide decision set (key decisions)
-6. ./.aide/bin/aide state set ralph:phase building
-
-BUILDING PHASE (per task):
-1. ./.aide/bin/aide task list (find next)
-2. ./.aide/bin/aide task claim <id>
-3. Re-verify gap exists
-4. Write failing tests
-5. Implement
-6. BACKPRESSURE: Tests MUST pass
-7. ./.aide/bin/aide task complete <id>
-8. Atomic commit
-9. Repeat or verify completion
-```
-
----
-
-## Swarm Compatibility
-
-This skill is **swarm-compatible**. Multiple ralph agents can:
-
-- Work on different tasks in parallel
-- Share discoveries via `./.aide/bin/aide memory`
-- Check decisions via `./.aide/bin/aide decision get`
-- Claim tasks atomically via `./.aide/bin/aide task claim`
-
-No file conflicts because all state is in aide's database.
-
----
-
-## Phase 3: Final QA (Swarm Mode)
-
-**MANDATORY** when ralph runs with swarm (multiple agents). After all tasks show `[done]`:
-
-### Step 1: Spawn QA Agent
-
-The orchestrator spawns a **single** QA subagent:
-
-```
-Spawn a final QA agent with instructions:
-"You are the QA agent for a ralph swarm session. Your job is NOT to trust the task list.
-Instead, independently verify the implementation against the original objective."
-```
-
-### Step 2: QA Agent Workflow
-
-The QA agent must:
-
-#### a) Load the Objective (not the task list)
-
-```bash
-./.aide/bin/aide state get ralph:objective
-```
-
-#### b) Independent Verification
-
-**Ignore the task list.** Instead, verify from first principles:
-
-1. **Read the code** - Does it implement the objective?
-2. **Check for gaps** - Are there missing pieces the tasks didn't cover?
-3. **Run full test suite** - Not just individual task tests
-   ```bash
-   npm test
-   npm run build
-   npm run lint
-   ```
-4. **Integration check** - Does it work as a whole?
-
-#### c) Find & Fix Gaps
-
-If gaps are found:
-
-```bash
-# Record the gap
-./.aide/bin/aide memory add --category=discovery --tags=ralph,qa "QA found gap: <description>"
-
-# Create fix task
-./.aide/bin/aide task create "QA fix: <description>" --tags=ralph,qa-fix
-
-# Implement the fix (follow standard backpressure rules)
-# ...
-
-# Mark complete
-./.aide/bin/aide task complete <id>
-```
-
-#### d) Final Sign-off
-
-Only when QA agent confirms:
-
-- All tests passing
-- Build clean
-- Lint clean
-- Objective fully met (not just tasks)
-
-```bash
-./.aide/bin/aide state set ralph:qa "passed"
-./.aide/bin/aide state set ralph:phase complete
-```
-
-### Step 3: QA Failure Handling
-
-If QA finds unfixable issues:
-
-```bash
-./.aide/bin/aide state set ralph:qa "failed"
-./.aide/bin/aide memory add --category=blocker --tags=ralph,qa "QA failed: <reason>"
-```
-
-Report to user with specific failures. **DO NOT** mark complete.
-
----
-
-## Swarm + Ralph Workflow Summary
-
-```
-ORCHESTRATOR                    SWARM AGENTS              QA AGENT
-     │                               │                        │
-     ├─► Planning phase              │                        │
-     │   (create tasks)              │                        │
-     │                               │                        │
-     ├─► Spawn N agents ────────────►│                        │
-     │                               ├─► Claim tasks          │
-     │                               ├─► Implement            │
-     │                               ├─► Backpressure tests   │
-     │                               ├─► Complete & commit    │
-     │                               │                        │
-     │◄── All tasks [done] ──────────┤                        │
-     │                               │                        │
-     ├─► Merge worktrees             │                        │
-     │   (worktree-resolve)          │                        │
-     │                               │                        │
-     ├─► Spawn QA agent ─────────────┼───────────────────────►│
-     │                               │                        ├─► Ignore task list
-     │                               │                        ├─► Verify objective
-     │                               │                        ├─► Fix gaps
-     │                               │                        ├─► Full test suite
-     │                               │                        │
-     │◄── QA passed ─────────────────┼────────────────────────┤
-     │                               │                        │
-     └─► Mark complete               │                        │
-```
-
-The QA phase ensures swarm work is **truly complete**, not just task-list complete.