Merge remote-tracking branch 'upstream/main' into copilot/resolve-code-branch-conflicts

Copilot · Copilot · commit 4fc9ff65a3a2 · 2026-03-19T03:00:25.000Z
# Conflicts:
#	README-zh.md
#	docs/zh/s01-the-agent-loop.md
#	docs/zh/s04-subagent.md
diff --git a/README-ja.md b/README-ja.md
diff --git a/README-zh.md b/README-zh.md
diff --git a/README.md b/README.md
diff --git a/agents/__init__.py b/agents/__init__.py
@@ -1,2 +1,3 @@
-# agents/ - Python teaching agents (s01-s12) + reference agent (s_full)
+# agents/ - Harness implementations (s01-s12) + full reference (s_full)
 # Each file is self-contained and runnable: python agents/s01_agent_loop.py
+# The model is the agent. These files are the harness.
diff --git a/agents/s01_agent_loop.py b/agents/s01_agent_loop.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: the loop -- the model's first connection to the real world.
 """
 s01_agent_loop.py - The Agent Loop
 
diff --git a/agents/s02_tool_use.py b/agents/s02_tool_use.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: tool dispatch -- expanding what the model can reach.
 """
 s02_tool_use.py - Tools
 
diff --git a/agents/s03_todo_write.py b/agents/s03_todo_write.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: planning -- keeping the model on course without scripting the route.
 """
 s03_todo_write.py - TodoWrite
 
diff --git a/agents/s04_subagent.py b/agents/s04_subagent.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: context isolation -- protecting the model's clarity of thought.
 """
 s04_subagent.py - Subagents
 
diff --git a/agents/s05_skill_loading.py b/agents/s05_skill_loading.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: on-demand knowledge -- domain expertise, loaded when the model asks.
 """
 s05_skill_loading.py - Skills
 
diff --git a/agents/s06_context_compact.py b/agents/s06_context_compact.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: compression -- clean memory for infinite sessions.
 """
 s06_context_compact.py - Compact
 
diff --git a/agents/s07_task_system.py b/agents/s07_task_system.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: persistent tasks -- goals that outlive any single conversation.
 """
 s07_task_system.py - Tasks
 
diff --git a/agents/s08_background_tasks.py b/agents/s08_background_tasks.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: background execution -- the model thinks while the harness waits.
 """
 s08_background_tasks.py - Background Tasks
 
diff --git a/agents/s09_agent_teams.py b/agents/s09_agent_teams.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: team mailboxes -- multiple models, coordinated through files.
 """
 s09_agent_teams.py - Agent Teams
 
diff --git a/agents/s10_team_protocols.py b/agents/s10_team_protocols.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: protocols -- structured handshakes between models.
 """
 s10_team_protocols.py - Team Protocols
 
diff --git a/agents/s11_autonomous_agents.py b/agents/s11_autonomous_agents.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: autonomy -- models that find work without being told.
 """
 s11_autonomous_agents.py - Autonomous Agents
 
diff --git a/agents/s12_worktree_task_isolation.py b/agents/s12_worktree_task_isolation.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: directory isolation -- parallel execution lanes that never collide.
 """
 s12_worktree_task_isolation.py - Worktree + Task Isolation
 
diff --git a/agents/s_full.py b/agents/s_full.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: all mechanisms combined -- the complete cockpit for the model.
 """
 s_full.py - Full Reference Agent
 
diff --git a/docs/en/s01-the-agent-loop.md b/docs/en/s01-the-agent-loop.md
@@ -3,6 +3,8 @@
 `[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"One loop & Bash is all you need"* -- one tool + one loop = an agent.
+>
+> **Harness layer**: The loop -- the model's first connection to the real world.
 
 ## Problem
 
diff --git a/docs/en/s02-tool-use.md b/docs/en/s02-tool-use.md
@@ -3,6 +3,8 @@
 `s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"Adding a tool means adding one handler"* -- the loop stays the same; new tools register into the dispatch map.
+>
+> **Harness layer**: Tool dispatch -- expanding what the model can reach.
 
 ## Problem
 
diff --git a/docs/en/s03-todo-write.md b/docs/en/s03-todo-write.md
@@ -3,6 +3,8 @@
 `s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"An agent without a plan drifts"* -- list the steps first, then execute.
+>
+> **Harness layer**: Planning -- keeping the model on course without scripting the route.
 
 ## Problem
 
diff --git a/docs/en/s04-subagent.md b/docs/en/s04-subagent.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"Break big tasks down; each subtask gets a clean context"* -- subagents use independent messages[], keeping the main conversation clean.
+>
+> **Harness layer**: Context isolation -- protecting the model's clarity of thought.
 
 ## Problem
 
diff --git a/docs/en/s05-skill-loading.md b/docs/en/s05-skill-loading.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"Load knowledge when you need it, not upfront"* -- inject via tool_result, not the system prompt.
+>
+> **Harness layer**: On-demand knowledge -- domain expertise, loaded when the model asks.
 
 ## Problem
 
diff --git a/docs/en/s06-context-compact.md b/docs/en/s06-context-compact.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"Context will fill up; you need a way to make room"* -- three-layer compression strategy for infinite sessions.
+>
+> **Harness layer**: Compression -- clean memory for infinite sessions.
 
 ## Problem
 
diff --git a/docs/en/s07-task-system.md b/docs/en/s07-task-system.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`
 
 > *"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.
+>
+> **Harness layer**: Persistent tasks -- goals that outlive any single conversation.
 
 ## Problem
 
diff --git a/docs/en/s08-background-tasks.md b/docs/en/s08-background-tasks.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`
 
 > *"Run slow operations in the background; the agent keeps thinking"* -- daemon threads run commands, inject notifications on completion.
+>
+> **Harness layer**: Background execution -- the model thinks while the harness waits.
 
 ## Problem
 
diff --git a/docs/en/s09-agent-teams.md b/docs/en/s09-agent-teams.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
 
 > *"When the task is too big for one, delegate to teammates"* -- persistent teammates + async mailboxes.
+>
+> **Harness layer**: Team mailboxes -- multiple models, coordinated through files.
 
 ## Problem
 
diff --git a/docs/en/s10-team-protocols.md b/docs/en/s10-team-protocols.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`
 
 > *"Teammates need shared communication rules"* -- one request-response pattern drives all negotiation.
+>
+> **Harness layer**: Protocols -- structured handshakes between models.
 
 ## Problem
 
diff --git a/docs/en/s11-autonomous-agents.md b/docs/en/s11-autonomous-agents.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
 
 > *"Teammates scan the board and claim tasks themselves"* -- no need for the lead to assign each one.
+>
+> **Harness layer**: Autonomy -- models that find work without being told.
 
 ## Problem
 
diff --git a/docs/en/s12-worktree-task-isolation.md b/docs/en/s12-worktree-task-isolation.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`
 
 > *"Each works in its own directory, no interference"* -- tasks manage goals, worktrees manage directories, bound by ID.
+>
+> **Harness layer**: Directory isolation -- parallel execution lanes that never collide.
 
 ## Problem
 
diff --git a/docs/ja/s01-the-agent-loop.md b/docs/ja/s01-the-agent-loop.md
@@ -3,6 +3,8 @@
 `[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"One loop & Bash is all you need"* -- 1つのツール + 1つのループ = エージェント。
+>
+> **Harness 層**: ループ -- モデルと現実世界を繋ぐ最初の接点。
 
 ## 問題
 
diff --git a/docs/ja/s02-tool-use.md b/docs/ja/s02-tool-use.md
@@ -3,6 +3,8 @@
 `s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"ツールを足すなら、ハンドラーを1つ足すだけ"* -- ループは変わらない。新ツールは dispatch map に登録するだけ。
+>
+> **Harness 層**: ツール分配 -- モデルが届く範囲を広げる。
 
 ## 問題
 
diff --git a/docs/ja/s03-todo-write.md b/docs/ja/s03-todo-write.md
@@ -3,6 +3,8 @@
 `s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"計画のないエージェントは行き当たりばったり"* -- まずステップを書き出し、それから実行。
+>
+> **Harness 層**: 計画 -- 航路を描かずにモデルを軌道に乗せる。
 
 ## 問題
 
diff --git a/docs/ja/s04-subagent.md b/docs/ja/s04-subagent.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"大きなタスクを分割し、各サブタスクにクリーンなコンテキストを"* -- サブエージェントは独立した messages[] を使い、メイン会話を汚さない。
+>
+> **Harness 層**: コンテキスト隔離 -- モデルの思考の明晰さを守る。
 
 ## 問題
 
diff --git a/docs/ja/s05-skill-loading.md b/docs/ja/s05-skill-loading.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"必要な知識を、必要な時に読み込む"* -- system prompt ではなく tool_result で注入。
+>
+> **Harness 層**: オンデマンド知識 -- モデルが求めた時だけ渡すドメイン専門性。
 
 ## 問題
 
diff --git a/docs/ja/s06-context-compact.md b/docs/ja/s06-context-compact.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"コンテキストはいつか溢れる、空ける手段が要る"* -- 3層圧縮で無限セッションを実現。
+>
+> **Harness 層**: 圧縮 -- クリーンな記憶、無限のセッション。
 
 ## 問題
 
diff --git a/docs/ja/s07-task-system.md b/docs/ja/s07-task-system.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`
 
 > *"大きな目標を小タスクに分解し、順序付けし、ディスクに記録する"* -- ファイルベースのタスクグラフ、マルチエージェント協調の基盤。
+>
+> **Harness 層**: 永続タスク -- どの会話よりも長く生きる目標。
 
 ## 問題
 
diff --git a/docs/ja/s08-background-tasks.md b/docs/ja/s08-background-tasks.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`
 
 > *"遅い操作はバックグラウンドへ、エージェントは次を考え続ける"* -- デーモンスレッドがコマンド実行、完了後に通知を注入。
+>
+> **Harness 層**: バックグラウンド実行 -- モデルが考え続ける間、Harness が待つ。
 
 ## 問題
 
diff --git a/docs/ja/s09-agent-teams.md b/docs/ja/s09-agent-teams.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
 
 > *"一人で終わらないなら、チームメイトに任せる"* -- 永続チームメイト + 非同期メールボックス。
+>
+> **Harness 層**: チームメールボックス -- 複数モデルをファイルで協調。
 
 ## 問題
 
diff --git a/docs/ja/s10-team-protocols.md b/docs/ja/s10-team-protocols.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`
 
 > *"チームメイト間には統一の通信ルールが必要"* -- 1つの request-response パターンが全交渉を駆動。
+>
+> **Harness 層**: プロトコル -- モデル間の構造化されたハンドシェイク。
 
 ## 問題
 
diff --git a/docs/ja/s11-autonomous-agents.md b/docs/ja/s11-autonomous-agents.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
 
 > *"チームメイトが自らボードを見て、仕事を取る"* -- リーダーが逐一割り振る必要はない。
+>
+> **Harness 層**: 自律 -- 指示なしで仕事を見つけるモデル。
 
 ## 問題
 
diff --git a/docs/ja/s12-worktree-task-isolation.md b/docs/ja/s12-worktree-task-isolation.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`
 
 > *"各自のディレクトリで作業し、互いに干渉しない"* -- タスクは目標を管理、worktree はディレクトリを管理、IDで紐付け。
+>
+> **Harness 層**: ディレクトリ隔離 -- 決して衝突しない並列実行レーン。
 
 ## 問題
 
diff --git a/docs/zh/s01-the-agent-loop.md b/docs/zh/s01-the-agent-loop.md
@@ -3,6 +3,8 @@
 `[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"One loop & Bash is all you need"* -- 一个工具 + 一个循环 = 一个 Agent。
+>
+> **Harness 层**: 循环 -- 模型与真实世界的第一道连接。
 
 ## 问题
 
diff --git a/docs/zh/s02-tool-use.md b/docs/zh/s02-tool-use.md
@@ -3,6 +3,8 @@
 `s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"加一个工具, 只加一个 handler"* -- 循环不用动, 新工具注册进 dispatch map 就行。
+>
+> **Harness 层**: 工具分发 -- 扩展模型能触达的边界。
 
 ## 问题
 
diff --git a/docs/zh/s03-todo-write.md b/docs/zh/s03-todo-write.md
@@ -3,6 +3,8 @@
 `s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"没有计划的 agent 走哪算哪"* -- 先列步骤再动手, 完成率翻倍。
+>
+> **Harness 层**: 规划 -- 让模型不偏航, 但不替它画航线。
 
 ## 问题
 
diff --git a/docs/zh/s04-subagent.md b/docs/zh/s04-subagent.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"大任务拆小, 每个小任务干净的上下文"* -- Subagent 用独立 messages[], 不污染主对话。
+>
+> **Harness 层**: 上下文隔离 -- 守护模型的思维清晰度。
 
 ## 问题
 
diff --git a/docs/zh/s05-skill-loading.md b/docs/zh/s05-skill-loading.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"用到什么知识, 临时加载什么知识"* -- 通过 tool_result 注入, 不塞 system prompt。
+>
+> **Harness 层**: 按需知识 -- 模型开口要时才给的领域专长。
 
 ## 问题
 
diff --git a/docs/zh/s06-context-compact.md b/docs/zh/s06-context-compact.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"上下文总会满, 要有办法腾地方"* -- 三层压缩策略, 换来无限会话。
+>
+> **Harness 层**: 压缩 -- 干净的记忆, 无限的会话。
 
 ## 问题
 
diff --git a/docs/zh/s07-task-system.md b/docs/zh/s07-task-system.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`
 
 > *"大目标要拆成小任务, 排好序, 记在磁盘上"* -- 文件持久化的任务图, 为多 agent 协作打基础。
+>
+> **Harness 层**: 持久化任务 -- 比任何一次对话都长命的目标。
 
 ## 问题
 
diff --git a/docs/zh/s08-background-tasks.md b/docs/zh/s08-background-tasks.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`
 
 > *"慢操作丢后台, agent 继续想下一步"* -- 后台线程跑命令, 完成后注入通知。
+>
+> **Harness 层**: 后台执行 -- 模型继续思考, harness 负责等待。
 
 ## 问题
 
diff --git a/docs/zh/s09-agent-teams.md b/docs/zh/s09-agent-teams.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
 
 > *"任务太大一个人干不完, 要能分给队友"* -- 持久化队友 + JSONL 邮箱。
+>
+> **Harness 层**: 团队邮箱 -- 多个模型, 通过文件协调。
 
 ## 问题
 
diff --git a/docs/zh/s10-team-protocols.md b/docs/zh/s10-team-protocols.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`
 
 > *"队友之间要有统一的沟通规矩"* -- 一个 request-response 模式驱动所有协商。
+>
+> **Harness 层**: 协议 -- 模型之间的结构化握手。
 
 ## 问题
 
diff --git a/docs/zh/s11-autonomous-agents.md b/docs/zh/s11-autonomous-agents.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
 
 > *"队友自己看看板, 有活就认领"* -- 不需要领导逐个分配, 自组织。
+>
+> **Harness 层**: 自治 -- 模型自己找活干, 无需指派。
 
 ## 问题
 
diff --git a/docs/zh/s12-worktree-task-isolation.md b/docs/zh/s12-worktree-task-isolation.md
diff --git a/skills/agent-builder/references/agent-philosophy.md b/skills/agent-builder/references/agent-philosophy.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#!/usr/bin/env python3`
	`2`	`+# Harness: the loop -- the model's first connection to the real world.`
`2`	`3`	`"""`
`3`	`4`	`s01_agent_loop.py - The Agent Loop`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#!/usr/bin/env python3`
	`2`	`+# Harness: tool dispatch -- expanding what the model can reach.`
`2`	`3`	`"""`
`3`	`4`	`s02_tool_use.py - Tools`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#!/usr/bin/env python3`
	`2`	`+# Harness: planning -- keeping the model on course without scripting the route.`
`2`	`3`	`"""`
`3`	`4`	`s03_todo_write.py - TodoWrite`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#!/usr/bin/env python3`
	`2`	`+# Harness: context isolation -- protecting the model's clarity of thought.`
`2`	`3`	`"""`
`3`	`4`	`s04_subagent.py - Subagents`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#!/usr/bin/env python3`
	`2`	`+# Harness: on-demand knowledge -- domain expertise, loaded when the model asks.`
`2`	`3`	`"""`
`3`	`4`	`s05_skill_loading.py - Skills`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#!/usr/bin/env python3`
	`2`	`+# Harness: compression -- clean memory for infinite sessions.`
`2`	`3`	`"""`
`3`	`4`	`s06_context_compact.py - Compact`
`4`	`5`