@jun133/athlete 0.0.2

package/spec/principles/P07-/344/273/273/345/212/241/345/233/276/350/246/201/350/220/275/347/233/230.md

@@ -0,0 +1,20 @@
+# P07 任务图要落盘
+
+## 原则
+
+大目标要拆成任务，而且任务不能只存在模型脑子里，要写到磁盘上。
+
+## 为什么
+
+只有落盘，任务才能恢复、共享、协作、追踪。
+
+## 在 Athlete 里的含义
+
+Athlete 当前已经有任务板真相源。
+
+下一阶段总指挥层要基于这套任务板继续长，而不是新发明一套平行任务宇宙。
+
+## 当前对应
+
+- `src/tasks/store.ts`
+- `src/tasks/types.ts`

package/spec/principles/P08-/346/205/242/346/223/215/344/275/234/346/224/276/345/220/216/345/217/260.md

@@ -0,0 +1,23 @@
+# P08 慢操作放后台
+
+## 原则
+
+慢操作不要堵住主循环，应该丢到后台跑。
+
+## 为什么
+
+这样 agent 可以一边等后台结果，一边继续做下一步。
+
+## 在 Athlete 里的含义
+
+background 不是附属功能，它是 Athlete 耐跑能力的一部分。
+
+总指挥层以后要会判断：
+
+- 哪些事自己现在就做
+- 哪些事应该丢给 background
+
+## 当前对应
+
+- `src/background/`
+- `src/tools/background/`

package/spec/principles/P09-/344/273/273/345/212/241/345/244/252/345/244/247/345/260/261/345/210/206/347/273/231/351/230/237/345/217/213.md

@@ -0,0 +1,21 @@
+# P09 任务太大就分给队友
+
+## 原则
+
+一个 agent 做不完的大任务，就要支持分给别的队友。
+
+## 为什么
+
+这样系统才能从“单智能体”升级到“多智能体协作”。
+
+## 在 Athlete 里的含义
+
+Athlete 未来不是默认 swarm，而是：
+
+- 主 Agent 仍然是核心
+- 复杂任务时按需分给 teammate
+
+## 当前对应
+
+- `src/team/`
+- `src/tools/team/spawnTeammateTool.ts`

package/spec/principles/P10-/351/230/237/345/217/213/344/271/213/351/227/264/350/246/201/346/234/211/347/273/237/344/270/200/345/215/217/350/256/256.md

@@ -0,0 +1,23 @@
+# P10 队友之间要有统一协议
+
+## 原则
+
+队友之间的协商不能靠自由文本临时约定，必须有统一的 request-response 模式。
+
+## 为什么
+
+如果每种协作都各写一套消息格式，系统会越来越多特例，最后协议就不再是唯一真相源。
+
+## 在 Athlete 里的含义
+
+信息通知可以是普通消息；
+
+但任何会改变协作状态的动作，都必须走协议化 request-response。
+
+## 当前对应
+
+- `src/team/requestStore.ts`
+- `src/team/messageBus.ts`
+- `src/tools/team/planApprovalTool.ts`
+- `src/tools/team/shutdownRequestTool.ts`
+- `src/tools/team/shutdownResponseTool.ts`

package/spec/principles/P11-/351/230/237/345/217/213/350/207/252/345/267/261/350/256/244/351/242/206/344/273/273/345/212/241.md

@@ -0,0 +1,25 @@
+# P11 队友自己认领任务
+
+## 原则
+
+队友不一定要等领导逐个分配，也可以自己看任务板、自己认领。
+
+## 为什么
+
+这样更接近自治系统，不会所有事都卡在一个中心节点上。
+
+## 在 Athlete 里的含义
+
+总指挥层不是永远手动给每个 teammate 写死指令。
+
+系统应该允许：
+
+- 明确指派
+- 自主认领
+
+两种协作方式并存。
+
+## 当前对应
+
+- `src/tasks/`
+- `src/team/worker.ts`

package/spec/principles/P12-/345/267/245/344/275/234/345/214/272/345/222/214/344/273/273/345/212/241/350/246/201/351/232/224/347/246/273.md

@@ -0,0 +1,20 @@
+# P12 工作区和任务要隔离
+
+## 原则
+
+任务和目录都要隔离，不能所有队友都在同一个工作目录里乱改。
+
+## 为什么
+
+只有隔离，多个任务并行时才不会互相污染。
+
+## 在 Athlete 里的含义
+
+- task 管目标
+- worktree 管目录
+- 两者通过绑定关系协同
+
+## 当前对应
+
+- `src/worktrees/store.ts`
+- `src/tools/worktrees/`

package/spec/principles/P13-session/346/230/257/344/273/273/345/212/241/347/216/260/345/234/272.md

@@ -0,0 +1,30 @@
+# P13 session 是任务现场
+
+## 原则
+
+session 不是聊天记录附件，而是任务现场。
+
+## 为什么
+
+Athlete 的核心价值之一是长任务不中断。
+
+如果 session 只是普通历史消息：
+
+- 续跑价值会很弱
+- 压缩后容易丢失关键状态
+- 长任务恢复会越来越不可靠
+
+## 在 Athlete 里的含义
+
+session 里应该能承接：
+
+- 消息历史
+- todo 状态
+- verification 状态
+- task state
+
+## 当前对应
+
+- `src/agent/sessionStore.ts`
+- `src/agent/taskState.ts`
+- `src/agent/verificationState.ts`

package/spec/principles/P14-/346/211/247/350/241/214/347/272/246/346/235/237/344/270/215/346/230/257/345/256/211/345/205/250/347/255/226/347/225/245.md

@@ -0,0 +1,27 @@
+# P14 执行约束不是安全策略
+
+## 原则
+
+允许目录、命令分类、计划门槛，这些都只是执行约束，不是完整安全系统。
+
+## 为什么
+
+如果把“看起来有拦截”误当成“已经安全”：
+
+- 容易误判风险
+- 容易对普通用户过度承诺
+
+## 在 Athlete 里的含义
+
+Athlete 当前更适合：
+
+- 可信工作区
+- 明确边界的项目自动化
+
+它不是“任何人都能随便托管高风险生产系统”的安全平台。
+
+## 当前对应
+
+- `src/utils/commandPolicy.ts`
+- `src/utils/validation.ts`
+- `src/agent/runTurn.ts`

package/spec/principles/P15-provider/345/277/205/351/241/273/345/217/257/346/233/277/346/215/242.md

@@ -0,0 +1,22 @@
+# P15 provider 必须可替换
+
+## 原则
+
+模型提供方必须可替换，Athlete 不能被单一厂商接口锁死。
+
+## 为什么
+
+模型会变、价格会变、稳定性会变。
+
+Athlete 要做 harness，不做某一家的皮肤。
+
+## 在 Athlete 里的含义
+
+- 当前优先支持 OpenAI-compatible 接口
+- provider 选择属于配置层，不属于业务层
+
+## 当前对应
+
+- `src/agent/api.ts`
+- `src/config/env.ts`
+- `src/types.ts`

package/spec/principles/P16-/351/205/215/347/275/256/345/217/252/350/203/275/346/234/211/344/270/200/344/270/252/345/205/245/345/217/243.md

@@ -0,0 +1,22 @@
+# P16 配置只能有一个入口
+
+## 原则
+
+配置必须有统一入口，不能一半在命令行、一半在代码常量、一半在隐式状态。
+
+## 为什么
+
+配置一旦分散：
+
+- 用户搞不清当前行为从哪来
+- 维护者很难排查问题
+
+## 在 Athlete 里的含义
+
+配置读取要收敛到同一套路径与环境变量机制。
+
+## 当前对应
+
+- `src/config/init.ts`
+- `src/config/store.ts`
+- `src/config/env.ts`

package/spec/principles/P17-/346/211/251/345/261/225/351/235/240/344/272/213/344/273/266/347/224/237/351/225/277.md

@@ -0,0 +1,32 @@
+# P17 扩展靠事件生长
+
+## 原则
+
+扩展不能只靠往 system prompt 里继续堆规则，应该沿着清晰的扩展点生长。
+
+## 为什么
+
+Athlete 未来一定会长：
+
+- skills
+- 更多工具
+- 更多角色
+- 更多运行时通知
+
+如果没有扩展点，主循环和工具层都会越来越胖。
+
+## 在 Athlete 里的含义
+
+当前扩展入口主要有三种：
+
+- tool registry
+- skills
+- MCP
+
+下一阶段要补的是更明确的 runtime / lifecycle 事件点。
+
+## 当前对应
+
+- `src/tools/runtimeRegistry.ts`
+- `src/skills/catalog.ts`
+- `src/mcp/`

package/spec/principles/P18-/344/270/273/345/276/252/347/216/257/345/222/214/346/226/207/344/273/266/351/203/275/344/270/215/350/203/275/351/225/277/350/203/226.md

@@ -0,0 +1,36 @@
+# P18 主循环和文件都不能长胖
+
+## 原则
+
+主循环不能无限长，文件也不能无限长。
+
+## 为什么
+
+Athlete 以后会继续长总指挥层、skills、角色和协议。
+
+如果不控制体积：
+
+- AI 更容易改坏系统
+- 人更难定位职责
+- 小改动会牵动全身
+
+## 铁律
+
+1. 单文件默认不超过 300 行。
+2. 文件超过 300 行时，必须先检查是不是职责耦合。
+3. 只要出现“一个文件里有两件以上主要事情”，优先拆目录或拆文件。
+4. 主循环只保留全局调度规则，不塞模块细节。
+
+## Athlete 当前阶段的执行方式
+
+- 优先新增目录，不优先堆到已有大文件
+- 一类状态一个 store
+- 一类工具一个子目录
+- 一类角色一个清晰边界
+
+## 当前对应
+
+- `src/agent/runTurn.ts`
+- `src/tools/`
+- `src/team/`
+- `src/tasks/`

package/spec/principles/P19-/345/205/210/345/206/231/345/244/261/350/264/245/346/265/213/350/257/225/345/206/215/345/206/231/345/256/236/347/216/260.md

@@ -0,0 +1,29 @@
+# P19 先写失败测试再写实现
+
+## 原则
+
+要优先把“会不会被改坏”写成测试，再去写实现。
+
+## 为什么
+
+Athlete 的核心价值是骨架稳定。
+
+没有 fail-first：
+
+- 回归 bug 会反复出现
+- AI 改完一轮下一轮又打回去
+
+## 在 Athlete 里的含义
+
+优先保护这些骨架：
+
+- 主循环
+- skill/context
+- task/background
+- team/protocol
+- worktree isolation
+
+## 当前对应
+
+- `tests/`
+- `npm test`

package/spec/principles/README.md

@@ -0,0 +1,39 @@
+# 宪法原则
+
+这一组文档是 Athlete 当前唯一有效的架构原则集合。
+
+它们直接服务于实现与维护。
+
+## 当前原则体系
+
+### 核心 12 条
+
+- `P01-一个循环一个智能体.md`
+- `P02-加一个工具只加一个处理器.md`
+- `P03-先计划再动手.md`
+- `P04-大任务拆给子智能体.md`
+- `P05-知识按需加载.md`
+- `P06-上下文要能压缩.md`
+- `P07-任务图要落盘.md`
+- `P08-慢操作放后台.md`
+- `P09-任务太大就分给队友.md`
+- `P10-队友之间要有统一协议.md`
+- `P11-队友自己认领任务.md`
+- `P12-工作区和任务要隔离.md`
+
+### 当前工程铁律
+
+- `P13-session是任务现场.md`
+- `P14-执行约束不是安全策略.md`
+- `P15-provider必须可替换.md`
+- `P16-配置只能有一个入口.md`
+- `P17-扩展靠事件生长.md`
+- `P18-主循环和文件都不能长胖.md`
+- `P19-先写失败测试再写实现.md`
+
+## 使用规则
+
+1. 新原则必须长期有效，且跨多个模块成立。
+2. 临时实现细节不要升格成原则。
+3. 若与当前实现冲突，应优先修正文档或实现，不能长期并存。
+4. 若只是模块约束，优先写到 `modules/`、`implementation/` 或 `adr/`。

package/spec/repo//345/274/200/345/217/221/350/247/204/345/210/231.md

@@ -0,0 +1,39 @@
+# 开发规则
+
+## 总则
+
+Athlete 是 harness 工程，不是一次性脚本。
+
+所有改动优先保护：
+
+1. 耐跑底盘
+2. 控制面真相
+3. 扩展边界
+
+## 文件规则
+
+1. 单文件默认不超过 300 行。
+2. 超过 300 行时必须检查是不是耦合过多。
+3. 能拆目录就拆目录，能拆文件就拆文件。
+4. 一个文件只做一件主要事情。
+5. 一个模块尽量只保留一个主要变更理由。
+
+## 架构规则
+
+1. 控制面判断不偷塞进工具细节。
+2. 工具只通过注册表接入。
+3. 新状态优先进入现有真相源，不先新建平行 JSON。
+4. skills 负责知识与流程，不替代工具动作。
+5. 总指挥层负责调度，不负责具体文件改写。
+
+## 文档规则
+
+1. SPEC 写当前真实能力与未来方向，但两者必须分开。
+2. docs 偏解释和维护，spec 偏约束和边界。
+3. ADR 只记录关键决定，不拿来写宣传。
+
+## 测试规则
+
+1. 关键骨架改动先补失败测试。
+2. 修过的真实 bug 尽量固化成回归测试。
+3. 不为了覆盖率堆低价值测试。

package/spec/repo//346/234/254/345/234/260/345/221/275/344/273/244/344/270/216/346/265/201/347/250/213.md

@@ -0,0 +1,32 @@
+# 本地命令与流程
+
+## 常用命令
+
+```powershell
+npm install
+npm run build
+npm run typecheck
+npm test
+npm run dev
+```
+
+## 推荐开发流程
+
+1. 先确认改动落在哪一层
+2. 先补或设计测试
+3. 再改实现
+4. 运行 `npm test`
+5. 最后更新 SPEC / docs
+
+## 写 SPEC 的流程
+
+1. 先写当前真实能力
+2. 再写未来方向
+3. 检查有没有把两者混在一起
+4. 检查单文件是否过胖
+
+## 写代码的流程
+
+1. 先找真相源
+2. 再找工具入口
+3. 最后再看 UI 是否要同步

package/spec/testing/fail-first-/347/254/254/344/270/200/346/211/271/346/265/213/350/257/225/345/210/227/350/241/250.md

@@ -0,0 +1,11 @@
+# fail-first 第一批测试列表
+
+## 先补的测试
+
+1. 总指挥层不会破坏现有 continuation
+2. 总指挥层不会绕过 task board 真相源
+3. lead 能在 subagent / teammate / background 之间做正确分流
+4. skills 元数据缺失时有明确失败结果
+5. skill 加载后能被后续 turn 正确识别
+6. reviewer / verifier 角色不会越权修改任务分配
+7. 单文件拆分后 registry 与 runtime 行为不变

package/spec/testing/fixtures-/350/247/204/350/214/203.md

@@ -0,0 +1,20 @@
+# fixture 规范
+
+## 原则
+
+fixture 只保留能说明问题的最小状态。
+
+## 推荐 fixture 类型
+
+- task board 样例
+- protocol request 样例
+- team inbox 样例
+- worktree index 样例
+- compact / resume session 样例
+- skill metadata 样例
+
+## 规则
+
+1. 一个 fixture 只服务一个测试主题。
+2. 不把大量无关状态塞进同一个 fixture。
+3. 真实 bug 的 fixture 优先长期保留。

package/spec/testing//346/265/213/350/257/225/347/255/226/347/225/245.md

@@ -0,0 +1,97 @@
+# 测试策略
+
+## 目标
+
+测试优先保护 Athlete 的骨架，
+不是为了表面覆盖率。
+
+## 当前重点
+
+- 主循环没坏
+- context / continuation / recovery 没坏
+- lightweight context externalization 没坏
+- checkpoint / reload / resume 没坏
+- runtime stats / runtime summary 没坏
+- task / background 没坏
+- team / protocol / policy 没坏
+- worktree isolation 没坏
+- skill catalog 与 skill loading 没坏
+- Playwright MCP 接线、优先级与 artifact 路由没坏
+- post-completion closeout 不会退回无意义循环
+
+## 当前测试类型
+
+### 1. 骨架测试
+
+保护架构约束，不让主骨架被改坏。
+
+### 2. 缺陷回归测试
+
+真实 bug 修掉后，把 bug 固化成测试。
+
+### 3. 结构预算测试
+
+保护主循环和关键控制面文件不继续长胖。
+
+## 当前已覆盖的重点
+
+- runtime registry / tool visibility
+- skill metadata / discovery / loading / gating
+- continuation / compact / recovery
+- lightweight context externalization
+- checkpoint 持久化 / reload / resume
+- runtime metrics 持久化 / reload / summary
+- finalize / closeout gating
+- lightweight verification signals
+- orchestrator routing / dispatch
+- protocol / policy / task board truth source
+- Playwright 默认值与 artifact 路由
+- browser-first tool priority
+- shell detour workflow guard
+- post-completion todo/task loop prevention
+
+## 命令
+
+默认本地测试：
+
+```powershell
+npm test
+```
+
+只做测试编译：
+
+```powershell
+npm run test:build
+```
+
+核心测试集：
+
+```powershell
+npm run test:core
+```
+
+真实 API 验证（不进入默认 `npm test`）：
+
+```powershell
+npm run verify:runtime-context-api
+npm run verify:runtime-checkpoint-api
+npm run verify:runtime-observability-api
+```
+
+## 当前原则
+
+1. 骨架测试优先。
+2. 回归测试优先。
+3. 默认测试不要强依赖不稳定外部 API。
+4. 真实 API / 真实浏览器验证可以做，但不要强塞进默认 `npm test`。
+5. runtime observability 这类能力必须同时覆盖：
+   - 结构化持久化
+   - reload 后一致性
+   - 用户可读 summary
+   - 真实 API 验证
+
+## 不建议的做法
+
+- 为了数量堆很多低价值小测试
+- 把不稳定的真实 API 测试塞进默认 `npm test`
+- 只测 prompt 文案，不测底层机器状态