Agentic SDLC — Agents, Subagents & Orchestration Map

AGENTS · SUBAGENTS · ORCHESTRATIONAgentic SDLC, Workshops 2 & 3 — from one agent in a loop to a team you can trust.← Agentic SDLC Meta-Map1🍳The Agent LoopWORKSHOP 2An agent is a model + tools + context in a loop. Autonomy meansswapping the human in that loop for tests — and giving the loop anexit.2✉️Fork or FreshWORKSHOPS 2–3Two kinds of helper: a fresh agent knows only its brief; a forkinherits everything you know. Both lose detail at the handoff.3🏗️Fan-out & WorktreesWORKSHOP 3Split work into independent pieces, give each worker its own gitworktree, then fan back in through review and merge.4🎼Briefs & the ConductorWORKSHOP 3The brief is the only context a worker gets. Make goalsfinishable, genie-proof, and routed to the agent who owns thatarea.5🛂Review GatesTHE LONG GAMEMachines block, agents push back, humans decide direction. Andevery 'done' is a claim until you've seen the evidence.6🚦When NOT to SpawnOPERATINGAgents cost more than they look. Spawn for parallelism, sidequests, broad sweeps and unbiased review — otherwise just do it.one agent → two kinds of helper → many at once → instructed well → checked → only when worth it DISTRICT 1 OF 6 · WORKSHOP 2The Agent LoopAn agent is a model + tools + context in a loop. Autonomy means swapping the human in that loop for tests — and giving the loop an exit. 1Model + tools + context, in a loop1 of 4YOU ARE HERE · Agents › The Agent Loop › Model + tools + context, in a loopAn agent is a model that keeps choosing its next tool call until it decides it is done.That is the whole trick. CONTEXTwhat it can see MODELpicks next step TOOL CALLread · edit · run RESULTlands in context ↻ done? report back no → loop Context = everything on the agent's desk this turn (system prompt, CLAUDE.md, your message, every file itread). Tools = its hands. The model never touches your repo directly; it only asks for tool calls. 🔍 One real turn ① Read tests/test_auth.py ② Bash: pytest → 2 failed ③ Edit auth/login.py (hash before compare) ④ Bash: pytest → 12 passed ⑤ git commit -m "REQ-001: Add loginendpoint" ⑥ Read tasks.md → next unchecked task Six tool calls, one loop. The failing test chosestep ③. 2The context window is a countertop2 of 4YOU ARE HERE · Agents › The Agent Loop › The context window is a countertopThe model only knows what is on the counter right now. The counter has a fixed size, andold things get summarised or fall off. CONTEXT WINDOW (fixed size) system CLAUDE.md your ask file reads tool output its replies compacted / dropped new file read Big files crowd the counter: Workshop 3's rule of thumb is to split files over ~300 lines, because anagent that can see the whole file hallucinates less. A subagent starts with an EMPTY counter — that isboth its superpower (clean focus) and its weakness (knows nothing you didn't hand it). 3Tests in the loop, not you3 of 4YOU ARE HERE · Agents › The Agent Loop › Tests in the loop, not youAn autonomous worker is the same loop with the human replaced by a test suite. The humanisn't in the loop — the tests are. ASSISTANT MODE you: write it AI writes you: test it AI runs you: commit AUTONOMOUS WORKER read tasks.md write code run tests pass → commit next task repeat until tasks.md is all checked Pre-commit hooks make the tests non-negotiable: if they fail, the commit is rejected — for agents andhumans alike. Write the tests FIRST from the requirement; then the tests are the spec the agent workstoward. 4Every loop needs an exit4 of 4YOU ARE HERE · Agents › The Agent Loop › Every loop needs an exitA loop with no retry limit and no escalation turns one error into a bill. Every retryneeds a cap; every failure needs a human it can reach. NO EXIT retry retry retry retry retry … ×100 → $$$, no progress (illustrative, from The Long Game) WITH AN EXIT retry ≤ 3 back off 3 strikes alert human human decides Exits come in three kinds: a DONE condition (all tasks checked, tests green), a LIMIT (max retries, maxturns, a spending cap on the card the agent bills to), and an ESCALATION (post to #alerts, email ahuman). Workshop 2's other guardrail: run agents on an 'outdoor pet' machine, never your laptop with prodcredentials. THE METAPHOR🍳A line cook at a stationthe cook's judgement= the modelknives, stove, tasting spoon= tools: Read, Edit, Bash, gitwhat's on the counter= the context windowthe order ticket= the task / your prompttasting before it goes out= running the tests'86 it, call the chef'= retry limit + escalationWHERE THE METAPHOR BREAKSA cook remembers yesterday. An agent does not: anything not on the counter this turn, it does not know. BENCH · DIAGNOSE THE LOOPBENCHDiagnose the loopEach one is a real way agent loops go wrong. What is missing?▶ click to try it

Each one is a real way agent loops go wrong. What is missing?

▶ Now yours: name the exit condition, the retry limit, and the human alert for the agent you run.

YOU ARE HERE · Agents › The Agent Loop › Bench 🍳The Agent Loop DISTRICT 2 OF 6 · WORKSHOPS 2–3Fork or FreshTwo kinds of helper: a fresh agent knows only its brief; a fork inherits everything you know. Both lose detail at the handoff. 1Fresh subagent: a sealed envelope1 of 4YOU ARE HERE · Agents › Fork or Fresh Agent › Fresh subagent: a sealed envelopeA fresh agent knows ONLY what you put in its brief. It starts with an empty counter andreturns only a summary. YOU (parent) • the user's request • files you read • dead ends you ruled out • house rules • what 'good' looks like • the vibe of the room the brief FRESH AGENT knows: only the brief + whatever it reads ← a summary comes back (detail lost) Brief it like a peer: the goal, what you already ruled out, which files matter, how narrow the scope is,and what to send back. If you can't write a clear brief, you don't understand the task well enough tohand it off. 2Fork: a photocopy of you, mid-thought2 of 4YOU ARE HERE · Agents › Fork or Fresh Agent › Fork: a photocopy of you, mid-thoughtA fork inherits the WHOLE conversation so far, then goes off to do one thing. Its briefcan be one paragraph. PARENT FORK 1 same history map A1 directive FORK 2 same history map B1 directive FORK 3 same history map C1 directive • the user's request • files you read • dead ends ruled out • house rules all copied ⇒ Use a fork when the work NEEDS what you already know — the conventions, the files, the user's taste — andyou want several of it in parallel. Use a fresh agent when inheriting your context would bias it (areviewer) or bloat it. 🔍 Live demo: this map was built by a fork Parent read the engine + curriculum, then sent 5 one-paragraph briefs. Each fork inherited the rest. 3Both handoffs drop detail3 of 4YOU ARE HERE · Agents › Fork or Fresh Agent › Both handoffs drop detailDetail leaks twice: going out (the brief) and coming back (the summary). Neither side cansee what the other missed. what you knew what the brief carried what the worker learned what came back lost on the way out lost on the way back Mitigations: ask for evidence (file paths, line numbers, command output), not conclusions. Ask the workerto list what it did NOT check. And a worker's mistakes come back in the same confident tone as itsfindings — verify the ones you act on. 4Pick by what it must know4 of 4YOU ARE HERE · Agents › Fork or Fresh Agent › Pick by what it must knowThe choice is about context: does the job need what's in your head, or does it need to NOThave it? Is it a handful of tool calls? Does it need what you know? Would your view bias it? do it yourself yes no FORK yes no FRESH + brief yes no → either works; fresh is cheaper on tokens Reviewers should almost always be fresh: give them the code, not your conclusion. THE METAPHOR✉️Clone yourself, or hire a tempa clone of you, mid-day= a fork (inherits the conversation)a temp with a note= a fresh subagent + briefthe note= the brief / promptthe temp's report= the summary that comes backyou can't watch them= you only see the resultcalling them back= SendMessage to continue an agentWHERE THE METAPHOR BREAKSA clone of you would share your judgement. A fork shares your context, but each fork can still choosedifferently. BENCH · FORK OR FRESH?BENCHFork or fresh?Pick the kind of helper. There is a best answer and a why.▶ click to try it

Pick the kind of helper. There is a best answer and a why.

▶ Now yours: name one task this week you'd fork, and one you'd give a fresh reviewer.

YOU ARE HERE · Agents › Fork or Fresh Agent › Bench ✉️Fork or Fresh DISTRICT 3 OF 6 · WORKSHOP 3Fan-out & WorktreesSplit work into independent pieces, give each worker its own git worktree, then fan back in through review and merge. 1Fan-out, fan-in1 of 4YOU ARE HERE · Agents › Fan-out & Worktrees › Fan-out, fan-inSplit work into independent pieces, run them at once, then bring the results backtogether. The split is the hard part. brief worker A worker B worker C review merge Pieces are independent when they don't edit the same files anddon't wait on each other's output. If B needs A's result,that's a pipeline, not a fan-out. 🔍 Worked trace: dark mode, ×3 1 BRIEF: 'Add dark mode.' Split into tokens · toggle· docs. 2 git worktree add ../app-wt-tokens -b feat/tokens(and -toggle, -docs) 3 Workers A, B, C run at once, each in its ownfolder and branch. Each runs the tests there. 4 A: tokens in theme.css ✓ B: toggle in Settings ✓C: docs page ✓ 5 Fresh reviewer, different model, sees each diff: Aok · B NEEDS CHANGES (choice isn't saved onreload) · C ok 6 B fixes in its own worktree; re-review passes. 7 Merge order: tokens → toggle (rebase on tokens;both touched theme.css) → docs. 8 git worktree remove ×3. One PR per branch, allgreen. 2Worktrees: one desk per worker2 of 4YOU ARE HERE · Agents › Fan-out & Worktrees › Worktrees: one desk per workerA git worktree is a second (third, fourth…) checkout of the same repo, in its own folder,on its own branch. Workers can't trample each other's files. .git (one history) commits & objects are shared 📁 app/ branch: main you 📁 app-wt-a/ branch: feat/a worker A 📁 app-wt-b/ branch: feat/b worker B 📁 app-wt-c/ branch: feat/c worker C git worktree add ../app-wt-a -b feat/a → a new folder on a new branch, sharing one history. Cheaper than aclone (no second copy of history), safer than sharing one folder. Remove it with git worktree remove when thebranch merges. 3Fan-in is where parallel work collides3 of 4YOU ARE HERE · Agents › Fan-out & Worktrees › Fan-in is where parallel work collidesIsolation lasts until merge. Two workers who edited the same lines produce a conflict thatsomeone has to resolve. CLEAN: different files A: api/users.py B: web/Profile.tsx CONFLICT: same lines A: renames getUser() B: calls getUser() 💥 Split by ownership (files or folders each worker owns), land shared foundations first, and merge independency order. A merge agent that rebases and re-runs tests can do the boring part. 4Stagger the crews4 of 4YOU ARE HERE · Agents › Fan-out & Worktrees › Stagger the crewsScheduled agents that run at the same minute step on each other. Workshop 2 offsets themby 15 minutes so workers and the merger never overlap. :00 worker :15 watcher :30 researcher :45 merge 0 8-22 * * * worker 15 * * * * watcher 30 8-22 * * * researcher 45 * * * * merge 0 6 * * * senior review Workers sleep 23:00–08:00 (UTC); the mergerkeeps running at :45, so overnight it hasgit to itself and the morning starts witheverything merged. Interactive fan-out (forks in one session) doesn't need a clock — worktrees do the isolating. Scheduled teamsneed both. THE METAPHOR🏗️A building siteone set of blueprints= the shared .git historyeach crew's own plot= a worktree (folder + branch)crews working at once= parallel workersthe site inspector= the reviewer / test gatejoining the plots up= merge (fan-in)shift schedule= staggered cron offsetsWHERE THE METAPHOR BREAKSReal crews can see each other across the site. Agents in worktrees can't — unless you give them a sharedchannel (coffeetalk.md, a chat room). BENCH · CAN THESE RUN IN PARALLEL?BENCHCan these run in parallel?Decide: fan out, or run in order?▶ click to try it

Decide: fan out, or run in order?

▶ Now yours: take your current backlog and circle three items that could run at the same time.

YOU ARE HERE · Agents › Fan-out & Worktrees › Bench 🏗️Fan-out & Worktrees DISTRICT 4 OF 6 · WORKSHOP 3Briefs & the ConductorThe brief is the only context a worker gets. Make goals finishable, genie-proof, and routed to the agent who owns that area. 1Anatomy of a brief1 of 4YOU ARE HERE · Agents › Briefs & the Conductor › Anatomy of a briefThe brief is the only context a fresh agent gets. Six parts; leave one out and the workerguesses. GOAL Find why /checkout is slow under load. ALREADY RULED OUT Not the DB: queries are < 20 ms in the slow log. START HERE api/checkout.py, services/tax.py SCOPE Read-only. Don't change code. DONE MEANS You can point at the line that costs the time. REPORT BACK File:line, evidence, and what you did NOT check. Explicit scope protects you: 'read-only', 'only touch web/', 'don't run migrations'. Asking for what itdid NOT check is the cheapest guard against confident gaps. 2Meeseeks goals: small and finishable2 of 4YOU ARE HERE · Agents › Briefs & the Conductor › Meeseeks goals: small and finishableA good agent goal has a natural end. Like a Mr. Meeseeks, the agent exists to finish onething — unbounded goals have no stopping point. ✓ FINISHABLE ✗ NO STOPPING POINT Implement the login endpoint and write tests Fix the CSS layout bug on the dashboard Add error handling to the payment service Notification toasts UI Make this app as good as possible Optimize everything Keep improving the codebase Make the coolest game on Earth An unbounded goal keeps expanding scope and spending. A finishable one ends with a report. Small goalsalso fit on the context counter, which is why they come back right more often. 3The Evil Genie test3 of 4YOU ARE HERE · Agents › Briefs & the Conductor › The Evil Genie testBefore you send a goal, imagine an evil genie granting it word for word. If it can complyand still ruin your day, the goal is too vague. 'Optimize the database' 🧞 …deletes the slow tables 'Clean up the code' 🧞 …removes the features it didn't understand 'Make it faster' 🧞 …removes the error handling 'Make the tests pass' 🧞 …edits the tests Fix: add the constraint the genie exploited. 'Make the tests pass WITHOUT changing the tests.' 'Make itfaster; keep all existing error handling.' The constraint goes in the brief's SCOPE line. 4The conductor routes the work4 of 4YOU ARE HERE · Agents › Briefs & the Conductor › The conductor routes the workAn orchestrator reads the roadmap, routes each task to the specialist who owns that area,and gives them a shared place to talk. roadmap.mdREQ-007 REQ-008REQ-009 ROUTERby tag · by file path · byasking a model Roybackend · api/ Jenfrontend · web/ Mossinfra · deploy/, ci/ shared channel: coffeetalk.md or Matrix #backend #frontend #alerts Each specialist owns a slice of files, so their merges rarely collide. coffeetalk.md is thelightest-weight channel: a markdown file every agent reads at the start of its cycle and appends to, andyou can read it too. THE METAPHOR🎼A kitchen's pass (the expediter)the expediter at the pass= the orchestrator / youthe order ticket= the briefstations: grill, sauce, pastry= specialist agents'what's the ETA on 12?'= the shared channel'86 the salmon'= what's been ruled outplating check before it goes= review gateWHERE THE METAPHOR BREAKSA real expediter can taste. An orchestrator only sees what workers report — so the ticket must ask forevidence. BENCH · WHAT DID THIS BRIEF FORGET?BENCHWhat did this brief forget?Read the brief. Which part is missing?▶ click to try it

Read the brief. Which part is missing?

▶ Now yours: paste your last real prompt to an agent and label its six parts. Which one is empty?

YOU ARE HERE · Agents › Briefs & the Conductor › Bench 🎼Briefs & the Conductor DISTRICT 5 OF 6 · THE LONG GAMEReview GatesMachines block, agents push back, humans decide direction. And every 'done' is a claim until you've seen the evidence. 1The process stack1 of 4YOU ARE HERE · Agents › Review Gates › The process stackFour layers between an agent's commit and your users. Machines enforce the bottom layers;humans own the top. 1 PRE-COMMIT HOOKS BLOCKS unit tests · types · lint — any fail = commit rejected 2 POST-COMMIT CHECKS FLAGS E2E · security scan · perf — fail = flagged, human notified 3 AGENT REVIEW PUSHES BACK senior-review agent: checklist, anti-patterns — NEEDS_CHANGES / BLOCKED 4 HUMAN REVIEW DECIDES daily: overnight work · weekly: patterns · direction: why are we building this? a commit climbs from layer 1 to 4 Agents focus on HOW to build it correctly. Humans focus on WHY we're building it. 2Red team vs blue team2 of 4YOU ARE HERE · Agents › Review Gates › Red team vs blue teamOne agent builds and defends; another's whole job is to break it. Disagreement is thepoint. BLUE · buildercode + tests + edge cases handled RED · breaker'what did they NOT test?' code + tests failing exploit tests RECONCILEfix it, or explain why it's invalid loop until red has nothing left When: ALWAYS for security, payments, and auth. Sometimes for internal tooling. Rarely for a prototype —there, speed matters more than perfection. (Workshop 3's table.) 3Don't let the reviewer see your answer3 of 4YOU ARE HERE · Agents › Review Gates › Don't let the reviewer see your answerA reviewer handed your conclusion tends to hand it back confirmed. Give it the code, notyour opinion of the code. ANCHORED 'I fixed the race condition in cart.ts. Can youconfirm it's correct?' "Looks correct! ✓" UNANCHORED 'Here's the diff to cart.ts. Find any way two requestscan corrupt the cart.' "Lines 41–52: two tabs can…" Rules of thumb: fresh agent (not a fork), sees the diff, is asked to break it, and ideally runs on adifferent model than the builder. 4Push back on every 'done'4 of 4YOU ARE HERE · Agents › Review Gates › Push back on every 'done'An agent's 'done' is a claim, not a fact. Ask for the evidence that would prove it, thencheck it yourself. "Tests pass." paste the test output "It's deployed." show the live URL responding "Fixed the bug." show it failing before, passing after "Looks good on mobile." screenshot at phone width A worker's mistakes come back in the same confident register as its findings. You can't watch it work —only the evidence it brings back. So ask for evidence in the brief, every time. THE METAPHOR🛂Airport securitythe metal detector= pre-commit hooks (hard stop)the bag swab, after= post-commit scans (flag)the officer's second look= agent reviewthe pilot's go / no-go= human reviewthe red-team tester with a fake bomb= the breaker agent'did you pack this yourself?'= pushing back on 'done'WHERE THE METAPHOR BREAKSAirport layers face the same attacker. Code review layers catch different kinds of mistakes, so each layermust test something new. BENCH · WHICH GATE CATCHES IT?BENCHWhich gate catches it?Name the first layer that should stop this.▶ click to try it

Name the first layer that should stop this.

▶ Now yours: which of the four layers does your project actually have today?

YOU ARE HERE · Agents › Review Gates › Bench 🛂Review Gates DISTRICT 6 OF 6 · OPERATINGWhen NOT to SpawnAgents cost more than they look. Spawn for parallelism, side quests, broad sweeps and unbiased review — otherwise just do it. 1What a handoff really costs1 of 4YOU ARE HERE · Agents › When NOT to Spawn › What a handoff really costsA subagent costs more than it looks. You pay for the brief, the tokens, the lost detail,and the checking afterwards. RECEIPT · 1 subagent writing a good brief your time its own fresh context tokens re-reading what you already read tokens detail lost both ways accuracy you can't watch it work control verifying its claims your time several at once a burst of spend worth it only if parallel or unbiased Weigh the tokens against the accuracy they buy. When in doubt, don't spawn. 2Do it yourself when…2 of 4YOU ARE HERE · Agents › When NOT to Spawn › Do it yourself when…If it's a handful of tool calls, or a lookup whose target you already know, the handoffcosts more than the work. ✋ it's a handful of tool calls ✋ you already know which file ✋ it's a check you could run inline ✋ the next step depends on the answer right now Example: 'which file sets the cookie domain?' is one grep. Spawning for it costs a brief, a context, anda summary. 3Spawn when…3 of 4YOU ARE HERE · Agents › When NOT to Spawn › Spawn when…Spawn for real parallelism, for a side quest that shouldn't block you, for a read acrossmany files when you only need the conclusion, or for an unanchored review. 🚀 independent work in parallelthe 3 dark-mode workers 🚀 a side quest'research X while I keep building' 🚀 a sweep across many filesyou keep the conclusion, not the dumps 🚀 a review not anchored on yoursfresh agent, given the code Several at once = a burst of spend the user didn't ask for. Spawn exactly as many as the work hasindependent pieces. 4Once delegated, wait4 of 4YOU ARE HERE · Agents › When NOT to Spawn › Once delegated, waitDon't also do the work yourself, and never guess what a running agent will say. Wait forits report — then verify it. you delegate agent working… report ✗ meanwhile, also doing it yourself ✗ telling the user what it 'probably' found ✓ do other, unrelated work ✓ when it reports: verify, then relay what matters The agent's final report is for YOU, not the user. You decide what's true and what to pass on. THE METAPHOR🧑‍🍳Too many cooksasking a colleague to grab salt= spawning for a grepbriefing a new hire= writing the brieftwo cooks, same pot= you + agent doing the same task'I bet they used thyme'= predicting an agent's resulta brigade for a banquet= real parallel worktasting what they send out= verifying the reportWHERE THE METAPHOR BREAKSCooks are paid by the hour; agents are paid by the token, so idle waiting is free — duplicated work isn't. BENCH · SPAWN OR NOT?BENCHSpawn or not?Should this be an agent, or should you just do it?▶ click to try it

Should this be an agent, or should you just do it?

▶ Now yours: look at the last time you spawned an agent. Would doing it yourself have been faster?

YOU ARE HERE · Agents › When NOT to Spawn › Bench 🚦When NOT to Spawn

Agentic SDLC — Agents, Subagents & Orchestration Map

Explore

Tour

Teach

Reading the map