the-grid-cc 1.7.1 → 1.7.3

package/01-SUMMARY.md

@@ -0,0 +1,95 @@
+---
+cluster: grid-viz
+block: 01
+subsystem: tooling
+requires:
+  - block: none
+    provides: "Initial block"
+provides:
+  - "Terminal visualization tool for Grid state"
+  - "Colorful CLI output with progress bars and status"
+  - "Scratchpad, blockers, and learnings display"
+affects:
+  - Future Grid monitoring and debugging workflows
+tech-stack:
+  added: [chalk@4.1.2, Node.js CLI]
+  patterns: [markdown parsing, terminal visualization, ANSI colors]
+key-files:
+  created:
+    - tools/grid-viz/grid-viz.js
+    - tools/grid-viz/package.json
+    - tools/grid-viz/README.md
+    - tools/grid-viz/package-lock.json
+  modified: []
+commits: [210b17a, 13407a9, 8e3313b]
+
+# WARMTH - knowledge that survives to next Program
+lessons_learned:
+  codebase_patterns:
+    - "Grid state lives in .grid/ directory at project root"
+    - "STATE.md uses markdown with ## headings and **Label:** format"
+    - "Scratchpad entries use ### for entry headers"
+    - "LEARNINGS.md, BLOCKERS.md, DECISIONS.md use bullet lists"
+  gotchas:
+    - "chalk ^4.1.2 is CommonJS compatible; v5+ is ESM only"
+    - "Node.js scripts need #!/usr/bin/env node shebang"
+    - "chmod +x required for executable scripts"
+  user_preferences:
+    - "User prefers ANSI art and terminal aesthetics (Grid theme)"
+    - "Clean output with visual hierarchy (colors, spacing)"
+    - "'End of Line.' footer matches Grid lore"
+  almost_did:
+    - "Considered using chalk v5, chose v4 for CommonJS compatibility"
+    - "Almost used JSON for state, but Grid uses markdown"
+  fragile_areas:
+    - "Markdown parsing is basic - assumes specific formatting"
+    - "Progress percentage extraction uses regex - brittle if format changes"
+---
+
+# Block 01: grid-viz Terminal Visualization Summary
+
+**One-liner:** Terminal visualization tool displaying Grid state with colorful CLI output, progress bars, and scratchpad entries using chalk@4.1.2
+
+## Tasks Completed
+
+| Thread | Name | Commit | Files |
+|--------|------|--------|-------|
+| 1 | Create grid-viz.js | 210b17a | grid-viz.js (248 lines) |
+| 2 | Create package.json and README | 13407a9 | package.json, README.md |
+| 3 | Test and install dependencies | 8e3313b | node_modules/, package-lock.json |
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Decisions Made
+
+**1. Use chalk v4.1.2 instead of v5+**
+- Rationale: v4 uses CommonJS (require), v5+ is ESM-only
+- Grid tooling expects traditional Node.js scripts
+- Better compatibility with existing tools
+
+**2. Auto-discover .grid directory**
+- Rationale: User can run from anywhere in project tree
+- Searches current directory and parents
+- More convenient than requiring exact path
+
+**3. Graceful degradation for missing files**
+- Rationale: Not all .grid files exist in every project
+- Tool should show what's available
+- Better UX than failing on missing files
+
+**4. Parse markdown instead of JSON**
+- Rationale: Grid uses markdown for human readability
+- STATE.md, SCRATCHPAD.md are markdown format
+- Simple regex/string parsing sufficient
+
+## Next Block Readiness
+
+Tool is ready for integration into Grid CLI if desired. Potential enhancements:
+- Add watch mode (--watch flag for live updates)
+- Export JSON format for programmatic use
+- Add filtering options (--blockers-only, --scratchpad-only)
+- Integration with grid status command
+
+No blockers for future work.

package/README.md

@@ -1,33 +1,51 @@
-# THE GRID
+<h1 align="center">THE GRID</h1>
 
 <p align="center">
-  <strong>From install to shipping features: 5 minutes.</strong>
-  <br>
-  Multi-agent orchestration for Claude Code that keeps your context clean
+  <strong>Multi-agent orchestration for Claude Code that keeps your context clean.</strong>
 </p>
 
 <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>
+  Solves context rot — the quality degradation that happens as Claude fills its context window.
 </p>
 
 <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"/>
+    <img src="https://img.shields.io/npm/dm/the-grid-cc?style=for-the-badge&color=blue" alt="npm downloads"/>
+  </a>
+  <a href="https://github.com/JamesWeatherhead/grid/stargazers">
+    <img src="https://img.shields.io/github/stars/JamesWeatherhead/grid?style=for-the-badge&color=yellow" alt="GitHub stars"/>
   </a>
+</p>
+
+<p align="center">
   <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"/>
+    <img src="https://img.shields.io/badge/LICENSE-MIT-cyan.svg?style=for-the-badge" alt="MIT License"/>
   </a>
 </p>
 
+<br>
+
+<p align="center">
+
+```
+npx the-grid-cc
+```
+
+</p>
+
+<p align="center">
+  <strong>Works on Mac, Windows, and Linux.</strong>
+</p>
+
+<br>
+
+<p align="center">
+  <img src="assets/terminal.svg" alt="The Grid Terminal" width="700"/>
+</p>
+
 ---
 
 ## The Problem

package/assets/terminal.svg

@@ -0,0 +1,120 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 520">
+  <defs>
+    <linearGradient id="termBg" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#2d2d2d"/>
+      <stop offset="100%" style="stop-color:#1a1a1a"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Terminal window -->
+  <rect width="800" height="520" rx="10" fill="url(#termBg)"/>
+
+  <!-- Title bar -->
+  <rect width="800" height="32" rx="10" fill="#3d3d3d"/>
+  <rect y="22" width="800" height="10" fill="#3d3d3d"/>
+
+  <!-- Traffic lights -->
+  <circle cx="20" cy="16" r="6" fill="#ff5f57"/>
+  <circle cx="40" cy="16" r="6" fill="#febc2e"/>
+  <circle cx="60" cy="16" r="6" fill="#28c840"/>
+
+  <!-- Title -->
+  <text x="400" y="20" fill="#888" font-family="SF Mono, Monaco, monospace" font-size="13" text-anchor="middle">Terminal</text>
+
+  <!-- Prompt line -->
+  <text x="20" y="60" font-family="SF Mono, Monaco, Consolas, monospace" font-size="14">
+    <tspan fill="#6cf">~</tspan>
+    <tspan fill="#888"> $ </tspan>
+    <tspan fill="#fff">npx the-grid-cc</tspan>
+  </text>
+
+  <!-- TRON-style GRID logo using rectangles -->
+  <g fill="#0ff" transform="translate(60, 85)">
+    <!-- T -->
+    <rect x="0" y="0" width="40" height="8"/>
+    <rect x="16" y="8" width="8" height="32"/>
+
+    <!-- H -->
+    <rect x="50" y="0" width="8" height="40"/>
+    <rect x="50" y="16" width="24" height="8"/>
+    <rect x="66" y="0" width="8" height="40"/>
+
+    <!-- E -->
+    <rect x="84" y="0" width="24" height="8"/>
+    <rect x="84" y="0" width="8" height="40"/>
+    <rect x="84" y="16" width="20" height="8"/>
+    <rect x="84" y="32" width="24" height="8"/>
+
+    <!-- Space -->
+
+    <!-- G -->
+    <rect x="130" y="0" width="28" height="8"/>
+    <rect x="130" y="0" width="8" height="40"/>
+    <rect x="130" y="32" width="28" height="8"/>
+    <rect x="150" y="20" width="8" height="20"/>
+    <rect x="142" y="20" width="16" height="8"/>
+
+    <!-- R - FIXED: proper R shape with diagonal leg -->
+    <rect x="168" y="0" width="8" height="40"/>
+    <rect x="168" y="0" width="28" height="8"/>
+    <rect x="188" y="0" width="8" height="20"/>
+    <rect x="168" y="16" width="28" height="8"/>
+    <!-- diagonal leg of R - approximated with angled rectangles -->
+    <rect x="180" y="24" width="8" height="8"/>
+    <rect x="188" y="32" width="8" height="8"/>
+
+    <!-- I -->
+    <rect x="210" y="0" width="24" height="8"/>
+    <rect x="218" y="8" width="8" height="24"/>
+    <rect x="210" y="32" width="24" height="8"/>
+
+    <!-- D -->
+    <rect x="244" y="0" width="8" height="40"/>
+    <rect x="244" y="0" width="20" height="8"/>
+    <rect x="264" y="4" width="8" height="32"/>
+    <rect x="244" y="32" width="20" height="8"/>
+  </g>
+
+  <!-- Version and description -->
+  <text font-family="SF Mono, Monaco, Consolas, monospace" font-size="14">
+    <tspan x="60" y="165" fill="#fff">The Grid</tspan>
+    <tspan fill="#888"> v1.7.2</tspan>
+    <tspan x="60" y="185" fill="#888">Multi-agent orchestration for Claude Code</tspan>
+  </text>
+
+  <!-- Installation checkmarks -->
+  <text font-family="SF Mono, Monaco, Consolas, monospace" font-size="14">
+    <tspan x="60" y="225" fill="#28c840">✓</tspan>
+    <tspan fill="#ccc"> Installed commands/grid</tspan>
+    <tspan x="60" y="245" fill="#28c840">✓</tspan>
+    <tspan fill="#ccc"> Installed agents</tspan>
+  </text>
+
+  <!-- Done message -->
+  <text x="60" y="285" font-family="SF Mono, Monaco, Consolas, monospace" font-size="14">
+    <tspan fill="#28c840">Done!</tspan>
+    <tspan fill="#ccc"> Run </tspan>
+    <tspan fill="#fff">/grid</tspan>
+    <tspan fill="#ccc"> to get started.</tspan>
+  </text>
+
+  <!-- Second prompt - /grid session -->
+  <text x="20" y="330" font-family="SF Mono, Monaco, Consolas, monospace" font-size="14">
+    <tspan fill="#6cf">~</tspan>
+    <tspan fill="#888"> $ </tspan>
+    <tspan fill="#fff">/grid</tspan>
+  </text>
+
+  <!-- Master Control output -->
+  <text font-family="SF Mono, Monaco, Consolas, monospace" font-size="14">
+    <tspan x="60" y="375" fill="#0ff" font-weight="bold">THE GRID</tspan>
+    <tspan x="60" y="393" fill="#0ff">════════</tspan>
+    <tspan x="60" y="430" fill="#fff">Master Control online.</tspan>
+    <tspan x="60" y="465" fill="#ccc">What would you like to build?</tspan>
+  </text>
+
+  <!-- Blinking cursor -->
+  <rect x="60" y="480" width="8" height="14" fill="#fff" opacity="0.8">
+    <animate attributeName="opacity" values="0.8;0;0.8" dur="1s" repeatCount="indefinite"/>
+  </rect>
+</svg>

package/commands/grid/VERSION

@@ -1 +1 @@
-1.7.0
+1.7.3

package/commands/grid/help.md

@@ -19,6 +19,7 @@ COMMANDS
   /grid:refine       Run Refinement Swarm (visual, E2E, personas)
   /grid:debug        Start systematic bug investigation
   /grid:status       Show current Grid state
+  /grid:model        Configure model selection (opus/sonnet/haiku)
   /grid:help         This help
 
 MODES
@@ -26,6 +27,12 @@ MODES
   GUIDED             MC drives, asks only when essential.
   HANDS ON           Collaborative decisions.
 
+MODEL TIERS
+  /grid:model quality      Opus for all agents (default, best results)
+  /grid:model balanced     Sonnet for most (good balance)
+  /grid:model budget       Haiku where possible (lowest cost)
+  /grid:model custom       Configure per-agent
+
 REFINEMENT SWARM
   /grid:refine              Full swarm (visual + E2E + personas)
   /grid:refine visual       Screenshot + vision analysis only

package/commands/grid/mc.md

@@ -259,20 +259,48 @@ depends_on: []
 
 ### Model Routing
 
-Route different Programs to different models based on task complexity:
+**Default: QUALITY tier (Opus for all agents)**
+
+Check `.grid/config.json` for user model preferences. Users can configure via `/grid:model`.
 
 | Program | Quality | Balanced | Budget |
 |---------|---------|----------|--------|
 | Planner | opus | sonnet | sonnet |
 | Executor | opus | sonnet | sonnet |
-| Recognizer | sonnet | sonnet | haiku |
+| Recognizer | opus | sonnet | haiku |
+| Visual Inspector | opus | sonnet | haiku |
+| E2E Exerciser | opus | sonnet | haiku |
+| Persona Simulator | opus | sonnet | sonnet |
+| Refinement Synth | opus | sonnet | sonnet |
+
+**Model Selection Logic:**
+```python
+def get_model(program_type):
+    """Get model based on .grid/config.json or default to opus."""
+    try:
+        config = json.loads(read(".grid/config.json"))
+        tier = config.get("model_tier", "quality")
+    except:
+        tier = "quality"  # Default: Opus
+
+    if tier == "quality":
+        return "opus"
+    elif tier == "balanced":
+        return "sonnet"
+    elif tier == "budget":
+        # Some programs need reasoning capability
+        if program_type in ["planner", "executor", "persona_simulator"]:
+            return "sonnet"
+        return "haiku"
+    return "opus"
+```
 
 Pass `model` parameter to Task():
 ```python
 Task(
   prompt="...",
   subagent_type="general-purpose",
-  model="sonnet",  # or "opus", "haiku"
+  model="opus",  # Default: quality tier
   description="..."
 )
 ```

package/commands/grid/model.md

@@ -0,0 +1,188 @@
+# /grid:model - Configure Model Selection
+
+---
+name: grid:model
+description: Configure which Claude model to use for Grid agents
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - AskUserQuestion
+---
+
+Configure which Claude models The Grid uses for its agents.
+
+## USAGE
+
+```
+/grid:model                    # Show current config + options
+/grid:model quality            # Use Opus for everything (best results, highest cost)
+/grid:model balanced           # Use Sonnet for most tasks (good balance)
+/grid:model budget             # Use Haiku where possible (lowest cost)
+/grid:model custom             # Configure per-agent models
+```
+
+## MODEL TIERS
+
+### QUALITY (Default)
+All agents use **Opus** - best reasoning, highest quality output.
+
+| Agent | Model |
+|-------|-------|
+| Planner | opus |
+| Executor | opus |
+| Recognizer | opus |
+| Visual Inspector | opus |
+| E2E Exerciser | opus |
+| Persona Simulator | opus |
+
+**Best for:** Complex projects, production code, when quality matters most.
+**Cost:** ~3-5x more than Balanced.
+
+### BALANCED
+Most agents use **Sonnet** - good reasoning, moderate cost.
+
+| Agent | Model |
+|-------|-------|
+| Planner | sonnet |
+| Executor | sonnet |
+| Recognizer | sonnet |
+| Visual Inspector | sonnet |
+| E2E Exerciser | sonnet |
+| Persona Simulator | sonnet |
+
+**Best for:** Most projects, good quality/cost tradeoff.
+**Cost:** Baseline.
+
+### BUDGET
+Use **Haiku** where possible, Sonnet for complex reasoning.
+
+| Agent | Model |
+|-------|-------|
+| Planner | sonnet (needs reasoning) |
+| Executor | sonnet (needs reasoning) |
+| Recognizer | haiku |
+| Visual Inspector | haiku |
+| E2E Exerciser | haiku |
+| Persona Simulator | sonnet (needs reasoning) |
+
+**Best for:** Prototypes, learning, cost-sensitive projects.
+**Cost:** ~50-70% less than Balanced.
+
+### CUSTOM
+Set each agent individually.
+
+## EXECUTION
+
+When user runs `/grid:model`:
+
+### No argument - Show current config
+```
+MODEL CONFIGURATION
+═══════════════════
+
+Current tier: {tier}
+
+| Agent             | Model   |
+|-------------------|---------|
+| Planner           | {model} |
+| Executor          | {model} |
+| Recognizer        | {model} |
+| Visual Inspector  | {model} |
+| E2E Exerciser     | {model} |
+| Persona Simulator | {model} |
+
+Commands:
+  /grid:model quality   - Opus for everything
+  /grid:model balanced  - Sonnet for most
+  /grid:model budget    - Haiku where possible
+  /grid:model custom    - Configure individually
+
+End of Line.
+```
+
+### With tier argument - Set tier
+```python
+# Read or create config
+config_path = ".grid/config.json"
+try:
+    config = json.loads(read(config_path))
+except:
+    config = {}
+
+# Set tier
+config["model_tier"] = tier  # "quality" | "balanced" | "budget"
+
+# Write config
+write(config_path, json.dumps(config, indent=2))
+```
+
+Display:
+```
+MODEL TIER SET: {TIER}
+═════════════════════
+
+All Grid agents will now use {tier} models.
+
+| Agent             | Model   |
+|-------------------|---------|
+| Planner           | {model} |
+| ...               | ...     |
+
+To change: /grid:model {other_tier}
+
+End of Line.
+```
+
+### Custom mode - Interactive selection
+Use AskUserQuestion to let user pick model for each agent type:
+
+```
+CUSTOM MODEL CONFIGURATION
+══════════════════════════
+
+Select model for each agent type:
+```
+
+Then save to `.grid/config.json`:
+```json
+{
+  "model_tier": "custom",
+  "models": {
+    "planner": "opus",
+    "executor": "sonnet",
+    "recognizer": "haiku",
+    "visual_inspector": "haiku",
+    "e2e_exerciser": "haiku",
+    "persona_simulator": "sonnet"
+  }
+}
+```
+
+## CONFIG FILE FORMAT
+
+`.grid/config.json`:
+```json
+{
+  "model_tier": "quality",
+  "models": {
+    "planner": "opus",
+    "executor": "opus",
+    "recognizer": "opus",
+    "visual_inspector": "opus",
+    "e2e_exerciser": "opus",
+    "persona_simulator": "opus"
+  },
+  "topology": "hierarchical"
+}
+```
+
+## RULES
+
+1. Default to "quality" (Opus) if no config exists
+2. Never use Haiku for Planner/Executor (needs reasoning capability)
+3. Show cost implications when changing tiers
+4. Config persists in `.grid/config.json`
+
+End of Line.

package/commands/grid/refine.md

@@ -127,7 +127,7 @@ Dev server command: {dev_command}
 Execute visual inspection. Save to .grid/refinement/
 """,
   subagent_type="general-purpose",
-  model="sonnet",
+  model="opus",  # Default: quality tier
   description="Visual Inspector"
 )
 
@@ -141,7 +141,7 @@ Dev server command: {dev_command}
 Execute E2E testing. Save to .grid/refinement/
 """,
   subagent_type="general-purpose",
-  model="sonnet",
+  model="opus",  # Default: quality tier
   description="E2E Exerciser"
 )
 
@@ -162,7 +162,7 @@ Become this persona. Use the product. Report findings.
 Save to .grid/refinement/personas/{persona.slug}.md
 """,
     subagent_type="general-purpose",
-    model="sonnet",
+    model="opus",  # Default: quality tier
     description=f"Persona: {persona.name}"
   )
 ```
@@ -196,7 +196,7 @@ Task(
 Synthesize all findings into .grid/REFINEMENT_PLAN.md
 """,
   subagent_type="general-purpose",
-  model="sonnet",
+  model="opus",  # Default: quality tier
   description="Refinement Synthesizer"
 )
 ```

package/package.json

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