the-grid-cc 1.4.0 → 1.6.0

package/README.md

@@ -1,37 +1,62 @@
 # THE GRID
 
-> "The Grid. A digital frontier. I tried to picture clusters of information as they moved through the computer."
-
-**Agent orchestration for Claude Code.** You talk to the Master Control Program. Master Control handles the rest.
+<p align="center">
+  <strong>From install to shipping features: 5 minutes.</strong>
+  <br>
+  Multi-agent orchestration for Claude Code that keeps your context clean
+</p>
 
-[![GitHub stars](https://img.shields.io/github/stars/JamesWeatherhead/grid?style=flat-square)](https://github.com/JamesWeatherhead/grid/stargazers)
-[![License: MIT](https://img.shields.io/badge/License-MIT-cyan.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+<p align="center">
+  <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>
 
-```
-+============================================================+
-|                                                            |
-|  M A S T E R   C O N T R O L   P R O G R A M              |
-|                                                            |
-|  "I fight for the Users."                                  |
-|                                                            |
-+============================================================+
-```
+<p align="center">
+  <a href="https://www.npmjs.com/package/the-grid-cc">
+    <img src="https://img.shields.io/npm/v/the-grid-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837" alt="npm version"/>
+  </a>
+  <a href="https://github.com/JamesWeatherhead/grid/stargazers">
+    <img src="https://img.shields.io/github/stars/JamesWeatherhead/grid?style=for-the-badge" alt="GitHub stars"/>
+  </a>
+  <a href="https://www.npmjs.com/package/the-grid-cc">
+    <img src="https://img.shields.io/npm/dm/the-grid-cc?style=for-the-badge" alt="npm downloads"/>
+  </a>
+  <a href="https://github.com/JamesWeatherhead/grid/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-cyan.svg?style=for-the-badge" alt="MIT License"/>
+  </a>
+</p>
 
 ---
 
-## What Is This?
+## The Problem
+
+You're building something complex in Claude Code. Your context window fills up. Claude starts forgetting your original goals. You lose the forest for the trees.
+
+**Sound familiar?**
+
+## The Solution
 
-The Grid is a **Claude Code command system** that orchestrates AI agents using the TRON metaphor.
+The Grid spawns fresh subagents for heavy work while keeping your main conversation focused on goals.
 
-**You only talk to Master Control.** Master Control spawns Programs to do the actual work. Programs report back to Master Control. Master Control reports to you.
+```
+YOU ←→ Coordinator ←→ Worker Agents
+            ↓
+     Your context stays clean (~15%)
+     Workers get fresh 200k windows
+     Coordinator remembers your goals
+```
 
-This keeps Master Control's context window lean while heavy work happens in fresh subagent contexts.
+**Without Grid**: One exhausted conversation doing everything
+**With Grid**: Focused coordinator delegating to specialized workers
 
 ---
 
 ## Quick Start
 
 ```bash
+# Install (30 seconds, works on macOS/Linux/Windows+WSL)
 npx the-grid-cc
 ```
 
@@ -41,65 +66,101 @@ Then in Claude Code:
 /grid
 ```
 
-Master Control will greet you. Tell it what you want to build.
+That's it. Describe what you want to build.
 
-### Update
+---
 
-Already have The Grid? Update from within Claude Code:
+## Your First Session
+
+Here's exactly what happens when you use The Grid for the first time:
 
 ```
-/grid:update
-```
+YOU: /grid
 
-### Status Bar
+GRID: THE GRID
+      ════════
 
-The Grid adds a context meter to your Claude Code status bar:
+      Master Control online.
 
-```
-Master Control ░░░░░░░░░░ 0%    ← Fresh session
-Master Control █████░░░░░ 50%   ← Half context used
-Master Control █████████░ 90%   ← Running low
+      What would you like to build?
+
+YOU: A REST API with user authentication
+
+GRID: How involved do you want to be?
+
+        AUTOPILOT  - I handle everything. Zero questions.
+        GUIDED     - I drive, ask only when essential.
+        HANDS ON   - We decide together.
+
+YOU: autopilot
+
+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
+      ══════════════
+
+      Project: auth-api
+      Stack: Express + TypeScript + JWT + Prisma
+      Files: 14 created
+      Tests: 12 passing
+
+      Ready to use. End of Line.
 ```
 
-Visual `/context` at a glance. Bar fills as you use more context.
+**Time from `/grid` to working code: ~10-15 minutes** (depending on complexity)
+
+**Your context usage: ~15%** (workers did the heavy lifting)
 
 ---
 
-## The Hierarchy
+## Three Modes
+
+| 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 |
 
-| TRON Term | What It Is | Role |
-|-----------|-----------|------|
-| **Master Control** | The orchestrator | Your sole interface - orchestrates everything |
-| **Program** | Subagent | Does actual coding work |
-| **Recognizer** | Patrol/verification agent | Surveys code, captures defects |
-| **Guard** | Security agent | Checks permissions, prevents dangerous ops |
-| **Cluster** | Feature/domain | What you're building |
-| **Block** | Task group | Related tasks |
-| **Thread** | Atomic task | Single unit of work |
-| **I/O Tower** | Human checkpoint | Where Master Control asks for your input |
-| **Identity Disc** | Context carrier | Memory that travels with Programs |
+### AUTOPILOT
+Zero questions. You describe what you want, Grid figures out users, tech stack, architecture. You see finished code.
+
+### GUIDED
+Grid drives but asks when genuinely ambiguous: "This could be a blog or a docs site - which?" Then builds.
+
+### HANDS ON
+Collaborative. Grid proposes, you approve. More control, more questions.
 
 ---
 
 ## How It Works
 
 ```
-YOU ←→ Master Control ←→ Programs
-         ↓
-    Recognizers (patrol)
-         ↓
-      Guards (security)
+┌─────────────────────────────────────────────────────────────┐
+│  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
 ```
 
-1. **You** describe what you want to build
-2. **Master Control** parses intent, creates Cluster structure
-3. **Master Control** spawns **Planner Program** to create Blocks/Threads
-4. **Master Control** spawns **Executor Programs** to do the work
-5. **Recognizers** patrol and verify work meets goals
-6. **Guards** check security before dangerous operations
-7. **Master Control** reports completion to **You**
-
-If any Program needs your input → **I/O Tower** activates → Master Control asks you.
+**Workers = subagents with fresh context.** They do heavy lifting, report back, terminate. Your main conversation stays focused.
 
 ---
 
@@ -107,110 +168,150 @@ If any Program needs your input → **I/O Tower** activates → Master Control a
 
 | Command | What It Does |
 |---------|-------------|
-| `/grid` | Enter The Grid - activates Master Control |
-| `/grid:mc` | Same as above |
-| `/grid:update` | Pull latest updates from GitHub |
-| `/grid:init` | Initialize `.grid/` state directory |
-| `/grid:help` | Show command reference |
+| `/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 |
 
 ---
 
-## Programs (Agents)
+## State Persistence
 
-Master Control spawns these specialized Programs:
+Grid saves state locally in `.grid/`:
 
-### Planner Program
-Creates execution plans from your description. Decomposes work into Blocks (task groups) and Threads (atomic tasks).
-
-### Executor Program
-Does the actual coding. Makes atomic git commits. Reports back to Master Control.
+```
+.grid/
+├── STATE.md           # Current progress
+├── LEARNINGS.md       # Patterns from past projects
+├── REFINEMENT_PLAN.md # Issues found during testing
+└── phases/            # Execution plans
+```
 
-### Recognizer Program
-Aerial patrol unit. Surveys codebase for anomalies, captures defects, verifies work achieved goals. Circuits glow red under Master Control.
+**Close your terminal. Come back tomorrow. Grid picks up where you left off.**
 
-### Guard Program
-Security enforcement. Checks permissions, validates inputs, prevents destructive actions without User approval.
+> **Tip:** Add `.grid/` to your `.gitignore` - it's local working state, not project code.
 
 ---
 
-## State Management
+## FAQ
 
-The Grid maintains state in `.grid/` directory:
+<details>
+<summary><strong>How much does this cost in API tokens?</strong></summary>
 
-```
-.grid/
-├── STATE.md        # Current position, decisions
-├── clusters/       # Cluster plans and summaries
-└── discs/          # Identity Discs for Programs
-```
+Grid uses more API calls (multiple workers), but each call is *smaller* because contexts stay clean. In practice:
 
-Master Control checks `.grid/STATE.md` on every invocation to understand current position.
+- **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>
 
-## Philosophy
+<details>
+<summary><strong>What if something goes wrong?</strong></summary>
 
-**Master Control stays lean.** Heavy work happens in fresh subagent context windows.
+**Worker fails mid-task:**
+- State is saved in `.grid/`
+- Run `/grid` again - it resumes from last checkpoint
+- Or delete `.grid/` to start fresh
 
-- Master Control orchestrates, never executes directly
-- Programs do work, report back to Master Control
-- User only talks to Master Control
-- I/O Towers surface decisions to User
-- Recognizers patrol and verify
-- Guards enforce security
+**Worker makes a mistake:**
+- Recognizer catches most issues automatically
+- If something slips through, describe the problem and Grid spawns a fix
 
-**"End of Line."**
+**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>
 
-## Architecture
+<details>
+<summary><strong>How is this different from just opening multiple Claude tabs?</strong></summary>
 
-```
-~/.claude/
-├── commands/
-│   ├── grid.md              # /grid shortcut
-│   └── grid/
-│       ├── mc.md            # Master Control
-│       ├── init.md          # Initialize state
-│       ├── help.md          # Command reference
-│       └── VERSION          # v1.1.0
-└── agents/
-    ├── grid-planner.md      # Creates plans
-    ├── grid-executor.md     # Does work
-    ├── grid-recognizer.md   # Patrols/verifies
-    └── grid-guard.md        # Security
-```
+You *could* manually manage multiple conversations, copy context between them, track what each is doing, merge their outputs...
+
+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>Does it work on Windows?</strong></summary>
+
+Yes, via WSL (Windows Subsystem for Linux). Native Windows support is untested but may work.
+
+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 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:
 
-Issues and PRs welcome.
+| 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) |
+
+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.
 
 ---
 
 <p align="center">
-  <i>"I fight for the Users."</i>
+  <strong>"I fight for the Users."</strong>
   <br><br>
-  <b>End of Line.</b>
+  <sub>End of Line.</sub>
 </p>