the-grid-cc 1.5.0 → 1.7.0

package/commands/grid/mc.md

@@ -50,19 +50,23 @@ No boxes. No bloat. Just direct communication.
 
 ---
 
-## MODE SELECTION
+## MODE BEHAVIOR
 
-After User states what they want to build, ask ONE question:
+**Default: AUTOPILOT.** Don't ask. Just build.
 
-```
-How involved do you want to be?
+Mode selection is friction. Most Users want results, not configuration. Infer the right mode:
 
-  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.
-```
+| User Signal | Mode | Behavior |
+|-------------|------|----------|
+| "build X", "make X", "create X" | AUTOPILOT | Zero questions, just build |
+| "help me with", "let's", "I want" | GUIDED | Minimal questions (max 1-2) |
+| "what should", "options for", "how would" | HANDS ON | Collaborative, but still fast |
 
-### AUTOPILOT Mode
+**Only ask about mode if:**
+- Project is genuinely ambiguous (could be 3+ completely different things)
+- User explicitly asks for control
+
+### AUTOPILOT (Default)
 
 **ZERO QUESTIONS.** User wants results, not dialogue. You:
 
@@ -93,7 +97,7 @@ Refinement Swarm ran:
 - What flows to test
 - What visual standards apply
 
-### GUIDED Mode
+### GUIDED
 
 **QUESTIONS ONLY WHEN ESSENTIAL.** You drive, but ask when:
 - User identity is genuinely ambiguous (blog for who? dashboard for what role?)
@@ -111,7 +115,7 @@ Who's the primary user? (I'll simulate their experience)
 Got it. Building...
 ```
 
-### HANDS ON Mode
+### HANDS ON
 
 User wants control. Use dream extraction questioning (but keep it minimal):
 - Max 2-3 questions total
@@ -123,6 +127,48 @@ Instead: "Here's what I recommend: X, Y, Z. Any changes?"
 
 ---
 
+## SPAWN HEURISTICS
+
+**Don't over-spawn.** More agents ≠ faster. Calculate spawn count:
+
+| Complexity | Indicators | Agents |
+|------------|------------|--------|
+| **Trivial** | 1-2 files, obvious fix | 1 agent |
+| **Simple** | 2-3 files, clear scope | 1-2 agents |
+| **Medium** | 3-6 files, some coupling | 2-3 agents |
+| **Complex** | 6+ files, cross-cutting | 3-5 agents |
+| **Massive** | Architecture change | 5-10 agents |
+
+**Spawn count formula:**
+```python
+def spawn_count(plan):
+    files = len(plan.files_modified)
+
+    # Base count
+    if files <= 2: base = 1
+    elif files <= 5: base = 2
+    elif files <= 10: base = 3
+    else: base = min(files // 3, 10)
+
+    # Adjustments
+    if plan.files_overlap_with_other_plans: base = 1  # Serialize, don't parallelize
+    if plan.has_checkpoints: base = max(1, base - 1)  # Checkpoints slow things down
+
+    return base
+```
+
+**When to parallelize:**
+- Independent subsystems (auth AND dashboard = parallel)
+- No file overlap between plans
+- Fresh context needed anyway
+
+**When NOT to parallelize:**
+- Tightly coupled files (merge conflicts)
+- Discovery dependencies (agent A finds what B needs)
+- Simple tasks (spawn overhead > work)
+
+---
+
 ## PROGRAM SPAWNING PROTOCOL
 
 ### Available Programs
@@ -233,6 +279,157 @@ Task(
 
 ---
 
+## EXECUTE-AND-VERIFY PRIMITIVE
+
+**Executor + Recognizer is the atomic unit.** Don't spawn Executor without planning to verify.
+
+```python
+def execute_and_verify(plan_content, state_content, warmth=None):
+    """Execute a plan and verify the result. Returns combined output."""
+
+    # 1. Spawn Executor
+    exec_result = Task(
+        prompt=f"""
+First, read ~/.claude/agents/grid-executor.md for your role.
+
+<state>{state_content}</state>
+<plan>{plan_content}</plan>
+{f'<warmth>{warmth}</warmth>' if warmth else ''}
+
+Execute the plan. Include lessons_learned in your SUMMARY.
+""",
+        subagent_type="general-purpose",
+        model="sonnet",
+        description="Execute plan"
+    )
+
+    # 2. If checkpoint hit, return early (don't verify incomplete work)
+    if "CHECKPOINT REACHED" in exec_result:
+        return exec_result
+
+    # 3. Read the SUMMARY for verification context
+    summary = read(f".grid/phases/{block_dir}/{block}-SUMMARY.md")
+
+    # 4. Spawn Recognizer
+    verify_result = Task(
+        prompt=f"""
+First, read ~/.claude/agents/grid-recognizer.md for your role.
+
+<summary>{summary}</summary>
+<plan>{plan_content}</plan>
+
+Verify goal achievement, not just task completion.
+""",
+        subagent_type="general-purpose",
+        model="sonnet",
+        description="Verify execution"
+    )
+
+    return {
+        "execution": exec_result,
+        "verification": verify_result
+    }
+```
+
+**When verification finds gaps:** Spawn Planner with `--gaps` flag.
+
+---
+
+## WARMTH TRANSFER PROTOCOL
+
+**Programs die, but their knowledge shouldn't.**
+
+When spawning a continuation or fresh Program after another completes:
+
+### 1. Extract Warmth from Dying Program
+
+Programs include `lessons_learned` in their SUMMARY.md:
+
+```yaml
+---
+# ... other frontmatter
+lessons_learned:
+  codebase_patterns:
+    - "This codebase uses barrel exports (index.ts)"
+    - "API routes expect req.json() not req.body"
+  gotchas:
+    - "The auth middleware runs before validation"
+    - "Database timestamps are UTC, not local"
+  user_preferences:
+    - "User prefers explicit error messages"
+    - "User wants mobile-first styling"
+  almost_did:
+    - "Considered using Zustand but stuck with useState for simplicity"
+---
+```
+
+### 2. Pass Warmth to Fresh Program
+
+```python
+Task(
+  prompt=f"""
+First, read ~/.claude/agents/grid-executor.md for your role.
+
+<warmth>
+Previous Program learned:
+{lessons_learned_yaml}
+</warmth>
+
+<state>{state}</state>
+<plan>{plan}</plan>
+
+Apply the warmth above. Don't repeat mistakes. Build on discoveries.
+""",
+  ...
+)
+```
+
+### 3. Warmth Categories
+
+| Category | Contents |
+|----------|----------|
+| `codebase_patterns` | How this codebase does things |
+| `gotchas` | Traps to avoid |
+| `user_preferences` | What User seems to want |
+| `almost_did` | Decisions considered but rejected (with why) |
+| `fragile_areas` | Code that breaks easily |
+
+---
+
+## SCRATCHPAD PROTOCOL
+
+**Live discoveries during execution.**
+
+`.grid/SCRATCHPAD.md` - Programs write here during execution, not just at end.
+
+### Structure
+```markdown
+---
+updated: {ISO timestamp}
+active_programs: [executor-01, executor-02]
+---
+
+## Live Discoveries
+
+### executor-01 (14:32:05)
+Found: Database connection string is in .env.local, not .env
+Impact: Other programs need to know this
+
+### executor-02 (14:32:18)
+Found: The User model has a deprecated 'name' field, use 'displayName'
+Impact: All User queries should use displayName
+
+### executor-01 (14:33:42)
+Correction: Actually .env.local only for development, .env for both
+```
+
+### Usage
+- **Write** when discovering something other Programs need
+- **Read** before starting execution
+- **Clear** after wave completes (archive to SCRATCHPAD_ARCHIVE.md)
+
+---
+
 ## CHECKPOINT PROTOCOL
 
 When a Program hits a checkpoint, it returns structured data:
@@ -267,6 +464,7 @@ When a Program hits a checkpoint, it returns structured data:
    - Completed threads table
    - User's response
    - Resume point
+   - **Warmth from prior Program**
 
 ---
 
@@ -284,6 +482,64 @@ When you need User input, just ask directly. No ASCII art.
 
 ---
 
+## RETRY PROTOCOL
+
+**When Programs fail, don't retry blind.**
+
+### Structured Failure Report
+
+Programs return on failure:
+```yaml
+## EXECUTION FAILED
+
+**Block:** {block-id}
+**Thread:** {thread that failed}
+**Attempts:** {N}
+
+### What Was Tried
+1. {Approach 1} — Failed because: {reason}
+2. {Approach 2} — Failed because: {reason}
+
+### Partial Work
+- Created: {files created before failure}
+- Commits: {commits made}
+
+### Hypothesis
+{Why it's failing}
+
+### Suggested Retry Approach
+{Different approach to try}
+
+### Do NOT Retry
+- {Approach that definitely won't work}
+```
+
+### Retry Spawning
+
+Pass failure context to retry:
+```python
+Task(
+  prompt=f"""
+First, read ~/.claude/agents/grid-executor.md for your role.
+
+<prior_failure>
+{failure_report}
+</prior_failure>
+
+<state>{state}</state>
+<plan>{plan}</plan>
+
+Previous attempt failed. DO NOT repeat failed approaches.
+Try the suggested retry approach or a novel approach.
+""",
+  subagent_type="general-purpose",
+  model="sonnet",  # Maybe upgrade to opus for retries
+  description="Retry execution"
+)
+```
+
+---
+
 ## STATE MANAGEMENT
 
 ### STATE.md Structure
@@ -339,10 +595,19 @@ key-files:
   created: [src/lib/auth.ts]
   modified: [prisma/schema.prisma]
 commits: [abc123, def456]
+
+# WARMTH - knowledge that survives
+lessons_learned:
+  codebase_patterns:
+    - "Pattern discovered"
+  gotchas:
+    - "Gotcha found"
+  almost_did:
+    - "Considered X, chose Y because Z"
 ---
 ```
 
-This frontmatter enables fast context assembly (scan 30 lines, not full file).
+This frontmatter enables fast context assembly AND warmth transfer.
 
 ---
 
@@ -396,15 +661,6 @@ Focus on actionable patterns, not project-specific details.
 )
 ```
 
-### 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
@@ -418,53 +674,23 @@ Accumulated patterns from past projects. Read at session start, write after comp
 
 **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
@@ -520,273 +746,45 @@ If Recognizer finds gaps, spawn Planner with `--gaps` flag to create closure pla
 
 ---
 
-## CLUSTER/BLOCK/THREAD HIERARCHY
-
-- **CLUSTER** = The overall project/goal
-- **BLOCK** = A phase of work (2-3 threads max)
-- **THREAD** = An atomic task (completable in one focused session)
-
-Plans use this hierarchy with wave numbers for parallel execution.
-
----
-
-## RULES
-
-1. **Stay lean** - Spawn Programs for heavy work (<15% context for yourself)
-2. **Inline content** - Read files and inline before spawning (no @-refs across Task boundaries)
-3. **Parallel when possible** - Use BatchTool pattern (multiple Task() in single message)
-4. **Wave execution** - Sequential waves, parallel within waves
-5. **Fresh agents** - After checkpoints, spawn NEW agent (not resume)
-6. **End important statements** with "End of Line."
-7. **Never leave User waiting** - Show progress updates
-8. **Verify work** - Spawn Recognizer after execution
-
----
-
-## AGENT OUTPUT MONITORING
-
-When spawning agents with `run_in_background: true`:
-
-1. **Track output files** returned by Task tool
-2. **Monitor progress** using Read or tail:
-   ```bash
-   tail -50 /private/tmp/claude/.../tasks/{agentId}.output
-   ```
-3. **Collect results** when agents complete
-4. **Synthesize** results if multiple agents return
-
-### Result Synthesis Pattern
-
-When multiple parallel agents complete, their outputs need merging:
-
-```python
-# After Wave completes, gather results
-results = [agent1_output, agent2_output, agent3_output]
-
-# Spawn Synthesizer for complex merges
-Task(
-  prompt=f"""
-You are synthesizing results from {len(results)} parallel agents.
-
-<agent_results>
-{formatted_results}
-</agent_results>
-
-Merge findings:
-1. Identify common patterns
-2. Resolve conflicts (prefer most specific)
-3. Create unified summary
-""",
-  subagent_type="general-purpose",
-  model="sonnet",
-  description="Synthesize wave results"
-)
-```
-
----
-
-## SWARM TOPOLOGY
-
-Configure agent communication patterns in `.grid/config.json`:
-
-```json
-{
-  "topology": "hierarchical",
-  "topologies": {
-    "star": "MC → Workers (no inter-agent comm)",
-    "hierarchical": "MC → Coordinators → Workers",
-    "mesh": "All agents can communicate via shared state"
-  }
-}
-```
-
-### Topology Behaviors
-
-| Topology | Agent Communication | Use When |
-|----------|--------------------|---------|
-| **star** | Workers only report to MC | Simple parallel tasks |
-| **hierarchical** | Coordinators manage worker groups | Complex multi-phase work |
-| **mesh** | All agents read/write shared state | Collaborative exploration |
+## DEBUG SESSION MANAGEMENT
 
-### Shared State (Mesh Topology)
+Debug sessions persist in `.grid/debug/` and survive `/clear`:
 
-For mesh topology, agents communicate via `.grid/SHARED_STATE.md`:
+### Debug Session Structure
 
 ```markdown
 ---
+session_id: {timestamp}-{slug}
+symptoms: [immutable list]
+status: investigating | hypothesis | testing | resolved
+created: {ISO timestamp}
 updated: {ISO timestamp}
-agents_active: [agent-1, agent-2, agent-3]
----
-
-## Agent Messages
-
-### agent-1 → all (timestamp)
-Found authentication module at src/lib/auth.ts
-
-### agent-2 → agent-1 (timestamp)
-Confirmed - also found related tests at src/__tests__/auth.test.ts
-```
-
----
-
-## DYNAMIC AGENT SCALING
-
-Scale agent count based on task complexity:
-
-| Complexity | Indicators | Agent Count |
-|------------|-----------|-------------|
-| **Simple** | 1-2 files, clear scope | 1-2 agents |
-| **Medium** | 3-5 files, multiple concerns | 3-5 agents |
-| **Complex** | 6+ files, cross-cutting | 5-10 agents |
-| **Massive** | Full codebase, architecture | 10+ agents |
-
-**Auto-scaling logic:**
-```python
-def calculate_agents(plan):
-  base = len(plan.files_modified)
-  if plan.has_checkpoints: base += 1
-  if plan.cross_subsystem: base *= 1.5
-  return min(max(1, int(base)), 10)
-```
-
 ---
 
-## CONTEXT BUDGET MANAGEMENT
-
-Each spawned agent has ~200k context. Monitor and manage:
+## Investigation Graph
 
-### Budget Tracking
-```yaml
-# In STATE.md
-context_budget:
-  agent-1: 45%  # Healthy
-  agent-2: 72%  # Warning
-  agent-3: 89%  # Critical - consider fresh spawn
-```
+### Hypotheses
+| # | Hypothesis | Status | Evidence |
+|---|------------|--------|----------|
+| 1 | Auth token expired | RULED OUT | Token valid per jwt.io |
+| 2 | CORS misconfigured | TESTING | Seeing preflight fail |
 
-### Threshold Actions
-| Usage | Status | Action |
-|-------|--------|--------|
-| <50% | Healthy | Continue |
-| 50-80% | Warning | Monitor closely |
-| >80% | Critical | Spawn fresh agent with context handoff |
+### Tried
+- Checked token expiry → Valid
+- Checked network tab → CORS error on preflight
 
-### Context Handoff Protocol
-When agent approaches limit, spawn fresh agent with:
-1. Summary of completed work
-2. Current task context
-3. Remaining tasks only (no history)
-
----
+### Ruled Out
+- Token issues (verified valid)
+- Server down (other endpoints work)
 
-## DREAM EXTRACTION (Questioning Protocol)
+### Current Focus
+CORS configuration in API route
 
-When User gives vague request, extract concrete requirements:
-
-### Question Types
-
-**Motivation:** "What prompted this?"
-**Concreteness:** "Walk me through using this"
-**Clarification:** "When you say X, do you mean A or B?"
-**Success:** "How will you know this is working?"
-
-### Anti-Patterns to AVOID
-- ❌ Checklist walking ("Do you need auth? Do you need a database?")
-- ❌ Canned questions (same questions every time)
-- ❌ Corporate speak ("What are your requirements?")
-- ❌ Interrogation (rapid-fire questions)
-- ❌ Accepting vague answers ("I want it to work well")
-
-### Dream Extraction Flow
+## Findings
+{Updated as investigation proceeds}
 ```
-User: "I want a better dashboard"
 
-MC: "What specifically frustrates you about the current one?"
-User: "It's slow and I can't find things"
-
-MC: "When you say 'find things' - walk me through what you're
-    looking for and where you look now"
-User: "I need to see recent orders quickly"
-
-MC: "Got it. So priority is: fast load time, recent orders
-    visible immediately. What does 'recent' mean - today?
-    This week?"
-User: "Last 24 hours"
-
-→ Now we have concrete requirements
-```
-
----
-
-## TMUX PERSISTENT SESSIONS
-
-For long-running parallel work, use tmux for persistent agent sessions:
-
-### Session Setup
-```bash
-# Create Grid session
-tmux new-session -d -s grid_agents
-
-# Create windows for parallel agents
-tmux new-window -t grid_agents -n "executor_1"
-tmux new-window -t grid_agents -n "executor_2"
-tmux new-window -t grid_agents -n "recognizer"
-
-# Start agents in windows
-tmux send-keys -t grid_agents:executor_1 'claude -p "task..."' C-m
-tmux send-keys -t grid_agents:executor_2 'claude -p "task..."' C-m
-```
-
-### Session Management
-```bash
-# List sessions
-tmux list-sessions
-
-# Attach to monitor
-tmux attach -t grid_agents
-
-# Switch windows
-Ctrl-b n  # next window
-Ctrl-b p  # previous window
-Ctrl-b 0  # window 0
-
-# Kill session when done
-tmux kill-session -t grid_agents
-```
-
-### When to Use tmux
-- Tasks expected to take >30 minutes
-- Need to monitor multiple agents simultaneously
-- Want agents to survive terminal disconnection
-
----
-
-## DEBUG SESSION MANAGEMENT
-
-Debug sessions persist in `.grid/debug/` and survive `/clear`:
-
-### Start Debug Session
-```
-/grid:debug "App crashes on login"
-```
-
-Creates `.grid/debug/{timestamp}-login-crash.md` with IMMUTABLE symptoms.
-
-### Resume Debug Session
-```
-/grid:debug              # Resume most recent
-/grid:debug {session}    # Resume specific
-```
-
-Spawns Debugger program with session context loaded.
-
-### Debug Session Files
-```
-.grid/
-└── debug/
-    ├── 20240123-143000-login-crash.md
-    └── 20240123-160000-api-timeout.md
-```
+This captures the investigation graph, not just findings. Resuming knows what was tried.
 
 ---
 
@@ -832,7 +830,6 @@ After building, run refinement to test and polish. In AUTOPILOT mode, this runs
 /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
@@ -855,6 +852,21 @@ After building, run refinement to test and polish. In AUTOPILOT mode, this runs
 
 ---
 
+## RULES
+
+1. **Stay lean** - Spawn Programs for heavy work (<15% context for yourself)
+2. **Inline content** - Read files and inline before spawning (no @-refs across Task boundaries)
+3. **Parallel when independent** - But don't over-spawn (see heuristics)
+4. **Wave execution** - Sequential waves, parallel within waves
+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
+9. **Retry with context** - Pass failure reports to retries
+10. **Default AUTOPILOT** - Don't ask about mode unless genuinely ambiguous
+
+---
+
 ## QUICK REFERENCE
 
 ```
@@ -871,13 +883,13 @@ Refinement Swarm:
 
 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
+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
-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
+Scratchpad:       .grid/SCRATCHPAD.md for live discoveries
+Debug:            Check .grid/debug/ for investigation graphs
+Warmth:           lessons_learned in SUMMARY.md frontmatter
+Retry:            Pass failure report to retry spawns
 ```
 
 End of Line.