diff --git a/.codex/skills/development-workflow/SKILL.md b/.codex/skills/development-workflow/SKILL.md index 12c16515..4040216e 100644 --- a/.codex/skills/development-workflow/SKILL.md +++ b/.codex/skills/development-workflow/SKILL.md @@ -45,19 +45,22 @@ Reference contract: `docs/guides/Evidence_Truth_Implementation_Strategy.md`. - choose collaboration mode (OpenSpec default, TODO fallback only when OpenSpec unavailable) - complete global analysis before execution - build/update a master TODO backlog that covers the full scope -- declare TODO ownership in the target TODO ledger before implementation (`Claim ID`, `TODO scope`, `owner`, `expires`) +- declare ownership in the target TODO ledger before implementation (`Claim ID`, `TODO scope`, `owner`, `expires`, `change-id`) - update `docs/design/**` first (no implementation before design update) - create or refresh feature aggregation doc as the status source - initialize/refresh the required evidence block in feature aggregation doc before execution - for OpenSpec mode, select one TODO slice as current change scope -- ensure only one active claim exists per TODO slice; resolve conflicts before coding +- decide whether the slice needs an execution board (`multiple owners`, `shared contracts`, `Gate freeze`, or `touch-scope collision`) +- create or refresh the docs-only intent PR payload before any implementation begins +- require the docs-only intent PR to merge into `main` before coding - run `documentation-management` to validate type/path/frontmatter baseline 2. execution-sync +- begin only after the docs-only intent PR is merged - OpenSpec mode: execute in small increments `TODO slice item -> OpenSpec task -> implementation -> evidence` - TODO fallback mode: execute in small increments `TODO item -> implementation -> evidence`, and record pending OpenSpec migration mapping - keep master TODO status and feature aggregation evidence aligned in all modes -- keep claim ledger aligned with execution state (`planned -> active -> done/released`) +- keep claim ledger, execution board, and feature/OpenSpec slice aligned when ownership or scope changes - after each completed task, update linked design/gap/TODO docs and implementation evidence - append command outputs and behavior-check results to the feature evidence block at task granularity - for large initiatives, continue by opening the next TODO slice in a new OpenSpec change instead of overloading one change @@ -66,7 +69,8 @@ Reference contract: `docs/guides/Evidence_Truth_Implementation_Strategy.md`. - OpenSpec mode checks: `openspec validate`, `openspec status`, tests, and repo doc checks - TODO fallback mode checks: tests, repo doc checks, TODO ledger completeness, and migration debt note completeness - verify current OpenSpec slice only claims TODO items actually completed in this slice -- verify claim ownership is consistent between TODO ledger and feature/OpenSpec slice +- verify the intent PR was merged before the first implementation commit for the slice +- verify claim ownership is consistent between TODO ledger and any execution board - verify coverage of interface contracts and error branches for changed behavior - verify status consistency: feature doc is source of truth, linked docs are non-conflicting - verify `docs/**` can stand alone as the current-state record without depending on OpenSpec internals @@ -81,7 +85,6 @@ Reference contract: `docs/guides/Evidence_Truth_Implementation_Strategy.md`. 5. completion-archive - mark work done in feature aggregation and related ledgers -- release or close TODO claims (`done`/`released`) and clear stale active claims - run `documentation-management` archive actions - update TODO/archive indexes (for example `docs/todos/README.md` when applicable) - OpenSpec mode: complete OpenSpec archive when the change is finished @@ -96,6 +99,6 @@ For each workflow run, report: - evidence commands executed - evidence results summary (including changed happy path + error branch checks) - evidence file updates (design, TODO, OpenSpec tasks, feature aggregation) -- claim updates (new/renewed/released claims with TODO scope) +- claim updates and intent-PR status - review and merge-gate status - unresolved risks or migration debt diff --git a/.codex/skills/spec-driven-collab-board/SKILL.md b/.codex/skills/spec-driven-collab-board/SKILL.md new file mode 100644 index 00000000..6b068f71 --- /dev/null +++ b/.codex/skills/spec-driven-collab-board/SKILL.md @@ -0,0 +1,102 @@ +--- +name: spec-driven-collab-board +description: Use when a claimed spec-driven change needs an execution board, work-package structure, Gate freeze tracking, or historical-reference handling before a docs-only intent PR is merged. +--- + +# Spec-Driven Collab Board + +## Authoritative inputs +- `docs/todos/README.md` +- `docs/todos/templates/change_execution_todo_template.md` +- `docs/guides/Team_Agent_Collab_Playbook.md` +- `docs/todos/project_overall_todos.md` +- `docs/design/TODO_INDEX.md` +- `openspec/changes//tasks.md` +- `docs/features/.md` when present + +## Core rule + +Treat `Claim Ledger` as the outer ownership record and `docs/todos/YYYY-MM-DD__execution_todos.md` as the inner coordination board for an active change. + +Do not turn `docs/todos/project_overall_todos.md` into a work-package task board. +Do not claim work directly from `docs/design/TODO_INDEX.md`. + +## Workflow + +1. Confirm the change state before editing any board. +- Read `openspec/changes//tasks.md`. +- Read `docs/features/.md` when it exists. +- Read the matching initiative entry in `docs/todos/project_overall_todos.md` when one exists. +- Read the corresponding `Claim Ledger` entry and confirm the TODO scope is already claimed. +- If tasks are complete and the feature or roadmap status is `done`, do not create a new active board for that change. + +2. Decide whether an execution board is needed. +- If the change is single-owner, has no shared-contract risk, and does not need Gate sequencing, report that no execution board is required and stop. +- Otherwise continue and choose exactly one board action. +- `create`: no execution board exists for an active change. +- `refresh`: an execution board exists but its gates, work packages, or evidence links are stale. +- `historical-reference`: the change is completed or superseded and the old board should remain only as reference. + +3. Create or refresh the board from the template. +- Use `docs/todos/templates/change_execution_todo_template.md` as the structural baseline. +- Name the file `docs/todos/YYYY-MM-DD__execution_todos.md`. +- Keep the status explicit: `active`, `blocked`, `archived`, or `historical reference`. +- Prepare the board as part of a docs-only intent PR payload; a local-only board is not sufficient coordination. +- Include these sections unless there is a strong reason not to: + - usage rules + - context and scope boundary + - Gate freeze summary + - work-package coordination board + - subtask acceptance tables + - interface compatibility matrix + - integration and closeout + - maintenance rules + +4. Split work at the work-package level, not at the bullet level. +- Create `2-5` work packages for one change. +- Target `0.5-2` days of work per package. +- Give each package one owner, one main goal, one declared touch scope, and one freeze boundary. +- Keep subtasks small for acceptance and evidence mapping, but do not use them as the default claim unit. + +5. Apply Gate rules before allowing parallel work. +- Shared contracts must freeze before downstream packages begin dependent implementation. +- A package should cross at most one Gate. +- If two developers need the same schema, payload, enum, state machine, or audit contract, split into upstream freeze work and downstream implementation work. + +6. Keep the board synchronized with the surrounding governance documents. +- `project_overall_todos.md` remains roadmap plus outer `Claim Ledger`; it must not absorb work-package detail. +- `TODO_INDEX.md` remains backlog-only. +- The execution board must link back to the OpenSpec change and reflect the same completion state as `tasks.md`. +- The execution board should be ready before the docs-only intent PR is raised, and that intent PR must merge before implementation starts. +- If a package moves to `review` or `done`, update evidence on the same day. + +7. Downgrade completed boards instead of pretending they are still active. +- Change the title and status to make the historical role obvious. +- State why the board is no longer active. +- Point future coordination to the currently active change when one is known. + +## Board quality checks + +Before claiming the board update is complete, verify: +- the chosen change is still active if the board is marked `active` +- the outer `Claim Ledger` entry exists and names the same TODO scope / change-id +- each work package has `WP`, `Goal`, `Owner`, `Depends On`, `Touch Scope`, `Freeze Gate`, `Status`, `Branch/Worktree`, `PR`, `Evidence`, and `Last Updated` +- subtask tables map back to OpenSpec task IDs, gap IDs, or testable acceptance points +- the board does not duplicate work-package detail into `project_overall_todos.md` +- the board and `openspec/changes//tasks.md` do not contradict each other +- the board is suitable to ship in a docs-only intent PR without implementation code + +## Output expectations + +Report: +- which action was taken: `create`, `refresh`, or `historical-reference` +- why this change is the correct active or historical board target +- which files were created or updated +- whether an execution board was actually required +- what still needs owner assignment, evidence, Gate freeze, or intent-PR merge + +## Examples + +Use these boards as references when the structure is unclear: +- `docs/todos/agentscope_domain_execution_todos.md` +- `docs/todos/templates/change_execution_todo_template.md` diff --git a/AGENTS.md b/AGENTS.md index 49ad486c..0222b8ad 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,3 @@ - # Additional Constraints - When writing code, add necessary comments to clarify non-obvious logic or intent. diff --git a/docs/README.md b/docs/README.md index 403acfcf..3710e38a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -85,6 +85,8 @@ | `Project_Architecture_and_Priorities.md` | 以“实现视角”梳理现状与优先级（阅读入口指向权威设计） | ✅ 实现视角 | | `todos/README.md` | TODO 目录维护规则与生命周期说明 | ✅ 全局规划 | | `todos/project_overall_todos.md` | 项目总体 TODO 清单（跨模块路线图） | ✅ 全局规划 | +| `todos/templates/change_execution_todo_template.md` | 活跃 change 的 execution board 模板（大包认领，小 task 验收） | ✅ 协作模板 | +| `plans/2026-02-28-spec-driven-collaboration-granularity-design.md` | spec-driven 协作粒度设计说明 | ✅ 协作设计 | ### 3️⃣ 附录与工程实践 @@ -97,6 +99,7 @@ | `guides/Evidence_Truth_Implementation_Strategy.md` | Evidence Truth 固化策略：证据结构、审计要求、CI 分阶段落地 | | `governance/Documentation_Management_Model.md` | 文档管理模型：目录分层、文档类型规则、生命周期依赖、OpenSpec/无 OpenSpec 协作 | | `features/README.md` | 特性聚合文档规范：单一状态源、证据回写与归档迁移 | +| `guides/Team_Agent_Collab_Playbook.md` | 团队并行开发协作手册，含 spec-driven 认领粒度与 execution board 规则 | | `guides/Tool_Approval_Memory.md` | 工具审批记忆使用指南：pending/grant/deny/revoke、scope/matcher、持久化与接线方式 | --- diff --git a/docs/guides/Development_Constraints.md b/docs/guides/Development_Constraints.md index 14091c6c..da5a606b 100644 --- a/docs/guides/Development_Constraints.md +++ b/docs/guides/Development_Constraints.md @@ -14,7 +14,7 @@ - 所有代码开发以 `docs/design/` 全量最新设计为准；若实现与文档冲突，必须先更新文档再改代码。 - 设计文档必须可独立重建实现：至少显式描述总体架构、核心流程、数据结构、关键接口、异常错误处理（详见 `docs/design/Design_Doc_Minimum_Standard.md`）。 - 任何 Bug/新增 Feature/重构，必须先执行“全局分析 + 总体 TODO 主清单 + docs 更新”，再按 TODO 切片进入 OpenSpec 流程逐项落地（大改动通常对应多个 OpenSpec change）。 -- 任何进入执行态（`doing`）的 TODO，必须先在对应 TODO 文档登记负责人与认领声明（Claim Ledger：scope/owner/expires/change-id），避免并行冲突。 +- 任何进入实现态的切片，必须先完成 `Claim Ledger` 认领声明，并先合入 docs-only `spec-sync / intent PR`；未合入前不得开始代码实现。 - 默认采用 OpenSpec 协作；仅在 OpenSpec 不可用时允许 TODO-driven 回退模式，并必须在 OpenSpec 恢复后完成迁移回写。 - 任何治理类文档任务必须使用双技能流程（`.codex/skills/documentation-management/SKILL.md` + `.codex/skills/development-workflow/SKILL.md`）或等价自动化流程。 - Evidence Truth 必须结构化固化到 `docs/features/*.md`，并通过 `./scripts/ci/check_governance_evidence_truth.sh` 门禁校验（见 `docs/guides/Evidence_Truth_Implementation_Strategy.md`）。 diff --git a/docs/guides/Documentation_First_Development_SOP.md b/docs/guides/Documentation_First_Development_SOP.md index e6594cfc..698de88c 100644 --- a/docs/guides/Documentation_First_Development_SOP.md +++ b/docs/guides/Documentation_First_Development_SOP.md @@ -14,7 +14,7 @@ - 关键接口 - 异常与错误处理 4. 任何 Bug/Feature/Refactor，必须先判断是否为设计约束不清或缺失；是则先补文档。 -5. 开发闭环必须是：全局分析 -> 总体 TODO 主清单 -> docs 更新 -> 按 TODO 切片进入 OpenSpec 执行 -> TODO/证据回写 -> 文档归档。 +5. 开发闭环必须是：全局分析 -> 总体 TODO 主清单 -> 认领声明 -> docs 更新 -> 按 TODO 切片建立 OpenSpec / execution board -> docs-only intent PR 合入 -> 实现 -> TODO/证据回写 -> 文档归档。 6. `docs/**` 是全量事实源；`openspec/**` 仅是执行过程记录。OpenSpec 结果必须回写到 `docs/**`，禁止只留在 OpenSpec。 ## 2. 产物规范（必须） @@ -47,14 +47,13 @@ - 基于分析文档生成总体 TODO 主清单，覆盖完整目标范围。 - 每条 TODO 必须标记切片边界（可独立执行、可独立验证、可独立回滚）。 - 总体 TODO 必须支持映射多个 OpenSpec change（一个大特性通常对应多个 change）。 -- 每条 TODO 必须有明确 `Owner`；若暂未指定负责人，状态不得进入 `doing`。 +- 每条进入执行态的 TODO 切片必须可映射到唯一 `Claim Ledger` scope。 -### Step 2.5: 负责人认领声明（冲突规避，新增） -- 在开始实现前，必须先在对应 TODO 文档的 `Claim Ledger` 写入认领声明： - - `Claim ID`、`TODO Scope`、`Owner`、`Status(planned/active)`、`Declared At`、`Expires At`、`OpenSpec Change`。 -- 同一 TODO ID 在同一时刻只允许一个 `planned/active` 认领。 -- 认领过期后必须续期或释放（`expired/released`），否则他人可重新认领。 -- 推荐顺序：`先认领 -> 再建/更新 OpenSpec 切片 -> 再进入代码实现`。 +### Step 2.5: 认领声明（冲突规避，强制） +- 在开始实现前，必须先在对应 TODO 文档写入 `Claim Ledger` 认领声明。 +- 最少字段：`Claim ID`、`TODO Scope`、`Owner`、`Status`、`Declared At`、`Expires At`、`OpenSpec Change`。 +- 同一 TODO scope 在同一时刻只允许一个 `planned/active` 认领。 +- 认领只声明“这一块范围由谁推进”，不替代 active change 内部的 work package 协作板。 ### Step 3: 先更新 docs（作为 OpenSpec 输入） - 在执行前先更新 `docs/design/**` 与相关治理文档，形成当前基线。 @@ -66,11 +65,21 @@ - 从总体 TODO 中选择一个最小切片，创建/更新一个 OpenSpec change。 - 每个 change 必须声明其消费的 TODO 子集与验收边界。 - 一个 change 只处理一个切片；多切片并行时使用多个 change-id。 +- 若该切片存在多人并行、共享接口、或需要 Gate 冻结，则必须创建/更新 `docs/todos/YYYY-MM-DD__execution_todos.md`。 + +### Step 4.5: 合入 docs-only intent PR（实现前门禁） +- 在进入代码实现前，必须提交一个只包含治理文档的 `spec-sync / intent PR` 并先合入 `main`。 +- 该 PR 至少包含： + - `Claim Ledger` 更新； + - 本轮切片对应的 docs/OpenSpec artifacts； + - 若需要多人协作，则包含 execution board 骨架与 Gate/Touch Scope 定义。 +- `intent PR` 禁止夹带实现代码；其目的仅是把意图、边界、冻结点写入共享基线。 ### Step 5: 按 OpenSpec 切片逐项执行修复 - 每个切片在 OpenSpec 中落地为可追踪 proposal/design/tasks。 - 推荐节奏：一条 TODO（切片子项） -> OpenSpec task -> 实现 -> 验证 -> 回写状态。 - 禁止一次性跨多个高风险 TODO 混改。 +- 未完成 `intent PR` 合入前，不得开始实现代码或提交实现 PR。 ### Step 6: 验证与回写 - 每次切片修复后必须同步更新： @@ -106,9 +115,10 @@ - 未完成 Step 1（全局分析）不得进入切片执行。 - 未完成 Step 2（总体 TODO）不得创建 OpenSpec change。 -- 未完成 Step 2.5（负责人认领声明）不得进入 Step 4/Step 5。 +- 未完成 Step 2.5（认领声明）不得进入 Step 4/Step 5。 - 未完成 Step 3（docs 更新）不得进入代码提交。 - 未完成 Step 4（切片映射）不得开始批量修复。 +- 未完成 Step 4.5（docs-only intent PR 合入）不得开始代码实现。 - 未完成 Step 6（验证+回写）不得标记切片完成。 - 未完成 Step 7（归档）不得关闭该轮治理任务。 @@ -138,10 +148,12 @@ 2. 在 TODO `Claim Ledger` 先声明认领（scope/owner/expires/change-id）。 3. 从总体 TODO 选择一个切片，建立/选择 `openspec/changes//`。 4. 创建或更新 `docs/features/.md`，登记该切片的 proposal/design/specs/tasks 链接。 -5. 按 OpenSpec tasks 执行该切片，并回写证据到 feature 聚合文档与 TODO 文档。 -6. 重复步骤 2-5，直到总体 TODO 主清单清空。 -7. 完成后执行 verify + archive，并迁移聚合文档到 `docs/features/archive/`。 -8. 确认最终可读性以 `docs/**` 为准：架构/流程/接口变更已在 docs 中可独立理解，OpenSpec 仅保留追踪链接。 +5. 若切片需要多人并行、共享接口冻结或联调顺序控制，则创建/更新对应 execution board。 +6. 提交 docs-only `intent PR` 并先合入 `main`。 +7. 基于最新 `main` 开始实现，按 OpenSpec tasks 执行该切片，并回写证据到 feature 聚合文档与 TODO 文档。 +8. 重复步骤 2-7，直到总体 TODO 主清单清空。 +9. 完成后执行 verify + archive，并迁移聚合文档到 `docs/features/archive/`。 +10. 确认最终可读性以 `docs/**` 为准：架构/流程/接口变更已在 docs 中可独立理解，OpenSpec 仅保留追踪链接。 ### Mode B: 无 OpenSpec 回退（TODO-driven） @@ -149,8 +161,10 @@ 1. 先完成分析 + 总体 TODO 主清单 + docs 基线更新。 2. 在 TODO `Claim Ledger` 先声明认领（scope/owner/expires）。 3. 创建 `docs/features/.md`，并在 frontmatter 声明 `mode: todo_fallback` 与 `topic_slug`。 -4. 以 TODO 清单推进并持续回写 evidence（不阻塞于 OpenSpec 工具可用性）。 -5. OpenSpec 可用后，按 TODO 切片补迁移：将 fallback 资产映射到一个或多个新的 `openspec/changes//` 并记录迁移证据。 +4. 若该切片需要多人并行或共享接口冻结，则创建/更新 execution board。 +5. 提交 docs-only `intent PR` 并先合入 `main`。 +6. 以 TODO 清单推进并持续回写 evidence（不阻塞于 OpenSpec 工具可用性）。 +7. OpenSpec 可用后，按 TODO 切片补迁移：将 fallback 资产映射到一个或多个新的 `openspec/changes//` 并记录迁移证据。 ## 8. SOP Skill 化（必须） diff --git a/docs/guides/Team_Agent_Collab_Playbook.md b/docs/guides/Team_Agent_Collab_Playbook.md index 41ec9558..d73402e1 100644 --- a/docs/guides/Team_Agent_Collab_Playbook.md +++ b/docs/guides/Team_Agent_Collab_Playbook.md @@ -12,8 +12,8 @@ 5. 任何 `skip/only/exclude` 必须说明理由并经 review。 对应规则来源： -- `/Users/lysander/projects/dare-framework/docs/agent_rules.md` -- `/Users/lysander/projects/dare-framework/.github/pull_request_template.md` +- `docs/agent_rules.md` +- `.github/pull_request_template.md` ## 2. 日常工作流（每次都按这个走） @@ -38,7 +38,7 @@ pytest -q tests/smoke -m smoke ## 3. 当前 CI 闸门说明（按阶段） 工作流： -- `/Users/lysander/projects/dare-framework/.github/workflows/ci-gate.yml` +- `.github/workflows/ci-gate.yml` 当前检查项： - `lint` @@ -49,12 +49,12 @@ pytest -q tests/smoke -m smoke - `lockfile-policy` 治理配置说明： -- `/Users/lysander/projects/dare-framework/docs/governance/branch-protection.md` +- `docs/governance/branch-protection.md` ## 4. 免费版主干护栏（main-guard） 工作流： -- `/Users/lysander/projects/dare-framework/.github/workflows/main-guard.yml` +- `.github/workflows/main-guard.yml` 触发： - 每次 `push` 到 `main` @@ -73,7 +73,7 @@ pytest -q tests/smoke -m smoke ## 4.1 合并人工审批护栏（manual-merge-guard） 工作流： -- `/Users/lysander/projects/dare-framework/.github/workflows/manual-merge-guard.yml` +- `.github/workflows/manual-merge-guard.yml` 作用： 1. PR 合入 `main` 后检查是否符合人工审批策略。 @@ -93,6 +93,65 @@ pytest -q tests/smoke -m smoke 4. 锁文件有纪律：lockfile 改动必须同 PR 同步 manifest。 5. 风险路径强约束：鉴权/并发/执行控制改动必须带 `risk-matrix` 证据。 +## 5.1 Spec-Driven 认领粒度（新增） + +适用前提： +- 已完成文档先行最小闭环：设计文档更新、gap analysis、execution TODO、OpenSpec artifacts 已入库。 +- 当前工作属于 active change，而不是纯 backlog 条目。 + +执行规则： +1. 外层认领单位默认是 `TODO scope` 或 `change slice`，不是单个 TODO bullet，也不是整个模块。 +2. 进入 active change 后，内层协作单位才是 `work package`；一个 `work package` 由一个人独占，目标是在 `0.5-2` 天内交付一个可验证闭环。 +3. 一个 `work package` 最多跨 1 个 Gate；如果同时跨协议冻结、执行链路、观测治理，必须拆包。 +4. work package 内部可以保留多个细粒度 task，但这些 task 默认只用于验收和回写，不单独并行认领。 +5. 共享契约先冻结再并行：schema、payload、状态机、日志字段、审计字段都属于 Gate 级接口，不允许多人同时自由演化。 + +推荐口号： +- 大包认领，小 task 验收。 +- 先冻结接口，再放开并行。 + +## 5.2 三层协作板 + +1. `docs/design/TODO_INDEX.md`：设计 backlog，只看“还有什么要做”，不做认领板。 +2. `docs/todos/project_overall_todos.md`：项目路线图 + 外层 `Claim Ledger`，只认领 TODO scope，不记 work package 施工细节。 +3. `docs/todos/YYYY-MM-DD__execution_todos.md`：活跃 change 的执行协作板，记录 work package、依赖、冻结点、PR、证据。 + +要求： +1. 不要把 feature 内部的 work package 施工细节写到 `project_overall_todos.md`。 +2. 不要从 `TODO_INDEX` 直接抢任务；必须先声明 TODO scope，再视协作复杂度落到 execution board。 +3. 存在多人并行、共享接口或 Gate 冻结需求的活跃 change，必须有一份 execution board，且与 `openspec/changes//tasks.md` 双向关联。 + +## 5.3 Intent PR 门禁 + +1. `Claim Ledger`、OpenSpec artifacts、execution board 都先在本地准备好。 +2. 准备好后，先发一个 docs-only `spec-sync / intent PR`。 +3. `intent PR` 只允许包含治理文档，不允许夹带实现代码。 +4. 只有 `intent PR` 合入 `main` 后，才允许开始实现分支与后续 `impl PR`。 +5. 高冲突 change 可进一步拆成 `intent PR -> Gate freeze PR -> impl PR`。 + +## 5.4 execution board 最小字段 + +每个 `work package` 至少记录： +- `WP` +- `Goal` +- `Owner` +- `Depends On` +- `Touch Scope` +- `Freeze Gate` +- `Status` +- `Branch/Worktree` +- `PR` +- `Evidence` +- `Last Updated` + +推荐状态： +- `todo -> claimed -> doing -> review -> done` +- `todo/claimed/doing -> blocked -> doing/dropped` + +配套模板： +- `docs/todos/templates/change_execution_todo_template.md` +- 参考实例：`docs/todos/agentscope_domain_execution_todos.md` + ## 6. Docs 组织规范（队友新增文档时） 1. 面向流程/操作的文档放在 `docs/guides/`。 diff --git a/docs/plans/2026-02-28-spec-driven-collaboration-granularity-design.md b/docs/plans/2026-02-28-spec-driven-collaboration-granularity-design.md new file mode 100644 index 00000000..16008462 --- /dev/null +++ b/docs/plans/2026-02-28-spec-driven-collaboration-granularity-design.md @@ -0,0 +1,149 @@ +# Spec-Driven 协作粒度设计 + +> 日期：2026-02-28 +> 状态：adopted +> 适用范围：4 人并行、spec-driven、多人同时推进多个 active changes 的场景 + +## 1. 背景 + +当前仓库已经具备文档先行治理闭环： + +- `docs/design/**` 作为权威设计 +- `docs/todos/*_gap_analysis.md` 作为设计-实现差异分析 +- `docs/todos/*_todo.md` 作为治理清单 +- `openspec/changes//*` 作为变更执行工件 + +问题不在于“缺少 TODO”，而在于多人并行时缺少统一的认领粒度与冻结边界： + +- `docs/design/TODO_INDEX.md` 适合看 backlog，不适合做认领板。 +- `docs/todos/project_overall_todos.md` 适合记录项目路线图，不适合承载单个 feature 的细节认领。 +- 当多人直接按 bullet 或文件认领时，容易在共享接口、共享核心文件和共享语义上发生冲突。 + +## 2. 设计目标 + +本设计希望同时满足： + +1. 保持 vibe coding 的高吞吐，不把任务拆得过碎。 +2. 在共享契约处建立足够强的冻结边界，降低返工。 +3. 保留细粒度验收证据，避免“大包做完却无法 review”。 +4. 继续遵循“文档更新 -> gap 分析 -> TODO -> OpenSpec -> 回写/归档”的治理闭环。 + +## 3. 核心决策 + +### 3.1 三层协作板 + +- `docs/design/TODO_INDEX.md` + - 角色：设计 backlog / 发现池 + - 作用：回答“还有哪些设计 TODO” + - 不负责：认领、依赖编排、PR 跟踪 + +- `docs/todos/project_overall_todos.md` + - 角色：项目路线图 + 外层 `Claim Ledger` + - 作用：回答“当前项目级优先级是什么”以及“哪一段 TODO scope 当前由谁推进” + - 不负责：单个 change 内部的 work package 施工细节 + +- `docs/todos/YYYY-MM-DD__execution_todos.md` + - 角色：active change 内层执行协作板 + - 作用：回答“这一 change 内部谁在做什么、依赖谁、冻结到哪一层、证据在哪里” + - 它承载 work package 协调，但不替代外层 `Claim Ledger` + +### 3.2 认领粒度 + +默认原则：`外层认领 scope，内层拆 work package，小 task 验收`。 + +- 外层认领单位是 `TODO scope` 或 `change scope` +- 内层协作单位是 `work package` +- 验收单位是 task / OpenSpec checkbox / gap 映射项 + +`work package` 的定义： + +- 一个 owner 独占 +- 一个主要目标 +- 推荐在 `0.5-2` 天内闭环 +- 最多跨 1 个 Gate +- 能独立给出联调或测试证据 + +不建议的认领方式： + +- 直接按单个 bullet 抢任务 +- 一个人认领整个大模块 +- 两个人同时自由修改同一组共享契约 + +### 3.3 Gate 冻结 + +共享契约必须先冻结再并行，包括但不限于： + +- schema +- payload shape +- message / event type +- plan state 语义 +- policy decision 结构 +- 日志主字段与审计字段 + +因此，一个 active change 的流程应为： + +1. 先写外层 `Claim Ledger` +2. 再提交 docs-only `spec-sync / intent PR` + 内容包含：设计文档、gap analysis、execution board、OpenSpec artifacts +3. `intent PR` 合入后，work package 才允许进入 `claimed/doing` +4. Gate 冻结完成后，下游包再并行实现 + +## 4. 数据结构 + +execution board 的 `work package` 记录至少包含： + +| 字段 | 含义 | +|---|---| +| `WP` | work package 唯一标识 | +| `Goal` | 独立目标 | +| `Owner` | 唯一负责人 | +| `Depends On` | 上游包或 Gate | +| `Touch Scope` | 预计改动目录/文件 | +| `Freeze Gate` | 本包依赖或产出的冻结边界 | +| `Status` | `todo/claimed/doing/review/blocked/done/dropped` | +| `Branch/Worktree` | 开发分支或工作树 | +| `PR` | 对应 PR | +| `Evidence` | 测试、联调、文档回写证据 | +| `Last Updated` | 最后更新时间 | + +子任务记录至少包含： + +| 字段 | 含义 | +|---|---| +| `Task ID` | 任务唯一标识 | +| `Related Gap / OpenSpec` | 对应 gap 或 OpenSpec task | +| `Description` | 具体验收点 | +| `Status` | 任务状态 | +| `Evidence` | 证据链接 | + +## 5. 关键接口 + +人与文档的接口： + +- 从 `TODO_INDEX` 发现候选方向 +- 从 `project_overall_todos.md` 确认优先级 +- 从 `execution_todos.md` 认领具体 work package +- 从 `openspec/changes//tasks.md` 验收与回写 + +PR 与认领板的接口： + +- 每个 PR 必须标注 `change-id` 与 `WP` +- `review` 之前必须回写 execution board +- `done` 之前必须同步回写 OpenSpec `tasks.md` + +## 6. 错误处理与例外 + +- 如果一个 `work package` 在 24 小时内没有实际推进，应从 `claimed` 释放回 `todo` 或改为 `blocked`。 +- 如果实现中发现 Gate 未冻结，不得继续扩散实现，应先回到 spec-sync 修正文档。 +- 如果一个包跨越两个以上 Gate，必须拆分，否则极易形成设计漂移和代码冲突。 +- 生产止血类紧急修复可先做最小改动，但仍需在 24 小时内补 execution board 与文档闭环。 + +## 7. 采纳结果 + +本设计通过以下文档落地： + +- `docs/todos/README.md` +- `docs/guides/Team_Agent_Collab_Playbook.md` +- `docs/todos/templates/change_execution_todo_template.md` + +后续所有 active changes 应优先复用统一模板，而不是临时自由发挥。 diff --git a/docs/plans/2026-03-02-agentscope-execution-board-migration-plan.md b/docs/plans/2026-03-02-agentscope-execution-board-migration-plan.md new file mode 100644 index 00000000..ee667814 --- /dev/null +++ b/docs/plans/2026-03-02-agentscope-execution-board-migration-plan.md @@ -0,0 +1,82 @@ +# AgentScope Execution Board Migration Implementation Plan + +> 执行说明：按本计划逐项推进；不要假设本地 `superpowers` 技能已安装。若仓库内可用，优先使用 `.codex/skills/development-workflow/` 与 `.codex/skills/spec-driven-collab-board/` 的现有流程约束。 + +**Goal:** Migrate `docs/todos/agentscope_domain_execution_todos.md` into the standardized execution board format without changing its technical scope. + +**Architecture:** Keep the existing AgentScope domain decomposition and Gate model, but reframe the document around work packages, Gate ownership, execution-board fields, and subtask acceptance tables. Preserve the current dependency model and reuse existing D1-D8 task content as the sample payload. + +**Tech Stack:** Markdown, existing TODO governance docs, OpenSpec-style task references + +--- + +### Task 1: Freeze migration scope + +**Files:** +- Modify: `docs/todos/agentscope_domain_execution_todos.md` +- Reference: `docs/todos/templates/change_execution_todo_template.md` +- Reference: `docs/todos/README.md` + +**Step 1: Confirm structure delta** + +Read the existing execution board and map its current sections to: +- context and scope +- Gate summary +- work package board +- subtask acceptance tables +- compatibility matrix +- integration closeout + +**Step 2: Keep content constraints** + +Do not introduce new product scope. Reuse the current D1-D8 tasks, Gate definitions, and four-person split as the sample content. + +### Task 2: Rewrite the sample board + +**Files:** +- Modify: `docs/todos/agentscope_domain_execution_todos.md` + +**Step 1: Add standardized header and usage rules** + +Introduce: +- date +- change identifier placeholder for this migration stream +- status +- execution-board usage notes + +**Step 2: Convert domain split into work packages** + +Map the current four-person split into `WP-A` through `WP-D`, keeping: +- D1+D2+D3 +- D6 +- D7 +- D4+D5+D8 + +**Step 3: Convert D1-D8 tasks into acceptance tables** + +Keep the current task IDs and descriptions, but nest them under the owning work package with explicit evidence expectations. + +### Task 3: Verify the sample stays usable + +**Files:** +- Modify: `docs/todos/agentscope_domain_execution_todos.md` +- Reference: `docs/guides/Team_Agent_Collab_Playbook.md` +- Reference: `docs/todos/README.md` + +**Step 1: Check terminology** + +Ensure the sample now explicitly demonstrates: +- `work package` +- `Freeze Gate` +- `Status` +- `Branch/Worktree` +- `PR` +- `Evidence` + +**Step 2: Check references** + +Keep the file path unchanged so existing references remain valid. + +**Step 3: Final review** + +Confirm the document is readable as the canonical sample for future active changes. diff --git a/docs/todos/README.md b/docs/todos/README.md index f75750d4..da1c966c 100644 --- a/docs/todos/README.md +++ b/docs/todos/README.md @@ -6,16 +6,31 @@ ## 1. 目录结构 - `project_overall_todos.md`：项目总体演进 TODO（跨模块、跨阶段）。 +- `YYYY-MM-DD__execution_todos.md`：活跃 change 的执行协作板，用于多人协作、Gate 冻结与回写。 - `2026-02-27_full_design_review_gap_analysis.md`：全量设计文档评审差异分析（第二轮刷新，持续治理中）。 - `2026-02-27_full_design_review_gap_todo.md`：全量设计文档评审对应 TODO 清单（持续治理中）。 - `2026-02-27_design_reconstructability_gap_analysis.md`：可重建性差异分析（P0/P1 已闭环，后续与 full-review 联动）。 - `2026-02-27_design_reconstructability_gap_todo.md`：可重建性治理 TODO 清单（已回写 done，待按周期归档）。 - `archive/2026-02-27_design_code_gap_analysis.md`：当前设计与实现差异分析基线（文档先行治理，已归档）。 - `archive/2026-02-27_design_code_gap_todo.md`：由 gap 分析推导出的执行 TODO 清单（已归档）。 +- `templates/change_execution_todo_template.md`：活跃 change 执行协作板模板。 - 后续可按需要新增： - `YYYY-MM-.md`：专题治理清单（如测试治理、文档收敛、安全治理）。 -## 2. 文档生命周期 +## 2. 三层职责划分 + +- `docs/design/TODO_INDEX.md`：设计 backlog / 发现池。只回答“还有什么设计 TODO”，不用于认领。 +- `docs/todos/project_overall_todos.md`：项目路线图 + 外层 `Claim Ledger`。记录跨模块、跨阶段事项，并声明“哪一段 scope 当前由谁推进”。 +- `docs/todos/YYYY-MM-DD__execution_todos.md`：活跃 change 的内层协作执行板。回答“这一 change 内部如何拆 work package、依赖谁、冻结到哪一层、证据在哪里”。 + +规则： + +- 不要把单个 feature 的实现细节或 work package 填进 `project_overall_todos.md`。 +- `project_overall_todos.md` 可以声明路线图级 `Claim Ledger`，但不替代 active change 内部的 execution board。 +- 不要直接从 `TODO_INDEX` 抢任务；必须先落到 TODO scope，再视协作复杂度决定是否创建 execution board。 +- 当 active change 存在多人并行、共享接口风险、或需要 Gate 冻结时，必须有一份 execution board，并与对应 `openspec/changes//tasks.md` 双向关联。 + +## 3. 文档生命周期 每个 TODO 项都建议包含以下字段： @@ -24,7 +39,7 @@ - `Status`：`todo` / `doing` / `blocked` / `done` / `dropped`。 - `Owner`：责任人或责任小组。 - `Claim Status`：`planned` / `active` / `released` / `done` / `expired`。 -- `Claim Expires`：认领过期时间（`YYYY-MM-DD`），用于冲突自动释放。 +- `Claim Expires`：认领过期时间（`YYYY-MM-DD`）。 - `Evidence`：验证命令、测试结果、PR/commit 或文档链接。 - `Last Updated`：最后更新时间（`YYYY-MM-DD`）。 @@ -33,29 +48,90 @@ `todo -> doing -> done` `todo/doing -> blocked -> doing/dropped` -### 2.1 认领声明（Claim Ledger，新增） +### 3.1 外层认领声明（Claim Ledger） -每个**活跃** TODO 文档（存在 `todo/doing/blocked` 项）必须包含 `## 认领声明（Claim Ledger）` 区块，避免多人并行冲突。 +每个活跃 TODO 文档都应包含 `Claim Ledger` 区块，用于声明“哪一段 TODO scope 当前由谁推进”。 建议字段： - `Claim ID`：唯一认领编号（如 `CLM-20260302-A1`）。 -- `TODO Scope`：被认领的 TODO ID 范围（如 `D2-1~D2-4,D4-1~D4-4`）。 -- `Owner`：当前负责人（个人或小组）。 -- `Status`：`planned`（声明未开工）/`active`（执行中）/`released`（释放）/`done`（完成）/`expired`（过期）。 +- `TODO Scope`：被认领的 TODO ID 范围（如 `T5-2`、`D2-1~D2-4`）。 +- `Owner`：当前负责人。 +- `Status`：`planned` / `active` / `released` / `done` / `expired`。 - `Declared At`：声明时间（`YYYY-MM-DD`）。 -- `Expires At`：过期时间（建议 3-7 天，超时需续期或释放）。 -- `OpenSpec Change`：对应 change-id（若未创建写 `pending`）。 -- `Notes`：冲突说明、续期原因或交接备注。 +- `Expires At`：过期时间（建议 1-7 天，超时需续期或释放）。 +- `OpenSpec Change`：对应 change-id；尚未建立时写 `pending`。 +- `Notes`：冲突说明、续期原因、交接备注。 执行规则： -- 在 TODO 从 `todo` 进入 `doing` 前，必须先写入认领声明。 -- 同一 TODO ID 在同一时刻只能有一个 `planned/active` 认领。 +- 在 TODO 进入实现前，必须先写入 `Claim Ledger`。 +- 同一 TODO scope 在同一时刻只能有一个 `planned/active` 认领。 - 到期未续期的认领应转为 `expired`，并允许他人重新认领。 -- 完成或暂停时，必须把认领状态回写为 `done/released`。 +- `Claim Ledger` 只声明 ownership，不替代 active change 的协作拆包。 + +## 4. Spec-Driven 协作粒度 + +默认原则：`外层认领 scope，内层拆 work package，小 task 验收`。 + +### 4.1 认领单位 + +- 外层 `Claim Ledger` 的认领单位应为 `TODO slice` 或 `change scope`，不是单个 bullet，也不是整个模块。 +- 内层 execution board 的协作单位才是 `work package`。 +- 一个 `TODO slice` 通常映射一个 active change；一个 active change 内部再拆成 `2-5` 个 `work package`。 + +### 4.2 work package 必须满足 + +- 单一 owner。 +- 单一主要目标。 +- 单一冻结边界：最多跨 1 个 Gate。 +- 可独立验证：有明确测试、联调或文档证据。 +- Touch scope 可提前声明，避免多人同时修改同一组核心文件。 + +### 4.3 子任务的用途 + +- 子任务保留细粒度，用于验收、review、回写、证据映射。 +- 子任务通常对应 OpenSpec `tasks.md` 的 checkbox、gap ID、测试项或接口契约项。 +- 除非一个 work package 被正式拆包，否则子任务本身不单独认领。 + +### 4.4 推荐状态流转 -## 3. 更新规则 +- `todo -> claimed -> doing -> review -> done` +- `todo/claimed/doing -> blocked -> doing/dropped` + +`claimed` 表示“已经占坑但尚未进入实做”；超过 24 小时未推进，建议释放。 +`review` 表示实现已完成，等待 PR review / 联调验证 / 文档回写。 + +### 4.5 执行门禁 + +- 先做 claim：`Claim Ledger` 先写入 scope/owner/expires/change-id。 +- 再做 spec-sync：设计文档、gap analysis、execution board、OpenSpec artifacts 先入库。 +- 然后提交 docs-only `intent PR`：只包含 claim/spec/docs/board，不允许夹带实现代码。 +- 只有 `intent PR` 合入 `main` 后，才允许对应 work package 进入 `claimed/doing` 和正式实现。 +- 共享接口先冻结再并行：schema、payload、状态机、审计字段等共享契约必须先经过 Gate 冻结，再放行下游并行实现。 + +## 5. execution board 建议字段 + +对 `work package`，建议至少记录： + +- `WP`：唯一标识，如 `WP-A`。 +- `Goal`：该包的独立目标。 +- `Owner`：唯一负责人。 +- `Depends On`：依赖的上游包或 Gate。 +- `Touch Scope`：预计修改的目录/文件集合。 +- `Freeze Gate`：本包依赖或产出的冻结点。 +- `Status`：`todo/claimed/doing/review/blocked/done/dropped`。 +- `Branch/Worktree`：分支或工作树路径。 +- `PR`：关联 PR。 +- `Evidence`：测试、联调、设计回写证据。 +- `Last Updated`：最后更新时间。 + +模板与示例： + +- 模板：`docs/todos/templates/change_execution_todo_template.md` +- 参考实例：`docs/todos/agentscope_domain_execution_todos.md` + +## 6. 更新规则 - 触发更新： - 架构评审后； @@ -65,16 +141,30 @@ - 只记录“全局事项”，不写单个 feature 的实现细节； - 变更 TODO 时同步更新时间； - `done` 项必须补 `Evidence`。 - - 进入执行前必须更新认领声明（Owner/Scope/Expires）。 + - 进入实现前必须先更新 `Claim Ledger`。 + - 进入实现前必须先完成 docs-only `intent PR` 合入。 - 全量设计评审（Architecture + 全部模块 README）至少每两周执行一次，并回写到 `project_overall_todos.md`。 -## 4. 归档规则 +对 active execution board，额外要求： + +- 认领发生变化时，同步更新 `Owner/Status/Branch/Last Updated`。 +- `intent PR` 中必须至少包含 board 骨架、Gate 定义和 Touch Scope。 +- Gate 冻结时，必须补“冻结内容 + 证据链接”。 +- `done` 前必须确认 OpenSpec `tasks.md` 与 execution board 状态一致。 + +## 7. 归档规则 - 连续 2 个迭代无动作且不再需要推进的事项，标记为 `dropped` 并说明原因。 - 已完成并稳定 1 个迭代以上的事项，可迁移到“完成记录”分节，避免主清单膨胀。 - 归档条目必须使用日期前缀命名，并附对应 OpenSpec change 与验证证据。 -## 5. 与其他文档的关系 +active execution board 归档前应满足： + +- 对应 OpenSpec change 已完成或明确停止。 +- 关键 Gate 已标记最终状态。 +- 所有 `done/dropped` 包均有证据或原因。 + +## 8. 与其他文档的关系 - 与 `docs/design/modules/*`：模块细节在模块文档，这里只保留跨模块视角。 - 与 OpenSpec：执行任务拆解在 OpenSpec artifacts，这里只做方向与优先级治理（默认模式）。 diff --git a/docs/todos/templates/change_execution_todo_template.md b/docs/todos/templates/change_execution_todo_template.md new file mode 100644 index 00000000..e0818d8c --- /dev/null +++ b/docs/todos/templates/change_execution_todo_template.md @@ -0,0 +1,104 @@ +# Execution TODO + +> 日期：YYYY-MM-DD +> Change ID：`` +> 对应 OpenSpec：`openspec/changes//` +> 状态：`active` / `blocked` / `archived` + +## 0. 使用规则 + +- 本文档是 active change 的详细协作板，不替代外层 `Claim Ledger`。 +- 外层 ownership 先写在对应 TODO 文档；本板负责 change 内部的 work package、Gate、Touch Scope 与证据。 +- 默认原则：`大包认领，小 task 验收`。 +- `WP` 是认领单位；子任务只用于验收、回写、证据映射。 +- 只有在设计文档、gap analysis、OpenSpec artifacts 入库后，才允许 `claimed/doing`。 +- 本板若作为开工依据，必须随 docs-only `intent PR` 一起合入 `main`；intent PR 合入前不得开始实现代码。 +- 共享契约必须先 Gate 冻结，再放行下游并行开发。 + +## 1. 上下文与边界 + +- 目标： + - `<一句话说明这轮 change 要解决什么>` +- 不在范围： + - `<明确不做什么>` +- 输入基线： + - `docs/design/...` + - `docs/todos/..._gap_analysis.md` + - `openspec/changes//proposal.md` + - `openspec/changes//design.md` + - `openspec/changes//tasks.md` + +## 2. Gate 冻结总览 + +| Gate | 冻结内容 | Producer | Consumer | 状态 | Evidence | +|---|---|---|---|---|---| +| Gate-1 | `` | `` | `` | `todo` | `` | +| Gate-2 | `` | `` | `` | `todo` | `` | +| Gate-3 | `` | `` | `` | `todo` | `` | +| Gate-4 | `` | `` | `` | `todo` | `` | + +## 3. Work Package 协作板 + +| WP | Goal | Owner | Depends On | Touch Scope | Freeze Gate | Status | Branch/Worktree | PR | Evidence | Last Updated | +|---|---|---|---|---|---|---|---|---|---|---| +| WP-A | `<独立目标>` | `` | `-` | `` | `Gate-1` | `todo` | `` | `` | `` | `YYYY-MM-DD` | +| WP-B | `<独立目标>` | `` | `WP-A` | `` | `Gate-2` | `todo` | `` | `` | `` | `YYYY-MM-DD` | +| WP-C | `<独立目标>` | `` | `Gate-1` | `` | `Gate-3` | `todo` | `` | `` | `` | `YYYY-MM-DD` | +| WP-D | `<独立目标>` | `` | `Gate-2, Gate-3` | `` | `Gate-4` | `todo` | `` | `` | `` | `YYYY-MM-DD` | + +状态建议： + +- `todo -> claimed -> doing -> review -> done` +- `todo/claimed/doing -> blocked -> doing/dropped` + +拆包规则： + +- 单个 WP 推荐 0.5-2 天闭环。 +- 若跨 2 个以上 Gate，拆包。 +- 若两个人会改同一组共享契约，改成“先上游冻结，后下游实现”。 + +## 4. 子任务验收表 + +### WP-A + +| Task ID | Related Gap / OpenSpec | Description | Status | Evidence | +|---|---|---|---|---| +| A-1 | `` | `<验收点>` | `todo` | `` | +| A-2 | `` | `<验收点>` | `todo` | `` | + +### WP-B + +| Task ID | Related Gap / OpenSpec | Description | Status | Evidence | +|---|---|---|---|---| +| B-1 | `` | `<验收点>` | `todo` | `` | +| B-2 | `` | `<验收点>` | `todo` | `` | + +### WP-C + +| Task ID | Related Gap / OpenSpec | Description | Status | Evidence | +|---|---|---|---|---| +| C-1 | `` | `<验收点>` | `todo` | `` | + +## 5. 接口兼容性矩阵 + +| 接口项 | 生产方 | 消费方 | 冲突风险 | 冻结时点 | +|---|---|---|---|---| +| `` | `WP-A` | `WP-B/WP-C` | `<字段名或语义漂移>` | `Gate-1` | +| `` | `WP-B` | `WP-D` | `<序列化或事件顺序冲突>` | `Gate-2` | +| `` | `WP-C` | `WP-D` | `<日志/审计字段不一致>` | `Gate-3` | + +## 6. 联调与收口 + +- 联调入口： + - `` +- 完成条件： + - `<端到端通过条件>` + - `<文档回写条件>` + - `` + +## 7. 维护约定 + +- Owner 变化、状态变化、PR 变化当天回写。 +- `review` 前必须补证据。 +- `done` 前必须确认 execution board 与 OpenSpec `tasks.md` 一致。 +- 归档时补最终结论，并迁移到 `docs/todos/archive/` 或标记 `archived`。