[{"data":1,"prerenderedAt":2074},["ShallowReactive",2],{"docs:\u002Forchestration":3},{"id":4,"title":5,"accent":6,"body":7,"description":2034,"estReadTime":2035,"extension":2036,"eyebrow":2037,"icon":2038,"intro":2039,"lastUpdated":2039,"meta":2040,"navigation":288,"next":2041,"path":2044,"prev":2045,"review":2039,"seo":2048,"stem":6,"tocItems":2062,"__hash__":2073},"docs\u002Forchestration.md","Orchestration","orchestration",{"type":8,"value":9,"toc":2006},"minimark",[10,19,76,194,405,866,940,1389,1672,1757,1927,2002],[11,12,13,14,18],"p",{},"Most of this guide assumes one Claude, one session, one working directory. That model works for 90% of what you'll do. Orchestration is about the other 10% — work that's either too big for one context window, too parallel to be sequential, or too repetitive to babysit. The tools here (subagents, worktrees, Agent Teams, AGENTS.md) don't make Claude smarter. They let you run ",[15,16,17],"em",{},"more of it at once"," without the outputs colliding.",[20,21,24,27,56,64,69],"docs-section",{"id":22,"title":23},"when","When to Scale Up",[11,25,26],{},"Scaling up adds real cost: more tokens, more coordination overhead, more places for state to drift. Don't reach for it until one of these signals shows up.",[28,29,30,38,44,50],"ul",{},[31,32,33,37],"li",{},[34,35,36],"strong",{},"Your context hits 70% before you've written code."," Exploration alone is filling the window. Push exploration into a subagent so only the summary lands in your main session.",[31,39,40,43],{},[34,41,42],{},"The task has 2+ independent streams."," \"Build the API and the UI in parallel\" or \"migrate 8 files with the same refactor.\" Sequential execution leaves real time on the table.",[31,45,46,49],{},[34,47,48],{},"You're running the same motion repeatedly."," Five bug fixes this afternoon? That's a team-of-implementers problem, not a single-session problem.",[31,51,52,55],{},[34,53,54],{},"You need a second opinion you trust."," A reviewer subagent that can't see your main context will catch things you and your main Claude both missed.",[57,58,61],"docs-callout",{"title":59,"variant":60},"The anti-signal","warning",[11,62,63],{},"If the work is inherently sequential — each step needs the previous step's output — parallelism buys you nothing and costs you 2-3× tokens. A database migration that runs schema → data → verification is not an orchestration problem. It's a workflow problem. Solve it in one session with checkpoints.",[65,66,68],"h3",{"id":67},"the-2-minute-test","The 2-minute test",[11,70,71,72,75],{},"Before spawning anything, ask: ",[15,73,74],{},"\"Could I describe the sub-task in a self-contained prompt that doesn't reference my current conversation?\""," If yes, a subagent (or a parallel session) works. If you'd need to paste your last 15 turns as preamble, it's not independent enough — stay in one session.",[20,77,80,83,170,176],{"id":78,"title":79},"tiers","The 3 Tiers",[11,81,82],{},"Every orchestration setup lands in one of three tiers. Pick the lowest tier that solves your problem — complexity compounds fast above tier 1.",[84,85,86,105],"table",{},[87,88,89],"thead",{},[90,91,92,96,99,102],"tr",{},[93,94,95],"th",{},"Tier",[93,97,98],{},"Shape",[93,100,101],{},"You reach for it when",[93,103,104],{},"Cost",[106,107,108,130,150],"tbody",{},[90,109,110,116,124,127],{},[111,112,113],"td",{},[34,114,115],{},"1 — Subagents",[111,117,118,119,123],{},"Main Claude delegates to named agents via the ",[120,121,122],"code",{},"Task"," tool. Same session, fresh context per call.",[111,125,126],{},"Exploration, review, research, parallel classification tasks.",[111,128,129],{},"1–3× tokens, seconds of latency.",[90,131,132,137,144,147],{},[111,133,134],{},[34,135,136],{},"2 — Agent Teams",[111,138,139,140,143],{},"Multiple Claude sessions (often in separate worktrees) coordinated by an ",[120,141,142],{},"AGENTS.md"," and shared state on disk.",[111,145,146],{},"Parallel feature work, long-running refactors, conductor-style human-in-the-loop.",[111,148,149],{},"3–10× tokens, minutes to hours.",[90,151,152,157,164,167],{},[111,153,154],{},[34,155,156],{},"3 — External orchestrator",[111,158,159,160,163],{},"A program (Claude Agent SDK, LangGraph, CrewAI, n8n, etc.) spawns and routes Claude calls. No ",[120,161,162],{},"claude"," CLI in the hot path.",[111,165,166],{},"Production agent systems, user-facing agents, scheduled pipelines.",[111,168,169],{},"Whatever your infra costs; Claude Code is no longer involved.",[11,171,172,173,175],{},"The most common mistake is skipping from tier 1 to tier 3 because \"proper orchestration means a framework.\" It almost never does. A well-designed tier-2 team with a good ",[120,174,142],{}," handles 80% of what people build frameworks for.",[57,177,180],{"title":178,"variant":179},"Where each tier lives in this guide","info",[11,181,182,183,188,189,193],{},"Tier 1 (subagents) is covered in ",[184,185,187],"a",{"href":186},"\u002Fextensions#subagents","Extensions → Subagents",". Tier 2 (Agent Teams) is this section's main event. Tier 3 lives at the bottom — ",[184,190,192],{"href":191},"#external","External Orchestrators"," — because it's a different product category.",[20,195,198,201,215,218,371,386,390],{"id":196,"title":197},"graduation","Subagents → Teams",[11,199,200],{},"Tier 1 has a ceiling. You'll know you've hit it when you see these:",[28,202,203,206,209,212],{},[31,204,205],{},"Your main session is spending 30%+ of its turns coordinating subagents instead of thinking about your problem.",[31,207,208],{},"Two subagents need to edit the same file and you're manually sequencing them.",[31,210,211],{},"You want a subagent to run for 20 minutes while you keep working — but subagents block the main session.",[31,213,214],{},"You need different agents to have different git branches open simultaneously.",[11,216,217],{},"That's the moment to graduate. Here's the minimum viable migration:",[219,220,226],"pre",{"className":221,"code":222,"filename":223,"language":224,"meta":225,"style":225},"language-bash shiki shiki-themes github-light","# 1. Give each agent its own worktree\ngit worktree add ..\u002Frepo-impl -b feat\u002Fauth-impl main\ngit worktree add ..\u002Frepo-review -b feat\u002Fauth-review main\n\n# 2. Start a Claude session in each, in separate terminals\n(cd ..\u002Frepo-impl && claude)\n(cd ..\u002Frepo-review && claude)\n\n# 3. Create shared state both can read\u002Fwrite\nmkdir -p .claude\u002Fstate\u002Ffeat-auth\n\n# 4. Point both at the same AGENTS.md (checked in at repo root)\n#    — see the AGENTS.md section below for the template\n","from subagent to team in 4 commands","bash","",[120,227,228,237,264,283,290,296,316,331,336,342,354,359,365],{"__ignoreMap":225},[229,230,233],"span",{"class":231,"line":232},"line",1,[229,234,236],{"class":235},"sAwPA","# 1. Give each agent its own worktree\n",[229,238,240,244,248,251,254,258,261],{"class":231,"line":239},2,[229,241,243],{"class":242},"s7eDp","git",[229,245,247],{"class":246},"sYBdl"," worktree",[229,249,250],{"class":246}," add",[229,252,253],{"class":246}," ..\u002Frepo-impl",[229,255,257],{"class":256},"sYu0t"," -b",[229,259,260],{"class":246}," feat\u002Fauth-impl",[229,262,263],{"class":246}," main\n",[229,265,267,269,271,273,276,278,281],{"class":231,"line":266},3,[229,268,243],{"class":242},[229,270,247],{"class":246},[229,272,250],{"class":246},[229,274,275],{"class":246}," ..\u002Frepo-review",[229,277,257],{"class":256},[229,279,280],{"class":246}," feat\u002Fauth-review",[229,282,263],{"class":246},[229,284,286],{"class":231,"line":285},4,[229,287,289],{"emptyLinePlaceholder":288},true,"\n",[229,291,293],{"class":231,"line":292},5,[229,294,295],{"class":235},"# 2. Start a Claude session in each, in separate terminals\n",[229,297,299,303,306,308,311,313],{"class":231,"line":298},6,[229,300,302],{"class":301},"sgsFI","(",[229,304,305],{"class":256},"cd",[229,307,253],{"class":246},[229,309,310],{"class":301}," && ",[229,312,162],{"class":242},[229,314,315],{"class":301},")\n",[229,317,319,321,323,325,327,329],{"class":231,"line":318},7,[229,320,302],{"class":301},[229,322,305],{"class":256},[229,324,275],{"class":246},[229,326,310],{"class":301},[229,328,162],{"class":242},[229,330,315],{"class":301},[229,332,334],{"class":231,"line":333},8,[229,335,289],{"emptyLinePlaceholder":288},[229,337,339],{"class":231,"line":338},9,[229,340,341],{"class":235},"# 3. Create shared state both can read\u002Fwrite\n",[229,343,345,348,351],{"class":231,"line":344},10,[229,346,347],{"class":242},"mkdir",[229,349,350],{"class":256}," -p",[229,352,353],{"class":246}," .claude\u002Fstate\u002Ffeat-auth\n",[229,355,357],{"class":231,"line":356},11,[229,358,289],{"emptyLinePlaceholder":288},[229,360,362],{"class":231,"line":361},12,[229,363,364],{"class":235},"# 4. Point both at the same AGENTS.md (checked in at repo root)\n",[229,366,368],{"class":231,"line":367},13,[229,369,370],{"class":235},"#    — see the AGENTS.md section below for the template\n",[11,372,373,374,377,378,381,382,385],{},"The key shift: tier 1 is ",[15,375,376],{},"one Claude talking to itself",", tier 2 is ",[15,379,380],{},"multiple Claudes talking through files on disk",". Shared state in ",[120,383,384],{},".claude\u002Fstate\u002F"," replaces the implicit shared context of a single session.",[65,387,389],{"id":388},"what-graduation-does-not-mean","What graduation does NOT mean",[28,391,392,395,398],{},[31,393,394],{},"You don't need a framework. Bash, git worktrees, and markdown files are enough.",[31,396,397],{},"You don't need a message bus. The filesystem is your message bus.",[31,399,400,401,404],{},"You don't need to abandon the main Claude. It stays as the ",[34,402,403],{},"conductor"," — the one you talk to — and it spawns or instructs the others.",[20,406,409,416,420,573,577,610,614,820,838,842],{"id":407,"title":408},"worktrees","Git Worktrees",[11,410,411,412,415],{},"Git worktrees let one repo have multiple working directories, each on its own branch, sharing the same ",[120,413,414],{},".git"," store. They're the load-bearing primitive of tier 2 orchestration — every parallel agent gets its own directory, edits its own files, and commits to its own branch with zero contention.",[65,417,419],{"id":418},"the-60-second-tour","The 60-second tour",[219,421,424],{"className":221,"code":422,"filename":423,"language":224,"meta":225,"style":225},"# Create a new worktree on a new branch\ngit worktree add ..\u002Fmyproject-featA -b feat\u002FA main\n\n# Create one on an existing branch\ngit worktree add ..\u002Fmyproject-hotfix hotfix\u002Flogin\n\n# List everything\ngit worktree list\n#   \u002FUsers\u002Fyou\u002Fmyproject          abc123 [main]\n#   \u002FUsers\u002Fyou\u002Fmyproject-featA    def456 [feat\u002FA]\n#   \u002FUsers\u002Fyou\u002Fmyproject-hotfix   ghi789 [hotfix\u002Flogin]\n\n# Remove when done (deletes the dir, keeps the branch)\ngit worktree remove ..\u002Fmyproject-featA\n\n# Force-remove if the dir has uncommitted changes\ngit worktree remove --force ..\u002Fmyproject-featA\n\n# Prune stale entries (after manual rm -rf, etc.)\ngit worktree prune\n","essential worktree commands",[120,425,426,431,449,453,458,472,476,481,490,495,500,505,509,514,527,532,538,552,557,563],{"__ignoreMap":225},[229,427,428],{"class":231,"line":232},[229,429,430],{"class":235},"# Create a new worktree on a new branch\n",[229,432,433,435,437,439,442,444,447],{"class":231,"line":239},[229,434,243],{"class":242},[229,436,247],{"class":246},[229,438,250],{"class":246},[229,440,441],{"class":246}," ..\u002Fmyproject-featA",[229,443,257],{"class":256},[229,445,446],{"class":246}," feat\u002FA",[229,448,263],{"class":246},[229,450,451],{"class":231,"line":266},[229,452,289],{"emptyLinePlaceholder":288},[229,454,455],{"class":231,"line":285},[229,456,457],{"class":235},"# Create one on an existing branch\n",[229,459,460,462,464,466,469],{"class":231,"line":292},[229,461,243],{"class":242},[229,463,247],{"class":246},[229,465,250],{"class":246},[229,467,468],{"class":246}," ..\u002Fmyproject-hotfix",[229,470,471],{"class":246}," hotfix\u002Flogin\n",[229,473,474],{"class":231,"line":298},[229,475,289],{"emptyLinePlaceholder":288},[229,477,478],{"class":231,"line":318},[229,479,480],{"class":235},"# List everything\n",[229,482,483,485,487],{"class":231,"line":333},[229,484,243],{"class":242},[229,486,247],{"class":246},[229,488,489],{"class":246}," list\n",[229,491,492],{"class":231,"line":338},[229,493,494],{"class":235},"#   \u002FUsers\u002Fyou\u002Fmyproject          abc123 [main]\n",[229,496,497],{"class":231,"line":344},[229,498,499],{"class":235},"#   \u002FUsers\u002Fyou\u002Fmyproject-featA    def456 [feat\u002FA]\n",[229,501,502],{"class":231,"line":356},[229,503,504],{"class":235},"#   \u002FUsers\u002Fyou\u002Fmyproject-hotfix   ghi789 [hotfix\u002Flogin]\n",[229,506,507],{"class":231,"line":361},[229,508,289],{"emptyLinePlaceholder":288},[229,510,511],{"class":231,"line":367},[229,512,513],{"class":235},"# Remove when done (deletes the dir, keeps the branch)\n",[229,515,517,519,521,524],{"class":231,"line":516},14,[229,518,243],{"class":242},[229,520,247],{"class":246},[229,522,523],{"class":246}," remove",[229,525,526],{"class":246}," ..\u002Fmyproject-featA\n",[229,528,530],{"class":231,"line":529},15,[229,531,289],{"emptyLinePlaceholder":288},[229,533,535],{"class":231,"line":534},16,[229,536,537],{"class":235},"# Force-remove if the dir has uncommitted changes\n",[229,539,541,543,545,547,550],{"class":231,"line":540},17,[229,542,243],{"class":242},[229,544,247],{"class":246},[229,546,523],{"class":246},[229,548,549],{"class":256}," --force",[229,551,526],{"class":246},[229,553,555],{"class":231,"line":554},18,[229,556,289],{"emptyLinePlaceholder":288},[229,558,560],{"class":231,"line":559},19,[229,561,562],{"class":235},"# Prune stale entries (after manual rm -rf, etc.)\n",[229,564,566,568,570],{"class":231,"line":565},20,[229,567,243],{"class":242},[229,569,247],{"class":246},[229,571,572],{"class":246}," prune\n",[65,574,576],{"id":575},"why-this-matters-for-claude","Why this matters for Claude",[28,578,579,589,599],{},[31,580,581,584,585,588],{},[34,582,583],{},"No write contention."," Two Claudes editing ",[120,586,587],{},"src\u002Fauth.ts"," in the same directory is a race condition. In separate worktrees, it's two branches that merge cleanly at the end.",[31,590,591,594,595,598],{},[34,592,593],{},"Independent state."," Each directory has its own ",[120,596,597],{},"node_modules",", its own build output, its own terminal history. A failed migration in worktree A doesn't corrupt worktree B.",[31,600,601,604,605,609],{},[34,602,603],{},"Cheap branching experiments."," Run three different approaches to the same task, keep the winner, delete the rest. This is the ",[184,606,608],{"href":607},"\u002Fworkflows#best-of-n","Best of N"," pattern.",[65,611,613],{"id":612},"a-real-parallel-work-setup","A real parallel-work setup",[219,615,618],{"className":221,"code":616,"filename":617,"language":224,"meta":225,"style":225},"# Main session stays in the primary checkout — this is the conductor\ncd ~\u002Fcode\u002Fmyapp\n\n# Spawn worker worktrees\ngit worktree add ..\u002Fmyapp-api      -b feat\u002Fbilling-api      main\ngit worktree add ..\u002Fmyapp-ui       -b feat\u002Fbilling-ui       main\ngit worktree add ..\u002Fmyapp-migrate  -b feat\u002Fbilling-migrate  main\n\n# Open one terminal per worker, start Claude in each\n# Terminal 1:  cd ..\u002Fmyapp-api     && claude\n# Terminal 2:  cd ..\u002Fmyapp-ui      && claude\n# Terminal 3:  cd ..\u002Fmyapp-migrate && claude\n\n# When all three branches are green, merge them in the main checkout\ncd ~\u002Fcode\u002Fmyapp\ngit merge --no-ff feat\u002Fbilling-migrate\ngit merge --no-ff feat\u002Fbilling-api\ngit merge --no-ff feat\u002Fbilling-ui\n\n# Clean up\ngit worktree remove ..\u002Fmyapp-api\ngit worktree remove ..\u002Fmyapp-ui\ngit worktree remove ..\u002Fmyapp-migrate\n","parallel feature work",[120,619,620,625,632,636,641,661,681,701,705,710,715,720,725,729,734,740,753,764,775,779,784,796,808],{"__ignoreMap":225},[229,621,622],{"class":231,"line":232},[229,623,624],{"class":235},"# Main session stays in the primary checkout — this is the conductor\n",[229,626,627,629],{"class":231,"line":239},[229,628,305],{"class":256},[229,630,631],{"class":246}," ~\u002Fcode\u002Fmyapp\n",[229,633,634],{"class":231,"line":266},[229,635,289],{"emptyLinePlaceholder":288},[229,637,638],{"class":231,"line":285},[229,639,640],{"class":235},"# Spawn worker worktrees\n",[229,642,643,645,647,649,652,655,658],{"class":231,"line":292},[229,644,243],{"class":242},[229,646,247],{"class":246},[229,648,250],{"class":246},[229,650,651],{"class":246}," ..\u002Fmyapp-api",[229,653,654],{"class":256},"      -b",[229,656,657],{"class":246}," feat\u002Fbilling-api",[229,659,660],{"class":246},"      main\n",[229,662,663,665,667,669,672,675,678],{"class":231,"line":298},[229,664,243],{"class":242},[229,666,247],{"class":246},[229,668,250],{"class":246},[229,670,671],{"class":246}," ..\u002Fmyapp-ui",[229,673,674],{"class":256},"       -b",[229,676,677],{"class":246}," feat\u002Fbilling-ui",[229,679,680],{"class":246},"       main\n",[229,682,683,685,687,689,692,695,698],{"class":231,"line":318},[229,684,243],{"class":242},[229,686,247],{"class":246},[229,688,250],{"class":246},[229,690,691],{"class":246}," ..\u002Fmyapp-migrate",[229,693,694],{"class":256},"  -b",[229,696,697],{"class":246}," feat\u002Fbilling-migrate",[229,699,700],{"class":246},"  main\n",[229,702,703],{"class":231,"line":333},[229,704,289],{"emptyLinePlaceholder":288},[229,706,707],{"class":231,"line":338},[229,708,709],{"class":235},"# Open one terminal per worker, start Claude in each\n",[229,711,712],{"class":231,"line":344},[229,713,714],{"class":235},"# Terminal 1:  cd ..\u002Fmyapp-api     && claude\n",[229,716,717],{"class":231,"line":356},[229,718,719],{"class":235},"# Terminal 2:  cd ..\u002Fmyapp-ui      && claude\n",[229,721,722],{"class":231,"line":361},[229,723,724],{"class":235},"# Terminal 3:  cd ..\u002Fmyapp-migrate && claude\n",[229,726,727],{"class":231,"line":367},[229,728,289],{"emptyLinePlaceholder":288},[229,730,731],{"class":231,"line":516},[229,732,733],{"class":235},"# When all three branches are green, merge them in the main checkout\n",[229,735,736,738],{"class":231,"line":529},[229,737,305],{"class":256},[229,739,631],{"class":246},[229,741,742,744,747,750],{"class":231,"line":534},[229,743,243],{"class":242},[229,745,746],{"class":246}," merge",[229,748,749],{"class":256}," --no-ff",[229,751,752],{"class":246}," feat\u002Fbilling-migrate\n",[229,754,755,757,759,761],{"class":231,"line":540},[229,756,243],{"class":242},[229,758,746],{"class":246},[229,760,749],{"class":256},[229,762,763],{"class":246}," feat\u002Fbilling-api\n",[229,765,766,768,770,772],{"class":231,"line":554},[229,767,243],{"class":242},[229,769,746],{"class":246},[229,771,749],{"class":256},[229,773,774],{"class":246}," feat\u002Fbilling-ui\n",[229,776,777],{"class":231,"line":559},[229,778,289],{"emptyLinePlaceholder":288},[229,780,781],{"class":231,"line":565},[229,782,783],{"class":235},"# Clean up\n",[229,785,787,789,791,793],{"class":231,"line":786},21,[229,788,243],{"class":242},[229,790,247],{"class":246},[229,792,523],{"class":246},[229,794,795],{"class":246}," ..\u002Fmyapp-api\n",[229,797,799,801,803,805],{"class":231,"line":798},22,[229,800,243],{"class":242},[229,802,247],{"class":246},[229,804,523],{"class":246},[229,806,807],{"class":246}," ..\u002Fmyapp-ui\n",[229,809,811,813,815,817],{"class":231,"line":810},23,[229,812,243],{"class":242},[229,814,247],{"class":246},[229,816,523],{"class":246},[229,818,819],{"class":246}," ..\u002Fmyapp-migrate\n",[57,821,824],{"title":822,"variant":823},"One CLAUDE.md, many worktrees","tip",[11,825,826,827,830,831,833,834,837],{},"Every worktree shares the repo's ",[120,828,829],{},"CLAUDE.md"," via the same git objects — edit it once, every agent sees the update next turn. The only per-worktree state you need to think about is ",[120,832,384],{}," (if you scope it per-branch) and ",[120,835,836],{},".env"," files (which aren't checked in).",[65,839,841],{"id":840},"pitfalls","Pitfalls",[28,843,844,850,856],{},[31,845,846,849],{},[34,847,848],{},"Submodules and LFS"," can behave oddly across worktrees. Test once before committing to this workflow in a repo that uses them.",[31,851,852,855],{},[34,853,854],{},"Tooling that hardcodes paths"," (some node scripts, IDE caches) can point back at the main checkout. Prefer relative paths in scripts.",[31,857,858,861,862,865],{},[34,859,860],{},"Leftover worktrees"," accumulate. Run ",[120,863,864],{},"git worktree list"," weekly; delete anything older than a week you don't recognize.",[20,867,870,877,881,884,893,902,906,912,919,927],{"id":868,"title":869},"models","Conductor vs Orchestrator",[11,871,872,873,876],{},"Two coordination models, picked by ",[15,874,875],{},"who decides what runs next",".",[65,878,880],{"id":879},"conductor-model-human-driven","Conductor model (human-driven)",[11,882,883],{},"You're the conductor. You start agent A, read its output, decide whether to run agent B or repair agent A. The main Claude session is just one of your hands.",[219,885,891],{"className":886,"code":888,"filename":889,"language":890,"meta":225},[887],"language-text","You (to main Claude): Review the plan doc at .claude\u002Fstate\u002Fplans\u002Fauth.md\n                      and tell me if it's ready for implementation.\nMain Claude:          LGTM, but step 3 is ambiguous — should the JWT expire\n                      in 15m or 24h?\nYou:                  15m. Update the plan.\nYou (switch terminal, in ..\u002Frepo-impl): Implement step 1 of the plan\n                                         at .claude\u002Fstate\u002Fplans\u002Fauth.md.\n","a conductor session","text",[120,892,888],{"__ignoreMap":225},[11,894,895,898,899,901],{},[34,896,897],{},"Pick this when:"," the work is novel, the stakes are medium-to-high, or your ",[120,900,142],{}," is still evolving. You catch drift in real time.",[65,903,905],{"id":904},"orchestrator-model-claude-driven","Orchestrator model (Claude-driven)",[11,907,908,909,911],{},"The main Claude is the orchestrator. Given a goal, it reads ",[120,910,142],{},", spawns the right subagents in the right order, and only comes back to you for approvals or when it's stuck.",[219,913,917],{"className":914,"code":915,"filename":916,"language":890,"meta":225},[887],"You: Ship feature \"password reset flow\" end-to-end. Follow AGENTS.md.\n     Stop and ask me only if:\n       - a plan step seems wrong\n       - a test fails 3 times in a row\n       - you need a secret or external access I haven't provided\nMain Claude: [spawns planner → reviews plan with you → spawns implementer\n              → spawns tester → spawns reviewer → reports]\n","an orchestrator prompt",[120,918,915],{"__ignoreMap":225},[11,920,921,923,924,926],{},[34,922,897],{}," you've shipped this shape of feature 5+ times, ",[120,925,142],{}," is stable, and the cost of an extra round-trip is high (e.g. you're AFK for lunch).",[57,928,930],{"title":929,"variant":179},"You don't pick one forever",[11,931,932,933,935,936,939],{},"Same repo, same team — you'll conductor the novel stuff and orchestrate the routine stuff. The ",[120,934,142],{}," you write for orchestrator-mode is what you slowly build up ",[15,937,938],{},"while"," you're in conductor-mode. That's the compound-learning loop.",[20,941,944,947,951,958,962,1172,1176,1353,1357,1360,1367],{"id":942,"title":943},"teams","Agent Teams Deep Dive",[11,945,946],{},"Extensions introduced the idea. This section shows a complete, minimal team you can copy.",[65,948,950],{"id":949},"the-four-files","The four files",[219,952,956],{"className":953,"code":954,"filename":955,"language":890,"meta":225},[887],"repo\u002F\n├── AGENTS.md                       # the team charter\n├── CLAUDE.md                       # the repo's shared context\n├── .claude\u002F\n│   ├── agents\u002F\n│   │   ├── planner.md\n│   │   ├── implementer.md\n│   │   ├── reviewer.md\n│   │   └── tester.md\n│   └── state\u002F                      # agents read\u002Fwrite here\n│       ├── plans\u002F\n│       ├── reviews\u002F\n│       └── runs\u002F\n","team layout",[120,957,954],{"__ignoreMap":225},[65,959,961],{"id":960},"the-agentsmd","The AGENTS.md",[219,963,967],{"className":964,"code":965,"filename":142,"language":966,"meta":225,"style":225},"language-markdown shiki shiki-themes github-light","# Feature-work Agent Team\n\nFour roles coordinate to ship one feature at a time. The main Claude session\nis the orchestrator; everyone else is a subagent or a parallel worktree.\n\n## Roles\n\n| Role         | Tools                       | Model  | Can edit source? |\n| ------------ | --------------------------- | ------ | ---------------- |\n| planner      | Read, Grep, Glob, Write     | opus   | no (plans only)  |\n| implementer  | Read, Edit, Write, Bash     | sonnet | yes              |\n| tester       | Read, Edit, Write, Bash     | sonnet | only `**\u002F*.test.*` |\n| reviewer     | Read, Grep, Glob, Bash(git) | opus   | no               |\n\n## Ordering\n\nplanner → implementer → tester → reviewer → orchestrator (ship or repair).\n\n## Shared state\n\n- Plans:   `.claude\u002Fstate\u002Fplans\u002F\u003Cfeature>.md`\n- Reviews: `.claude\u002Fstate\u002Freviews\u002F\u003Cfeature>.md`\n- Runs:    `.claude\u002Fstate\u002Fruns\u002F\u003Cfeature>\u002F\u003Ciso-timestamp>.md`\n\nEvery role ends its turn by writing a summary to the appropriate file.\n\n## Rules of engagement\n\n- The planner NEVER writes code. If it catches itself, stop and write a plan step.\n- The reviewer NEVER edits. Verdicts go to `state\u002Freviews\u002F`.\n- The tester edits only test files. If a test requires a source change,\n  hand back to the orchestrator with a note.\n- Any role that spends >5 turns without progress stops and reports blocker.\n","markdown",[120,968,969,975,979,984,989,993,998,1002,1007,1012,1017,1022,1033,1038,1042,1047,1051,1056,1060,1065,1069,1081,1091,1101,1106,1112,1117,1123,1128,1136,1150,1158,1164],{"__ignoreMap":225},[229,970,971],{"class":231,"line":232},[229,972,974],{"class":973},"surfw","# Feature-work Agent Team\n",[229,976,977],{"class":231,"line":239},[229,978,289],{"emptyLinePlaceholder":288},[229,980,981],{"class":231,"line":266},[229,982,983],{"class":301},"Four roles coordinate to ship one feature at a time. The main Claude session\n",[229,985,986],{"class":231,"line":285},[229,987,988],{"class":301},"is the orchestrator; everyone else is a subagent or a parallel worktree.\n",[229,990,991],{"class":231,"line":292},[229,992,289],{"emptyLinePlaceholder":288},[229,994,995],{"class":231,"line":298},[229,996,997],{"class":973},"## Roles\n",[229,999,1000],{"class":231,"line":318},[229,1001,289],{"emptyLinePlaceholder":288},[229,1003,1004],{"class":231,"line":333},[229,1005,1006],{"class":301},"| Role         | Tools                       | Model  | Can edit source? |\n",[229,1008,1009],{"class":231,"line":338},[229,1010,1011],{"class":301},"| ------------ | --------------------------- | ------ | ---------------- |\n",[229,1013,1014],{"class":231,"line":344},[229,1015,1016],{"class":301},"| planner      | Read, Grep, Glob, Write     | opus   | no (plans only)  |\n",[229,1018,1019],{"class":231,"line":356},[229,1020,1021],{"class":301},"| implementer  | Read, Edit, Write, Bash     | sonnet | yes              |\n",[229,1023,1024,1027,1030],{"class":231,"line":361},[229,1025,1026],{"class":301},"| tester       | Read, Edit, Write, Bash     | sonnet | only ",[229,1028,1029],{"class":256},"`**\u002F*.test.*`",[229,1031,1032],{"class":301}," |\n",[229,1034,1035],{"class":231,"line":367},[229,1036,1037],{"class":301},"| reviewer     | Read, Grep, Glob, Bash(git) | opus   | no               |\n",[229,1039,1040],{"class":231,"line":516},[229,1041,289],{"emptyLinePlaceholder":288},[229,1043,1044],{"class":231,"line":529},[229,1045,1046],{"class":973},"## Ordering\n",[229,1048,1049],{"class":231,"line":534},[229,1050,289],{"emptyLinePlaceholder":288},[229,1052,1053],{"class":231,"line":540},[229,1054,1055],{"class":301},"planner → implementer → tester → reviewer → orchestrator (ship or repair).\n",[229,1057,1058],{"class":231,"line":554},[229,1059,289],{"emptyLinePlaceholder":288},[229,1061,1062],{"class":231,"line":559},[229,1063,1064],{"class":973},"## Shared state\n",[229,1066,1067],{"class":231,"line":565},[229,1068,289],{"emptyLinePlaceholder":288},[229,1070,1071,1075,1078],{"class":231,"line":786},[229,1072,1074],{"class":1073},"sqxcx","-",[229,1076,1077],{"class":301}," Plans:   ",[229,1079,1080],{"class":256},"`.claude\u002Fstate\u002Fplans\u002F\u003Cfeature>.md`\n",[229,1082,1083,1085,1088],{"class":231,"line":798},[229,1084,1074],{"class":1073},[229,1086,1087],{"class":301}," Reviews: ",[229,1089,1090],{"class":256},"`.claude\u002Fstate\u002Freviews\u002F\u003Cfeature>.md`\n",[229,1092,1093,1095,1098],{"class":231,"line":810},[229,1094,1074],{"class":1073},[229,1096,1097],{"class":301}," Runs:    ",[229,1099,1100],{"class":256},"`.claude\u002Fstate\u002Fruns\u002F\u003Cfeature>\u002F\u003Ciso-timestamp>.md`\n",[229,1102,1104],{"class":231,"line":1103},24,[229,1105,289],{"emptyLinePlaceholder":288},[229,1107,1109],{"class":231,"line":1108},25,[229,1110,1111],{"class":301},"Every role ends its turn by writing a summary to the appropriate file.\n",[229,1113,1115],{"class":231,"line":1114},26,[229,1116,289],{"emptyLinePlaceholder":288},[229,1118,1120],{"class":231,"line":1119},27,[229,1121,1122],{"class":973},"## Rules of engagement\n",[229,1124,1126],{"class":231,"line":1125},28,[229,1127,289],{"emptyLinePlaceholder":288},[229,1129,1131,1133],{"class":231,"line":1130},29,[229,1132,1074],{"class":1073},[229,1134,1135],{"class":301}," The planner NEVER writes code. If it catches itself, stop and write a plan step.\n",[229,1137,1139,1141,1144,1147],{"class":231,"line":1138},30,[229,1140,1074],{"class":1073},[229,1142,1143],{"class":301}," The reviewer NEVER edits. Verdicts go to ",[229,1145,1146],{"class":256},"`state\u002Freviews\u002F`",[229,1148,1149],{"class":301},".\n",[229,1151,1153,1155],{"class":231,"line":1152},31,[229,1154,1074],{"class":1073},[229,1156,1157],{"class":301}," The tester edits only test files. If a test requires a source change,\n",[229,1159,1161],{"class":231,"line":1160},32,[229,1162,1163],{"class":301},"  hand back to the orchestrator with a note.\n",[229,1165,1167,1169],{"class":231,"line":1166},33,[229,1168,1074],{"class":1073},[229,1170,1171],{"class":301}," Any role that spends >5 turns without progress stops and reports blocker.\n",[65,1173,1175],{"id":1174},"a-single-agent-file","A single agent file",[219,1177,1180],{"className":964,"code":1178,"filename":1179,"language":966,"meta":225,"style":225},"---\nname: implementer\ndescription: Use this agent to execute ONE step of a plan at `.claude\u002Fstate\u002Fplans\u002F\u003Cfeature>.md`. It edits source files, runs the test suite, and reports what changed.\ntools: Read, Edit, Write, Bash(npm test), Bash(git diff*)\nmodel: sonnet\n---\n\nYou are the implementer on a feature team. You receive a feature slug and a\nstep number. You execute exactly that step and no more.\n\n## Workflow\n\n1. Read `.claude\u002Fstate\u002Fplans\u002F\u003Cfeature>.md`. Find step \u003CN>.\n2. Implement it. Do not touch files outside the plan's scope.\n3. Run `npm test -- --related` (or the project's equivalent) until green.\n4. Append a run log to `.claude\u002Fstate\u002Fruns\u002F\u003Cfeature>\u002F\u003Ciso-timestamp>.md`\n   with the step number, files touched, and test results.\n5. Return a one-line summary to the orchestrator.\n\n## Rules\n\n- If step \u003CN> is ambiguous, STOP. Do not guess. Hand back with a question.\n- If tests fail 3× in a row, STOP. Report the failure and what you tried.\n- NEVER modify the plan file. If the plan is wrong, report it; don't fix it.\n",".claude\u002Fagents\u002Fimplementer.md",[120,1181,1182,1187,1199,1209,1219,1229,1233,1237,1242,1247,1251,1256,1260,1274,1282,1296,1306,1311,1319,1323,1328,1332,1339,1346],{"__ignoreMap":225},[229,1183,1184],{"class":231,"line":232},[229,1185,1186],{"class":301},"---\n",[229,1188,1189,1193,1196],{"class":231,"line":239},[229,1190,1192],{"class":1191},"shJU0","name",[229,1194,1195],{"class":301},": ",[229,1197,1198],{"class":246},"implementer\n",[229,1200,1201,1204,1206],{"class":231,"line":266},[229,1202,1203],{"class":1191},"description",[229,1205,1195],{"class":301},[229,1207,1208],{"class":246},"Use this agent to execute ONE step of a plan at `.claude\u002Fstate\u002Fplans\u002F\u003Cfeature>.md`. It edits source files, runs the test suite, and reports what changed.\n",[229,1210,1211,1214,1216],{"class":231,"line":285},[229,1212,1213],{"class":1191},"tools",[229,1215,1195],{"class":301},[229,1217,1218],{"class":246},"Read, Edit, Write, Bash(npm test), Bash(git diff*)\n",[229,1220,1221,1224,1226],{"class":231,"line":292},[229,1222,1223],{"class":1191},"model",[229,1225,1195],{"class":301},[229,1227,1228],{"class":246},"sonnet\n",[229,1230,1231],{"class":231,"line":298},[229,1232,1186],{"class":301},[229,1234,1235],{"class":231,"line":318},[229,1236,289],{"emptyLinePlaceholder":288},[229,1238,1239],{"class":231,"line":333},[229,1240,1241],{"class":301},"You are the implementer on a feature team. You receive a feature slug and a\n",[229,1243,1244],{"class":231,"line":338},[229,1245,1246],{"class":301},"step number. You execute exactly that step and no more.\n",[229,1248,1249],{"class":231,"line":344},[229,1250,289],{"emptyLinePlaceholder":288},[229,1252,1253],{"class":231,"line":356},[229,1254,1255],{"class":973},"## Workflow\n",[229,1257,1258],{"class":231,"line":361},[229,1259,289],{"emptyLinePlaceholder":288},[229,1261,1262,1265,1268,1271],{"class":231,"line":367},[229,1263,1264],{"class":1073},"1.",[229,1266,1267],{"class":301}," Read ",[229,1269,1270],{"class":256},"`.claude\u002Fstate\u002Fplans\u002F\u003Cfeature>.md`",[229,1272,1273],{"class":301},". Find step \u003CN>.\n",[229,1275,1276,1279],{"class":231,"line":516},[229,1277,1278],{"class":1073},"2.",[229,1280,1281],{"class":301}," Implement it. Do not touch files outside the plan's scope.\n",[229,1283,1284,1287,1290,1293],{"class":231,"line":529},[229,1285,1286],{"class":1073},"3.",[229,1288,1289],{"class":301}," Run ",[229,1291,1292],{"class":256},"`npm test -- --related`",[229,1294,1295],{"class":301}," (or the project's equivalent) until green.\n",[229,1297,1298,1301,1304],{"class":231,"line":534},[229,1299,1300],{"class":1073},"4.",[229,1302,1303],{"class":301}," Append a run log to ",[229,1305,1100],{"class":256},[229,1307,1308],{"class":231,"line":540},[229,1309,1310],{"class":301},"   with the step number, files touched, and test results.\n",[229,1312,1313,1316],{"class":231,"line":554},[229,1314,1315],{"class":1073},"5.",[229,1317,1318],{"class":301}," Return a one-line summary to the orchestrator.\n",[229,1320,1321],{"class":231,"line":559},[229,1322,289],{"emptyLinePlaceholder":288},[229,1324,1325],{"class":231,"line":565},[229,1326,1327],{"class":973},"## Rules\n",[229,1329,1330],{"class":231,"line":786},[229,1331,289],{"emptyLinePlaceholder":288},[229,1333,1334,1336],{"class":231,"line":798},[229,1335,1074],{"class":1073},[229,1337,1338],{"class":301}," If step \u003CN> is ambiguous, STOP. Do not guess. Hand back with a question.\n",[229,1340,1341,1343],{"class":231,"line":810},[229,1342,1074],{"class":1073},[229,1344,1345],{"class":301}," If tests fail 3× in a row, STOP. Report the failure and what you tried.\n",[229,1347,1348,1350],{"class":231,"line":1103},[229,1349,1074],{"class":1073},[229,1351,1352],{"class":301}," NEVER modify the plan file. If the plan is wrong, report it; don't fix it.\n",[65,1354,1356],{"id":1355},"running-the-team","Running the team",[11,1358,1359],{},"From the main Claude session in the primary worktree:",[219,1361,1365],{"className":1362,"code":1363,"filename":1364,"language":890,"meta":225},[887],"We're adding \"soft delete for user accounts.\" Run the team:\n\n1. Use the planner agent to turn this into a plan at\n   .claude\u002Fstate\u002Fplans\u002Fsoft-delete.md. Stop and show me when done.\n2. After I approve the plan, use the implementer agent for each step\n   in sequence.\n3. After implementation, use the tester agent to extend tests.\n4. Finally, use the reviewer agent to file a review.\n5. Report back with the review's verdict.\n","kicking off a run",[120,1366,1363],{"__ignoreMap":225},[57,1368,1370],{"title":1369,"variant":823},"Start with two roles",[11,1371,1372,1373,1376,1377,1380,1381,1384,1385,1388],{},"Four roles is the end state. Start with ",[15,1374,1375],{},"planner"," + ",[15,1378,1379],{},"implementer",". Add ",[15,1382,1383],{},"reviewer"," when you trip over the same bug twice. Add ",[15,1386,1387],{},"tester"," when coverage starts slipping. Don't build the whole menagerie on day one — you'll spend more time curating it than shipping.",[20,1390,1393,1400,1404,1424,1428,1439,1562,1573,1577,1580,1587,1605,1609,1612,1669],{"id":1391,"title":1392},"gates","Quality Gates",[11,1394,1395,1396,1399],{},"A quality gate is a check that blocks progress until it passes. In a single session, ",[15,1397,1398],{},"you"," are the gate — you review before merging. With multiple agents running in parallel, you can't be everywhere. Gates move the checking into the loop.",[65,1401,1403],{"id":1402},"three-kinds-of-gate","Three kinds of gate",[28,1405,1406,1412,1418],{},[31,1407,1408,1411],{},[34,1409,1410],{},"Blocking"," — the run stops until the check passes. Typecheck, unit tests, lint with errors.",[31,1413,1414,1417],{},[34,1415,1416],{},"Warning"," — the run continues but flags the issue. Lint with warnings, coverage dips, perf budgets.",[31,1419,1420,1423],{},[34,1421,1422],{},"Informational"," — the check records data for later. Diff size, file count, token cost.",[65,1425,1427],{"id":1426},"gates-as-hooks-the-automated-path","Gates as hooks (the automated path)",[11,1429,1430,1431,1434,1435,1438],{},"A ",[120,1432,1433],{},"PostToolUse"," hook that runs after every ",[120,1436,1437],{},"Edit"," is the simplest gate you'll write:",[219,1440,1445],{"className":1441,"code":1442,"filename":1443,"language":1444,"meta":225,"style":225},"language-json shiki shiki-themes github-light","{\n  \"hooks\": {\n    \"PostToolUse\": [\n      {\n        \"matcher\": \"Edit|Write\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"npm run -s typecheck 2>&1 | tail -20\",\n            \"timeout\": 60\n          }\n        ]\n      }\n    ]\n  }\n}\n",".claude\u002Fsettings.json","json",[120,1446,1447,1452,1460,1468,1473,1486,1493,1498,1510,1522,1532,1537,1542,1547,1552,1557],{"__ignoreMap":225},[229,1448,1449],{"class":231,"line":232},[229,1450,1451],{"class":301},"{\n",[229,1453,1454,1457],{"class":231,"line":239},[229,1455,1456],{"class":256},"  \"hooks\"",[229,1458,1459],{"class":301},": {\n",[229,1461,1462,1465],{"class":231,"line":266},[229,1463,1464],{"class":256},"    \"PostToolUse\"",[229,1466,1467],{"class":301},": [\n",[229,1469,1470],{"class":231,"line":285},[229,1471,1472],{"class":301},"      {\n",[229,1474,1475,1478,1480,1483],{"class":231,"line":292},[229,1476,1477],{"class":256},"        \"matcher\"",[229,1479,1195],{"class":301},[229,1481,1482],{"class":246},"\"Edit|Write\"",[229,1484,1485],{"class":301},",\n",[229,1487,1488,1491],{"class":231,"line":298},[229,1489,1490],{"class":256},"        \"hooks\"",[229,1492,1467],{"class":301},[229,1494,1495],{"class":231,"line":318},[229,1496,1497],{"class":301},"          {\n",[229,1499,1500,1503,1505,1508],{"class":231,"line":333},[229,1501,1502],{"class":256},"            \"type\"",[229,1504,1195],{"class":301},[229,1506,1507],{"class":246},"\"command\"",[229,1509,1485],{"class":301},[229,1511,1512,1515,1517,1520],{"class":231,"line":338},[229,1513,1514],{"class":256},"            \"command\"",[229,1516,1195],{"class":301},[229,1518,1519],{"class":246},"\"npm run -s typecheck 2>&1 | tail -20\"",[229,1521,1485],{"class":301},[229,1523,1524,1527,1529],{"class":231,"line":344},[229,1525,1526],{"class":256},"            \"timeout\"",[229,1528,1195],{"class":301},[229,1530,1531],{"class":256},"60\n",[229,1533,1534],{"class":231,"line":356},[229,1535,1536],{"class":301},"          }\n",[229,1538,1539],{"class":231,"line":361},[229,1540,1541],{"class":301},"        ]\n",[229,1543,1544],{"class":231,"line":367},[229,1545,1546],{"class":301},"      }\n",[229,1548,1549],{"class":231,"line":516},[229,1550,1551],{"class":301},"    ]\n",[229,1553,1554],{"class":231,"line":529},[229,1555,1556],{"class":301},"  }\n",[229,1558,1559],{"class":231,"line":534},[229,1560,1561],{"class":301},"}\n",[11,1563,1564,1565,1568,1569,1572],{},"If ",[120,1566,1567],{},"typecheck"," exits non-zero, Claude sees the output and self-corrects on the next turn. Gate cost: one ",[120,1570,1571],{},"tsc"," per edit. Worth it in most projects.",[65,1574,1576],{"id":1575},"gates-as-review-agents-the-semantic-path","Gates as review agents (the semantic path)",[11,1578,1579],{},"Typecheck catches syntax. It doesn't catch \"this violates our service-layer convention.\" That's a review agent:",[219,1581,1585],{"className":1582,"code":1583,"filename":1584,"language":890,"meta":225},[887],"Use the reviewer agent to audit the diff on feat\u002Fbilling-api.\nThe review is blocking: do NOT merge until the reviewer returns LGTM.\n","prompt to main Claude, after implementer finishes",[120,1586,1583],{"__ignoreMap":225},[11,1588,1589,1590,1592,1593,1604],{},"Pair the review with a simple ",[120,1591,224],{}," check — ",[15,1594,1595,1596,1599,1600,1603],{},"\"has ",[120,1597,1598],{},".claude\u002Fstate\u002Freviews\u002Fbilling-api.md"," been written in the last 10 minutes and does its first line say ",[120,1601,1602],{},"LGTM","?\""," — and you've got a hard gate without any CI.",[65,1606,1608],{"id":1607},"gates-in-ci-the-last-line-of-defense","Gates in CI (the last line of defense)",[11,1610,1611],{},"Everything above runs on your machine. For work headed to production, add CI gates that don't trust the local run:",[219,1613,1618],{"className":1614,"code":1615,"filename":1616,"language":1617,"meta":225,"style":225},"language-yaml shiki shiki-themes github-light","- run: npm run typecheck\n- run: npm test\n- run: npm run lint -- --max-warnings=0\n- run: npx claude-code-review  # runs an eval-based review agent in CI\n",".github\u002Fworkflows\u002Fpr.yml (excerpt)","yaml",[120,1619,1620,1633,1644,1655],{"__ignoreMap":225},[229,1621,1622,1625,1628,1630],{"class":231,"line":232},[229,1623,1624],{"class":301},"- ",[229,1626,1627],{"class":1191},"run",[229,1629,1195],{"class":301},[229,1631,1632],{"class":246},"npm run typecheck\n",[229,1634,1635,1637,1639,1641],{"class":231,"line":239},[229,1636,1624],{"class":301},[229,1638,1627],{"class":1191},[229,1640,1195],{"class":301},[229,1642,1643],{"class":246},"npm test\n",[229,1645,1646,1648,1650,1652],{"class":231,"line":266},[229,1647,1624],{"class":301},[229,1649,1627],{"class":1191},[229,1651,1195],{"class":301},[229,1653,1654],{"class":246},"npm run lint -- --max-warnings=0\n",[229,1656,1657,1659,1661,1663,1666],{"class":231,"line":285},[229,1658,1624],{"class":301},[229,1660,1627],{"class":1191},[229,1662,1195],{"class":301},[229,1664,1665],{"class":246},"npx claude-code-review",[229,1667,1668],{"class":235},"  # runs an eval-based review agent in CI\n",[11,1670,1671],{},"The combination of local hook + review agent + CI makes it genuinely hard to merge a regression. Each catches a different class of failure.",[20,1673,1675,1690,1694,1711,1715,1733,1737,1746],{"id":1674,"title":142},"agents-md",[11,1676,1677,1679,1680,1682,1683,1685,1686,1689],{},[120,1678,142],{}," is to a team what ",[120,1681,829],{}," is to a single session: the shared context every agent loads before doing anything. The difference is that ",[120,1684,142],{}," is about the ",[15,1687,1688],{},"choreography"," — who does what, in what order, with what tools.",[65,1691,1693],{"id":1692},"what-goes-in-agentsmd","What goes in AGENTS.md",[28,1695,1696,1699,1702,1705,1708],{},[31,1697,1698],{},"The roster (with tools + models per role)",[31,1700,1701],{},"The ordering (the default pipeline, with allowed skips\u002Frepairs)",[31,1703,1704],{},"The shared-state convention (where plans, reviews, run logs live)",[31,1706,1707],{},"The rules of engagement (who can edit what, when to stop)",[31,1709,1710],{},"The escalation path (when to hand back to the human)",[65,1712,1714],{"id":1713},"what-does-not","What does NOT",[28,1716,1717,1724,1730],{},[31,1718,1719,1720,1723],{},"Anything a role-specific ",[120,1721,1722],{},".claude\u002Fagents\u002F\u003Crole>.md"," can say — put the specifics there.",[31,1725,1726,1727,1729],{},"Domain conventions (those go in ",[120,1728,829],{},").",[31,1731,1732],{},"Secrets, environment, or machine-specific paths.",[65,1734,1736],{"id":1735},"the-compound-learning-loop","The compound-learning loop",[11,1738,1739,1741,1742,1745],{},[120,1740,142],{}," is where your team's ",[15,1743,1744],{},"meta-experience"," lives. Every time you catch a coordination bug — implementer edited a test file, reviewer started proposing fixes, planner started writing code — patch the rules of engagement. After a few weeks, the doc reflects the actual way your team works. New agents you spin up inherit that lessons-learned for free.",[57,1747,1750],{"title":1748,"variant":1749},"The diff test","success",[11,1751,1752,1753,1756],{},"Once a month, ",[120,1754,1755],{},"git log -p AGENTS.md"," and read the diffs. Every edit should correspond to a specific failure you hit. If you see rules with no story behind them, delete them — they're cargo cult.",[20,1758,1761,1771,1775,1778,1868,1872,1895,1899,1919],{"id":1759,"title":1760},"econ","Token Economics",[11,1762,1763,1764,1766,1767,1770],{},"Parallelism costs tokens. Every additional Claude session has its own system prompt, its own tools, its own ",[120,1765,829],{}," — typically 30–50K tokens of overhead before any work starts. Three parallel agents cost roughly 3× the baseline ",[15,1768,1769],{},"plus"," whatever each agent consumes on task.",[65,1772,1774],{"id":1773},"a-rough-calculator","A rough calculator",[11,1776,1777],{},"For a feature that would take one session ~100K tokens end-to-end:",[84,1779,1780,1796],{},[87,1781,1782],{},[90,1783,1784,1787,1790,1793],{},[93,1785,1786],{},"Setup",[93,1788,1789],{},"Token cost",[93,1791,1792],{},"Wall time",[93,1794,1795],{},"Good when",[106,1797,1798,1812,1826,1840,1854],{},[90,1799,1800,1803,1806,1809],{},[111,1801,1802],{},"Solo session",[111,1804,1805],{},"~100K",[111,1807,1808],{},"60 min",[111,1810,1811],{},"Simple features, novel work",[90,1813,1814,1817,1820,1823],{},[111,1815,1816],{},"Solo + 1 review subagent",[111,1818,1819],{},"~130K",[111,1821,1822],{},"65 min",[111,1824,1825],{},"Anything you'd ship to prod",[90,1827,1828,1831,1834,1837],{},[111,1829,1830],{},"3-agent team, sequential",[111,1832,1833],{},"~200K",[111,1835,1836],{},"45 min",[111,1838,1839],{},"Clear plan, parallelizable steps",[90,1841,1842,1845,1848,1851],{},[111,1843,1844],{},"3-agent team, parallel worktrees",[111,1846,1847],{},"~250K",[111,1849,1850],{},"20 min",[111,1852,1853],{},"You have deadline pressure",[90,1855,1856,1859,1862,1865],{},[111,1857,1858],{},"Best-of-N (3 attempts)",[111,1860,1861],{},"~300K",[111,1863,1864],{},"30 min",[111,1866,1867],{},"High-ambiguity, subjective quality",[65,1869,1871],{"id":1870},"when-it-pays-off","When it pays off",[28,1873,1874,1880,1889],{},[31,1875,1876,1879],{},[34,1877,1878],{},"Your hourly rate > your token bill."," If parallel work saves you 30 minutes and costs $3 extra, that's a rounding error.",[31,1881,1882,1885,1886,1888],{},[34,1883,1884],{},"The team is well-shaped."," Re-running the same Team on the same type of feature amortizes the ",[120,1887,142],{}," investment.",[31,1890,1891,1894],{},[34,1892,1893],{},"You'd have failed the first time anyway."," Review agents catch issues that would cost 10× the tokens to fix after ship.",[65,1896,1898],{"id":1897},"when-it-doesnt","When it doesn't",[28,1900,1901,1907,1913],{},[31,1902,1903,1906],{},[34,1904,1905],{},"One-off exploratory work."," You won't know what shape the solution should take until you've done it once. Parallel attempts at the wrong problem don't help.",[31,1908,1909,1912],{},[34,1910,1911],{},"Sequential features disguised as parallel."," If step B depends on step A's output, running them in parallel means step B starts with stale assumptions and has to be redone.",[31,1914,1915,1918],{},[34,1916,1917],{},"Unstable models\u002Ftools."," If you haven't yet verified that the Claude-per-role idea works for your codebase, three failures in parallel is just more failures.",[11,1920,1921,1922,1926],{},"See ",[184,1923,1925],{"href":1924},"\u002Ftokens#subagent-econ","Token Mastery → Subagent Economics"," for a deeper breakdown of the subagent side of this math.",[20,1928,1930,1933,1937,1940,1951,1955,1958,1969,1973,1976,1989,1993],{"id":1929,"title":192},"external",[11,1931,1932],{},"Everything above keeps Claude Code in the driver's seat. At some point, you'll hit a problem that isn't really a Claude Code problem anymore — it's a product, or a pipeline, or a scheduled job. That's when you move to tier 3.",[65,1934,1936],{"id":1935},"claude-agent-sdk","Claude Agent SDK",[11,1938,1939],{},"Anthropic's official SDK for embedding Claude-Code-style agents in your own programs. Same harness concepts (tools, sub-agents, hooks) exposed as a Python\u002FTypeScript API. Choose this when:",[28,1941,1942,1945,1948],{},[31,1943,1944],{},"You're building an agent that lives inside an app, not a terminal.",[31,1946,1947],{},"You need programmatic control over the loop (retries, timeouts, tool whitelisting).",[31,1949,1950],{},"You want the Claude Code mental model without the Claude Code CLI.",[65,1952,1954],{"id":1953},"framework-orchestrators-langgraph-crewai-n8n-etc","Framework orchestrators (LangGraph, CrewAI, n8n, etc.)",[11,1956,1957],{},"Graph-based or flow-based systems that route LLM calls through a state machine. Claude is one node among many; the framework owns the control flow. Choose when:",[28,1959,1960,1963,1966],{},[31,1961,1962],{},"Multiple model providers (Claude + OpenAI + local) participate in the same flow.",[31,1964,1965],{},"The flow is long-lived, event-driven, or needs to survive process restarts.",[31,1967,1968],{},"You need a visual editor, audit logs, or enterprise-grade observability out of the box.",[65,1970,1972],{"id":1971},"when-external-is-the-wrong-answer","When external is the wrong answer",[11,1974,1975],{},"Every team I've watched adopt a framework before tier 2 spent 2–4 weeks fighting it. The failure mode is always the same: the framework's abstractions don't match the team's actual workflow, so people build workarounds that recreate the Claude Code primitives one at a time. By the time they're productive, they've written a worse Agent Teams setup at 10× the complexity.",[57,1977,1979],{"title":1978,"variant":60},"The tier-3 escape hatch",[11,1980,1981,1982,1984,1985,1988],{},"You earn the right to tier 3 by outgrowing tier 2. If you're at tier 1 and reaching for LangGraph, you're almost certainly solving the wrong problem. Get to a working ",[120,1983,142],{}," + worktree setup first. If ",[15,1986,1987],{},"that"," starts creaking, frameworks are the next honest step.",[65,1990,1992],{"id":1991},"the-decision-in-one-sentence","The decision, in one sentence",[11,1994,1995,1996,1998,1999,876],{},"Stay in tier 2 as long as the agents are helping ",[15,1997,1398],{}," ship. Move to tier 3 when the agents are shipping for ",[15,2000,2001],{},"someone else",[2003,2004,2005],"style",{},"html pre.shiki code .sAwPA, html code.shiki .sAwPA{--shiki-default:#6A737D}html pre.shiki code .s7eDp, html code.shiki .s7eDp{--shiki-default:#6F42C1}html pre.shiki code .sYBdl, html code.shiki .sYBdl{--shiki-default:#032F62}html pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html pre.shiki code .sgsFI, html code.shiki .sgsFI{--shiki-default:#24292E}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .surfw, html code.shiki .surfw{--shiki-default:#005CC5;--shiki-default-font-weight:bold}html pre.shiki code .sqxcx, html code.shiki .sqxcx{--shiki-default:#E36209}html pre.shiki code .shJU0, html code.shiki .shJU0{--shiki-default:#22863A}",{"title":225,"searchDepth":239,"depth":239,"links":2007},[2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033],{"id":67,"depth":266,"text":68},{"id":388,"depth":266,"text":389},{"id":418,"depth":266,"text":419},{"id":575,"depth":266,"text":576},{"id":612,"depth":266,"text":613},{"id":840,"depth":266,"text":841},{"id":879,"depth":266,"text":880},{"id":904,"depth":266,"text":905},{"id":949,"depth":266,"text":950},{"id":960,"depth":266,"text":961},{"id":1174,"depth":266,"text":1175},{"id":1355,"depth":266,"text":1356},{"id":1402,"depth":266,"text":1403},{"id":1426,"depth":266,"text":1427},{"id":1575,"depth":266,"text":1576},{"id":1607,"depth":266,"text":1608},{"id":1692,"depth":266,"text":1693},{"id":1713,"depth":266,"text":1714},{"id":1735,"depth":266,"text":1736},{"id":1773,"depth":266,"text":1774},{"id":1870,"depth":266,"text":1871},{"id":1897,"depth":266,"text":1898},{"id":1935,"depth":266,"text":1936},{"id":1953,"depth":266,"text":1954},{"id":1971,"depth":266,"text":1972},{"id":1991,"depth":266,"text":1992},"Multi-agent patterns, the 3-tier orchestrator landscape, Agent Teams, git worktrees, AGENTS.md, and quality gates.","25 min","md","Scale beyond one session","LucideNetwork",null,{},{"title":2042,"path":2043},"Evals","\u002Fevals","\u002Forchestration",{"title":2046,"path":2047},"Token Mastery","\u002Ftokens",{"title":2049,"description":2050,"keywords":2051,"proficiencyLevel":2060,"timeRequired":2061},"Orchestration — Multi-Agent Claude Code at Scale","When to scale up from a single session: the 3-tier orchestrator landscape, subagents graduating to Agent Teams, git worktrees, conductor vs orchestrator models, AGENTS.md, quality gates, token economics, and external orchestrators compared.",[2052,2053,2054,2055,2056,2057,2058,2059],"multi-agent orchestration","claude code subagents","agent teams","git worktrees","agents md","conductor orchestrator","quality gates","parallel agents","Advanced","PT25M",[2063,2064,2065,2066,2067,2068,2069,2070,2071,2072],{"id":22,"title":23,"level":239},{"id":78,"title":79,"level":239},{"id":196,"title":197,"level":239},{"id":407,"title":408,"level":239},{"id":868,"title":869,"level":239},{"id":942,"title":943,"level":239},{"id":1391,"title":1392,"level":239},{"id":1674,"title":142,"level":239},{"id":1759,"title":1760,"level":239},{"id":1929,"title":192,"level":239},"2HLvxt-yev7u0akZB1GQ54F7ZSR4YEGZMfRQlglj4Zk",1777109528355]