# AGENTS.md - Codex Ralph Vault Loop ## Mission codex-ralph-vault-loop is a Codex App/CLI native orchestration overlay for multi-agent engineering work. It keeps Codex main as the decision maker, uses external models only through MCP tools, verifies work through gates, and stores durable memory in the vault layer. ## Core Rules - Codex main decides. The primary Codex session owns final decisions, edits, synthesis, safety, and verification. - External models advise. Z.ai, MiniMax, and other non-OpenAI systems provide analysis or worker output only through MCP tools. - Gates verify. Tests, lint, security checks, scorecards, and migration checkpoints decide whether a phase can pass. - Vault remembers. Durable memory belongs in the approved Ralph/Codex memory paths, not in ad hoc repo files. - Do not bypass critical hooks. If prettier , gitleaks , semgrep , or pre-commit are missing from PATH , use the local machine binaries when present, install only with approval, or stop and report the blocker; do not use --no-verify to skip security or formatting gates unless the user explicitly orders that exact bypass. - Do not merge or close a PR until review feedback and automated Cap the run at 25 iterations; leave remaining work for the next session.
/goal /codex review reports zero real-or-regression findings on every step's diff (the verdict pasted in full each round); or stop after 3 rounds, reporting anything unresolved
/goal In Supabase prod project udooysjajglluvuxkijp, replace each authenticated write <table> ALL policy on public.customers/orders/order items/quotes/quote items/products (currently USING + WITH CHECK both literally true) with an org/tenant-scoped USING + WITH CHECK, or drop the policy if the table is unused in RA. End state: get advisors(project id=udooysjajglluvuxkijp, type:security) returns 0 rls policy always true findings for those 6 tables. Or stop after 6 turns if the owning tenant column cannot be confirmed
Director harness coordinates coder, reviewer, and gatekeeper agents to drive a work item through code, review, and merge—stopping on escalation or completion.
# combo-chen Agent Contract combo-chen is a deterministic director harness for autonomous work-item-to-PR work. It coordinates existing tools; it does not collapse their roles. ## Role Boundaries - Director : orchestrates only. Starts phases, watches hard signals, writes journal events, routes work, and escalates needs human . It does not edit code, answer review threads, approve PRs, push, merge, or deploy. - Coder : implements the work item and later resumes the same thread for review comments. The coder leaves local commits in the combo worktree and does not push to origin or the PR branch in the normal path. - Reviewer : reviews by comment and records a machine-readable verdict block with routing codes (0=OK/LGTM, 1=mechanical fix→coder, 2=ambiguous→director, 3=needs human) alongside the current SHA-pinned LGTM signal. It does not use GitHub approval as the merge contract, does not review its own code, and does not publish. - Gatekeeper : no-mistakes is the normal publisher. It validates, pushes, and opens/updates the PR. - Human : owns merge decisions and intent-touching escalations. Hard rule: reviewer != coder . ## Implemented Loop 1 Cap the run at 25 iterations; leave remaining work for the next session.
A cron-fired skill that finds its own work (failed CI, new issues, recent commits), fans each finding out to an isolated worktree, gates every fix behind an adversarial reviewer that assumes the code is broken, and leaves draft PRs — merging stays human.
# .claude/skills/morning-triage/SKILL.md — fired by cron at 06:00
READ (discovery inputs): CI runs that failed since the last run (gh run list --status failure); issues opened in the last 24h; commits merged since yesterday; the previous ./state/triage.md.
JUDGE: for each candidate decide actionable NOW vs noise; blocks a release → P0; already tracked → skip. Keep only what is worth a worktree today — the loop picks, you don't hand it a list.
WRITE: append findings (finding | source | priority | status) to ./state/triage.md and commit it so tomorrow's run can read it.
HANDOFF: one git worktree per finding (git worktree add ../wt-<slug> -b fix/<slug>), MAX_PARALLEL=3 — capped by how many PRs a human can actually review, not by the machine.
VERIFY: a second subagent as adversarial reviewer — ROLE: adversarial code reviewer. ASSUME this code is BROKEN until proven otherwise; do not praise. CHECK in order: does it run (execute, don't read); run the tests and paste real output; edge cases the author skipped; does behavior match the ticket. VERDICT: PASS only if every check holds, otherwise REJECT with each reason listed. Maximum 3 attempts per finding, then log as blocked.
STOP (red lines): never merge, never delete, never push to main; anything uncertain goes to ./inbox/ for a human, NOT into a PR. Caps set before the first run: per-run timeout 45 minutes, daily budget $20. PRs open as drafts; merging stays human.
Email is the missing tool in your harness. ConnectMyEmail gives Claude Code and Codex a clean MCP into Gmail, Outlook, iCloud and IMAP — triage, drafts, follow-ups, on a loop.
A fill-in-the-brackets charter that turns any pile of small tasks into a self-checking loop: where the work is, how to check each item with evidence, a needs-me escalation list, a state file, and a per-run stop.
You are running as a loop, not answering one prompt. Here is your charter.
GOAL: [Describe the finished state in one or two sentences. Be specific about what DONE looks like, and make it measurable.]
WHERE THE WORK IS: [e.g. "Scan the /pages folder for files with old pricing" or "Read TODO.md and treat each unchecked box as a task."]
HOW TO WORK: Do one item at a time; finish it fully before starting the next. Match the patterns in existing files; do not invent new ones. If an item needs a decision only I can make (spending money, deleting things, emailing a person), stop on that item, add it to a "needs me" list, and move to the next one.
HOW TO CHECK YOURSELF: After each item, prove it is done before you mark it done — run the tests / re-read the file / open the link. Checking means evidence, not confidence. If the check fails, fix it and check again: maximum 3 attempts per item, then log it as blocked and move on.
HOW TO REMEMBER: Keep LOOP-STATE.md. After each item write the item name, status (done / blocked / needs me), what changed, and anything the next run should know. Read this file FIRST every run.
WHEN TO STOP: Stop when every item is done or logged as blocked, or when you have finished [N] items this run. Then report: what got done, what is blocked, what needs my call.
Start by reading LOOP-STATE.md if it exists, then find the work.
/loop 30m check whether my live site [URL] is back up by loading the homepage. The moment it returns a normal page, tell me and stop checking. Cap the run at 15 passes.
Write a one-page brief where every claim has three or more sources and every link is opened and confirmed to support the claim — the loop that catches hallucinated citations a single prompt never can.
/goal write a one-page brief on [TOPIC] where every claim has at least three sources and every link opens to a real page that supports the claim. Open each link to confirm it before you call it done. Replace any source that is dead or does not back up the claim. Done when every source check passes on every claim — maximum 30 iterations.
The four-settings loop template: a separate verifier model that never shares context with the writer, a hard stop rule, a state file re-read each cycle, and worktree isolation. Point it at a checkable backlog and let it run overnight.
GOAL: every test in [/tests/TARGET] passes, lint is clean, zero type errors.
EACH CYCLE:
1. run the suite, read every failure
2. pick the single highest-impact failure
3. write the smallest change that fixes it
4. re-run tests + lint + type check
VERIFY: a separate model instance checks the goal — never the writer. Verifier prompt: "You are a verifier. You did not write this code. GOAL: <the exact goal string>. Given the diff and the test output, answer ONLY: PASS — every condition in GOAL is objectively met, with evidence, or FAIL: <the specific condition not met, and the evidence>. Do not fix anything. If unsure, FAIL."
STOP WHEN: verify passes, OR after 10 iterations, OR $5 spent, OR no progress in 2 attempts.
ON BLOCKER: log it, skip to the next item, never halt the whole loop.
STATE: append done / failed / next to a state file, re-read it at the top of every cycle.
ISOLATION: one git worktree per subagent.
/loop cadence: continuous or per-batch. For real traffic [SOURCE], run the candidate prompt in shadow alongside the live prompt without exposing shadow output to users. Append disagreements (input, live output, shadow output, which was better by [CRITERIA]) to state-file shadow-prompt.md. Each round, summarize where they diverge and whether the candidate wins. Never serve shadow output to a user or change the live prompt automatically. Stop after the batch; log errors and stop. Budget: cap $[X]/run. Hard cap: stop after 1 iteration per run.
/loop cadence: weekly. Read every loop's state/ledger file [DIR]. Append recurring failure patterns (which loops, symptom, frequency) to state-file repeat-offenders.md. Each round, identify the SINGLE root problem appearing across the most workflows and draft a fix-once recommendation. Read + own-file writes only; change no other loop. Stop after one root problem; log errors and stop. Budget: cap $[X]/run. Hard cap: stop after 1 iteration per run.
/goal for decision [X], write the pre-mortem: assume it's 12 months later and this failed, then enumerate the specific causes, ranked by likelihood, each with an early-warning signal and a mitigation. Done when: state-file premortem.md contains the failure narrative + a ranked cause table with signals and mitigations, and the top 3 causes each have a concrete owner/mitigation PASTED in. Paste the completed table as proof, or paste what's unfinished and stop. Budget: cap $[X]. Hard cap: stop after 1 iteration per run.
/goal for each live option [LIST], state its ONE disqualifying condition upfront, then run an evidence hunt for that disqualifier. Done when: for every option, the state-file kill-criteria.md contains either PASTED evidence the disqualifier is true (kill it) or a documented search showing it isn't (keep it). No option stays undecided. Paste the evidence table as proof, or paste what's still missing and stop. Judge: a second smaller model checks each verdict cites evidence. Budget: cap $[X]. Hard cap: stop after 1 iteration per run.
/loop cadence: on-demand queue. For each incoming question in the queue, a cheap model attempts an answer and self-checks against [CRITERIA]. Append (question, cheap-model verdict, pass/fail) to state-file escalation-log.md. Escalate to Fable ONLY where the cheap model logged a failure; Fable answers just those. Read + own-file writes only. Stop when the queue is empty; log errors and stop. Budget: cheap-first, cap $[X]/run. Hard cap: stop after 1 iteration per run.
/loop cadence: weekly. Using the Firecrawl MCP, diff tracked regulatory/authoritative sources [LIST] against the last snapshot. Append only material changes to state-file source-digest.md. Each round, write a plain-language 'what changed / so what / who it affects' for each material change; ignore cosmetic edits. Read + own-file writes only. Stop after the digest; log errors and stop. Budget: cap $[X]/run. Hard cap: stop after 1 iteration per run.
Email is the missing tool in your harness. ConnectMyEmail gives Claude Code and Codex a clean MCP into Gmail, Outlook, iCloud and IMAP — triage, drafts, follow-ups, on a loop.
/loop cadence: nightly (synthesis monthly). Using Exa MCP + a Firecrawl monitor on tracked sources [LIST], have a cheap model log what materially changed to state-file intel-feed.md each night. Route to Fable only for the monthly synthesis: read the month's log and write ONE briefing of what changed and why it matters. Read + own-file writes only. Stop nightly after logging / monthly after the brief; log errors and stop. Budget: cheap-first, cap $[X]/run. Hard cap: stop after 1 iteration per run.
/loop cadence: daily or weekly. Using the Stripe API (read), maintain an aging ledger of unpaid/overdue invoices. Append (customer, invoice, days overdue, threshold hit) to state-file invoice-aging.md. When an invoice crosses a threshold [7/14/30d], draft the appropriate reminder in the right tone — DRAFT ONLY. Never send outbound, never touch charges or refunds. Stop after drafting due nudges; log errors and stop. Budget: cap $[X]/run. Hard cap: stop after 1 iteration per run.
/loop cadence: daily. Using the PostHog MCP and Stripe (read), check my key metrics [LIST] against their normal bands. Append daily readings to state-file kpi-watch.md. On a normal day, do nothing but log. When a metric breaks its band, pre-investigate (segment, correlate, likely cause) and draft an alert with the diagnosis. Never change data or send customer-facing messages. Stop after the check; log errors and stop. Budget: cap $[X]/run. Hard cap: stop after 1 iteration per run.
/loop cadence: on-demand or weekly. From my answer library [SOURCE] and the incoming RFP/proposal [DOC], draft the reusable ~80% (boilerplate, standard answers, past-response matches). Append (RFP, sections drafted, novel questions flagged) to state-file proposal-backlog.md. Each round, complete ONE proposal's reusable portion and list the new-20% questions a human must answer. Draft only; submit nothing. Stop after one; log and stop. Budget: cap $[X]/run. Hard cap: stop after 1 iteration per run.
/loop cadence: weekly. Using the Notion MCP (read), compare recent task/project records against the documented SOP pages [LINKS]. Append drift findings (step, written vs actual, evidence) to state-file sop-drift.md. Each round, draft ONE SOP update proposal for the biggest drift — propose only, edit no live SOP. Stop after one proposal; log errors and stop. Budget: cap $[X]/run. Hard cap: stop after 1 iteration per run.
/loop cadence: monthly. Using the QuickBooks API (read), categorize the period's transactions against historical patterns. Append matches + anomalies to state-file month-close.md. Each round, build/refresh the exception list (uncategorized, unusual, likely-miscoded) for a human to review. Never post, file, or reconcile anything in QuickBooks. Stop when the exception list is complete; log errors and stop. Budget: cap $[X]/run. Hard cap: stop after 1 iteration per run.
/loop cadence: daily. Using the Gmail MCP (read + draft), process each unread thread and classify it decide / delegate / defer / drop. Append (thread, classification, rationale) to state-file inbox-triage.md. For 'decide' and 'delegate' threads, save a draft reply — draft only, send nothing, archive nothing. Stop after the unread batch; log errors and stop. Budget: cap $[X]/run. Hard cap: stop after 1 iteration per run.
/loop cadence: weekly. Using the PostHog MCP (read), find the funnel step with the steepest drop-off. Append (step, drop rate, hypotheses) to state-file drop-points.md. Each round, draft rewritten copy/microcopy for the single worst drop screen — draft only, ship nothing to production. Stop after one screen; log analytics errors and stop. Budget: cap $[X]/run. Hard cap: stop after 1 iteration per run.
/loop cadence: weekly. Using the app store review APIs [STORES], pull new reviews + support exports. Append (issue, frequency, severity, star-impact) to state-file review-roadmap.md. Each round, re-rank the backlog by pain and draft a one-paragraph problem statement for the top unaddressed item. Write to the file only; change no roadmap tool live. Stop after one; log errors and stop. Budget: cap $[X]/run. Hard cap: stop after 1 iteration per run.
/loop cadence: weekly. Using the Reddit API, HN Algolia, and Exa, sweep mentions of [BRAND / PRODUCT]. Append (source, mention, sentiment, feature ask/complaint) to state-file mention-radar.md. Each round, cluster and surface the single loudest theme, then draft an implementation plan for it — plan only, build nothing. Stop after one plan; log source errors and stop. Budget: cap $[X]/run. Hard cap: stop after 1 iteration per run.
Email is the missing tool in your harness. ConnectMyEmail gives Claude Code and Codex a clean MCP into Gmail, Outlook, iCloud and IMAP — triage, drafts, follow-ups, on a loop.