paulh
/
recipe-manager
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
recipe-manager/RUNBOOK.md

3.8 KiB
Raw Blame History

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.