The Coding-Agent Toolkit: A Workflow Loop You Can Install
Seven host-neutral steps to improve agent productivity, now public, that run the same on Claude Code and OpenAI Codex.
The previous issue was a reading list on coding agents. It separated three loops that run around one:
the agent loop that writes or edits code,
the harness loop that decides whether the work is acceptable, and
the workflow loop that decides what work should exist, who reviews it, and what state survives into the next run.
The argument was that the workflow loop is where the engineer stays. The issue closed on a design rule — decide what the agent may change, define how the harness checks it, preserve the evidence needed for review, and keep the research claim outside the automation boundary — and then stopped, because a reading list describes a loop without handing you one.
The three loops from the last issue. The agent loop writes code; the harness loop checks whether the work is acceptable; the workflow loop decides whether the work should exist, who reviews it, and how state persists. This release is one implementation of that outer loop.
coding-agent-toolkit is now public: seven host-neutral steps that take a piece of work from a rough idea to a merged pull request, on both Claude Code and OpenAI Codex. It is the specific workflow loop I run daily, released now because the shape has stopped moving. The agent does the work; the toolkit keeps the state.
A concrete case for what “keeps the state” buys you. An agent starts a data-loader fix, patches the imports, and gets three tests green before it runs out of context. The next morning, a fresh session — maybe on the other host — picks up the branch. With nothing durable on disk, it re-reads the repo, guesses at what was in flight, and quietly widens a loader fix into a refactor of the ingestion layer. With a spec, a plan, an open issue, and a handoff snapshot to read first, it resumes the same scoped task: finish the loader fix, keep the diff reviewable, and stop. The workflow loop is what makes the second outcome the default.
What The Seven Steps Do
Five steps carry a piece of work forward — align, plan, plan-issues, next-issue, ship — and two, handoff and continue, carry state across the gaps between sessions. Each writes one file the next step reads, so state lives on disk rather than in a conversation, and each exists to head off a specific way delegated work goes wrong.
The five delivery steps, the file or GitHub object each writes, and the two transition steps that carry state across boundaries. The file on disk is the contract that the next step reads.
align→spec.md. Interrogates a rough request into a verifiable end-state, one question at a time, before any code is written — so the agent is not optimizing toward an implicit, private definition of done.plan→plan.md. Breaks the spec into issue-sized chunks with dependencies, so one request does not arrive as a single sprawling change that no one can review.plan-issues→ a GitHub milestone and one issue per chunk. Dry-run by default;--applywrites. The work becomes reviewable units under version control, not lines in a chat transcript.next-issue→ a branch, an implementation, tests, and a PR. Takes the lowest-numbered open issue in the active milestone, so the agent works the next scoped unit instead of whatever is convenient.ship→ a squash-merge and a closed milestone. Runs only after verifying that every issue has a commit with a closing footer, so nothing merges while leaving the work graph half-open.handoff/continue→ a durable session transition.handoffwrites a snapshot;continuereplays it and flags drift — so the next session does not trust stale prose, and drift does not stay invisible until it corrupts the next task.
Six of the seven ship as a Claude skill and a mirrored Codex prompt. plan is the exception: it delegates to each host’s native plan mode and a capture hook, because re-implementing plan mode as a shell command would discard the structured output the host already produces.
Closes #N in a PR body is the signal that bubbles state up: a merged PR closes its issue, and ship closes the milestone once every issue is closed by a commit footer. GitHub is the projection; the file each step writes to disk is the contract the next step — or the next agent — reads, rather than re-deriving where things stand.
The same steps apply to non-code work when the deliverable consists of reviewable files. Closes #N closes an issue about a chapter draft or a research report as cleanly as one about a bug fix.
How It Answers The Design Rule
The last issue’s rule had four clauses. The toolkit maps onto three directly; the harness clause it leaves to your existing tests and review.
Decide what the agent may change.
alignproduces a spec with acceptance criteria before the agent touches a file. The scope is written down and reviewable in advance, so “the agent wrote something” and “the agent did the agreed work” become separate, checkable claims.Preserve the evidence needed for review. The chain produces a milestone, issues, branches, and a merged PR — a trail a human reads, rather than an agent transcript to reconstruct afterward. The diff arrives scoped to one issue, tied to a stated spec, with a closing footer.
Keep the research claim outside the automation boundary. The last issue’s sharpest example was a data-loader test made to pass by dropping the tickers that had stopped returning history: the suite goes green, and the backtest quietly runs on survivors only. The code is correct; the research claim has changed. A host-neutral workflow layer does not prevent that edit by itself — domain checks do that: a frozen universe, a survivorship guard, an invariant test.
What the workflow changes is visibility. The edit arrives as a scoped PR against a spec that stated what the loader was for, so a reviewer sees a change to the ticker universe instead of a green checkmark, and the domain checks have somewhere to run. The same reading list noted that many agent failures are workflow failures — abandoned reviews, duplicate work, task mismatches — rather than syntax errors, and that this is the layer this works on.
The toolkit does not make the model write better code, nor does it replace tests, domain invariants, data checks, cost models, or review. It makes the agent work legible enough that those checks — and a human — can still own the result.
Cross-Host State
The same workflow runs on Claude Code and OpenAI Codex because there is no orchestrator between them. The cross-host primitive is a shared durable state under .workspace/, read natively by both.
Swapping hosts mid-feature works because the next session — whichever host it runs on — picks up where the last one left off by reading what the last one wrote. There is deliberately no “execute as the other host” command; the file is the swap.
Session continuity has one refinement worth calling out. A prose handoff goes stale silently: the next session cannot tell whether what it describes is still true. handoff pairs the summary with a fenced block of read-only commands, each carrying an inline # expect: <value>. continue runs each command, compares the output to the expected value, and flags every divergence. Drift is information: a repo one commit ahead is fine; a milestone that has since closed may matter. continue surfaces suggested next steps and does not act on them.
This release supersedes claude-code-toolkit, the broader, Claude-only predecessor — a wide collection of patterns and plugins. This one is narrower: seven steps, two hosts, one job. It is a sibling, not a competitor, to code review: if you run roborev, open reviews on the current branch surface when a session starts, and stay silent when it is not installed. One reviews code, one drives work, and they compose.
Installing It
Claude Code. Copy or symlink skills/ into your project’s .claude/skills/, or install the workflow plugin from the coding-agent-plugins marketplace, which mirrors the same steps. The marketplace is Claude-side; the toolkit itself is cross-host.
OpenAI Codex. Point your prompts directory at codex/prompts/, or copy the files in.
Then invoke the steps in order on a new piece of work, and handoff / continue at the boundaries of anything long-running. The SKILL.md in each step directory is that step’s authoritative documentation; there is no separate runtime to install.
The toolkit is pre-1.0 and MIT-licensed. The step contracts are stable enough for daily use, but their shape may still shift in response to friction encountered in real work. Issues and PRs are welcome. Repository: github.com/stefan-jansen/coding-agent-toolkit.
Where This Sits In The ML4T Work
The near-term value of coding agents for ML4T readers is the bounded, checkable work: environment repair, notebook maintenance, data-loader fixes, test scaffolding, CI triage, reproducible experiment plumbing. The workflow loop is what keeps that work reviewable as you delegate more of it, and what draws the line the last issue insisted on — between the changes you hand to the loop and the ones that decide whether a result is real.
Today I am teaching a free Maven Lightning Lesson, Getting stuff done with coding agents (4:00 PM UTC), which walks through this chain end-to-end: turning an ambiguous goal into a scoped work unit, keeping state across sessions, and using review gates so a human still owns the result.
For the hands-on version, I am running a workshop, Loop Engineering: Reliable Work From Coding Agents, on July 18 (10 am–2 pm EDT). It builds what this issue describes, on your own keyboard: turn a vague goal into a verifiable spec, project the plan onto GitHub issues, and write a handoff that survives the session boundary. It also puts you in front of the green-but-wrong failure — the suite passes while the result is corrupted — and has you write a verification skill the agent cannot satisfy by quietly dropping the tickers that stopped reporting.
The same division of labor — what you hand to the loop, what stays with you because it decides whether the result is real — runs through the Machine Learning for Trading: From Research to Production cohort across nine case studies; the current summer cohort is full, with a waitlist for the next.