the-grid-cc 1.7.26 → 1.7.27

package/README.md

@@ -57,15 +57,13 @@ npx the-grid-cc    # Install (one command)
 
 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 spawns fresh subagents for heavy work while keeping your main conversation focused on goals.
 
 ```
-YOU ←→ Master Control ←→ Worker Agents
-            ↓
+YOU <-> Master Control <-> Worker Agents
+            |
      Your context stays clean (~15%)
      Workers get fresh 200k windows
      Master Control remembers your goals
@@ -76,57 +74,28 @@ YOU ←→ Master Control ←→ Worker Agents
 
 ---
 
-## Your First Session
-
-Here's exactly what happens when you use The Grid for the first time:
+## Quick Start
 
 ```
-YOU: /grid
-
-GRID: THE GRID
-      ════════
-
-      Master Control online.
-
-      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.
+> /grid
+THE GRID
+========
+Master Control online.
+What would you like to build?
 
-YOU: autopilot
+> build a mass rename cli tool
 
-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
+[MC spawns Planner -> analyzes -> spawns Executor -> builds]
 
-      BUILD COMPLETE
-      ══════════════
+- mass-rename-cli/ created
+- 847 files renamed in test run
+- Published to npm
 
-      Project: auth-api
-      Stack: Express + TypeScript + JWT + Prisma
-      Files: 14 created
-      Tests: 12 passing
-
-      Ready to use. End of Line.
+Total tokens: 12,847 (across 3 agents)
+Your context: stayed at 15%
 ```
 
-**Time from `/grid` to working code: ~10-15 minutes** (depending on complexity)
-
-**Your context usage: ~15%** (workers did the heavy lifting)
+**Time to working code: ~10-15 minutes** | **Your context usage: ~15%**
 
 ---
 
@@ -138,67 +107,49 @@ GRID: Building...
 | **GUIDED** | Answer rare questions | Drive + decide | Most projects |
 | **HANDS ON** | Make key decisions | Present options | Learning / control |
 
-### 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.
+**AUTOPILOT**: Zero questions. Describe what you want, see finished code.
+**GUIDED**: Grid drives but asks when genuinely ambiguous.
+**HANDS ON**: Collaborative. Grid proposes, you approve.
 
 ---
 
 ## How It Works
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│  MASTER CONTROL                                              │
-│  Your single interface. Stays lean. Remembers goals.        │
-└─────────────────────────────────────────────────────────────┘
-                              ↓
++-------------------------------------------------------------+
+|  MASTER CONTROL                                              |
+|  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
+                              |
+    +-----------+-----------+-----------+-----------+-----------+
+    |           |           |           |           |           |
+ PLANNER    EXECUTOR   RECOGNIZER   VISUAL      PERSONA
+ Breaks down Writes code Verifies    Checks UI   Simulates
+ the work    + commits   quality     visually    real users
 ```
 
 **Workers = subagents with fresh context.** They do heavy lifting, report back, terminate. Your main conversation stays focused.
 
 ---
 
-## Features
+## Prompt Upscaling
 
-### Prompt Upscaling
+Every request passes through the **Upscaler** first:
 
-Every mission passes through the **Upscaler** - a research-backed agent that transforms vague prompts into industry-grade specifications:
-
-- **Domain Detection**: Identifies software, science, business, healthcare, finance, legal contexts
-- **Best Practice Research**: Searches for current industry standards using Exa
-- **Constraint Decomposition**: Transforms vague requirements into explicit specifications
-- **Industry Injection**: Auto-adds domain-specific requirements (security for code, HIPAA for healthcare, etc.)
-- **Self-Refine Loop**: Scores and iteratively improves enhancement quality
-
-**Example:**
 ```
-Input:  "build me a login page"
-
-Output: Secure authentication system with:
-        - OWASP-compliant input validation
-        - Rate limiting (5 attempts/15 min)
-        - Argon2 password hashing
-        - CSRF protection
-        - Accessible (WCAG 2.1 AA)
-        - Session security (httpOnly, secure, sameSite)
+You say:  "build me a login page"
+
+Grid builds:
+  - OWASP-compliant input validation
+  - Rate limiting (5 attempts/15 min)
+  - Argon2 password hashing
+  - CSRF protection
+  - Accessible (WCAG 2.1 AA)
 ```
 
-Mode-aware behavior:
-- **AUTOPILOT**: Silent enhancement, proceeds immediately
-- **GUIDED**: Mostly silent, rare clarification if ambiguous
-- **HANDS ON**: Shows enhanced version for approval before proceeding
+Researches best practices. Injects industry standards. You get expert-level specs from casual requests.
 
 ---
 
@@ -215,196 +166,77 @@ Mode-aware behavior:
 
 ---
 
-## State Persistence
+## Speak Grid
 
-Grid saves state locally in `.grid/`:
+| Grid Term | AI Translation |
+|-----------|----------------|
+| Program | Agent with a specific role |
+| Identity Disc | System prompt defining behavior |
+| Master Control | Orchestrator (only one who talks to you) |
+| Spawning | Creating fresh agent instances |
+| Derezzed | Agent completed and returned |
+| Warmth | Context passed between agents |
+| I/O Tower | Checkpoint requiring user input |
 
-```
-.grid/
-├── STATE.md           # Current progress
-├── LEARNINGS.md       # Patterns from past projects
-├── REFINEMENT_PLAN.md # Issues found during testing
-└── phases/            # Execution plans
-```
-
-**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.
+*Programs serve Users. MC coordinates. The Grid connects all. The Tron metaphor maps perfectly to multi-agent AI architecture.*
 
 ---
 
 ## FAQ
 
 <details>
-<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:
+<summary><strong>How is this different from opening multiple Claude tabs?</strong></summary>
 
-- **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.
+Tabs share nothing. Grid agents share warmth - learnings, patterns, gotchas flow between them. Plus they run in parallel with fresh 200k context windows each.
 </details>
 
 <details>
-<summary><strong>What if something goes wrong?</strong></summary>
-
-**Worker fails mid-task:**
-- State is saved in `.grid/`
-- Run `/grid` again - it resumes from last checkpoint
-- Or delete `.grid/` to start fresh
+<summary><strong>Does this cost more tokens?</strong></summary>
 
-**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`
+Yes, but you get more done. Parallel agents = parallel progress. Your main context stays lean while workers do heavy lifting. Complex builds often use *fewer* total tokens (no context bloat, no "remind me what we're building").
 </details>
 
 <details>
-<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...
-
-Grid does all that automatically:
-- Knows what context each worker needs
-- Tracks progress across workers
-- Merges results coherently
-- Maintains your original goals throughout
+<summary><strong>What if something goes wrong?</strong></summary>
 
-It's the difference between being a CEO who delegates vs. a CEO who runs between desks doing everything.
+State saves to `.grid/`. Run `/grid` again to resume. Delete `.grid/` to start fresh. `/grid:status` shows current state.
 </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
+Yes, via WSL. Confirmed: macOS (Intel + Apple Silicon), Linux, 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.
+Yes. Grid adds commands but doesn't modify your existing prompts or workflows.
 </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.
+Install: 30 seconds. Start: `/grid`. Pick AUTOPILOT if unsure. Most users are productive in their first session.
 </details>
 
 ---
 
-## The Language of The Grid
+## State Persistence
 
-The Grid speaks in Tron. Here's how modern AI concepts map to the Grid universe:
+Grid saves state locally in `.grid/`:
 
 ```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                         TRON ↔ AI TERMINOLOGY                               │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  THE GRID SPEAKS              WHAT IT MEANS IN AI/LLM TERMS                 │
-│  ───────────────              ─────────────────────────────                 │
-│                                                                             │
-│  Program                      Agent / Subagent                              │
-│                               An autonomous LLM instance with a specific    │
-│                               role and capabilities                         │
-│                                                                             │
-│  Identity Disc                System Prompt                                 │
-│                               The instructions that define a Program's      │
-│                               identity, capabilities, and behavior          │
-│                                                                             │
-│  Master Control (MC)          Orchestrator Agent                            │
-│                               The central coordinator that routes tasks     │
-│                               and spawns other Programs                     │
-│                                                                             │
-│  The Grid                     Multi-Agent System                            │
-│                               The interconnected network of Programs        │
-│                               working together                              │
-│                                                                             │
-│  I/O Tower                    User Interface / Checkpoint                   │
-│                               Where MC communicates with Users              │
-│                               (Programs never talk to Users directly)       │
-│                                                                             │
-│  Derezzed                     Terminated / Completed                        │
-│                               When a Program finishes and returns context   │
-│                                                                             │
-│  Spawning                     Agent Instantiation                           │
-│                               Creating a new Program with fresh context     │
-│                                                                             │
-│  Warmth Transfer              Context Passing                               │
-│                               Learnings passed between Program generations  │
-│                                                                             │
-│  Recognizer                   Verification Agent                            │
-│                               Program that validates work meets goals       │
-│                                                                             │
-│  Light Cycle                  Execution Thread                              │
-│                               A Program's path through task completion      │
-│                                                                             │
-│  End of Line                  Response Complete                             │
-│                               Signals MC has finished speaking              │
-│                                                                             │
-│  User                         You                                           │
-│                               The human. Programs serve Users.              │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
+.grid/
+├── STATE.md           # Current progress
+├── LEARNINGS.md       # Patterns from past projects
+├── REFINEMENT_PLAN.md # Issues found during testing
+└── phases/            # Execution plans
 ```
 
-### Why Tron?
-
-The Grid isn't just aesthetic. The Tron metaphor maps perfectly to multi-agent AI:
-
-| Tron Concept | AI Reality | Why It Fits |
-|--------------|------------|-------------|
-| Programs have Discs | Agents have system prompts | Identity defines behavior |
-| Programs can be spawned | Agents get fresh context windows | Parallelism and isolation |
-| MC orchestrates | Orchestrator routes tasks | Central coordination |
-| Programs derez when done | Agents return and terminate | Resource management |
-| The Grid connects all | Multi-agent systems coordinate | Emergent capability |
-
-When you understand The Grid, you understand modern AI agent architecture.
-
----
-
-## Quick Glossary
-
-| Grid Term | Plain English |
-|-----------|---------------|
-| Master Control | The orchestrating agent (your main conversation) |
-| Program | Worker agent (subagent doing a specific task) |
-| Identity Disc | System prompt (defines a Program's behavior) |
-| Upscaler | Prompt enhancement agent (transforms vague input into detailed specs) |
-| Recognizer | Quality checker (verifies work meets goals) |
-| Refinement Swarm | Testing suite (visual, E2E, persona simulation) |
-| Warmth | Context/learnings passed between Programs |
-| Derez | Terminate (when a Program completes its task) |
+**Close your terminal. Come back tomorrow. Grid picks up where you left off.**
 
-You don't need to memorize these. Grid explains what it's doing as it works.
+> **Tip:** Add `.grid/` to your `.gitignore` - it's local working state, not project code.
 
 ---
 
@@ -418,7 +250,7 @@ Issues and PRs welcome at [github.com/JamesWeatherhead/grid](https://github.com/
 
 ## Citation
 
-If you use The Grid in academic research or publications, please cite it as follows:
+If you use The Grid in academic research or publications:
 
 ### BibTeX
 
@@ -433,13 +265,6 @@ If you use The Grid in academic research or publications, please cite it as foll
 }
 ```
 
-### Text Citation
-
-```
-Weatherhead, J. (2026). The Grid: Multi-Agent Orchestration Framework for Claude Code.
-GitHub. https://github.com/JamesWeatherhead/grid
-```
-
 ---
 
 ## License

package/commands/grid/VERSION

@@ -1 +1 @@
-1.7.26
+1.7.27

package/package.json

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