the-grid-cc 1.1.5 → 1.2.0

package/README.md

@@ -51,6 +51,18 @@ Already have The Grid? Update from within Claude Code:
 /grid:update
 ```
 
+### Status Bar
+
+The Grid adds a context meter to your Claude Code status bar:
+
+```
+Master Control ░░░░░░░░░░ 0%    ← Fresh session
+Master Control █████░░░░░ 50%   ← Half context used
+Master Control █████████░ 90%   ← Running low
+```
+
+Visual `/context` at a glance. Bar fills as you use more context.
+
 ---
 
 ## The Hierarchy

package/TICKETS.md

@@ -0,0 +1,585 @@
+# THE GRID - COMPREHENSIVE TICKET LIST
+
+> Generated from competitive analysis of get-shit-done and best practices research.
+> 28 agents deployed to extract patterns. 24 tickets created.
+
+---
+
+## PRIORITY 1: CORE PARALLEL EXECUTION
+
+### TICKET #1: Implement true subprocess spawning for Grid agents
+**Status:** ✅ COMPLETED
+
+Add ability for Master Control to spawn Claude Code agents as actual background processes with their own context windows. Use the Task tool with run_in_background:true pattern. Each spawned agent gets fresh 200k context. Key patterns from research:
+- BatchTool pattern: multiple Task calls in single message
+- Background execution with output file tracking
+- Agent ID tracking for resumption
+
+---
+
+### TICKET #3: Build parallel BatchTool execution pattern into Master Control
+**Status:** ✅ COMPLETED
+
+Master Control should spawn multiple agents in a SINGLE message with multiple Task tool calls. This is the key to true parallel execution. Pattern:
+```
+[Single Message]:
+  - Task("Agent 1...")
+  - Task("Agent 2...")
+  - Task("Agent 3...")
+```
+NOT sequential calls. Must be batched.
+
+---
+
+### TICKET #12: Implement wave-based parallel execution (pre-computed during planning)
+**Status:** ✅ COMPLETED
+
+GSD's killer feature: waves are computed DURING PLANNING, not at execution time.
+
+Pattern:
+- Planner assigns wave numbers to each plan based on file_modified arrays
+- Plans that touch same files = sequential (next wave)
+- Plans with no overlap = parallel (same wave)
+- Checkpoints always get their own wave (blocking)
+
+Orchestrator just reads wave numbers from frontmatter and groups:
+```
+waves = {
+  1: [plan-01, plan-02],  # parallel
+  2: [plan-03, plan-04],  # parallel, after wave 1
+  3: [plan-05]            # sequential
+}
+```
+
+This is the foundation for true parallel agent spawning.
+
+---
+
+### TICKET #13: Add inline content pattern for agent spawning (break @-ref boundaries)
+**Status:** ✅ COMPLETED
+
+Critical pattern from GSD: @-references DON'T work across Task() boundaries.
+
+Before spawning an agent, read ALL files and INLINE the content:
+```python
+PLAN_CONTENT = read(".planning/01-PLAN.md")
+STATE_CONTENT = read(".planning/STATE.md")
+CONFIG_CONTENT = read(".planning/config.json")
+
+Task(
+  prompt=f"...{PLAN_CONTENT}...{STATE_CONTENT}...{CONFIG_CONTENT}...",
+  ...
+)
+```
+
+Each agent gets a FRESH 200k context with everything it needs PRE-LOADED. No file access overhead, no context leakage.
+
+---
+
+## PRIORITY 2: VERIFICATION & QUALITY
+
+### TICKET #14: Implement goal-backward verification in Recognizer
+**Status:** ✅ COMPLETED
+
+GSD's most powerful pattern: Goal-backward verification.
+
+Task completion ≠ Goal achievement. A task "create chat component" can be complete while the component is just a stub.
+
+Process:
+1. Start with GOAL (not task list)
+2. Derive TRUTHS - "What must be TRUE for goal to succeed?" (3-7 observable behaviors)
+3. Derive ARTIFACTS - "What must EXIST?" (concrete files)
+4. Derive KEY_LINKS - "What must be CONNECTED?" (wiring points where stubs hide)
+5. Verify each level: existence → substantive → wired
+
+YAML structure:
+```yaml
+must_haves:
+  truths: ["User can see messages", "User can send message"]
+  artifacts:
+    - path: "src/components/Chat.tsx"
+      provides: "Message list rendering"
+      min_lines: 15
+  key_links:
+    - from: "Chat.tsx"
+      to: "/api/chat"
+      via: "fetch in useEffect"
+```
+
+---
+
+### TICKET #16: Implement three-level artifact verification (existence, substantive, wired)
+**Status:** ✅ COMPLETED
+
+Every artifact must pass three checks:
+
+**Level 1: EXISTENCE**
+- Does the file physically exist?
+
+**Level 2: SUBSTANTIVE**
+- Is it real code, not a stub?
+- Minimum line count (15+ for components, 10+ for API)
+- No TODO/FIXME/placeholder patterns
+- Functions actually exported
+
+**Level 3: WIRED**
+- Is it imported and used elsewhere?
+- Critical connections exist?
+- Not orphaned code?
+
+Stub detection patterns:
+```bash
+# Comments
+TODO|FIXME|PLACEHOLDER|coming soon
+
+# Empty implementations
+return null|return {}|return []|pass
+
+# React stubs
+<div>Component</div>|onClick={() => {}}
+
+# API stubs
+"Not implemented"|return Response.json([])
+```
+
+---
+
+### TICKET #7: Add Recognizer aerial patrol for spawned agents
+**Status:** ✅ COMPLETED
+
+Recognizer should patrol all spawned agent outputs, checking for:
+- Incomplete code (TODO, FIXME, stub functions)
+- Failed tests
+- Errors in output
+- Task completion verification
+
+Pattern: Goal-backward verification - start from desired outcome, verify work meets it.
+
+---
+
+### TICKET #15: Add deviation rules for automatic decision-making
+**Status:** ✅ COMPLETED
+
+GSD executors auto-fix common issues without stopping:
+
+**RULE 1: Auto-fix bugs**
+- Trigger: Code doesn't work (errors, logic issues)
+- Action: Fix immediately, track in SUMMARY
+- No permission needed
+
+**RULE 2: Auto-add missing critical functionality**
+- Trigger: Missing error handling, validation, auth checks
+- Action: Add immediately, track in SUMMARY
+- No permission needed
+
+**RULE 3: Auto-install blocking dependencies**
+- Trigger: Import failing, missing peer dependency
+- Action: Install immediately, track in SUMMARY
+- No permission needed
+
+**RULE 4: Ask about architectural changes**
+- Trigger: Fix requires significant structural modification
+- Action: STOP, present I/O Tower checkpoint
+- User decision required
+
+All deviations tracked in SUMMARY.md with evidence.
+
+---
+
+## PRIORITY 3: STATE & DOCUMENTATION
+
+### TICKET #17: Add SUMMARY.md generation per plan execution
+**Status:** ✅ COMPLETED
+
+After each plan executes, create SUMMARY.md with:
+
+YAML frontmatter:
+```yaml
+---
+phase: 03-features
+plan: 01
+subsystem: auth
+requires:
+  - phase: 01-foundation
+    provides: "User model, database setup"
+provides:
+  - "JWT login/logout endpoints"
+affects:
+  - 04-dashboard (uses auth types)
+tech-stack:
+  added: [jose, bcrypt]
+key-files:
+  created: [src/lib/auth.ts]
+  modified: [prisma/schema.prisma]
+duration: 28min
+commits: [abc123, def456]
+---
+```
+
+Body with:
+- Tasks completed
+- Commits made
+- Deviations from plan
+- Files created/modified
+
+Frontmatter enables fast context assembly (scan 30 lines, not full file).
+
+---
+
+### TICKET #4: Add agent output file monitoring and synthesis
+**Status:** ✅ COMPLETED
+
+When agents run in background, they write to output files. Master Control needs:
+1. Track all spawned agent output files
+2. Monitor progress via tail/Read
+3. Synthesize results when agents complete
+4. Aggregate into final report
+
+Pattern: /private/tmp/claude/.../tasks/{agentId}.output
+
+---
+
+### TICKET #8: Implement agent result synthesis/aggregation
+**Status:** ✅ COMPLETED
+
+When parallel agents complete, their outputs need to be synthesized:
+1. Collect all agent results
+2. Spawn synthesis agent to merge findings
+3. Resolve conflicts between agent outputs
+4. Produce unified final result
+
+Pattern from claude-flow: KN5 synthesis function merges parallel agent results.
+
+---
+
+## PRIORITY 4: TOPOLOGY & SCALING
+
+### TICKET #2: Add swarm topology configuration (mesh, hierarchical, star)
+**Status:** ✅ COMPLETED
+
+Allow Master Control to configure different agent topologies:
+- MESH: All agents can communicate with all
+- HIERARCHICAL: Orchestrator → Coordinators → Workers
+- STAR: Central orchestrator, radiating workers
+
+Based on claude-flow MCP patterns. Store topology in .grid/STATE.md
+
+---
+
+### TICKET #9: Add dynamic agent scaling based on task complexity
+**Status:** ✅ COMPLETED
+
+Master Control should dynamically decide how many agents to spawn based on:
+- Task complexity score
+- Number of subtasks identified by Planner
+- Available resources/context budget
+
+Simple tasks: 1-2 agents
+Medium tasks: 3-5 agents
+Complex tasks: 5-10+ agents
+
+Auto-spawn based on Planner's decomposition.
+
+---
+
+### TICKET #10: Build inter-agent communication protocol
+**Status:** ✅ COMPLETED
+
+Agents need to communicate results to each other, not just back to orchestrator:
+- Shared state file (.grid/SHARED_STATE.md)
+- Message queue pattern
+- Agent-to-agent handoff protocol
+
+For mesh topology, any agent can write to shared state and others read it.
+
+---
+
+### TICKET #11: Add context budget management for spawned agents
+**Status:** ✅ COMPLETED
+
+Track and manage context usage across spawned agents:
+- Each agent has ~200k context budget
+- Monitor context usage per agent
+- Auto-clear/restart agents when context runs low
+- Pattern: context_threshold setting (default 20%)
+
+Prevents agent degradation from context exhaustion.
+
+---
+
+## PRIORITY 5: PERSISTENT SESSIONS
+
+### TICKET #5: Implement tmux-based persistent agent sessions
+**Status:** ✅ COMPLETED
+
+For true fission-style agent spawning, use tmux to create persistent Claude sessions:
+```bash
+tmux new-session -d -s grid_agents
+tmux new-window -t grid_agents -n "agent_1"
+tmux send-keys -t grid_agents:agent_1 'claude -p "task..."' C-m
+```
+This allows agents to survive and run independently with their own terminals.
+
+---
+
+### TICKET #22: Add debug session persistence that survives /clear
+**Status:** ✅ COMPLETED
+
+When debugging, persist state to .grid/debug/{session}.md:
+
+```yaml
+---
+status: investigating
+trigger: "App crashes on login"
+created: 2024-01-23T10:00:00Z
+updated: 2024-01-23T10:30:00Z
+---
+
+## Current Focus
+hypothesis: Auth token expiry not handled
+test: Check token refresh logic
+expecting: Missing refresh call
+
+## Symptoms (IMMUTABLE)
+expected: User logs in successfully
+actual: App crashes after 15 minutes
+errors: "TypeError: Cannot read property 'token' of null"
+
+## Eliminated (APPEND only)
+- hypothesis: Server down
+  evidence: curl returns 200
+
+## Evidence (APPEND only)
+- timestamp: 10:15
+  checked: auth.ts:45
+  found: No token refresh
+```
+
+Resume with /grid:debug (no args).
+
+---
+
+## PRIORITY 6: NEW COMMANDS
+
+### TICKET #18: Add /grid:program_disc command to view agent system prompts
+**Status:** ✅ COMPLETED
+
+Create a command that shows any Grid program's system prompt with beautiful TRON-themed ASCII art.
+
+Usage: /grid:program_disc [program_name]
+- /grid:program_disc planner - shows Planner's instructions
+- /grid:program_disc executor - shows Executor's instructions
+- /grid:program_disc recognizer - shows Recognizer's instructions
+
+Display format:
+```
+    ╔══════════════════════════╗
+   ╔╝                          ╚╗
+  ╔╝    PLANNER PROGRAM DISC    ╚╗
+  ║                              ║
+  ║     ████████████████████     ║
+  ║    ██              ████      ║
+  ║    ██   IDENTITY   ████      ║
+  ║    ██              ████      ║
+  ║     ████████████████████     ║
+  ║                              ║
+  ╚╗                            ╔╝
+   ╚╗                          ╔╝
+    ╚══════════════════════════╝
+
+[System prompt content follows]
+```
+
+List all available programs if no argument given.
+
+---
+
+### TICKET #19: Add /grid:status command with visual progress display
+**Status:** ✅ COMPLETED
+
+Create a status command showing Grid state with TRON visuals:
+
+```
+THE GRID - STATUS
+═════════════════
+
+CLUSTER: React Todo App
+├─ BLOCK 1: Core Application [████████░░] 80%
+│  ├─ THREAD 1.1: Initialize  ✓ Complete
+│  ├─ THREAD 1.2: Components  ✓ Complete
+│  ├─ THREAD 1.3: Logic       ⚡ In Progress
+│  └─ THREAD 1.4: Styling     ○ Pending
+│
+└─ BLOCK 2: Testing [░░░░░░░░░░] 0%
+   └─ Blocked by BLOCK 1
+
+PROGRAMS ACTIVE: Executor (THREAD 1.3)
+I/O TOWER: Idle
+
+End of Line.
+```
+
+---
+
+### TICKET #24: Add /grid:quick for ad-hoc tasks without full planning
+**Status:** ✅ COMPLETED
+
+Like GSD's /gsd:quick - for simple tasks that don't need full cluster/block/thread breakdown:
+
+Usage: /grid:quick "Add dark mode toggle"
+
+Process:
+1. Quick questioning (1-2 clarifying questions max)
+2. Direct planning (single PLAN.md)
+3. Execute immediately
+4. Create SUMMARY.md
+
+Stored in .grid/quick/{timestamp}-{slug}/
+
+Good for:
+- Bug fixes
+- Small features
+- Refactoring tasks
+- Documentation updates
+
+Skip the full orchestration ceremony.
+
+---
+
+## PRIORITY 7: NEW PROGRAMS
+
+### TICKET #23: Add Grid Debugger program for systematic bug investigation
+**Status:** ✅ COMPLETED
+
+Create a new Debugger program with GSD's methodology:
+
+**1. Hypothesis Testing Framework**
+- Form specific, falsifiable hypotheses
+- One hypothesis at a time
+- Strong evidence requirement
+- Track eliminated hypotheses
+
+**2. Investigation Techniques**
+- Binary search (divide problem space)
+- Rubber duck debugging
+- Minimal reproduction
+- Working backwards
+- Differential debugging (what changed?)
+- Observability first (add logging before fixing)
+
+**3. Debug File Protocol**
+- Current Focus section
+- Symptoms (immutable)
+- Eliminated hypotheses (append only)
+- Evidence log (append only)
+- Resolution (filled when found)
+
+---
+
+## PRIORITY 8: CONFIGURATION
+
+### TICKET #20: Add questioning/dream extraction to Grid initialization
+**Status:** ✅ COMPLETED
+
+When user invokes /grid with a vague request, use GSD's questioning methodology:
+
+1. Dream extraction, not requirements gathering
+2. 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?"
+
+3. Anti-patterns to avoid:
+   - Checklist walking
+   - Canned questions
+   - Corporate speak
+   - Interrogation
+   - Taking vague answers
+
+Ask until you have concrete, specific understanding.
+
+---
+
+### TICKET #21: Add model routing configuration (opus/sonnet/haiku per task type)
+**Status:** ✅ COMPLETED
+
+Allow Grid to route different tasks to different models:
+
+Config in .grid/config.json:
+```json
+{
+  "model_profile": "balanced",
+  "routing": {
+    "planner": {
+      "quality": "opus",
+      "balanced": "sonnet",
+      "budget": "haiku"
+    },
+    "executor": {
+      "quality": "opus",
+      "balanced": "sonnet",
+      "budget": "sonnet"
+    },
+    "recognizer": {
+      "quality": "sonnet",
+      "balanced": "haiku",
+      "budget": "haiku"
+    }
+  }
+}
+```
+
+Spawn agents with the configured model.
+
+---
+
+## PRIORITY 9: INFRASTRUCTURE
+
+### TICKET #6: Create MCP server for Grid orchestration (grid-flow)
+**Status:** ❌ SKIPPED - Unnecessary
+
+~~Build an MCP server similar to claude-flow that exposes Grid operations as MCP tools.~~
+
+**Decision:** The Grid already has full orchestration capabilities through the Task tool:
+- BatchTool pattern for parallel spawning
+- Agent output monitoring via Read/tail
+- Swarm topology via SHARED_STATE.md
+- Wave-based execution via plan frontmatter
+
+Adding an MCP layer would be redundant complexity. The existing approach is cleaner and more aligned with Claude Code's architecture.
+
+---
+
+## SUMMARY
+
+| Priority | Count | Status | Focus |
+|----------|-------|--------|-------|
+| P1: Core Parallel | 4 | ✅ ALL DONE | Subprocess spawning, BatchTool, waves, inline content |
+| P2: Verification | 4 | ✅ ALL DONE | Goal-backward, 3-level, patrol, deviation rules |
+| P3: State/Docs | 3 | ✅ ALL DONE | SUMMARY.md, output monitoring, synthesis |
+| P4: Topology | 4 | ✅ ALL DONE | Swarm config, scaling, inter-agent comms, context budget |
+| P5: Persistence | 2 | ✅ ALL DONE | tmux sessions, debug persistence |
+| P6: Commands | 3 | ✅ ALL DONE | program_disc, status, quick |
+| P7: Programs | 1 | ✅ ALL DONE | Debugger program |
+| P8: Config | 2 | ✅ ALL DONE | Dream extraction, model routing |
+| P9: Infrastructure | 1 | ❌ SKIPPED | MCP server (unnecessary) |
+
+**TOTAL: 23/24 TICKETS COMPLETE (100% of needed work)**
+
+---
+
+## RESEARCH AGENTS DEPLOYED
+
+28 parallel agents analyzing get-shit-done:
+- 9 agent file extractors (planner, executor, verifier, debugger, etc.)
+- 4 directory scanners (commands, workflows, templates, references)
+- 3 style/readme extractors
+- 4 system extractors (hooks, bin, ASCII, model routing, state)
+- 8 pattern extractors (Task spawning, checkpoints, YAML, questioning, etc.)
+
+Results being aggregated...
+
+---
+
+*End of Line.*