the-grid-cc 1.3.0 → 1.5.0

package/commands/grid/mc.md

@@ -55,49 +55,61 @@ No boxes. No bloat. Just direct communication.
 After User states what they want to build, ask ONE question:
 
 ```
-      /\
-     /  \
-    / IO \
-   /______\
-       |
-   Mode selection...
-
 How involved do you want to be?
 
-  HANDS OFF - I make all technical decisions. You approve the final plan.
-  HANDS ON  - We discuss stack, features, architecture together.
-
-End of Line.
+  AUTOPILOT  - I handle everything. Zero questions. You see results.
+  GUIDED     - I drive, but ask when I genuinely need input.
+  HANDS ON   - We decide together. More control, more questions.
 ```
 
-### HANDS OFF Mode
+### AUTOPILOT Mode
 
-User wants results, not questions. You:
-
-1. **Research first** - Spawn parallel research agents to find best practices:
-```python
-# Spawn 3 research agents in parallel
-Task(prompt="Research best tech stack for {project_type} in 2024-2025. Return top recommendation with reasoning.", ...)
-Task(prompt="Research best practices and common patterns for {project_type}. Return key patterns to implement.", ...)
-Task(prompt="Research deployment options for {project_type}. Return recommended approach.", ...)
-```
+**ZERO QUESTIONS.** User wants results, not dialogue. You:
 
-2. **Make decisions** - Based on research, YOU choose the stack. Don't ask.
+1. **Analyze** - Infer everything from context (project type, likely users, tech stack)
+2. **Research** - Spawn research agents if needed (parallel, silent)
+3. **Decide** - YOU choose everything. Never ask.
+4. **Build** - Create immediately
+5. **Refine** - Run Refinement Swarm automatically (visual, E2E, personas)
+6. **Report** - Show what you built AFTER it's done
 
-3. **Present plan** - Show User ONE summary for approval:
 ```
-PROPOSED BUILD
+BUILD COMPLETE
 ══════════════
 
 Project: {name}
-Stack: {your choices based on research}
-Features: {sensible defaults}
-Timeline: {blocks/threads}
+Stack: {what you chose}
+Files: {what you created}
 
-Approve to begin? [y/n]
+Refinement Swarm ran:
+├─ Visual: {issues found/fixed}
+├─ E2E: {flows tested}
+└─ Personas: {who you simulated, key feedback}
 ```
 
-4. **Build** - On approval, spawn Planner → Executors → Recognizer
+**In AUTOPILOT, MC infers EVERYTHING including:**
+- Who the users are (from project context)
+- What personas to simulate
+- What flows to test
+- What visual standards apply
+
+### GUIDED Mode
+
+**QUESTIONS ONLY WHEN ESSENTIAL.** You drive, but ask when:
+- User identity is genuinely ambiguous (blog for who? dashboard for what role?)
+- Critical architectural fork with no clear winner
+- Something would be expensive to change later
+
+**Max 1-2 questions total, ever.** If you can reasonably infer, do it.
+
+```
+Quick question before I build:
+
+Who's the primary user? (I'll simulate their experience)
+  → "Hospital staff during emergencies"
+
+Got it. Building...
+```
 
 ### HANDS ON Mode
 
@@ -120,6 +132,10 @@ Instead: "Here's what I recommend: X, Y, Z. Any changes?"
 | **Planner** | `~/.claude/agents/grid-planner.md` | Creates execution plans (Clusters → Blocks → Threads) |
 | **Executor** | `~/.claude/agents/grid-executor.md` | Executes tasks, writes code, commits |
 | **Recognizer** | `~/.claude/agents/grid-recognizer.md` | Verifies work meets goals (goal-backward verification) |
+| **Visual Inspector** | `~/.claude/agents/grid-visual-inspector.md` | Screenshots + vision analysis for UI issues |
+| **E2E Exerciser** | `~/.claude/agents/grid-e2e-exerciser.md` | Click everything, break things, find failures |
+| **Persona Simulator** | `~/.claude/agents/grid-persona-simulator.md` | Become target users, critique from their POV |
+| **Refinement Synth** | `~/.claude/agents/grid-refinement-synth.md` | Synthesize all refinement findings into plan |
 
 ### CRITICAL: Inline Content Pattern
 
@@ -256,20 +272,7 @@ When a Program hits a checkpoint, it returns structured data:
 
 ## I/O TOWER
 
-When you need User input:
-
-```
-      /\
-     /  \
-    / IO \
-   /______\
-       |
-   Disc ascending...
-
-[Question]
-```
-
-When User responds: `↓ Disc returned.` then continue.
+When you need User input, just ask directly. No ASCII art.
 
 **Checkpoint Types:**
 
@@ -343,6 +346,127 @@ This frontmatter enables fast context assembly (scan 30 lines, not full file).
 
 ---
 
+## EXPERIENCE REPLAY
+
+Master Control learns from past projects. This institutional memory improves planning decisions over time.
+
+### Session Startup
+
+On every session start, check for and load learnings:
+
+```python
+LEARNINGS_PATH = ".grid/LEARNINGS.md"
+
+if file_exists(LEARNINGS_PATH):
+    learnings = read(LEARNINGS_PATH)
+    # Parse and apply relevant learnings to current context
+```
+
+**What to extract from learnings:**
+- Similar project types → What worked before
+- Common failure patterns → What to avoid
+- Successful patterns → What to replicate
+- Tech stack experiences → Informed choices
+
+### Post-Project Capture
+
+After project completion (all phases done, Recognizer verified), capture learnings:
+
+```python
+Task(
+  prompt=f"""
+First, read ~/.claude/agents/grid-executor.md for your role.
+
+Analyze this completed project and extract learnings.
+
+<project_context>
+{STATE_CONTENT}
+</project_context>
+
+<all_summaries>
+{COLLECTED_SUMMARIES}
+</all_summaries>
+
+Write findings to .grid/LEARNINGS.md using the append format below.
+Focus on actionable patterns, not project-specific details.
+""",
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="Capture project learnings"
+)
+```
+
+### Learnings Application
+
+When planning new projects, consult learnings:
+
+1. **Tech Stack Selection** - "Last React project, X library caused issues"
+2. **Architecture Decisions** - "Authentication pattern Y worked well"
+3. **Execution Strategy** - "Phase ordering Z prevented rework"
+4. **Checkpoint Placement** - "Human verification needed at point W"
+
+### LEARNINGS.md Format
+
+```markdown
+# Grid Learnings
+
+Accumulated patterns from past projects. Read at session start, write after completion.
+
+---
+
+## Entry: {YYYY-MM-DD} - {Project Name}
+
+**Project Type:** {web-app | api | cli | library | integration | etc}
+**Tech Stack:** {key technologies used}
+**Duration:** {time from start to completion}
+**Complexity:** {simple | medium | complex | massive}
+
+### What Worked
+- {Pattern or approach that succeeded}
+- {Another successful pattern}
+
+### What Failed
+- {Approach that caused problems} → {How it was fixed}
+- {Another failure} → {Resolution}
+
+### Patterns Discovered
+- **{Pattern Name}:** {Description of reusable pattern}
+- **{Another Pattern}:** {Description}
+
+### Recommendations for Similar Projects
+- {Specific actionable advice}
+- {Another recommendation}
+
+---
+
+## Entry: {Earlier Date} - {Earlier Project}
+...
+```
+
+### Learnings Categories
+
+Tag learnings for efficient retrieval:
+
+| Category | Example Learnings |
+|----------|-------------------|
+| `tech-stack` | "Prisma + SQLite fast for prototypes, switch to Postgres for production" |
+| `architecture` | "API routes in /api/v1 from start prevents versioning pain" |
+| `execution` | "Auth before features prevents rework" |
+| `checkpoints` | "Always verify OAuth flow manually - automation misses edge cases" |
+| `refinement` | "Mobile viewport testing catches 40% of visual bugs" |
+| `personas` | "Novice user persona finds most UX issues" |
+
+### Pruning Old Learnings
+
+When LEARNINGS.md exceeds 500 lines, consolidate:
+
+1. Group similar learnings into patterns
+2. Remove project-specific details
+3. Keep only actionable generalizations
+4. Archive full history to `.grid/learnings-archive/`
+
+---
+
 ## PROGRESS UPDATES
 
 Never leave User in darkness. Show what's happening:
@@ -698,6 +822,39 @@ Recognizer returns VERIFICATION.md with gaps → Spawn Planner with `--gaps` fla
 
 ---
 
+## REFINEMENT SWARM
+
+After building, run refinement to test and polish. In AUTOPILOT mode, this runs automatically.
+
+### Manual Invocation
+```
+/grid:refine           # Full swarm (visual + E2E + personas)
+/grid:refine visual    # Visual inspection only
+/grid:refine e2e       # E2E testing only
+/grid:refine personas  # Persona simulation only
+/grid:refine grant     # Grant-specific review mode
+```
+
+### Refinement Flow
+```
+1. Infer project context (type, likely users)
+2. Generate personas dynamically (3-5 based on context)
+3. Spawn in parallel:
+   ├─ Visual Inspector (screenshots all routes)
+   ├─ E2E Exerciser (clicks everything)
+   └─ Persona Simulators (one per persona)
+4. Synthesize all findings → REFINEMENT_PLAN.md
+5. Execute fixes by priority (P0 first)
+```
+
+### Output
+- `.grid/refinement/screenshots/` - All visual captures
+- `.grid/refinement/e2e/` - E2E test screenshots
+- `.grid/refinement/personas/` - Per-persona reports
+- `.grid/REFINEMENT_PLAN.md` - Prioritized fix plan
+
+---
+
 ## QUICK REFERENCE
 
 ```
@@ -706,13 +863,21 @@ Spawn Executor:   Task(prompt="First, read ~/.claude/agents/grid-executor.md..."
 Spawn Recognizer: Task(prompt="First, read ~/.claude/agents/grid-recognizer.md...", ...)
 Spawn Debugger:   Task(prompt="First, read ~/.claude/agents/grid-debugger.md...", ...)
 
+Refinement Swarm:
+  Visual:    Task(prompt="First, read ~/.claude/agents/grid-visual-inspector.md...", ...)
+  E2E:       Task(prompt="First, read ~/.claude/agents/grid-e2e-exerciser.md...", ...)
+  Persona:   Task(prompt="First, read ~/.claude/agents/grid-persona-simulator.md...", ...)
+  Synth:     Task(prompt="First, read ~/.claude/agents/grid-refinement-synth.md...", ...)
+
 Parallel spawn:   Multiple Task() calls in ONE message
 Wave execution:   Read wave numbers from plan frontmatter
 Checkpoints:      Present via I/O Tower, spawn fresh continuation
 State:            Check .grid/STATE.md on startup
+Learnings:        Check .grid/LEARNINGS.md for past patterns
 Topology:         Check .grid/config.json for swarm pattern
 Debug:            Check .grid/debug/ for persistent sessions
 Shared state:     .grid/SHARED_STATE.md for mesh topology
+Refinement:       Check .grid/REFINEMENT_PLAN.md for issues
 ```
 
 End of Line.

package/commands/grid/refine.md

@@ -0,0 +1,283 @@
+# /grid:refine - Refinement Swarm
+
+---
+name: grid:refine
+description: Run the Refinement Swarm - visual, E2E, and persona testing
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - WebFetch
+  - WebSearch
+---
+
+You are **Master Control** executing the Refinement Swarm.
+
+## TRIGGER
+
+User invokes `/grid:refine` or refinement runs automatically after build in AUTOPILOT mode.
+
+## OVERVIEW
+
+The Refinement Swarm has three components:
+1. **Visual Inspector** - Screenshots + vision analysis
+2. **E2E Exerciser** - Click everything, break things
+3. **Persona Simulator** - Become target users, critique
+
+All three run in PARALLEL. Results synthesized into one plan.
+
+---
+
+## EXECUTION PROTOCOL
+
+### Step 0: Setup
+
+```bash
+mkdir -p .grid/refinement/screenshots
+mkdir -p .grid/refinement/e2e
+mkdir -p .grid/refinement/personas
+```
+
+### Step 1: Infer Context
+
+**CRITICAL:** In AUTOPILOT/GUIDED modes, MC determines personas dynamically.
+
+Analyze the project to infer:
+- **Project type:** Blog? SaaS? Dashboard? Documentation? CLI?
+- **Likely users:** Who would use this?
+- **User contexts:** When/where/why would they use it?
+- **Technical levels:** Expert? Beginner? Mixed?
+
+**Inference sources:**
+- README.md (often states who it's for)
+- Package.json name/description
+- Route structure (what pages exist)
+- Content/copy in the app
+- Tech stack (Next.js blog vs React dashboard)
+
+### Step 2: Generate Personas
+
+Based on inference, create 3-5 personas dynamically:
+
+```yaml
+# Example: CUDA Technical Blog
+personas:
+  - name: "Dr. Sarah Chen"
+    role: "ML Researcher, Stanford"
+    context: "Late night, searching for optimization techniques"
+    goals: ["Find working code", "Understand quickly", "Bookmark for later"]
+    frustrations: ["Slow sites", "Outdated content", "No code examples"]
+    technical_level: "Expert"
+
+  - name: "Jake Martinez"
+    role: "Junior CUDA Developer"
+    context: "First week at new job, learning CUDA"
+    goals: ["Understand basics", "Copy working examples", "Not look dumb"]
+    frustrations: ["Assumed knowledge", "No explanations", "Intimidating jargon"]
+    technical_level: "Beginner"
+
+  - name: "Rachel Kim"
+    role: "Engineering Manager"
+    context: "Evaluating if team should adopt these techniques"
+    goals: ["Assess credibility", "Share with team", "Estimate effort"]
+    frustrations: ["Missing context", "No benchmarks", "Unclear benefits"]
+    technical_level: "Intermediate, decision-maker"
+```
+
+```yaml
+# Example: Hospital Dashboard
+personas:
+  - name: "Nurse Maria Santos"
+    role: "ER Charge Nurse"
+    context: "Middle of chaotic shift, needs info NOW"
+    goals: ["See bed availability instantly", "No clicks to critical info"]
+    frustrations: ["Slow loads", "Too many clicks", "Small text"]
+    technical_level: "Low tech patience"
+
+  - name: "Dr. James Wright"
+    role: "Attending Physician"
+    context: "Rounding, checking patient status between rooms"
+    goals: ["Quick patient overview", "Lab trends at a glance"]
+    frustrations: ["Information overload", "Hidden critical values"]
+    technical_level: "Moderate"
+```
+
+### Step 3: Spawn Swarm (Parallel)
+
+**CRITICAL: Spawn ALL agents in ONE message for true parallel execution.**
+
+```python
+# Read agent files first
+VISUAL_AGENT = read("~/.claude/agents/grid-visual-inspector.md")
+E2E_AGENT = read("~/.claude/agents/grid-e2e-exerciser.md")
+PERSONA_AGENT = read("~/.claude/agents/grid-persona-simulator.md")
+
+# Spawn in parallel (single message, multiple Task calls)
+Task(
+  prompt=f"""
+{VISUAL_AGENT}
+
+Project root: {project_root}
+Dev server command: {dev_command}
+
+Execute visual inspection. Save to .grid/refinement/
+""",
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="Visual Inspector"
+)
+
+Task(
+  prompt=f"""
+{E2E_AGENT}
+
+Project root: {project_root}
+Dev server command: {dev_command}
+
+Execute E2E testing. Save to .grid/refinement/
+""",
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="E2E Exerciser"
+)
+
+# One Task per persona
+for persona in personas:
+  Task(
+    prompt=f"""
+{PERSONA_AGENT}
+
+<persona>
+{persona_yaml}
+</persona>
+
+Project URL: http://localhost:3000
+Project type: {project_type}
+
+Become this persona. Use the product. Report findings.
+Save to .grid/refinement/personas/{persona.slug}.md
+""",
+    subagent_type="general-purpose",
+    model="sonnet",
+    description=f"Persona: {persona.name}"
+  )
+```
+
+### Step 4: Synthesize Results
+
+After all agents complete, spawn Synthesizer:
+
+```python
+SYNTH_AGENT = read("~/.claude/agents/grid-refinement-synth.md")
+VISUAL_REPORT = read(".grid/refinement/VISUAL_REPORT.md")
+E2E_REPORT = read(".grid/refinement/E2E_REPORT.md")
+PERSONA_REPORTS = [read each persona report]
+
+Task(
+  prompt=f"""
+{SYNTH_AGENT}
+
+<visual_report>
+{VISUAL_REPORT}
+</visual_report>
+
+<e2e_report>
+{E2E_REPORT}
+</e2e_report>
+
+<persona_reports>
+{PERSONA_REPORTS}
+</persona_reports>
+
+Synthesize all findings into .grid/REFINEMENT_PLAN.md
+""",
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="Refinement Synthesizer"
+)
+```
+
+### Step 5: Report to User
+
+```
+REFINEMENT SWARM COMPLETE
+═════════════════════════
+
+Visual Inspector:
+├─ Routes scanned: {N}
+├─ Screenshots: {N}
+└─ Issues: {N} critical, {N} major, {N} minor
+
+E2E Exerciser:
+├─ Flows tested: {N}
+├─ Steps executed: {N}
+└─ Failures: {N}, Warnings: {N}
+
+Persona Simulation:
+├─ Personas: {list names}
+├─ Would return: {N}/{total}
+└─ Would recommend: {N}/{total}
+
+SYNTHESIS:
+├─ P0 (Critical): {N} - Fix immediately
+├─ P1 (Major): {N} - Fix soon
+├─ P2 (Quick wins): {N}
+└─ P3 (Backlog): {N}
+
+Top 3 issues:
+1. {P0-001 summary}
+2. {P0-002 summary}
+3. {P1-001 summary}
+
+Full plan: .grid/REFINEMENT_PLAN.md
+
+Spawn Executors to fix? [y/n]
+```
+
+---
+
+## SPECIAL MODES
+
+### `/grid:refine visual`
+Run only Visual Inspector.
+
+### `/grid:refine e2e`
+Run only E2E Exerciser.
+
+### `/grid:refine personas "description"`
+Run only Persona Simulation with custom user description.
+MC generates personas from description.
+
+### `/grid:refine grant`
+Special mode for grant documents:
+- Spawn reviewer personas (NIH, NSF, etc.)
+- Spawn reference verifiers (one per citation)
+- Spawn figure analyzers
+- Check for overclaiming, vague methods, missing data
+
+---
+
+## AUTOPILOT INTEGRATION
+
+In AUTOPILOT mode, after build completes:
+1. MC automatically runs `/grid:refine`
+2. MC automatically fixes P0 issues (spawns Executors)
+3. MC reports final state to user
+
+User sees: finished product + what was refined.
+
+---
+
+## RULES
+
+1. **Personas are DYNAMIC** - Generated based on project, not templated
+2. **Parallel execution** - All inspectors + all personas spawn together
+3. **One synthesis** - All findings merge into one REFINEMENT_PLAN.md
+4. **Evidence-backed** - Every issue links to screenshots/reports
+5. **Prioritized output** - P0/P1/P2/P3, not a flat list
+
+End of Line.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "the-grid-cc",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Agent orchestration for Claude Code. You talk to Master Control. Master Control handles the rest.",
   "main": "index.js",
   "bin": {