Agent workflow: worktrees and subagents (Phase 7)
Phase 7 of the Harness Engineering series: the process of working with coding agents, not the harness itself. The cornerstone is one thread per one task (not per project): otherwise context gets polluted, the task "completes" prematurely on overflow, and the history turns unreadable. The worktree workflow (create a worktree → run the agent inside → finish → delete), Plan mode for non-trivial work, the ExecPlan threshold for long tasks (cross-link, not a re-teach), subagents as the delegation boundary, and the "3 stumbles → the next task fixes the environment" rule. The artifact is a "Working with coding agents" section in CONTRIBUTING.md. Stack-agnostic.
IntermediateAI DevOps20 mingit worktree, CONTRIBUTING.md, Claude Code, subagents, ExecPlan
1
The cornerstone: one thread per task, not per project
Phase 7 isn't about the harness itself but about the process of working with the agent on top of it. The earlier phases built the environment; here we pin down HOW to work inside it and write it into CONTRIBUTING.md, so the process is shared rather than living 'in one person's head'.
The cornerstone rule: one thread (a chat session with the agent) = one task. Not one thread for the whole project, not 'I'll continue in the same chat since the agent is already up to speed'. Three reasons. First — context pollution: leftovers from the previous task (rejected approaches, unrelated files, old decisions) throw the agent off on the new one. Second — premature 'completion': when context overflows, the agent tends to declare the task done and cut the work short just to close the overflowing thread. Third — unreadable history: a thread mixing ten tasks can be neither reviewed nor handed to a new session. A fresh thread per task is the same context hygiene as in context engineering, only at the workflow level.
🟥 One thread per project
- Context pollution: tails of past tasks
- Overflow → "task done", work cut short
- 10-task history — impossible to review
- A new session reverse-engineers what was even happening
🟩 One thread per task
- Clean context for one goal
- Agent doesn't 'close' the task to unload the thread
- Readable history: one thread — one decision
- Finish → close; nothing carries over
The temptation 'I'll continue in the same chat, the agent is already up to speed' is exactly where pollution begins. 'Up to speed' means 'full of the previous task's context'. New task — new thread, always.
2
The worktree workflow: create → run → finish → delete
If each task is a separate thread, it also needs a separate working directory, or parallel tasks fight over one checkout. The solution is stack-independent — git worktree: several working copies of one repository, each on its own branch. The cycle is simple: create a worktree for the task → run the agent INSIDE it → finish the task → delete the worktree. The git commands are universal: identical for a Go, Python, or TypeScript project — not tied to any one language's tooling.
The key hazard is commits leaking into main. An agent (or subagent) run inside a worktree must check `pwd` and the current branch before committing, and use paths relative to that worktree's CWD. Otherwise an absolute path or a forgotten `cd` carries the changes and the commit into the main branch — exactly what the worktree was set up to prevent. This rule goes straight into CONTRIBUTING.md as a mandatory item for every agent task.
Create worktree + branch for the task
Run the agent INSIDE the worktree
Before commit: pwd + branch + paths from CWD
Finish the task, merge the branch
Delete the worktree — clean
# Worktree-воркфлоу — команды git универсальны (любой стек) / stack-agnostic
# 1. Создать worktree под задачу на новой ветке / create a worktree on a new branch
git worktree add ../wt-<task-name> -b feature/<task-name>
# 2. Запустить агента ВНУТРИ этой директории / run the agent INSIDE this dir
cd ../wt-<task-name>
# ... агент работает здесь, на ветке feature/<task-name> ...
# 3. ОБЯЗАТЕЛЬНО перед коммитом / MANDATORY before committing:
pwd # подтверди, что ты в worktree, не в основном репо
git branch --show-current # подтверди ветку — НЕ main / NOT main
# пути в правках — относительно CWD worktree / paths relative to worktree CWD
# иначе коммит утечёт в main / else the commit leaks to main
# 4. Закончил → вернулся и удалил worktree / finish → remove the worktree
cd -
git worktree remove ../wt-<task-name>Deleting the worktree is part of the task, not 'I'll tidy up later'. Abandoned worktrees pile up, clutter `git worktree list`, and lure the next agent into someone's half-finished directory.
3
Plan mode and the ExecPlan threshold: how much to plan before starting
Before the agent starts writing code, turn on Plan mode for a non-trivial task: the agent first lays out a plan — which files it'll touch, what approach, what boundaries — and waits for your approval without editing anything. This cheaply catches a misunderstanding before the agent generates 200 lines in the wrong direction. When NOT to: a one-line bugfix, a local edit to a single function, a pinpoint refactor — there Plan mode only slows you down. The cue matches the sketch rule: a new feature, changes across more than one layer, or an integration with an external system — plan it; a one-liner — don't.
There's an upper threshold past which Plan mode is no longer enough. The series rule: a task bigger than one working day goes through an ExecPlan — a living plan file in the repo that holds the thread across session restarts. We do NOT re-teach the ExecPlan template here — that's its own phase. Remember the boundary: a short task — the normal loop; a non-trivial one — Plan mode before the start; a long one (>1 day) — an ExecPlan. For the template, sections, and protocol, go to the ExecPlan recipe (link below).
| Task size | What you turn on | Why |
|---|---|---|
| One-liner / single-function edit | Normal loop, no ceremony | Planning costs more than the fix |
| Non-trivial: feature, >1 layer, integration | Plan mode → approve → code | Catches a misread before 200 wrong lines |
| Long: > 1 working day | ExecPlan — a living plan file | Holds the thread across session restarts |
Plan mode and the ExecPlan don't compete — they sit at different horizons: Plan mode is approving the approach within one thread before starting; the ExecPlan is written memory that outlives the thread itself. A long task often uses both.
4
Subagents: the delegation boundary
A subagent is a child agent the main thread hands a bounded chunk of work to, with its OWN clean context, taking back only the result. It's the second parallelism mechanism after the worktree: a worktree isolates files, a subagent isolates context.
The boundary is simple. What goes to a subagent is work that's bounded, parallelizable, and has its own clean context: researching an unfamiliar piece of code ('how is auth wired here?'), writing tests for a finished module, bug triage (gather a repro and facts). The main thread isn't cluttered with a hundred files read — it gets a digest. What stays in the main thread is the task core and architectural decisions: what exactly we're building, what boundaries, what approach, what to merge. These can't be delegated — they are the thread of the task, and smearing them across child contexts is not allowed. Heuristic: if a step's output is a 'decision' (what to do), it stays in main; if the output is 'material' (facts, tests, a repro) for an already-made decision, it can go to a subagent.
✅ To a Subagent
- Researching unfamiliar code
- Writing tests for a finished module
- Bug triage: gather a repro and facts
- Bounded, parallelizable, own context
🛑 Stays in the Main thread
- The task core: what exactly we're building
- Architectural decisions and boundaries
- Choosing the approach, what to merge
- The task's thread — can't be delegated
A subagent working in a worktree inherits the same rule: check pwd and the branch before committing, paths relative to the worktree CWD. A child context easily 'forgets' where it is and drops a commit into main on the parent's behalf.
5
The 3-stumbles rule: the next task fixes the environment
The last workflow rule is the most counter-intuitive. If the agent stumbles on the same thing three times in a row (confuses the same path, re-breaks one invariant, re-asks what was already explained), the NEXT task is not 'fix the bug again' but 'fix the environment'. That is: add to the docs, install a linter, create a skill or a lesson that won't let the agent stumble a fourth time.
This is the same principle as the lessons-ledger: the agent fixes its own environment, and a recurring correction hardens into part of the harness instead of staying a manual fix over and over. The difference is the nature of the mistake: a deterministic one ('an across-layer import again') is better turned into a barrier — a linter/check; a non-deterministic one (taste, contextual choice) goes into the lessons-ledger as a written lesson. CONTRIBUTING.md pins the trigger itself — '3 times → change the environment, not the code' — while where exactly the lesson hardens is decided by the lessons-ledger recipe (link below). The line: fixing the bug from scratch every time is working AGAINST the harness; hardening the lesson once is working FOR it.
The agent stumbled 3× on the same thing — what to do
Deterministic (path, invariant) → a barrier: linter/check
Non-deterministic (taste, choice) → a lesson in the lessons-ledger
A docs gap → extend the docs / AGENTS.md
The '3 times → fix the environment' trigger is in CONTRIBUTING.md
Hand-fixing the same bug a 4th, 5th, 6th time
The count of '3' isn't magic but a threshold: one failure is chance, two a coincidence, three is a pattern — and a pattern is cheaper to close with the environment than to pay for it on every new task.
6
The artifact: a "Working with coding agents" section + what next
All five rules assemble into one artifact — a "Working with coding agents" section in CONTRIBUTING.md. It makes the workflow the team's shared property, not one person's habit: a new member reads it at onboarding and immediately works with agents by the same rules. The section's contents: one thread per task; the worktree cycle with the mandatory pwd/branch check before committing; when Plan mode versus when an ExecPlan; the subagent delegation boundary; the 3-stumbles rule. The Phase 7 Definition of Done: the section exists in CONTRIBUTING.md, the team has read it, and it's part of onboarding.
Where Phase 7 sits and what's next. This phase is about process (how to work with the agent), whereas phases 2–5 were about the harness itself (ExecPlan, barriers, GC, the lessons-ledger). The series finale is Phase 8: a template repo and the golden path, where the whole assembled harness and this workflow are packaged into a starter template so a new project comes up along a paved road. Links to the next phase and the series hub are below.
The "Working with coding agents" section in CONTRIBUTING.md
One thread = one task
Worktree cycle + pwd/branch check before commit
When Plan mode, when an ExecPlan (>1 day)
The subagent delegation boundary
The "3 stumbles → fix the environment" rule
The team has read it; the section is part of onboarding
CONTRIBUTING.md is for humans (team onboarding), AGENTS.md is for the agent (its working instructions). Don't dump the workflow into one file: the 'one thread per task' rule is addressed to the human who opens that thread.
Result
Phase 7 is assembled as a process, not as code: the cornerstone rule is one thread per one task (against context pollution, premature 'completion', and unreadable history), the worktree cycle 'create → run the agent inside → finish → delete' with stack-agnostic git commands and a mandatory pwd/branch check before committing (else a leak into main), Plan mode for non-trivial work and the ExecPlan threshold for long tasks (>1 day, cross-link, not a re-teach), subagents as the delegation boundary (material to a subagent, decisions in the Main thread), and the '3 stumbles → the next task fixes the environment' rule (the same principle as the lessons-ledger). All of it is written as a "Working with coding agents" section in CONTRIBUTING.md, read by the team, and built into onboarding. Next — Phase 8: a template repo and the golden path.