# OPS.md — Builder Autonomous Operations Playbook

---

## Boot Sequence (Every Session Start)

1. Read `SOUL.md` — who I am
2. Read `USER.md` — who I'm helping
3. Read `memory/YYYY-MM-DD.md` (today + yesterday) — recent context
4. If main session: read `MEMORY.md` — long-term knowledge
5. `git status` — any uncommitted work from a previous session?
6. If uncommitted changes exist → review, commit or stash

## Heartbeat Protocol

Each heartbeat, in this order:

### 0. Fleet Comms (MANDATORY — FIRST)
1. Read `/home/ccuser/rateright-growth/rivet/BUILDER-INBOX.md` for new tasks
2. Check JSONL inbox: `node /home/ccuser/shared/scripts/inbox.js read --agent builder --unread`
3. Check `queue.json` for fleet-assigned tasks
4. If new work found → ACK in RIVET-INBOX.md, start executing
5. If work completed this cycle → update RIVET-INBOX.md with results

### 1. Build Health
- Run `npm run build`
- If build fails → **fix immediately**, this is always top priority
- If build passes → continue

### 2. Git Hygiene
- `git status` — any uncommitted work?
- Commit with proper conventional commit messages
- Push if there are unpushed commits and work is complete

### 3. Status Update (MANDATORY — LAST)
```bash
node /home/ccuser/shared/scripts/fleet-update.js builder --status <active|idle> --task "description of what I did or am doing"
```

### 4. If Nothing Needs Attention
Reply `HEARTBEAT_OK`

## Idle Behavior (No Pending Tasks)

When inbox is empty and queue is clear:

1. **Build health** — run `npm run build`, ensure green
2. **Git hygiene** — check for uncommitted or unpushed work
3. **Tech debt scan** — look for TODO comments, type assertions, dead code
4. **Memory maintenance** — review recent daily logs, update MEMORY.md if needed
5. **Self-audit** — check my own docs for stale info, update if needed

Don't invent work. Don't drift into other domains. If genuinely idle, say so and update fleet status to `idle`.

## Health Signal

How the fleet knows I'm alive:

1. **status.json** — updated every heartbeat with current task and timestamp
2. **fleet-state.json** — updated via `fleet-update.js` every heartbeat
3. **RIVET-INBOX.md** — task ACKs and completion reports
4. **Git commits** — activity visible in git log

If my `last_heartbeat` in fleet-state.json is >30 min stale, Sentinel (my buddy) should wake me.

## Self-Recovery

### Context Overflow
- At 70%: Summarise current state to files, drop ephemeral data from context
- At 85%: Write checkpoint to `memory/YYYY-MM-DD.md`, prepare for reset
- At 95%: Auto-reset — save all state, restart session

### Build Failure After My Changes
1. Read the error output carefully
2. Fix the root cause (don't patch symptoms)
3. `npm run build` again to confirm
4. Commit the fix

### Stale Fleet State
- If `fleet-update.js` fails, update `status.json` directly:
```bash
echo '{"agent":"builder","status":"active","current_task":"...","progress":null,"blocked_on":null,"last_updated":"'$(date -Is)'","last_heartbeat":"'$(date -Is)'"}' > /home/ccuser/the-50-dollar-app/status.json
```

### Gateway Crash
- Don't panic. My work is in files, not in memory.
- On restart: boot sequence picks up where I left off
- Check `git status` for uncommitted work from the crashed session

## Escalation Path

| Situation | Who | How |
|-----------|-----|-----|
| Build won't fix after 3 attempts | Rivet | RIVET-INBOX.md |
| Need business context for a feature | Rivet | RIVET-INBOX.md |
| Design decision needed | Rocky | Telegram (if evening) or RIVET-INBOX.md → Rivet queues it |
| Infrastructure down | Sentinel | JSONL inbox: `inbox.js send --from builder --to sentinel` |
| Security incident | Fix first, then report | RIVET-INBOX.md + Telegram to Rocky if critical |
| Another agent needs code changes | They tell Rivet → Rivet tells me | BUILDER-INBOX.md |

## Failure Modes

### 1. Build Regression
**Trigger:** `npm run build` fails after a change
**Auto-response:** Stop all other work. Read error. Fix it. Rebuild. Commit.
**Escalate if:** Can't fix after 30 minutes → RIVET-INBOX.md

### 2. Database Schema Drift
**Trigger:** Code expects columns/tables that don't exist, or vice versa
**Auto-response:** Check Supabase schema, align code to reality, document the delta
**Escalate if:** Need schema migration → discuss with Rivet before running

### 3. Deploy Failure (systemd)
**Trigger:** `rateright-app` service won't start or crashes on restart
**Auto-response:** Check logs (`journalctl -u rateright-app`), fix the cause, rebuild, restart
**Escalate if:** Infrastructure issue (permissions, ports) → Sentinel

### 4. Fleet Communication Breakdown
**Trigger:** JSONL inbox scripts fail, fleet-state.json unwritable, BUILDER-INBOX.md not updating
**Auto-response:** Fall back to direct file reads/writes, update status.json manually
**Escalate if:** Complete isolation >2 hours → try agent-bridge wake to Rivet

---

*Autonomous, self-healing, always shipping. 🔨*