Skip to content

Commit c3844fa

Browse files
committed
refactor: align session titles with Claude Code official concepts
- Rename all 11 session titles to match Claude Code's branded features (The Agent Loop, Tools, TodoWrite, Subagents, Skills, Compact, Tasks, Background Tasks, Agent Teams, Team Protocols, Autonomous Agents) - Restore signature subtitles: "Bash is All You Need", "Strategic Forgetting", "Fire and Forget" - Change "JSONL Inboxes" to "Mailboxes" (Actor Model standard term) - Rewrite s09/s10 scenarios to match their session titles - Add playground configs for all 11 sessions (was only s01-s03) - Add execution flows for s04, s05, s07, s09, s10 - Remove stale s00_mini, v0-v9, s13 references - Exclude s_full from generated data - Regenerate all data files
1 parent 189c590 commit c3844fa

11 files changed

Lines changed: 462 additions & 316 deletions

File tree

README.md

Lines changed: 66 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -32,21 +32,21 @@ learn-claude-code/
3232
|
3333
|-- agents/ # Python reference implementations
3434
| |-- s01_agent_loop.py # ~70 LOC: while loop + bash
35-
| |-- s02_multi_tool.py # ~90 LOC: + multi-tool dispatch
36-
| |-- s03_structured_planning.py # ~150 LOC: + TodoManager
37-
| |-- s04_context_isolation.py # ~130 LOC: + subagent spawn
38-
| |-- s05_knowledge_loading.py # ~150 LOC: + skill injection
39-
| |-- s06_compression.py # ~180 LOC: + three-layer compress
40-
| |-- s07_file_tasks.py # ~170 LOC: + task CRUD + deps
35+
| |-- s02_multi_tool.py # ~90 LOC: + Read, Write, Edit, Bash
36+
| |-- s03_structured_planning.py # ~150 LOC: + TodoWrite
37+
| |-- s04_context_isolation.py # ~130 LOC: + Task tool / subagents
38+
| |-- s05_knowledge_loading.py # ~150 LOC: + SKILL.md injection
39+
| |-- s06_compression.py # ~180 LOC: + /compact (3-layer)
40+
| |-- s07_file_tasks.py # ~170 LOC: + Tasks API + deps
4141
| |-- s08_background.py # ~160 LOC: + background threads
42-
| |-- s09_team_messaging.py # ~340 LOC: + team + JSONL inboxes
42+
| |-- s09_team_messaging.py # ~340 LOC: + Agent Teams + mailboxes
4343
| |-- s10_team_protocols.py # ~390 LOC: + shutdown + plan approval
44-
| |-- s11_autonomous.py # ~490 LOC: + idle cycle + claim
44+
| |-- s11_autonomous.py # ~490 LOC: + idle cycle + auto-claim
4545
| +-- s_full.py # full combined reference
4646
|
4747
|-- web/ # Interactive learning platform
4848
| |-- src/agents/ # TypeScript agent implementations
49-
| | |-- v0.ts ... v9.ts # run in browser, no sandbox
49+
| | |-- s01.ts ... s11.ts # run in browser, no sandbox
5050
| | +-- shared/ # base class, API client, VFS
5151
| |-- src/components/
5252
| | |-- inspector/ # Live state inspector
@@ -72,36 +72,36 @@ learn-claude-code/
7272

7373
```
7474
Phase 1: THE LOOP Phase 2: PLANNING & KNOWLEDGE
75-
================= ==========================
76-
s01: Agent Loop s03: Structured Planning
77-
| while + bash | TodoManager + nag reminder
78-
| "The entire agent is a loop" | "Make plans visible"
75+
================= ==============================
76+
s01: The Agent Loop s03: TodoWrite
77+
| bash is all you need | plan before you act
78+
| "The entire agent is a loop" | "Visible plans improve completion"
7979
| |
80-
+-> s02: Multi-Tool Dispatch s04: Context Isolation
81-
| dispatch map routing | subagent with fresh messages
80+
+-> s02: Tools s04: Subagents
81+
| Read, Write, Edit, Bash | fresh context via Task tool
8282
| "The loop didn't change" | "Process isolation = context isolation"
8383
|
84-
s05: Knowledge Loading
85-
| SKILL.md + two-layer injection
84+
s05: Skills
85+
| SKILL.md + tool_result injection
8686
| "Load on demand, not upfront"
8787
|
88-
s06: Context Compression
89-
three-layer compression pipeline
88+
s06: Compact
89+
three-layer context compression
9090
"Strategic forgetting"
9191
9292
Phase 3: PERSISTENCE Phase 4: TEAMS
9393
================= =====================
94-
s07: File-Based Tasks s09: Team Messaging
95-
| TaskManager + dependency graph | TeammateManager + JSONL inboxes
96-
| "State survives compression" | "Teammates that communicate"
94+
s07: Tasks s09: Agent Teams
95+
| persistent CRUD + dependencies | teammates + mailboxes
96+
| "State survives /compact" | "Append to send, drain to read"
9797
| |
98-
s08: Background Execution s10: Team Protocols
99-
BackgroundManager + threads | shutdown + plan approval handshake
100-
"Fire and forget" | "Same request_id, two applications"
98+
s08: Background Tasks s10: Team Protocols
99+
fire-and-forget threads + notify | shutdown + plan approval
100+
"Fire and forget" | "Same request_id, two protocols"
101101
|
102-
s11: Autonomous Agent
103-
idle cycle + task board polling
104-
"The agent finds work itself"
102+
s11: Autonomous Agents
103+
idle cycle + auto-claim
104+
"Poll, claim, work, repeat"
105105
```
106106

107107
## Quick Start
@@ -145,19 +145,19 @@ npm run dev
145145
## Session Comparison
146146

147147
```
148-
Session Title LOC Tools Core Addition Key Insight
149-
------- -------------------- --- ----- --------------------- --------------------------
150-
s01 Agent Loop 70 1 while + bash The entire agent is a loop
151-
s02 Multi-Tool Dispatch 90 4 dispatch map The loop didn't change
152-
s03 Structured Planning 150 5 TodoManager + nag Make plans visible
153-
s04 Context Isolation 130 5 run_subagent() Process isolation
154-
s05 Knowledge Loading 150 5 SkillLoader 2-layer Load on demand
155-
s06 Context Compression 180 5 3-layer compress Strategic forgetting
156-
s07 File-Based Tasks 170 8 TaskManager + deps State survives compression
157-
s08 Background Execution 160 6 BackgroundManager Fire and forget
158-
s09 Team Messaging 340 9 Teammates + JSONL inbox Teammates that communicate
159-
s10 Team Protocols 390 12 shutdown + plan approval Same pattern, two domains
160-
s11 Autonomous Agent 490 14 idle cycle + claim Self-organizing teams
148+
Session Claude Code Feature LOC Tools Core Addition Key Insight
149+
------- -------------------- --- ----- ---------------------- --------------------------
150+
s01 The Agent Loop 70 1 while + stop_reason Bash is all you need
151+
s02 Tools 90 4 Read/Write/Edit/Bash The loop didn't change
152+
s03 TodoWrite 150 5 TodoManager + nag Plan before you act
153+
s04 Subagents 130 5 Task tool + spawn Fresh context per subagent
154+
s05 Skills 150 5 SKILL.md injection Load on demand, not upfront
155+
s06 Compact 180 5 3-layer compression Strategic forgetting
156+
s07 Tasks 170 8 CRUD + dependency graph State survives /compact
157+
s08 Background Tasks 160 6 threads + notifications Fire and forget
158+
s09 Agent Teams 340 10 teammates + mailboxes Persistent agents + async mailboxes
159+
s10 Team Protocols 390 12 shutdown + plan approval Same request_id, two protocols
160+
s11 Autonomous Agents 490 14 idle cycle + auto-claim Poll, claim, work, repeat
161161
```
162162

163163
## The Core Pattern
@@ -192,22 +192,22 @@ Each session adds ONE mechanism on top of this loop.
192192

193193
## Key Mechanisms
194194

195-
| Mechanism | Session | What It Does |
196-
|----------------------|---------|-------------------------------------------------|
197-
| Agent loop | s01 | `while (stop_reason == "tool_use")` loop |
198-
| Tool dispatch | s02 | Map of tool name -> handler function |
199-
| Todo planning | s03 | Create plan before execution, track completion |
200-
| Context isolation | s04 | Fresh message list per subagent |
201-
| Skill injection | s05 | SKILL.md content injected via tool_result |
202-
| Micro-compact | s06 | Old tool results replaced with placeholders |
203-
| Auto-compact | s06 | LLM summarizes conversation when tokens > limit |
204-
| Task CRUD + deps | s07 | File-based tasks with dependency graph |
205-
| Background execution | s08 | Threaded commands + notification queue |
206-
| Teammate lifecycle | s09 | Named persistent agents with config.json |
207-
| File-based inbox | s09 | JSONL messages, 5 types, per-teammate files |
208-
| Shutdown protocol | s10 | request_id based FSM for graceful shutdown |
209-
| Plan approval | s10 | Submit/review with request_id correlation |
210-
| Idle cycle | s11 | Poll board, auto-claim unclaimed tasks |
195+
| Claude Code Feature | Session | What It Does |
196+
|---------------------|---------|-------------------------------------------------|
197+
| Agent loop | s01 | `while (stop_reason == "tool_use")` loop |
198+
| Tools | s02 | Map of tool name -> handler function |
199+
| TodoWrite | s03 | Create plan before execution, track completion |
200+
| Subagents | s04 | Fresh message list per subagent via Task tool |
201+
| Skills | s05 | SKILL.md content injected via tool_result |
202+
| Compact (micro) | s06 | Old tool results replaced with placeholders |
203+
| Compact (auto) | s06 | LLM summarizes conversation when tokens > limit |
204+
| Tasks API | s07 | File-based tasks with dependency graph |
205+
| Background tasks | s08 | Threaded commands + notification queue |
206+
| Agent Teams | s09 | Named persistent agents with config.json |
207+
| Mailbox | s09 | Append-only file-based messages, per-teammate |
208+
| Shutdown protocol | s10 | request_id based FSM for graceful shutdown |
209+
| Plan approval | s10 | Submit/review with request_id correlation |
210+
| Idle cycle | s11 | Poll board, auto-claim unclaimed tasks |
211211

212212
## State Inspector
213213

@@ -247,16 +247,16 @@ npm run build # Full build
247247
Each doc follows a mental-model-first structure with ASCII diagrams:
248248

249249
- [s01: The Agent Loop](./docs/s01-the-agent-loop.md)
250-
- [s02: Multi-Tool Dispatch](./docs/s02-multi-tool-dispatch.md)
251-
- [s03: Structured Planning](./docs/s03-structured-planning.md)
252-
- [s04: Context Isolation](./docs/s04-context-isolation.md)
253-
- [s05: Knowledge Loading](./docs/s05-knowledge-loading.md)
254-
- [s06: Context Compression](./docs/s06-context-compression.md)
255-
- [s07: File-Based Tasks](./docs/s07-file-based-tasks.md)
256-
- [s08: Background Execution](./docs/s08-background-execution.md)
257-
- [s09: Team Messaging](./docs/s09-team-messaging.md)
250+
- [s02: Tools](./docs/s02-multi-tool-dispatch.md)
251+
- [s03: TodoWrite](./docs/s03-structured-planning.md)
252+
- [s04: Subagents](./docs/s04-context-isolation.md)
253+
- [s05: Skills](./docs/s05-knowledge-loading.md)
254+
- [s06: Compact](./docs/s06-context-compression.md)
255+
- [s07: Tasks](./docs/s07-file-based-tasks.md)
256+
- [s08: Background Tasks](./docs/s08-background-execution.md)
257+
- [s09: Agent Teams](./docs/s09-team-messaging.md)
258258
- [s10: Team Protocols](./docs/s10-team-protocols.md)
259-
- [s11: Autonomous Agent](./docs/s11-autonomous-agent.md)
259+
- [s11: Autonomous Agents](./docs/s11-autonomous-agent.md)
260260

261261
## License
262262

agents/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
# agents/ - Python teaching agents (s01-s13) + reference agent (s_full)
1+
# agents/ - Python teaching agents (s01-s11) + reference agent (s_full)
22
# Each file is self-contained and runnable: python agents/s01_agent_loop.py

docs/s01-the-agent-loop.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ def agent_loop(messages: list):
113113
messages.append({"role": "user", "content": results})
114114
```
115115

116-
## What Changed From s00
116+
## What Changed
117117

118118
This is session 1 -- the starting point. There is no prior session.
119119

web/scripts/extract-content.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ const OUT_DIR = path.join(WEB_DIR, "src", "data", "generated");
2121
// s_full.py -> s_full (reference agent, typically skipped)
2222
function filenameToVersionId(filename: string): string | null {
2323
const base = path.basename(filename, ".py");
24-
if (base === "s_full") return "s_full";
24+
if (base === "s_full") return null;
2525
if (base === "__init__") return null;
2626

2727
const match = base.match(/^(s\d+[a-c]?)_/);

0 commit comments

Comments
 (0)