the-grid-cc 1.7.1 → 1.7.2

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,74 @@
+<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>
+
+  <!-- Terminal content -->
+  <text font-family="SF Mono, Monaco, Consolas, monospace" font-size="14" fill="#ccc">
+    <!-- Prompt -->
+    <tspan x="20" y="60" fill="#6cf">~</tspan>
+    <tspan fill="#888"> $ </tspan>
+    <tspan fill="#fff">npx the-grid-cc</tspan>
+
+    <!-- ASCII Art - THE GRID -->
+    <tspan x="20" y="100" fill="#0ff">  ████████╗██╗  ██╗███████╗     ██████╗ ██████╗ ██╗██████╗ </tspan>
+    <tspan x="20" y="118" fill="#0ff">  ╚══██╔══╝██║  ██║██╔════╝    ██╔════╝ ██╔══██╗██║██╔══██╗</tspan>
+    <tspan x="20" y="136" fill="#0ff">     ██║   ███████║█████╗      ██║  ███╗██████╔╝██║██║  ██║</tspan>
+    <tspan x="20" y="154" fill="#0ff">     ██║   ██╔══██║██╔══╝      ██║   ██║██╔══██╗██║██║  ██║</tspan>
+    <tspan x="20" y="172" fill="#0ff">     ██║   ██║  ██║███████╗    ╚██████╔╝██║  ██║██║██████╔╝</tspan>
+    <tspan x="20" y="190" fill="#0ff">     ╚═╝   ╚═╝  ╚═╝╚══════╝     ╚═════╝ ╚═╝  ╚═╝╚═╝╚═════╝ </tspan>
+
+    <!-- Version -->
+    <tspan x="20" y="230" fill="#fff">The Grid</tspan>
+    <tspan fill="#888"> v1.7.2</tspan>
+
+    <tspan x="20" y="250" fill="#888">Multi-agent orchestration for Claude Code</tspan>
+
+    <!-- Installation -->
+    <tspan x="20" y="290" fill="#28c840">✓</tspan>
+    <tspan fill="#ccc"> Installed commands/grid</tspan>
+    <tspan x="20" y="310" fill="#28c840">✓</tspan>
+    <tspan fill="#ccc"> Installed agents</tspan>
+
+    <!-- Done -->
+    <tspan x="20" y="350" fill="#28c840">Done!</tspan>
+    <tspan fill="#ccc"> Run </tspan>
+    <tspan fill="#fff">/grid</tspan>
+    <tspan fill="#ccc"> to get started.</tspan>
+
+    <!-- Master Control session -->
+    <tspan x="20" y="390" fill="#6cf">~</tspan>
+    <tspan fill="#888"> $ </tspan>
+    <tspan fill="#fff">/grid</tspan>
+
+    <tspan x="20" y="430" fill="#0ff">THE GRID</tspan>
+    <tspan x="20" y="448" fill="#0ff">════════</tspan>
+
+    <tspan x="20" y="478" fill="#fff">Master Control online.</tspan>
+
+    <tspan x="20" y="508" fill="#ccc">What would you like to build?</tspan>
+  </text>
+
+  <!-- Cursor -->
+  <rect x="20" y="495" width="8" height="16" 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.2

package/package.json

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

package/tools/grid-viz/PLAN.md

@@ -0,0 +1,235 @@
+---
+cluster: grid-viz
+block: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - tools/grid-viz/grid-viz.js
+  - tools/grid-viz/package.json
+  - tools/grid-viz/README.md
+autonomous: true
+
+must_haves:
+  truths:
+    - "User can run grid-viz.js and see formatted Grid state"
+    - "Progress bar displays current block/phase completion"
+    - "Recent scratchpad entries are visible"
+    - "Active blockers and decisions are highlighted"
+    - "Warmth/learnings count is shown"
+  artifacts:
+    - path: "tools/grid-viz/grid-viz.js"
+      provides: "Main CLI visualization script"
+      min_lines: 150
+      exports: []
+    - path: "tools/grid-viz/package.json"
+      provides: "Package manifest with chalk dependency"
+      exports: []
+    - path: "tools/grid-viz/README.md"
+      provides: "Usage documentation"
+      min_lines: 20
+  key_links:
+    - from: "grid-viz.js"
+      to: ".grid/STATE.md"
+      via: "fs.readFileSync parse"
+      pattern: "readFileSync.*STATE\\.md"
+    - from: "grid-viz.js"
+      to: ".grid/SCRATCHPAD.md"
+      via: "fs.readFileSync parse"
+      pattern: "readFileSync.*SCRATCHPAD\\.md"
+    - from: "grid-viz.js"
+      to: ".grid/LEARNINGS.md"
+      via: "fs.readFileSync parse"
+      pattern: "readFileSync.*LEARNINGS\\.md"
+---
+
+<objective>
+Build a terminal visualization tool that displays Grid project state in a clear, colorful format.
+
+Purpose: Provide quick visual insight into Grid project progress without reading raw markdown files.
+Output: Single-file Node.js CLI tool with chalk-based terminal rendering.
+</objective>
+
+<context>
+Grid projects store state in .grid/ directory with structured markdown files:
+- STATE.md: Current cluster, blocks, threads, active programs
+- SCRATCHPAD.md: Running notes, discoveries, decisions
+- LEARNINGS.md: Lessons learned during execution
+
+This tool reads these files and renders a dashboard view with:
+- Color-coded sections (chalk)
+- Progress indicators for blocks/threads
+- Recent activity highlights
+- Visual hierarchy
+
+Target usage: `node grid-viz.js` from Grid project root or `node /path/to/grid-viz.js` from anywhere.
+</context>
+
+<threads>
+
+<thread type="auto">
+  <name>Thread 1: Create grid-viz.js with file parsing and terminal rendering</name>
+  <files>tools/grid-viz/grid-viz.js</files>
+  <action>
+Create grid-viz.js as a single-file Node.js CLI tool:
+
+1. **File Structure:**
+   - Shebang line: `#!/usr/bin/env node`
+   - Import: fs, path, chalk
+   - Helper functions: parseStateFile(), parseScratchpad(), parseLearnings()
+   - Rendering functions: renderHeader(), renderProgress(), renderScratchpad(), renderBlockers(), renderWarmth()
+   - Main function: main()
+
+2. **File Parsing:**
+   - Read .grid/STATE.md: Extract cluster name, status, energy, blocks table
+   - Read .grid/SCRATCHPAD.md: Extract last 5 entries (look for timestamped sections or bullet points)
+   - Read .grid/LEARNINGS.md: Count total learnings entries
+   - Handle missing files gracefully (show "No .grid/ directory found")
+
+3. **Terminal Rendering:**
+   - Header: Cyan bold "GRID PROJECT STATE" with cluster name
+   - Progress section:
+     - Green for COMPLETE blocks/threads
+     - Yellow for IN_PROGRESS
+     - White for PENDING
+     - Bar visualization using Unicode box characters
+   - Scratchpad: Recent discoveries (yellow highlights on key terms)
+   - Blockers: Red-highlighted active decisions from STATE.md "I/O TOWER" section
+   - Warmth: Count of learnings with flame emoji if >0
+
+4. **Color Scheme:**
+   - Headers: cyan bold
+   - Success/complete: green
+   - In-progress: yellow
+   - Pending: white/dim
+   - Errors/blockers: red
+   - Highlights: magenta for important keywords
+
+5. **Error Handling:**
+   - Check if .grid/ exists in current directory
+   - If not, show helpful message: "Not a Grid project. Run from Grid project root."
+   - Gracefully handle malformed markdown
+
+**What to avoid and WHY:**
+- Avoid complex CLI argument parsing - This is a simple visualization tool, not a complex CLI. Keep it single-purpose.
+- Avoid external markdown parsers - Use simple regex/string parsing to keep it lightweight and dependency-free except chalk.
+- Avoid real-time watching - This is a snapshot tool. Running it again shows updated state.
+  </action>
+  <verify>Run `node tools/grid-viz/grid-viz.js` from /Users/jacweath/grid and confirm it displays formatted state with colors</verify>
+  <done>grid-viz.js exists, reads all three .grid files, renders colorful terminal output with progress bars, scratchpad highlights, and warmth summary</done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 2: Create package.json and README.md</name>
+  <files>tools/grid-viz/package.json, tools/grid-viz/README.md</files>
+  <action>
+Create supporting files:
+
+1. **package.json:**
+```json
+{
+  "name": "grid-viz",
+  "version": "1.0.0",
+  "description": "Terminal visualization for Grid project state",
+  "main": "grid-viz.js",
+  "bin": {
+    "grid-viz": "./grid-viz.js"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}
+```
+
+2. **README.md:**
+Include:
+- Project description
+- Installation: `npm install` in tools/grid-viz/
+- Usage:
+  - From Grid project: `node tools/grid-viz/grid-viz.js`
+  - From anywhere: `node /path/to/grid-viz.js` (must be in Grid project dir)
+  - Future: Install globally with `npm install -g`
+- Screenshot/example output (ASCII art mockup)
+- Requirements: Node 14+, chalk dependency
+- What it displays:
+  - Cluster status and energy
+  - Block/thread progress
+  - Recent scratchpad discoveries (last 5)
+  - Active blockers from I/O Tower
+  - Warmth summary (learnings count)
+
+**What to avoid and WHY:**
+- Avoid overpromising features - Document only what exists now. No "coming soon" features.
+- Avoid complex installation steps - This is a dev tool for Grid maintainers, not public npm package (yet).
+  </action>
+  <verify>Verify package.json is valid JSON and README.md is clear and accurate</verify>
+  <done>package.json and README.md exist with accurate content, npm install works in tools/grid-viz/</done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 3: Test grid-viz with Grid repo state and document output format</name>
+  <files>tools/grid-viz/grid-viz.js</files>
+  <action>
+Test and refine the visualization:
+
+1. **Test Cases:**
+   - Run from /Users/jacweath/grid (has .grid/ directory)
+   - Test with COMPLETE cluster (current state)
+   - Verify colors render correctly in terminal
+   - Check progress bar calculation (e.g., 4/4 threads = 100% = full bar)
+   - Verify scratchpad parsing extracts recent entries
+   - Confirm learnings count is accurate
+
+2. **Output Format Refinement:**
+   - Ensure proper spacing and alignment
+   - Use Unicode box-drawing characters for visual structure:
+     - ┌─┐ │ ├─┤ └─┘ for sections
+     - ▓░ for progress bars
+   - Keep total output under 50 lines for quick scanning
+   - Make "no blockers" state clear (green checkmark)
+
+3. **Edge Cases:**
+   - Empty scratchpad (show "No recent activity")
+   - Zero learnings (show "No learnings recorded yet")
+   - Missing I/O Tower section (skip blockers section)
+   - Malformed STATE.md (show error but don't crash)
+
+4. **Documentation:**
+   - Add inline comments explaining file parsing logic
+   - Document expected .grid/ file structure at top of file
+   - Include example output in README.md
+
+**What to avoid and WHY:**
+- Avoid assuming specific STATE.md formats - Parse flexibly since Grid state format may evolve.
+- Avoid truncating important info - Show all blockers/decisions even if many (they're critical).
+  </action>
+  <verify>Run `cd /Users/jacweath/grid && node tools/grid-viz/grid-viz.js` and confirm output is clear, colorful, and informative</verify>
+  <done>grid-viz tested successfully with Grid repo, handles edge cases gracefully, README includes example output</done>
+</thread>
+
+</threads>
+
+<verification>
+1. Run grid-viz from /Users/jacweath/grid and see formatted output
+2. Check that colors display correctly (cyan headers, green success, yellow warnings, red errors)
+3. Verify progress bars show correct completion percentages
+4. Confirm scratchpad shows last 5 entries
+5. Verify learnings count is accurate
+6. Test error handling by running from non-Grid directory
+7. Confirm package.json dependencies install correctly
+</verification>
+
+<success_criteria>
+- grid-viz.js exists and is executable
+- Displays Grid state with colors using chalk
+- Shows progress bar for blocks/threads
+- Renders recent scratchpad entries (last 5)
+- Highlights active blockers/decisions
+- Shows warmth summary (learnings count)
+- Handles missing .grid/ directory gracefully
+- README.md documents usage clearly
+- Tool runs successfully from Grid project root
+</success_criteria>

package/tools/grid-viz/README.md

@@ -0,0 +1,84 @@
+# grid-viz
+
+Terminal visualization tool for The Grid state.
+
+## What it does
+
+Displays colorful, formatted terminal output showing:
+- Current cluster status (name, status, energy)
+- Phase and block progress with visual progress bars
+- Recent scratchpad entries
+- Active blockers and pending decisions
+- Warmth/learnings count
+
+## Installation
+
+From the grid-viz directory:
+
+```bash
+npm install
+chmod +x grid-viz.js
+```
+
+## Usage
+
+Run from anywhere within a Grid-initialized project:
+
+```bash
+node /Users/jacweath/grid/tools/grid-viz/grid-viz.js
+```
+
+Or if installed globally:
+
+```bash
+npm install -g .
+grid-viz
+```
+
+The tool automatically searches for the `.grid` directory in the current path or parent directories.
+
+## Requirements
+
+- Node.js (v12 or higher)
+- chalk ^4.1.2 (installed via npm)
+
+## Output Format
+
+```
+═══════════════════════════════════════════════════════════════════════
+  THE GRID - State Visualization
+═══════════════════════════════════════════════════════════════════════
+
+Grid directory: /path/to/.grid
+
+CLUSTER STATUS
+  Name:     React Todo App
+  Status:   COMPLETE
+  Energy:   9000
+  Progress: ████████████████████████████████████████ 100%
+  Last:     2026-01-23 - Completed 01-PLAN.md
+
+RECENT SCRATCHPAD ENTRIES
+  [1] executor-01 (2026-01-23 19:00)
+      Found: React hooks require functional components...
+
+WARMTH
+  Learnings: 12 patterns captured
+
+═══════════════════════════════════════════════════════════════════════
+  End of Line.
+```
+
+## Files Parsed
+
+- `.grid/STATE.md` - Cluster status and progress
+- `.grid/SCRATCHPAD.md` - Recent discoveries (last 5)
+- `.grid/LEARNINGS.md` - Captured patterns count
+- `.grid/BLOCKERS.md` - Active blockers (top 5)
+- `.grid/DECISIONS.md` - Pending decisions (top 3)
+
+## Error Handling
+
+- Gracefully handles missing files
+- Shows warning if .grid directory not found
+- Displays available information even if some files are missing