video youtu.be Watch ↗

Claude Code Task System: Orchestrating a Team of Agents Through a Task Graph

TL;DR

IndyDevDan walks through Claude Code's Task System — a native substrate for running a team of agents — by dissecting one reusable plan_w_team.md slash command that turns a short request into a full implementation plan and then executes it with specialized sub-agents. Three ideas carry the video: (1) a task graph — the TaskUpdate tool exposes tasks with an owner plus addBlocks/addBlockedBy dependency edges, so a primary agent delegates work and sub-agents ping back to unblock their dependents in order, staffed as recurring builder/validator pairs where each build task is gated by a paired validator running an executable check (py_compile, "contains required section"); (2) a meta-prompt — a templated command (<requested content> placeholders, <if …> conditional sections, a Stop hook that asserts the generated plan contains its required sections) that you author once and deploy over and over; (3) an explicit anti-hype stance — "more agents, more autonomy, more compute doesn't always mean better outcomes," so the value is coordination toward a common goal, not agent count. The demo is deliberately mundane (documenting an existing hooks codebase) to show the machinery, not a flashy result. Net: this is the orchestrator-workers pattern given a first-class runtime, wrapped in the simplicity discipline — stay close to the fundamentals of the agent.

Concepts introduced

Agent Task Graph — the headline: a team of agents coordinated by a shared task list with owner + blocks/blockedBy dependency edges (Claude Code's Task System / the TaskUpdate tool), staffed as builder/validator pairs.
Meta-Prompt — the reusable, templated prompt (plan_w_team.md) that expands a short request into a full plan, with placeholder substitution, conditional sections, and a hook-enforced output format.

Held, not dropped

Themes the capture touches that don't warrant their own concept page yet — spin out on demand:

Claude Code hooks as validation gates — the Stop hook running validate_*.py, and the plan's "each new hook gets its own JSON log file." A Claude-Code-specific mechanism; currently folded into Meta-Prompt (format enforcement) and Agent Supervision (automated gating). Spin out as agent-hooks if a second independent source treats hooks as a first-class concept.
"Ralph Wiggum" technique (briefly name-dropped at ~24:25 alongside multi-agent orchestration) — an external technique reference, not developed here.
Slash commands as a personal prompt library — the delivery vehicle; covered by Reusable Workflow Library, not re-abstracted.
general-purpose vs. specialized team-member agents (.claude/agents/team/*.md) — the agent-role-definition layer; held pending a source that develops it.

Key claims

A team of agents needs a shared task graph with dependency edges and per-task ownership — not just parallel invocation — to coordinate toward one goal. principle → Agent Task Graph
Model task dependencies as blocks/blockedBy edges and let a completing task unblock its dependents automatically. (best practice — context: orchestrating interdependent sub-agents on a runtime that acts on the edges) → Agent Task Graph
Pair every builder agent with a validator agent whose task depends on the build and gates on an executable check. (best practice — context: multi-agent builds where a late-caught failure is expensive; costs an extra agent per unit of work) → Agent Task Graph, Agent Supervision
More agents, more autonomy, and more compute don't always mean better outcomes — what matters is coordination toward a common goal. principle → Agentic Simplicity, Agent Task Graph
A meta-prompt fixes the shape of good output as an enforced template and fills only the request-specific content per invocation. principle → Meta-Prompt
Template with explicit placeholders and conditional sections; write everything outside the marked slots verbatim. (best practice — context: authoring reusable prompt/plan generators) → Meta-Prompt
Enforce the meta-prompt's output format with a validator (a Stop hook checking required sections) rather than trusting the generation. (best practice — context: pipelines where a downstream agent depends on the artifact's structure) → Meta-Prompt, Agent Supervision
Author the reusable prompt once; it "gives value every single time." observation → Reusable Workflow Library
The generated plan is a concrete, checkable spec (acceptance criteria + validation commands), not a vague description. observation → Spec-Driven Development
The Task System is on by default with sub-agents and "really helps in the planning phase." observation → Agent Task Graph

Why this builds on the graph (and corroborates the simplicity thesis)

Dominant stance — builds_on. The video's headline mechanism is the orchestrator-workers pattern (Agentic Workflow Patterns, Workflows vs Agents) given a native runtime substrate: instead of wiring delegation ad-hoc inside one long prompt, Claude Code's Task System exposes tasks as first-class objects with ownership and blocks/blockedBy edges. That's a genuine sharpening of a known concept, so it lands as builds_on and spins out Agent Task Graph and Meta-Prompt as the new nodes rather than as a wholly novel attachment.

Secondary — corroborates Agentic Simplicity. The anti-hype close is an independent witness to the simplicity thesis, extended to team size: "more agents… doesn't always mean better outcomes." Where Anthropic's "Building Effective Agents" argues find the simplest solution and add complexity only when it pays, this source argues the same for orchestration — coordination structure, not agent count, is what buys the gain, and un-coordinated autonomy is "slop." Two sources now converge on simplicity over sophistication.

Also present — builds_on Spec-Driven Development and Agent Supervision. The generated plan is a spec (checkable acceptance criteria + validation commands), and the builder/validator pairing is supervision internalized into the graph — an agent gating another agent's work before it reaches the human. Neither is contradicted; both gain a concrete instance.

Illustrated walkthrough

Visual coverage is ok (max blind gap ~60s, at roughly 14:00–15:00 during the "blocked-tasks unblock" explanation, which is narrated over grid-sampled frames). The sampler misses text-on-solid-background changes, so absence of a frame there is not evidence nothing changed on screen.

t=00:13 — "ORCHESTRATE" title card. A single green word on black sets the thesis: the new paradigm is tools for engineers to orchestrate intelligence, explicitly not the "powerful but dangerous" auto-pilot bots. Framing over hype from the first frame.
t=01:38 — the plan_w_team.md slash command (the whole trick in one file). A .claude/commands/plan_w_team.md open in the editor. Front-matter: model: opus, disallowed-tools: Task, EnterPlanMode (the planner itself may not spawn tasks — it only writes the plan), and a Stop hook that runs two validators — validate_new_file.py --directory specs --extension .md and validate_file_contains.py asserting the plan contains ## Task Description, ## Objective, ## Relevant Files, ## Step by Step Tasks, ## Acceptance Criteria, ## Team Orchestration, and ### Team Members. The command body (# Plan With Team) instructs the agent to expand USER_PROMPT into a blueprint. This one file is the meta-prompt.
t=05:02 — ### TEAM ORCHESTRATION block. A full-screen section marker. The point made over it: a team without task dependencies and without a way for agents to communicate cannot pursue a mission — it just produces parallel, uncoordinated work. The orchestration block is where the plan declares the coordination structure.
t=06:42 — the templated Plan Format (meta-prompting mechanics). The command's ## Workflow and ## Plan Format. Workflow steps: Understand Codebase (no sub-agents, read patterns directly), Design Solution, Define Team Members (from .claude/agents/team/*.md or fall back to general-purpose), Define Step by Step Tasks (guided by ORCHESTRATION_PROMPT, with parallel/sequential structure and task IDs), then generate a kebab-case filename and save. The templating rules are explicit: "Replace <requested content> with the requested content… anything NOT in <requested content> should be written EXACTLY as it appears," and conditional blocks like <if task_type is feature or complexity is medium/complex, include these sections:> → ## Problem Statement, ## Solution Approach → </if>. The prompt is teaching the agent to build the plan "as you would."
t=12:00 — the generated concrete plan (specs/hooks-update-with-team.md). Split view: the template on the left, the expanded plan on the right. Its ## Acceptance Criteria are concrete and checkable — "All 12 hook types implemented (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit…)," "5 new status lines (v5–v9)," "All Python files compile — uv run python -m py_compile passes," settings.json updated, per-hook JSON log files, README updated. A ## Validation Commands list gives one py_compile per file. The plan is a spec.
t=13:30 — the TaskUpdate tool signature (the Task System API itself). A clean code card titled Task Tool: TaskUpdate. Parameters: taskId, status: "pending" | "in_progress" | "completed" | "deleted", subject, description, activeForm, owner, metadata: Record<string, unknown>, addBlocks: string[], addBlockedBy: string[]. This is the whole substrate in eleven lines: ownership plus dependency edges. Everything else is the graph built out of these calls.
t=18:30 — the generated task list (builder/validator pairs). The plan's ## Step by Step Tasks, e.g. ### 10. Validate SubagentStart Hook — Task ID validate-subagent- start, Depends On build-subagent-start, Assigned To subagent-start-validator, Agent Type validator, Parallel false, then Verify …exists and is valid Python / Run uv run python -m py_compile …. Every builder task has a mirror validator task that depends on it. Editor tabs show builder.md and validator.md — the two foundational team-member definitions. "A builder and a validator" is the bare-minimum team; agents can resume if something goes wrong.
t=25:28 — the anti-hype close. A mood image: a lone figure walking into a tunnel of green/gold data streams. Over it: "there's a lot of hype right now… a lot of slop engineering and just vibe coding" from people "that have no idea what's going on underneath the hood." The pitch is to be the engineer who actually learns to use agents and build systems that operate with and without you — "these are just tools and prompts… stay close to the fundamentals of the agent at a foundational level while increasing what we can do."