the-grid-cc 1.7.13 → 1.7.14

package/commands/grid/daemon.md

@@ -0,0 +1,637 @@
+# /grid:daemon - Background Execution Mode
+
+---
+name: grid:daemon
+description: Fire-and-forget long-running autonomous execution
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+---
+
+Launch, monitor, and control long-running Grid sessions that execute in the background.
+
+## USAGE
+
+```bash
+/grid:daemon "task description"     # Start new daemon
+/grid:daemon status                 # Check active daemon
+/grid:daemon status <id>            # Check specific daemon
+/grid:daemon list                   # List all daemons
+/grid:daemon stop                   # Stop active daemon
+/grid:daemon stop <id>              # Stop specific daemon
+/grid:daemon resume "response"      # Resume from checkpoint
+/grid:daemon logs                   # Tail daemon logs
+/grid:daemon logs <id>              # Tail specific daemon logs
+```
+
+## WHEN TO USE
+
+**Good for:**
+- Complex multi-hour builds
+- Overnight refactoring
+- Large codebase migrations
+- Tasks you want to run while away
+- Background work while you continue coding
+
+**Use regular `/grid` for:**
+- Interactive development
+- Tasks needing frequent input
+- Learning/exploration
+- Quick builds (< 30 min)
+
+---
+
+## BEHAVIOR
+
+### Starting a Daemon
+
+When user runs `/grid:daemon "task"`:
+
+1. **Generate Daemon ID**
+   ```
+   {YYYYMMDD}-{HHMMSS}-{slug}
+   Example: 20260123-143000-build-auth-api
+   ```
+
+2. **Create Daemon Directory**
+   ```
+   .grid/daemon/{daemon-id}/
+   ├── task.txt           # Original task description
+   ├── checkpoint.json    # Execution state
+   ├── heartbeat.json     # Health monitoring
+   ├── output.log         # Full output log
+   └── audit.log          # Action audit trail
+   ```
+
+3. **Initialize Checkpoint**
+   ```json
+   {
+     "version": "1.0",
+     "daemon_id": "{id}",
+     "created": "{ISO timestamp}",
+     "updated": "{ISO timestamp}",
+     "status": "starting",
+     "task": {
+       "description": "{user description}",
+       "mode": "autopilot"
+     },
+     "progress": {
+       "current_wave": 0,
+       "total_waves": 0,
+       "completed_blocks": [],
+       "current_block": null,
+       "percent": 0
+     }
+   }
+   ```
+
+4. **Launch Background Execution**
+
+   **Option A: Claude Code Background Agent (v2.0.60+)**
+   - Spawn Task() with daemon orchestrator
+   - Use Ctrl+B equivalent to background if available
+   - Monitor via scratchpad
+
+   **Option B: External Process (Fallback)**
+   ```bash
+   nohup claude --print -p "..." > .grid/daemon/{id}/output.log 2>&1 &
+   echo $! > .grid/daemon/{id}/pid
+   ```
+
+5. **Display Confirmation**
+   ```
+   DAEMON SPAWNED
+   ══════════════
+
+   ID: 20260123-143000-build-auth-api
+   Task: Build REST API with user authentication
+   Mode: Autopilot
+
+   Status: Initializing
+   Monitor: /grid:daemon status
+   Stop: /grid:daemon stop
+
+   You can close this terminal. Work continues in background.
+
+   End of Line.
+   ```
+
+---
+
+### Checking Status
+
+When user runs `/grid:daemon status`:
+
+1. **Find Active Daemon**
+   - Check `.grid/daemon/*/checkpoint.json` for `status != "complete"`
+   - If multiple active, show list
+   - If none active, show "No active daemons"
+
+2. **Read Checkpoint State**
+   ```json
+   {
+     "status": "executing",
+     "progress": {
+       "current_wave": 2,
+       "total_waves": 4,
+       "percent": 45
+     }
+   }
+   ```
+
+3. **Read Recent Scratchpad/Logs**
+   - Last 10 entries from scratchpad
+   - Last 20 lines from output.log
+
+4. **Display Status**
+   ```
+   DAEMON STATUS
+   ═════════════
+
+   ID: 20260123-143000-build-auth-api
+   Runtime: 1h 23m
+   Status: Executing
+
+   Progress: [█████████░░░░░░░░░░░] 45%
+
+   Current: Wave 2 of 4
+     Block 05 - User Authentication
+     ├─ Thread 5.1: JWT utilities ✓
+     ├─ Thread 5.2: Auth middleware ⚡ In Progress
+     └─ Thread 5.3: Protected routes ○ Pending
+
+   Recent Activity:
+     14:52 - executor-05: Implementing JWT verification
+     14:48 - executor-04: Completed database models
+     14:45 - recognizer: Wave 1 verified ✓
+
+   Commits: 8 made
+   Est. Remaining: ~2h 15m
+
+   End of Line.
+   ```
+
+---
+
+### Handling Checkpoints
+
+When daemon reaches a checkpoint:
+
+1. **Update Checkpoint State**
+   ```json
+   {
+     "status": "checkpoint",
+     "checkpoint_stack": [{
+       "type": "human-verify",
+       "block": "07",
+       "details": {
+         "what_built": "Stripe webhook endpoint",
+         "how_to_verify": ["Run stripe listen...", "Trigger event..."]
+       },
+       "created": "{timestamp}"
+     }]
+   }
+   ```
+
+2. **Attempt Notification**
+   - System notification (if enabled)
+   - Write to `.grid/daemon/{id}/ATTENTION_NEEDED`
+
+3. **Pause Execution**
+   - Daemon waits for user response
+   - Heartbeat continues (shows "checkpoint" status)
+
+4. **Status Shows Checkpoint**
+   ```
+   DAEMON CHECKPOINT
+   ═════════════════
+
+   ID: 20260123-143000-build-auth-api
+   Status: AWAITING USER
+
+   Checkpoint Type: human-verify
+   Block: 07 - Payment Webhooks
+
+   What was built:
+   - Stripe webhook endpoint at /api/webhooks/stripe
+   - Event handlers for payment intents
+   - Signature verification
+
+   How to verify:
+   1. Run: stripe listen --forward-to localhost:3000/api/webhooks/stripe
+   2. Run: stripe trigger payment_intent.succeeded
+   3. Check logs for "Payment succeeded" event
+
+   Resume:
+     /grid:daemon resume "approved"
+     /grid:daemon resume "Issue: [describe problem]"
+
+   End of Line.
+   ```
+
+---
+
+### Resuming from Checkpoint
+
+When user runs `/grid:daemon resume "response"`:
+
+1. **Validate Response**
+   - "approved" / "done" / "yes" → Clear checkpoint, continue
+   - Other text → Pass as feedback, may re-plan
+
+2. **Update Checkpoint**
+   ```json
+   {
+     "status": "executing",
+     "checkpoint_stack": [],
+     "checkpoint_history": [{
+       "type": "human-verify",
+       "response": "approved",
+       "resolved": "{timestamp}"
+     }]
+   }
+   ```
+
+3. **Signal Daemon to Continue**
+   - Write response to `.grid/daemon/{id}/resume.txt`
+   - Daemon monitors this file and continues
+
+4. **Display Confirmation**
+   ```
+   DAEMON RESUMED
+   ══════════════
+
+   Checkpoint cleared: human-verify (Block 07)
+   Response: approved
+
+   Continuing execution...
+
+   Current: Block 08 - Order Management
+   Status: Executing
+
+   End of Line.
+   ```
+
+---
+
+### Stopping a Daemon
+
+When user runs `/grid:daemon stop`:
+
+1. **Request Graceful Stop**
+   - Write "STOP" to `.grid/daemon/{id}/control.txt`
+   - Daemon completes current Program, then exits
+
+2. **Wait for Completion (with timeout)**
+   ```
+   DAEMON STOPPING
+   ═══════════════
+
+   ID: 20260123-143000-build-auth-api
+   Waiting for current work to complete...
+
+   [████████░░░░░░░░░░░░] 40% - Finishing executor-05
+
+   Timeout: 2 minutes (then force stop)
+   ```
+
+3. **Update Final State**
+   ```json
+   {
+     "status": "stopped",
+     "stop_reason": "user_requested",
+     "stopped_at": "{timestamp}"
+   }
+   ```
+
+4. **Display Completion**
+   ```
+   DAEMON STOPPED
+   ══════════════
+
+   ID: 20260123-143000-build-auth-api
+   Final Status: Stopped at Block 05
+
+   Work Completed:
+   - Blocks 01-04 complete
+   - Block 05 partial (Thread 5.2 in progress)
+
+   Commits Made: 8
+   Files Modified: 15
+
+   Resume Later:
+     /grid:daemon resume-stopped 20260123-143000-build-auth-api
+
+   End of Line.
+   ```
+
+---
+
+### Listing Daemons
+
+When user runs `/grid:daemon list`:
+
+```
+DAEMON LIST
+═══════════
+
+Active:
+  20260123-143000-build-auth-api    Executing    45%    1h 23m
+
+Checkpointed:
+  20260122-091500-refactor-db       human-verify          12h ago
+
+Completed:
+  20260121-160000-add-tests         Complete     100%   2d ago
+  20260120-103000-fix-bugs          Complete     100%   3d ago
+
+Stopped:
+  20260119-143000-big-migration     Stopped       60%   4d ago
+
+Commands:
+  /grid:daemon status <id>     View details
+  /grid:daemon resume <id>     Resume checkpointed
+  /grid:daemon logs <id>       View logs
+  /grid:daemon clean           Remove completed (>7 days)
+
+End of Line.
+```
+
+---
+
+### Viewing Logs
+
+When user runs `/grid:daemon logs`:
+
+```
+DAEMON LOGS
+═══════════
+
+ID: 20260123-143000-build-auth-api
+Showing last 50 lines (tail -f mode):
+
+14:52:33 [executor-05] Starting JWT verification implementation
+14:52:35 [executor-05] Reading existing auth utils...
+14:52:38 [executor-05] Creating src/lib/jwt.ts
+14:52:45 [executor-05] Writing verifyToken function
+14:53:12 [executor-05] Adding refresh token rotation
+14:53:45 [executor-05] Committing: feat(05): Add JWT utilities
+14:53:48 [scratchpad] executor-05: Found pattern - uses jose library
+14:54:02 [executor-05] Thread 5.1 complete
+14:54:05 [executor-05] Starting Thread 5.2: Auth middleware
+...
+
+(Press Ctrl+C to exit log view)
+```
+
+---
+
+## DAEMON ORCHESTRATOR
+
+The daemon uses a specialized orchestrator that:
+
+1. **Operates Headless**
+   - No user prompts
+   - Decisions logged, not asked
+   - Checkpoints pause, don't prompt
+
+2. **Writes Heartbeats**
+   - Every 30 seconds to heartbeat.json
+   - Enables external health monitoring
+
+3. **Checkpoints Aggressively**
+   - After every Program completion
+   - After every wave
+   - On any error
+
+4. **Handles Recovery**
+   - On start, checks for existing checkpoint
+   - Verifies git state matches checkpoint
+   - Resumes or reconciles as needed
+
+### Orchestrator Prompt Template
+
+```python
+Task(
+  prompt=f"""
+First, read ~/.claude/agents/grid-daemon-orchestrator.md for your role.
+
+DAEMON MODE EXECUTION
+═════════════════════
+
+Daemon ID: {daemon_id}
+Task: {task_description}
+Mode: Autopilot (zero user interaction unless checkpoint)
+
+<checkpoint>
+{checkpoint_json if resuming else "New daemon - no prior state"}
+</checkpoint>
+
+<warmth>
+{warmth_from_checkpoint if resuming else "No prior warmth"}
+</warmth>
+
+RULES:
+1. Write heartbeat every 30 seconds
+2. Checkpoint after every Program completes
+3. On checkpoint types, PAUSE and wait for resume signal
+4. Never prompt user - log decisions instead
+5. On error, checkpoint and STOP
+
+Execute the task. Report progress to checkpoint.json.
+""",
+  subagent_type="general-purpose",
+  model="opus",
+  description=f"Daemon: {daemon_id}"
+)
+```
+
+---
+
+## DIRECTORY STRUCTURE
+
+```
+.grid/
+├── STATE.md                    # Regular Grid state
+├── daemon/
+│   ├── active                  # Symlink to active daemon (if any)
+│   ├── 20260123-143000-build-auth-api/
+│   │   ├── task.txt            # Original task
+│   │   ├── checkpoint.json     # Full execution state
+│   │   ├── heartbeat.json      # Health monitoring
+│   │   ├── control.txt         # Control signals (STOP, PAUSE)
+│   │   ├── resume.txt          # Resume responses
+│   │   ├── output.log          # Full Claude output
+│   │   ├── audit.log           # Action audit trail
+│   │   └── ATTENTION_NEEDED    # Flag file when checkpoint hit
+│   └── 20260122-091500-refactor-db/
+│       └── ...
+└── ...
+```
+
+---
+
+## CONFIGURATION
+
+Settings in `.grid/config.json`:
+
+```json
+{
+  "daemon": {
+    "default_mode": "autopilot",
+    "max_runtime_hours": 24,
+    "checkpoint_on_wave_complete": true,
+    "heartbeat_interval_seconds": 30,
+    "stall_threshold_minutes": 30,
+
+    "notifications": {
+      "system": true,
+      "sound": true,
+      "webhook": null
+    },
+
+    "notify_on": {
+      "start": false,
+      "checkpoint": true,
+      "complete": true,
+      "error": true,
+      "stall": true
+    },
+
+    "cleanup": {
+      "auto_clean_completed_days": 7,
+      "keep_audit_logs": true
+    }
+  }
+}
+```
+
+---
+
+## CONSTRAINTS
+
+- **One active daemon per project** (multiple stopped/completed allowed)
+- **Autopilot mode only** (no GUIDED/HANDS ON in daemon)
+- **Checkpoints still require user** (design intentional for safety)
+- **No destructive git operations** without explicit prior approval
+- **Max runtime enforced** (default 24 hours, configurable)
+
+---
+
+## ERROR HANDLING
+
+### Daemon Crash
+
+If daemon process dies unexpectedly:
+
+1. Next `/grid:daemon status` detects no heartbeat
+2. Offers recovery:
+   ```
+   DAEMON RECOVERY NEEDED
+   ══════════════════════
+
+   ID: 20260123-143000-build-auth-api
+   Last Heartbeat: 15 minutes ago
+   Last Checkpoint: Block 05, Thread 5.2
+
+   The daemon appears to have crashed.
+
+   Options:
+     /grid:daemon recover     Resume from last checkpoint
+     /grid:daemon status -f   Force status check
+     /grid:daemon stop -f     Mark as stopped, don't resume
+
+   End of Line.
+   ```
+
+### API Errors
+
+Rate limits, auth failures, etc:
+
+1. Daemon enters exponential backoff
+2. After 5 retries, checkpoints and pauses
+3. Status shows error state:
+   ```
+   Status: ERROR - API rate limit
+   Retry in: 5 minutes
+   Or: /grid:daemon resume "retry now"
+   ```
+
+---
+
+## CURRENT LIMITATIONS
+
+**What works today (via manual setup):**
+- Basic daemon pattern with nohup
+- State persistence via checkpoint files
+- Manual resume via /grid:daemon resume
+
+**What needs Claude Code changes:**
+- Native daemon/service mode
+- Built-in notifications
+- IPC for status queries
+- Automatic crash recovery
+
+**What needs external tooling:**
+- Process monitoring daemon
+- System notification integration
+- Webhook delivery service
+
+See `/docs/DAEMON_ARCHITECTURE.md` for full technical design and future roadmap.
+
+---
+
+## EXAMPLES
+
+### Basic Usage
+
+```bash
+# Start daemon for overnight work
+/grid:daemon "Refactor entire codebase to TypeScript with full type safety"
+
+# Check progress next morning
+/grid:daemon status
+
+# Handle checkpoint
+/grid:daemon resume "approved"
+
+# View logs if something seems wrong
+/grid:daemon logs
+```
+
+### Complex Project
+
+```bash
+# Large project with expected checkpoints
+/grid:daemon "Build complete SaaS application with:
+- User authentication (email + OAuth)
+- Stripe billing integration
+- Admin dashboard
+- API documentation"
+
+# Expected checkpoints:
+# 1. human-verify: Auth flow working
+# 2. human-action: Set up Stripe test keys
+# 3. human-verify: Billing integration working
+# 4. human-verify: Final review
+```
+
+---
+
+## RULES
+
+1. **Fire and forget** - User launches, daemon runs independently
+2. **Checkpoint at boundaries** - Every wave, every completion
+3. **Heartbeat always** - 30 second intervals for health monitoring
+4. **Graceful degradation** - Crash → checkpoint → resume
+5. **No silent failures** - Errors trigger notification + pause
+6. **Audit everything** - Full trail in audit.log
+7. **One active per project** - Prevents conflicts
+8. **Safety first** - Checkpoints for anything destructive
+
+End of Line.