scoped-agent-loop

A two-agent Codex loop with a hard boundary.

This is the safe version of multi-agent orchestration:

1. a planner proposes steps
2. a policy file checks every step
3. an executor runs only allowlisted work
4. every action writes a receipt
5. the loop continues from receipts, not vibes

No hidden routing. No renamed agents. No silent sensitive work. If a step is not allowed, the loop stops and asks you.

Setup (3 mins)

1. clone this repo
2. give workflow.png to your agent
3. copy loop.md, planner.md, executor.md, and policy.yaml into the conversation
4. create task.md with the job you want done, then say:

run this as a /loop automation

The loop

task.md
  -> planner proposes one step
  -> policy checks the step
  -> if allowed: executor runs it
  -> receipt goes into receipts/
  -> log.md updates
  -> planner re-plans from receipts
  -> stop when done or blocked

Files

• loop.md - the loop driver
• planner.md - planner role (no execution)
• executor.md - executor role (allowlist only)
• policy.yaml - hard rules
• receipt.schema.json - receipt shape
• task.md.example - starter task
• examples/allowed-step.json - example allowed step
• examples/blocked-step.json - example blocked step
• workflow.png - give this to your agent
• workflow.excalidraw - source diagram

Rules that never move

• Planner never executes.
• Executor never invents steps.
• Policy is fail-closed.
• Publish, delete, spend, credentials, prod, messages, and external posts need human approval.
• Every action must leave a receipt.
• If anything is unclear, stop and ask.

How to run it inside Codex

1. Open a Codex thread in the repo.
2. Attach workflow.png.
3. Paste loop.md as the system driver.
4. Keep planner.md, executor.md, and policy.yaml in context.
5. Write your goal into task.md.
6. Say: run this as a /loop automation.

The agent should:

1. read task.md
2. write a proposed step
3. check it against policy.yaml
4. either run it or stop for approval
5. append a receipt
6. update log.md
7. continue until done

Customize the policy

Edit policy.yaml first. That is the product.

• add only the paths you want touched
• add only the commands you want allowed
• put irreversible actions under human approval
• keep the forbidden list boring and strict

If the loop feels slow, your policy is doing its job.