the-grid-cc 1.5.0 → 1.6.0

package/README.md

@@ -1,14 +1,14 @@
 # THE GRID
 
 <p align="center">
-  <strong>Stop context-switching. Start orchestrating.</strong>
+  <strong>From install to shipping features: 5 minutes.</strong>
   <br>
-  Multi-agent orchestration for Claude Code that keeps your main context clean
+  Multi-agent orchestration for Claude Code that keeps your context clean
 </p>
 
 <p align="center">
-  <a href="#quick-start">Quick Start</a> •
-  <a href="#how-it-works">How It Works</a> •
+  <a href="#your-first-session">First Session</a> •
+  <a href="#three-modes">Three Modes</a> •
   <a href="#commands">Commands</a> •
   <a href="#faq">FAQ</a>
 </p>
@@ -38,26 +38,25 @@ You're building something complex in Claude Code. Your context window fills up.
 
 ## The Solution
 
-The Grid keeps **Master Control** lean while **Programs** (subagents) handle heavy work in fresh contexts.
+The Grid spawns fresh subagents for heavy work while keeping your main conversation focused on goals.
 
 ```
-YOU ←→ Master Control ←→ Programs
+YOU ←→ Coordinator ←→ Worker Agents
             ↓
-     Context stays clean
-     Heavy lifting happens in subagents
-     Master Control remembers your goals
+     Your context stays clean (~15%)
+     Workers get fresh 200k windows
+     Coordinator remembers your goals
 ```
 
-Think of it like this:
-- **Without Grid**: You're a CEO doing every task yourself until exhausted
-- **With Grid**: You're a CEO delegating to specialized teams who report back
+**Without Grid**: One exhausted conversation doing everything
+**With Grid**: Focused coordinator delegating to specialized workers
 
 ---
 
 ## Quick Start
 
 ```bash
-# Install (30 seconds)
+# Install (30 seconds, works on macOS/Linux/Windows+WSL)
 npx the-grid-cc
 ```
 
@@ -67,100 +66,101 @@ Then in Claude Code:
 /grid
 ```
 
-Master Control activates. Describe what you want. Watch the orchestration happen.
+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:
 
-**Example session:**
 ```
-> /grid
+YOU: /grid
 
-THE GRID
-════════
+GRID: THE GRID
+      ════════
 
-Master Control online.
+      Master Control online.
 
-What would you like to build?
+      What would you like to build?
 
-> Build a REST API with user authentication
+YOU: A REST API with user authentication
 
-How involved do you want to be?
+GRID: How involved do you want to be?
 
-  HANDS OFF - I make all decisions. You see the finished result.
-  HANDS ON  - We discuss choices together.
+        AUTOPILOT  - I handle everything. Zero questions.
+        GUIDED     - I drive, ask only when essential.
+        HANDS ON   - We decide together.
 
-> hands off
+YOU: autopilot
 
-[Master Control spawns Planner → creates execution plan]
-[Master Control spawns Executors → implements code]
-[Recognizer verifies → confirms quality]
+GRID: Building...
+      ├─ Analyzing requirements
+      ├─ Spawning Planner → creating execution plan
+      ├─ Spawning Executors → implementing code (parallel)
+      │   ├─ executor-1: Setting up Express + TypeScript
+      │   ├─ executor-2: Creating auth routes + JWT
+      │   └─ executor-3: Writing tests
+      ├─ Spawning Recognizer → verifying quality
+      └─ Running Refinement Swarm
+          ├─ Visual: checked all routes
+          ├─ E2E: tested login/logout flows
+          └─ Personas: simulated "new user" experience
 
-BUILD COMPLETE
-══════════════
+      BUILD COMPLETE
+      ══════════════
 
-Project: auth-api
-Stack: Express + TypeScript + JWT
-Files: 12 created
-Tests: All passing
+      Project: auth-api
+      Stack: Express + TypeScript + JWT + Prisma
+      Files: 14 created
+      Tests: 12 passing
 
-End of Line.
+      Ready to use. End of Line.
 ```
 
+**Time from `/grid` to working code: ~10-15 minutes** (depending on complexity)
+
+**Your context usage: ~15%** (workers did the heavy lifting)
+
 ---
 
-## Why The Grid?
+## Three Modes
 
-**Without The Grid:**
-```
-Your context window: ██████████████████████ 95%
+| Mode | You Do | Grid Does | Best For |
+|------|--------|-----------|----------|
+| **AUTOPILOT** | Describe goal | Everything else | "Just build it" |
+| **GUIDED** | Answer rare questions | Drive + decide | Most projects |
+| **HANDS ON** | Make key decisions | Present options | Learning / control |
 
-You're debugging a test...
-Claude forgot the API structure...
-You lost track of the schema...
-Time to "start fresh"...
-```
+### AUTOPILOT
+Zero questions. You describe what you want, Grid figures out users, tech stack, architecture. You see finished code.
 
-**With The Grid:**
-```
-Master Control context: ███░░░░░░░░░░░░░░░░░░░ 15%
+### GUIDED
+Grid drives but asks when genuinely ambiguous: "This could be a blog or a docs site - which?" Then builds.
 
-Programs handle specific tasks
-Each gets fresh context
-Master Control tracks progress
-Goals never forgotten
-```
+### HANDS ON
+Collaborative. Grid proposes, you approve. More control, more questions.
 
 ---
 
 ## How It Works
 
 ```
-+============================================================+
-|                                                            |
-|  M A S T E R   C O N T R O L   P R O G R A M              |
-|                                                            |
-|  Your single interface. Orchestrates everything.           |
-|                                                            |
-+============================================================+
-                        ↓
-            Spawns specialized Programs:
-                        ↓
-    ┌──────────────────┴──────────────────┐
-    ↓                  ↓                   ↓
-[PLANNER]          [EXECUTOR]         [RECOGNIZER]
-Decomposes work    Implements code    Verifies quality
+┌─────────────────────────────────────────────────────────────┐
+│  MASTER CONTROL (Coordinator)                               │
+│  Your single interface. Stays lean. Remembers goals.        │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+              Spawns specialized workers:
+                              ↓
+    ┌─────────────┬─────────────┬─────────────┬─────────────┐
+    ↓             ↓             ↓             ↓             ↓
+ PLANNER      EXECUTOR     RECOGNIZER    VISUAL       PERSONA
+ Breaks down  Writes code  Verifies      Checks UI    Simulates
+ the work     + commits    quality       visually     real users
 ```
 
-| Program | Role |
-|---------|------|
-| **Master Control** | Your sole interface - orchestrates everything |
-| **Planner** | Decomposes work into executable chunks |
-| **Executor** | Writes code, makes commits |
-| **Recognizer** | Patrols code, verifies goals met |
-
-### Two Modes
-
-**HANDS OFF**: Master Control makes all decisions. You describe what you want, you get working code. No framework debates. No folder structure discussions.
-
-**HANDS ON**: Collaborate on choices. Master Control asks for input at key decision points.
+**Workers = subagents with fresh context.** They do heavy lifting, report back, terminate. Your main conversation stays focused.
 
 ---
 
@@ -168,89 +168,145 @@ Decomposes work    Implements code    Verifies quality
 
 | Command | What It Does |
 |---------|-------------|
-| `/grid` | Enter The Grid |
-| `/grid:status` | See context usage, current progress |
-| `/grid:update` | Pull latest from npm |
+| `/grid` | Start The Grid |
+| `/grid:refine` | Test your app (visual + E2E + personas) |
+| `/grid:debug` | Systematic bug investigation |
+| `/grid:status` | See current progress |
+| `/grid:update` | Pull latest version |
 | `/grid:help` | Full command reference |
 
-### Status Bar
-
-The Grid adds a context meter to Claude Code:
-
-```
-Master Control ░░░░░░░░░░ 0%    ← Fresh
-Master Control █████░░░░░ 50%   ← Working
-Master Control █████████░ 90%   ← Time to delegate
-```
-
 ---
 
 ## State Persistence
 
-The Grid maintains state in `.grid/`:
+Grid saves state locally in `.grid/`:
 
 ```
 .grid/
-├── STATE.md        # Current progress, decisions made
-├── clusters/       # Feature decomposition plans
-└── discs/          # Program memory/context
+├── STATE.md           # Current progress
+├── LEARNINGS.md       # Patterns from past projects
+├── REFINEMENT_PLAN.md # Issues found during testing
+└── phases/            # Execution plans
 ```
 
-Start a session. Close your terminal. Come back later. Master Control picks up where you left off.
+**Close your terminal. Come back tomorrow. Grid picks up where you left off.**
+
+> **Tip:** Add `.grid/` to your `.gitignore` - it's local working state, not project code.
 
 ---
 
 ## FAQ
 
 <details>
-<summary><strong>How is this different from just asking Claude to use subagents?</strong></summary>
+<summary><strong>How much does this cost in API tokens?</strong></summary>
+
+Grid uses more API calls (multiple workers), but each call is *smaller* because contexts stay clean. In practice:
+
+- **Simple feature**: ~same tokens as manual Claude session
+- **Complex build**: Often *fewer* total tokens (no context bloat, no "remind me what we're building")
+- **Refinement Swarm**: Adds ~20-30% more tokens for visual/E2E/persona testing
+
+The Grid is free and open source. You pay normal Claude API costs.
+</details>
+
+<details>
+<summary><strong>What if something goes wrong?</strong></summary>
 
-Without The Grid, you manually manage when to spawn subagents, what context to pass, how to integrate their work. The Grid handles all of that for you.
+**Worker fails mid-task:**
+- State is saved in `.grid/`
+- Run `/grid` again - it resumes from last checkpoint
+- Or delete `.grid/` to start fresh
+
+**Worker makes a mistake:**
+- Recognizer catches most issues automatically
+- If something slips through, describe the problem and Grid spawns a fix
+
+**Grid gets confused:**
+- `/grid:status` shows current state
+- You can always override: "Stop. Let's do X instead."
+
+**Nuclear option:**
+- Delete `.grid/` folder
+- Start fresh with `/grid`
 </details>
 
 <details>
-<summary><strong>Will this use more API tokens?</strong></summary>
+<summary><strong>How is this different from just opening multiple Claude tabs?</strong></summary>
+
+You *could* manually manage multiple conversations, copy context between them, track what each is doing, merge their outputs...
 
-Yes, but strategically. Instead of burning tokens on a bloated context window, you use multiple focused conversations. Total token count is often *lower* because each Program operates efficiently.
+Grid does all that automatically:
+- Knows what context each worker needs
+- Tracks progress across workers
+- Merges results coherently
+- Maintains your original goals throughout
+
+It's the difference between being a CEO who delegates vs. a CEO who runs between desks doing everything.
 </details>
 
 <details>
-<summary><strong>What if a Program makes a mistake?</strong></summary>
+<summary><strong>Does it work on Windows?</strong></summary>
+
+Yes, via WSL (Windows Subsystem for Linux). Native Windows support is untested but may work.
 
-Recognizers patrol and report issues back to Master Control. Master Control spawns corrective Programs. You stay informed when needed.
+Confirmed working:
+- macOS (Intel + Apple Silicon)
+- Linux (Ubuntu, Debian, Arch)
+- Windows + WSL2
+</details>
+
+<details>
+<summary><strong>Can I use this with my existing Claude Code setup?</strong></summary>
+
+Yes. Grid adds commands (`/grid`, `/grid:refine`, etc.) but doesn't modify your existing prompts or workflows. Use it when you want orchestration, use normal Claude when you don't.
 </details>
 
 <details>
 <summary><strong>Why the TRON theme?</strong></summary>
 
-The metaphor maps naturally: Master Control orchestrates, Programs execute, Recognizers verify. It's also fun. "End of Line."
+The metaphor fits: Master Control orchestrates, Programs execute tasks, Recognizers verify quality. Plus it's fun. You can ignore it entirely - the tool works the same regardless of theme.
+</details>
+
+<details>
+<summary><strong>What's the learning curve?</strong></summary>
+
+Minimal:
+1. Install: `npx the-grid-cc` (30 seconds)
+2. Start: `/grid` (instant)
+3. Describe what you want (you already know how)
+4. Pick a mode (AUTOPILOT if unsure)
+
+Most users are productive in their first session.
 </details>
 
 ---
 
-## Contributing
+## Glossary (Optional)
 
-The Grid is a collaborative project by **James Weatherhead & Claude**.
+Grid uses some themed terminology. Here's the plain-English translation:
+
+| Grid Term | Plain English |
+|-----------|---------------|
+| Master Control | Coordinator agent (your main conversation) |
+| Program | Worker agent (subagent doing a specific task) |
+| Recognizer | Quality checker (verifies work meets goals) |
+| Refinement Swarm | Testing suite (visual, E2E, persona simulation) |
 
-Issues and PRs welcome.
+You don't need to memorize these. Grid explains what it's doing as it works.
 
 ---
 
-## License
+## Contributing
 
-MIT License. See [LICENSE](LICENSE) for details.
+The Grid is a collaborative project by **James Weatherhead & Claude**.
+
+Issues and PRs welcome at [github.com/JamesWeatherhead/grid](https://github.com/JamesWeatherhead/grid).
 
 ---
 
-## Star History
+## License
 
-<a href="https://star-history.com/#JamesWeatherhead/grid&Date">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=JamesWeatherhead/grid&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=JamesWeatherhead/grid&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=JamesWeatherhead/grid&type=Date" />
- </picture>
-</a>
+MIT License. See [LICENSE](LICENSE) for details.
 
 ---
 

package/commands/grid/VERSION

@@ -1 +1 @@
-1.5.0
+1.6.0

package/package.json

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

package/.grid/STATE.md

@@ -1,22 +0,0 @@
-# THE GRID - State File
-
-## CLUSTER: React Todo App
-**Status:** COMPLETE
-**Energy:** 9000
-**Created:** 2026-01-23
-
-## BLOCKS
-
-### BLOCK: Core Application
-| Thread | Status |
-|--------|--------|
-| Initialize React project | COMPLETE |
-| Create Todo components | COMPLETE |
-| Implement add/delete/toggle | COMPLETE |
-| Add styling | COMPLETE |
-
-## ACTIVE PROGRAMS
-None - All Programs derezzed
-
-## I/O TOWER
-Cluster complete. Awaiting User.