abc/analysis_claude_code
1
0
Fork 0
mirror of https://github.com/shareAI-lab/analysis_claude_code.git synced 2026-03-22 02:15:42 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix session doc

Browse Source
This commit is contained in:
CrazyBoyM 2026-02-27 02:19:54 +08:00
parent 665831c774
commit 4f39ee4512
39 changed files with 283 additions and 232 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
README-ja.md
View File

@ -26,27 +26,27 @@
> **s01**   *"One loop & Bash is all you need"* — 1つのツール + 1つのループ = エージェント
>
> **s02**   *"ループは変わらない"* — ツール追加はハンドラー追加であり、ループの作り直しではない
> **s02**   *"ツールを足すなら、ハンドラーを1つ足すだけ"* — ループは変わらない。新ツールは dispatch map に登録するだけ
>
> **s03**   *"行動する前に計画せよ"* — 可視化された計画がタスク完了率を向上させる
> **s03**   *"計画のないエージェントは行き当たりばったり"* — まずステップを書き出し、それから実行
>
> **s04**   *"プロセス分離 = コンテキスト分離"* — サブエージェントごとに新しい messages[]
> **s04**   *"大きなタスクを分割し、各サブタスクにクリーンなコンテキストを"* — サブエージェントは独立した messages[] を使い、メイン会話を汚さない
>
> **s05**   *"必要な時にロード、事前にではなく"* — system prompt ではなく tool_result で知識を注入
> **s05**   *"必要な知識を、必要な時に読み込む"* — system prompt ではなく tool_result で注入
>
> **s06**   *"戦略的忘却"* — 古いコンテキストを忘れて無限セッションを実現
> **s06**   *"コンテキストはいつか溢れる、空ける手段が要る"* — 3層圧縮で無限セッションを実現
>
> **s07**   *"状態は圧縮を生き延びる"* — ファイルベースの状態はコンテキスト圧縮に耐える
> **s07**   *"大きな目標を小タスクに分解し、順序付けし、ディスクに記録する"* — ファイルベースのタスクグラフ、マルチエージェント協調の基盤
>
> **s08**   *"撃ちっ放し"* — ノンブロッキングスレッド + 通知キュー
> **s08**   *"遅い操作はバックグラウンドへ、エージェントは次を考え続ける"* — デーモンスレッドがコマンド実行、完了後に通知を注入
>
> **s09**   *"追記で送信、排出で読取"* — 永続チームメイトのための非同期メールボックス
> **s09**   *"一人で終わらないなら、チームメイトに任せる"* — 永続チームメイト + 非同期メールボックス
>
> **s10**   *"同じ request_id、2つのプロトコル"* — 1つの FSM パターンでシャットダウン + プラン承認
> **s10**   *"チームメイト間には統一の通信ルールが必要"* — 1つの request-response パターンが全交渉を駆動
>
> **s11**   *"ポーリング、クレーム、作業、繰り返し"* — コーディネーター不要、エージェントが自己組織化
> **s11**   *"チームメイトが自らボードを見て、仕事を取る"* — リーダーが逐一割り振る必要はない
>
> **s12**   *"ディレクトリで分離し、タスクIDで調整する"* — タスクボード + 必要時の worktree レーン
> **s12**   *"各自のディレクトリで作業し、互いに干渉しない"* — タスクは目標を管理、worktree はディレクトリを管理、IDで紐付け
---
@ -167,17 +167,17 @@ learn-claude-code/
| セッション | トピック | モットー |
|-----------|---------|---------|
| [s01](./docs/ja/s01-the-agent-loop.md) | エージェントループ | *One loop & Bash is all you need* |
| [s02](./docs/ja/s02-tool-use.md) | Tool Use | *ループは変わらない* |
| [s03](./docs/ja/s03-todo-write.md) | TodoWrite | *行動する前に計画せよ* |
| [s04](./docs/ja/s04-subagent.md) | サブエージェント | *プロセス分離 = コンテキスト分離* |
| [s05](./docs/ja/s05-skill-loading.md) | Skills | *必要な時にロード、事前にではなく* |
| [s06](./docs/ja/s06-context-compact.md) | Context Compact | *戦略的忘却* |
| [s07](./docs/ja/s07-task-system.md) | タスクシステム | *状態は圧縮を生き延びる* |
| [s08](./docs/ja/s08-background-tasks.md) | バックグラウンドタスク | *撃ちっ放し* |
| [s09](./docs/ja/s09-agent-teams.md) | エージェントチーム | *追記で送信、排出で読取* |
| [s10](./docs/ja/s10-team-protocols.md) | チームプロトコル | *同じ request_id、2つのプロトコル* |
| [s11](./docs/ja/s11-autonomous-agents.md) | 自律エージェント | *ポーリング、クレーム、作業、繰り返し* |
| [s12](./docs/ja/s12-worktree-task-isolation.md) | Worktree + タスク分離 | *ディレクトリで分離し、タスクIDで調整する* |
| [s02](./docs/ja/s02-tool-use.md) | Tool Use | *ツールを足すなら、ハンドラーを1つ足すだけ* |
| [s03](./docs/ja/s03-todo-write.md) | TodoWrite | *計画のないエージェントは行き当たりばったり* |
| [s04](./docs/ja/s04-subagent.md) | サブエージェント | *大きなタスクを分割し、各サブタスクにクリーンなコンテキストを* |
| [s05](./docs/ja/s05-skill-loading.md) | Skills | *必要な知識を、必要な時に読み込む* |
| [s06](./docs/ja/s06-context-compact.md) | Context Compact | *コンテキストはいつか溢れる、空ける手段が要る* |
| [s07](./docs/ja/s07-task-system.md) | タスクシステム | *大きな目標を小タスクに分解し、順序付けし、ディスクに記録する* |
| [s08](./docs/ja/s08-background-tasks.md) | バックグラウンドタスク | *遅い操作はバックグラウンドへ、エージェントは次を考え続ける* |
| [s09](./docs/ja/s09-agent-teams.md) | エージェントチーム | *一人で終わらないなら、チームメイトに任せる* |
| [s10](./docs/ja/s10-team-protocols.md) | チームプロトコル | *チームメイト間には統一の通信ルールが必要* |
| [s11](./docs/ja/s11-autonomous-agents.md) | 自律エージェント | *チームメイトが自らボードを見て、仕事を取る* |
| [s12](./docs/ja/s12-worktree-task-isolation.md) | Worktree + タスク分離 | *各自のディレクトリで作業し、互いに干渉しない* |
## 次のステップ -- 理解から出荷へ

44
README-zh.md
View File

@ -26,27 +26,27 @@
> **s01**   *"One loop & Bash is all you need"* — 一个工具 + 一个循环 = 一个智能体
>
> **s02**   *"循环没有变"* — 加工具就是加 handler, 不是重写循环
> **s02**   *"加一个工具, 只加一个 handler"* — 循环不用动, 新工具注册进 dispatch map 就行
>
> **s03**   *"先计划再行动"* — 可见的计划提升任务完成率
> **s03**   *"没有计划的 agent 走哪算哪"* — 先列步骤再动手, 完成率翻倍
>
> **s04**   *"进程隔离 = 上下文隔离"* — 每个子智能体独立 messages[]
> **s04**   *"大任务拆小, 每个小任务干净的上下文"* — 子智能体用独立 messages[], 不污染主对话
>
> **s05**   *"按需加载, 而非预装"* — 通过 tool_result 注入知识, 而非塞进 system prompt
> **s05**   *"用到什么知识, 临时加载什么知识"* — 通过 tool_result 注入, 不塞 system prompt
>
> **s06**   *"策略性遗忘"* — 忘掉旧上下文, 换来无限会话
> **s06**   *"上下文总会满, 要有办法腾地方"* — 三层压缩策略, 换来无限会话
>
> **s07**   *"状态在压缩后存活"* — 文件持久化的状态不怕上下文压缩
> **s07**   *"大目标要拆成小任务, 排好序, 记在磁盘上"* — 文件持久化的任务图, 为多 agent 协作打基础
>
> **s08**   *"发射后不管"* — 非阻塞线程 + 通知队列
> **s08**   *"慢操作丢后台, agent 继续想下一步"* — 后台线程跑命令, 完成后注入通知
>
> **s09**   *"追加即发送, 排空即读取"* — 异步邮箱实现持久化队友通信
> **s09**   *"任务太大一个人干不完, 要能分给队友"* — 持久化队友 + 异步邮箱
>
> **s10**   *"同一个 request_id, 两个协议"* — 一个 FSM 模式驱动关机 + 计划审批
> **s10**   *"队友之间要有统一的沟通规矩"* — 一个 request-response 模式驱动所有协商
>
> **s11**   *"轮询, 认领, 工作, 重复"* — 无需协调者, 智能体自组织
> **s11**   *"队友自己看看板, 有活就认领"* — 不需要领导逐个分配, 自组织
>
> **s12**   *"目录隔离, 任务 ID 协调"* — 任务板协调 + 按需 worktree 隔离通道
> **s12**   *"各干各的目录, 互不干扰"* — 任务管目标, worktree 管目录, 按 ID 绑定
---
@ -167,17 +167,17 @@ learn-claude-code/
| 课程 | 主题 | 格言 |
|------|------|------|
| [s01](./docs/zh/s01-the-agent-loop.md) | Agent 循环 | *One loop & Bash is all you need* |
| [s02](./docs/zh/s02-tool-use.md) | Tool Use | *循环没有变* |
| [s03](./docs/zh/s03-todo-write.md) | TodoWrite | *先计划再行动* |
| [s04](./docs/zh/s04-subagent.md) | 子智能体 | *进程隔离 = 上下文隔离* |
| [s05](./docs/zh/s05-skill-loading.md) | Skills | *按需加载, 而非预装* |
| [s06](./docs/zh/s06-context-compact.md) | Context Compact | *策略性遗忘* |
| [s07](./docs/zh/s07-task-system.md) | 任务系统 | *状态在压缩后存活* |
| [s08](./docs/zh/s08-background-tasks.md) | 后台任务 | *发射后不管* |
| [s09](./docs/zh/s09-agent-teams.md) | 智能体团队 | *追加即发送, 排空即读取* |
| [s10](./docs/zh/s10-team-protocols.md) | 团队协议 | *同一个 request_id, 两个协议* |
| [s11](./docs/zh/s11-autonomous-agents.md) | 自治智能体 | *轮询, 认领, 工作, 重复* |
| [s12](./docs/zh/s12-worktree-task-isolation.md) | Worktree + 任务隔离 | *目录隔离, 任务 ID 协调* |
| [s02](./docs/zh/s02-tool-use.md) | Tool Use | *加一个工具, 只加一个 handler* |
| [s03](./docs/zh/s03-todo-write.md) | TodoWrite | *没有计划的 agent 走哪算哪* |
| [s04](./docs/zh/s04-subagent.md) | 子智能体 | *大任务拆小, 每个小任务干净的上下文* |
| [s05](./docs/zh/s05-skill-loading.md) | Skills | *用到什么知识, 临时加载什么知识* |
| [s06](./docs/zh/s06-context-compact.md) | Context Compact | *上下文总会满, 要有办法腾地方* |
| [s07](./docs/zh/s07-task-system.md) | 任务系统 | *大目标要拆成小任务, 排好序, 记在磁盘上* |
| [s08](./docs/zh/s08-background-tasks.md) | 后台任务 | *慢操作丢后台, agent 继续想下一步* |
| [s09](./docs/zh/s09-agent-teams.md) | 智能体团队 | *任务太大一个人干不完, 要能分给队友* |
| [s10](./docs/zh/s10-team-protocols.md) | 团队协议 | *队友之间要有统一的沟通规矩* |
| [s11](./docs/zh/s11-autonomous-agents.md) | 自治智能体 | *队友自己看看板, 有活就认领* |
| [s12](./docs/zh/s12-worktree-task-isolation.md) | Worktree + 任务隔离 | *各干各的目录, 互不干扰* |
## 学完之后 -- 从理解到落地

44
README.md
View File

@ -26,27 +26,27 @@
> **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* |
| [s02](./docs/en/s02-tool-use.md) | Tool Use | *The loop didn't change* |
| [s03](./docs/en/s03-todo-write.md) | TodoWrite | *Plan before you act* |
| [s04](./docs/en/s04-subagent.md) | Subagents | *Process isolation = context isolation* |
| [s05](./docs/en/s05-skill-loading.md) | Skills | *Load on demand, not upfront* |
| [s06](./docs/en/s06-context-compact.md) | Context Compact | *Strategic forgetting* |
| [s07](./docs/en/s07-task-system.md) | Tasks | *State survives /compact* |
| [s08](./docs/en/s08-background-tasks.md) | Background Tasks | *Fire and forget* |
| [s09](./docs/en/s09-agent-teams.md) | Agent Teams | *Append to send, drain to read* |
| [s10](./docs/en/s10-team-protocols.md) | Team Protocols | *Same request_id, two protocols* |
| [s11](./docs/en/s11-autonomous-agents.md) | Autonomous Agents | *Poll, claim, work, repeat* |
| [s12](./docs/en/s12-worktree-task-isolation.md) | Worktree + Task Isolation | *Isolate by directory, coordinate by task ID* |
| [s02](./docs/en/s02-tool-use.md) | Tool Use | *Adding a tool means adding one handler* |
| [s03](./docs/en/s03-todo-write.md) | TodoWrite | *An agent without a plan drifts* |
| [s04](./docs/en/s04-subagent.md) | Subagents | *Break big tasks down; each subtask gets a clean context* |
| [s05](./docs/en/s05-skill-loading.md) | Skills | *Load knowledge when you need it, not upfront* |
| [s06](./docs/en/s06-context-compact.md) | Context Compact | *Context will fill up; you need a way to make room* |
| [s07](./docs/en/s07-task-system.md) | Tasks | *Break big goals into small tasks, order them, persist to disk* |
| [s08](./docs/en/s08-background-tasks.md) | Background Tasks | *Run slow operations in the background; the agent keeps thinking* |
| [s09](./docs/en/s09-agent-teams.md) | Agent Teams | *When the task is too big for one, delegate to teammates* |
| [s10](./docs/en/s10-team-protocols.md) | Team Protocols | *Teammates need shared communication rules* |
| [s11](./docs/en/s11-autonomous-agents.md) | Autonomous Agents | *Teammates scan the board and claim tasks themselves* |
| [s12](./docs/en/s12-worktree-task-isolation.md) | Worktree + Task Isolation | *Each works in its own directory, no interference* |
## What's Next -- from understanding to shipping

2
docs/en/s02-tool-use.md
View File

@ -2,7 +2,7 @@
`s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
> *"The loop didn't change"* -- adding tools means adding handlers, not rewriting the loop.
> *"Adding a tool means adding one handler"* -- the loop stays the same; new tools register into the dispatch map.
## Problem

2
docs/en/s03-todo-write.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
> *"Plan before you act"* -- visible plans improve task completion.
> *"An agent without a plan drifts"* -- list the steps first, then execute.
## Problem

2
docs/en/s04-subagent.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
> *"Process isolation = context isolation"* -- fresh messages[] per subagent.
> *"Break big tasks down; each subtask gets a clean context"* -- subagents use independent messages[], keeping the main conversation clean.
## Problem

2
docs/en/s05-skill-loading.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
> *"Load on demand, not upfront"* -- inject knowledge via tool_result, not system prompt.
> *"Load knowledge when you need it, not upfront"* -- inject via tool_result, not the system prompt.
## Problem

2
docs/en/s06-context-compact.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`
> *"Strategic forgetting"* -- forget old context to enable infinite sessions.
> *"Context will fill up; you need a way to make room"* -- three-layer compression strategy for infinite sessions.
## Problem

61
docs/en/s07-task-system.md
View File

@ -1,36 +1,52 @@
# s07: Tasks
# s07: Task System
`s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`
> *"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.
- **What's done?** -- `completed` tasks, whose completion automatically unblocks dependents.
```
.tasks/
task_1.json {"id":1, "status":"completed", ...}
task_1.json {"id":1, "status":"completed"}
task_2.json {"id":2, "blockedBy":[1], "status":"pending"}
task_3.json {"id":3, "blockedBy":[2], "status":"pending"}
task_3.json {"id":3, "blockedBy":[1], "status":"pending"}
task_4.json {"id":4, "blockedBy":[2,3], "status":"pending"}
Dependency resolution:
+----------+ +----------+ +----------+
| task 1 | --> | task 2 | --> | task 3 |
| complete | | blocked | | blocked |
+----------+ +----------+ +----------+
| ^
+--- completing task 1 removes it from
task 2's blockedBy list
Task graph (DAG):
+----------+
+--> | task 2 | --+
| | pending | |
+----------+ +----------+ +--> +----------+
| task 1 | | task 4 |
| completed| --> +----------+ +--> | blocked |
+----------+ | task 3 | --+ +----------+
| pending |
+----------+
Ordering: task 1 must finish before 2 and 3
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.
```python
def _clear_dependency(self, completed_id):
@ -59,7 +75,7 @@ def _clear_dependency(self, completed_id):
self._save(task)
```
3. `update` handles status transitions and dependency wiring.
3. **Status + dependency wiring**: `update` handles transitions and dependency edges.
```python
def update(self, task_id, status=None,
@ -84,16 +100,17 @@ TOOL_HANDLERS = {
}
```
From s07 onward, Task is the default for multi-step work. Todo remains for quick checklists.
From s07 onward, the task graph is the default for multi-step work. s03's Todo remains for quick single-session checklists.
## What Changed From s06
| Component | Before (s06) | After (s07) |
|---|---|---|
| Tools | 5 | 8 (`task_create/update/list/get`) |
| State storage | In-memory only | JSON files in `.tasks/` |
| Dependencies | None | `blockedBy + blocks` graph |
| Persistence | Lost on compact | Survives compression |
| Planning model | Flat checklist (in-memory) | Task graph with dependencies (on disk) |
| Relationships | None | `blockedBy` + `blocks` edges |
| Status tracking | Done or not | `pending` -> `in_progress` -> `completed` |
| Persistence | Lost on compression | Survives compression and restarts |
## Try It
@ -105,4 +122,4 @@ python agents/s07_task_system.py
1. `Create 3 tasks: "Setup project", "Write code", "Write tests". Make them depend on each other in order.`
2. `List all tasks and show the dependency graph`
3. `Complete task 1 and then list tasks to see task 2 unblocked`
4. `Create a task board for refactoring: parse -> transform -> emit -> test`
4. `Create a task board for refactoring: parse -> transform -> emit -> test, where transform and emit can run in parallel after parse`

2
docs/en/s08-background-tasks.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`
> *"Fire and forget"* -- non-blocking threads + notification queue.
> *"Run slow operations in the background; the agent keeps thinking"* -- daemon threads run commands, inject notifications on completion.
## Problem

2
docs/en/s09-agent-teams.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
> *"Append to send, drain to read"* -- async mailboxes for persistent teammates.
> *"When the task is too big for one, delegate to teammates"* -- persistent teammates + async mailboxes.
## Problem

2
docs/en/s10-team-protocols.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`
> *"Same request_id, two protocols"* -- one FSM pattern powers shutdown + plan approval.
> *"Teammates need shared communication rules"* -- one request-response pattern drives all negotiation.
## Problem

2
docs/en/s11-autonomous-agents.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
> *"Poll, claim, work, repeat"* -- no coordinator needed, agents self-organize.
> *"Teammates scan the board and claim tasks themselves"* -- no need for the lead to assign each one.
## Problem

2
docs/en/s12-worktree-task-isolation.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`
> *"Isolate by directory, coordinate by task ID"* -- task board + optional worktree lanes.
> *"Each works in its own directory, no interference"* -- tasks manage goals, worktrees manage directories, bound by ID.
## Problem

2
docs/ja/s02-tool-use.md
View File

@ -2,7 +2,7 @@
`s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
> *"The loop didn't change"* -- ツール追加はハンドラ追加であり、ループの書き換えではない。
> *"ツールを足すなら、ハンドラーを1つ足すだけ"* -- ループは変わらない。新ツールは dispatch map に登録するだけ。
## 問題

2
docs/ja/s03-todo-write.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
> *"Plan before you act"* -- 可視化された計画がタスク完了率を向上させる。
> *"計画のないエージェントは行き当たりばったり"* -- まずステップを書き出し、それから実行。
## 問題

2
docs/ja/s04-subagent.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
> *"Process isolation = context isolation"* -- サブエージェントごとに新しいmessages[]。
> *"大きなタスクを分割し、各サブタスクにクリーンなコンテキストを"* -- サブエージェントは独立した messages[] を使い、メイン会話を汚さない。
## 問題

2
docs/ja/s05-skill-loading.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
> *"Load on demand, not upfront"* -- 知識はsystem promptではなくtool_result経由で注入する。
> *"必要な知識を、必要な時に読み込む"* -- system prompt ではなく tool_result で注入。
## 問題

2
docs/ja/s06-context-compact.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`
> *"Strategic forgetting"* -- 古いコンテキストを忘れることで無限セッションを実現する。
> *"コンテキストはいつか溢れる、空ける手段が要る"* -- 3層圧縮で無限セッションを実現。
## 問題

63
docs/ja/s07-task-system.md
View File

@ -1,36 +1,52 @@
# s07: Tasks
# s07: Task System
`s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`
> *"State survives /compact"* -- ファイルベースの状態はコンテキスト圧縮を生き延びる。
> *"大きな目標を小タスクに分解し、順序付けし、ディスクに記録する"* -- ファイルベースのタスクグラフ、マルチエージェント協調の基盤。
## 問題
インメモリ状態(s03のTodoManager)はコンテキスト圧縮(s06)で消える。auto_compactがメッセージを要約に置換した後、todoリストは失われる。要約テキストからの復元は不正確で脆い。
s03のTodoManagerはメモリ上のフラットなチェックリストに過ぎない: 順序なし、依存関係なし、ステータスは完了か未完了のみ。実際の目標には構造がある -- タスクBはタスクAに依存し、タスクCとDは並行実行でき、タスクEはCとDの両方を待つ。
ファイルベースのタスクがこれを解決する: 状態をディスクに書き込めば、圧縮もプロセス再起動も生き延び、やがてマルチエージェントでの共有(s09+)も可能になる。
明示的な関係がなければ、エージェントは何が実行可能で、何がブロックされ、何が同時に走れるかを判断できない。しかもリストはメモリ上にしかないため、コンテキスト圧縮(s06)で消える。
## 解決策
フラットなチェックリストをディスクに永続化する**タスクグラフ**に昇格させる。各タスクは1つのJSONファイルで、ステータス・前方依存(`blockedBy`)・後方依存(`blocks`)を持つ。タスクグラフは常に3つの問いに答える:
- **何が実行可能か?** -- `pending`ステータスで`blockedBy`が空のタスク。
- **何がブロックされているか?** -- 未完了の依存を待つタスク。
- **何が完了したか?** -- `completed`のタスク。完了時に後続タスクを自動的にアンブロックする。
```
.tasks/
task_1.json {"id":1, "status":"completed", ...}
task_1.json {"id":1, "status":"completed"}
task_2.json {"id":2, "blockedBy":[1], "status":"pending"}
task_3.json {"id":3, "blockedBy":[2], "status":"pending"}
task_3.json {"id":3, "blockedBy":[1], "status":"pending"}
task_4.json {"id":4, "blockedBy":[2,3], "status":"pending"}
Dependency resolution:
+----------+ +----------+ +----------+
| task 1 | --> | task 2 | --> | task 3 |
| complete | | blocked | | blocked |
+----------+ +----------+ +----------+
| ^
+--- completing task 1 removes it from
task 2's blockedBy list
タスクグラフ (DAG):
+----------+
+--> | task 2 | --+
| | pending | |
+----------+ +----------+ +--> +----------+
| task 1 | | task 4 |
| completed| --> +----------+ +--> | blocked |
+----------+ | task 3 | --+ +----------+
| pending |
+----------+
順序: task 1 は 2 と 3 より先に完了する必要がある
並行: task 2 と 3 は同時に実行できる
依存: task 4 は 2 と 3 の両方を待つ
ステータス: pending -> in_progress -> completed
```
このタスクグラフは s07 以降の全メカニズムの協調バックボーンとなる: バックグラウンド実行(s08)、マルチエージェントチーム(s09+)、worktree分離(s12)はすべてこの同じ構造を読み書きする。
## 仕組み
1. TaskManager: タスクごとに1つのJSONファイル、依存グラフ付きCRUD。
1. **TaskManager**: タスクごとに1つのJSONファイル、依存グラフ付きCRUD。
```python
class TaskManager:
@ -48,7 +64,7 @@ class TaskManager:
return json.dumps(task, indent=2)
```
2. タスク完了時に、他タスクの`blockedBy`リストから完了IDを除去する。
2. **依存解除**: タスク完了時に、他タスクの`blockedBy`リストから完了IDを除去し、後続タスクをアンブロックする。
```python
def _clear_dependency(self, completed_id):
@ -59,7 +75,7 @@ def _clear_dependency(self, completed_id):
self._save(task)
```
3. `update`が状態遷移と依存配線を担う。
3. **ステータス遷移 + 依存配線**: `update`がステータス変更と依存エッジを担う。
```python
def update(self, task_id, status=None,
@ -84,16 +100,17 @@ TOOL_HANDLERS = {
}
```
s07以降、Taskがマルチステップ作業のデフォルト。Todoは軽量チェックリスト用に残る。
s07以降、タスクグラフがマルチステップ作業のデフォルト。s03のTodoは軽量な単一セッション用チェックリストとして残る。
## s06からの変更点
| Component | Before (s06) | After (s07) |
| コンポーネント | Before (s06) | After (s07) |
|---|---|---|
| Tools | 5 | 8 (`task_create/update/list/get`) |
| State storage | In-memory only | JSON files in `.tasks/` |
| Dependencies | None | `blockedBy + blocks` graph |
| Persistence | Lost on compact | Survives compression |
| 計画モデル | フラットチェックリスト (メモリ) | 依存関係付きタスクグラフ (ディスク) |
| 関係 | なし | `blockedBy` + `blocks` エッジ |
| ステータス追跡 | 完了か未完了 | `pending` -> `in_progress` -> `completed` |
| 永続性 | 圧縮で消失 | 圧縮・再起動後も存続 |
## 試してみる
@ -105,4 +122,4 @@ python agents/s07_task_system.py
1. `Create 3 tasks: "Setup project", "Write code", "Write tests". Make them depend on each other in order.`
2. `List all tasks and show the dependency graph`
3. `Complete task 1 and then list tasks to see task 2 unblocked`
4. `Create a task board for refactoring: parse -> transform -> emit -> test`
4. `Create a task board for refactoring: parse -> transform -> emit -> test, where transform and emit can run in parallel after parse`

2
docs/ja/s08-background-tasks.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`
> *"Fire and forget"* -- ノンブロッキングスレッド + 通知キュー。
> *"遅い操作はバックグラウンドへ、エージェントは次を考え続ける"* -- デーモンスレッドがコマンド実行、完了後に通知を注入。
## 問題

2
docs/ja/s09-agent-teams.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
> *"Append to send, drain to read"* -- 永続的なチームメイトのための非同期メールボックス。
> *"一人で終わらないなら、チームメイトに任せる"* -- 永続チームメイト + 非同期メールボックス。
## 問題

2
docs/ja/s10-team-protocols.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`
> *"Same request_id, two protocols"* -- 1つのFSMパターンがシャットダウンとプラン承認の両方を支える。
> *"チームメイト間には統一の通信ルールが必要"* -- 1つの request-response パターンが全交渉を駆動。
## 問題

2
docs/ja/s11-autonomous-agents.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
> *"Poll, claim, work, repeat"* -- コーディネーター不要、エージェントが自己組織化する。
> *"チームメイトが自らボードを見て、仕事を取る"* -- リーダーが逐一割り振る必要はない。
## 問題

2
docs/ja/s12-worktree-task-isolation.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`
> *"Isolate by directory, coordinate by task ID"* -- タスクボード + worktreeレーンで並行作業を分離する。
> *"各自のディレクトリで作業し、互いに干渉しない"* -- タスクは目標を管理、worktree はディレクトリを管理、IDで紐付け。
## 問題

2
docs/zh/s02-tool-use.md
View File

@ -2,7 +2,7 @@
`s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
> *"The loop didn't change"* -- 加工具就是加 handler, 不是重写循环。
> *"加一个工具, 只加一个 handler"* -- 循环不用动, 新工具注册进 dispatch map 就行。
## 问题

2
docs/zh/s03-todo-write.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
> *"Plan before you act"* -- 先列计划, 完成率翻倍。
> *"没有计划的 agent 走哪算哪"* -- 先列步骤再动手, 完成率翻倍。
## 问题

2
docs/zh/s04-subagent.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
> *"Process isolation = context isolation"* -- 每个子智能体拿到一个干净的 messages[]。
> *"大任务拆小, 每个小任务干净的上下文"* -- 子智能体用独立 messages[], 不污染主对话。
## 问题

2
docs/zh/s05-skill-loading.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
> *"Load on demand, not upfront"* -- 知识通过 tool_result 按需注入, 别塞进 system prompt。
> *"用到什么知识, 临时加载什么知识"* -- 通过 tool_result 注入, 不塞 system prompt。
## 问题

2
docs/zh/s06-context-compact.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`
> *"Strategic forgetting"* -- 有策略地遗忘, 换来无限会话。
> *"上下文总会满, 要有办法腾地方"* -- 三层压缩策略, 换来无限会话。
## 问题

61
docs/zh/s07-task-system.md
View File

@ -1,36 +1,52 @@
# s07: Tasks (任务系统)
# s07: Task System (任务系统)
`s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`
> *"State survives /compact"* -- 写进文件的状态, 压缩也杀不死。
> *"大目标要拆成小任务, 排好序, 记在磁盘上"* -- 文件持久化的任务图, 为多 agent 协作打基础。
## 问题
内存里的状态 (s03 的 TodoManager) 扛不住上下文压缩 (s06)。auto_compact 一跑, 消息被摘要替换, todo list 就没了。智能体只能从摘要文本里猜 -- 有损且容易出错。
s03 的 TodoManager 只是内存中的扁平清单: 没有顺序、没有依赖、状态只有做完没做完。真实目标是有结构的 -- 任务 B 依赖任务 A, 任务 C 和 D 可以并行, 任务 E 要等 C 和 D 都完成。
写到磁盘就不一样了: 文件状态能扛住压缩、进程重启, 后面还能给多个智能体共享 (s09+)。
没有显式的关系, 智能体分不清什么能做、什么被卡住、什么能同时跑。而且清单只活在内存里, 上下文压缩 (s06) 一跑就没了。
## 解决方案
把扁平清单升级为持久化到磁盘的**任务图**。每个任务是一个 JSON 文件, 有状态、前置依赖 (`blockedBy`) 和后置依赖 (`blocks`)。任务图随时回答三个问题:
- **什么可以做?** -- 状态为 `pending` 且 `blockedBy` 为空的任务。
- **什么被卡住?** -- 等待前置任务完成的任务。
- **什么做完了?** -- 状态为 `completed` 的任务, 完成时自动解锁后续任务。
```
.tasks/
task_1.json {"id":1, "status":"completed", ...}
task_1.json {"id":1, "status":"completed"}
task_2.json {"id":2, "blockedBy":[1], "status":"pending"}
task_3.json {"id":3, "blockedBy":[2], "status":"pending"}
task_3.json {"id":3, "blockedBy":[1], "status":"pending"}
task_4.json {"id":4, "blockedBy":[2,3], "status":"pending"}
Dependency resolution:
+----------+ +----------+ +----------+
| task 1 | --> | task 2 | --> | task 3 |
| complete | | blocked | | blocked |
+----------+ +----------+ +----------+
| ^
+--- completing task 1 removes it from
task 2's blockedBy list
任务图 (DAG):
+----------+
+--> | task 2 | --+
| | pending | |
+----------+ +----------+ +--> +----------+
| task 1 | | task 4 |
| completed| --> +----------+ +--> | blocked |
+----------+ | task 3 | --+ +----------+
| pending |
+----------+
顺序: task 1 必须先完成, 才能开始 2 和 3
并行: task 2 和 3 可以同时执行
依赖: task 4 要等 2 和 3 都完成
状态: pending -> in_progress -> completed
```
这个任务图是 s07 之后所有机制的协调骨架: 后台执行 (s08)、多 agent 团队 (s09+)、worktree 隔离 (s12) 都读写这同一个结构。
## 工作原理
1. TaskManager: 每个任务一个 JSON 文件, CRUD + 依赖图。
1. **TaskManager**: 每个任务一个 JSON 文件, CRUD + 依赖图。
```python
class TaskManager:
@ -48,7 +64,7 @@ class TaskManager:
return json.dumps(task, indent=2)
```
2. 完成任务时, 自动将其 ID 从其他任务的 `blockedBy` 中移除。
2. **依赖解除**: 完成任务时, 自动将其 ID 从其他任务的 `blockedBy` 中移除, 解锁后续任务。
```python
def _clear_dependency(self, completed_id):
@ -59,7 +75,7 @@ def _clear_dependency(self, completed_id):
self._save(task)
```
3. `update` 处理状态变更和依赖关联。
3. **状态变更 + 依赖关联**: `update` 处理状态转换和依赖边。
```python
def update(self, task_id, status=None,
@ -84,16 +100,17 @@ TOOL_HANDLERS = {
}
```
从 s07 起, Task 是多步工作的默认选择。Todo 仍可用于快速清单。
从 s07 起, 任务图是多步工作的默认选择。s03 的 Todo 仍可用于单次会话内的快速清单。
## 相对 s06 的变更
| 组件 | 之前 (s06) | 之后 (s07) |
|---|---|---|
| Tools | 5 | 8 (`task_create/update/list/get`) |
| 状态存储 | 仅内存 | `.tasks/` 中的 JSON 文件 |
| 依赖关系 | 无 | `blockedBy + blocks` 图 |
| 持久化 | 压缩后丢失 | 压缩后存活 |
| 规划模型 | 扁平清单 (仅内存) | 带依赖关系的任务图 (磁盘) |
| 关系 | 无 | `blockedBy` + `blocks` 边 |
| 状态追踪 | 做完没做完 | `pending` -> `in_progress` -> `completed` |
| 持久化 | 压缩后丢失 | 压缩和重启后存活 |
## 试一试
@ -107,4 +124,4 @@ python agents/s07_task_system.py
1. `Create 3 tasks: "Setup project", "Write code", "Write tests". Make them depend on each other in order.`
2. `List all tasks and show the dependency graph`
3. `Complete task 1 and then list tasks to see task 2 unblocked`
4. `Create a task board for refactoring: parse -> transform -> emit -> test`
4. `Create a task board for refactoring: parse -> transform -> emit -> test, where transform and emit can run in parallel after parse`

2
docs/zh/s08-background-tasks.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`
> *"Fire and forget"* -- 发射后不管: 非阻塞线程 + 通知队列。
> *"慢操作丢后台, agent 继续想下一步"* -- 后台线程跑命令, 完成后注入通知。
## 问题

2
docs/zh/s09-agent-teams.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
> *"Append to send, drain to read"* -- 追加即发送, 排空即读取: 异步邮箱让队友能持久通信。
> *"任务太大一个人干不完, 要能分给队友"* -- 持久化队友 + JSONL 邮箱。
## 问题

2
docs/zh/s10-team-protocols.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`
> *"Same request_id, two protocols"* -- 一个 FSM 模式, 同时驱动关机和计划审批。
> *"队友之间要有统一的沟通规矩"* -- 一个 request-response 模式驱动所有协商。
## 问题

2
docs/zh/s11-autonomous-agents.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
> *"Poll, claim, work, repeat"* -- 不需要协调者, 智能体自己找活干。
> *"队友自己看看板, 有活就认领"* -- 不需要领导逐个分配, 自组织。
## 问题

2
docs/zh/s12-worktree-task-isolation.md
View File

@ -2,7 +2,7 @@
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`
> *"Isolate by directory, coordinate by task ID"* -- 任务板管目标, worktree 管执行, 用任务 ID 绑定。
> *"各干各的目录, 互不干扰"* -- 任务管目标, worktree 管目录, 按 ID 绑定。
## 问题

78
web/src/data/generated/docs.json
View File

File diff suppressed because one or more lines are too long

38
web/src/data/generated/versions.json
View File

@ -34,7 +34,7 @@
"id": "s02",
"filename": "s02_tool_use.py",
"title": "Tools",
"subtitle": "The Loop Didn't Change",
"subtitle": "One Handler Per Tool",
"loc": 115,
"tools": [
"bash",
@ -48,7 +48,7 @@
"edit_file"
],
"coreAddition": "Tool dispatch map",
"keyInsight": "Adding tools means adding handlers, not rewriting the loop",
"keyInsight": "The loop stays the same; new tools register into the dispatch map",
"classes": [],
"functions": [
{
@ -102,7 +102,7 @@
"todo"
],
"coreAddition": "TodoManager + nag reminder",
"keyInsight": "Visible plans improve task completion and accountability",
"keyInsight": "An agent without a plan drifts; list the steps first, then execute",
"classes": [
{
"name": "TodoManager",
@ -149,7 +149,7 @@
"id": "s04",
"filename": "s04_subagent.py",
"title": "Subagents",
"subtitle": "Process Isolation = Context Isolation",
"subtitle": "Clean Context Per Subtask",
"loc": 146,
"tools": [
"bash",
@ -162,7 +162,7 @@
"task"
],
"coreAddition": "Subagent spawn with isolated messages[]",
"keyInsight": "Process isolation gives context isolation for free",
"keyInsight": "Subagents use independent messages[], keeping the main conversation clean",
"classes": [],
"functions": [
{
@ -208,7 +208,7 @@
"id": "s05",
"filename": "s05_skill_loading.py",
"title": "Skills",
"subtitle": "SKILL.md + tool_result Injection",
"subtitle": "Load on Demand",
"loc": 177,
"tools": [
"bash",
@ -221,7 +221,7 @@
"load_skill"
],
"coreAddition": "SkillLoader + two-layer injection",
"keyInsight": "Skills inject via tool_result, not system prompt",
"keyInsight": "Inject knowledge via tool_result when needed, not upfront in the system prompt",
"classes": [
{
"name": "SkillLoader",
@ -268,7 +268,7 @@
"id": "s06",
"filename": "s06_context_compact.py",
"title": "Compact",
"subtitle": "Strategic Forgetting",
"subtitle": "Three-Layer Compression",
"loc": 200,
"tools": [
"bash",
@ -281,7 +281,7 @@
"compact"
],
"coreAddition": "micro-compact + auto-compact + archival",
"keyInsight": "Forgetting old context enables infinite-length sessions",
"keyInsight": "Context will fill up; three-layer compression strategy enables infinite sessions",
"classes": [],
"functions": [
{
@ -337,7 +337,7 @@
"id": "s07",
"filename": "s07_task_system.py",
"title": "Tasks",
"subtitle": "Persistent CRUD with Dependencies",
"subtitle": "Task Graph + Dependencies",
"loc": 202,
"tools": [
"bash",
@ -356,7 +356,7 @@
"task_get"
],
"coreAddition": "TaskManager with file-based state + dependency graph",
"keyInsight": "File-based state survives context compression",
"keyInsight": "A file-based task graph with ordering, parallelism, and dependencies -- the coordination backbone for multi-agent work",
"classes": [
{
"name": "TaskManager",
@ -403,7 +403,7 @@
"id": "s08",
"filename": "s08_background_tasks.py",
"title": "Background Tasks",
"subtitle": "Fire and Forget",
"subtitle": "Background Threads + Notifications",
"loc": 193,
"tools": [
"bash",
@ -418,7 +418,7 @@
"check_background"
],
"coreAddition": "BackgroundManager + notification queue",
"keyInsight": "Non-blocking daemon threads + notification queue",
"keyInsight": "Run slow operations in the background; the agent keeps thinking ahead",
"classes": [
{
"name": "BackgroundManager",
@ -488,7 +488,7 @@
"broadcast"
],
"coreAddition": "TeammateManager + file-based mailbox",
"keyInsight": "Persistent teammates with async mailbox inboxes",
"keyInsight": "When one agent can't finish, delegate to persistent teammates via async mailboxes",
"classes": [
{
"name": "MessageBus",
@ -540,7 +540,7 @@
"id": "s10",
"filename": "s10_team_protocols.py",
"title": "Team Protocols",
"subtitle": "Shutdown + Plan Approval",
"subtitle": "Shared Communication Rules",
"loc": 414,
"tools": [
"bash",
@ -562,7 +562,7 @@
"shutdown_request"
],
"coreAddition": "request_id correlation for two protocols",
"keyInsight": "Same request-response pattern, two applications",
"keyInsight": "One request-response pattern drives all team negotiation",
"classes": [
{
"name": "MessageBus",
@ -629,7 +629,7 @@
"id": "s11",
"filename": "s11_autonomous_agents.py",
"title": "Autonomous Agents",
"subtitle": "Idle Cycle + Auto-Claim",
"subtitle": "Scan Board, Claim Tasks",
"loc": 494,
"tools": [
"bash",
@ -652,7 +652,7 @@
"claim_task"
],
"coreAddition": "Task board polling + timeout-based self-governance",
"keyInsight": "Polling + timeout makes teammates self-organizing",
"keyInsight": "Teammates scan the board and claim tasks themselves; no need for the lead to assign each one",
"classes": [
{
"name": "MessageBus",
@ -769,7 +769,7 @@
"worktree_events"
],
"coreAddition": "Composable worktree lifecycle + event stream over a shared task board",
"keyInsight": "Task board coordinates ownership, worktrees isolate execution, and events make lifecycle auditable",
"keyInsight": "Each works in its own directory; tasks manage goals, worktrees manage directories, bound by ID",
"classes": [
{
"name": "EventBus",

22
web/src/lib/constants.ts
View File

@ -15,17 +15,17 @@ export const VERSION_META: Record<string, {
prevVersion: string | null;
}> = {
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" },
s06: { title: "Compact", subtitle: "Strategic Forgetting", coreAddition: "micro-compact + auto-compact + archival", keyInsight: "Forgetting old context enables infinite-length sessions", layer: "memory", prevVersion: "s05" },
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" },
s08: { title: "Background Tasks", subtitle: "Fire and Forget", coreAddition: "BackgroundManager + notification queue", keyInsight: "Non-blocking daemon threads + notification queue", layer: "concurrency", prevVersion: "s07" },
s09: { title: "Agent Teams", subtitle: "Teammates + Mailboxes", coreAddition: "TeammateManager + file-based mailbox", keyInsight: "Persistent teammates with async mailbox inboxes", layer: "collaboration", prevVersion: "s08" },
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" },
s11: { title: "Autonomous Agents", subtitle: "Idle Cycle + Auto-Claim", coreAddition: "Task board polling + timeout-based self-governance", keyInsight: "Polling + timeout makes teammates self-organizing", 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: "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" },
};
export const LAYERS = [