> **s01** *"One loop & Bash is all you need"*— one tool + one loop = an agent
>
> **s02** *"The loop didn't change"*— adding tools means adding handlers, not rewriting the loop
> **s02** *"Adding a tool means adding one handler"*— the loop stays the same; new tools register into the dispatch map
>
> **s03** *"Plan before you act"*— visible plans improve task completion
> **s03** *"An agent without a plan drifts"*— list the steps first, then execute; completion doubles
>
> **s04** *"Process isolation = context isolation"*— fresh messages[] per subagent
> **s04** *"Break big tasks down; each subtask gets a clean context"*— subagents use independent messages[], keeping the main conversation clean
>
> **s05** *"Load on demand, not upfront"*— inject knowledge via tool_result, not system prompt
> **s05** *"Load knowledge when you need it, not upfront"*— inject via tool_result, not the system prompt
>
> **s06** *"Strategic forgetting"*— forget old context to enable infinite sessions
> **s06** *"Context will fill up; you need a way to make room"*— three-layer compression strategy for infinite sessions
>
> **s07** *"State survives /compact"*— file-based state outlives context compression
> **s07** *"Break big goals into small tasks, order them, persist to disk"*— a file-based task graph with dependencies, laying the foundation for multi-agent collaboration
>
> **s08** *"Fire and forget"*— non-blocking threads + notification queue
> **s08** *"Run slow operations in the background; the agent keeps thinking"*— daemon threads run commands, inject notifications on completion
>
> **s09** *"Append to send, drain to read"*—async mailboxes for persistent teammates
> **s09** *"When the task is too big for one, delegate to teammates"*— persistent teammates + async mailboxes
>
> **s10** *"Same request_id, two protocols"*— one FSM pattern powers shutdown + plan approval
> **s10** *"Teammates need shared communication rules"*— one request-response pattern drives all negotiation
>
> **s11** *"Poll, claim, work, repeat"*— no coordinator needed, agents self-organize
> **s11** *"Teammates scan the board and claim tasks themselves"*— no need for the lead to assign each one
>
> **s12** *"Isolate by directory, coordinate by task ID"*— task board + optional worktree lanes
> **s12** *"Each works in its own directory, no interference"*— tasks manage goals, worktrees manage directories, bound by ID
---
@ -167,17 +167,17 @@ Available in [English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/j
| Session | Topic | Motto |
|---------|-------|-------|
| [s01](./docs/en/s01-the-agent-loop.md) | The Agent Loop | *One loop & Bash is all you need* |
> *"State survives /compact"* -- file-based state outlives context compression.
> *"Break big goals into small tasks, order them, persist to disk"* -- a file-based task graph with dependencies, laying the foundation for multi-agent collaboration.
## Problem
In-memory state (TodoManager from s03) dies when context compresses (s06). After auto_compact replaces messages with a summary, the todo list is gone. The agent can only reconstruct from summary text -- lossy and error-prone.
s03's TodoManager is a flat checklist in memory: no ordering, no dependencies, no status beyond done-or-not. Real goals have structure -- task B depends on task A, tasks C and D can run in parallel, task E waits for both C and D.
File-based tasks solve this: write state to disk, and it survives compression, process restarts, and eventually multi-agent sharing (s09+).
Without explicit relationships, the agent can't tell what's ready, what's blocked, or what can run concurrently. And because the list lives only in memory, context compression (s06) wipes it clean.
## Solution
Promote the checklist into a **task graph** persisted to disk. Each task is a JSON file with status, dependencies (`blockedBy`), and dependents (`blocks`). The graph answers three questions at any moment:
- **What's ready?** -- tasks with `pending` status and empty `blockedBy`.
- **What's blocked?** -- tasks waiting on unfinished dependencies.
Parallelism: tasks 2 and 3 can run at the same time
Dependencies: task 4 waits for both 2 and 3
Status: pending -> in_progress -> completed
```
This task graph becomes the coordination backbone for everything after s07: background execution (s08), multi-agent teams (s09+), and worktree isolation (s12) all read from and write to this same structure.
## How It Works
1. TaskManager: one JSON file per task, CRUD with dependency graph.
1. **TaskManager**: one JSON file per task, CRUD with dependency graph.
```python
class TaskManager:
@ -48,7 +64,7 @@ class TaskManager:
return json.dumps(task, indent=2)
```
2. Completing a task clears its ID from every other task's `blockedBy` list.
2. **Dependency resolution**: completing a task clears its ID from every other task's `blockedBy` list, automatically unblocking dependents.
s01:{title:"The Agent Loop",subtitle:"Bash is All You Need",coreAddition:"Single-tool agent loop",keyInsight:"The minimal agent kernel is a while loop + one tool",layer:"tools",prevVersion: null},
s02:{title:"Tools",subtitle:"The Loop Didn't Change",coreAddition:"Tool dispatch map",keyInsight:"Adding tools means adding handlers, not rewriting the loop",layer:"tools",prevVersion:"s01"},
s03:{title:"TodoWrite",subtitle:"Plan Before You Act",coreAddition:"TodoManager + nag reminder",keyInsight:"Visible plans improve task completion and accountability",layer:"planning",prevVersion:"s02"},
s04:{title:"Subagents",subtitle:"Process Isolation = Context Isolation",coreAddition:"Subagent spawn with isolated messages[]",keyInsight:"Process isolation gives context isolation for free",layer:"planning",prevVersion:"s03"},
s05:{title:"Skills",subtitle:"SKILL.md + tool_result Injection",coreAddition:"SkillLoader + two-layer injection",keyInsight:"Skills inject via tool_result, not system prompt",layer:"planning",prevVersion:"s04"},
s07:{title:"Tasks",subtitle:"Persistent CRUD with Dependencies",coreAddition:"TaskManager with file-based state + dependency graph",keyInsight:"File-based state survives context compression",layer:"planning",prevVersion:"s06"},
s10:{title:"Team Protocols",subtitle:"Shutdown + Plan Approval",coreAddition:"request_id correlation for two protocols",keyInsight:"Same request-response pattern, two applications",layer:"collaboration",prevVersion:"s09"},
s12:{title:"Worktree + Task Isolation",subtitle:"Isolate by Directory",coreAddition:"Composable worktree lifecycle + event stream over a shared task board",keyInsight:"Task board coordinates ownership, worktrees isolate execution, and events make lifecycle auditable",layer:"collaboration",prevVersion:"s11"},
s02:{title:"Tools",subtitle:"One Handler Per Tool",coreAddition:"Tool dispatch map",keyInsight:"The loop stays the same; new tools register into the dispatch map",layer:"tools",prevVersion:"s01"},
s03:{title:"TodoWrite",subtitle:"Plan Before You Act",coreAddition:"TodoManager + nag reminder",keyInsight:"An agent without a plan drifts; list the steps first, then execute",layer:"planning",prevVersion:"s02"},
s04:{title:"Subagents",subtitle:"Clean Context Per Subtask",coreAddition:"Subagent spawn with isolated messages[]",keyInsight:"Subagents use independent messages[], keeping the main conversation clean",layer:"planning",prevVersion:"s03"},
s05:{title:"Skills",subtitle:"Load on Demand",coreAddition:"SkillLoader + two-layer injection",keyInsight:"Inject knowledge via tool_result when needed, not upfront in the system prompt",layer:"planning",prevVersion:"s04"},
s06:{title:"Compact",subtitle:"Three-Layer Compression",coreAddition:"micro-compact + auto-compact + archival",keyInsight:"Context will fill up; three-layer compression strategy enables infinite sessions",layer:"memory",prevVersion:"s05"},
s07:{title:"Tasks",subtitle:"Task Graph + Dependencies",coreAddition:"TaskManager with file-based state + dependency graph",keyInsight:"A file-based task graph with ordering, parallelism, and dependencies -- the coordination backbone for multi-agent work",layer:"planning",prevVersion:"s06"},
s08:{title:"Background Tasks",subtitle:"Background Threads + Notifications",coreAddition:"BackgroundManager + notification queue",keyInsight:"Run slow operations in the background; the agent keeps thinking ahead",layer:"concurrency",prevVersion:"s07"},
s09:{title:"Agent Teams",subtitle:"Teammates + Mailboxes",coreAddition:"TeammateManager + file-based mailbox",keyInsight:"When one agent can't finish, delegate to persistent teammates via async mailboxes",layer:"collaboration",prevVersion:"s08"},
s10:{title:"Team Protocols",subtitle:"Shared Communication Rules",coreAddition:"request_id correlation for two protocols",keyInsight:"One request-response pattern drives all team negotiation",layer:"collaboration",prevVersion:"s09"},
s11:{title:"Autonomous Agents",subtitle:"Scan Board, Claim Tasks",coreAddition:"Task board polling + timeout-based self-governance",keyInsight:"Teammates scan the board and claim tasks themselves; no need for the lead to assign each one",layer:"collaboration",prevVersion:"s10"},
s12:{title:"Worktree + Task Isolation",subtitle:"Isolate by Directory",coreAddition:"Composable worktree lifecycle + event stream over a shared task board",keyInsight:"Each works in its own directory; tasks manage goals, worktrees manage directories, bound by ID",layer:"collaboration",prevVersion:"s11"},
CrazyBoyM
2 months ago