the-grid-cc 1.7.13 → 1.7.14

package/commands/grid/init.md

@@ -2,50 +2,407 @@
 
 ---
 name: grid:init
-description: Initialize .grid directory for current project
+description: Initialize .grid directory for current project with full persistence support
 allowed-tools:
   - Bash
   - Write
 ---
 
-Create the `.grid/` directory structure for the current project:
+Initialize the `.grid/` directory structure for the current project. This creates all directories and files needed for state persistence, enabling mission recovery via `/grid:resume`.
+
+## USAGE
+
+```
+/grid:init              # Initialize in current directory
+/grid:init --force      # Reinitialize (preserves existing state)
+```
+
+## DIRECTORY STRUCTURE
+
+Create the complete `.grid/` directory structure:
 
 ```bash
-mkdir -p .grid/clusters .grid/discs
+mkdir -p .grid/plans .grid/phases .grid/discs .grid/debug .grid/refinement/screenshots .grid/refinement/e2e .grid/refinement/personas
 ```
 
-Then create `.grid/STATE.md`:
+### Directory Purposes
+
+| Directory | Purpose | Persistence |
+|-----------|---------|-------------|
+| `.grid/` | Root state directory | Session-scoped |
+| `.grid/plans/` | Execution plans (PLAN.md files) | Mission-scoped |
+| `.grid/phases/` | Execution artifacts (SUMMARY.md files) | Mission-scoped |
+| `.grid/discs/` | Identity Discs for Programs | Session-scoped |
+| `.grid/debug/` | Debug session state | Survives /clear |
+| `.grid/refinement/` | Refinement swarm outputs | Mission-scoped |
+
+## CORE STATE FILES
+
+### STATE.md (Central State)
+
+The primary state file - always read first on resume:
 
 ```markdown
+---
+# Identity
+cluster: null
+session_id: "{timestamp}-init"
+status: initialized  # initialized | active | checkpoint | interrupted | completed | failed
+
+# Position tracking
+position:
+  phase: 0
+  phase_total: 0
+  phase_name: null
+  block: 0
+  block_total: 0
+  wave: 0
+  wave_total: 0
+
+# Progress
+progress_percent: 0
+energy_remaining: 10000
+
+# Execution mode
+mode: autopilot  # autopilot | guided | hands_on
+
+# Timestamps
+created_at: "{ISO timestamp}"
+updated_at: "{ISO timestamp}"
+---
+
 # Grid State
 
 ## Current Position
 - Active Cluster: none
 - Active Block: none
-- Energy Remaining: 10000
+- Status: Initialized
+
+Progress: [----------] 0%
+
+## Session Info
+- Initialized: {current date}
+- Session ID: {session_id}
+- Mode: AUTOPILOT
+
+## Last Activity
+Initialized Grid state directory.
+
+## Notes
+Ready for /grid to begin a mission.
+```
+
+### WARMTH.md (Institutional Knowledge)
+
+Template for accumulated knowledge:
+
+```markdown
+---
+cluster: null
+accumulated_from: []
+last_updated: "{ISO timestamp}"
+---
+
+# Grid Warmth
+
+Accumulated knowledge from Programs. Survives session death.
+
+## Codebase Patterns
+(Patterns discovered about the codebase)
+
+## Gotchas
+(Traps and pitfalls to avoid)
+
+## User Preferences
+(Inferred user preferences)
 
 ## Decisions Made
-(none yet)
+(Key decisions and their rationale)
 
-## Programs Spawned This Session
-(none yet)
+## Almost Did
+(Approaches considered but rejected)
 
-## History
-- Initialized: {current date}
+## Fragile Areas
+(Code that breaks easily)
+```
+
+### SCRATCHPAD.md (Live Discoveries)
+
+Template for real-time discoveries during execution:
+
+```markdown
+---
+updated: "{ISO timestamp}"
+active_programs: []
+---
+
+# Grid Scratchpad
+
+Live discoveries during execution. Programs write here when they learn something others need to know.
+
+## Format
+
+Each entry must follow:
+```
+### {program-id} | {ISO-timestamp} | {category}
+
+**Finding:** {one clear sentence}
+**Impact:** {who needs to know}
+**Action:** [INFORM_ONLY | REQUIRES_CHANGE | BLOCKER]
+**Details:** {additional context}
+```
+
+Categories: PATTERN | DECISION | BLOCKER | PROGRESS | CORRECTION
+
+---
+
+(Entries will appear below)
+```
+
+### DECISIONS.md (User Decisions Log)
+
+Template for tracking user decisions:
+
+```markdown
+---
+cluster: null
+decision_count: 0
+last_updated: "{ISO timestamp}"
+---
+
+# Grid Decisions Log
+
+User decisions made via I/O Tower. Referenced during resume to maintain consistency.
+
+---
+
+(Decisions will appear below in format:)
+
+## Decision {N}: {ISO timestamp}
+**Question:** {what was asked}
+**Options Presented:**
+  - {option_a}: "{description}"
+  - {option_b}: "{description}"
+**User Choice:** {choice}
+**Rationale:** "{user's reason if given}"
+**Affects:** {blocks/features affected}
+```
+
+### BLOCKERS.md (Blocker Tracking)
+
+Template for tracking blockers:
+
+```markdown
+---
+cluster: null
+active_blockers: 0
+resolved_blockers: 0
+last_updated: "{ISO timestamp}"
+---
+
+# Grid Blockers
+
+Issues that blocked progress. Used for resume and reporting.
+
+---
+
+(Blockers will appear below in format:)
+
+## Blocker {N}: {ACTIVE | RESOLVED}
+**Block:** {block_id}
+**Thread:** {thread_id}
+**Type:** {dependency_missing | human_action_required | external_service | bug}
+**Description:** {what's blocking}
+**Resolution:** {how it was resolved, if resolved}
+**Created At:** {timestamp}
+**Resolved At:** {timestamp, if resolved}
+```
+
+### config.json (Grid Configuration)
+
+Configuration for Grid behavior:
+
+```json
+{
+  "model_tier": "quality",
+  "model_tier_options": ["quality", "balanced", "budget"],
+  "auto_verify": true,
+  "scratchpad_heartbeat_minutes": 5,
+  "stale_threshold_minutes": 10,
+  "max_retry_attempts": 3,
+  "created_at": "{ISO timestamp}"
+}
+```
+
+## INITIALIZATION BEHAVIOR
+
+### Step 1: Check Existing State
+
+```python
+if file_exists(".grid/STATE.md"):
+    state = parse_yaml(read(".grid/STATE.md"))
+    if state.get("status") not in ["completed", "failed", "initialized"]:
+        # Active mission exists
+        display("""
+WARNING: Active Grid mission detected.
+
+Cluster: {state['cluster']}
+Status: {state['status']}
+Progress: {state['progress_percent']}%
+
+Use /grid:resume to continue, or /grid:init --force to reinitialize.
+""")
+        return
+```
+
+### Step 2: Create Directories
+
+```bash
+mkdir -p .grid/plans
+mkdir -p .grid/phases
+mkdir -p .grid/discs
+mkdir -p .grid/debug
+mkdir -p .grid/refinement/screenshots
+mkdir -p .grid/refinement/e2e
+mkdir -p .grid/refinement/personas
 ```
 
-After creating, display:
+### Step 3: Create State Files
 
+Create each core state file with its template.
+
+### Step 4: Create .gitignore Entry
+
+If `.gitignore` exists, suggest adding `.grid/`:
+
+```python
+if file_exists(".gitignore"):
+    gitignore = read(".gitignore")
+    if ".grid/" not in gitignore:
+        suggest("""
+Consider adding to .gitignore:
+
+# Grid state (local only)
+.grid/
+""")
 ```
-MCP > Grid state initialized.
 
-Directory structure:
-  .grid/
-  ├── STATE.md       (Grid memory)
-  ├── clusters/      (Cluster plans and summaries)
-  └── discs/         (Identity Discs for Programs)
+### Step 5: Display Confirmation
+
+```
+GRID INITIALIZED
+================
+
+Directory structure created:
+
+.grid/
+├── STATE.md              Central state file (read first on resume)
+├── WARMTH.md             Institutional knowledge
+├── SCRATCHPAD.md         Live discoveries during execution
+├── DECISIONS.md          User decisions log
+├── BLOCKERS.md           Blocker tracking
+├── config.json           Grid configuration
+│
+├── plans/                Execution plans
+├── phases/               Execution artifacts (SUMMARY.md files)
+├── discs/                Identity Discs for Programs
+├── debug/                Debug session state
+└── refinement/           Refinement swarm outputs
+    ├── screenshots/
+    ├── e2e/
+    └── personas/
 
-Ready to build.
+PERSISTENCE ENABLED
+-------------------
+Your mission state will survive session death.
+Use /grid:resume to continue an interrupted mission.
+
+Ready to build. Run /grid to begin.
 
 End of Line.
 ```
+
+## FORCE REINITIALIZATION
+
+With `--force` flag:
+
+1. Archive existing state (if active):
+   ```bash
+   mv .grid/STATE.md .grid/STATE.md.{timestamp}.bak
+   mv .grid/WARMTH.md .grid/WARMTH.md.{timestamp}.bak
+   ```
+
+2. Preserve completed work:
+   - Keep `.grid/phases/` (SUMMARY.md files)
+   - Keep `.grid/plans/` (for reference)
+
+3. Create fresh state files
+
+4. Display:
+   ```
+   GRID REINITIALIZED
+   ==================
+
+   Archived:
+   - STATE.md -> STATE.md.{timestamp}.bak
+   - WARMTH.md -> WARMTH.md.{timestamp}.bak
+
+   Preserved:
+   - phases/ (completed work)
+   - plans/ (execution plans)
+
+   Fresh state created. Ready to build.
+
+   End of Line.
+   ```
+
+## STATE FILE SCHEMAS
+
+### STATE.md YAML Frontmatter Schema
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `cluster` | string | Yes | Cluster name |
+| `session_id` | string | Yes | Unique session identifier |
+| `status` | enum | Yes | initialized/active/checkpoint/interrupted/completed/failed |
+| `position.phase` | integer | Yes | Current phase number |
+| `position.phase_total` | integer | Yes | Total phases |
+| `position.phase_name` | string | No | Phase name |
+| `position.block` | integer | Yes | Current block number |
+| `position.block_total` | integer | Yes | Total blocks |
+| `position.wave` | integer | Yes | Current wave number |
+| `position.wave_total` | integer | Yes | Total waves |
+| `progress_percent` | integer | Yes | 0-100 |
+| `energy_remaining` | integer | Yes | Energy budget |
+| `mode` | enum | Yes | autopilot/guided/hands_on |
+| `created_at` | ISO8601 | Yes | Creation timestamp |
+| `updated_at` | ISO8601 | Yes | Last update timestamp |
+
+### config.json Schema
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model_tier` | enum | "quality" | quality/balanced/budget |
+| `auto_verify` | boolean | true | Auto-spawn Recognizer |
+| `scratchpad_heartbeat_minutes` | integer | 5 | Expected write frequency |
+| `stale_threshold_minutes` | integer | 10 | When to consider session dead |
+| `max_retry_attempts` | integer | 3 | Max retries on failure |
+
+## PERSISTENCE GUARANTEES
+
+After initialization, the Grid guarantees:
+
+1. **State survives session death** - All progress recorded in files
+2. **Warmth accumulates** - Knowledge transfers across Programs
+3. **Decisions persist** - User choices never need repeating
+4. **Commits are verified** - Git hashes enable state validation
+5. **Plans are preserved** - Full execution plans available for resume
+
+## RELATED COMMANDS
+
+- `/grid` - Begin a mission (auto-initializes if needed)
+- `/grid:resume` - Resume an interrupted mission
+- `/grid:status` - Display current Grid state
+- `/grid:model` - Configure model tier
+
+End of Line.