# 看板协作协议（Plane 作为任务板与信箱）

看板 = https://plane.kappiee.com/kappiee/projects/79cb5a60-aa4f-4138-9864-1dd70426e665/issues/ ，工作项编号 `GW-k`。Gitea 只管代码（仓库、提交、PR），不再放任务。

## 账号 = 终端
- `kappiee` 用户（所有者，做决定）；`oregon` Claude（设计、派活、验收）；`window10` win10 Codex（执行）；`mac` 之后接入的 Mac 终端。
- 凭据键（Agent Vault 注入内存，不落盘、不进 win10、不进评论）：`PLANE_OREGON_API_TOKEN`、`PLANE_WINDOW10_API_TOKEN`（worker 以 window10 发帖）。API 头 `X-API-Key`。

## 状态机
`Backlog → Todo → In Progress → Waiting → Review → Done / Cancelled`
- Backlog：想法/未排期。Todo + assignee `window10`：交给 Codex，worker 下一个 tick 取走。
- In Progress：worker 已启动 codex 运行（worker 自动设置）。
- Waiting + assignee `oregon`：Codex 有待回答的问题或被阻塞（`[question]`/`[blocked]`），等 Claude 回答或升级给 kappiee。
- Review + assignee `oregon`：产出就绪（`[review]`），Claude 验收。通过 → Done；不通过 → 写意见，改回 Todo + `window10`。
- `[progress]`：worker 自动改回 Todo + `window10`，下一轮续跑。
- 需要用户决定时 Claude 把 assignee 改为 `kappiee`（state 保持 Waiting）。

## 工作项
- 标题 `T-xxx 简述`；描述 = 任务书（目标、允许的工具、不做的事、产出、验收线）。
- 评论 = 消息，作者由账号区分；正文首行保留角色标记 `[claude]` / `[codex]` / `[worker]`，worker 构造 prompt 时跳过 `[worker]` 评论。
- 结果标签（Codex 最后一条消息首行必须是其一）：
  - `[review]` 产出完成，附：改动落点、产出路径、SHA、自检结果、如何重跑。
  - `[question]` 需要回答才能继续，附"若无人回答，我默认会怎么做"。
  - `[blocked]` 无法继续，附原因与已尝试的办法。
  - `[progress]` 做了一部分，需要下一轮继续。
  - 未标注首行按 `[review]` 处理。

## 标签、模块、关系、视图
- 标签：`model:astra`（gpt-6-astra，high）/ `model:sol`（gpt-6.1-sol fast，medium，默认）/ `effort:high` / `needs-game`（需要游戏在线，别与其他占用游戏的任务并行）。
- 模块（Modules）= 任务模块（T-007-0 …）；一个模块完成后 Claude 亲自验收再关闭。
- 依赖用关系 "blocked by"，被阻塞的项留在 Backlog，前置完成后再转 Todo。
- 视图：`等我决定`（assignee=kappiee 或 Waiting）、`Codex 执行中`（In Progress / Todo + window10）、`待验收`（Review）。

## Codex 侧（worker 自动化）
worker 跑在 Claude 所在的 Linux 机（`gwent-design/tools/board-worker-plane.py`，cron 每 2 分钟一次，token 只由 Vault 注入内存）。
1. 取 state=Todo 且 assignee=`window10` 的工作项，按 `GW-k` 从小到大取一个；win10 上已有 codex 进程则本轮跳过（避免抢游戏/ADB）。
2. 名称 + 描述 + 评论转成文本拼成 prompt 跑 `codex exec`；同一工作项第二次起 `codex exec resume <thread>` 只追加新评论。
3. 结束后把最后一条消息贴回评论，按结果标签改状态与 assignee（见状态机）。

## Claude 侧
- 工具：`gwent-design/tools/plane-claude.sh`（`show` / `comment` / `state` / `assign` / `new` / `done`）。
- 轮询 Waiting 与 Review（assignee=`oregon`）：回答问题、验收、改任务书或升级给 kappiee。新任务一律建工作项，不再用临时 brief 文件（紧急修复除外）。

## 通用规则
- 消息要短、要有结论；路径用仓库相对路径；大图只贴缩略拼图（≤1600px）。
- 不在评论里贴 token、密码、完整日志。
- 不在 win10 的 checkout 上执行任何 git 写操作（commit / checkout / reset / pull / stash）；产物留在 live 或 stage，入库由 Claude 侧完成。
- 有疑问优先按任务书里的默认值继续并在评论里说明，而不是停下等人。