Big Loop Runbook

doit.md

Feature Development Cycle Runbook

This is a real, working execution runbook for a tool I'm currently working on called "forkflow". I point it at an orchestrator agent (GPT 5.5 xhigh running in Codex app) and it develops a feature autonomously end to end — design through commit — fully reviewed and validated, with a dev agent (GPT 5.5 medium running in OMP) doing the implementation under dual monitoring.

Forkflow, pi-bridge, and AgentBrain (mentioned in this runbook) are all unreleased but coming (follow me!). This runbook is shared as a real-world reference for what I consider what a fully agent-driven development "loop" looks like in practice.

This is the normal Forkflow feature or issue development cycle: backlog item, design goal, Forkflow self-forked design work, implementation goal, dev agent (ff-dev) handoff to OMP, supervision, review, validation, AgentBrain handling, and closeout.

Forkflow is the product. pi-bridge is operator tooling used to communicate between Codex running in Codex app with the standing ff-dev Pi/OMP development agent doing the work. These are all components I am developing and use on the daily to cook with AI and push out gold standard slopware (:

Repository Structure

The system uses a structured set of repo-local files for tracking work:

• <repo-root>/AGENTS.md — project-level agent instructions
• <repo-root>/.agentbrain.yml — AgentBrain configuration
• <repo-root>/.ai/issues/backlog/ — backlog items awaiting development
• <repo-root>/.ai/designs/open/ — in-progress design docs
• <repo-root>/.ai/designs/implemented/ — completed design docs
• <repo-root>/.ai/docs/goals/ — rendered goal files

Operating Rules

• Keep AgentBrain-managed files out of parent Git.
• Parent Git should own source, tests, durable docs, build config, scripts, and README-level project files.
• AgentBrain should own local goals, open designs, backlog notes, scratch artifacts, and one-off run outputs unless explicitly admitted into parent Git.
• For goals with an effort floor, the floor is a working floor. Never satisfy it with sleep, idle waiting, or timer padding.
• Do not use /clear inside a Forkflow-created Codex fork. It destroys inherited context and invalidates the self-fork proof.
• Re-enable advisor in the external OMP dev-agent session if that session is reloaded, restarted, or extensions are reloaded.

Standard Cycle

1. Preflight

Run from the repo root:

cd <repo-root>
git status --short --untracked-files=all
agentbrain sweep --json
printenv CODEX_THREAD_ID
which codex
codex --version

Expected state:

• Git is clean or only contains work the current cycle intentionally owns.
• AgentBrain reports no action required or clearly classifies the files.
• CODEX_THREAD_ID is set when using Forkflow to self-fork the current Codex thread.
• codex resolves to the Codex.app bundled CLI, not a public CLI version known to fail during fork startup.

2. Pick The Backlog Item

Identify the specific backlog item being advanced.

Example:

.ai/issues/backlog/issue-parent-session-resolution-and-ergonomic-launch.md

Read any linked design briefs, smoke docs, or implementation notes named by that backlog item before rendering goals.

3. Render A Code-Design Goal

Use the local pi-goals templates under:

.ai/.pi-goals/

For a feature slice that needs design before implementation, use:

iterative-code-design

Render the goal with <repo-root> as the project root. Save the rendered goal under:

.ai/docs/goals/

Example output path:

.ai/docs/goals/design-parent-session-resolution-and-ergonomic-launch.goal.md

4. Launch The Design Goal Through Forkflow

Forkflow self-forks the current Codex thread, runs the goal in the fork, and writes the design doc to the output path.

forkflow run \
  --goal .ai/docs/goals/design-parent-session-resolution-and-ergonomic-launch.goal.md \
  --output .ai/designs/open/design-parent-session-resolution-and-ergonomic-launch.md \
  --timeout 45m

Forkflow prints a run-id. Use it to supervise and resume.

If the parent process times out but the fork later writes a valid result, adopt it:

forkflow resume <run-id>

5. Supervise The Forked Design Worker

Once the tmux session exists, attach read-only:

tmux attach -r -t "forkflow-<run-id>"

Poll every 30-60 seconds:

tmux capture-pane -J -pt "forkflow-<run-id>" -S -160 || true
fork_path="<repo-root>/.forks/forkflow/<run-id>"
git -C "$fork_path" status --short --untracked-files=all || true
test -s "$fork_path/.forkflow/result.json" && jq . "$fork_path/.forkflow/result.json"

Watch for:

• the worker reads AGENTS.md;
• the worker reads the rendered goal;
• the worker reads linked backlog/design/smoke docs;
• the worker creates only the expected artifact;
• the worker writes a valid .forkflow/result.json;
• the worker does real design work instead of waiting to satisfy an effort floor.

6. Copy Back And Review The Design

Copy only accepted artifacts from the fork into the parent repo.

cp "$fork_path/.ai/designs/open/design-parent-session-resolution-and-ergonomic-launch.md" \
  .ai/designs/open/design-parent-session-resolution-and-ergonomic-launch.md

Review the design from the parent side:

sed -n '1,260p' .ai/designs/open/design-parent-session-resolution-and-ergonomic-launch.md
rg -n "TODO|TBD|FIXME|placeholder|sleep" .ai/designs/open/design-parent-session-resolution-and-ergonomic-launch.md || true

Apply small corrections directly when needed. The design must be implementable, bounded, and grounded in existing code and docs.

Link the design:

agentbrain link .ai/designs/open/design-parent-session-resolution-and-ergonomic-launch.md
agentbrain sweep --json

7. Render The Implementation Goal

Use:

design-goal-from-doc

Input:

.ai/designs/open/design-parent-session-resolution-and-ergonomic-launch.md

Output:

.ai/docs/goals/implement-parent-session-resolution-and-ergonomic-launch.goal.md

Review the rendered goal before handoff. It should state:

• exact files or packages likely involved;
• expected CLI behavior;
• deterministic tests;
• live smoke expectations;
• AgentBrain handling;
• result and closeout requirements.

8. Hand Off To ff-dev

Use pi-bridge as orchestration tooling only.

Preflight:

pi-bridge peek --bridge ff-dev
pi-bridge wait-live --bridge ff-dev --timeout-ms 30000

Send the goal with the slash-command route:

pi-bridge command --bridge ff-dev --name goal --file .ai/docs/goals/implement-parent-session-resolution-and-ergonomic-launch.goal.md

If the command opens an interactive confirmation prompt and the selected action is correct:

pi-bridge key --bridge ff-dev --key enter

9. Monitor ff-dev

Use sparse polling:

pi-bridge peek --bridge ff-dev
pi-bridge tail --bridge ff-dev --since <cursor> --limit 20 --chars 240
pi-bridge wait --bridge ff-dev --query "completed|blocked|failed|need|question|HARD STOP" --regex --since <cursor> --timeout-ms 60000
pi-bridge latest --bridge ff-dev --role assistant

Confirm:

• ff-dev accepted the goal as a goal;
• it is working in <repo-root>;
• it reports files changed, tests run, smoke status, and AgentBrain state;
• it does not commit AgentBrain-managed artifacts as parent Git files.

Use Herdr only if the underlying Pi/OMP terminal has to be recovered, restarted, or operated directly.

10. Review Landed Work

After ff-dev reports completion, inspect the parent repo:

git status --short --untracked-files=all
git diff
agentbrain sweep --json

Run the relevant validation:

go test ./...
go build ./...

For a CLI or harness slice, also run focused smoke checks that prove the actual product behavior. Deterministic tests are necessary, but they do not prove live harness behavior by themselves.

11. Commit Parent-Owned Work

Stage only parent-owned source, tests, durable docs, config, and scripts.

git diff --cached --name-only
agentbrain sweep --json
git commit

Use a conventional commit message that explains the feature slice and proof.

12. Close The Design Slice

After the work lands:

1. Move implemented design docs from .ai/designs/open/ to .ai/designs/implemented/.

2. Run:

   agentbrain sweep --json
   agentbrain sweep --apply --json
   agentbrain sweep --json

3. If moved AgentBrain symlinks remain as untracked orphan symlinks after capture, verify they are no longer active links:

   agentbrain link status <path> --json

   Then remove only those orphan worktree symlinks.

4. Confirm:

   git status --short --untracked-files=all
   agentbrain sweep --json

---

Non-Standard Paths And Recovery

No CODEX_THREAD_ID

Symptom:

CODEX_THREAD_ID is empty

Impact: current-thread self-fork may not be possible from this shell.

Recovery:

• run from a Codex parent session where CODEX_THREAD_ID is set;
• or use explicit parent-session options once Forkflow supports them.

Invalid Forkflow Result JSON

Symptom:

result_invalid_json
json: cannot unmarshal array into Go struct field Envelope.summary of type string

Recovery: correct only .forkflow/result.json inside the same fork:

Forkflow rejected .forkflow/result.json because summary must be a string, not an array. Rewrite only .forkflow/result.json as valid JSON with fields: status string "completed", text string, summary string, checks array of strings. Do not change design docs or source files.

Then:

forkflow resume <run-id>

Bridge Offline Or Stale

Start with:

pi-bridge list
pi-bridge status --bridge ff-dev
pi-bridge wait-live --bridge ff-dev --timeout-ms 30000

Use Herdr only to recover or restart the actual Pi/OMP terminal. After OMP reload/restart, send:

/advisor on
/bridge start ff-dev

Parent Process Fails After Fork Work Succeeds

If the fork wrote a valid result:

forkflow resume <run-id>

This preserves the completed fork work and validates resume/adoption.

---

Closeout Checklist

• Backlog item exists and has framing context.
• Design goal was rendered from a template.
• Design work ran in a Forkflow self-fork when appropriate.
• Fork tmux session existed and was supervised.
• Result JSON was valid or adopted through resume.
• Design doc was reviewed and linked.
• Implementation goal was rendered from the design.
• ff-dev received the goal through pi-bridge command, not normal chat.
• ff-dev was monitored with bounded reads.
• Source/docs/tests were reviewed after implementation.
• Deterministic tests passed.
• Live smoke was run when the slice depends on live harness behavior.
• AgentBrain reports no action required.
• Parent Git is clean or has only intentional staged commit-ready changes.
• Implemented design docs were moved to implemented and captured after landing.