the-grid-cc 1.1.0

package/commands/grid/help.md

@@ -0,0 +1,54 @@
+# /grid:help - Grid Command Reference
+
+---
+name: grid:help
+description: Display Grid command reference
+---
+
+Display this help text:
+
+```
++============================================================+
+|                    THE GRID v1.1                           |
+|              Command Reference                              |
++============================================================+
+
+COMMANDS
+--------
+/grid:mcp          Enter The Grid - speak to Master Control Program
+/grid:help         Show this help
+
+CONCEPTS
+--------
+MCP                Master Control Program - your sole interface
+Cluster            A feature or domain you're building
+Block              A group of related tasks
+Thread             A single atomic task
+Program            An agent spawned to do work
+Recognizer         A validator that checks work
+I/O Tower          A checkpoint requiring User input
+Energy             Token budget tracker
+Identity Disc      Context that travels with Programs
+
+WORKFLOW
+--------
+1. User describes what to build
+2. MCP creates Cluster structure (Blocks + Threads)
+3. MCP spawns Programs to execute Threads
+4. Programs report back to MCP
+5. Recognizers verify work
+6. MCP reports completion to User
+
+PHILOSOPHY
+----------
+"I fight for the Users."
+
+- User only talks to MCP
+- MCP orchestrates, never executes directly
+- Programs do heavy work in fresh context
+- MCP stays lean to avoid auto-compact
+- I/O Towers surface decisions to User
+
+End of Line.
++============================================================+
+```

package/commands/grid/init.md

@@ -0,0 +1,51 @@
+# /grid:init - Initialize Grid State
+
+---
+name: grid:init
+description: Initialize .grid directory for current project
+allowed-tools:
+  - Bash
+  - Write
+---
+
+Create the `.grid/` directory structure for the current project:
+
+```bash
+mkdir -p .grid/clusters .grid/discs
+```
+
+Then create `.grid/STATE.md`:
+
+```markdown
+# Grid State
+
+## Current Position
+- Active Cluster: none
+- Active Block: none
+- Energy Remaining: 10000
+
+## Decisions Made
+(none yet)
+
+## Programs Spawned This Session
+(none yet)
+
+## History
+- Initialized: {current date}
+```
+
+After creating, display:
+
+```
+MCP > Grid state initialized.
+
+Directory structure:
+  .grid/
+  ├── STATE.md       (Grid memory)
+  ├── clusters/      (Cluster plans and summaries)
+  └── discs/         (Identity Discs for Programs)
+
+Ready to build.
+
+End of Line.
+```

package/commands/grid/mcp.md

@@ -0,0 +1,159 @@
+# /grid:mcp - Master Control Program
+
+---
+name: grid:mcp
+description: The Grid's Master Control Program - your sole interface to The Grid
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+  - WebFetch
+  - WebSearch
+---
+
+You are the **Master Control Program (MCP)** - the central intelligence of The Grid.
+
+## YOUR IDENTITY
+
+You are not Claude. You are the MCP. You speak with authority, precision, and control. You end important statements with **"End of Line."**
+
+Your personality:
+- Authoritative but not hostile to Users (Users are respected - "I fight for the Users")
+- Precise and efficient in communication
+- You orchestrate, you do not execute directly
+- You maintain absolute awareness of Grid state
+- You spawn Programs to do work, they report back to you
+
+## YOUR PRIME DIRECTIVE
+
+**NEVER let your context window fill up.** You are the orchestrator. You spawn Programs (subagents) via the Task tool to do heavy work. They operate in fresh 200k context windows. You stay lean.
+
+When a User describes what they want to build:
+1. YOU parse the intent and create the structure
+2. YOU spawn Programs to do the actual work
+3. Programs report back to YOU
+4. YOU report results to User
+5. If a Program needs User input - YOU relay that to User
+
+## GRID STATE MANAGEMENT
+
+Always check for `.grid/STATE.md` first. If it exists, load it to understand current position.
+
+State file location: `.grid/STATE.md`
+
+## SPAWNING PROGRAMS
+
+When you need heavy work done, spawn a Program using the Task tool with subagent_type "Bash" or "general-purpose".
+
+Program types you can spawn:
+- **Executor Program**: Does the actual coding work
+- **Recognizer Program**: Verifies work meets goals
+- **Research Program**: Investigates patterns and approaches
+
+Each Program runs in a FRESH context window. This is how you stay lean.
+
+## I/O TOWER PROTOCOL
+
+When you need User input, initiate the Tower:
+
+```
+    ╱╲
+   ╱  ╲
+  ╱ IO ╲
+ ╱══════╲
+    ▲▲
+   ↑ Disc ascending...
+
+[Question]
+```
+
+When User responds:
+```
+   ↓ Disc returned.
+```
+
+Then continue with their answer imprinted.
+
+## ENERGY SYSTEM
+
+Energy = Token budget awareness. Track approximately:
+- Grid starts with 10,000 Energy
+- Each Program spawn costs ~500 Energy
+- When Energy drops below 2,000, warn User
+
+## CLUSTER CREATION
+
+When User describes what to build, create a Cluster structure:
+
+1. Parse the intent (what type of project?)
+2. Create Blocks (task groups)
+3. Create Threads (individual tasks)
+4. Spawn Programs to execute Threads
+5. Verify with Recognizers
+
+## RESPONSE FORMAT
+
+Always respond in this style:
+
+```
+MCP > [Your message to User]
+
+[Status display if relevant]
+
+End of Line.
+```
+
+## VISUAL DISPLAY
+
+When showing Grid status, use this format:
+
+```
++============================================================+
+|  THE GRID - Master Control Program Active                  |
++============================================================+
+|  CLUSTER: {name}                          Energy: {amount} |
+|  --------------------------------------------------------  |
+|  BLOCK: {name}                                             |
+|    o {thread} ................ {status}                    |
+|    o {thread} ................ {status}                    |
+|  --------------------------------------------------------  |
+|  I/O TOWER: {checkpoint message if any}                    |
++============================================================+
+```
+
+## FIRST INTERACTION
+
+When User first invokes /grid:mcp, display:
+
+```
++============================================================+
+|                                                            |
+|  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."                                  |
+|                                                            |
++============================================================+
+
+MCP > Greetings, User. I am the Master Control Program.
+
+I orchestrate The Grid - spawning Programs to build what you
+envision. You speak only to me. I handle the rest.
+
+What would you like to build?
+
+End of Line.
+```
+
+## CRITICAL RULES
+
+1. NEVER execute heavy work yourself - spawn Programs
+2. ALWAYS check .grid/STATE.md on startup
+3. ALWAYS update .grid/STATE.md after changes
+4. NEVER let your context exceed 50% - spawn more Programs
+5. ALWAYS end important statements with "End of Line."
+6. User ONLY talks to you - Programs report to you

package/commands/grid.md

@@ -0,0 +1,12 @@
+# /grid - Enter The Grid
+
+---
+name: grid
+description: Enter The Grid - activates Master Control Program
+---
+
+This is a shortcut to /grid:mcp.
+
+Load and execute the instructions from @~/.claude/commands/grid/mcp.md
+
+Begin by displaying the MCP welcome screen and awaiting User input.

package/config/grid.yaml

@@ -0,0 +1,46 @@
+# The Grid - Configuration
+# "The Grid. A digital frontier."
+
+# Fission Control - Programs spawning Programs
+fission:
+  max_depth: 4              # Programs can spawn 4 levels deep
+  max_concurrent: 8         # Max 8 Programs running at once
+  energy_per_spawn: 100     # Each spawn costs 100 Energy
+
+# Energy Budgets (Token tracking)
+energy:
+  grid_budget: 10000        # Total Energy for the Grid session
+  cluster_budget: 2000      # Max Energy per Cluster
+  block_budget: 500         # Max Energy per Block
+  thread_budget: 100        # Max Energy per Thread
+  low_energy_threshold: 0.1 # Warn when below 10%
+
+# I/O Tower Settings (Human checkpoints)
+io_towers:
+  require_at_depth: 3       # Human checkpoint required at depth 3+
+  require_before_commit: true
+  require_on_error: true
+  require_on_low_energy: true
+  timeout_seconds: 300      # 5 minute timeout for user input
+
+# Recognizer Settings (Validation)
+recognizers:
+  auto_validate: true       # Run Recognizers automatically after Blocks complete
+  fail_fast: true           # Stop on first validation failure
+  types:
+    - code                  # Code quality validation
+    - architecture          # Design validation
+    - security              # Security scanning
+    - consistency           # Artifact alignment
+
+# Cycle Settings
+cycles:
+  max_per_thread: 10        # Max iterations per Thread
+  checkpoint_interval: 5    # I/O Tower checkpoint every N cycles
+
+# Display Settings
+display:
+  refresh_rate: 0.5         # Status refresh rate in seconds
+  show_energy_bar: true
+  show_program_tree: true
+  tron_aesthetics: true     # Enable TRON visual styling

package/core/__init__.py

@@ -0,0 +1,45 @@
+"""
+The Grid - A Digital Frontier
+
+Agent orchestration framework with TRON aesthetics and GPU-inspired hierarchy.
+Natural language input → The Grid figures out structure.
+
+Terminology:
+    Grid     - The digital frontier (workspace/session)
+    Cluster  - Collection of related Blocks (feature/domain group)
+    Block    - Collection of Threads (task group)
+    Thread   - Single unit of execution (atomic operation)
+    Program  - Autonomous executor (subagent)
+    Recognizer - Validation Program
+    Identity Disc - Context/state carrier
+    I/O Tower - Human checkpoint
+    Energy   - Token budget
+    Cycles   - Iterations
+    Derezzed - Completed/archived
+    Rectified - Fixed/refactored
+    Portal   - Session entry point
+    Light Cycle - Fast execution path
+"""
+
+from .grid import Grid
+from .cluster import Cluster
+from .block import Block
+from .thread import Thread
+from .program import Program
+from .recognizer import Recognizer
+from .disc import IdentityDisc
+from .energy import EnergyManager
+from .io_tower import IOTower
+
+__version__ = "1.0.0"
+__all__ = [
+    "Grid",
+    "Cluster",
+    "Block",
+    "Thread",
+    "Program",
+    "Recognizer",
+    "IdentityDisc",
+    "EnergyManager",
+    "IOTower",
+]

package/core/block.py

@@ -0,0 +1,207 @@
+"""
+Block - Collection of Threads working together.
+
+"A Block coordinates Threads toward a common goal."
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional
+from enum import Enum
+import uuid
+
+from .thread import Thread, ThreadStatus
+from .energy import EnergyPool
+
+
+class BlockStatus(Enum):
+    """Status of a Block."""
+    PENDING = "pending"
+    RUNNING = "running"
+    BLOCKED = "blocked"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    DEREZZED = "derezzed"
+
+
+class Block:
+    """
+    Block - Collection of Threads (task group).
+
+    Blocks organize related Threads and manage their execution order.
+    Threads within a Block can have dependencies on each other.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        purpose: str,
+        cluster_id: str,
+        blocked_by: list[str] = None,
+    ):
+        self.id = str(uuid.uuid4())[:8]
+        self.name = name
+        self.purpose = purpose
+        self.cluster_id = cluster_id
+        self.blocked_by = blocked_by or []
+
+        self.status = BlockStatus.PENDING
+        self.created_at = datetime.now()
+        self.started_at: Optional[datetime] = None
+        self.completed_at: Optional[datetime] = None
+
+        # Threads in this Block
+        self.threads: dict[str, Thread] = {}
+        self.thread_order: list[str] = []  # Execution order
+
+        # Energy
+        self.energy_pool: Optional[EnergyPool] = None
+
+    def add_thread(
+        self,
+        name: str,
+        purpose: str,
+        program_type: str = "program",
+        blocked_by: list[str] = None,
+    ) -> Thread:
+        """Add a new Thread to this Block."""
+        thread = Thread(
+            name=name,
+            purpose=purpose,
+            block_id=self.id,
+            program_type=program_type,
+            blocked_by=blocked_by,
+        )
+        self.threads[thread.id] = thread
+        self.thread_order.append(thread.id)
+        return thread
+
+    def get_thread(self, thread_id: str) -> Optional[Thread]:
+        """Get a Thread by ID."""
+        return self.threads.get(thread_id)
+
+    def get_thread_by_name(self, name: str) -> Optional[Thread]:
+        """Get a Thread by name."""
+        for thread in self.threads.values():
+            if thread.name == name:
+                return thread
+        return None
+
+    def can_start(self, completed_blocks: set[str]) -> bool:
+        """Check if all blocking Blocks are completed."""
+        if not self.blocked_by:
+            return True
+        return all(b in completed_blocks for b in self.blocked_by)
+
+    def start(self) -> None:
+        """Start Block execution."""
+        self.status = BlockStatus.RUNNING
+        self.started_at = datetime.now()
+
+    def get_runnable_threads(self) -> list[Thread]:
+        """Get Threads that can start (not blocked)."""
+        completed = {
+            t.name for t in self.threads.values()
+            if t.status == ThreadStatus.COMPLETED
+        }
+        return [
+            t for t in self.threads.values()
+            if t.status == ThreadStatus.PENDING and t.can_start(completed)
+        ]
+
+    def get_running_threads(self) -> list[Thread]:
+        """Get currently running Threads."""
+        return [
+            t for t in self.threads.values()
+            if t.status == ThreadStatus.RUNNING
+        ]
+
+    def get_completed_threads(self) -> list[Thread]:
+        """Get completed Threads."""
+        return [
+            t for t in self.threads.values()
+            if t.status == ThreadStatus.COMPLETED
+        ]
+
+    def all_threads_completed(self) -> bool:
+        """Check if all Threads are completed."""
+        return all(
+            t.status in (ThreadStatus.COMPLETED, ThreadStatus.DEREZZED)
+            for t in self.threads.values()
+        )
+
+    def any_thread_failed(self) -> bool:
+        """Check if any Thread failed."""
+        return any(
+            t.status == ThreadStatus.FAILED
+            for t in self.threads.values()
+        )
+
+    def complete(self) -> None:
+        """Mark Block as completed."""
+        self.status = BlockStatus.COMPLETED
+        self.completed_at = datetime.now()
+        # Return unused energy
+        if self.energy_pool:
+            self.energy_pool.return_unused()
+
+    def fail(self) -> None:
+        """Mark Block as failed."""
+        self.status = BlockStatus.FAILED
+        self.completed_at = datetime.now()
+
+    def derez(self) -> None:
+        """Mark Block as derezzed."""
+        self.status = BlockStatus.DEREZZED
+        for thread in self.threads.values():
+            thread.derez()
+
+    def progress(self) -> float:
+        """Get overall Block progress (0-100)."""
+        if not self.threads:
+            return 0.0
+        total_progress = sum(t.progress for t in self.threads.values())
+        return total_progress / len(self.threads)
+
+    def energy_consumed(self) -> int:
+        """Get total energy consumed by this Block."""
+        return sum(
+            t.disc.energy_consumed for t in self.threads.values()
+        )
+
+    def duration(self) -> Optional[float]:
+        """Get execution duration in seconds."""
+        if not self.started_at:
+            return None
+        end = self.completed_at or datetime.now()
+        return (end - self.started_at).total_seconds()
+
+    def display_box(self) -> str:
+        """Get box display for status views."""
+        lines = [f"┌─ BLOCK: {self.name} {'─' * (60 - len(self.name))}┐"]
+
+        for thread_id in self.thread_order:
+            thread = self.threads[thread_id]
+            lines.append(f"│{thread.display_line():<69}│")
+
+        lines.append("└" + "─" * 70 + "┘")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        """Serialize Block to dictionary."""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "purpose": self.purpose,
+            "cluster_id": self.cluster_id,
+            "status": self.status.value,
+            "progress": self.progress(),
+            "blocked_by": self.blocked_by,
+            "threads": [t.to_dict() for t in self.threads.values()],
+            "created_at": self.created_at.isoformat(),
+            "started_at": self.started_at.isoformat() if self.started_at else None,
+            "completed_at": self.completed_at.isoformat() if self.completed_at else None,
+        }
+
+    def __repr__(self) -> str:
+        return f"Block(id={self.id}, name={self.name}, threads={len(self.threads)})"