From 7739eaed7f8f3915437a8def198a6d0d7206dbc7 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Thu, 29 Oct 2026 10:24:04 +0000 Subject: [PATCH] Start subagents with a fresh context window, not a fork (#1341) * Tell skills to start subagents with a fresh context window Some Codex models fork the parent conversation when spawning a subagent, which inherits its context and defeats the point of a subagent. Co-Authored-By: Claude Opus 5.5 * Trim fresh-context line to one plain sentence Co-Authored-By: Claude Opus 5.5 * Add fresh-context subagent rule to repo standards Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .changeset/subagents-fresh-context.md | 5 +++++ CLAUDE.md | 2 ++ skills/engineering/code-review/SKILL.md | 2 +- skills/engineering/codebase-design/DESIGN-IT-TWICE.md | 2 +- skills/engineering/implement-spec/SKILL.md | 2 ++ skills/engineering/improve-codebase-architecture/SKILL.md | 2 +- skills/engineering/research/SKILL.md | 2 +- skills/engineering/wayfinder/SKILL.md | 2 +- skills/in-progress/chief-of-staff/SKILL.md | 2 +- skills/productivity/grilling/SKILL.md | 2 +- 10 files changed, 16 insertions(+), 7 deletions(-) create mode 100644 .changeset/subagents-fresh-context.md diff --git a/.changeset/subagents-fresh-context.md b/.changeset/subagents-fresh-context.md new file mode 100644 index 0000000..515bfe3 --- /dev/null +++ b/.changeset/subagents-fresh-context.md @@ -0,0 +1,5 @@ +--- +"mattpocock-skills": patch +--- + +Skills that dispatch subagents (`implement-spec`, `code-review`, `codebase-design`, `improve-codebase-architecture`, `wayfinder`, `research`, `grilling`, `chief-of-staff`) now say to start each one with a fresh context window rather than forking the current conversation, which some harnesses (Codex) do by default and which throws away the clean context a subagent exists for. diff --git a/CLAUDE.md b/CLAUDE.md index fc5db87..cc3dbb3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,6 +24,8 @@ To (re)link every skill outside `deprecated/` and `misc/` into the local harness No em-dashes anywhere in this repo's prose (`SKILL.md` files, docs, `README.md`, `CHANGELOG.md`, ADRs, changesets, code comments). Where a sentence reaches for one, rewrite it instead with a comma, colon, period, parentheses, or a conjunction, whichever the sentence actually wants; never do a blind character substitution. +Every skill that dispatches a subagent says to start it with a fresh context window. Some harnesses (Codex, for one) fork the parent conversation by default, and a fork inherits the parent's context, which is what the subagent was meant to escape. + ## Agent skills ### Triage labels diff --git a/skills/engineering/code-review/SKILL.md b/skills/engineering/code-review/SKILL.md index 373a4f2..83183e0 100644 --- a/skills/engineering/code-review/SKILL.md +++ b/skills/engineering/code-review/SKILL.md @@ -8,7 +8,7 @@ Two-axis review of the diff between `HEAD` and a fixed point the user supplies: - **Standards**: does the code conform to this repo's documented coding standards? - **Spec**: does the code faithfully implement the originating issue / spec? -Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. +Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. Start every sub-agent with a fresh context window. The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`. diff --git a/skills/engineering/codebase-design/DESIGN-IT-TWICE.md b/skills/engineering/codebase-design/DESIGN-IT-TWICE.md index d099013..aebdc9f 100644 --- a/skills/engineering/codebase-design/DESIGN-IT-TWICE.md +++ b/skills/engineering/codebase-design/DESIGN-IT-TWICE.md @@ -18,7 +18,7 @@ Show this to the user, then immediately proceed to Step 2. The user reads and th ### 2. Spawn sub-agents -Spawn 3+ sub-agents in parallel. Each must produce a **radically different** interface for the deepened module. +Spawn 3+ sub-agents in parallel, each with a fresh context window. Each must produce a **radically different** interface for the deepened module. Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint: diff --git a/skills/engineering/implement-spec/SKILL.md b/skills/engineering/implement-spec/SKILL.md index 1839237..77bf59b 100644 --- a/skills/engineering/implement-spec/SKILL.md +++ b/skills/engineering/implement-spec/SKILL.md @@ -12,6 +12,8 @@ The goal is the entire spec implemented on a single **integration branch**, with The tickets are not a list of steps. They are a **task graph** with blocking relationships between them. This means there is always a **frontier** of tickets which are ready to be grabbed. +Start every subagent with a fresh context window. + Communication to and from subagents should be sparse. Communicate primarily through **context pointers**: to the spec, tickets, research notes, and previous commits. Don't duplicate information already available via pointers. **Implementer subagents** should be run in the background where possible for maximum concurrency. diff --git a/skills/engineering/improve-codebase-architecture/SKILL.md b/skills/engineering/improve-codebase-architecture/SKILL.md index 44cc7d3..f1eabb5 100644 --- a/skills/engineering/improve-codebase-architecture/SKILL.md +++ b/skills/engineering/improve-codebase-architecture/SKILL.md @@ -24,7 +24,7 @@ This command is _informed_ by the project's domain model and built on a shared d Read the project's domain glossary (`GLOSSARY.md`) and any ADRs in the area you're touching first. -Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction: +Then spawn a sub-agent with a fresh context window to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction: - Where does understanding one concept require bouncing between many small modules? - Where are modules **shallow**, with an interface nearly as complex as the implementation? diff --git a/skills/engineering/research/SKILL.md b/skills/engineering/research/SKILL.md index fecee97..ffc9eb8 100644 --- a/skills/engineering/research/SKILL.md +++ b/skills/engineering/research/SKILL.md @@ -3,7 +3,7 @@ name: research description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent. --- -Spin up a **background agent** to do the research, so you keep working while it reads. +Spin up a **background agent** to do the research, so you keep working while it reads. Start it with a fresh context window. Its job: diff --git a/skills/engineering/wayfinder/SKILL.md b/skills/engineering/wayfinder/SKILL.md index e28cf30..975d6bf 100644 --- a/skills/engineering/wayfinder/SKILL.md +++ b/skills/engineering/wayfinder/SKILL.md @@ -112,7 +112,7 @@ User invokes with a loose idea. 2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** (the way to the destination is already clear, the whole journey small enough for one session), you don't need a map. Stop and ask the user how they'd like to proceed. 3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**. 4. **Create the tickets you can specify now** as child issues of the map, then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Write cross-references in that pass too, with real ids: a placeholder `#` auto-links to an unrelated issue. Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog: the **Not yet specified** section. -5. **Fire the research subagents.** For each `research` ticket you just created, spin up a subagent that calls the Skill tool with "research" to resolve it in parallel, capturing its findings on a throwaway `research/` branch with a context pointer from the ticket. Push the branch but open no PR: it is never merged. +5. **Fire the research subagents.** For each `research` ticket you just created, spin up a subagent with a fresh context window that calls the Skill tool with "research" to resolve it in parallel, capturing its findings on a throwaway `research/` branch with a context pointer from the ticket. Push the branch but open no PR: it is never merged. 6. Stop: charting is one session's work; it hand-resolves nothing. ### Work through the map diff --git a/skills/in-progress/chief-of-staff/SKILL.md b/skills/in-progress/chief-of-staff/SKILL.md index 6dbdd4d..8ea0f46 100644 --- a/skills/in-progress/chief-of-staff/SKILL.md +++ b/skills/in-progress/chief-of-staff/SKILL.md @@ -19,7 +19,7 @@ Harness-permitting, you will suggest recurring schedules which can help in achie All work should be done in subagents. Protect your context window. -Use background agents so you can stay in active dialogue with the user. +Use background agents so you can stay in active dialogue with the user. Start every subagent with a fresh context window. Communication to and from subagents should be sparse. Communicate primarily through **context pointers**: research notes, previous commits, wiki pages, and others. Don't duplicate information already available via pointers. diff --git a/skills/productivity/grilling/SKILL.md b/skills/productivity/grilling/SKILL.md index df69d99..d2f09a1 100644 --- a/skills/productivity/grilling/SKILL.md +++ b/skills/productivity/grilling/SKILL.md @@ -25,6 +25,6 @@ Word each question so "yes" accepts your recommended answer. Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one. -Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait. +Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent with a fresh context window to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait. The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.