Codex-teammode Workflow

中文优先 / English below.

安装

1. Clone 本仓库到本地：

   git clone https://github.com/gdl1605/codex-teammode-workflow.git
   

2. 打开 clone 得到的目录，复制 BOOTSTRAP_PROMPT.md 的全部内容。

3. 在任意一个你想安装工作流的项目中打开 agent 对话（如 Codex 或 Claude Code），粘贴并发送即可。Agent 会读取工作流，并将它安装到当前项目。

这是什么

Codex-teammode Workflow 是一个面向 Codex 同时兼容 Claude Code 的 prompt-first 工作流包。它不是运行时框架，而是一组可复制到任意项目中的 Markdown 规则、bootstrap prompt 和 docs scaffold，让个人开发者和小团队在 AI 编码会话中稳定执行：

• audit-first 根因锁定
• 普通开发：正式计划交付前核对关键取舍来源，Grill-me 澄清未确认选择；主 agent 实现，fresh evaluator 独立核验事实与假设
• docs impact check
• 可选 $docs-review：人工触发的跨文档事实对账与清理
• prompt 显式触发的 Team Loop：Leader + planner / generator / scout / evaluator
• 不让 agent 自己宣布人工验收；Team Loop 停在 human_acceptance_required 或 blocked

适用对象

• 使用 Codex 或 Claude Code 的个人开发者
• 希望统一 AI 协作规则的小团队
• 经常被上下文丢失、想象式修复、未审计执行困扰的 AI coding agent 重度用户

安装后会生成什么

目标 agent 会读取工作流内核，审计目标仓库，并创建或合并：

AGENTS.md                          # Codex / AGENTS.md-aware tools 入口
CLAUDE.md                          # Claude Code 入口，与 AGENTS.md 同步
workflow/audit-first.md            # 根因审计优先流程
docs/
  README.md                        # docs 入口地图
  workflow/                        # 普通开发、独立 evaluator、Team Loop、docs maintenance
  product/                         # 项目事实占位，需按目标仓库填写
  architecture/                    # 架构占位，需按目标仓库填写
  handoff/                         # 跨会话 handoff
  plans/                           # active / completed plans
  evidence/                        # audit evidence

升级旧项目

当目标项目已经安装过旧版工作流时，不要重新粘贴 bootstrap prompt 做全量覆盖。把新版 codex-teammode-workflow/ 文件夹放进目标项目后，粘贴 UPDATE_PROMPT.md。

升级流程按 UPDATE_MANIFEST.md 的 ownership 策略执行：

• workflow kernel：清单内的普通开发 / Team Loop 内核及 workflow/audit-first.md 原地替换旧版文件；按 remove-workflow 清单删除退役 planner schema 等精确文件，不生成 .new，并清理旧升级遗留的 workflow .new 文件。
• mixed files：AGENTS.md、CLAUDE.md、docs/README.md 只替换 codex-teammode:managed block，保留 block 外的目标项目规则。
• target facts：docs/product/*、docs/architecture/*、docs/handoff/*、docs/plans/*、docs/evidence/* 永不自动覆盖。

升级完成后，目标项目应写入 docs/workflow/.codex-teammode-version，用于记录版本和已安装文件 hash。后续升级会用这个 marker 做基线和报告，但 workflow kernel 仍按新版原地替换。

重要边界

这个项目只安装 工作流机制，不安装任何业务事实。

Bootstrap prompt 会要求目标 agent 不要复制本仓库的产品状态、计划、证据、架构结论或领域示例。普通实现事实仍以目标仓库的 current code 为首要证据；显式运行 $docs-review 时则按 claim 类型路由权限，业务意图、部署、人工验收和法务状态不能被“代码已实现”替代。

核心概念

• 普通工作流：主 agent 在正式计划交付前核对关键取舍来源、追问未确认选择（含仅规划），授权实现后派 fresh 只读 evaluator；确定缺口直接回主 agent，业务争议交用户裁决。
• Team Loop：由 Leader 在同一个会话里调度 planner / generator / scout / evaluator。
• audit-first：根因未锁定时先审计、写 evidence，再进入执行。
• Fact priority：普通实现事实按 current code > topic docs > docs/handoff/latest.md > archive；$docs-review 对业务意图、部署、验收和法务 claim 使用各自权限。
• docs impact / docs-review：前者是每轮增量微循环；后者是人工触发、Plan/Apply 两阶段的事实校正宏循环。
• docs-review v3 plan gate：scanner schema 5 的每条 finding 都绑定 source fingerprint、结构化 resolution group、精确人工权限和批准文件；完整 audit scope 与每项 edit contract 同时冻结，机器 Claim ID / 稳定锚点不得写进业务 docs。
• docs-review sharded closure：大型全文审查按预算分片，原始 auditor JSON 无损校验；所有 shard pass 后再由全新 synthesis auditor 做跨分片终审，任一不足先停在人类确认门。
• human_acceptance_required：Team Loop 的人工验收停点，只有人类可以验收。

更多术语见 CONCEPTS.md。

Docs Review Skill

skills/docs-review/ 是随工作流包版本化、但只允许人工显式触发的
项目事实校正 skill。它解决的是长期增量维护后常见的宏观偏差：同一业务事实散落在多份
docs 中、current 与 candidate 混写、active/completed 生命周期错位、历史状态伪装成当前
状态，以及实现、部署、验收、法务和发布被压缩成一个模糊的“已完成”。

它和普通 docs impact 的分工是：

• docs impact 是每轮结束时维护受影响主落点的微循环。
• $docs-review 是人工触发、跨文档对账和清理的宏循环，不会被普通 docs 修改自动调用。

Codex 中推荐分两阶段使用：

Plan Mode:  $docs-review [scope=<domain-or-docs-path>]
Default Mode: $docs-review apply

Plan Mode 只读 docs、current code、schema、tests 和已有 evidence，逐类判断事实权限并向人类
询问无法由仓库证据唯一决定的业务含义。apply 只消费同一任务中已经批准、通过 schema-3
计划门且 baseline 未漂移的方案，只修改批准列表中的 Markdown docs；它不会顺手修改业务
代码、migration、测试、部署环境或外部系统。

v3 为每条 scanner-schema-5 finding 记录 source fingerprint、结构化 disposition、目标语义、
证据和精确人工权限，并冻结完整 audit_scope_manifest 与结构化 edit_contracts，验证
canonical transfer、path rewrite 和 lifecycle move 的后置条件；自然语言业务含义交给独立
审计，不把 Claim ID、audit ID 或 validator 专用锚点写进项目 docs。Apply 后，大型全文范围
会按预算拆成多个 fresh shard auditor，原始 JSON 报告必须无损保存并通过严格校验。全部 shard
pass 后，还要由一个全新的 synthesis auditor 重新核验 canonical owner、跨分片 consumer 和
原始 evidence。任一 deficiency 或协议错误都会立即停在人类确认门，不能在同一失败轮自行修复。

最终 verdict 只有 consistent、partially_consistent 或 blocked；这些结果都不会自动推导
human_accepted、legal_accepted、deployed 或 released。完整协议见
SKILL.md，事实模型与独立审计角色见
skills/docs-review/references/。

普通开发工作流

安装后，未显式启用 Team Loop 的开发维护使用普通工作流，主 agent 可以直接改文件：

核对原要求与实际代码 → 草案 → 关键取舍来源核对 / Grill-me 澄清 → 正式计划
→ 仅规划则交付结束；已授权实现则继续实现、必要验证和 fresh evaluator 核验

evaluator 首先审查关键断言来自已有事实、用户决定还是 agent 假设，重点找假设被写成事实、被升级成执行条件，以及计划与实际消费者之间的遗漏。审查依据来自原要求、有效合同、实际 diff、真实调用链和实际验证证据；实现者总结只用于导航。

已有决定不重复追问，不为每次改动新建 Spec、校验脚本或审批。用户和目标项目的明确权限 / subagent 限制仍然有效。问答、只读、仅计划及安装升级按各自任务执行，不自动进入实现循环；普通独立核验也不启动可选宏循环。

仅规划也要在正式计划交付前交代关键取舍的决定及出处。已有用户决定、有效合同或明确委托足够时，引用依据直接沿用；仍是 agent 建议的关键选择先问用户。不能因自己选了“默认 / 首版暂不支持”就宣称没有未决项。普通实现细节不逐项请用户批准。

Grill-me 默认调用原生结构化提问工具发出可选卡片；Codex 暴露 request_user_input_async 时使用它。每轮发当前可回答的独立问题，给出选项、影响和推荐，收到实际用户回答后更新同一份计划，再推进依赖问题。推荐、预选和工具返回都不算确认，不按等待时长自行代答；只有工具不可用或受限时才说明限制并改用文本选项。

完整流程与 Review Request 见 default-workflow.md，只读 subagent 合同见 independent-evaluator.md。

Team Loop 工作流

Team Loop 是显式选择的多角色工作流。只有用户在 prompt 中明确使用 @team-loop、要求使用 Team Loop / teamloop，或明确要求 Leader 调度 subagent 时才启用。仅要求独立 evaluator、讨论、引用或修改这些规则不构成触发；未触发时使用普通开发工作流。

Team Loop 的核心通信结构是：

User
  <-> Leader
      -> planner subagent
      -> generator subagent
      -> scout subagent A / B
      -> evaluator subagent
      -> human_acceptance_required

两种运行模式

本节只在用户已经明确进入 Team Loop 后使用，用于选择 Team Loop 内部节奏，不作为自动触发 Team Loop 的条件。

• plan-gated：先把 planner 收口结果交给用户确认，再派 generator。
• auto-execute：Leader 在 planner 快速收口后直接派 generator，最后仍停在人工验收。

角色规范

• Leader 是唯一调度者。Leader 负责确认目标、判断 plan-gated / auto-execute、派生 subagent、附带 Context Bootstrap、核验每个 subagent 的 Read Scope Ack、整理 Evidence Pack、运行验证、组装 Evaluation Bundle，并决定返工、阻塞或停在 human_acceptance_required。Leader 不能直接实现或改文件，不能让 subagent 彼此直接通信，也不能替 evaluator 自评通过。
• Planner subagent 是 Team Loop 内部只读角色。它负责读取入口文档、目标相关 docs / code / handoff / evidence，收口目标和非目标，判断风险模式，定义 allowed scope / forbidden scope、minimum progress unit、generator 启动前核对清单、可能的 scout 问题和 evaluator focus。planner 不改代码，也不能把建议实现层写成已验证事实。
• Generator 是默认唯一写代码角色。它必须消费 Leader 提供的 planner handoff 和 Evidence Pack，但仍要重新审计 current code，并在输出里给出 Read Scope Ack、touched files、修改摘要、验证建议、evaluator notes 和 docs impact。若审计范围过大，generator 只能向 Leader 提交 Scout Request，不能直接联系 scout 或自行派生 subagent。
• Scout 是只读线索收集角色。它只回答 Leader 指定的问题，只读必要的 current code、docs、handoff 或 evidence，并输出 verified facts、inferences、unresolved 和 citations。Scout Evidence 只能回 Leader，不能直接传给 generator，也不能设计完整实现方案或评价结果是否通过。
• Evaluator 是独立核验角色。它只消费 Leader 提供的 Evaluation Bundle 作为叙事入口，并读取必要 diff、code 和 docs 做复核。evaluator 要核验 generator 的 read scope、actual diff、allowed scope、docs impact 和验证输出，优先找 P0 / P1 阻塞问题；P2 / P3 默认进入 residual risk、backlog 或人工验收。

硬规则

• subagent 之间禁止直接通信；所有 planner / generator / scout / evaluator 输出都只回 Leader。
• Leader 每次派生 fresh subagent 必须附带 Context Bootstrap；复用 planner / scout 时必须附带 cache manifest 和 freshness check。每个 subagent 输出开头必须有 Read Scope Ack。
• planner / scout 可按 freshness check 有限复用；generator / evaluator 每轮 fresh。
• Evidence Pack 不能替代 generator 自己读取 current code；对当前实现事实，证据优先级是 current code > topic docs > handoff，业务意图和外部生命周期事实按各自权限/evidence 路由。
• P0 / P1、验证失败、越过 forbidden scope、缺少关键 read scope 时进入返工或 blocked。
• Team Loop 的终态只能是 human_acceptance_required 或 blocked；accepted 只能由人类明确表达。

完整规范和启动模板见 workflow-kernel/docs/workflow/team-loop.md，subagent 默认核心合同见 workflow-kernel/docs/workflow/team-loop-core.md，轻量角色胶囊见 workflow-kernel/docs/workflow/team-loop-roles/。

当前状态

发布记录为 v0.3.1；当前源码内核为尚未发布的 0.4.0-dev，普通工作流变更见 CHANGELOG.md 的 Unreleased。核心内核中文优先，README 提供中英双语入口，支持 Codex 和 Claude Code；其他工具可参考 AGENTS.md/CLAUDE.md 约定自行适配。

贡献

欢迎贡献：

• 更清晰的 workflow kernel 表达
• Codex / Claude Code 使用反馈
• 英文翻译
• 更好的安装脚本和一致性检查
• 泛化、脱敏、可复用的示例模板

见 CONTRIBUTING.md。

路线图见 ROADMAP.md，支持渠道见 SUPPORT.md。

License

MIT.

English

Installation

1. Clone this repository locally:

   git clone https://github.com/gdl1605/codex-teammode-workflow.git
   

2. Open the cloned directory and copy the entire contents of BOOTSTRAP_PROMPT.md.

3. Open an agent conversation in any project where you want the workflow installed, paste the contents, and send. The agent will read the workflow and install it into that project.

About

Codex-teammode Workflow is a prompt-first workflow package for Codex and Claude Code. It is not a runtime framework. It is a portable set of Markdown rules, a bootstrap prompt, and a docs scaffold that helps solo developers and small teams run a consistent AI coding process.

Default development keeps planning and implementation in the main agent, traces consequential choices to their authority and clarifies unconfirmed choices before formal plan delivery (including plan-only tasks), and dispatches a fresh read-only evaluator after authorized implementation. Explicit Team Loop instead uses a Leader coordinating planner, generator, scout, and evaluator roles. Both use evidence appropriate to the claim and scoped docs impact checks. The optional explicit-only $docs-review skill remains separately installable.

The bundled docs-review skill is optional and installed separately through
install.sh --install-docs-review; bootstrap does not modify personal skill directories.

Docs Review v3 uses scanner schema 5 and a schema-3 plan gate: each deterministic finding
binds its source fingerprint to scoped authority, intended semantics, evidence, and approved
docs. The plan also freezes the complete audit scope and executable edit contracts. Audit-only
IDs and validator phrases stay out of project documentation. After apply, large full-read
scopes are split into bounded independent shards; raw reports are validated losslessly and a
fresh synthesis auditor must pass before the final verdict. Any deficiency stops at a human
approval gate. Unchanged passing shards may be safely reused by hash in a correction round,
but synthesis is always fresh.

Upgrade an existing target project by copying in the newer package and pasting UPDATE_PROMPT.md. Updates are ownership-based: workflow kernel files replace old workflow files in place, mixed files use managed blocks, and target project facts are never overwritten.

Docs Review At A Glance

skills/docs-review/ is an explicit-only macro workflow for
reconciling project facts after incremental documentation has accumulated duplication, stale
state, lifecycle leakage, or conflicting business meaning. It complements the per-turn
docs impact micro loop and is never invoked automatically by routine documentation edits.

Run $docs-review [scope=<domain-or-docs-path>] in Plan Mode for a read-only audit and human
arbitration, then run $docs-review apply in Default Mode only after the same task has an
approved schema-3 plan and an unchanged baseline. Apply is docs-only: it does not change
business code, migrations, tests, deployments, or external systems.

Version 3 binds every scanner-schema-5 finding to an exact source fingerprint, structured
disposition, evidence, intended semantics, and scoped authority. It also closes the complete
audit scope and validates executable edit contracts for transfers, path rewrites, and moves.
Post-apply closure uses bounded fresh shard auditors, losslessly validated raw JSON reports,
and a new synthesis auditor for cross-shard consumers and original evidence. Any deficiency
or protocol failure stops at a human approval gate. See the complete contract in
skills/docs-review/SKILL.md.

Default Development At A Glance

Read the original request and current code, draft a proportional plan, and trace consequential choices to user decisions, effective contracts, or explicit delegation before formal plan delivery, including plan-only tasks. Use the built-in Grill-me step for still-unconfirmed choices and record answers and authority in the same plan. Choosing a default yourself does not settle a user decision. When no questions are needed, briefly identify the existing basis; routine implementation details need no extra approval. If authorized, implement, run necessary focused checks, and dispatch a fresh read-only evaluator. No external Grill-me skill installation is required.

Drive Grill-me with native structured question cards. Use request_user_input_async when exposed, respecting its current schema and mode restrictions. Present independent questions together with options, consequences, and a recommendation; wait for actual user answers, update the same plan, then ask dependent questions. A recommended/preselected option, tool return, closed request, or elapsed time is not an answer. Explain an actual tool limitation before falling back to numbered text choices.

The evaluator checks facts versus decisions versus assumptions, actual behavior and consumers, unsupported execution conditions, and completion claims. Send the original requirements and corrections, canonical contracts, confirmed decisions, labeled assumptions, actual changes, and real validation evidence through a scoped Review Request. Confirmed gaps return directly to the implementing main agent; factual unknowns need evidence; genuine business disputes remain for the user. Requesting only this evaluator does not start Team Loop.

See default-workflow.md and independent-evaluator.md. Respect explicit target restrictions; do not add approval rituals, arbitrary gates, or new test harnesses. Read-only, plan-only, installation, and update tasks do not automatically enter the development loop.

Team Loop At A Glance

Team Loop is an explicit alternative to default development. It starts only when the user explicitly asks for @team-loop, Team Loop, teamloop, or Leader-driven subagent coordination. Requesting an independent evaluator, discussing, quoting, or editing its rules does not start the loop.

• Leader is the only scheduler. It chooses plan-gated or auto-execute, sends each subagent a Context Bootstrap, checks Read Scope Ack, prepares Evidence Packs and Evaluation Bundles, runs validation, and stops at human_acceptance_required. Leader does not implement changes directly.
• Planner subagent is read-only. It narrows the problem, risk mode, allowed scope, forbidden scope, minimum progress unit, generator startup checks, possible scout questions, and evaluator focus.
• Generator is the default writing role. It must re-audit current code before implementation, respect forbidden scope, report touched files and docs impact, and request scout support only through Leader.
• Scout is read-only evidence support. It answers Leader-scoped questions with verified facts, inferences, unresolved items, citations, and confidence.
• Evaluator is independent verification. It reviews the Evaluation Bundle, diff, code, docs, validation output, generator read scope, and docs impact claim before returning pass, request changes, or blocked.

Planner and scout may be reused across dispatches with freshness checks; generator and evaluator are always fresh per round.

Each fresh subagent should receive a slim Context Bootstrap with the current tool's primary entry file, docs/README.md, team-loop-core.md, and only its matching role capsule.

Subagents never talk directly to each other. The final state is human_acceptance_required or blocked; only a human can mark the work accepted.