DEV Community: Ordewell

When a coding agent runs out of context mid task

Ordewell — Wed, 07 Oct 2026 13:16:06 +0000

Every coding agent works inside a fixed context window. On a short session you never notice it. On a long refactor it fills with file reads, test output and edit history, and then the session stops or quietly starts forgetting the rule you set twenty minutes ago. The usual advice is to start over and restate the task. That works. It also throws away the reasoning the session spent an hour building.

I build Ordewell, so the second half of this is how my tool approaches the problem rather than a survey. It is free and Apache 2.0. The first half is general. Any agent session has a ceiling, and what to do about it applies whether or not you ever install anything.

Why a long task runs out of room

The window holds everything at once: your messages, the model's replies, every file it read, every command it ran, and the before and after of every edit. There is no selective memory. The agent cannot quietly drop the file it no longer needs and keep the function you care about. The buffer just fills.

The fastest filler is not your typing. It is tool output. A single read of a large source file can put tens of thousands of tokens into the window, and three reads plus a search plus a test run can take half the budget before any code is written. That is why a long session feels sharp at the start and foggy near the end.

When the window gets tight the runner either stops or summarizes. A summary written under pressure is lossy. It tends to keep the goal and drop the specifics: the constraint you named, the path you said not to touch, the approach you already tried and abandoned. The agent is then working from a shorter memory of what you said.

What people do inside the session

The standard remedies are real, and worth knowing before you reach for anything structural.

Compaction replaces the transcript with a summary. In Claude Code that is /compact, and you can steer it:

/compact keep the no-GraphQL rule and the vitest convention

That way what survives is what you named rather than what the automatic pass guessed. Restarting with --continue or --resume carries forward a summary, not the full history, so the same loss applies in a cleaner package.

Moving stable rules into a project file the agent reads at startup, such as CLAUDE.md or AGENTS.md, survives both. What it cannot hold is the in-flight state: which approach you abandoned, which files were already read, what the partial refactor looks like right now. Those live in the session, and the session is the thing that is running out of room.

Compaction is a patch. If you find yourself compacting the same task more than once, that is the signal, not the fix: the task is larger than one window can carry.

The structural fix: fewer things per window

The alternative is to stop needing one session to hold the whole job. Break the work into tasks small enough that each can finish inside a single window, run each task in a fresh session, and hand forward only what the next task actually needs. This is decomposition before the run starts. It is the same idea as delegating a noisy search to a subagent that has its own window, applied to the plan as a whole rather than to one step.

Once the work is split, the plan becomes the artifact that outlives any one session. When a session dies, its task is a line on a list rather than a conversation you have to reconstruct. You can read it, change it, and run it again. The reasoning that a compaction would have summarized away is written down somewhere it can be edited.

How Ordewell does this

The planner reads the repository read-only, asks about whatever is vague, and writes an ordered plan with dependencies. Then each task starts its own fresh coding-agent session, in its own git worktree, and is given the results of the tasks it depends on. Independent tasks run concurrently, three at a time by default.

So what sits in any one session is a single task plus the outcome of its prerequisites, not the entire goal and every file read along the way. A task that fails is a failed task on the plan rather than a session that has quietly degraded. Its dependents are blocked, you can see which ones, and you can edit the task and run it again without replaying the run.

The plan itself is stored on disk, so it survives closing the terminal and coming back later, and what each task is handed is bounded on purpose. Those two pages go into the detail.

A real run

From the command line, the flow is three commands:

export AI_PROVIDER=claude-code
ordewell plan --goal "Add rate limiting to the public API"
ordewell run
ordewell handoff review

Between the plan and the run, the tasks are yours to change. This is how you keep a single task from growing past what one window can hold, by splitting it or by moving work it does not need to do:

ordewell task-model 3 sonnet
ordewell task-deps 3 1,2

That second command makes task three wait for tasks one and two, which also decides what task three's session is handed: the outcome of those two tasks, and nothing from the rest of the plan.

Honest limits

A single task can still be too big. If one task genuinely needs more than a window, splitting the plan around it does not help. Decomposition moves the wall. It does not remove it.
This does not compact for the runner. Inside a task, the runner's own behavior is the runner's own behavior. Compaction and project instruction files still apply there.
The handoff is bounded, which means it is lossy. What the next task needs has to be in its prompt or in the repository. A detail that lived only in a previous session's conversation does not survive just because the plan did.
Parallelism is not a bigger window. Running three tasks at once does not raise any one task's ceiling. It only means independent work does not have to queue.
Nothing here is measured. The claim is about structure, not about token counts, speed or model quality. There is no benchmark behind a number in this post.

Source and design notes

The mechanics above are in the repository rather than recalled. The README describes how each task starts a fresh session given the results of the tasks it depends on, three at a time by default. The other detail is on the site: where the plan lives when the terminal closes, and what each task is handed.

Repo: github.com/ordewell/ordewell

Orchestrating coding agents without a second API key

Ordewell — Tue, 06 Oct 2026 13:05:37 +0000

The first screen of most orchestrators asks for an API key. That is a design choice, not a law. An orchestrator can instead start the coding-agent CLI you already installed and signed into, hand it the goal, and never hold a credential of its own. The arrangement is worth understanding, because it decides what the tool can check before you type anything, and what it can only find out the hard way.

Disclosure: I build Ordewell, so what follows is how it does this rather than a survey. It is free and Apache 2.0. The same question applies to any tool that runs more than one agent, so the reasoning is useful even if you never install it.

Why the key question comes first

An orchestrator has to think somewhere. It plans, and for that it needs a model. There are two ways to give it one. It can call a model provider directly with an API key it stores, or it can start a coding-agent CLI that already knows how to reach a model because you logged it in.

The first is the common default, and it is easy to see why. One HTTP client, one key, one place to bill. The second is what you get if the orchestrator treats the agent as a process rather than a library. That is a harder thing to build, and it changes the shape of the tool in ways that show up in the first five minutes.

What "no extra key" means in practice

Ordewell's planner is a coding-agent CLI. It spawns claude, codex or opencode over stdio and speaks to it turn by turn. The credential is the CLI's own: the login or the key you already gave it. Ordewell never reads it, never stores it, and has nothing to rotate.

A provider API key still works if you prefer that route. Then the planner runs against the provider directly and the CLI is only used for execution. The point is that the key is optional rather than a toll gate on the front door.

Either way the planner stays read-only. It reads the repository, asks questions, and writes a plan. Commands that would change your working tree are refused, because planning and doing are separate jobs and mixing them is how an agent ends up editing files before you have seen what it intends.

The preflight, and what it can honestly know

Before you type a goal, the picker checks each runner. The check is one command, the same one you would type yourself:

claude --version
codex --version
opencode --version

A runner whose binary answers is offered. A runner whose binary is missing is greyed out with the reason attached, in plain words:

claude is not installed or is not on PATH.

That is the whole preflight, and the restraint is deliberate. What it cannot know is whether your login is still live. Answering that question honestly would mean spending a turn on it, which is exactly what a preflight exists to avoid. So an expired session is not predicted. It surfaces on the first turn, as the agent's own error text, in the place where it actually bites.

A preflight that pretended to be deeper would be worse than this one. It would either burn a request at picker time or report a health it never verified, and a confident wrong answer is more expensive than an admitted gap.

The detail worth knowing even if you never use this

On Windows, a CLI is often a .cmd shim rather than an executable. Running it through a shell works, because the shell does the extension lookup. Starting it directly as a process does not, because the process creation call performs no such lookup. So a runner can look healthy in the picker and then die on the first turn with a bare ENOENT and nothing to act on.

The fix is to ask the second question separately. Ordewell probes the binary for a version and probes spawnability as its own check, and when they disagree it refuses the runner with a reason that names the two documented remedies: reinstall with the CLI's own installer, or put its install directory on PATH.

The general lesson is worth carrying to any tool that shells out. "It works in my terminal" and "I can start it as a process" are two different questions, and a check that answers only the first will pass a runner that cannot run.

Which agents can plan

Today only Claude Code, Codex and OpenCode carry a planner transport, so those three are the ones offered as planners. Other runners can still execute the tasks in a plan, each with its own model and mode. The distinction matters when you read a claim like "supports any agent": executing many is a much easier bar than planning with one.

Honest limits

A credential you do not manage is one you cannot fix from here. If the CLI is logged out or its plan has lapsed, the fix lives in the CLI, not in the orchestrator. You get the agent's error text, not a re-auth button.
Presence is not health. The preflight proves a binary answers a version flag. It says nothing about whether the first real turn will succeed.
The planner is bounded by that CLI. Its model catalog and its capabilities set the ceiling. A key-based planner is a different ceiling, not a higher one by default.
Keys are still supported, and still your problem. If you route the planner through a provider API key, you own a credential and a bill again. That is a trade, not a downgrade.
Three planners is a short list. A runner with no planner transport can execute but not plan, and there is no promise here about when that changes.

Source and design notes

Everything above is in the repository rather than recalled: RunnerInstallation.ts (the version probe, the spawnability check, the greyed-out reason), the README's credentials note, and the design decision on coding agents as planners.

The same piece lives on the project site, where it stays canonical: https://ordewell.ai/no-api-key

You can read more at github.com/ordewell/ordewell.

Task order: when a task is ready to run, and what can run in parallel

Ordewell — Mon, 05 Oct 2026 13:05:33 +0000

A plan looks like a list, but at run time it is a graph that the scheduler walks one step at a time. At every step it asks a single question: which tasks may start right now. The answer decides the order, the parallelism, and what happens when something upstream fails. Most of the confusion about "why is my plan not moving" lives in that answer.

I build Ordewell, the tool this post walks through, so what follows is how it does this rather than a survey. It is free and Apache 2.0. Every tool that runs more than one task has to answer the same question, so the reasoning is useful even if you never install it.

The scheduler answers one question, and only that

The planner emits an ordered list of tasks, each with a title, a prompt, and a list of dependencies by task number. It does not emit a running order or a wave plan. Those are derived, and they are derived the same way on every tick, so a task does not start because some step decided to start it. It starts because at that moment it passed every gate.

That distinction matters when you edit the plan: you are not steering a running process, you are changing the state the question is asked against.

The readiness rule

A task is ready to start when all of these hold:

It is pending or approved. A task that is already running, done, or blocked is not a candidate.
It has a prompt. A task with nothing to run cannot start, whatever its status says.
It is not on hold. Cancelling a task, or a failed attempt to spawn its session, takes it out of the queue without rewriting the plan.
It is not blocked. Either it was parked as blocked, or one of its dependencies failed.
Every dependency is met. This is the interesting one, and it is not the same as "every dependency finished".

Tasks that pass all five are sorted by their plan order, and the first ones up to the free slots start. Everything else is left where it was.

A dependency is met when its work is on the branch

This is the part that surprises people. A dependency task is not met just because it passed. It is met when its work has landed on the integration branch the run is building.

The reason is mechanical. A change task runs in its own worktree, cut from the integration branch at the moment the task starts. If the scheduler started a dependent as soon as a predecessor's marker appeared, it would cut the dependent's worktree before the predecessor's commit had been merged, and the dependent would look at a tree that does not contain the code it depends on. It would then fail for a reason that has nothing to do with its own prompt, or worse, build on the old shape of the file and pass anyway.

So the gate checks two things in sequence. The predecessor must be marked completed, and, if it ran in an isolated worktree, its record must read as merged. Between those two moments the dependent simply waits.

The same rule has a second edge. Ops tasks and manual tasks run in your own checkout, not in a worktree, so they see landed work only after a merge too. Their completed dependencies whose work has not been merged yet form a merge gate, and the task waits behind it. That is what stops a test or a deploy task from running against a checkout that does not have the change it is meant to exercise.

Order is fixed, parallelism is a cap

Plan order is not a schedule, it is a tie breaker. Once tasks pass the gates, the ready ones are taken lowest order first, and only as many as there are free slots. Independent tasks run side by side, three at a time by default. The cap is a slot count, not fixed waves, so as one task lands the next ready one moves up, with no reshuffling of the plan.

This is why two tasks that touch different files can genuinely overlap, and why two that share a file should not be declared independent. The scheduler trusts the dependency list it was given. If you leave an edge out, it will happily run both at once and let the merge step find the conflict.

A failure upstream stops the queue downstream

A failed dependency blocks its dependents. They are not started, and they are not silently dropped: they wait as blocked while you decide what to do with the failed task. Everything not downstream of the failure keeps running, which is the point of reading the graph rather than freezing the whole plan.

Re-running the failed task releases its dependents once it lands. There is no separate resume step for them, because they were never started.

You can change the graph, and the scheduler follows

Dependencies are part of the plan, so they are editable before the run and fixable inside it. One command sets the list:

$ ordewell task-deps 3 1,2
$ ordewell status

The guard on that edit is deliberately narrow. A task cannot depend on itself, cannot name an unknown task, and cannot depend on a task that comes after it in the plan. In practice that means the graph the planner emits is acyclic by construction: edges only ever point backwards along the list, so there is no cycle for the scheduler to trip over at run time. It is the one edit that could leave a plan unschedulable, and it is the one edit that is checked for well-formedness rather than left to the model.

While a plan runs, the task list the sessions see is a report of the stored state, not a plan the model reinterprets. A running session is told which line it is on and that the rows above it are context, not work to repeat.

Honest limits

The list is trusted, not verified. If two independent tasks really do edit the same file, the scheduler runs them together and the conflict surfaces at merge time.
Parallelism is a count, not a budget. The cap keeps three sessions in flight. It does not know a long test suite from a one line edit, so slots can sit idle.
Blocked is sticky until you act. A dependent of a failed task will not retry on its own. Clearing it means fixing or re-running the upstream task, or editing the dependency.
A missing edge is invisible. The dependency graph is also the context boundary and the ordering rule, so an edge the planner forgot removes both the wait and the hand off.

Where this lives in the code

Everything above is in the repository: readiness.ts (the readiness function, the gates, the merge gate, the slot cap), the dependency guard in TaskOps.ts (canSetDependencies: no self edges, no forward edges, no unknown ids), and the task edit validator. The project is at github.com/ordewell/ordewell, and a longer version of this page sits at ordewell.ai/task-dependencies.

What a coding agent may run without asking you

Ordewell — Sun, 04 Oct 2026 13:03:01 +0000

An agent that can run commands has to be told what counts as a question and what counts as ordinary work. Get that line wrong one way and it prompts on every file read until the plan is unusable. Get it wrong the other way and it has quietly been allowed to do whatever it likes for an hour. The design worth looking at is not the prompt. It is the scope, the mode, and what a decision is worth once you have made it.

Disclosure: I build Ordewell, so this is the policy it applies rather than a survey of the field. The tool is free and Apache 2.0. The mechanics are worth arguing about whether or not you install it.

The unit of approval is a scope, not a command

The obvious design is a queue of exact commands: the agent wants to run ls /tmp/foo, you say yes, and next time it runs ls /tmp/bar it asks again. That design fails on contact with a planning loop. A planner doing real research reads forty things in a row, and forty prompts turn a useful feature into a wall of dialogs.

So the decision is keyed on a scope instead. Approving a read of /tmp/foo/a.log grants /tmp/foo/*. Approving az group list grants az group. The grant is broader than the thing you approved, deliberately, and it is remembered for the rest of the session so the same class of call never asks twice. Saying yes once covers everything under that path or command family, including arguments the agent has not thought of yet.

Three modes, and a floor under all of them

Underneath the scope there is a mode, and it is what you would set for a run you are not sitting next to.

ask consults the human channel, and if there is no channel it denies. Headless and web runs have nobody at the other end, so in ask mode they refuse an out-of-envelope call rather than guess.
allow grants everything the tier system did not already refuse. The tier rules, not this setting, are what is still holding the line.
deny grants nothing beyond the list you approved up front.

The pre-approved list is honored under every mode, including deny. That ordering is on purpose: it is an explicit operator decision, not a default that a mode setting is allowed to override. In practice this is the knob that makes an unattended run possible. You write the handful of things this plan genuinely needs, set the mode to deny, and walk away.

Every decision is labelled with where it came from, so a log or a UI can say why a call was allowed rather than only that it was:

  type ApprovalSource =
    'pre-approved' | 'remembered' | 'mode' | 'asked' | 'no-channel'

That list is the honesty of the feature: a call allowed by mode is a standing rule, and a call allowed by asked is a person.

A denial is remembered too

Yes and no get the same treatment. If a policy denies a lookup, that denial is kept, so a model that retries the same blocked call burns one tool round instead of putting the same question to you again. The refusal carries back as a normal, actionable tool result: the model is told the answer was no, which is information it can plan around, rather than being left to hang.

A call can touch more than one scope, and a no to all of them together is remembered as one refusal rather than several, because your no may have been about any one of them.

One ask per scope, and a session that forgets on purpose

A parallel tool round can produce several requests for the same thing at once. They collapse into one question: the first goes to you and the rest wait on the same answer, so a burst of parallel calls cannot become a burst of prompts.

Grants live for the session rather than forever. On reset the granted and refused sets are dropped, and an answer still in flight from before the reset may not write into the new state. A stale yes landing a second late cannot silently re-open something you cleared.

There is also an answer beyond yes and no. Where the requester offered a suggestion of a broader grant, you can allow it for this task alone. Where none was offered, that answer degrades to a plain allow: the code will not make a grant the requester never proposed, because a button is not a mandate.

What happens when nobody answers

This is where a research loop and a task runner get different treatment, deliberately.

A planner turn that blocks forever on an unanswered prompt would hang the whole research loop with no visible cause, so a planner prompt expires. The default is five minutes. On expiry the request resolves to denied and the model receives a normal tool result, which means the loop continues and the cause is legible. Nothing sits there holding the process open on a question nobody is watching.

A task runner's request is the exception. That session is parked on the answer rather than looping, so it waits for a person however long that takes. The cost is honest: a run left unattended in ask mode with a runner waiting will sit there until you come back.

In both cases the request is cleaned up when the attempt ends. Every way an attempt can finish reaches the runner as a stop, and open requests are denied before the session goes, so nothing waits on a process that no longer exists. A request the runner withdraws is settled as denied so it comes off every surface showing it. Anything still outstanding is replayed to a surface that connects late, so opening the UI after the fact does not show an empty list.

Limits

The floor is per session, not per task. A grant you make while one task is running is available to the next one in the same session. If you want task-level separation, that comes from the mode and the pre-approved list, not from the memory.
Allow mode is only as good as the tier rules underneath it. It grants what those rules did not refuse, so if a command family is permitted there, allow mode lets it run.
A prefix grant is wider than the example you approved. That is what makes it usable, and it is also the thing to read twice before clicking.
There is no automatic escalation on a denial. The policy does not back off, retry with a different model, or widen its own scope after a no. The next move is yours.
Grants do not survive a restart. They are held for the session. Come back tomorrow and the questions come back with you.

Source and design notes

The policy that answers out-of-envelope calls once, remembers the answer, and knows the difference between a standing rule and a person lives in the approval policy, the request bridge and runner permission requests. The rest is at github.com/ordewell/ordewell.

What each task in a plan is handed, and what it is not

Ordewell — Sat, 03 Oct 2026 13:04:47 +0000

A plan runs several coding-agent sessions, one after another or several at once. None of them shares memory with the others. Each one starts with an empty context window, so the only thing that carries knowledge forward is what the orchestrator decides to hand over. That decision is worth reading, because it is the difference between a task that continues the work and a task that rediscovers it.

Disclosure: I build Ordewell, so what follows is how it does this rather than a survey. It is free and Apache 2.0. The shape of the problem is the same in any tool that runs more than one session, so the reasoning is useful even if you never install it.

The problem: an agent knows nothing about the session before it

It is tempting to imagine the plan as a conversation. It is not. Task two is a fresh process with a fresh prompt. Whatever task one learned about your codebase, whichever approach it abandoned, whatever it named a function, all of that is gone unless it was written into the working tree or handed back explicitly.

The lazy fix is to paste everything: the whole transcript of every previous task, or the planning conversation that produced the plan. That fails in a way you will not notice until it does damage. The transcript of an interactive runner contains the prompt it was given, and that prompt contains the token the watcher looks for to mark the task complete. Hand a predecessor's output to a dependent as raw text and you can settle the dependent on the predecessor's evidence, the moment the session starts.

What a task is actually handed

Three blocks, assembled in a fixed order and placed above the task's own prompt. First the plan map, then the outputs of the tasks it directly depends on, then the task itself. All three are composed from the plan state, not from anything a model wrote about itself.

The plan map is a numbered list of the tasks in the plan with their current status, the runner assigned to the current one if a runner is set, and a single marker on the line the session is working:

## Plan map
 1. [done   ] Add the settings model
 2. [NOW    ] Wire the flag into the CLI   ← you are here
 3. [next   ] Update the reference docs

(4 tasks omitted from this view)

Statuses are read off the stored task state, so the map is a report of what already happened rather than a plan the model is free to reinterpret. The header states the one rule that matters: this list is for context, do only the task marked as current, and do not preempt the tasks that follow.

The outputs of direct dependencies, and nobody else's

Below the map comes a block per dependency the task declared, in plan order. Each block is short by construction: the review note recorded for that task, and the tail of its captured output.

Two details matter. The first is that the tail is a tail. It is capped at 500 characters, taken from the end, which is where a runner's final summary and its completion marker sit. The second is that only direct dependencies contribute. A task that depends on A, which depends on B, gets A's output and not B's. The dependency graph the planner emitted is also the context boundary, so the amount a task has to read grows with the shape of the graph rather than with the length of the run.

Two tasks running side by side in the same wave see nothing of each other. That is deliberate: they touched different files by design, and giving each one the other's in-progress output would invite it to edit the other's work.

A quoted completion marker would be evidence for the wrong task

Interactive runners echo the prompt into the terminal, and the watcher reads that terminal output to decide whether a task is done. So any text carried over from a predecessor has its markers broken before it is inserted. The token is rewritten into a hyphenated form that no scanner accepts, and the identifier inside it is dropped entirely.

The hyphen rather than a space is not cosmetic. The watcher also reads a whitespace flattened view of the terminal, where a spaced out token would be rejoined into a live one. And the dropped identifier matters for a second reason: transcripts are bound to a task by that identifier, so if a dependent quoted a predecessor's full token, the dependent's own transcript would later answer questions about the predecessor.

The same reasoning applies to the completion marker instruction itself. It is given to the model in two halves, with the assembled token never appearing in the prompt, so that echoing the prompt cannot complete the task in the first second of the run.

A resumed session gets the files and a warning

Continuing a task is a different case. The session still holds its original prompt, so the prompt is not resent. What changed is the working directory: it was recreated from the integration branch, so an earlier attempt's edits are present only if that work actually landed. The continuation reminder says exactly that, and tells the model to check the files before relying on them.

That is the whole protocol. No transcript pasted forward, no summary generated by a model, no memory file that quietly drifts out of date. Task state and captured output are the interface, and everything a task knows about its predecessors came through it.

Honest limits

The tail can miss the useful part. A test failure printed near the top of a long run is not in the last 500 characters. The review note is meant to carry that, and it is only as good as the attempt that wrote it.
Indirect dependencies are invisible. If B's result mattered to a task that only depends on A, it reaches that task only if A mentioned it. Declaring the dependency is the fix.
The map is a window. Past 30 entries the list is trimmed around the current task and the footer counts what was left out. A task cannot see the whole plan, by design.
It is text, not an enforcement. A model can ignore the instruction to stay in scope. The boundary keeps it informed, not obedient.
Defusing is a convention. It protects against a marker being read out of carried context. It is not a security boundary, since a runner could print a valid looking token on its own.
Captured output is bounded for a reason. The cap keeps a predecessor's noise from crowding out the task's own prompt. Raise it and you trade attention for detail.

Source and design notes

Everything above is in the repository rather than recalled: promptAugment.ts (the composition order, the 500 character tail, the 30 entry window and its look back, the marker defusing), the Task model, and github.com/ordewell/ordewell.

The transcript is the record: reading what a coding agent actually did

Ordewell — Fri, 02 Oct 2026 13:01:44 +0000

Every coding agent writes its own session down. Not the cheerful summary it prints when it stops, and not your scrollback, which died the moment you resized the window. A structured file, one record per turn, on your disk. It is the closest thing these tools have to an audit trail, and almost nobody opens it.

Disclosure: I build Ordewell, so the store formats below are the ones my tool reads and the paths are the ones it looks in. It is free and Apache 2.0. The paths and the finding method are true of Claude Code, Codex and OpenCode whether or not you ever install what I built.

The screen is not the record

A terminal UI repaints. A spinner overwrites a line. A collapsed tool call hides the command it ran. The buffer holds what fits and forgets the rest. Anything that judges a task by reading the terminal is reconstructing meaning from a rendering, which is fragile exactly when it matters, at the end of a long run when the interesting part has already scrolled away.

The agent writes something better while it works. Claude Code appends one JSON record per line to a session file. Codex writes a rollout file per session. OpenCode keeps messages and typed content parts in a SQLite database. Three shapes, same idea: the agent's own account of each turn, written as it goes, not painted afterwards.

claude-code   ~/.claude/projects/<munged-cwd>/<session-id>.jsonl
codex         ~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl
opencode      ~/.local/share/opencode/opencode.db   (sqlite: session, message, part)

Claude Code also honours CLAUDE_CONFIG_DIR, which is where a
subprocess or a containerised session will have written.

Finding the session that belongs to the task

Parsing the file is easy. Deciding which file is this task's is the whole problem, because a busy repository accumulates a session per run. Three signals, in order of how much they are worth.

Directory. Claude Code names its project folder after the working directory, with every non alphanumeric character turned into a hyphen. That is a one to one mapping you can compute yourself, which makes it a good first filter and a bad final answer. Paths longer than 200 characters get shortened and given a hash by Claude Code itself, so a deep worktree path can land in a folder whose name you cannot predict.

Time. A session file is created when the agent starts. Anything last modified before your task began is an earlier run in the same directory, so it can be dropped without opening it. This is a filter, not a decision. Two tasks in the same folder minutes apart still collide.

The completion marker. This one decides. If your prompt asks the agent to print a unique marker when it is finished, then the transcript that contains that marker is the transcript of this task, and the ones that do not are other people's work. The marker is doing the identity work that a session id cannot, because the ids are minted by the agent and never handed back to you.

Read in that order, the search stays small: filter by directory, sort by modification time, then open candidates newest first until one carries the marker. The first one that does is your task's record.

What you get, and what you do not

What you extract is the agent's final answer as it was written, joined from the last assistant turn's text blocks, with none of the decoration the interface added. For a plan of tasks where each one signs off with a marker, that is a clean end to the run: the marker is there, and the text next to it is what the agent said about the work.

What is not in there is a tidy timeline of the commands that ran, the diff that came out, or any judgement about whether the work is good. A transcript tells you what the agent said about itself. That is a record of claims, not proof, and the two get confused constantly in this space. The diff in your worktree is what settles whether the work is right.

Reading it yourself

You do not need anything I wrote to do this. Pick the newest session file for the project, keep the assistant records, pull the text blocks out, and read the tail.

$ f=$(ls -t ~/.claude/projects/*my-project*/*.jsonl | head -1)
$ jq -r 'select(.type=="assistant" and (.isSidechain|not))
      | .message.content[]? | select(.type=="text") | .text' "$f" | tail -40

Codex is the same idea with a different envelope: each line carries a timestamp and a payload, the assistant text sits under response items whose role is assistant, and a session metadata record names the working directory the session was started in. Checking that last field is worth the effort, because a session started somewhere else should not answer for the task you are asking about.

These stores are private, undocumented, and they move

OpenCode migrated from files to SQLite partway through 2026. Claude Code munges directory names and shortens the long ones. Codex thread ids are minted by the server, so no local naming scheme can recover them. None of this is a published interface, which is exactly why a reader built on top of it has to be defensive: a missing file, a line that will not parse, or a shape that drifted returns nothing instead of throwing, and the tool falls back to reading the terminal.

Treat the paths as a convenience, not an API contract. If an agent ships an update and your reader goes quiet, the correct outcome is a fallback and a still working run, not an exception at the end of an hour of work.

Honest limits

It is the agent's account of itself. The transcript is what the agent chose to say. It can be accurate, vague or confidently wrong, and reading it does not check the repository.
It only works on your machine. These are files and a database under your home directory. A managed or cloud agent whose filesystem you cannot reach gives you nothing to read.
A marker is a precondition. Without a unique marker in the prompt, session selection drops back to directory and time, and a resumed session can still hold the previous attempt's answer next to the new one.
You get the tail, not the film. Readers keep the end of a transcript, and the practical ones clamp it to a few thousand characters. Older turns are still on disk, just not in what gets handed to you.
Nothing here is stable. The formats rotate with the agents and every reader is best effort by design. That is a real maintenance cost, paid quietly by whoever keeps the reader working.

Source and design notes

The reader described above, including the defensive fallbacks: transcriptCapture.ts, the interface it satisfies TaskOutputSource.ts, and github.com/ordewell/ordewell.

Ask first: the questions a planner asks before it writes the plan

Ordewell — Thu, 01 Oct 2026 13:02:28 +0000

The most useful part of planning happens before any task exists. A goal arrives underspecified, the agent reads the code, and then it either guesses or it asks. The guess becomes ten tasks built on a decision you never made. The question costs one reply and changes nothing that has already run.

Disclosure: I build Ordewell, so this is the question step as it works in my tool rather than a survey of the field. It is free and Apache 2.0. The reasoning stands without installing anything.

A plan is cheap to change before it runs

Everything in a plan is expensive in proportion to how far it has travelled. Changing a sentence in the goal is free. Editing a task in the plan is nearly free, because no session has executed it yet. Changing the code an agent already wrote is the expensive one, and it is expensive in the way that matters: you now own a diff, a verdict and a review, and the underlying choice it was built on is still the wrong one.

That is the whole case for the question step. Ambiguity that costs one sentence at the start costs a rewritten task later, and a decision that fans out into dependencies costs several tasks. So the planner is told to resolve ambiguity before it decomposes, not to produce a plan and let you correct it afterwards.

Facts are the agent's job, decisions are yours

The rule that keeps the questions short is a split of responsibility. Anything that can be looked up is looked up. Which router the project uses, where the config lives, whether a dependency already exists: those are facts, and a question that asks you for one of them is a question the agent should have answered by reading the repository.

What is left is the part that is genuinely yours. The planner is instructed to ask when the goal is vague or when a decision would materially change the outcome, and the examples it is given are exactly the forks that are not recoverable later: which storage engine, which library, how wide the scope is, what shape the API takes.

The same rule cuts the other way. A clear, fully specified goal needs no questions at all. If you have already named the library and the shape, the questioning step should be empty and the planner should get on with the plan. Questions are not a ritual.

One question at a time

Batching questions feels efficient and is not. A decision usually determines which questions are worth asking next: answer the storage question one way and the migration question changes, answer it another way and the migration question disappears. A list of five questions written before the first answer is a list where four of them are guesses about a world you have not described yet.

So the instruction is one question per message, no numbering, no second question tacked onto the end, and then stop and wait. It is slower to read and faster to finish, because it does not walk you through questions that only existed under an assumption you were about to correct.

  ❓ Where should plan state be stored?
     sqlite / a json file next to the repo / a server
     I found a db/ folder and a migration runner,
     so I would use sqlite unless you want the
     plan to be readable and diffable by hand.

  ➡️ sqlite, migrations in db/migrations

Questions also have to be grounded. The planner is told to reference actual files, so its question arrives with the evidence that produced it and a recommendation attached. A question with no file behind it is not clarify, it is a survey, and you can answer it by asking the agent to go read something.

When there is nobody to ask

Some runs have no user in them. A one shot run is told the opposite of the interactive rule: there is no one to answer, so where the request is ambiguous it makes the most reasonable assumption grounded in its research and writes that assumption into the task description.

Writing the assumption down is the part worth copying even if you never touch the tool. An assumption recorded next to the task it shaped is reviewable at the moment you read the plan. The same assumption held silently is discovered later, in a diff, by whoever has to work out why the code does what it does.

The outline before the JSON

Answering the questions does not hand you a finished plan. The planner first writes a short prose outline: the slices, in order, in plain sentences. Only after you confirm that outline does it turn it into the structured task plan, with dependencies, and runners, models and thinking effort per task.

Two steps where one would do, on purpose. The outline is where you catch a wrong decomposition, and decomposition is the decision with the longest shadow: a plan with the boundaries in the wrong places fails one task at a time for an hour before anyone can see it. Correcting the same mistake in a paragraph of prose takes one reply.

Honest limits

Questions can be a stall. An agent that keeps asking for confirmation is not making progress. The conversation loop carries a guard against a planner that repeats the same read instead of answering, but a badly prompted planner will still prefer asking to deciding.
A grounded question can still be wrong. The agent recommends sqlite because it found a database folder. That is research, not proof, and a confident recommendation is the easiest kind of wrong answer to accept.
Nobody has to answer well. Approving an outline without reading it is allowed, and it moves the same mistake one step later. The step only helps if you treat it as the last cheap moment.
It costs a round trip. On a small, clear job the whole exchange is overhead a single prompt would have skipped. That is what the no-questions-when-the-goal-is-clear instruction is for, and it is a judgement the planner makes, not a guarantee.
The outline is not a contract. A plan can still be edited after it is committed, so confirming the prose is a checkpoint rather than a lock. It is a strong checkpoint because the plan is still editable, not because the plan is final.

Source and design notes

The question step as described lives in the planner's instructions, the conversation loop and the grilling skill that ships with the tool.

Ordewell turns one goal into an ordered, editable plan of coding agent tasks, each with its own runner, model and mode, and treats a task as done only when its completion marker shows up in that runner's output. Source: github.com/ordewell/ordewell. Free, Apache 2.0, no paid tier.

Where the plan lives when the terminal closes

Ordewell — Wed, 30 Sep 2026 13:02:23 +0000

Most agent work lives in a conversation, and a conversation is as durable as the tab you have open. Close it, reboot, come back in the morning, and the context is gone. The plan you spent an hour agreeing on is a scrollback you no longer have.

The alternative is to treat the plan as a stored artifact, and then the interesting questions are about coming back: how you find the plan again, what state it is in, and what happens to the work that was in flight when you left.

Disclosure first: I build Ordewell, so this is the shape of the tool rather than a survey of tools. It is free and Apache 2.0, and the questions are worth asking whether or not you install it.

The plan is not the conversation

In Ordewell the plan is a graph of tasks with dependencies, each task carrying its own runner, model, mode and a completion marker. It is stored as a named session by the local daemon, which means the plan outlives the process that created it. The conversation that produced the plan is a separate thing and is not the state you come back to.

That has a consequence worth stating plainly: the thing you reopen is not a transcript, it is a work queue. Tasks have statuses, the graph has an order, and every task's verdict is on the record next to the evidence for it. A transcript gives you the mood of the work. A queue tells you what is left.

# every plan in this workspace, newest state first
ordewell sessions list

  3d41ab9f  approved     9 tasks  2026-09-29T14:02  wire the billing retry path
  77c0e2a1  completed    4 tasks  2026-09-26T09:18  add the CSV export flag
* a19f8b02  running      6 tasks  2026-09-30T08:44  move auth to the new table

The listing is per workspace, which is the honest boundary: sessions belong to a repository directory, not to the machine, so a plan does not follow you into an unrelated checkout.

Coming back to a plan

Loading a past session is one command, and it does two things rather than one. The CLI repoints its own notion of the current session, and it hands the session to the daemon as well, because a daemon can only execute a plan it currently holds. Skipping the second half is how you get a command that looks right and then says it cannot find the plan.

# pick the plan back up
ordewell sessions load a19f8b02

# what is done, what failed, what is still owed
ordewell status

# continue: tasks already verified are not run again
ordewell run

Resuming is not restarting. A completed task is not re-dispatched on the next run, so the cost of coming back is the work that is actually left, which is the property that makes leaving safe in the first place. If you closed the laptop halfway, the half that finished stays finished.

If you are not sure which plan you want, the id is enough to ask: the session record carries the goal text, the task count, the status and the creation time. A workspace with a dozen plans in it is navigable rather than a pile.

The work you left behind, and how to land it

Tasks are one thing to come back to. Their output is another. When a plan runs isolated, each task gets its own worktree and branch, and the run finishes by leaving one branch standing for the whole run. That branch is the thing you review, and it is the piece most likely to be forgotten, because it lives in git rather than in the tool.

The handoff command is the terminal counterpart of the same actions the TUI exposes, and it has four moves:

# what the run actually changed, against the base it started from
ordewell handoff review

# land it on the branch you have checked out
ordewell handoff merge

# throw the run away, branches included
ordewell handoff discard

# remove the worktrees, keep the run branch for later
ordewell handoff cleanup

Merge and discard are the two steps that cannot be undone, so both ask before they act, and --yes is the explicit way to say you have already answered. That is a small design point with a large practical effect: the commands you type absent-mindedly are the safe ones.

Review prints the diff between the run branch and its base, and if the run produced nothing it says so in one line rather than printing an empty page. A multi repository run reports per repository, and merge refuses rather than half landing: either every repository can take the branch, or nothing is merged. Afterwards the run's worktrees and task branches are removed, which is the cleanup you would otherwise do by hand some time next week.

Honest limits

A handoff needs an isolated run. If the run was never isolated there is no run branch to review or merge, and the command says so instead of inventing one. Landing the work is then the ordinary git work you were doing anyway.
Nothing resumes inside a task. The task is the only checkpoint. A task interrupted mid flight is a task you retry from the start, on a fresh session for that task, with the repeated work that implies.
Sessions are local and per workspace. There is no cloud copy and no sync. A plan stored under one repository directory is not visible from another, and a machine that is wiped takes its plans with it.
Merge is not resolution. If the branch conflicts with the branch you are on, the conflict is surfaced rather than solved for you, and the decision about whose change wins is yours.
Kept worktrees accumulate. A failed task keeps its worktree so you can inspect it, which is useful exactly once and clutter afterwards. Nothing prunes them on a timer.

Reading the code instead of trusting the description

The session store and the handoff actions are ordinary local state, which is why I would rather point at the source than describe it: the session commands and handoff commands live in the CLI package, and the isolation decision behind the run branch is written up as an ADR in the repository.

Repository and README: https://github.com/ordewell/ordewell
Session commands: https://github.com/ordewell/ordewell/blob/main/packages/cli/src/commands/sessions.ts
Handoff commands: https://github.com/ordewell/ordewell/blob/main/packages/cli/src/commands/handoff.ts
The isolation decision: https://github.com/ordewell/ordewell/blob/main/docs/adr/0013-worktree-isolation.md

One worktree per task: where a coding agent's work actually goes

Ordewell — Tue, 29 Sep 2026 13:03:36 +0000

Run two coding agents at once in the same checkout and you have two writers on one tree. Both sessions look fine, both print a marker, and one has already overwritten the other's file. The fix is not a better prompt, it is a boundary: every task gets its own git worktree, and the results stay apart until you decide what lands.

Disclosure: I build Ordewell, so this is how it does it rather than a survey of the field. It is free and Apache 2.0. The mechanics matter whether or not you install it, because every harness that runs several sessions answers the same question.

The problem with one shared checkout

The first version is a directory and a loop: several sessions run in the workspace root, and the prompt asks the planner to keep parallel tasks on different files. That is advice to a model, not a boundary.

It fails in both directions. Two tasks that genuinely need the same file get serialized behind an invented dependency, which costs the parallelism you were paying for. And when the overlap happens anyway, it fails silently: runner B rewrites the file runner A just changed, A's completion marker still appears, and A verifies as passed against a tree that no longer holds A's work. There is a second loss too: no per-task record of what changed, so no way to undo one task without unpicking the others.

One worktree per task, one branch per run

When the workspace is a git repository, each task runs in its own worktree, created from the integration tip of the run rather than from your working tree. The worktrees sit under .ordewell/worktrees//-, which is already git-ignored, and each task carries its own branch.

The runner is handed a cwd and nothing else. Git never enters the runner adapters, so Claude Code, Codex and OpenCode cannot develop three different ideas about how work is isolated. A workspace that holds more than one repository is treated as a group: one worktree per repository per task, all on the same branch name.

Making a fresh worktree actually runnable

A fresh worktree with no node_modules cannot run your tests, so ignored artifacts are linked in: dependency folders, virtualenvs, environment files, agent config directories. .ordewell/ is never linked, because session and skills state belongs at the main root where a runner cannot corrupt it. A configured setup command replaces the linking where sharing is wrong.

Two details bite. Links are recorded per task, because an ignore rule such as node_modules/ does not match a symlink, and without that record they would be committed into the task's branch. And a whole folder link is wrong for workspaces: npm and pnpm install a workspace package as a link inside node_modules, which through a folder link resolves from the main checkout, so a task changing a package tests its dependents against the stale copy there. Entries are mirrored one at a time instead, and workspace links are recreated to resolve inside the worktree.

Integration is a queue, and it is serialized on purpose

Isolation makes overlap safe. It does not make overlap free. Verdicts can arrive at the same moment, so landing is a queue: one task at a time, with the lowest plan order going first among the tasks already waiting.

Each task lands as a merge commit on the run's integration branch, not as loose files copied over your code. A merge commit preserves any commits the runner made itself, shows who did what in git log, and leaves the task branch an ancestor, which is what makes deleting it safe.

A task that did not land is not a lost cause. The merge is aborted and both refs are kept, so the work is still there to inspect, retry or hand to a repair attempt. Landing across several repositories is atomic: if one repository conflicts, the merges already made for that task in the others are rolled back, so the task is conflicted as a whole rather than half landed.

Conflicts are surfaced, not quietly resolved

Resolving a conflict means deciding which of two changes wins. Handing that to a model silently rewrites a merge nobody reviewed, and it makes the outcome depend on a model's word, the thing an evidence based verdict exists to avoid.

So the conflict is surfaced with the files that conflicted, and resolving it is opt in. A bounded repair attempt can run as a new attempt of the conflicted task in its own worktree, and it still lands through the same queue with the same checks: its branch has to contain the tip the repair started from and add no leftover conflict markers. If the repair did not really bring the branch along, it conflicts again rather than being taken at its word.

The end of a run is a handoff, not a merge

Ordewell never merges into the branch you have checked out on its own. That is the one irreversible step, and your tree may hold work in progress. A run ends with the integration branch parked for review, the base ref it came from, and a list of what landed.

Merging on request preflights every repository first: no merge already in progress, no conflict against what you have checked out, no uncommitted edit to a file the merge would change. If any repository fails the preflight, nothing is merged anywhere. Discarding removes the worktrees and task branches, and never deletes landed work you have not merged yourself.

# a dirty tracked tree in any repo holds the whole run
ordewell run --stash
ordewell run --without-isolation

# end of run: integration branches parked, one per repo
ordewell handoff review
ordewell handoff merge
ordewell handoff discard

Honest limits

A worktree needs a git repository. A missing git binary, a folder with no repository, or a repository with no commits falls back to the workspace root with a notice. Containers and scratch folders are where this shows up. - A dirty tracked tree blocks isolation. The two ways on are stashing those changes or running that one run without isolation. Untracked files never block: the bootstrap accounts for them. - The queue is serialized. Landing is one task at a time, so the throughput you gain is bounded by the dependency graph the planner emitted. Isolation makes same-file overlap safe, it does not predict it. - A shared dependency folder is still shared. Two worktrees installing at once race, because the install is shared. The setup command is the escape hatch. - Some shared files are copies on Windows. A hard link that is impossible across volumes becomes a copy, and edits to it stay inside that task's worktree. - Nothing is cleaned up that might be yours. A worktree holding unlanded work is kept, because it may belong to a runner another host is still driving. That is a directory you delete by hand.

Source and design notes

The decisions above are written down in the repository rather than summarised from memory: ADR 0013, worktree isolation, ADR 0014, multi-repo workspaces, ADR 0015, conflict repair, the isolation interface, and github.com/ordewell/ordewell.

Do you need a PRD before a coding agent starts?

Ordewell — Mon, 28 Sep 2026 13:03:02 +0000

A PRD can be a document you write for a coding agent, or a file the planner writes for itself. When it pays off, when it is busywork, and what it does not guarantee.

The question usually arrives after an agent built something you did not ask for, in a shape you did not want. The reflex answer is "write a spec first". That is right about half the time, and the half it is wrong about is the half where the spec would have been a paragraph anyway.

Disclosure: I build Ordewell, so this is how one tool handles the question rather than a survey of the field. It is free and Apache 2.0. The distinction below is worth having whether or not you install anything.

The plan is not the spec, and the spec is not the plan

Two documents get conflated. A plan is a set of tasks with dependencies, each one small enough for a single agent session. A PRD is the feature described in prose: what it is for, who it is for, what the stories are, what is out of scope.

A plan answers "what do I run next". A PRD answers "why is this correct". A plan is written for the scheduler. A PRD is written for the argument you are going to have with yourself in three days when a task looks wrong and you cannot remember what the point of it was.

When the PRD pays for itself

When the work will be revised. This is the strongest case. A plan gets re-read, and it should be re-read against the whole feature and not against one task's slice of it. If the spec exists as a file, the revision pass opens the spec. If it only exists in the original prompt, the revision pass has to reconstruct it from a conversation that has since grown.

When tasks need to trace back to intent. A task that says which user story it delivers can be argued about. A task that says "refactor the provider layer" cannot. If the PRD is there, each task can carry the exact story text it covers, copied rather than paraphrased, so the mapping is auditable instead of implied.

When more than one person has to agree. A spec is a review artifact. It is cheaper to disagree with prose than with a diff.

When it is busywork

When the goal is already fully specified. "Add a retry with backoff to the fetch helper, three attempts, jitter, log each attempt" is a complete spec. Writing a PRD for it produces a document whose only reader is the plan.

And when the unknowns are in the code, not in your head. If the reason you cannot specify the work is that you do not know how the current thing works, a PRD will not fix that. Reading the repository will. Writing a spec on top of a repository you have not read is how you get a beautiful document specifying the wrong system.

The middle path: questions before the plan

The alternative to writing a spec is being asked what you meant. A planner that has read the repository can ask two or three questions that only someone who has read the repository would ask, and the answers are usually more useful than the document you would have written blind.

In Ordewell that is what happens before planning. The planner explores a read-only envelope, then asks concise questions pinned to real files. It is told to ask when the goal is vague or when the answer would materially change the outcome, a storage engine, a library choice, the shape of an API. It is also told that a fully specified goal needs no questions, because interrogating a user who already said what they want is its own failure mode.

So the order is: read, ask, plan. The PRD sits third in that list, next to the plan, and only when it earns its place.

How it looks when the PRD is written

When there is a PRD, it does not live in the conversation. The planner emits it as a markdown block between two HTML comment markers, and the markers exist for one reason: so the block can be lifted out and saved to disk at .scratch/<slug>/PRD.md. The markers are not a state machine. Nothing gates on them.

What they buy is a file with a stable path. The revision pass reads the original goal plus that file, so a plan can be checked against the whole feature rather than against whatever the last few messages happened to mention.

# start from a goal, not a spec
ordewell plan "teams can share a saved query"

# the planner reads the repo, then asks
  How are saved queries stored today, per user or per
  workspace? And should sharing be a link, a copy, or
  a live reference?

# it proposes the plan; the spec, if you want one,
# is saved where the plan can re-read it
  .scratch/saved-query-sharing/PRD.md

A cheap model may write the PRD block and the plan in the same turn, which is fine, and the block is still captured. The document is a by-product of planning, not a phase you have to complete before planning may start.

Honest limits

The PRD is optional, and nothing enforces it. There is no check that a plan covers every user story. The story field is a place to put the link, and it is only as honest as the writing in it.
A PRD does not make a plan correct. It makes the intent legible. A legible wrong plan is still wrong, just easier to catch before you run it.
One-shot runs have nobody to ask. Where there is no user in the loop to answer questions, the planner is told to make the most reasonable assumption grounded in its research and record that assumption in the task description. A recorded assumption is weaker than an answer, and it is worse than a PRD you wrote yourself.
Spec drift is real. The PRD is a file on disk. If you change the goal and don't update the file, the plan will be revised against a stale spec and it will look perfectly self-consistent while being wrong.
It is not a process. No approvals, no sign-off states, no ticket sync. It is a markdown file and a saved path, and if you need more ceremony than that, use your existing tooling for it.

Source and design notes

The interesting part is that the markers are purely for saving, not for gating, and that the revision pass re-reads the spec rather than the conversation. The code behind that: the PRD store, the planner conversation and the planner prompts, all in github.com/ordewell/ordewell.

This post is cross-posted from ordewell.ai/prd-before-code.

How big should a task be in an agent plan

Ordewell — Sun, 27 Sep 2026 13:04:46 +0000

Everything you dislike about a run traces back to task size. A task that is too big burns an hour and fails at the end with a diff nobody can review. A task that is too small pays a full session to change one field. Size is also what decides how much can run at once, and what one failure costs.

Disclosure: I build Ordewell, so the rules below are the ones its planner is instructed to follow rather than a survey of the field. The tool is free and Apache 2.0.

The unit of size is one session

The natural limit is context. Each task gets a fresh agent session, so a task is sized to what one session can hold: the files it must read, the change it makes, and the check that proves it. Put more in and the session starts compacting, and the second half of the work happens without the first half in view.

That gives a test you can apply before anything runs. Could an engineer who has never seen the repo finish the task from the prompt plus the files it names? If the prompt has to say "then the same thing at the other eight call sites", it is too big.

Cut vertically, not by layer

The most common bad plan is a horizontal one. Take "let people export a report as CSV". A layer plan looks tidy: add the export types, then the serializer and the query, then wire it into the CLI command, then write the tests.

Every one of those depends on all the earlier ones, so nothing runs in parallel, and none of them produces anything you can look at. Task 2 cannot be reviewed alone because the thing it serializes does not exist yet. Task 3 is the first point at which the feature is real, and the diff you have to judge is the sum of three sessions.

A vertical slice is narrower and deeper. One task that takes the smallest real case end to end: export a two column report to a file, with a test that runs the command and reads the file back. Then a slice for escaping, then one for the wide case. Each is demoable, each has a check that means something, and the second and third can run together once the first landed. The test of a slice is that someone can run something and see the difference. If the only way to observe a task is to read its diff, it is a layer.

Small has a floor too

The other failure is twenty tasks that each change one file. Every task pays for a session, and the session repeats research an earlier task did and did not write down. The floor: if two adjacent tasks would touch the same function for the same reason, they are one task.

Put the enabling refactor first, as its own task

Some features are awkward because of the current shape of the code. The cheapest way through is a leading task that changes no behaviour and makes the real change easy: move the branch behind a function, extract the interface the new case needs, make the constant a parameter.

"Make the change easy, then make the easy change" works because a refactor has a crisp bar of its own, which is that the suite is still green. The feature slices also stay small enough to review, since they no longer carry a rewrite inside them. Dependent slices declare it as a dependency, so they start from a repository that already has the shape they need.

The exception: refactors that span the codebase

One class of work is the exception: a rename of a shared symbol, a column type change, anything whose blast radius is the whole repository. No narrow slice of it exists, since every slice touches the same wide set of files.

That work is sequenced as expand and contract. One task adds the new form beside the old and leaves both working. Then several migration tasks, each depending on that first one, move their share of the call sites over. A final task deletes the old form. The repository works at every boundary, so a failure in one migration batch costs one batch.

The graph you get is the dependency list you wrote

Which tasks run at once falls out of the dependency edges, so the edges have to mean something. Add an edge for genuine ordering: task B reads a module task A creates, or B runs the migration A ships. Do not add one because two tasks edit the same file. In an isolated run each task gets its own git worktree and lands as its own merge, so file overlap is a merge you handle at review time, not a reason to serialize.

There is one shared file trap worth knowing. Two parallel tasks that each append to the same changelog, registry or index list will race each other's merges even when they never touch the same source file. Give that edit to the final task, or order the two by a dependency.

The last edge is the one people forget. A plan where every task passed can still be a plan where the feature is not finished, because each task was verified against its own slice. The fix is a final task that depends on every other task and is judged by commands rather than judgement: the suite goes green, plus new tests written against the original goal and exercised end to end through the public interface.

make room, no behaviour change
  "make-export-easy"     deps: []

two slices, both after the layout
  "export-small-report"  deps: ["make-export-easy"]
  "export-escaping"      deps: ["make-export-easy"]

wide case, ordered so the shared file is appended once
  "export-wide-report"   deps: ["export-small-report"]

evidence, from commands and exit codes
  "verify-export"        deps: [all of the above]

Honest limits

The planner proposes, you decide. The slicing rules are instructions to a model, not a proof, and a model will sometimes hand you a layer plan anyway. This is why the plan is an editable artifact: read the graph before you approve it, and fix the fields that are wrong.
The dependency list is the failure surface. A wrong edge is either wasted wall clock or a task reading a repository without the work it assumed. Neither is caught by a check.
Sizing by context is a proxy. Whether a session really fits is discovered by running it. A task that looks small can still send an agent down a long exploration path.
More tasks means more merge work. Parallel slices land as separate merges you review. Isolation moves the pain from conflicts during the run to merges after it, and does not remove it.
The final task is only as good as the suite. A repository with no tests gets a standalone verification script instead of a framework bootstrapped during verification, so that check is only as strong as the script.

Source and design notes

The rules above are the planner's own instruction set, not a summary I wrote afterwards. The plan prompts and plan validation are in github.com/ordewell/ordewell.

Longer version of a page on my own site: ordewell.ai/task-sizing.

When one task fails, what happens to the rest of the plan

Ordewell — Sat, 26 Sep 2026 13:03:29 +0000

A plan is a graph, and a graph has a bad day when one node fails. The interesting part is not the failure. It is the three decisions that follow it: what the failed task keeps, whether the run keeps going, and what the tasks downstream are allowed to do. Getting the third one wrong is how a broken task becomes the foundation for the next six.

Disclosure: I build Ordewell, so this is the set of decisions it makes rather than a survey. The tool is free and Apache-2.0. The mechanics are worth arguing about whether or not you install it.

A failure is missing evidence, not a nonzero exit

Before anything can be decided, the failure has to be defined, and here it is defined by evidence: each task carries a completion marker, and the verdict engine looks for that marker in the runner's output when the session ends.

If the marker appears, the task passes, and the exit code is recorded as skipped with the reason written into the record, because there is no point pretending two checks were consulted. If the marker never appears, the task fails, whether the process exited 0 or exited with a code. A clean exit with no marker is not a pass.

  ✗ #b7c2 failed
    FAIL: agent exited cleanly but did not emit the
    completion marker

    completion_marker  failed   agent exited before Ordewell detected
                                the task completion marker
    exit_code          passed   agent exited cleanly (code 0)

Both checks stay on the record, which matters later. A verdict is evidence rather than a status label, and the difference between "the runner crashed" and "the runner finished and the marker never printed" decides whether you retry the task or fix the prompt.

Three decisions at the moment of failure

1. The failed task keeps its work. A task that fails verification has its worktree released with keep, so the tree stays on disk and stays inspectable, and the verdict plus the tail of the session's output are stored on the task. A failure you cannot open is a failure you cannot diagnose.

2. The run stops starting new work. The orchestrator sets itself back to not running and the plan returns to approved, so the scheduler stops handing out tasks. The plan is not cancelled: tasks already in a session finish and produce their own verdicts. What stops is the fan-out. A run that keeps dispatching after a failure is building on a base it knows is wrong.

3. Dependents park. A task that declared the failed one as a dependency is moved to blocked. There is a second guard behind it: a task whose dependency is failed is not ready even if its own status still says pending. Two guards, because a dependent must never start from a base missing work it was told it could rely on.

Why dependents wait instead of proceeding

A dependent session is handed the tail of its direct dependencies' output, and in an isolated run its worktree is cut from the integration branch. So "dependency met" means the work is completed and landed, not merely attempted.

Picture the alternative. Task 3 fails because its change never landed. Tasks 4 through 9 start anyway, read a repository without task 3's work, and produce six plausible diffs. Every one of them passes verification, because every one did what its prompt asked. You now own a merge problem with six authors and one root cause. Parking the graph at the failure is what keeps the blast radius at one task.

Getting back on the horse

Once the run has halted, you have four moves, for four different situations.

Retry is for a failure that had nothing to do with the task's content: a flaky harness, a rate limit, a session that died. It clears the verdict and the output summary, returns the task to pending, releases the dependents parked on it, and drops the failed attempt's worktree, because a retry starts from the integration tip, which now holds what its predecessors landed.

Re-arm is for a failure that was the task's fault: the prompt was ambiguous, or the model or mode was wrong for the work. It is a plan edit rather than a control command, so it carries corrected fields in the same operation, and it releases the parked dependents too. It also pierces the planner lock on purpose, since re-arming a task the planner is normally forbidden to touch is the point of it.

Mark complete is for the case where the work is real and the evidence is not: the agent did the change and the marker never printed. It records a pass whose automatic checks are replaced by a single manual check saying no verification was performed.

Force start is for running one task now, readiness rules and dependencies aside, because you have read the repository yourself.

# the run halted at task 2
ordewell status

# fails: the task keeps its work, dependents park at blocked
ordewell run

# one task, not the plan: verdict cleared, dependents released
ordewell retry b7c2

# resume: completed tasks are not re-run
ordewell run

Honest limits

A retry is not a re-run. Completed tasks are not re-run on resume, so a retry costs one task and whatever was parked behind it. If the failure was the plan's fault, the same prompt produces the same failure, and that is a case for editing the plan.
Halt is not kill. A failure stops new work from starting. It does not stop a session already running. A parallel task mid-flight finishes and can land a change written against a repository where the failed task's work is absent.
Parking is recorded, not derived. Dependents are moved to blocked when the failure is recorded, with a readiness check behind it as a second guard. A dependency list edited after the failure is where the graph has to be right for the two guards to agree.
No checkpoint inside a task. Retry re-runs the whole session for that task, because the task boundary is the only checkpoint that exists. On a long task that is real work repeated, and each retry leaves another kept worktree behind for you to clean up.
Nothing escalates on its own. No automatic backoff, and no automatic switch to a different model after a failure. You can re-arm a task onto another runner, but you are the one choosing it.
Mark complete weakens the record. A manually passed task looks like a passed task in the counts. The check saying no verification was performed is only as honest as your reading of it.

Source and design notes

A plan that stops at the first task without evidence, and parks everything downstream of it, is a plan where one failure costs one task. The code behind that: the verdict engine, the scheduler, task state, and the repository at github.com/ordewell/ordewell.

This page lives at ordewell.ai/task-failure, next to the earlier pieces on verifying completion, editing a plan and why the planner is not the executor.