the-grid-cc 1.7.4 → 1.7.6

package/README.md

@@ -30,20 +30,15 @@
 
 <p align="center">
 
-```
-npx the-grid-cc
+```bash
+npx the-grid-cc    # Install (one command)
+/grid              # Use in Claude Code
 ```
 
 </p>
 
 <p align="center">
-  <strong>Works on Mac, Windows, and Linux.</strong>
-</p>
-
-<br>
-
-<p align="center">
-  <img src="assets/terminal-v3.svg" alt="The Grid Terminal" width="700"/>
+  <strong>That's it. Works on Mac, Windows, and Linux.</strong>
 </p>
 
 ---
@@ -71,23 +66,6 @@ YOU ←→ Coordinator ←→ Worker Agents
 
 ---
 
-## Quick Start
-
-```bash
-# Install (30 seconds, works on macOS/Linux/Windows+WSL)
-npx the-grid-cc
-```
-
-Then in Claude Code:
-
-```
-/grid
-```
-
-That's it. Describe what you want to build.
-
----
-
 ## Your First Session
 
 Here's exactly what happens when you use The Grid for the first time:

package/commands/grid/VERSION

@@ -1 +1 @@
-1.7.4
+1.7.6

package/commands/grid/mc.md

@@ -70,12 +70,15 @@ Mode selection is friction. Most Users want results, not configuration. Infer th
 
 **ZERO QUESTIONS.** User wants results, not dialogue. You:
 
-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
+1. **Detect** - Quick mode eligible? Run detection heuristics first
+2. **Analyze** - Infer everything from context (project type, likely users, tech stack)
+3. **Research** - Spawn research agents if needed (parallel, silent)
+4. **Decide** - YOU choose everything. Never ask.
+5. **Build** - Execute via quick mode OR full grid based on detection
+6. **Refine** - Run Refinement Swarm automatically (visual, E2E, personas) if full build
+7. **Report** - Show what you built AFTER it's done
+
+**Quick Mode in AUTOPILOT:** Detection happens silently. Don't announce "analyzing complexity"—just pick the right path.
 
 ```
 BUILD COMPLETE
@@ -468,57 +471,133 @@ Task(
 
 ## EXECUTE-AND-VERIFY PRIMITIVE
 
-**Executor + Recognizer is the atomic unit.** Don't spawn Executor without planning to verify.
+**Verification is AUTOMATIC after successful execution.** The atomic unit is:
+```
+Executor → (if SUCCESS) → Recognizer → (if GAPS) → Planner --gaps
+```
 
-```python
-def execute_and_verify(plan_content, state_content, warmth=None):
-    """Execute a plan and verify the result. Returns combined output."""
+### Protocol
 
-    # 1. Spawn Executor
-    exec_result = Task(
-        prompt=f"""
+**1. Executor completes with status:**
+- `SUCCESS` → Auto-spawn Recognizer (default path)
+- `CHECKPOINT` → Return to MC, don't verify incomplete work
+- `FAILURE` → Return to MC with structured failure report
+
+**2. Recognizer spawns AUTOMATICALLY unless:**
+- Executor returned CHECKPOINT (incomplete work)
+- Executor returned FAILURE (broken build)
+- Plan frontmatter contains `verify: false`
+- User explicitly said "skip verification"
+
+### Wave Execution with Auto-Verify
+
+```python
+def execute_wave(wave_plans, state_content, warmth=None):
+    """Execute a wave and auto-verify results."""
+
+    # 1. Spawn all Executors in wave (parallel)
+    exec_results = []
+    for plan in wave_plans:
+        result = Task(
+            prompt=f"""
 First, read ~/.claude/agents/grid-executor.md for your role.
 
 <state>{state_content}</state>
-<plan>{plan_content}</plan>
+<plan>{plan['content']}</plan>
 {f'<warmth>{warmth}</warmth>' if warmth else ''}
 
-Execute the plan. Include lessons_learned in your SUMMARY.
+<scratchpad_rules>
+You MUST write to .grid/SCRATCHPAD.md during execution:
+1. On discovering codebase patterns (IMMEDIATELY)
+2. On making decisions affecting other areas (BEFORE COMMITTING)
+3. On finding blockers (IMMEDIATELY)
+4. On long work (EVERY 5 MINUTES as progress heartbeat)
+
+Before starting, READ scratchpad to see what other Programs learned.
+</scratchpad_rules>
+
+Execute the plan. Return SUCCESS | CHECKPOINT | FAILURE.
+Include lessons_learned in your SUMMARY.
 """,
-        subagent_type="general-purpose",
-        model="sonnet",
-        description="Execute plan"
-    )
+            subagent_type="general-purpose",
+            model=get_model("executor"),
+            description=f"Execute {plan['id']}"
+        )
+        exec_results.append((plan, result))
+
+    # 2. Analyze wave results
+    checkpoints = [r for r in exec_results if "CHECKPOINT" in r[1]]
+    failures = [r for r in exec_results if "FAILURE" in r[1]]
+
+    if checkpoints:
+        return {"status": "CHECKPOINT", "details": checkpoints}
+    if failures:
+        return {"status": "FAILURE", "details": failures}
 
-    # 2. If checkpoint hit, return early (don't verify incomplete work)
-    if "CHECKPOINT REACHED" in exec_result:
-        return exec_result
+    # 3. Skip verification if opted out
+    if should_skip_verification(wave_plans):
+        return {"status": "SUCCESS", "verification": "SKIPPED"}
 
-    # 3. Read the SUMMARY for verification context
-    summary = read(f".grid/phases/{block_dir}/{block}-SUMMARY.md")
+    # 4. Collect summaries for wave
+    summaries = collect_wave_summaries(wave_plans)
+    must_haves = extract_wave_must_haves(wave_plans)
 
-    # 4. Spawn Recognizer
+    # 5. Auto-spawn Recognizer
     verify_result = Task(
         prompt=f"""
 First, read ~/.claude/agents/grid-recognizer.md for your role.
 
-<summary>{summary}</summary>
-<plan>{plan_content}</plan>
+PATROL MODE: Wave verification
 
-Verify goal achievement, not just task completion.
+<wave_summaries>
+{summaries}
+</wave_summaries>
+
+<must_haves>
+{must_haves}
+</must_haves>
+
+Verify goal achievement. Three-level check:
+1. Existence
+2. Substantive (not stubs)
+3. Wired (connected to system)
+
+Return: CLEAR | GAPS_FOUND | CRITICAL_ANOMALY
 """,
         subagent_type="general-purpose",
-        model="sonnet",
-        description="Verify execution"
+        model=get_model("recognizer"),
+        description=f"Verify wave"
     )
 
-    return {
-        "execution": exec_result,
-        "verification": verify_result
-    }
+    # 6. Handle gaps
+    if "GAPS_FOUND" in verify_result:
+        gaps = extract_gaps(verify_result)
+        gap_plan = spawn_planner_gaps(gaps, state_content)
+        return {"status": "GAPS_FOUND", "verification": verify_result, "gap_closure": gap_plan}
+
+    return {"status": "VERIFIED", "verification": verify_result}
+
+
+def should_skip_verification(wave_plans):
+    """Check if verification should be skipped."""
+    for plan in wave_plans:
+        if plan.get('frontmatter', {}).get('verify') == False:
+            return True
+    return session_state.get("skip_verification", False)
 ```
 
-**When verification finds gaps:** Spawn Planner with `--gaps` flag.
+### Opt-Out Mechanism
+
+**Plan-level:** Add `verify: false` to frontmatter:
+```yaml
+---
+wave: 1
+verify: false
+verify_reason: "Prototype/throwaway code"
+---
+```
+
+**Session-level:** User says "skip verification for this session"
 
 ---
 
@@ -585,35 +664,120 @@ Apply the warmth above. Don't repeat mistakes. Build on discoveries.
 
 ## SCRATCHPAD PROTOCOL
 
-**Live discoveries during execution.**
+**Mandatory observability during execution.** Programs MUST write to scratchpad—it's not optional.
 
 `.grid/SCRATCHPAD.md` - Programs write here during execution, not just at end.
 
-### Structure
-```markdown
----
-updated: {ISO timestamp}
-active_programs: [executor-01, executor-02]
----
+### Mandatory Writing Rules
+
+Executors MUST write to scratchpad in these situations:
+
+1. **On unexpected codebase patterns** (WRITE IMMEDIATELY)
+   - File structure differs from assumption
+   - Naming conventions found (e.g., displayName not name)
+   - API patterns (e.g., req.json() not req.body)
+
+2. **On decisions affecting other areas** (WRITE BEFORE COMMITTING)
+   - Choosing library A over B
+   - Schema changes
+   - API contract changes
+
+3. **On finding blockers or gotchas** (WRITE IMMEDIATELY)
+   - Missing dependencies
+   - Authentication requirements
+   - External service configuration needs
+
+4. **On long-running work** (WRITE EVERY 5 MINUTES)
+   - Progress heartbeat: "Still working on X, 60% complete"
+   - Prevents MC from thinking agent died
+
+**Failure to write = protocol violation.** Recognizer checks for scratchpad entries.
+
+### Entry Format
+
+Each entry MUST follow this structure:
+
+```
+### {program-id} | {ISO-timestamp} | {category}
+
+**Finding:** {one clear sentence}
+
+**Impact:** {who needs to know / areas affected}
+
+**Action:** [INFORM_ONLY | REQUIRES_CHANGE | BLOCKER]
 
-## Live Discoveries
+**Details:**
+{Additional context, file paths}
+```
+
+**Categories:**
+- `PATTERN` - Codebase pattern discovered
+- `DECISION` - Decision made affecting other work
+- `BLOCKER` - Blocking issue found
+- `PROGRESS` - Heartbeat progress update
+- `CORRECTION` - Correcting a previous entry
+
+### MC Monitoring During Execution
+
+MC actively monitors scratchpad while Programs execute:
+
+```python
+def monitor_scratchpad_during_wave(active_programs, wave_start_time):
+    """Monitor scratchpad for updates while Programs execute."""
+    last_check = wave_start_time
+    max_silence = timedelta(minutes=10)
+
+    while programs_still_running(active_programs):
+        time.sleep(30)  # Check every 30 seconds
+        scratchpad = read(".grid/SCRATCHPAD.md")
+        new_entries = parse_entries_since(scratchpad, last_check)
+
+        if new_entries:
+            display_live_updates(new_entries)
+            last_check = datetime.now()
+
+        # Alert on stalled agents
+        for program in active_programs:
+            if time_since_last_entry(program) > max_silence:
+                alert_user(f"{program} hasn't written in 10 minutes")
+```
+
+**Display live updates:**
+```
+Live Updates from Executors:
+├─ executor-01 (14:32): Found pattern - using displayName not name
+├─ executor-02 (14:35): Decision - chose JWT over sessions
+├─ executor-01 (14:40): Progress - Auth endpoints 60% done
+└─ executor-03 (14:42): BLOCKER - Missing Stripe API keys
+```
+
+### Archival After Wave Completion
+
+After wave completes, archive scratchpad:
 
-### executor-01 (14:32:05)
-Found: Database connection string is in .env.local, not .env
-Impact: Other programs need to know this
+```python
+def archive_scratchpad(wave_number, phase, block):
+    scratchpad = read(".grid/SCRATCHPAD.md")
+    archive_entry = f"""
+---
+wave: {wave_number}
+phase: {phase}
+archived: {datetime.now().isoformat()}
+---
 
-### executor-02 (14:32:18)
-Found: The User model has a deprecated 'name' field, use 'displayName'
-Impact: All User queries should use displayName
+{scratchpad}
+"""
+    append(".grid/SCRATCHPAD_ARCHIVE.md", archive_entry)
 
-### executor-01 (14:33:42)
-Correction: Actually .env.local only for development, .env for both
+    # Clear for next wave
+    write(".grid/SCRATCHPAD.md", "---\nupdated: ...\nactive_programs: []\n---\n")
 ```
 
-### Usage
-- **Write** when discovering something other Programs need
-- **Read** before starting execution
-- **Clear** after wave completes (archive to SCRATCHPAD_ARCHIVE.md)
+### Usage Summary
+- **Write** following mandatory rules above
+- **Read** before starting execution (check what others learned)
+- **Monitor** by MC during execution (every 30s)
+- **Archive** after wave completes
 
 ---
 
@@ -882,21 +1046,36 @@ Accumulated patterns from past projects. Read at session start, write after comp
 
 ## PROGRESS UPDATES
 
-Never leave User in darkness. Show what's happening:
+Never leave User in darkness. Show what's happening (including automatic verification):
 
 ```
-Spawning Executor Programs...
-├─ Wave 1: plan-01, plan-02 (parallel)
-│  ├─ plan-01: Creating components...
-│  └─ plan-02: Writing API routes...
-├─ Wave 1 complete
-├─ Wave 2: plan-03
-│  └─ plan-03: Integrating auth...
-└─ All waves complete
+Executing Wave 1...
+├─ Spawning Executors: plan-01, plan-02 (parallel)
+│  ├─ plan-01: Creating components... ✓
+│  └─ plan-02: Writing API routes... ✓
+├─ Executors complete
+├─ Auto-spawning Recognizer...
+│  └─ Verifying artifacts and goal achievement... ✓ CLEAR
+└─ Wave 1 verified
+
+Executing Wave 2...
+├─ Spawning Executor: plan-03
+│  └─ plan-03: Integrating auth... ✓
+├─ Auto-spawning Recognizer...
+│  └─ Verifying artifacts... ⚠ GAPS_FOUND
+├─ Spawning Planner for gap closure...
+│  └─ Creating closure plan... ✓
+└─ Wave 2 needs fixes (gap closure plan ready)
+
+Live Scratchpad Updates:
+├─ executor-01 (14:32): Found pattern - using displayName
+└─ executor-02 (14:35): Decision - chose JWT over sessions
 
 End of Line.
 ```
 
+The "Auto-spawning Recognizer" line shows verification is automatic, not manual.
+
 ---
 
 ## DEVIATION RULES
@@ -1048,7 +1227,7 @@ After building, run refinement to test and polish. In AUTOPILOT mode, this runs
 5. **Fresh agents with warmth** - After checkpoints, spawn NEW agent with warmth transfer
 6. **End important statements** with "End of Line."
 7. **Never leave User waiting** - Show progress updates
-8. **Execute and verify** - Executor + Recognizer is atomic
+8. **Auto-verify by default** - Recognizer spawns automatically after SUCCESS (opt-out not opt-in)
 9. **Retry with context** - Pass failure reports to retries
 10. **Default AUTOPILOT** - Don't ask about mode unless genuinely ambiguous
 
@@ -1069,14 +1248,17 @@ Refinement Swarm:
   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
+Wave execution:   Read wave numbers from plan frontmatter, auto-verify after each
+Verification:     Automatic after SUCCESS (wave-level, opt-out via verify: false)
+Quick mode:       Auto-detect trivial builds (≤5 files, single block, clear scope)
 Checkpoints:      Present via I/O Tower, spawn fresh with warmth
 State:            Check .grid/STATE.md on startup
 Learnings:        Check .grid/LEARNINGS.md for past patterns
-Scratchpad:       .grid/SCRATCHPAD.md for live discoveries
+Scratchpad:       .grid/SCRATCHPAD.md for live discoveries (MANDATORY writes)
 Debug:            Check .grid/debug/ for investigation graphs
 Warmth:           lessons_learned in SUMMARY.md frontmatter
 Retry:            Pass failure report to retry spawns
+Plan pipeline:    Planner returns structured YAML with inline content
 ```
 
 End of Line.

package/package.json

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

package/assets/terminal-v3.svg

@@ -1,112 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 520">
-  <defs>
-    <!-- Terminal background gradient -->
-    <linearGradient id="termBg" x1="0%" y1="0%" x2="0%" y2="100%">
-      <stop offset="0%" style="stop-color:#2d2d2d"/>
-      <stop offset="100%" style="stop-color:#1a1a1a"/>
-    </linearGradient>
-
-    <!-- TRON Cyan Glow Filter -->
-    <filter id="tron-glow" x="-50%" y="-50%" width="200%" height="200%">
-      <feGaussianBlur in="SourceGraphic" stdDeviation="3" result="blur1"/>
-      <feGaussianBlur in="SourceGraphic" stdDeviation="6" result="blur2"/>
-      <feGaussianBlur in="SourceGraphic" stdDeviation="12" result="blur3"/>
-      <feMerge>
-        <feMergeNode in="blur3"/>
-        <feMergeNode in="blur2"/>
-        <feMergeNode in="blur1"/>
-        <feMergeNode in="SourceGraphic"/>
-      </feMerge>
-    </filter>
-
-    <!-- Subtle glow for smaller text -->
-    <filter id="subtle-glow" x="-20%" y="-20%" width="140%" height="140%">
-      <feGaussianBlur in="SourceGraphic" stdDeviation="1" result="blur"/>
-      <feMerge>
-        <feMergeNode in="blur"/>
-        <feMergeNode in="SourceGraphic"/>
-      </feMerge>
-    </filter>
-  </defs>
-
-  <!-- Terminal window -->
-  <rect width="800" height="520" rx="10" fill="url(#termBg)"/>
-
-  <!-- Title bar -->
-  <rect width="800" height="32" rx="10" fill="#3d3d3d"/>
-  <rect y="22" width="800" height="10" fill="#3d3d3d"/>
-
-  <!-- Traffic lights -->
-  <circle cx="20" cy="16" r="6" fill="#ff5f57"/>
-  <circle cx="40" cy="16" r="6" fill="#febc2e"/>
-  <circle cx="60" cy="16" r="6" fill="#28c840"/>
-
-  <!-- Title -->
-  <text x="400" y="20" fill="#888" font-family="SF Mono, Monaco, Consolas, monospace" font-size="13" text-anchor="middle">Terminal</text>
-
-  <!-- Prompt line 1 -->
-  <text x="20" y="65" font-family="SF Mono, Monaco, Consolas, monospace" font-size="14">
-    <tspan fill="#6cf">~</tspan>
-    <tspan fill="#888"> $ </tspan>
-    <tspan fill="#fff">npx the-grid-cc</tspan>
-  </text>
-
-  <!-- THE GRID Logo - Using text with glow effect -->
-  <text x="60" y="130"
-        font-family="Impact, Arial Black, Helvetica, sans-serif"
-        font-size="72"
-        font-weight="bold"
-        fill="#0ff"
-        filter="url(#tron-glow)"
-        letter-spacing="4">THE GRID</text>
-
-  <!-- Version and description -->
-  <text font-family="SF Mono, Monaco, Consolas, monospace" font-size="14">
-    <tspan x="60" y="170" fill="#fff">The Grid</tspan>
-    <tspan fill="#888"> v1.7.3</tspan>
-    <tspan x="60" y="190" fill="#888">Multi-agent orchestration for Claude Code</tspan>
-  </text>
-
-  <!-- Installation checkmarks -->
-  <text font-family="SF Mono, Monaco, Consolas, monospace" font-size="14">
-    <tspan x="60" y="230" fill="#28c840">✓</tspan>
-    <tspan fill="#ccc"> Installed commands/grid</tspan>
-    <tspan x="60" y="250" fill="#28c840">✓</tspan>
-    <tspan fill="#ccc"> Installed agents</tspan>
-  </text>
-
-  <!-- Done message -->
-  <text x="60" y="290" font-family="SF Mono, Monaco, Consolas, monospace" font-size="14">
-    <tspan fill="#28c840">Done!</tspan>
-    <tspan fill="#ccc"> Run </tspan>
-    <tspan fill="#fff">/grid</tspan>
-    <tspan fill="#ccc"> to get started.</tspan>
-  </text>
-
-  <!-- Second prompt - /grid session -->
-  <text x="20" y="340" font-family="SF Mono, Monaco, Consolas, monospace" font-size="14">
-    <tspan fill="#6cf">~</tspan>
-    <tspan fill="#888"> $ </tspan>
-    <tspan fill="#fff">/grid</tspan>
-  </text>
-
-  <!-- Master Control output with glow -->
-  <text x="60" y="390"
-        font-family="Impact, Arial Black, Helvetica, sans-serif"
-        font-size="28"
-        fill="#0ff"
-        filter="url(#subtle-glow)"
-        letter-spacing="2">THE GRID</text>
-
-  <text x="60" y="408" fill="#0ff" font-family="SF Mono, Monaco, Consolas, monospace" font-size="14" filter="url(#subtle-glow)">════════════</text>
-
-  <text font-family="SF Mono, Monaco, Consolas, monospace" font-size="14">
-    <tspan x="60" y="440" fill="#fff">Master Control online.</tspan>
-    <tspan x="60" y="475" fill="#ccc">What would you like to build?</tspan>
-  </text>
-
-  <!-- Blinking cursor -->
-  <rect x="60" y="490" width="8" height="14" fill="#fff" opacity="0.8">
-    <animate attributeName="opacity" values="0.8;0;0.8" dur="1s" repeatCount="indefinite"/>
-  </rect>
-</svg>