update-agentic-workflow

A gated, two-model workflow for changing existing code.

Claude analyzes, specifies, plans, implements, and verifies. Codex independently reviews the plan, writes the verification checklist, and performs the final audit. You are the approval authority: the pipeline stops and waits at every gate.

This repository is a template. Copy CLAUDE.md, prompts/, scripts/, and CHANGE_REQUEST.md into the repository you want to change, fill in the change request, and run the driver.

---

Requirements

Tool	Used for
claude CLI, authenticated	every Claude stage
codex CLI, authenticated	every Codex stage
jq	parsing Claude's streaming JSON events
git	the target repo must be a git repo; the driver diffs the working tree
shasum, awk, column, tee	approval hashes, cost ledger

Run it from an interactive terminal. The approval gates read from stdin, so this does not work unattended or in CI.

The target repository should have a working build and test command that Claude can discover, and ideally a README.md — the baseline stage reads it.

---

Install into a target repository

From the root of the repository you want to change:

TEMPLATE=/path/to/update-agentic-workflow

cp -R "$TEMPLATE/prompts" .
cp -R "$TEMPLATE/scripts" .
cp "$TEMPLATE/CLAUDE.md" .
cp "$TEMPLATE/CHANGE_REQUEST.md" .
chmod +x scripts/*.sh

CLAUDE.md carries the rules every stage is held to — behavior classes, invariant statuses, artifact ownership, the completion rule. Do not skip it; the prompts assume it is in context.

Add the workflow's scratch state to the target repo's .gitignore:

# Agentic change-workflow state
.workflow/

Decide deliberately whether the artifacts are committed. Committing them gives you a durable record of why a change was made and what it was audited against. If you would rather keep them out of history, add:

BASELINE_REPORT.md
CHANGE_SPEC.md
CHANGE_PLAN.md
ADVERSARIAL_REVIEW.md
UPDATED_CHANGE_PLAN.md
IMPLEMENTATION_NOTES.md
CHANGE_TEST_REPORT.md
MANUAL_CHECKLIST.md
VERIFICATION_REPORT.md
DEFECTS.md
FINAL_AUDIT.md

Commit or stash unrelated work before starting. The implementation stage is told not to overwrite uncommitted work, and the driver captures git diff of the whole working tree as the record of what changed — unrelated edits pollute it.

---

Write the change request

CHANGE_REQUEST.md is the only artifact you own. Everything downstream is traced back to it. Fill in every section:

• Change Type — Feature, Bug Fix, Prototype, Refactor, Performance, Security, or Upgrade.
• Reproduction — for a bug, exact steps. The baseline stage will try to reproduce it, and a bug it cannot reproduce is a stop condition on the small track.
• Out of Scope — what must not change. This becomes the "files that must not change" list the final audit checks against.
• Success Criteria — observable evidence. This becomes the acceptance criteria that every later stage is traced to.

Vague input here is the single largest cost driver: the analysis stages widen their search to compensate, and the adversarial review spends its findings on ambiguity rather than on risk.

---

Run it

./scripts/change-workflow.sh

The driver is a resumable state machine. It runs stages until it hits a gate, prints what to review, and waits. Re-running it picks up from the recorded state in .workflow/state.

Stages

State	Runs	Model	Produces
ANALYZE	Claude	Sonnet	BASELINE_REPORT.md, CHANGE_SPEC.md
WAIT_ANALYSIS_APPROVAL	you	—	type APPROVE
PLAN	Claude, then Codex	Opus / high effort	CHANGE_PLAN.md, ADVERSARIAL_REVIEW.md
WAIT_PLAN_APPROVAL	you	—	type ACKNOWLEDGE
UPDATED_PLAN	Claude	Sonnet	UPDATED_CHANGE_PLAN.md
WAIT_UPDATED_PLAN_APPROVAL	you	—	type APPROVE
IMPLEMENT	Claude + Codex in parallel	Opus / low effort	source changes, IMPLEMENTATION_NOTES.md, CHANGE_TEST_REPORT.md, checklist base
CHECKLIST	Codex	low effort	MANUAL_CHECKLIST.md
EXECUTE_CHECKLIST	Claude	Sonnet	VERIFICATION_REPORT.md, DEFECTS.md
FINAL_AUDIT	Codex	high effort	FINAL_AUDIT.md
COMPLETE	—	—	prints the cost ledger

Codex always runs --sandbox read-only --ephemeral; it cannot modify your repository. Claude runs with an explicit tool allowlist (Read,Glob,Grep,Write,Edit,TodoWrite,Bash) — an allowlist, not a permission bypass.

During IMPLEMENT, Codex writes the verification checklist concurrently from the frozen, approved artifacts. Its prompt forbids reading source code, so it cannot race Claude's in-flight edits and cannot bias the checklist toward what was built instead of what was specified. The CHECKLIST stage then reconciles that base against the finished diff.

---

The gates

At each gate the driver prints the files to review and pauses twice: once for you to read them, once for the confirmation word.

==================================================
HUMAN REVIEW REQUIRED
  BASELINE_REPORT.md
  CHANGE_SPEC.md
==================================================

Edits you make at a gate are picked up by the next stage. This is the intended way to steer the workflow — correct a misread behavior in the baseline, tighten an acceptance criterion, reject a finding in the review.

The confirmation word differs by gate, and the difference is deliberate:

• APPROVE — you are endorsing the document's contents.
• ACKNOWLEDGE — you have read it, but you are not endorsing it. The adversarial review is acknowledged, not approved: the next stage's job is to dispose of each finding, not to obey them.

Typing anything else exits without advancing the state. Nothing is lost; re-run the driver to return to the same gate.

On acceptance, each file's SHA-256 is written to .workflow/approvals/. Every later stage re-verifies those hashes and refuses to run if an approved document changed underneath it. If you need to edit an approved document after the fact, re-run the driver and re-approve at the gate rather than editing in place.

A RELAXED or REMOVED invariant requires your explicit approval. The spec stage is instructed to highlight every one. Read for those specifically at the analysis gate.

---

Tracks

WORKFLOW_TRACK=small ./scripts/change-workflow.sh

The small track collapses baseline, spec, and plan into a single Opus call and merges the first two gates into one ACKNOWLEDGE. Every review gate, the adversarial review, the checklist, and the final audit still run.

Use it for a change whose analysis does not justify three cold starts. The prompt carries stop conditions and will escalate rather than compress: it writes TRACK-ESCALATION: rerun without WORKFLOW_TRACK=small into BASELINE_REPORT.md and halts if the change surface spans more than a handful of files, touches a schema or migration, requires relaxing an invariant, needs a prototype or feature flag, cannot reproduce the reported bug, or lands on paths with no test coverage.

full (the default) runs the three analysis stages separately.

---

Tuning

All knobs are environment variables. Defaults are in the header of change-workflow.sh.

Models

Opus is reserved for the two stages where a wrong answer is expensive to undo — the plan everything else hangs off, and the implementation itself. The largest-context stages are mostly read-and-record work and pay Sonnet rates.

Variable	Default
WORKFLOW_MODEL_BASELINE	sonnet
WORKFLOW_MODEL_CHANGE_SPEC	sonnet
WORKFLOW_MODEL_CHANGE_PLAN	opus
WORKFLOW_MODEL_UPDATED_PLAN	sonnet
WORKFLOW_MODEL_IMPLEMENT	opus
WORKFLOW_MODEL_EXECUTE	sonnet
WORKFLOW_MODEL_SMALL	opus

Per-stage budgets, in dollars

A runaway guard, not a target. The cap is checked between turns, so a stage stops shortly after crossing it rather than being preempted mid-turn. If a legitimate stage trips its cap, raise the cap — do not reduce the work.

Variable	Default
WORKFLOW_BUDGET_BASELINE	10
WORKFLOW_BUDGET_CHANGE_SPEC	5
WORKFLOW_BUDGET_CHANGE_PLAN	12
WORKFLOW_BUDGET_UPDATED_PLAN	5
WORKFLOW_BUDGET_IMPLEMENT	40
WORKFLOW_BUDGET_EXECUTE	20
WORKFLOW_BUDGET_SMALL	12

A stage that hits its cap exits non-zero and names the variable to raise. The state is not advanced, so re-running resumes that stage.

Effort

Variable	Default
WORKFLOW_EFFORT_CHANGE_SPEC	medium
WORKFLOW_EFFORT_UPDATED_PLAN	medium
WORKFLOW_EFFORT_EXECUTE	medium
WORKFLOW_CODEX_EFFORT_REVIEW	high
WORKFLOW_CODEX_EFFORT_CHECKLIST	low
WORKFLOW_CODEX_EFFORT_AUDIT	high

The two Codex judgement stages think; the two checklist stages transcribe an approved specification into checks.

Behavior

Variable	Default	Effect
WORKFLOW_TRACK	full	small collapses the three analysis stages into one
WORKFLOW_PARALLEL_CHECKLIST	1	0 writes the checklist serially after implementation
WORKFLOW_SESSION_REUSE	0	1 forks one Claude conversation across stages — faster, but every stage re-sends the whole upstream transcript on every turn, so cost grows with the pipeline. The artifacts on disk are a compressed form of that same context.

---

State, logs, and cost

Everything the driver keeps lives under .workflow/:

Path	Contents
.workflow/state	current state-machine position
.workflow/approvals/*.sha256	recorded approval hashes
.workflow/logs/*.jsonl	raw Claude event streams, one per stage
.workflow/logs/*.log	raw Codex output, one per stage
.workflow/cost.tsv	per-stage seconds, dollars, and token counts
.workflow/change.diff	the authoritative diff the final audit reads
.workflow/change-stat.txt	git diff --stat at implementation time
.workflow/MANUAL_CHECKLIST.base.md	Codex's parallel checklist draft

Running spend is printed at every gate and the full ledger is printed at COMPLETE. Codex stages report tokens only — no dollar figure — so they appear with - in the cost column and their token count in cache_w.

When a stage fails

The driver treats a budget breach, a turn-limit stop, and an API failure as failures even though the CLI exits 0 for some of them — it inspects the final result event. On failure it prints the raw event log path and exits without advancing the state, so re-running the driver retries the same stage.

Restarting

rm .workflow/state              # restart from ANALYZE, keeping approvals
rm -rf .workflow                # full reset, discarding approvals and logs
echo IMPLEMENT > .workflow/state   # jump to a specific stage

Jumping forward manually skips the approval verification that stage would normally have inherited. The stage's own verify_approval calls still run, so it will refuse if the documents it depends on were never approved.

---

Artifact ownership

Claude must not write Codex's artifacts, and vice versa. This is what makes the review independent.

Artifact	Owner
CHANGE_REQUEST.md	you
BASELINE_REPORT.md	Claude
CHANGE_SPEC.md	Claude
CHANGE_PLAN.md	Claude
ADVERSARIAL_REVIEW.md	Codex
UPDATED_CHANGE_PLAN.md	Claude
Source changes	Claude
IMPLEMENTATION_NOTES.md	Claude
CHANGE_TEST_REPORT.md	Claude
MANUAL_CHECKLIST.md	Codex
VERIFICATION_REPORT.md	Claude
DEFECTS.md	Claude
FINAL_AUDIT.md	Codex

---

Reading the result

At COMPLETE, read in this order:

1. FINAL_AUDIT.md — ends with exactly one of READY, READY WITH NON-BLOCKING ISSUES, or NOT READY.
2. VERIFICATION_REPORT.md — what was actually executed. Check for NOT RUN and BLOCKED before trusting any summary.
3. CHANGE_TEST_REPORT.md — N/A and NOT RUN are not interchangeable. N/A means the check does not apply; NOT RUN means it applies and was skipped.
4. .workflow/change.diff — read it yourself. It is the ground truth.

The change is not complete unless acceptance criteria are satisfied, no blocking audit findings remain, no unexplained regressions exist, approved invariants are still enforced, required manual checks were executed, and rollback or containment is understood.

MANUAL_CHECKLIST.md will contain checks that need a human browser, device, account, or external system. The verification stage is required to identify those rather than claim them. They are yours to run.

---

Repository layout

CLAUDE.md                  rules every stage is held to — copy this too
CHANGE_REQUEST.md          the template you fill in
scripts/
  change-workflow.sh       the driver; this is the entrypoint
prompts/
  small-analysis.md        small track: baseline + spec + plan in one call
  baseline.md              full track: BASELINE_REPORT.md
  change-spec.md           full track: CHANGE_SPEC.md
  change-plan.md           full track: CHANGE_PLAN.md
  adversarial-review.md    Codex: ADVERSARIAL_REVIEW.md
  updated-change-plan.md   Claude: UPDATED_CHANGE_PLAN.md
  implement-change.md      Claude: source changes + notes + test report
  manual-checklist-base.md Codex: parallel checklist, spec-only, no source
  manual-checklist-delta.md Codex: reconcile base against the finished diff
  manual-checklist.md      Codex: serial fallback (PARALLEL_CHECKLIST=0)
  execute-change-checklist.md  Claude: VERIFICATION_REPORT.md
  final-audit.md           Codex: FINAL_AUDIT.md

Every prompt carries a context economy or output economy section. Those are load-bearing, not stylistic: everything a tool returns stays in context and is re-sent on every later turn, and every artifact is read by several later stages. Edit prompts freely, but keep those sections.

Not part of this workflow

scripts/workflow.sh, scripts/codex-review-plan.sh, scripts/codex-create-checklist.sh, and prompts/execite-checklist.md belong to an earlier greenfield PROJECT_PLAN.md workflow. They are not invoked by change-workflow.sh and can be omitted when copying this template.