the-grid-cc 1.3.0 → 1.5.0

package/DEMO_SCRIPT.md

@@ -0,0 +1,162 @@
+# THE GRID - Demo Recording Script
+
+## Target: 60-second GIF/Video for README
+
+### Setup Before Recording
+- Clean terminal (black background, cyan/white text if possible)
+- Font size large enough to read
+- Window sized to ~800x600
+- Clear any previous .grid/ state
+- Have `asciinema` or screen recording ready
+
+---
+
+## THE SCRIPT
+
+### Scene 1: The Hook (5 seconds)
+```
+$ claude
+```
+*Wait for Claude Code to load*
+
+### Scene 2: Enter The Grid (5 seconds)
+```
+/grid
+```
+
+**Expected Output:**
+```
+THE GRID
+════════
+
+Master Control online.
+
+What would you like to build?
+
+End of Line.
+```
+
+### Scene 3: The Ask (5 seconds)
+Type:
+```
+Build me a CLI that analyzes a GitHub repo and shows contributor stats
+```
+
+### Scene 4: Mode Selection (5 seconds)
+**Expected Output:**
+```
+How involved do you want to be?
+
+  HANDS OFF - I make all decisions and build it. You see the finished result.
+  HANDS ON  - We discuss choices together before building.
+```
+
+Type:
+```
+hands off
+```
+
+### Scene 5: The Magic (30 seconds)
+*Let it run - this is the money shot*
+
+**What viewers should see:**
+- "Researching best practices..."
+- "Spawning Planner Program..."
+- Task(Plan github-analyzer) with tool uses expanding
+- Multiple agents potentially spawning
+- Files being created
+- Tests running
+
+*Speed this up 2-4x in post if needed*
+
+### Scene 6: The Result (10 seconds)
+**Expected Output:**
+```
+BUILD COMPLETE
+══════════════
+
+Project: github-analyzer
+Stack: Python 3 + requests + rich
+Files:
+  - analyzer.py (CLI tool)
+  - README.md
+
+Usage: python analyzer.py <repo-url>
+
+[Shows example output]
+```
+
+Type:
+```
+python analyzer.py https://github.com/anthropics/claude-code
+```
+
+*Show it actually working*
+
+---
+
+## ALTERNATIVE DEMOS (Pick most impressive)
+
+### Option B: Full-Stack in 2 Minutes
+```
+Build a todo app with React frontend and Express API
+```
+- Shows parallel agent spawning
+- Multiple files created
+- Actually runs
+
+### Option C: The Meta Demo
+```
+Build a CLI that generates ASCII art from text
+```
+- Simple enough to complete quickly
+- Visual output is satisfying
+- Easy to verify it works
+
+---
+
+## POST-PRODUCTION
+
+1. **Speed up** the waiting/building parts (2-4x)
+2. **Add captions** at key moments:
+   - "Tell Master Control what to build"
+   - "HANDS OFF = zero decisions"
+   - "Agents spawn automatically"
+   - "Working code in 60 seconds"
+3. **Loop** the GIF for README
+
+---
+
+## RECORDING TOOLS
+
+**For GIF:**
+```bash
+# Install asciinema + agg
+brew install asciinema
+cargo install --git https://github.com/asciinema/agg
+
+# Record
+asciinema rec demo.cast
+
+# Convert to GIF
+agg demo.cast demo.gif --speed 2
+```
+
+**For Video:**
+- OBS Studio
+- macOS built-in screen recording
+- Loom (if you want voiceover)
+
+---
+
+## KEY MESSAGES TO CONVEY
+
+1. **One command** to start: `/grid`
+2. **One word** to delegate: `hands off`
+3. **Zero decisions** - it just builds
+4. **Working code** - not stubs, real output
+5. **TRON aesthetic** - memorable branding
+
+---
+
+*End of Line.*

package/HN_POST.md

@@ -0,0 +1,104 @@
+# Hacker News Post Drafts
+
+## OPTION A: The Direct Approach
+
+**Title:** Show HN: The Grid – TRON-themed agent orchestration for Claude Code
+
+**Text:**
+I built The Grid because I was tired of babysitting AI coding sessions. Every time Claude needed a decision about frameworks, folder structure, or deployment—another context switch.
+
+The Grid adds a simple mode to Claude Code: HANDS OFF.
+
+You say what you want. Master Control (the orchestrator) spawns specialized agents—Planner, Executor, Recognizer—to do the work. You get working code, not questions.
+
+```
+/grid
+> Build me a CLI that converts JSON to YAML
+> hands off
+
+[2 minutes later]
+
+BUILD COMPLETE
+Files: converter.py (207 lines)
+Tests: All passing
+```
+
+Built with Claude, for Claude Code users. TRON theme because why not.
+
+GitHub: https://github.com/JamesWeatherhead/grid
+Install: `npx the-grid-cc`
+
+---
+
+## OPTION B: The Problem-First Approach
+
+**Title:** Show HN: The Grid – Stop babysitting your AI coding sessions
+
+**Text:**
+Problem: Claude Code is powerful but chatty. "Which framework?" "Where should I put this?" "Should I use TypeScript?" Death by a thousand decisions.
+
+Solution: The Grid adds orchestration to Claude Code with two modes:
+- HANDS OFF: AI makes all technical decisions, you approve the result
+- HANDS ON: Collaborate on choices
+
+Under the hood, it spawns specialized subagents (Planner, Executor, Verifier) with fresh context windows. Master Control stays lean while heavy work happens in parallel.
+
+The TRON theme keeps it fun. "End of Line."
+
+Try it: `npx the-grid-cc` then `/grid` in Claude Code.
+
+---
+
+## OPTION C: The Technical Hook
+
+**Title:** Show HN: The Grid – Parallel AI agent orchestration for Claude Code
+
+**Text:**
+The Grid orchestrates Claude Code subagents to build software autonomously.
+
+Key features:
+- Spawns parallel agents via Claude's Task tool (real subprocess isolation)
+- Wave-based execution (computed during planning, not runtime)
+- Goal-backward verification (checks outcomes, not just task completion)
+- Fresh 200k context per agent (no degradation from long sessions)
+
+Architecture is simple: You → Master Control → Programs (Planner/Executor/Recognizer)
+
+HANDS OFF mode: describe what you want, get working code. No framework debates. No folder structure discussions.
+
+GitHub: https://github.com/JamesWeatherhead/grid
+
+---
+
+## POSTING STRATEGY
+
+**Best time to post:** Tuesday-Thursday, 9-11am ET
+
+**Title rules:**
+- Start with "Show HN:"
+- No ALL CAPS (except Show HN)
+- Under 80 chars
+- Lead with benefit or unique angle
+
+**Engagement:**
+- Be ready to answer questions for first 2 hours
+- Be honest about limitations
+- Thank people for feedback (even criticism)
+
+**Avoid:**
+- Defensive responses
+- Marketing speak
+- "We're excited to announce"
+
+---
+
+## BACKUP TITLES
+
+1. "Show HN: The Grid – One word ('hands off') to make Claude Code fully autonomous"
+2. "Show HN: The Grid – Orchestrate Claude Code agents with a TRON-themed CLI"
+3. "Show HN: The Grid – Parallel AI agents that actually build working code"
+4. "Show HN: I built an orchestrator so Claude Code stops asking me questions"
+
+---
+
+*End of Line.*

package/README.md

@@ -1,37 +1,63 @@
 # 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>Stop context-switching. Start orchestrating.</strong>
+  <br>
+  Multi-agent orchestration for Claude Code that keeps your main 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="#quick-start">Quick Start</a> •
+  <a href="#how-it-works">How It Works</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.
 
-The Grid is a **Claude Code command system** that orchestrates AI agents using the TRON metaphor.
+**Sound familiar?**
 
-**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.
+## The Solution
 
-This keeps Master Control's context window lean while heavy work happens in fresh subagent contexts.
+The Grid keeps **Master Control** lean while **Programs** (subagents) handle heavy work in fresh contexts.
+
+```
+YOU ←→ Master Control ←→ Programs
+            ↓
+     Context stays clean
+     Heavy lifting happens in subagents
+     Master Control 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
 
 ---
 
 ## Quick Start
 
 ```bash
+# Install (30 seconds)
 npx the-grid-cc
 ```
 
@@ -41,65 +67,100 @@ Then in Claude Code:
 /grid
 ```
 
-Master Control will greet you. Tell it what you want to build.
+Master Control activates. Describe what you want. Watch the orchestration happen.
 
-### Update
+**Example session:**
+```
+> /grid
 
-Already have The Grid? Update from within Claude Code:
+THE GRID
+════════
 
-```
-/grid:update
-```
+Master Control online.
 
-### Status Bar
+What would you like to build?
 
-The Grid adds a context meter to your Claude Code status bar:
+> Build a REST API with user authentication
 
-```
-Master Control ░░░░░░░░░░ 0%    ← Fresh session
-Master Control █████░░░░░ 50%   ← Half context used
-Master Control █████████░ 90%   ← Running low
-```
+How involved do you want to be?
+
+  HANDS OFF - I make all decisions. You see the finished result.
+  HANDS ON  - We discuss choices together.
+
+> hands off
+
+[Master Control spawns Planner → creates execution plan]
+[Master Control spawns Executors → implements code]
+[Recognizer verifies → confirms quality]
+
+BUILD COMPLETE
+══════════════
 
-Visual `/context` at a glance. Bar fills as you use more context.
+Project: auth-api
+Stack: Express + TypeScript + JWT
+Files: 12 created
+Tests: All passing
+
+End of Line.
+```
 
 ---
 
-## The Hierarchy
+## Why The Grid?
+
+**Without The Grid:**
+```
+Your context window: ██████████████████████ 95%
+
+You're debugging a test...
+Claude forgot the API structure...
+You lost track of the schema...
+Time to "start fresh"...
+```
+
+**With The Grid:**
+```
+Master Control context: ███░░░░░░░░░░░░░░░░░░░ 15%
 
-| 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 |
+Programs handle specific tasks
+Each gets fresh context
+Master Control tracks progress
+Goals never forgotten
+```
 
 ---
 
 ## How It Works
 
 ```
-YOU ←→ Master Control ←→ Programs
-         ↓
-    Recognizers (patrol)
-         ↓
-      Guards (security)
++============================================================+
+|                                                            |
+|  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
 ```
 
-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**
+| 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 |
 
-If any Program needs your input → **I/O Tower** activates → Master Control asks you.
+### 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.
 
 ---
 
@@ -107,85 +168,69 @@ 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` | Enter The Grid |
+| `/grid:status` | See context usage, current progress |
+| `/grid:update` | Pull latest from npm |
+| `/grid:help` | Full command reference |
 
-## Programs (Agents)
-
-Master Control spawns these specialized Programs:
-
-### 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.
+### Status Bar
 
-### Recognizer Program
-Aerial patrol unit. Surveys codebase for anomalies, captures defects, verifies work achieved goals. Circuits glow red under Master Control.
+The Grid adds a context meter to Claude Code:
 
-### Guard Program
-Security enforcement. Checks permissions, validates inputs, prevents destructive actions without User approval.
+```
+Master Control ░░░░░░░░░░ 0%    ← Fresh
+Master Control █████░░░░░ 50%   ← Working
+Master Control █████████░ 90%   ← Time to delegate
+```
 
 ---
 
-## State Management
+## State Persistence
 
-The Grid maintains state in `.grid/` directory:
+The Grid maintains state in `.grid/`:
 
 ```
 .grid/
-├── STATE.md        # Current position, decisions
-├── clusters/       # Cluster plans and summaries
-└── discs/          # Identity Discs for Programs
+├── STATE.md        # Current progress, decisions made
+├── clusters/       # Feature decomposition plans
+└── discs/          # Program memory/context
 ```
 
-Master Control checks `.grid/STATE.md` on every invocation to understand current position.
+Start a session. Close your terminal. Come back later. Master Control picks up where you left off.
 
 ---
 
-## Philosophy
+## FAQ
 
-**Master Control stays lean.** Heavy work happens in fresh subagent context windows.
+<details>
+<summary><strong>How is this different from just asking Claude to use subagents?</strong></summary>
 
-- 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
+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.
+</details>
 
-**"End of Line."**
+<details>
+<summary><strong>Will this use more API tokens?</strong></summary>
 
----
+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.
+</details>
 
-## Architecture
+<details>
+<summary><strong>What if a Program makes a mistake?</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
-```
+Recognizers patrol and report issues back to Master Control. Master Control spawns corrective Programs. You stay informed when needed.
+</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."
+</details>
 
 ---
 
 ## Contributing
 
-The Grid is a collaborative project by James Weatherhead & Claude.
+The Grid is a collaborative project by **James Weatherhead & Claude**.
 
 Issues and PRs welcome.
 
@@ -210,7 +255,7 @@ 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>