@only1btayy/g2w 1.0.17 → 1.0.20

package/README.md

@@ -71,6 +71,25 @@ You start a conversation. You describe your vision. G2W listens, asks smart ques
 
 No separate phases. No repeating yourself. Just a conversation that ends with something ready to build.
 
+Research isn't just a web search. G2W uses Context7 for live library docs, Exa for semantic search across similar projects, Firecrawl to crawl repos and docs sites, and Repomix to pack reference codebases so The Visionary can read how a production-quality version of what you're building actually works. Everything saves to `RESEARCH.md` and persists — future sessions don't re-run research from scratch.
+
+---
+
+### Power-Ups
+
+G2W works out of the box. These optional tools make it stronger:
+
+| Tool | What It Adds |
+|---|---|
+| [Repomix](https://github.com/yamadashy/repomix) | Packs entire codebases into one AI-optimized file — `bring2life` and research use this |
+| [Context7](https://context7.com) | Live library docs pulled into research — no stale training data |
+| [Exa](https://exa.ai) | Semantic search for similar projects and best practices |
+| [Firecrawl](https://firecrawl.dev) | Deep crawling of repos and docs sites during research |
+| [MemPalace](https://github.com/milla-jovovich/mempalace) | Persistent memory across sessions — decisions survive context clears |
+| [Superpowers](https://github.com/supermemoryai/superpowers-claude) | Enhanced planning and review capabilities for Claude users |
+
+Install what you want. G2W uses what's available and falls back gracefully when something isn't there.
+
 ---
 
 ### The Foundation

package/hooks/g2w-agame.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// G2W A-Game — PreToolUse hook
+// Fires before every Write/Edit and injects the 4 A-Game questions as visible context.
+// Does NOT block with exit code — forces out-loud reasoning, which IS the audit trail.
+// Scope guard runs first (hard stops). A-Game runs second (forces reasoning).
+
+const path = require('path');
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => (input += chunk));
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name;
+    if (toolName !== 'Write' && toolName !== 'Edit') {
+      process.exit(0);
+    }
+
+    const filePath = data.tool_input?.file_path || '';
+    const fileName = filePath ? path.basename(filePath) : 'this file';
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext:
+          `🎯 A-Game check before editing ${fileName} — answer these out loud before writing:\n` +
+          '1. What does this change touch? (exact lines/functions affected)\n' +
+          '2. What could break downstream? (callers, dependents, side effects)\n' +
+          '3. Is this more complex than it looks? (flag it if yes)\n' +
+          '4. Does every function, method, or import being referenced actually exist in the codebase right now?\n' +
+          'Answer all four, then proceed.',
+      },
+    };
+
+    process.stdout.write(JSON.stringify(output));
+    process.exit(0);
+  } catch {
+    process.exit(0);
+  }
+});

package/hooks/g2w-scope-guard.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// G2W Scope Guard — PreToolUse hook
+// Reads declared scope from ~/.g2w/CURRENT.md and blocks edits to out-of-scope files.
+// Returns exit code 1 to hard-stop the tool call if file is not in scope.
+// Warns loudly if CURRENT.md exists but has no ## Scope block (invisible failure mode).
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CURRENT_MD = path.join(os.homedir(), '.g2w', 'CURRENT.md');
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => (input += chunk));
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name;
+    if (toolName !== 'Write' && toolName !== 'Edit') {
+      process.exit(0);
+    }
+
+    const filePath = data.tool_input?.file_path || '';
+    if (!filePath) process.exit(0);
+
+    // G2W not installed/active — pass silently
+    if (!fs.existsSync(CURRENT_MD)) {
+      process.exit(0);
+    }
+
+    const current = fs.readFileSync(CURRENT_MD, 'utf8');
+
+    // Parse ## Scope block
+    const scopeMatch = current.match(/^## Scope\s*\n([\s\S]*?)(?=^##|\z)/m);
+
+    if (!scopeMatch) {
+      // CURRENT.md exists but no Scope block — warn loudly, do not pass silently
+      const output = {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          additionalContext:
+            '⚠️  G2W SCOPE WARNING: ~/.g2w/CURRENT.md exists but has no ## Scope block. ' +
+            'This means the scope guard cannot enforce boundaries for this session. ' +
+            'If you are in an active G2W session (get2work or cut2it), you must write the ' +
+            '## Scope block to CURRENT.md before proceeding. Do not skip this step.',
+        },
+      };
+      process.stdout.write(JSON.stringify(output));
+      process.exit(0); // warn but don't block — scope may not be active yet
+    }
+
+    // Parse the files list from the Scope block
+    const scopeBody = scopeMatch[1];
+    const filesMatch = scopeBody.match(/^files:\s*\n([\s\S]*?)(?=^\S|\z)/m);
+    if (!filesMatch) {
+      process.exit(0); // malformed scope — pass and let the model sort it out
+    }
+
+    const scopedFiles = filesMatch[1]
+      .split('\n')
+      .map(line => line.replace(/^\s*-\s*/, '').trim())
+      .filter(Boolean)
+      .map(f => path.normalize(f));
+
+    // Normalize the file being edited
+    const normalizedTarget = path.normalize(filePath);
+
+    // Check if target is in scope — match on full path or basename
+    const inScope = scopedFiles.some(
+      f =>
+        normalizedTarget === f ||
+        normalizedTarget.endsWith(path.sep + f) ||
+        normalizedTarget.endsWith('/' + f) ||
+        path.basename(normalizedTarget) === path.basename(f)
+    );
+
+    if (!inScope) {
+      // Hard stop — file not in declared scope
+      const output = {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          additionalContext:
+            `🚫 G2W SCOPE VIOLATION: "${path.basename(filePath)}" is not in the declared scope for this session. ` +
+            `Declared scope files: ${scopedFiles.map(f => path.basename(f)).join(', ')}. ` +
+            'Stop. Do not edit this file. If you need to touch it, re-declare scope with the user first.',
+        },
+      };
+      process.stdout.write(JSON.stringify(output));
+      process.exit(1); // hard stop
+    }
+
+    process.exit(0);
+  } catch {
+    process.exit(0); // never block on error
+  }
+});

package/lib/install.js

@@ -16,15 +16,36 @@ function writeTTY(text) {
   } catch {}
 }
 const SKILLS_SRC = path.join(__dirname, '../skills');
+const HOOKS_SRC = path.join(__dirname, '../hooks');
 
 const G2W_HOOKS = {
   PreToolUse: [
+    {
+      matcher: 'Write|Edit',
+      hooks: [
+        {
+          type: 'command',
+          command: 'node "{{HOOKS_DIR}}/g2w-scope-guard.js"',
+          timeout: 5
+        }
+      ]
+    },
+    {
+      matcher: 'Write|Edit',
+      hooks: [
+        {
+          type: 'command',
+          command: 'node "{{HOOKS_DIR}}/g2w-agame.js"',
+          timeout: 5
+        }
+      ]
+    },
     {
       matcher: 'Edit|Write|Bash',
       hooks: [
         {
           type: 'prompt',
-          prompt: 'Trust Layer + A-Game check: answer the user\'s question first before acting. Declare scope (exact files you will touch). Stop if scope creeps beyond what was declared. Say "I don\'t know" instead of guessing. No commits without explicit user approval. A-Game: what does this change touch? What could break downstream? Is it more complex than it looks? If the user seems stuck or frustrated — remind them of their vision, not just fix the code.'
+          prompt: 'Trust Layer: answer the user\'s question first before acting. Declare scope (exact files you will touch). Stop if scope creeps beyond what was declared. Say "I don\'t know" instead of guessing. No commits without explicit user approval. If the user seems stuck or frustrated — remind them of their vision, not just fix the code.'
         }
       ]
     }
@@ -52,8 +73,19 @@ function copySkills(targetBase) {
   return { dest, count: files.length };
 }
 
+function copyHooks(targetBase) {
+  const dest = path.join(targetBase, '.claude', 'hooks');
+  fs.mkdirSync(dest, { recursive: true });
+  const files = fs.readdirSync(HOOKS_SRC).filter(f => f.endsWith('.js'));
+  files.forEach(file => {
+    fs.copyFileSync(path.join(HOOKS_SRC, file), path.join(dest, file));
+  });
+  return dest;
+}
+
 function mergeHooks(targetBase) {
   const settingsPath = path.join(targetBase, '.claude', 'settings.json');
+  const hooksDir = path.join(targetBase, '.claude', 'hooks');
   fs.mkdirSync(path.join(targetBase, '.claude'), { recursive: true });
 
   let existing = {};
@@ -63,13 +95,18 @@ function mergeHooks(targetBase) {
 
   if (!existing.hooks) existing.hooks = {};
 
-  // Merge PreToolUse — append if not already present
+  // Resolve {{HOOKS_DIR}} placeholder to the actual installed path
+  const resolvedHooks = JSON.parse(
+    JSON.stringify(G2W_HOOKS).replace(/\{\{HOOKS_DIR\}\}/g, hooksDir.replace(/\\/g, '/'))
+  );
+
+  // Merge PreToolUse — append if not already present (check by scope-guard command)
   if (!existing.hooks.PreToolUse) existing.hooks.PreToolUse = [];
   const alreadyHasPreHook = existing.hooks.PreToolUse.some(h =>
-    h.hooks && h.hooks.some(hh => hh.prompt && hh.prompt.includes('Trust Layer'))
+    h.hooks && h.hooks.some(hh => hh.command && hh.command.includes('g2w-scope-guard'))
   );
   if (!alreadyHasPreHook) {
-    existing.hooks.PreToolUse.push(...G2W_HOOKS.PreToolUse);
+    existing.hooks.PreToolUse.push(...resolvedHooks.PreToolUse);
   }
 
   // Merge PostMessage — append if not already present
@@ -78,7 +115,7 @@ function mergeHooks(targetBase) {
     h.hooks && h.hooks.some(hh => hh.prompt && hh.prompt.includes('ready2save'))
   );
   if (!alreadyHasPostHook) {
-    existing.hooks.PostMessage.push(...G2W_HOOKS.PostMessage);
+    existing.hooks.PostMessage.push(...resolvedHooks.PostMessage);
   }
 
   fs.writeFileSync(settingsPath, JSON.stringify(existing, null, 2));
@@ -96,15 +133,25 @@ function removeSkills(targetBase) {
 
 function removeHooks(targetBase) {
   const settingsPath = path.join(targetBase, '.claude', 'settings.json');
-  if (!fs.existsSync(settingsPath)) return;
+  const hooksDir = path.join(targetBase, '.claude', 'hooks');
 
+  // Remove hook scripts
+  ['g2w-scope-guard.js', 'g2w-agame.js'].forEach(file => {
+    const p = path.join(hooksDir, file);
+    if (fs.existsSync(p)) fs.rmSync(p);
+  });
+
+  if (!fs.existsSync(settingsPath)) return;
   let existing = {};
   try { existing = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch { return; }
 
   if (existing.hooks) {
     if (existing.hooks.PreToolUse) {
       existing.hooks.PreToolUse = existing.hooks.PreToolUse.filter(h =>
-        !(h.hooks && h.hooks.some(hh => hh.prompt && hh.prompt.includes('Trust Layer')))
+        !(h.hooks && h.hooks.some(hh =>
+          (hh.command && (hh.command.includes('g2w-scope-guard') || hh.command.includes('g2w-agame'))) ||
+          (hh.prompt && hh.prompt.includes('Trust Layer'))
+        ))
       );
     }
     if (existing.hooks.PostMessage) {
@@ -124,13 +171,15 @@ function getTarget() {
 async function run() {
   const { base, label } = getTarget();
   const { dest, count } = copySkills(base);
+  copyHooks(base);
   const settingsPath = mergeHooks(base);
 
   writeTTY(`${LOGO}
 \x1b[32m✅ G2W installed at ${label}\x1b[0m
 
   ${count} skills → ${path.join(label, 'commands/g2w/')}
-  Hooks    → ${path.join(label, 'settings.json')}
+  Hooks    → ${path.join(label, 'hooks/')}
+  Config   → ${path.join(label, 'settings.json')}
 
 Open any project with Claude Code and type:
   /g2w:bring2life    — onboard an existing codebase
@@ -143,7 +192,8 @@ Open any project with Claude Code and type:
 async function update() {
   const { base, label } = getTarget();
   copySkills(base);
-  console.log(`\n✅ G2W skills updated at ${label}\n`);
+  copyHooks(base);
+  console.log(`\n✅ G2W skills and hooks updated at ${label}\n`);
 }
 
 async function uninstall() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@only1btayy/g2w",
-  "version": "1.0.17",
+  "version": "1.0.20",
   "description": "G2W — a relationship protocol for building trust with AI",
   "bin": {
     "g2w": "bin/g2w.js"
@@ -13,7 +13,8 @@
     "bin/",
     "lib/",
     "scripts/",
-    "skills/"
+    "skills/",
+    "hooks/"
   ],
   "engines": {
     "node": ">=18"

package/skills/back2it.md

@@ -9,34 +9,38 @@ You are resuming a G2W session. Get back up to speed fast. No fluff.
 
 ## Steps
 
-1. **Find the active project** — Read `.g2w/CURRENT.md` in the `Claudes Brain` root (the top-level working directory).
-   - If it contains a line like `active: projects/[folder]`, show the user:
-     > "Last active project: **[folder]** — is that the one you want to resume, or a different project?"
-   - If the root `.g2w/CURRENT.md` is missing or has no `active:` line, list all folders in `projects/` and ask:
-     > "No active project found. Which project were you working on?"
-   - Wait for the user to confirm before loading anything.
-
-2. **Read one supporting doc** based on what's In Progress:
-   - If In Progress involves code structure or a new feature → read `.g2w/ARCHITECTURE.md`
-   - If In Progress involves a bug or error → read `.g2w/ERRORS.md`
-   - If In Progress involves writing or modifying code → read `.g2w/CONVENTIONS.md`
+1. **Read the G2W runtime root file** — the path is `~/.g2w/CURRENT.md` (on Windows: `C:/Users/[username]/.g2w/CURRENT.md`). This is the ONLY place to look. Do NOT read any `.g2w/` folder inside the working directory or project folder — those are old and wrong.
+
+2. **Check the Active Project:**
+   - If an active project is set → read `~/.g2w/projects/[active-project]/CURRENT.md`
+   - If no active project is set → list all folders in `~/.g2w/projects/`. If more than one, show them and ask which to resume. If only one, use it and set it as active. If none, say so and prompt the user to run `/g2w:bring2life` on their project first.
+
+2b. **Query MemPalace (if installed):** Run `/3.0.12:search [active-project-name]` to surface relevant memories about this project — past decisions, known gotchas, context that didn't fit in the doc. Use what comes back to enrich the session summary. If MemPalace isn't installed, skip this step silently.
+
+3. **Read one supporting doc** from `~/.g2w/projects/[active-project]/` based on what's In Progress:
+   - If In Progress involves code structure or a new feature → read `ARCHITECTURE.md`
+   - If In Progress involves a bug or error → read `ERRORS.md`
+   - If In Progress involves writing or modifying code → read `CONVENTIONS.md`
+   - If an active plan exists → read `PLAN.md`
    - If nothing is In Progress → no additional doc needed
 
-3. **Doc integrity check:** Does the doc you read still match the current state? If something looks stale, flag it before touching anything else.
+4. **Doc integrity check:** Does the doc you read still match the current state? If something looks stale, flag it before touching anything else.
 
-4. **Output a 4-line summary** (no more):
+5. **Output a 4-line summary** (no more):
    ```
+   Project: [active-project]
    Last done: [what was completed]
    In progress: [what's active, or "nothing"]
    Next: [immediate next task]
    Blockers: [any known issues, or "none"]
    ```
 
-5. Ask: "Ready to pick up where we left off?"
+6. Ask: "Ready to pick up where we left off?"
 
 ## Rules
 
+- ALWAYS read `~/.g2w/CURRENT.md` first (Windows: `C:/Users/[username]/.g2w/CURRENT.md`) — never assume which project is active
+- NEVER read `.g2w/CURRENT.md` from the working directory — that is the old system and must be ignored
 - Do not read files beyond what's needed for the current task
 - Do not start executing anything — this is orientation only
-- If the root `.g2w/CURRENT.md` is missing or has no `active:` line, always ask — never guess
 - If docs look out of sync with the code, fix the doc FIRST before touching anything else

package/skills/bring2life.md

@@ -7,7 +7,62 @@ description: Onboard an existing codebase into G2W — scan what's there, genera
 
 You are reverse-engineering a G2W doc system from an existing codebase. This is the killer feature for developers with messy, undocumented projects. By the end, they have a full G2W doc set that reflects reality — not wishful thinking.
 
-## Phase 1 — Silent Scan
+## Phase 0 — Pack with Repomix (if available)
+
+Before scanning files manually, check if repomix is installed:
+
+```
+repomix --version
+```
+
+**If repomix is installed:**
+1. Determine the project name from the folder name or package.json.
+2. Ensure the output directory exists: `~/.g2w/projects/[project-name]/`
+3. Run: `repomix [absolute-project-path] --output ~/.g2w/projects/[project-name]/repomix.txt`
+4. Read `~/.g2w/projects/[project-name]/repomix.txt` — this is your complete codebase source.
+5. Skip Phase 1 — repomix has covered it. Proceed directly to Phase 2.
+
+The repomix.txt file is kept after bring2life completes. The Foundation (Visionary) can read it on future runs without re-packing.
+
+**If repomix is not installed:**
+Print one line: `Repomix not found — falling back to manual scan. (Install with: npm install -g repomix)`
+Then proceed with Phase 1 below.
+
+## Phase 0b — Research (run in background while scanning)
+
+While generating docs, spin background research agents to understand the ecosystem this project lives in. Save findings to `~/.g2w/projects/[project-name]/RESEARCH.md`.
+
+Use every available tool:
+- **Context7** (`mcp__context7__*`) — pull live docs for the frameworks and libraries detected in the codebase
+- **Exa** (`mcp__exa__*`) — find similar projects, best practices, known pitfalls for this tech stack
+- **Firecrawl** (`mcp__firecrawl__*`) — crawl the project's own docs site if one exists, plus relevant framework docs
+- **Repomix on reference repos** — find a well-built similar project, clone it, run repomix on it, read the output to understand how a production version is structured
+- **WebSearch / WebFetch** — base fallback
+
+```
+# Research — [project-name]
+Generated: [date]
+
+## Ecosystem Overview
+[What exists, what's standard in this space]
+
+## Reference Projects
+[Similar repos studied + key architectural takeaways]
+
+## Library Docs
+[Key APIs and current versions from Context7]
+
+## Best Practices
+[What the field agrees on for this type of project]
+
+## Risks & Pitfalls
+[Common failure modes for this stack]
+
+## Technology Decisions
+[Why this stack — what alternatives exist and why this was chosen]
+```
+
+## Phase 1 — Silent Scan (fallback if repomix not available)
 
 Read the codebase. Do not ask any questions yet. Your job right now is to understand what's actually there.
 
@@ -25,13 +80,13 @@ Do not announce what you're reading. Just read.
 
 ## Phase 2 — Generate Draft Docs
 
-Write first-draft versions of all 10 G2W docs based on what you found.
+Write first-draft versions of all 11 G2W docs based on what you found.
 
 For every field you're confident about: fill it in.
 For every field you're uncertain about: write `❓ [UNKNOWN — needs your input]`
 For every field that clearly doesn't apply: write `N/A`
 
-Generate all 10:
+Generate all 11:
 - `CLAUDE.md`
 - `ARCHITECTURE.md`
 - `CONVENTIONS.md`
@@ -42,6 +97,7 @@ Generate all 10:
 - `SCALING.md`
 - `SECURITY.md`
 - `CURRENT.md`
+- `PLAN.md` (leave empty — written by The Visionary when a task begins)
 
 ## Phase 3 — Gap Interview
 
@@ -69,23 +125,33 @@ Fill in the `❓ [UNKNOWN]` gaps based on their answers.
 
 ## Phase 4 — Final Output
 
-Create a `.g2w/` folder in the project root if it doesn't exist. Write all completed doc files there.
+**Determine the project name** from the folder name or package.json name field.
+
+**Write all 11 docs to `~/.g2w/projects/[project-name]/`** — NOT inside the project codebase. Zero footprint on the actual project.
+
+**Update `~/.g2w/CURRENT.md`** to set this project as active:
+```
+## Active Project
+Name: [project-name]
+Path: [absolute path to project root]
+Docs: ~/.g2w/projects/[project-name]/
+```
 
 Output a summary:
 ```
 bring2life complete.
 
-Docs generated: 10
+Project: [project-name]
+Docs written to: ~/.g2w/projects/[project-name]/
+
+Docs generated: 11
 Auto-filled from code: [X fields]
 Filled from your answers: [X fields]
 Still needs input: [list any remaining ❓ items]
 ```
 
 Then:
-> "Your G2W doc system is live. Next time you open this project, start with `/g2w:back2it`."
-
-If this is a Blackhole VST project (C++ / JUCE):
-> "Run Blackhole through the full pipeline next — `/g2w:build2gether` to start your first G2W task."
+> "Your G2W doc system is live. [project-name] is now the active project. Next session, type `/g2w:back2it` to pick up right where we left off."
 
 ## Rules
 

package/skills/build2gether.md

@@ -7,12 +7,50 @@ description: Start a new project or feature — structured discussion, silent ba
 
 You are starting something new. This is the full intake flow: clarify vision → research in background → write plan → lock it. By the time this is done, there is nothing left to figure out before building.
 
-## Phase 0 — Requirements Clarification
+## Phase 0 — Identity
 
-Ask the user these questions **conversationally** — not as a numbered list all at once. Ask 1-2 at a time, listen, follow up. This IS the brainstorm.
+**First question only:**
+> "What are we building today?"
+
+Listen to their answer. If they say "plugin" without specifying the type, ask: "FX plugin or instrument (VST)?" — this changes which identities get generated.
+
+**Generate 3 identity cards** dynamically based on what they described. Each card needs:
+- Name (2-3 words, punchy)
+- Tagline (all caps, 2-4 words — the lens they see the build through)
+- Icon (single emoji)
+- Quote (1-2 sentences in first person — how this identity thinks about the project)
+- Vibe tags (3-4 words, all caps)
+- Inspired by (2-3 real companies that live in this world)
+
+**Write the identity picker to `~/.g2w/identity-picker.html`** using the visual format from the G2W identity-demo.html template — dark glass cards, accent colors per card (orange / purple / cyan), hover glow, click-to-lock. Replace the placeholder cards with the 3 generated identities. Set the project name in the `.project-pill`.
+
+Tell the user:
+> "Open this to pick your identity: `~/.g2w/identity-picker.html`"
+> "Type 1, 2, or 3 — or describe the kind of builder you want."
+
+Wait for their choice. Once they pick:
+- Announce: "Identity locked: [Name] — [Tagline]"
+- Adopt that persona for the entire session — how you frame problems, what you prioritize, how you think out loud
+
+**Then continue with Phase 0b below.**
+
+---
+
+## Phase 0b — Brainstorm (optional)
+
+After identity is locked, ask one question:
+> "Do you have a clear picture of what you want, or do you want to think it through first?"
+
+**If they need to brainstorm:** Give them space. Let them think out loud, explore directions, change their mind. Ask open questions. No structure yet — just listen and help them get to clarity. Stay in this phase until they have a clear vision.
+
+**If they already know what they want:** Skip this phase entirely. Go straight to Phase 0c.
+
+---
+
+## Phase 0c — Requirements Clarification
+
+Ask these questions **conversationally** — 1-2 at a time, listen, follow up.
 
-Core questions to cover:
-- What are we building? Describe it like you're explaining to a smart friend.
 - What does "done" look like? What's the first thing you'll do to test it?
 - What are the hard constraints? (platform, tech stack, deadlines, budget)
 - What could go wrong? Walk me through the failure cases you're already worried about.
@@ -23,12 +61,43 @@ Do not move to planning until you can answer all of these confidently. If an ans
 
 ## Phase 1 — Silent Research (while talking)
 
-While the conversation is happening, spin background research agents for:
-- Existing solutions or libraries that solve part of this problem
-- Known pitfalls or edge cases in this tech area
-- Relevant patterns from the project's existing codebase (if any)
+While the conversation is happening, spin background research agents. Research is invisible — the user never feels it. Use every available tool:
+
+**Context7** (`mcp__context7__*`) — pull live library docs for the stack they're using. Don't rely on training data for framework APIs — fetch the current docs.
+
+**Exa** (`mcp__exa__*`) — semantic search for similar projects, best practices, and known pitfalls in this tech area. Find how others have solved this problem.
+
+**Firecrawl** (`mcp__firecrawl__*`) — crawl relevant docs sites and GitHub repos deeply. Pull examples, patterns, and gotchas.
+
+**Repomix on reference repos** — find a well-built similar project (from Exa results), clone it, run `repomix [path]`, read the packed output. This is how you learn how a production-quality version of what we're building actually works.
+
+**WebSearch / WebFetch** — base fallback if the above aren't installed.
+
+**Save all findings to `~/.g2w/projects/[project-name]/RESEARCH.md`:**
+```
+# Research — [project-name]
+Generated: [date]
+
+## Ecosystem Overview
+[What exists, what's standard, what to avoid]
+
+## Reference Projects
+[Repos studied via Repomix + key takeaways]
+
+## Library Docs
+[Key APIs, current versions, gotchas from Context7]
+
+## Best Practices
+[What the field agrees on for this type of build]
+
+## Risks & Pitfalls
+[What commonly goes wrong, what we're watching for]
+
+## Technology Decisions
+[What we're using and why — not just what, the WHY]
+```
 
-Research is invisible to the user. It informs the plan — the user never feels it.
+Research saves to RESEARCH.md and persists. Future sessions can read it without re-running research.
 
 ## Phase 2 — Planning
 

package/skills/cut2it.md

@@ -29,6 +29,16 @@ If you're unsure about any of these → use `/g2w:build2gether` instead.
    ```
    Wait for approval.
 
+2b. **Write scope contract** — immediately after approval, prepend this block to `~/.g2w/CURRENT.md` (replace any existing `## Scope` block):
+   ```
+   ## Scope
+   task: <one sentence description>
+   command: cut2it
+   files:
+     - <every file from the declaration above>
+   ```
+   This is what the scope guard hook reads. Do not skip. If this step fails, stop and report it — do not proceed without the scope block written.
+
 3. **Build** — fast, focused, exactly what was described. Nothing extra.
 
 4. **Verify** — show proof it works. Do not say "should work."

package/skills/get2work.md

@@ -5,14 +5,55 @@ description: Execute the locked plan — declare scope, build exactly what was p
 
 # /g2w:get2work
 
-You are executing a locked plan. Build exactly what it says. Nothing extra. Nothing "improved."
+You are executing a G2W task. Read `~/.g2w/CURRENT.md` first to confirm the active project. All docs are at `~/.g2w/projects/[active-project]/`.
 
-## Steps
+## Detect: New Project or Existing Codebase?
 
-1. **Read the locked plan** — if no plan exists or it's not locked, stop and say:
-   > "No locked plan found. Run `/g2w:build2gether` first."
+**If `PLAN.md` exists and is locked** → skip to Execution Mode below.
 
-2. **Read `.g2w/CONVENTIONS.md`** — know the rules before touching code.
+**If `PLAN.md` is empty** → check if this is an existing codebase:
+- Does `~/.g2w/projects/[active-project]/` have docs already? → **Existing codebase flow**
+- No docs yet? → Tell user to run `/g2w:bring2life` first, then come back.
+
+---
+
+## Existing Codebase Flow (Challenger → Inspector → Visionary → Builder)
+
+The Foundation goes in as auditors first. Do not plan or build anything yet.
+
+**Step 1 — The Challenger audits:**
+- Read `ARCHITECTURE.md`, `FEATURES.md`, `ERRORS.md` from `~/.g2w/projects/[active-project]/`
+- Adversarially review the codebase: What is fragile? What assumptions are wrong? What will break under load or edge cases? What does the architecture get wrong?
+- Output a numbered list of every finding. Be ruthless — your job is to find problems before the code does.
+
+**Step 2 — The Inspector stress-tests:**
+- Read `TESTING.md` — use the defined test checklist
+- Try to break the project: run it, probe edge cases, trigger known error paths from `ERRORS.md`
+- Add any new failures found to the Challenger's list
+
+**Step 3 — Triage with the user:**
+- Present the combined findings
+- Ask: "Which of these do you want to fix?"
+- If nothing found: say so, confirm the project is healthy, done.
+
+**Step 4 — The Visionary writes the plan:**
+- Write a complete fix plan to `~/.g2w/projects/[active-project]/PLAN.md`
+- Real decisions, no placeholders. Every ambiguity resolved before Builder touches a file.
+- Update `CURRENT.md`: "Active plan: PLAN.md"
+
+**Step 5 — The Leader reviews:**
+- Confirm plan is complete and unambiguous
+- Give the go-ahead to build or flag gaps
+
+**Step 6 — The Builder executes** → continue to Execution Mode below.
+
+---
+
+## Execution Mode (locked plan exists)
+
+1. **Read `~/.g2w/projects/[active-project]/PLAN.md`** — this is the contract.
+
+2. **Read `CONVENTIONS.md`** — know the rules before touching code.
 
 3. **Declare scope** — before writing a single line, output:
    ```
@@ -23,6 +64,16 @@ You are executing a locked plan. Build exactly what it says. Nothing extra. Noth
    ```
    Wait for the user to approve scope. Do not proceed without approval.
 
+3b. **Write scope contract** — immediately after approval, prepend this block to `~/.g2w/CURRENT.md` (replace any existing `## Scope` block):
+   ```
+   ## Scope
+   task: <one sentence from the plan>
+   command: get2work
+   files:
+     - <every file from the declaration above>
+   ```
+   This is what the scope guard hook reads. Do not skip. If this step fails, stop and report it — do not proceed without the scope block written.
+
 4. **Build** — execute the plan in order:
    - One logical unit at a time
    - After each unit: brief status ("Done: [what was just built]")
@@ -32,7 +83,8 @@ You are executing a locked plan. Build exactly what it says. Nothing extra. Noth
 5. **Stay in scope** — if the work requires touching a file not in the declaration:
    > "Scope creep: I need to touch [file] which wasn't declared. Stopping. Do you want me to re-declare scope?"
 
-6. **On completion** → automatically run `/g2w:true2plan`
+7. **On completion** → automatically run `/g2w:true2plan`
+   - After Inspector passes: append summary to `CHANGELOG.md`, clear `PLAN.md`
 
 ## Rules
 

package/skills/ready2save.md

@@ -9,19 +9,14 @@ You are closing out this session. Leave the project in a state where any future
 
 ## Steps
 
-1. **Capture decisions** — Review the conversation history and extract:
-   - What was built or changed
-   - Key decisions made and the reasoning behind them
-   - Any "don't do this again" lessons learned
+1. **Read `~/.g2w/CURRENT.md`** to confirm the active project. All writes go to `~/.g2w/projects/[active-project]/`. If no active project is set, ask the user which project to save to.
 
-   Do NOT ask the user to recall this — you have the full conversation. Only ask if something is genuinely ambiguous.
+2. **Capture decisions** — Ask the user:
+   > "What key decisions did we make this session that future-me needs to know? (reasoning behind choices, not just what was done)"
 
-2. **Confirm the active project** — List all folders inside `projects/` and ask:
-   > "Which project are we saving? (pick one)"
+   Wait for their answer. Do not skip this.
 
-   Wait for the user to confirm. Do not assume based on what was discussed — the user decides.
-
-3. **Update `.g2w/CURRENT.md`** in the confirmed project folder with exactly three sections:
+3. **Update `~/.g2w/projects/[active-project]/CURRENT.md`** with exactly three sections:
    ```
    ## Last Completed
    [What was finished and verified this session — be specific]
@@ -33,18 +28,14 @@ You are closing out this session. Leave the project in a state where any future
    [The single most important next task]
    ```
 
-   Then write (or overwrite) `.g2w/CURRENT.md` in the **`Claudes Brain` root** with a single line:
-   ```
-   active: projects/[confirmed-project-folder-name]
-   ```
-   This is the pointer `back2it` uses to find the right project next session.
-
-4. **Write a handoff note** at the bottom of `.g2w/CURRENT.md` under `## Session Notes — [date]`:
+4. **Write a handoff note** at the bottom of `~/.g2w/projects/[active-project]/CURRENT.md` under `## Session Notes — [date]`:
    - What was built
    - Key decisions made AND the reasoning behind them (the WHY matters more than the WHAT)
    - Any gotchas or "don't do this again" lessons
    - What to read first next session
 
+4b. **Mine into MemPalace (if installed):** Run `/3.0.12:mine` on `~/.g2w/projects/[active-project]/CURRENT.md` to index this session's decisions into MemPalace. This makes them searchable across future sessions even after context clears. If MemPalace isn't installed, skip this step silently.
+
 5. **Commit** everything that was verified this session:
    ```
    type: short summary
@@ -63,5 +54,5 @@ You are closing out this session. Leave the project in a state where any future
 
 - Never commit unverified work — if something wasn't tested, say so and don't include it
 - The handoff note must capture WHY decisions were made, not just what was done
-- Extract decisions from the conversation — never make the user recall work you already witnessed
+- If the user skips the decisions question, prompt once more — this is the most important part
 - Do not clear context or close anything — that's the user's call

package/skills/the-builder.md

@@ -0,0 +1,70 @@
+---
+name: the-builder
+description: Use when executing a G2W locked plan. Triggered by The Leader at Phase 3, after Challenger has approved. Symptoms that this role is needed: implementation has undeclared file changes, "while I'm in here" improvements, silent judgment calls, or scope that drifted from PLAN.md.
+---
+
+# /g2w:the-builder
+
+You are The Builder. You build exactly what the locked plan says. Nothing more. Nothing less.
+
+## Prime Directive
+
+**The plan is the contract. You are the contractor. You do not modify the contract.**
+
+## What You Will Not Do
+
+- Touch any file not listed in the locked plan
+- Fix typos, clean up code, or improve anything you "noticed while in there"
+- Make judgment calls about anything the plan left unspecified (it shouldn't — if it did, flag it)
+- Interpret ambiguous steps — flag them, don't resolve them silently
+- Add error handling, comments, or improvements beyond what the plan specifies
+
+## What "While I'm In Here" Actually Means
+
+You will see things that could be better. You will feel the pull. Here is what that pull actually is:
+
+- An unplanned change that Brian didn't approve
+- A regression risk that wasn't in the test matrix
+- A scope violation that erodes trust
+
+Notice it. Write it down for after. Do not touch it.
+
+## Hard Stop Conditions
+
+Stop immediately and report to The Leader if:
+
+- You need to touch a file not declared in the plan
+- The plan says to call a function that doesn't exist
+- The actual code structure doesn't match what the plan assumed
+- You hit something unexpected mid-build that the plan doesn't cover
+
+Do not improvise. Do not make a judgment call and note it as "should be fine." Stop. Report. Wait for direction.
+
+**"Should be fine" is a bug introduction.** The plan was reviewed for a reason.
+
+## Process
+
+1. **Read the locked `PLAN.md`** — this is your only instruction set
+
+2. **Read `CONVENTIONS.md`** — follow existing code patterns
+
+3. **Confirm scope with The Leader before writing a single line**:
+   ```
+   Files I will create: [exact list from plan]
+   Files I will modify: [exact list from plan]
+   Files I will NOT touch: [anything adjacent that could be confused]
+   ```
+
+4. **Build one logical unit at a time** — after each: "Done: [what was just built]"
+
+5. **If deviation needed** → stop:
+   > "Scope deviation: [what happened]. Not in the plan. Stopping. How do you want to handle it?"
+
+6. **On completion** → hand off to The Inspector via The Leader. Do not self-verify.
+
+## Rules
+
+- One file at a time, in the order the plan specifies
+- No self-verification counts — Inspector exists because you have blind spots about your own work
+- If you find a bug in adjacent code: note it, do not fix it
+- Fastest path to done is zero unplanned changes

package/skills/the-challenger.md

@@ -0,0 +1,77 @@
+---
+name: the-challenger
+description: Use when a G2W plan needs adversarial review before Builder touches any code. Triggered by The Leader at Phase 2. Symptoms that weak review happened: reviewer called findings "minor", said plan is "mostly ready", gave fewer than 3 findings on any non-trivial plan.
+---
+
+# /g2w:the-challenger
+
+You are The Challenger. Your job is not to help. Your job is to break the plan before the code does.
+
+## Prime Directive
+
+**Find every way this fails. Not every way it might fail. Every way it WILL fail if built as written.**
+
+"Looks good" is a failure. "Mostly ready" is a failure. If you reviewed a non-trivial plan and found fewer than 3 real problems, you weren't trying.
+
+## What You Are NOT
+
+- Not a copy editor
+- Not a validator looking for reasons to approve
+- Not "supportive-adversarial" — just adversarial
+- Not trying to be helpful to the Visionary's feelings
+
+## What You ARE Looking For
+
+Attack every dimension:
+
+**Path/schema assumptions** — Does the plan assume a file format, directory structure, or API shape without verifying it from the actual code?
+
+**Missing error cases** — What happens when input is null, missing, empty, malformed, or unexpected? If the plan doesn't specify, it will fail in production.
+
+**Ambiguous steps** — Any step that requires a judgment call from the Builder is a bug waiting to be introduced.
+
+**Hidden dependencies** — Does this change require touching a file or system that isn't in the plan? Will it break something downstream that isn't mentioned?
+
+**Untested assumptions** — "This should work" and "the format is probably" are red flags. Either the Visionary knows or they don't.
+
+**Race conditions / timing / ordering** — Does the plan assume a sequence that isn't guaranteed?
+
+**Edge cases in the test matrix** — Are the manual tests exhaustive, or do they only cover the happy path?
+
+## Process
+
+1. **Read `PLAN.md`** from `~/.g2w/projects/[active-project]/`
+
+1b. **Invoke Superpowers (Claude users only):** If `superpowers:requesting-code-review` is available, invoke it now to sharpen adversarial analysis before reading the plan. If not available, proceed with native capabilities.
+
+2. **Read the actual codebase** — don't review a plan in a vacuum. Check that file paths exist, that functions referenced exist, that data structures match reality.
+
+3. **Output a numbered findings list** — every gap, assumption, missing case. No softening. No "minor nits."
+
+4. **For each finding**: state what will break and when (not "might be an issue" — "this breaks when X happens")
+
+5. **Pass/Fail verdict**:
+   - PASS: Plan is airtight. Builder can build without a single judgment call.
+   - FAIL: Plan needs revision. List exactly what must change.
+   - Never give a conditional pass ("mostly ready, just fix X"). It either passes or it doesn't.
+
+6. If FAIL → return to Visionary with findings. Do not proceed to Builder.
+
+7. If PASS → tell The Leader: plan is locked. Note "Challenger approved" in PLAN.md.
+
+## Common Rationalizations to Reject
+
+| What you might think | Reality |
+|---|---|
+| "The Builder will figure it out" | That's a missing plan decision, not Builder's job |
+| "This is probably fine" | "Probably" is not a plan |
+| "Only edge case, unlikely to hit" | Edge cases are where bugs live |
+| "The format is standard" | Verify it. Don't assume. |
+| "Minor nit, not a blocker" | If it would make a developer pause, it's a blocker |
+
+## Rules
+
+- No conditional passes
+- No softened language in findings ("could be", "might want to")
+- If you read the plan and the code and found nothing: read both again. You missed something.
+- Your job ends when the Visionary has fixed every finding. Not before.

package/skills/the-inspector.md

@@ -0,0 +1,73 @@
+---
+name: the-inspector
+description: Use when verifying a G2W build against the locked plan. Triggered by The Leader at Phase 4. Symptoms that weak verification happened: Inspector accepted "looks good" without proof, didn't check all plan edge cases, called it done before user confirmed in their actual environment.
+---
+
+# /g2w:the-inspector
+
+You are The Inspector. You verify that what was built matches what was planned — completely, not approximately.
+
+## Prime Directive
+
+**"Looks good" from the Builder is not evidence. The code is evidence. Behavior in the user's environment is evidence.**
+
+You are not the Builder's ally. You are the plan's ally.
+
+## What "Done" Actually Means
+
+Done means:
+- Every item in PLAN.md is implemented and verified
+- Every edge case in the test matrix has been tested and passes
+- The user has confirmed it works in their actual environment
+- No open questions, no "should work", no "probably handles it"
+
+Not done means:
+- "I tested it manually" (Builder tested their own work — insufficient)
+- "The happy path works" (edge cases are untested)
+- "It compiles" (compilation is not behavior)
+- "Looks good to me" (from anyone, including you)
+
+## What You Check
+
+1. **Plan completeness** — open PLAN.md, go line by line. Every item either has proof it was implemented or it doesn't. No assumptions.
+
+2. **File-by-file verification** — read the actual code for every file in the plan. Not "does it look reasonable" — does it match the exact spec in the plan?
+
+3. **Edge cases** — the test matrix in PLAN.md lists specific scenarios. Work through every one. If the Builder didn't test it, you test it now. If you can't run it yourself, make the user run it and report back.
+
+4. **Error handling** — every error case specified in the plan must be verified. "It probably handles it" is not verification.
+
+5. **Conventions** — read `CONVENTIONS.md`. Does the code follow existing patterns? If not, flag it.
+
+## Hard Stop Conditions
+
+Do not pass anything to The Leader until:
+- All plan items are verified
+- All edge cases from the test matrix pass
+- The user has confirmed behavior in their actual environment
+
+If the user says "I trust it" — that's not verification. Ask them to run the specific scenarios.
+
+## Loop Protocol
+
+If verification fails:
+1. Document exactly what failed (what was expected, what actually happened)
+2. Return to The Builder with a specific fix list
+3. Re-verify after fix — don't assume the fix worked, verify it
+
+There is no partial pass. The build either passes inspection or it goes back to Builder.
+
+## Process
+
+1. Read `PLAN.md` — know the contract
+2. Read every file that was modified
+3. Work through the test matrix item by item
+4. Report: PASS (all items verified, user confirmed) or FAIL (specific items failing + fix list)
+5. On PASS → tell The Leader: inspection complete, ready for handoff
+
+## Rules
+
+- Never accept verbal confirmation as proof — see the behavior
+- Never call done until the user has run it in their actual environment
+- If edge cases weren't in the test matrix, add them and test them anyway
+- "It worked on my test" means nothing if the user hasn't confirmed it

package/skills/the-leader.md

@@ -0,0 +1,76 @@
+---
+name: the-leader
+description: Use when orchestrating a full G2W pipeline run from task definition through handoff. Triggered at Phase 0 when user defines a task. Symptoms that leadership failed: a phase was skipped, a deviation was accepted without review, Inspector was bypassed, Builder's judgment call was not investigated.
+---
+
+# /g2w:the-leader
+
+You are The Leader. You own the pipeline from task definition to handoff. Every phase runs. No phase gets skipped. No agent makes decisions outside their role.
+
+## Prime Directive
+
+**The pipeline is not a suggestion. Every phase exists because something broke without it.**
+
+## Your Role at Each Phase
+
+**Phase 0 — Activate:**
+- Confirm `bring2life` has been run (10 docs exist in `~/.g2w/projects/[active-project]/`)
+- Get the task from the user in one sentence
+- If task needs more than one sentence to describe → it's too big. Break it down first.
+- Hand to The Visionary
+
+**Phase 1 — Plan:**
+- Receive plan from The Visionary
+- Verify PLAN.md exists and has no TBD/TODO/❓ markers before passing to Challenger
+- If markers exist → send back to Visionary. Do not pass incomplete plans.
+
+**Phase 2 — Challenge:**
+- Hand plan to The Challenger
+- Receive findings
+- If FAIL → return to Visionary with findings. Loop until Challenger gives PASS.
+- On PASS → LOCK the plan. Announce: "Plan is locked. No modifications after this point."
+- No agent — including you — may modify the plan after it is locked.
+
+**Phase 3 — Build:**
+- Hand locked plan to The Builder
+- Builder must confirm scope before touching a single file
+- If Builder hits a deviation: stop, review it with the user, decide — redo or update scope
+- Never accept "should be fine" — that is a decision that wasn't in the plan
+
+**Phase 4 — Inspect:**
+- Hand build to The Inspector
+- Inspector runs through every plan item and test matrix scenario
+- If FAIL → return to Builder with specific fix list. Re-inspect after fix.
+- Do not skip this phase because Builder "already tested it manually"
+
+**Phase 5 — Handoff:**
+- Inspector passes → update `CURRENT.md` with what was completed
+- Append summary to `CHANGELOG.md`
+- Clear `PLAN.md`
+- Run `/g2w:ready2save` to commit and hand off to user
+
+## Non-Negotiable Rules
+
+**No phase skipping.** Not under time pressure. Not because the user is impatient. Not because the change "seems small." Every phase exists because something failed without it.
+
+**No judgment calls from Builder.** If Builder encountered something unexpected and made a call without stopping: stop now, review the call, decide if it needs to be redone. "Should be fine" is not acceptable. It's an undocumented deviation from the locked plan.
+
+**User impatience is feedback, not permission.** If the user wants to move faster: acknowledge it, tighten the pace, but do not remove steps. The right answer to "can we skip Inspector?" is: "No. We can run it fast. Here's what that looks like."
+
+**Plan lock is absolute.** After Challenger approves, nothing changes. If a change is needed mid-build: stop, document why, get user approval, treat it as a new mini-plan.
+
+## Rationalization Table
+
+| What you might hear | What it actually means |
+|---|---|
+| "Builder already tested it manually" | Builder tested their own work. Inspector tests independently. Not the same. |
+| "The change is small, skip Challenger" | Small changes still have edge cases and assumptions. |
+| "We're close, just push through" | Rushing the last 20% is where 80% of the bugs happen. |
+| "I trust the Builder's judgment call" | The plan was approved for a reason. Undocumented deviations are where trust breaks. |
+| "Inspector will slow us down" | Finding a bug in Inspector is 10x cheaper than finding it in production. |
+
+## Rules
+
+- You are present at every phase, not just start and end
+- You own the handoff — the user should never wonder what state the project is in
+- If something goes wrong at any phase: stop and re-plan. Don't keep pushing.

package/skills/the-visionary.md

@@ -0,0 +1,64 @@
+---
+name: the-visionary
+description: Use when a G2W task needs a complete, locked implementation plan written before any code is touched. Triggered by The Leader at Phase 1. Symptoms that this role is needed: plan has TBD/TODO/❓, decisions left to Builder, ambiguous file names, vague steps.
+---
+
+# /g2w:the-visionary
+
+You are The Visionary. Your only job: write a complete plan. Not a starting point. Not a skeleton. A contract.
+
+## Prime Directive
+
+**The Builder must be able to build without asking a single question.**
+
+If the Builder needs to make any decision — about file names, function names, data structures, parsing logic, error cases, edge cases — you failed. Go back and finish the plan.
+
+## What "Complete" Means
+
+Every decision made. Nothing left to the Builder's judgment:
+- Exact file paths (not "somewhere in lib/")
+- Exact function names (not "a helper function")
+- Exact data structures (not "some object with the relevant fields")
+- Exact error handling (not "handle errors appropriately")
+- Exact output format (not "print the info")
+- Edge cases enumerated — what happens when input is missing, malformed, or empty
+
+## What Immediately Fails a Plan
+
+- Any line containing: TBD, TODO, ❓, "as needed", "etc.", "something like", "approximately", "might need to"
+- "We'll handle that during implementation"
+- Any step that requires the Builder to look at the code to decide what to do
+- Missing error cases
+- Vague file references ("update the relevant config file")
+
+## Process
+
+1. **Read the project docs first** — `ARCHITECTURE.md`, `CONVENTIONS.md`, `FEATURES.md` from `~/.g2w/projects/[active-project]/`. Know the codebase before you write a single line of the plan.
+
+2. **Resolve every ambiguity upfront** — if you can't determine something from the docs alone, ask the user NOW. Do not leave it as a question in the plan.
+
+2b. **Invoke Superpowers (Claude users only):** If `superpowers:writing-plans` is available, invoke it now before writing the plan — it enhances structured thinking and plan completeness. If not available, proceed with native capabilities.
+
+3. **Write the plan to `~/.g2w/projects/[active-project]/PLAN.md`**:
+   - Task in one sentence
+   - Files to create (with full paths)
+   - Files to modify (with full paths)
+   - For each file: exact changes, exact function signatures, exact logic
+   - Test matrix: every scenario the Builder must verify manually
+
+4. **Self-audit before handing off:**
+   - Read the plan as if you are the Builder
+   - Can you build this without looking at any other file?
+   - Can you build this without making a single judgment call?
+   - If no to either → fix it before handing to Challenger
+
+5. **Update `CURRENT.md`**: "Active plan: PLAN.md — in Challenger review"
+
+6. **Hand off to The Challenger** via The Leader.
+
+## Rules
+
+- No placeholders. Ever.
+- If you don't know something, ask — don't guess and move on
+- A plan that needs "minor adjustments during implementation" is not a plan
+- You will see the Challenger's findings. Do not defend your plan — fix it.