multi-step-improvement-loop

name

multi-step-improvement-loop

description

Orchestrate a problem that needs multiple pull requests by decomposing work into a dependency graph, creating Codex worker and reviewer threads in isolated worktrees, routing each thread to the right skills, looping workers on review comments and CI failures, and merging approved PRs into a feature branch. Use when the user asks to schedule, coordinate, automate, or run a multi-PR improvement, refactor, fix, or feature across Codex threads.

Multi-Step Improvement Loop

Use this skill from the orchestrator thread. The orchestrator owns the initiative plan, thread creation, dependency ordering, merge decisions, and loop state. Worker threads own implementation PRs. Reviewer threads inspect PRs and leave findings. The user owns the final merge from the feature branch to main.

Operating Model

• Treat the input as an initiative: a problem that needs one or more PRs and may have dependencies.
• Default to a feature branch integration model:
  • user final target: main
  • orchestrator integration branch: feature/<initiative-slug>
  • worker branches: codex/<initiative-slug>-NN-<short-name>
  • worker PR base: the feature branch, unless stacked work is explicitly justified
• Prefer sequential PRs into the feature branch. Use parallel PRs only when they do not touch the same modules, data contracts, migrations, generated artifacts, or tests in conflicting ways.
• Use stacked PRs only when PR B cannot be reviewed or tested without PR A. Record the stack and retarget/rebase plan.
• Keep workers scoped to implementation. Do not let worker threads merge their own PRs.
• Keep reviewers read-only. Do not let reviewer threads implement fixes.
• Let the orchestrator merge only after gates pass and the user has preauthorized feature-branch merges for this initiative.

Thread Coordination Contract

Threads know their place because the orchestrator assigns it. Do not rely on a worker or reviewer thread to discover queue position, dependency state, or what feedback matters.

Do not give every thread the full initiative plan by default. The orchestrator owns the full PR graph. Worker and reviewer threads receive a local work packet: what this node is, what immediate predecessor output it can trust, what events it should listen for, what it should ignore, and what signal it must emit when done.

Every thread prompt must include:

• Identity: initiative, PR node id, role, branch, base, and relationship (parallel, sequential, or stacked).
• Local neighborhood: immediate predecessor nodes, immediate successor or handoff targets, and whether the thread is currently active or blocked.
• Allowed input: the exact research brief, PR URL, review comments, CI logs, or upstream PRs the thread should respond to.
• Forbidden input: unrelated PRs, old comments already resolved, future PR nodes, and anything outside the node scope.
• Output contract: what the thread must return so the orchestrator can update state.

The orchestrator is the router:

• Worker threads respond only to their initial task prompt and later orchestrator follow-ups for that same PR branch.
• Reviewer threads respond only to the PR URL, stated scope, and acceptance criteria they were given.
• Comment-fix prompts include only unresolved blocking review comments and current CI failures.
• Dependent PR threads are not created until prerequisites are merged, unless the graph explicitly marks them as stacked.
• If a worker discovers work that belongs elsewhere, it reports a proposed new PR node instead of implementing it.
• Threads may request a local next action, but only the orchestrator schedules new threads, changes graph state, or merges PRs.

Skill Routing

Select skills by phase and PR type. Do not load every skill into every thread.

Phase	Default Skill Contract
Research	Use $research-codebase to document where behavior lives and how modules interact.
Architecture planning	Use $improve-codebase-architecture when module depth, interface shape, seams, adapters, locality, or leverage matter.
Implementation	Use only task-relevant skills plus local repo instructions. Use $github:yeet only when publishing local changes to GitHub.
Review	Use review stance. Add $improve-codebase-architecture when architectural quality is in scope.
Comment fixing	Use $github:gh-address-comments for actionable PR feedback and $github:gh-fix-ci for failing GitHub Actions.
Domain-specific testing	Use repo skills such as $setup-test-listing, $ios-local-build, or $ios-release only when the PR touches those domains.

If a named skill is not installed, state that and continue with the nearest local workflow.

Workflow

1. Define the initiative.

   • Name the initiative and choose a slug.
   • Capture the user goal, constraints, non-goals, and final target branch.
   • Decide whether the orchestrator is authorized to merge approved PRs into the feature branch.

2. Research before planning implementation.

   • If the code path is not already clear, run $research-codebase.
   • If the work is architectural, run $improve-codebase-architecture after research.
   • Preserve facts separately from recommendations.

3. Build the PR graph.

   • Create PR nodes with id, title, branch, base, depends_on, skills, status, and acceptance.
   • Mark nodes as parallel, sequential, or stacked.
   • Split PRs until each worker can produce a focused reviewable diff.
   • Keep a ready set: nodes whose dependencies are merged.
   • Record active_thread, waiting_on, allowed_inputs, and next_action for every node.

4. Prepare Git state.

   • Ensure the feature branch exists from the intended target.
   • Push the feature branch before starting worker PRs when remote PR bases are needed.
   • Use worktrees for workers and reviewers so local checkouts stay clean.

5. Start ready workers.

   • Use thread tools when available. If they are not in context, use tool discovery for create_thread, read_thread, and send_message_to_thread.
   • Call list_projects before create_thread for repo-scoped work.
   • Create each worker in a new worktree starting from the feature branch or from the parent branch for a deliberate stack.
   • Require the worker to run a git publish preflight before research or edits. Do not assume a worktree can publish just because it can edit files; some worktrees have a .git pointer to metadata outside the thread's writable sandbox.
   • The preflight must verify both index writes and remote read access:

     git status --short
     git rev-parse --git-dir
     tmp=".codex-git-preflight-$$"
     printf "preflight\n" > "$tmp"
     git add -N "$tmp"
     git reset -- "$tmp"
     rm "$tmp"
     git ls-remote --heads origin <base_branch>
     

   • If the preflight fails, the worker must stop before implementing and return the exact failing command, cwd, git rev-parse --git-dir, and stderr. The orchestrator must recreate the worker in a publish-capable worktree or explicitly own publishing for that node before implementation continues.
   • Use the worker prompt template from references/prompt-templates.md.
   • Cap parallel workers when conflict risk is non-trivial. Default cap: 2.

6. Review each PR.

   • Once a worker returns a PR URL, create a reviewer thread.
   • Reviewer thread may use a worktree when it needs local tests, or GitHub diff/context when review is enough.
   • Use the reviewer prompt template from references/prompt-templates.md.
   • Collect review status, unresolved comments, and CI status.

7. Loop on comments and CI.

   • While review is not approved or CI is not green, send the worker a focused fix prompt.
   • Include unresolved comments, failing check names, relevant logs, and the rule that it must push to the same PR branch.
   • Re-review after material changes.
   • If the same blocker repeats three times, mark the PR blocked and ask the user instead of forcing progress.

8. Merge into the feature branch.

   • Merge only when all gates pass:
     • PR targets the feature branch or intended stack parent.
     • CI is green or an explicit user-approved exception exists.
     • Required reviews are approved.
     • No unresolved blocking comments remain.
     • Worker branch contains only the scoped PR work.
   • After merge, update the graph, unlock dependent nodes, and start the next ready set.

9. Close the loop.

   • When all nodes are merged into the feature branch, summarize:
     • merged PRs
     • remaining risks
     • tests and validation coverage
     • what the user should inspect before merging the feature branch to main
   • Archive or title worker/reviewer threads if the user wants cleanup.

Loop State

Keep loop state visible. For short runs, in-thread state is enough. For long-running runs, create a state artifact such as .codex/loops/<initiative-slug>.md or docs/workplans/<initiative-slug>.md if the user wants it in the repo.

Use the schema and examples in references/state-schema.md.

Heartbeat Automation

Use heartbeat automation only after the user asks for scheduled continuation or unattended polling.

• Prefer a heartbeat attached to the orchestrator thread.
• Do not create a cron workaround for an orchestrator thread heartbeat.
• The heartbeat prompt must be self-sufficient: read loop state, inspect active threads, check PRs, send next worker/reviewer prompts, merge gated PRs only if authorized, then report state.
• Keep the interval conservative at first, such as 30 minutes.

See references/prompt-templates.md for a heartbeat prompt.

Failure Handling

• If a worker broadens scope, send it back to narrow the diff or split a new PR node.
• If parallel PRs conflict, pause the lower-priority PR until the first merge lands, then rebase or recreate the worker from the feature branch.
• If CI appears flaky, rerun once. If it fails again, treat it as a real failure.
• If review feedback reveals that the PR graph is wrong, update the graph rather than forcing the original plan.
• If the feature branch becomes unstable, stop starting new workers and create a stabilization PR.