187 lines
3.8 KiB
Markdown
187 lines
3.8 KiB
Markdown
# Recipe Manager Agentic Runbook
|
||
|
||
Last updated: 2026-03-24
|
||
|
||
## Purpose
|
||
Operational guide for running the Recipe Manager agent harness reliably.
|
||
|
||
---
|
||
|
||
## Core Execution Model
|
||
|
||
- One task per iteration
|
||
- One commit per iteration
|
||
- TODO.md is the authoritative queue
|
||
- Work only in:
|
||
`/home/paulh/.openclaw/workspace/projects/recipe-manager`
|
||
|
||
---
|
||
|
||
## Required Guards (Must Pass Before Coding)
|
||
|
||
### Pre-flight checks
|
||
Before any iteration starts, verify these files exist:
|
||
- `AGENT_INSTRUCTIONS.md`
|
||
- `TODO.md`
|
||
|
||
If missing, fail with:
|
||
`STUCK: bad working dir or missing harness files at /home/paulh/.openclaw/workspace/projects/recipe-manager`
|
||
|
||
---
|
||
|
||
## Monitoring Signals (How we know it's working)
|
||
|
||
A run is healthy only when all 3 are true:
|
||
1. Active session updated recently (`recipe-v1-iter*`)
|
||
2. New git commits are landing
|
||
3. TODO checkboxes advance
|
||
|
||
---
|
||
|
||
## Known Failure Modes and Fixes
|
||
|
||
## 1) Wrong working directory
|
||
### Symptom
|
||
Agent says AGENT_INSTRUCTIONS.md / TODO.md missing in `/workspace`.
|
||
|
||
### Root cause
|
||
Spawner started outside project root.
|
||
|
||
### Fix
|
||
- Force absolute project path in every task prompt
|
||
- Add mandatory pre-flight guard
|
||
- Relaunch fresh iteration
|
||
|
||
---
|
||
|
||
## 2) False “iteration already running”
|
||
### Symptom
|
||
Auto-iterator repeatedly prints SKIP even when no coding progress occurs.
|
||
|
||
### Root cause
|
||
It treated stale historical sessions as active.
|
||
|
||
### Fix
|
||
- Treat a session as active only if updated recently (freshness window)
|
||
- Use current phase labels only (`recipe-v1-iter*`)
|
||
|
||
---
|
||
|
||
## 3) Label mismatch across phases
|
||
### Symptom
|
||
Monitor reports wrong status or misses active runs.
|
||
|
||
### Root cause
|
||
MVP labels (`recipe-mvp-*`) used during v1 phase.
|
||
|
||
### Fix
|
||
- Update monitor + iterator to phase-specific labels
|
||
- Standardize naming per phase:
|
||
- MVP: `recipe-mvp-iter*`
|
||
- v1: `recipe-v1-iter*`
|
||
|
||
---
|
||
|
||
## 4) Model/provider auth mismatch
|
||
### Symptom
|
||
Cron jobs fail with:
|
||
- `No API key found for provider openai`
|
||
- or Copilot cooldown rate-limit errors
|
||
|
||
### Root cause
|
||
Using `openai/...` models without OpenAI API key.
|
||
|
||
### Fix
|
||
- Use OAuth provider model prefix: `openai-codex/...`
|
||
- For this project, prefer:
|
||
`openai-codex/gpt-5.3-codex`
|
||
|
||
---
|
||
|
||
## 5) Environment capability mismatch (Docker)
|
||
### Symptom
|
||
Task fails with `docker: command not found`.
|
||
|
||
### Root cause
|
||
Agent runtime host lacks Docker.
|
||
|
||
### Fix
|
||
- Mark as manual host validation task
|
||
- Continue with unblocked tasks
|
||
|
||
---
|
||
|
||
## 6) Runtime module mismatch (ESM/CommonJS)
|
||
### Symptom
|
||
Backend runtime error: `require is not defined`.
|
||
|
||
### Root cause
|
||
Using `require()` in ESM code path.
|
||
|
||
### Fix
|
||
- Replace `require('fs')` calls with ESM imports (`writeFileSync`)
|
||
- Build + rerun server
|
||
|
||
---
|
||
|
||
## Operational Controls
|
||
|
||
## Pause automation
|
||
Disable both jobs:
|
||
- Recipe Manager Auto-Iterator
|
||
- Recipe Manager Progress Monitor
|
||
|
||
## Resume automation
|
||
Enable both jobs, then manually kick one fresh iteration.
|
||
|
||
## Manual override iteration (safe restart)
|
||
Spawn one explicit iteration with:
|
||
- absolute project path
|
||
- pre-flight guard
|
||
- one-task/one-commit rule
|
||
|
||
---
|
||
|
||
## Completion Definition
|
||
|
||
A phase is complete when:
|
||
1. No unchecked tasks remain in that phase section of TODO.md
|
||
2. Latest iteration exits without STUCK/ERROR
|
||
3. Commit + TODO update are present
|
||
|
||
---
|
||
|
||
## Recommended Cadence
|
||
|
||
- Auto-iterator: every 15 minutes
|
||
- Progress monitor: every 5 minutes (high visibility mode)
|
||
|
||
If noisy, set monitor to every 10–15 minutes.
|
||
|
||
---
|
||
|
||
## Handoff Checklist (Before ending a session)
|
||
|
||
- [ ] Confirm latest commit hash
|
||
- [ ] Confirm active phase + next unchecked task
|
||
- [ ] Confirm auto-iterator enabled/disabled status
|
||
- [ ] Confirm monitor enabled/disabled status
|
||
- [ ] Confirm no stale active-session false positives
|
||
|
||
---
|
||
|
||
## Quick Status Commands
|
||
|
||
### Latest commit
|
||
`git log -1 --oneline`
|
||
|
||
### Next tasks
|
||
`grep -n "^- \[ \]" TODO.md | head`
|
||
|
||
### Recent progress
|
||
`git log --oneline -5`
|
||
|
||
---
|
||
|
||
This runbook should be updated whenever a new failure mode appears.
|