Repo Governance Bootstrap

何时调用

用户说出以下任一：

• "初始化文档治理 / 项目治理 / repo governance"
• "建立 ADR / roadmap / 文档骨架"
• "新仓库接入 AI 协作"
• "整理混乱的 docs 目录"

跳过条件：仓库已有 docs/INDEX.md 和 docs/ACTIVE_CONTEXT.md → 提演化方案、不重新初始化；绝不覆盖既有治理文件。

FOR

• 新仓库初始化
• 引入 AI coding workflow
• 重构混乱 docs 结构
• 建立长期演化管理

NOT FOR

• 重型流程管理 / Jira / RFC 工作流
• 复杂审批体系
• 外部 wiki 替代 Git
• 创建 future_plan.md / ideas.md / generic TODO dump

目标结构（最小）

docs/
├── INDEX.md
├── ACTIVE_CONTEXT.md                 # 当前焦点 / hot context
├── decisions/
│   └── ADR-0001-<slug>.md            # 仓库边界（ADR 编号固定 4 位）
├── modules/
│   └── <module>.md                   # 每个核心模块一个 flat 文件
└── roadmap/
    ├── README.md                     # status-bucket 索引（Active / Deferred / Obsolete）
    ├── active-roadmap.md             # 单文件，inline Status
    ├── deferred/
    │   └── README.md                 # deferred 索引（Items 表 + Entry Criteria + Promotion Rule）
    └── obsolete/
        └── README.md                 # obsolete 索引（仅索引，少用）

AGENTS.md                             # repo 治理规则（Codex 读）
CLAUDE.md                             # 一行：@AGENTS.md（Claude 读）

ACCESS.local.md                       # gitignored — 本机接入凭证 + 环境拓扑 + 验证配方

约定原则

• Roadmap 初始化即建三桶：active-roadmap.md（单文件，inline Status:）+ deferred/ + obsolete/（各带 README.md 索引）。active 保持单文件——item 内联，逐项拆文件无收益；deferred 项内容厚，一项一文件 <PREFIX>-DEFER-NNN-<slug>.md。<PREFIX> = 项目自定义 ID 前缀，按项目名取（不要硬编码他人前缀）。
• Module docs 默认单文件 modules/<m>.md。模块复杂到 README + architecture + evolution 各需独立维护时再拆成 modules/<m>/{overview,architecture,evolution}.md。
• ADR 编号固定 4 位零填充（ADR-0001、ADR-0014），全仓一致。
• 不创建 generic backlog（future_plan.md / ideas.md / TODO dump）；未来工作进 roadmap/deferred/。
• ACTIVE_CONTEXT 是快照不是日志：完整契约见 references/PROJECT_AGENT.md §6（canonical，随成品写进项目 AGENTS.md）+ 下方「ACTIVE_CONTEXT.md 模板」的契约头。核心 = 每次收口整篇重写而非追加。实证（why）：某项目 ACTIVE_CONTEXT 被当 checkpoint 日志逐条 append，4 天涨到 190 行后整体冻结腐烂。
• 外部任务系统优先：若程序任务已在外部系统跟踪（Jira / Linear / 飞书 bitable 等），roadmap 是映射层不是第二任务系统——沿用外部 ID（如 T-NNN），在 roadmap README 和 AGENTS.md Traceability 里写明外部 SoT；只给外部系统没有记录的仓库内部项造 RD 号。两套任务账本必烂一套。
• 接入凭证与操作配方进 `ACCESS.local.md`（gitignored）：committed 治理骨架（INDEX/ADR/module/roadmap/ACTIVE_CONTEXT）回答 what/why，全部不含 secret；它们缺的那一块——"怎么真正连上、登录、验证运行中的系统，以及连上用的凭证"——落在一份 gitignored 的 `ACCESS.local.md`，三段式：① 接入凭证（URL/账号/token/cred）② 环境拓扑速查（部署布局/tenant id/env flags/调用路径）③ 验证配方与 gotcha（E2E 验收步骤、调试踩坑）。它是 ACTIVE_CONTEXT.md 的本地含密镜像兄弟（committed=what，local=how-to-reach），是新会话/新 agent 摸到系统的入口。凭证口径必须一致：canonical home 是外部 vault（如团队密钥库），此文件是本机缓存，靠 gitignore + 提交前 redaction sweep 兜底；secret 永不进 committed tree / traces / 对外消息。建文件即把 ACCESS.local.md 写进 .gitignore。

（拓扑与凭证有意同进这一份、不另拆"非密 config"——内网拓扑[IP/库名/结构]本身也算敏感面，少一层"该进哪"的纠结。） 额外两条（AI/服务项目高频）：① 凭证间接——cred 常存于 env 变量 X 而代码读 Y（如存 <VENDOR>_KEY、 网关读 LLM_API_KEY），ACCESS 必记"谁存谁读 + 桥接命令"，是 demo-day 401 头号根因；② 依赖外部认证服务前 先跑活体 auth smoke 并读失败模式（失败模式见模板 ③）——便宜的当前态求证挡在昂贵的"以为配好了"之前。

• 治理目录值得 local-only git 化（尤其多子 repo 的 umbrella——目录本身套着各有 remote 的子 repo、自己不是 git repo）：把 docs/ + 治理文件纳入一个无 remote 的本地 git、gitignore 掉子 repo，换来文档变更历史、误删恢复、agent 派工后的 git diff 漂移审计。orchestration docs 一旦成为多 agent 并发写的 SoT 尤其值得（实证：曾发生 agent 误删关键 docs、无版本可恢复）。加 remote 前先做一次 secrets sweep（内网 IP/库名/拓扑也算敏感面），并在 AGENTS.md 写明这条。多 agent 编排场景配合 cto-orchestration skill。

执行步骤

1. 询问用户（如果未提供）：

• 项目名 / 一句话定位
• 核心 capability（≤3 个）
• 核心 module 名（≤3 个）
• 是否需要 AGENTS.md（推荐：是，串联 Codex + Claude）

1. 创建目录骨架：docs/decisions/、docs/modules/、docs/roadmap/deferred/、docs/roadmap/obsolete/（roadmap 三桶一次建好）。

1. 生成 `docs/INDEX.md`：含 Decisions / Modules / Roadmap / AI Context 四节 + Traceability 表（| Capability | Component | ADR | Roadmap |）。

1. 生成 `docs/decisions/ADR-0001-<slug>.md`：用下方 ADR 模板，主题是"仓库定位与边界"——记录这个仓库 FOR 什么 / NOT FOR 什么。Status: proposed 起步，由用户后续确认为 accepted。

1. 生成 `docs/modules/<m>.md`：每个核心模块一个文件，含 FOR / NOT FOR / Components / Evolution 节。

1. 生成 roadmap：roadmap/README.md（三桶索引）+ roadmap/active-roadmap.md（≥1 item，每项含 Status / Capability / Components / ADR / Acceptance Criteria）+ roadmap/deferred/README.md（空 Items 索引 + Entry Criteria + Promotion Rule）+ roadmap/obsolete/README.md（空索引）。

1. 生成 `docs/ACTIVE_CONTEXT.md`：当前焦点 + 在跑/在等的 workstream 表 + standing constraints + recent decisions（最近 3–5 条）。按"约定原则"的快照契约生成，头部带契约声明（见下方 ACTIVE_CONTEXT 模板）。

1. 生成 `AGENTS.md`：以 references/PROJECT_AGENT.md（中文成品宪法）为准落地，按其章节：Source of Truth 优先级 / 三档工作模式 / 模块边界（FOR / NOT FOR）/ Capability vs Component / 状态词汇 / 文档治理（已含文档生命周期 anti-rot：ACTIVE_CONTEXT 快照契约 + 收口归档仪式）/ Code Traceability / 完成标准。工具偏好若全局 agent 配置未覆盖项目特定项（如子仓库 toolchain）再补。Redaction 边界写明一条：secret/凭证只进 ACCESS.local.md（gitignored）与外部 vault，永不进 committed tree / traces / 日志 / 对外消息——避免 AGENTS.md 里 "creds never in repo tree" 与本机存明文凭证的口径自相矛盾。

1. 生成 `CLAUDE.md`：单行 @AGENTS.md。

1. 生成 `ACCESS.local.md` stub 并写进 `.gitignore`：用下方「ACCESS.local.md 模板」建三段式骨架（接入凭证 / 环境拓扑 / 验证配方），字段留空待用户填实；同步在 .gitignore 加 ACCESS.local.md 一行（带注释说明含 creds、永不提交）。绝不把真实凭证写进 stub。

1. 配置 memory-discipline hook（默认项目级，直接建）：把 references/memory-discipline-hook.sh 接成

PostToolUse hook——写 memory/*.md(非 MEMORY.md) 时确定性注入"事实细节→ACCESS.local.md/docs、只留指针"提醒。 默认写项目级配置（.claude/settings.json 等，blast radius 小、随 bootstrap 直接建不必问）；只有要全局跨项目 才问用户写 ~/.claude/。为什么需要 hook：该纪律在 cto-orchestration §5（知识层），但 skill 文本随长对话 salience 衰减，高频纪律须 hook 强制层兜底。三 agent wiring 见下方模板；绝不把真实 secret 写进 hook。

1. 完成时报告：列出已建文件 + 用户下一步建议（填实 ADR-0001 内容 / 完成首个 module 的 FOR-NOT FOR / 把第一个 roadmap item 标 active / 在 ACCESS.local.md 填本机接入凭证与验证配方 / 若配了 hook 跑一次 memory 写入确认提醒生效）。

memory-discipline hook 模板（步骤 11）

步骤 11 的三 agent wiring。references/memory-discipline-hook.sh = CC + codex 共用（双 extractor），omp 另走 JS hook。字段/flag 已 2026-06 本地实跑验证（见各 ⚠️）。<S> = 本 skill 安装路径。

① Claude Code — 项目 .claude/settings.json（实测可用）：

"hooks": { "PostToolUse": [{ "matcher": "Write|Edit|MultiEdit",
  "hooks": [{ "type": "command", "command": "bash <S>/references/memory-discipline-hook.sh" }] }] }

② codex — 项目 .codex/hooks.json（嵌套 JSON、非 TOML，实测）：

{"hooks":{"PostToolUse":[{"matcher":"*","hooks":[{"type":"command","command":"bash <S>/references/memory-discipline-hook.sh"}]}]}}

⚠️ 实测：codex 写文件 tool_name=apply_patch(非 Write)、路径在 .tool_input.command patch 文本里——脚本已含该 extractor。起 codex 要带两个 flag：--dangerously-bypass-approvals-and-sandbox --dangerously-bypass-hook-trust （缺后者 project-local hook 不被信任、不加载）。坑：~/.codex/hooks.json 若有解析错误（如 unknown field）会让 整套 hook 加载失败（含项目级）——先跑一次确认生效。

③ omp — JS hook references/memory-discipline-hook.ts（实测可用），omp --hook <S>/references/memory-discipline-hook.ts 或放 .omp/hooks/：

export default (pi)=>{ pi.on("tool_result", async (e)=>{ /* toolName 小写 write/edit、路径 e.input.path、排除 MEMORY.md */
  await pi.sendUserMessage(REMINDER, { deliverAs:"followUp" }); }); }

⚠️ 实测：omp 无 command/stdin hook，走 tool_result 事件（toolName 小写 write/edit、路径 event.input.path）。注入必须用 `pi.sendUserMessage(text,{deliverAs:"followUp"})`——落 role:user 进 transcript、模型下一轮读到并遵守；pi.sendMessage 是 hidden/developer 通道、模型常忽略，别用。措辞要中性（普通提醒口吻），伪 SYSTEM/"你必须…"会被当 prompt-injection 拒绝。

状态词汇

两套词汇独立、不可互换：ADR 4 态（Nygard）/ Roadmap 6 态。完整定义见 references/PROJECT_AGENT.md §5（canonical——它随成品写进项目 AGENTS.md，必须自包含）。 生成 ADR / roadmap 时按那里取值，本 skill 不复述全文，只守一条易错点：别把 ADR 的 `accepted` 安到 roadmap 上、别把 roadmap 的 `active/completed` 安到 ADR 上。

ADR 模板

编号 4 位零填充（ADR-0001、ADR-0014），全仓一致；起步 ADR 主题为仓库边界。

# ADR-NNN: <Title>

Status: proposed

Date: YYYY-MM-DD

## Context
<the problem / forces>

## Decision
<what we decided>

## Consequences
<positive / negative / future evolution>

组件引入 ADR 变体（lifecycle）

引入重依赖 / 重组件（数据存储 / MQ / 缓存 / 搜索 / 新外部服务 / 新能力类别）的 ADR，在基础模板上增 `Owner` / `Sunset Criteria` / `Review-by` 三段——记录"何时该退役"，防止引入后无人清理、沦为死基础设施。这是 ADR 天然该承载的槽，bootstrap 直接建。

# ADR-NNN: 引入 <组件>
Status: accepted
Date: YYYY-MM-DD
Owner: <谁负责其存续与退役>

## Context
<问题 + 为何 stdlib / 现有依赖不够；评估过的替代方案>
## Decision
<引入什么；如何 wrap behind interface 保持可替换>
## Sunset Criteria（退役判据）
- <什么条件下应被移除：依赖它的 X 特性下线 / 长期 QPS < N / 被 Y 替代>
## Review-by
- YYYY-MM-DD（到期必须复审：仍需要？可降级/移除？）
## Consequences
<运维成本 / 锁定风险 / 退役难度>

更细的 lifecycle 规则（重组件阈值 / wrap-behind-interface / 情境绑定 hardcode 与 prompt 的 EXPIRES·REVISIT-WHEN 内联过期标记 / 配套 CI 门禁）见 agent-backend-standard 附录 A；本骨架不重复、只建 ADR 这个槽。

模块文档模板

# Module: <name>

## FOR
- <capability A>

## NOT FOR
- <explicitly out of scope>

## Components
- `<path/to/component>`

## Evolution

### Active
- <item> — Status: active

### Deferred / Obsolete
- <item> — Status: deferred — reason

Roadmap 条目模板

## <ID>: <Title>

Status: proposed

Capability: <capability>

Components:
- `<path>`

ADR: <ADR-NNN or TBD>

Acceptance Criteria:
- <criterion>

Deferred 延期条目模板

ID = <PREFIX>-DEFER-NNN（<PREFIX> 为项目自定义前缀，如 AAM / PAY）。一项一文件存 roadmap/deferred/<PREFIX>-DEFER-NNN-<slug>.md，并在 roadmap/deferred/README.md 索引。

# <PREFIX>-DEFER-NNN: <Title>

Status: deferred

Priority: P2

Capability: <capability>

Components:
- `<path>`

Related ADRs:
- <ADR-NNN>

## Problem
<why it matters; kept across sessions>

## Proposed Direction
<approach>

## Non-goals
- <out of scope>

## Acceptance Criteria
- <criterion>

## Validation Plan
- <how it is verified>

Deferred 索引模板（roadmap/deferred/README.md）

# Deferred Roadmap

Future work accepted for tracking but not in active scope. Index instead of a generic backlog.

## Items

| ID | Priority | Status | Title | Components |
| --- | --- | --- | --- | --- |
| <PREFIX>-DEFER-001 | P2 | deferred | [<Title>](./<PREFIX>-DEFER-001-<slug>.md) | <components> |

## Entry Criteria

- 问题真实、需跨会话保留
- 不应扩张当前 active plan
- 有明确 owner component + acceptance criteria
- 不是某文件内的局部 TODO

## Promotion Rule

延期项转 active 时，在架构 plans 目录建具体 plan，保留链接，状态改 `active`，完成后改 `completed`。

ACTIVE_CONTEXT.md 模板

# Active Context — <project>

Last rewritten: YYYY-MM-DD

> **This file is a SNAPSHOT, not a journal.** Rewritten (never appended) at every
> workstream close, capped at ~60 lines. History lives in git; closed-workstream
> detail is archived. This is the entry point for any agent/session without the
> orchestrator's private memory.

## Current Focus
<one workstream, its single blocker, its next step>

## Live / Waiting Workstreams
| Workstream | State | Waiting on |
| --- | --- | --- |

## Standing Constraints
- <rules that outlive any single workstream>

## Recent Decisions (last 3–5 — older: git history / ADRs)
- YYYY-MM-DD — <decision>

ACCESS.local.md 模板

gitignored，永不提交/推送。 含明文凭证，只在本机做快速反查。生成时字段留空待用户填， stub 里绝不写真实 secret。凭证 canonical home 是外部 vault，此文件是本机缓存。

# <项目> 接入与访问（仅本机 — 已 gitignore，永不提交/推送）

> 此文件含凭证/环境/访问信息，供本机快速反查。**任何内容都不得**粘进 committed 文件、
> 子仓库目录、traces、日志或对外消息。凭证 canonical home = 外部 vault；这里是本机缓存。

## ① 接入凭证
- **<环境名>**：`<登录 URL>` → 登录 → 选 `<租户/项目>`。
  - 账号：`<account>`；密码：`<password 或"见 vault">`。
  - token / cred 获取方式：`<如何拿到，例如 localStorage.token / vault 路径>`。

### 外部服务 / 模型 endpoint（每个被认证调用的依赖一条：LLM 网关 / DB / 第三方 API）
- **<服务名>**：endpoint `<base url / host>`；auth header `<如 api-key / Authorization / Ocp-Apim-Subscription-Key>`；
  模型/部署/库名 `<model / deployment / db>`。
- **凭证间接（必记）**：cred 实际存在 env 变量 `<X，如 VENDOR_APIM_KEY>`，但代码读的是 `<Y，如 LLM_API_KEY>`
  —— **桥接** = `<如启动时 Y="$X" 进程 env 覆盖 .env；或 vault→Y 注入>`。
- **参数 gotcha**：`<如 gpt-5.x 用 max_completion_tokens 非 max_tokens；某 API 必带 version>`。

## ② 环境拓扑速查
- 部署布局：`<monorepo / 多服务 / 前后端目录>`。
- 关键 id：`<tenant id / project id / 资源 id>`。
- env flags：`<影响行为的开关>`。
- 调用路径：`<请求怎么走到目标代码——关键分叉点 file:line>`。

## ③ 验证配方与 gotcha
- **E2E 验收 recipe**：`<最小可复现的"摸到运行系统并确认生效"步骤>`。
- **活体 auth smoke（依赖建在它之上前先验，别等彩排）**：`<最小 curl/调用，打印 HTTP 码>`。
  **读失败模式**：401/403 = 凭证/header 错；**400 参数错 = 凭证其实通了**（已过认证到参数校验）；
  404 = base_url/路径/model 错。区分清楚才知道改 key 还是改配置。
- **调试踩坑**：`<本机/工具/环境特有的坑 + 绕过办法>`。

## 构建 / 工具
- `<本机构建、测试、跑服务的实际命令>`。

INDEX.md 模板

# Documentation Index

This index maps the repository source of truth.

## Decisions

- [ADR-0001: <Title>](decisions/ADR-0001-<slug>.md)

## Modules

- [<module>](modules/<module>.md)

## Roadmap

- [Active Roadmap](roadmap/active-roadmap.md)
- [Deferred Roadmap](roadmap/deferred/README.md)

## AI Context

- [Active Context](ACTIVE_CONTEXT.md)

## Traceability
| Capability | Component | ADR | Roadmap |
| --- | --- | --- | --- |
| <capability> | `<path>` | ADR-0001 | <ID> |

Success criteria

完成后：

• docs/INDEX.md 单文件即可定位所有 source of truth
• 至少 1 个 ADR，记录仓库边界（Status 为 proposed 或 accepted）
• 至少 1 个 module 有 FOR / NOT FOR
• Active roadmap 至少 1 个 item
• AGENTS.md + CLAUDE.md 生效，agent 进入新对话能识别上述结构

After bootstrap

完成后告诉用户：

• 日常开发由 AGENTS.md 管理（Source of Truth 优先级 / 状态词汇 / 三档工作模式 / 等）
• 新决策走 ADR，新计划进 roadmap，过时计划标 obsolete / rejected 不删