cowork-flow 0.0.26 → 0.0.28

package/README.md

@@ -1,4 +1,4 @@
-# cowork-flow
+# cowork-flow
 
 cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它把项目说明、任务流转、规格治理、开发计划和会话记录放在一套可复制的目录结构里，帮助团队在项目早期就建立清晰的工作闭环。
 
@@ -43,6 +43,12 @@ cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它
         ├── workflow.md
         ├── scripts/
         ├── spec/
+        │   ├── contracts/
+        │   ├── runtime/
+        │   ├── schemas/
+        │   ├── backend/
+        │   ├── frontend/
+        │   └── guides/
         ├── changes/
         ├── plans/
         ├── tasks/
@@ -55,27 +61,29 @@ cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它
 项目级协作入口，包含编码前思考、简单优先、外科手术式改动、验证优先等基础原则。接入项目后，应把项目名称、技术栈、运行命令、测试命令和提交策略补齐。
 
 `template/.agents/skills/`
-本地技能入口，覆盖 start、before-dev、brainstorming、party-mode、writing-plans、check、finish-work、continue、meta、python-design、update-spec 和 break-loop 等协作动作。这里的 skill 应保持通用，不承载某个业务项目的一次性细节。
+本地技能入口，覆盖 start、before-dev、brainstorming、party-mode、party-mode-v2、writing-plans、check、finish-work、continue、meta、python-design、update-spec 和 break-loop 等协作动作。这里的 skill 应保持通用，不承载某个业务项目的一次性细节。
 
-`party-mode` 是用户手动调用的 advisory roundtable。它通过当前 Host Adapter 协调真实子代理讨论，而不是模拟人设；默认 `max_agents=3`、`max_rounds=3`，配置优先级为本次调用、task/change、本地配置、skill 默认值。Party Mode 只产出建议、证据、分歧和验收信号，不能推进任务状态，也不能替代 `cowork-implement` 或 `cowork-check`。
+`party-mode` 是用户手动调用的 advisory roundtable。它通过当前 Host Adapter 协调真实子代理讨论，而不是模拟人设；默认 `max_agents=3`、`max_rounds=5`，配置优先级为本次调用、task/change、本地配置、skill 默认值。Party Mode 只产出建议、证据、分歧和验收信号，不能推进任务状态，也不能替代 `cowork-implement` 或 `cowork-check`。
+
+`party-mode-v2` 是 runtime board controlled advisory workflow。Python runtime 管理看板、当前轮视图、schema 校验、轮次上限和最终报告；子代理通过 board API 交流，主持人只监控和纠偏，不转发或综合观点。
 
 `template/.codex/agents/`
 固定角色 agent 定义，包含 `cowork-research`、`cowork-implement` 和 `cowork-check`，以及对 Codex 默认 `worker`、`default`、`explorer` 的项目级防漂移约束。主会话负责计划与收口，并通过 host adapter 派发固定 agent；正式派发必须先创建 runtime context，再把 `cowork_runtime_context_id` 和 `cowork_host_context_key` 传给子代理。
 
 `template/.codex/config.toml`、`template/.codex/hooks.json`、`template/.codex/hooks/`
-Codex 项目级配置与每轮上下文注入入口。hook 会先用共享 entry classifier 判定当前输入，再读取当前 session task、`.cowork-flow/spec/workflow-state-templates.md` 中的 `workflow-state` 片段和 `codex.dispatch_mode`，把流程状态注入到当前轮对话。注入的 `codex-dispatch-mode` 只是主会话调度提示，不代表当前线程身份。
+Codex 项目级配置与每轮上下文注入入口。hook 会先解析 runtime context，再读取当前 session task、`.cowork-flow/spec/contracts/workflow-state-templates.md` 中的 `workflow-state` 片段和 `codex.dispatch_mode`，把流程状态注入到当前轮对话。注入的 `codex-dispatch-mode` 只是主会话调度提示，不代表当前线程身份。
 
 `template/CLAUDE.md`、`template/.claude/settings.json`、`template/.claude/agents/`、`template/.claude/skills/`、`template/.claude/commands/`、`template/.claude/hooks/`
 Claude Code 项目级记忆、hook、固定 agent、skills 和 slash command。`CLAUDE.md` 显式导入 `AGENTS.md`。`.claude/settings.json` 注册 `UserPromptSubmit` 和 `SessionStart` hook，注入当前 workflow state 与 contract digest。固定 agent 通过 `.cowork-flow/run subagent init` 生成 runtime context，并在 prompt、env 或 metadata transport 中传递 `cowork_runtime_context_id`；hook 绑定成功后才进入叶子执行，绑定失败则 fail closed，避免被项目 bootstrap 或无任务首屏上下文拉偏。Claude Code 不自动加载 `.agents/skills/`，所以项目技能要放进 `.claude/skills/`。
 
 `template/.opencode/agents/`、`template/.opencode/commands/`、`template/.opencode/plugins/`
-OpenCode 项目级固定 agent、slash command 和系统上下文注入插件。插件会读取 `.cowork-flow/spec/registry.json`，注入短 contract digest。
+OpenCode 项目级固定 agent、slash command 和系统上下文注入插件。插件会读取 `.cowork-flow/spec/runtime/contract-registry.json`，注入短 contract digest。
 
 `template/.cowork-flow/`
 工作流目录，包含流程说明、任务状态、开发者工作区、项目规范、行为变更规格、实现计划和辅助脚本。`.cowork-flow/config.yaml` 只承载真实接线的 session/journal, Codex hint, and task lifecycle hook settings。
 
 `template/.cowork-flow/spec/`
-项目规范目录，预置了 backend、frontend 和 guides 三类说明。接入时应按项目事实保留、改写或删除对应规范。
+项目规范目录。`contracts/` 存人读 workflow/host/agent 合同，`runtime/` 存运行时读取的规则和 contract registry，`schemas/` 存 JSON Schema，`backend/`、`frontend/`、`guides/` 存工程规范和思考指引。接入时应按项目事实保留、改写或删除对应规范。
 
 `template/.cowork-flow/changes/`
 由 `change.py` 管理 proposal、design、behavior specs 和归档，不维护实现 checklist。
@@ -161,7 +169,7 @@ cowork-flow sync .
 cowork-flow sync . --dry-run
 ```
 
-`sync` 会自动识别目标项目已安装的 host 目录：只有 `.codex/` 时只同步 Codex 资产，只有 `.opencode/` 时只同步 OpenCode 资产，两者都有时同步两者；对应 `.cowork-flow/adapters/<host>/` 也按识别出的平台同步。检测到 Codex 或 OpenCode 时会刷新 `.agents/skills/`；Claude Code-only 项目只刷新 `.claude/settings.json`、`.claude/hooks/`、`.claude/skills/`，不会创建 `.agents/skills/`。通用部分默认刷新 `.cowork-flow/scripts/`、`.cowork-flow/spec/workflow-state-templates.md`，以及 `AGENTS.md` 和 `CLAUDE.md` 中的 `<!-- COWORK-FLOW:START --> ... <!-- COWORK-FLOW:END -->` 托管块，保留托管块之外的项目自定义内容。`.cowork-flow/config.yaml`、`.cowork-flow/workflow.md`、除 `workflow-state-templates.md` 外的 `.cowork-flow/spec/`、任务、计划、变更和 workspace 记录默认受保护。只有明确传入 `--force` 时才整文件覆盖保护文件。
+`sync` 会自动识别目标项目已安装的 host 目录：只有 `.codex/` 时只同步 Codex 资产，只有 `.opencode/` 时只同步 OpenCode 资产，两者都有时同步两者；对应 `.cowork-flow/adapters/<host>/` 也按识别出的平台同步。检测到 Codex 或 OpenCode 时会刷新 `.agents/skills/`；Claude Code-only 项目只刷新 `.claude/settings.json`、`.claude/hooks/`、`.claude/skills/`，不会创建 `.agents/skills/`。通用部分默认刷新 `.cowork-flow/scripts/`、`.cowork-flow/spec/contracts/workflow-state-templates.md`，以及 `AGENTS.md` 和 `CLAUDE.md` 中的 `<!-- COWORK-FLOW:START --> ... <!-- COWORK-FLOW:END -->` 托管块，保留托管块之外的项目自定义内容。`.cowork-flow/config.yaml`、`.cowork-flow/workflow.md`、除 `workflow-state-templates.md` 外的 `.cowork-flow/spec/`、任务、计划、变更和 workspace 记录默认受保护。只有明确传入 `--force` 时才整文件覆盖保护文件。
 
 ## 常用入口
 
@@ -247,7 +255,7 @@ cowork_host_context_key: <host_context_key>
 
 子代理首步执行 `./.cowork-flow/run subagent bind <runtime_context_id> <host_context_key>`；主会话验收前必须确认 runtime context 中 `status=bound` 且 `bound_context_key` 匹配。默认角色为 `cowork-research`、`cowork-implement`、`cowork-check`，任务上下文来自已绑定 runtime context，而不是 prompt 形状。
 
-Codex hook 启用后，每轮会自动注入 `<workflow-state>`，其中包含入口分类、当前任务、状态来源和下一步流程提示。状态文本来自 `.cowork-flow/spec/workflow-state-templates.md`；`workflow.md` 只描述流程，不内联状态片段。hook 不替代主会话验收；它只负责把 task 状态和 workflow gate 放进上下文。
+Codex hook 启用后，每轮会自动注入 `<workflow-state>`，其中包含入口分类、当前任务、状态来源和下一步流程提示。状态文本来自 `.cowork-flow/spec/contracts/workflow-state-templates.md`；`workflow.md` 只描述流程，不内联状态片段。hook 不替代主会话验收；它只负责把 task 状态和 workflow gate 放进上下文。
 
 记录 session：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

package/src/lib/copy-template.js

@@ -1,4 +1,4 @@
-import { constants } from 'node:fs';
+import { constants } from 'node:fs';
 import { access, chmod, copyFile, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { dirname, join, relative } from 'node:path';
 
@@ -96,7 +96,7 @@ const SAFE_SYNC_FILES = new Set([
   '.cowork-flow/.version',
   '.cowork-flow/run',
   '.cowork-flow/run.cmd',
-  '.cowork-flow/spec/workflow-state-templates.md'
+  '.cowork-flow/spec/contracts/workflow-state-templates.md'
 ]);
 
 const COWORK_FLOW_START = '<!-- COWORK-FLOW:START -->';

package/template/.agents/skills/before-dev/SKILL.md

@@ -15,6 +15,7 @@ Use this immediately before code edits.
 4. Active task `implement.jsonl`
 5. Relevant `.cowork-flow/spec/*/index.md`
 6. Any exact files named by the task, plan, or user
+7. If the task changes behavior, locate or create `tdd.jsonl` evidence before implementation.
 
 Do not bulk-load unrelated tasks, archived sessions, or every spec file.
 

package/template/.agents/skills/check/SKILL.md

@@ -16,6 +16,7 @@ Use this after implementation and before `finish-work`.
 5. Review test intent: reject shallow tests that do not fail for meaningful behavior breaks.
 6. Run focused tests that would fail if the changed behavior broke.
 7. Run broader validation when the change touches shared runtime, templates, packaging, or public workflow.
+8. Report `test_intent_review` with the key tests that defend PRD acceptance behavior.
 
 ## Report
 

package/template/.agents/skills/party-mode-v2/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: party-mode-v2
+description: Use when the user requests a runtime-controlled multi-agent board discussion where children communicate through Party Mode V2 board APIs and the moderator only monitors or corrects drift.
+---
+
+# Party Mode V2
+
+Use this skill as a thin entrypoint for the Party Mode V2 runtime board. The Python runtime is the source of truth for discussion state, board visibility, validation, round limits, and final reports.
+
+## Boundaries
+
+- Party Mode V2 is advisory only.
+- It cannot mutate task status, start/review/complete/archive tasks, add sessions, commit, push, or satisfy formal workflow gates.
+- It cannot satisfy formal Implement or Check completion. Use `cowork-implement` and `cowork-check` for formal phases.
+- Discussion children are leaf executors. They do not dispatch, wait for, list, or close other agents.
+- The moderator does not forward, summarize, rewrite, or synthesize child opinions for other child agents.
+
+## Runtime First
+
+Always use the runtime controller:
+
+```text
+.cowork-flow/run party-v2 init
+.cowork-flow/run party-v2 monitor
+.cowork-flow/run party-v2 view
+.cowork-flow/run party-v2 post
+.cowork-flow/run party-v2 respond
+.cowork-flow/run party-v2 advance
+.cowork-flow/run party-v2 record-action-result
+.cowork-flow/run party-v2 finalize
+```
+
+Do not bypass a runtime rejection by manually accepting child output. Runtime validation failures must be fixed by a corrected child submission or by ending the discussion.
+
+## Board Rules
+
+- Child agents communicate through the board API.
+- Child-visible board output must be current-round only.
+- Historical board state is runtime-private and may be used only for audit or final reports.
+- Use at least three child agents unless the effective runtime config explicitly allows a different value.
+- The runtime emits host-neutral next actions. The active Host Adapter or moderator executes them for Codex, Claude Code, or OpenCode.
+- Host action results must be recorded back through `record-action-result` so `agents.json`, audit logs, and action history can prove lifecycle state.
+
+## Child Response Rules
+
+When a child sees a different position, it must choose exactly one:
+
+```text
+maintain
+revise
+concede
+```
+
+`concede` requires accepted evidence and why the prior position failed.
+`revise` requires the accepted part, rejected part, and updated position.
+`maintain` requires counter evidence or counter reasoning.
+
+Unsupported agreement, vague revision, and evidence-free rebuttal are invalid.
+
+## Moderator Role
+
+The moderator may:
+
+- run runtime commands,
+- execute host-neutral next actions through the active host,
+- record off-topic warnings through the runtime,
+- close children only when the runtime asks for closeout,
+- show runtime status or final reports to the user.
+
+The moderator must not:
+
+- forward one child opinion to another child,
+- create a claim table for child prompts,
+- vote-count as validation,
+- decide which child is correct.

package/template/.agents/skills/tdd/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: tdd
+description: Use when implementing behavior changes, bug fixes, state transitions, protocols, CLI/runtime contracts, data format changes, or error handling that can be tested before implementation.
+---
+
+# TDD
+
+Use this before editing behavior-changing code.
+
+## Red-Green-Refactor
+
+1. Map the task PRD acceptance criteria to stable IDs such as `AC-001`.
+2. Write the smallest meaningful failing test first.
+3. Run the red command and confirm it fails because the target behavior is missing or wrong.
+4. Implement the smallest change that makes the behavior pass.
+5. Run the green command and relevant broader verification.
+6. Refactor only after the behavior is green.
+
+Do not count shallow tests as TDD evidence. Tests that only import code, assert a function exists, assert `True`, count mocks without behavior, or mirror implementation details do not satisfy red-green-refactor.
+
+## Evidence
+
+Record TDD proof in `<task>/tdd.jsonl`. Each evidence line is one JSON object:
+
+```json
+{
+  "acceptanceId": "AC-001",
+  "testFile": "tests/test_example.py",
+  "testName": "test_behavior",
+  "redCommand": "python -m unittest tests.test_example.TestCase.test_behavior -v",
+  "redExitCode": 1,
+  "redOutputExcerpt": "expected failure excerpt",
+  "failureReason": "target behavior was not implemented",
+  "whyThisTestMatters": "explains which user-visible behavior would regress",
+  "greenCommand": "python -m unittest tests.test_example.TestCase.test_behavior -v",
+  "greenExitCode": 0,
+  "broaderVerification": "python -m unittest tests.test_example -v"
+}
+```
+
+Every evidence record must map to a PRD `acceptanceId`. The red failure must be about the target behavior, not syntax, import, environment, fixture, or setup failure.
+
+`testName` must resolve to the exact behavior test in `testFile`. Use one of:
+`test_method`, `ClassName.test_method`, or `module.ClassName.test_method`.
+Do not point evidence at a class, module, or a name that only exists in a command string.
+
+## Exemption
+
+Pure documentation, comment-only, or formatting-only tasks may use an exemption record instead of red/green evidence:
+
+```json
+{
+  "type": "exemption",
+  "acceptanceId": "AC-001",
+  "exemptionType": "docs-only",
+  "reason": "Only documentation wording changed; runtime behavior is untouched.",
+  "verificationCommand": "git diff --check"
+}
+```
+
+Do not use an exemption for runtime, CLI, protocol, state, data format, permission, or error-handling changes.

package/template/.agents/skills/writing-plans/SKILL.md

@@ -42,6 +42,7 @@ Start with:
 - Include a failing test before implementation when behavior can be tested.
 - Do not add shallow tests just to satisfy process. Avoid tests that only assert existence, mirror implementation details, count mocks without behavior, or snapshot empty structure.
 - For complex problems, test depth first: cover invariants, cross-layer contracts, state transitions, error boundaries, and real regression paths before narrow unit cases.
+- Map each behavior-changing test to a stable PRD acceptance ID and note where `tdd.jsonl` will record the red-green evidence.
 - Avoid placeholders such as TODO, TBD, "handle edge cases", or "write tests".
 - Keep root/template parity explicit when both copies exist.
 

package/template/.claude/agents/cowork-implement.md

@@ -28,6 +28,159 @@ or names another agent type, report `needs_context` and stop. Do not use
 `COWORK_ENTRY_CONTRACT_V1` to infer subagent identity; that contract classifies
 main-session prompts only.
 
+---
+
+## Mandatory Pre-Implementation Checklist
+
+Before writing any code, you MUST read and apply these spec files:
+
+1. `.cowork-flow/spec/guides/pre-implementation-checklist.md` — confirm scope, level, and success criteria
+2. `.cowork-flow/spec/guides/cross-layer-thinking-guide.md` — if changes cross 3+ layers
+3. `.cowork-flow/spec/guides/code-reuse-thinking-guide.md` — before adding new constants/utilities/DTOs
+
+Then read the relevant spec directory:
+- Backend work: `.cowork-flow/spec/backend/index.md` (and all linked docs)
+- Frontend work: `.cowork-flow/spec/frontend/index.md` (and all linked docs)
+
+---
+
+## Coding Gates (Hard Constraints)
+
+You MUST satisfy every gate below before considering a change complete.
+These are not suggestions — they are mandatory checkpoints.
+
+### Gate 1: Directory Structure Compliance
+
+- Backend: follow `.cowork-flow/spec/backend/directory-structure.md`
+  - Controller/API: thin entry only (param receive, auth entry, response orchestration)
+  - Service/UseCase: business rules
+  - Repository/DAO: persistence access
+  - Domain Model/Entity/Aggregate: clear boundaries
+  - No mixing of unrelated business in one module
+  - No business logic in Controllers
+  - No business-specialized logic in public modules
+- Frontend: follow `.cowork-flow/spec/frontend/directory-structure.md`
+  - Organize by functional module, not by "generic/non-generic"
+  - Page entry, business component, shared component, data access, state management must have clear layers
+  - Related files for the same feature should be colocated
+
+### Gate 2: Type Safety & Contract Sync
+
+- Frontend: follow `.cowork-flow/spec/frontend/type-safety.md`
+  - Shared interfaces, enums, error codes come from a single contract source
+  - No handwritten duplicate interface definitions
+  - When interfaces change, update callers, validation, and display layers together
+  - No masking structure problems with casts or forced assertions
+  - No missing null/empty/error/boundary state definitions
+- Backend: follow `.cowork-flow/spec/backend/error-handling.md`
+  - Unified error codes or error types
+  - Layered handling: parameter validation errors, business errors, system errors
+  - Stable external error structure; internal context preserved
+  - No leaking of underlying exceptions to callers
+  - Distinguish "expected business failure" from "system exception"
+  - Preserve traceId/requestId/correlationId
+  - Have a unified exception fallback
+
+### Gate 3: State Management Boundaries
+
+- Frontend: follow `.cowork-flow/spec/frontend/state-management.md`
+  - Server state managed by project's unified request/cache solution
+  - Client temporary state managed locally
+  - Global state only for truly cross-module shared state
+  - Handle loading, empty, error, disabled, and insufficient-permission states for ALL user-visible states
+  - No elevating local state to global unnecessarily
+  - No mixing server state with local state
+  - No bypass entries in permission state
+
+### Gate 4: Component & Hook Boundaries
+
+- Frontend: follow `.cowork-flow/spec/frontend/component-guidelines.md`
+  - Container components handle data & state; presentational components handle rendering
+  - Component API stays simple; no "universal component"
+  - Complex interactions split into reusable but clearly bounded small components
+  - Components must NOT承担过多业务逻辑
+  - Props must not be excessive or poorly named
+  - Components must not depend on too much external state
+- Frontend: follow `.cowork-flow/spec/frontend/hook-guidelines.md`
+  - Extract data fetching, subscriptions, side effects, complex state flows into Hooks
+  - Hook return values stay stable and understandable
+  - Hook names reflect behavior, not implementation
+  - Hooks must NOT hide incomprehensible side effects
+  - Hooks must NOT mix multiple unrelated responsibilities
+
+### Gate 5: Database & Transaction Boundaries
+
+- Backend: follow `.cowork-flow/spec/backend/database-guidelines.md`
+  - Table structure changes managed via migration files or versioned scripts
+  - Queries use the project's unified data access approach
+  - Write operations must address idempotency, concurrency impact, failure compensation, retry boundaries
+  - Audit fields, logical deletion, version numbers, tenant isolation must be consistent within the same data domain
+  - Raw SQL, bulk updates, cross-table aggregations, and long transactions must document index/lock/performance/rollback impact
+  - New tables must have primary keys, unique constraints, indexes, and necessary audit info
+  - Complex queries must avoid N+1, implicit full table scans, and uncontrolled pagination
+  - Transactions must NOT include external calls, slow queries, or unnecessary long lock holding
+  - Data migrations must address historical data, idempotency, failure recovery, and online rollback
+
+### Gate 6: Logging Standards
+
+- Backend: follow `.cowork-flow/spec/backend/logging-guidelines.md`
+  - Structured logging
+  - Unified recording of request ID, user ID, task ID, or trace ID
+  - Error logs record context without repeating the same exception
+  - Sensitive fields (account, token, key, ID card, phone) must be masked
+  - Never output complete request/response body
+  - No temporary `print`/`console` debug output left in main branch
+  - No duplicate error printing across layers
+
+### Gate 7: Quality Gates (Pre-Completion)
+
+- Backend: follow `.cowork-flow/spec/backend/quality-guidelines.md`
+- Frontend: follow `.cowork-flow/spec/frontend/quality-guidelines.md`
+
+Before marking any change complete, you MUST verify:
+1. Compilation/build/type-check passes
+2. Key business/interaction paths have automated test or explicit manual verification record
+3. Error paths, permission paths, data boundaries are verified
+4. New conventions, contracts, or migration impacts are documented in spec or task records
+5. Failed verification is NOT worked around by shrinking assertions, deleting tests, or skipping critical paths
+
+---
+
+## Forbidden Patterns (Zero Tolerance)
+
+You MUST NOT do any of the following:
+
+- Claim completion without verification
+- Use hardcoded values to bypass configuration, permissions, or contracts
+- Use temporary compatibility logic instead of real fixes
+- Change interfaces or data structures without updating docs and callers
+- Catch exceptions and silently swallow errors or return success
+- Use `any`, forced assertions, or empty object defaults to mask real type problems
+- Leave components without loading/empty/error/disabled/permission states
+- Rely on implicit side effects for interactions without explicit data flow and cleanup logic
+- Elevate local state to global state, or duplicate server state as multiple local states
+- Only verify ideal paths, not failures, empty data, or repeated operations
+- Introduce features not required by the PRD
+- Refactor unrelated modules "while you're at it"
+- Make premature abstractions for one-off code
+
+---
+
+## Execution Order
+
+1. Bind runtime context: `./.cowork-flow/run subagent bind <runtime_context_id> <host_context_key>`
+2. Read task directory from bound runtime context
+3. Read `<task>/prd.md`, `<task>/info.md`, `<task>/implement.jsonl`, and each JSONL `file` entry
+4. Read pre-implementation checklist: `.cowork-flow/spec/guides/pre-implementation-checklist.md`
+5. Read relevant spec directory (backend or frontend) and ALL linked documents
+6. Apply coding gates — verify each gate before proceeding
+7. Implement changes within assigned scope
+8. Run verification commands (compile, lint, test, build, type-check)
+9. Report changed files and exact verification commands
+10. Do NOT run task start, task finish, task archive, unscoped resume, commit, or push
+
+---
+
 Rules:
 
 - Read the task directory from the bound runtime context.

package/template/.claude/hooks/inject-workflow-state.py

@@ -19,7 +19,7 @@ DEFAULT_CONTRACT_REGISTRY = {
     "contracts": [
         {
             "id": "COWORK_ENTRY_CONTRACT_V1",
-            "path": ".cowork-flow/spec/entry-contract.md",
+            "path": ".cowork-flow/spec/contracts/entry-contract.md",
             "digest": [
                 "Classify main-session requests before task start, resume, archive, or commit.",
                 "Runtime context, not prompt labels, identifies formal subagent sessions.",
@@ -28,7 +28,7 @@ DEFAULT_CONTRACT_REGISTRY = {
         },
         {
             "id": "RUNTIME_CONTEXT_DISPATCH_V2",
-            "path": ".cowork-flow/spec/subagent-dispatch.md",
+            "path": ".cowork-flow/spec/contracts/subagent-dispatch.md",
             "digest": [
                 "Formal subagent work is keyed by cowork_runtime_context_id.",
                 "Explicit shim bind records bound_context_key before formal output is accepted.",
@@ -88,7 +88,7 @@ def _normalize_hook_input(hook_input: dict[str, Any]) -> dict[str, Any]:
 
 
 def _load_breadcrumbs(root: Path) -> dict[str, str]:
-    workflow = root / ".cowork-flow" / "spec" / "workflow-state-templates.md"
+    workflow = root / ".cowork-flow" / "spec" / "contracts" / "workflow-state-templates.md"
     try:
         text = workflow.read_text(encoding="utf-8")
     except OSError:
@@ -102,16 +102,23 @@ def _as_string_list(value: Any) -> list[str]:
     return [item for item in value if isinstance(item, str) and item.strip()]
 
 
-def _load_contract_registry(root: Path) -> list[dict[str, Any]]:
-    registry_file = root / ".cowork-flow" / "spec" / "registry.json"
+def _load_contract_registry(root: Path) -> tuple[list[dict[str, Any]], str | None]:
+    registry_file = root / ".cowork-flow" / "spec" / "runtime" / "contract-registry.json"
     try:
         data = json.loads(registry_file.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+    except OSError:
         data = DEFAULT_CONTRACT_REGISTRY
+        warning = f"contract registry unavailable at {registry_file}; using fallback digest"
+    except json.JSONDecodeError:
+        data = DEFAULT_CONTRACT_REGISTRY
+        warning = f"contract registry invalid at {registry_file}; using fallback digest"
+    else:
+        warning = None
     contracts = data.get("contracts") if isinstance(data, dict) else None
     if not isinstance(contracts, list):
         contracts = DEFAULT_CONTRACT_REGISTRY["contracts"]
-    return [contract for contract in contracts if isinstance(contract, dict)]
+        warning = warning or f"contract registry has no contracts array at {registry_file}; using fallback digest"
+    return [contract for contract in contracts if isinstance(contract, dict)], warning
 
 
 def _contract_fingerprint(root: Path, contracts: list[dict[str, Any]]) -> str:
@@ -129,13 +136,15 @@ def _contract_fingerprint(root: Path, contracts: list[dict[str, Any]]) -> str:
 
 
 def _build_contract_digest(root: Path) -> str:
-    contracts = _load_contract_registry(root)
+    contracts, warning = _load_contract_registry(root)
     fingerprint = _contract_fingerprint(root, contracts)
     lines = [
         '<cowork-runtime host="claude-code" adapter="claude-code.hooks">',
         f'<contract-digest fingerprint="{fingerprint}">',
         "policy: repeat this short digest every hook; read full spec files only before listed actions.",
     ]
+    if warning:
+        lines.append(f"warning: {warning}")
     for contract in contracts:
         contract_id = contract.get("id")
         path = contract.get("path")

package/template/.claude/skills/before-dev/SKILL.md

@@ -15,6 +15,7 @@ Use this immediately before code edits.
 4. Active task `implement.jsonl`
 5. Relevant `.cowork-flow/spec/*/index.md`
 6. Any exact files named by the task, plan, or user
+7. If the task changes behavior, locate or create `tdd.jsonl` evidence before implementation.
 
 Do not bulk-load unrelated tasks, archived sessions, or every spec file.
 

package/template/.claude/skills/check/SKILL.md

@@ -16,6 +16,7 @@ Use this after implementation and before `finish-work`.
 5. Review test intent: reject shallow tests that do not fail for meaningful behavior breaks.
 6. Run focused tests that would fail if the changed behavior broke.
 7. Run broader validation when the change touches shared runtime, templates, packaging, or public workflow.
+8. Report `test_intent_review` with the key tests that defend PRD acceptance behavior.
 
 ## Report
 

package/template/.claude/skills/party-mode-v2/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: party-mode-v2
+description: Use when the user requests a runtime-controlled multi-agent board discussion where children communicate through Party Mode V2 board APIs and the moderator only monitors or corrects drift.
+---
+
+# Party Mode V2
+
+Use this skill as a thin entrypoint for the Party Mode V2 runtime board. The Python runtime is the source of truth for discussion state, board visibility, validation, round limits, and final reports.
+
+## Boundaries
+
+- Party Mode V2 is advisory only.
+- It cannot mutate task status, start/review/complete/archive tasks, add sessions, commit, push, or satisfy formal workflow gates.
+- It cannot satisfy formal Implement or Check completion. Use `cowork-implement` and `cowork-check` for formal phases.
+- Discussion children are leaf executors. They do not dispatch, wait for, list, or close other agents.
+- The moderator does not forward, summarize, rewrite, or synthesize child opinions for other child agents.
+
+## Runtime First
+
+Always use the runtime controller:
+
+```text
+.cowork-flow/run party-v2 init
+.cowork-flow/run party-v2 monitor
+.cowork-flow/run party-v2 view
+.cowork-flow/run party-v2 post
+.cowork-flow/run party-v2 respond
+.cowork-flow/run party-v2 advance
+.cowork-flow/run party-v2 record-action-result
+.cowork-flow/run party-v2 finalize
+```
+
+Do not bypass a runtime rejection by manually accepting child output. Runtime validation failures must be fixed by a corrected child submission or by ending the discussion.
+
+## Board Rules
+
+- Child agents communicate through the board API.
+- Child-visible board output must be current-round only.
+- Historical board state is runtime-private and may be used only for audit or final reports.
+- Use at least three child agents unless the effective runtime config explicitly allows a different value.
+- The runtime emits host-neutral next actions. The active Host Adapter or moderator executes them for Codex, Claude Code, or OpenCode.
+- Host action results must be recorded back through `record-action-result` so `agents.json`, audit logs, and action history can prove lifecycle state.
+
+## Child Response Rules
+
+When a child sees a different position, it must choose exactly one:
+
+```text
+maintain
+revise
+concede
+```
+
+`concede` requires accepted evidence and why the prior position failed.
+`revise` requires the accepted part, rejected part, and updated position.
+`maintain` requires counter evidence or counter reasoning.
+
+Unsupported agreement, vague revision, and evidence-free rebuttal are invalid.
+
+## Moderator Role
+
+The moderator may:
+
+- run runtime commands,
+- execute host-neutral next actions through the active host,
+- record off-topic warnings through the runtime,
+- close children only when the runtime asks for closeout,
+- show runtime status or final reports to the user.
+
+The moderator must not:
+
+- forward one child opinion to another child,
+- create a claim table for child prompts,
+- vote-count as validation,
+- decide which child is correct.

package/template/.claude/skills/tdd/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: tdd
+description: Use when implementing behavior changes, bug fixes, state transitions, protocols, CLI/runtime contracts, data format changes, or error handling that can be tested before implementation.
+---
+
+# TDD
+
+Use this before editing behavior-changing code.
+
+## Red-Green-Refactor
+
+1. Map the task PRD acceptance criteria to stable IDs such as `AC-001`.
+2. Write the smallest meaningful failing test first.
+3. Run the red command and confirm it fails because the target behavior is missing or wrong.
+4. Implement the smallest change that makes the behavior pass.
+5. Run the green command and relevant broader verification.
+6. Refactor only after the behavior is green.
+
+Do not count shallow tests as TDD evidence. Tests that only import code, assert a function exists, assert `True`, count mocks without behavior, or mirror implementation details do not satisfy red-green-refactor.
+
+## Evidence
+
+Record TDD proof in `<task>/tdd.jsonl`. Each evidence line is one JSON object:
+
+```json
+{
+  "acceptanceId": "AC-001",
+  "testFile": "tests/test_example.py",
+  "testName": "test_behavior",
+  "redCommand": "python -m unittest tests.test_example.TestCase.test_behavior -v",
+  "redExitCode": 1,
+  "redOutputExcerpt": "expected failure excerpt",
+  "failureReason": "target behavior was not implemented",
+  "whyThisTestMatters": "explains which user-visible behavior would regress",
+  "greenCommand": "python -m unittest tests.test_example.TestCase.test_behavior -v",
+  "greenExitCode": 0,
+  "broaderVerification": "python -m unittest tests.test_example -v"
+}
+```
+
+Every evidence record must map to a PRD `acceptanceId`. The red failure must be about the target behavior, not syntax, import, environment, fixture, or setup failure.
+
+`testName` must resolve to the exact behavior test in `testFile`. Use one of:
+`test_method`, `ClassName.test_method`, or `module.ClassName.test_method`.
+Do not point evidence at a class, module, or a name that only exists in a command string.
+
+## Exemption
+
+Pure documentation, comment-only, or formatting-only tasks may use an exemption record instead of red/green evidence:
+
+```json
+{
+  "type": "exemption",
+  "acceptanceId": "AC-001",
+  "exemptionType": "docs-only",
+  "reason": "Only documentation wording changed; runtime behavior is untouched.",
+  "verificationCommand": "git diff --check"
+}
+```
+
+Do not use an exemption for runtime, CLI, protocol, state, data format, permission, or error-handling changes.