martin1847/evolab / skills/repo-governance-bootstrap
repo-governance-bootstrap
Verified一次性初始化 AI 协作项目的轻量工程治理骨架。新仓库 / 文档治理初始化时调用(也是 cto-orchestration 接入新项目的第一步)。One-shot governance bootstrap for a new repo.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.9 KB |
| hooks.json | config | 592 B |
| references/PROJECT_AGENT.md | markdown | 7.9 KB |
| references/PR_SELF_CHECK.skeleton.md | markdown | 826 B |
| references/docs-check.shexecutable | script | 7.4 KB |
| references/engineering-gate.conf.example | other | 361 B |
| references/engineering-gate.shexecutable | script | 6.8 KB |
| references/hook-wiring.md | markdown | 2.4 KB |
| references/memory-discipline-hook.pyexecutable | script | 2.7 KB |
| references/memory-discipline-hook.ts | script | 1.5 KB |
| references/pre-commit.shexecutable | script | 1.4 KB |
| references/pre-push.template | other | 3.5 KB |
| references/templates.md | markdown | 14.4 KB |
references/templates.md
View on GitHub# 治理产物模板(bootstrap 步骤 4-10 用)
> 主干只留步骤与判据;所有生成物模板在此。目录:
> [ADR](#adr-模板) · [组件引入 ADR lifecycle 变体](#组件引入-adr-变体lifecycle) · [模块文档](#模块文档模板) ·
> [Roadmap 条目](#roadmap-条目模板) · [Deferred 条目](#deferred-延期条目模板) · [Deferred 索引](#deferred-索引模板roadmapdeferredreadmemd) ·
> [ACTIVE_CONTEXT](#active_contextmd-模板) · [ACCESS.local](#accesslocalmd-模板) · [INDEX](#indexmd-模板) ·
> [NORTH_STAR](#north_star-模板可选伞仓或有明确长期方向的仓) · [AGENTS.md minimal 变体](#agentsmd-minimal-变体维护型低活跃仓) ·
> [GOV INDEX](#gov-index-模板docsgovernanceindexmd演化项首条-gov-出现时才建) · [GOV 文档](#gov-文档模板docsgovernancegov-nnn-slugmd)
## ADR 模板
> 编号 4 位零填充(`ADR-0001`、`ADR-0014`),全仓一致;起步 ADR 主题为仓库边界。
```markdown
# 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 直接建。
```markdown
# 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 这个槽。
## 模块文档模板
```markdown
# 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 条目模板
```markdown
## <ID>: <Title>
Status: proposed
Capability: <capability>
Components:
- `<path>`
ADR: <ADR-NNN or TBD>
Acceptance Criteria:
- <criterion>
```
## Deferred 延期条目模板
ID = `<PREFIX>-DEFER-NNN`(`<PREFIX>` 为项目自定义前缀,如 `PAY` / `SHOP`)。一项一文件存 `roadmap/deferred/<PREFIX>-DEFER-NNN-<slug>.md`,并在 `roadmap/deferred/README.md` 索引。
```markdown
# <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`)
```markdown
# 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 模板
```markdown
# 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 模板(+ 值文件孪生 ACCESS.local.env)
> **两个文件都 gitignored,永不提交/推送。** 值/元数据物理分离(分离与注入判据见
> agent-backend-standard 附录 E):`.md` 只留元数据 + 秘密**名字** + gotcha(agent 可整读、
> 零遮蔽工序);**值**一律进纯 `KEY=VALUE` 的 `ACCESS.local.env`(`chmod 600`),用时
> `set -a; source ACCESS.local.env; set +a; <cmd>` 注入子进程 env,不落 stdout/argv。
> 命名刻意不入 `.env` 家族(防 dotenv 生态自动加载;同词干配对自明),
> gitignore 同时盖 `ACCESS.local.*` 与 `.env*` 兜底。生成时两文件字段留空待用户填,
> stub 里绝不写真实 secret。
```markdown
# <项目> 接入与访问(仅本机 — 已 gitignore,永不提交/推送)
> 本文件只放元数据/名字/gotcha;**值在同目录 ACCESS.local.env**(KEY=VALUE,chmod 600),
> 用 `set -a; source ACCESS.local.env; set +a; <cmd>` 注入。任何内容都不得粘进 committed
> 文件、traces、日志或对外消息。凭证 canonical home = 外部 vault;这里是本机缓存。
## ① 接入凭证
- **<环境名>**:`<登录 URL>` → 登录 → 选 `<租户/项目>`。
- 账号 env 键:`<ACCOUNT_KEY 名>`;密码 env 键:`<PASSWORD_KEY 名,值在 ACCESS.local.env 或 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 模板
> INDEX 是 traffic cop:只放链接与一行说明;任何更多的内容 = 放错了地方(内容归对应文档)。
```markdown
# Documentation Index
This index maps the repository source of truth. Links only — content lives in the linked docs.
## 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> |
```
---
## NORTH_STAR 模板(可选——伞仓或有明确长期方向的仓)
> 定长一到两页、原则 ≤7-8 条(Amazon tenets 尺寸纪律);每条带稳定 ID(`NS-1`…),评审
> brief、门禁与 ADR 按 ID 引用。宪法本身用 semver(spec-kit 约定:MAJOR=删改原则语义 /
> MINOR=新增原则或实质扩充 / PATCH=措辞澄清)。原则写法把 TOGAF 四字段
> (Name / Statement / Rationale / Implications)收敛成两行:Statement 一句 MUST/NEVER
> 判定句 + Rationale/裁决依据;Implications 落到「越线信号」节。生成语言从项目
> (项目文档用英文就生成英文,结构不变)。
```markdown
# 北极星 — <项目 / 生态名>
Status: accepted (maintainer, YYYY-MM-DD)
Version: 1.0.0 | Ratified: YYYY-MM-DD | Last amended: YYYY-MM-DD
> 本文件记录长期方向:什么必须发生 / 什么绝不发生。ADR 记录决策历史。
> 与 accepted ADR 冲突 = 两者必有一错:停下升级 maintainer,绝不静默择边。
## 终局(Destination)
<一段话:这个项目/生态长期要变成什么;护城河是什么(组合还是单点)。>
## 不可协商原则
- **NS-1 — <名称>.** <Statement:一句 MUST/NEVER 判定句。> <Rationale:为什么;
冲突时按什么裁。>(来源:README / ADR-xxxx / …)
- **NS-2 — …**(≤7-8 条;每条必须可被评审判定,禁模糊 "should")
## 工法(agent 时代工程纪律,可选节)
<canonical vs non-canonical 显式声明 / 就近 AGENTS.md / 防腐门必须 build-failing
且咬整类、baseline 只收不放 / 获批变更直接落地(逃生舱用 kill switch),owner 标明需灰度的生产变更才 flag 默认 OFF。>
## 越线信号(Tripwires)— 出现以下情况即偏航
- <每条对应一个 NS-ID 的具体反模式,写成评审可机械判定的形态>(NS-x)
## 生效路径(Enforcement)
本文件是软层(L1),只通过更硬的层生效:评审合同引用 NS-ID → 编辑时 hook →
build-failing 门(按语言:ArchUnit / cargo-deny / import-linter / NetArchTest /
dependency-cruiser)→ 周期 doc-vs-code 漂移审计。门清单归各仓 CI。
## 治理(Governance)
修订仅限 maintainer,须附书面理由;版本按上述 semver 递增并更新 Last amended;
原则语义变更后**同一变更内**同步下游消费者(评审模板 / 门禁规则 / 子仓 AGENTS.md
指针)。
```
---
## AGENTS.md minimal 变体(维护型/低活跃仓)
> 适用:maintained-only 仓(按需修、无 feature drive、无 ADR/roadmap 脚手架——即全量
> 宪法 `PROJECT_AGENT.md` 的启用条件不满足时)。目标 <60 行:agent 进来 30 秒知道
> 「这是什么、什么不许做、怎么构建」。伞仓覆盖检查
> (判据见 SKILL.md 伞仓三件套②)一行门:
> `missing=0; for d in */; do if [ -e "${d}.git" ] && [ ! -f "${d}AGENTS.md" ]; then echo "MISSING: $d"; missing=1; fi; done; exit "$missing"`。
> 生成语言从项目。节序按 blast radius 递减——最危险的纪律排第一节,agent 截断读取时
> 先看到的必须是最不能错的事。
```markdown
# <repo> — Agent 指南
<一句话定位。>(伞仓场景加:能力簇归属见伞仓 `docs/modules/<cluster>.md`。)
## 纪律(blast radius 最大的事排最前)
- Commit 留本地,owner 明确批准才 push;不加 AI 签名行。
- Secret、内部 hostname/IP、拓扑只进外部 vault 与 gitignored `ACCESS.local.md`;绝不进 committed tree / traces / 日志 / 对外消息。
- 行为变更须获批;获批的变更直接落地,要逃生舱就加 kill switch(默认开、`=0` 可杀),不做默认 OFF→ON 两步翻转;只有 owner 标明需灰度的生产变更才走 rollout 旗标默认 OFF(定义处写毕业条件);不顺手 refactor、不动格式。
- 存疑或需超 scope:STOP and report,不自行扩权。
## 边界(Scope)
- FOR: <2-3 条>
- NOT FOR: <1-2 条>
- 维护型仓:只在具体压力(真实 bug / 真实消费者需求)下动,不做推测性 feature
parity。
## 生态规则(伞仓场景才有本节)
- Wire 兼容性源头在 <参照仓>;本仓跟随 wire、绝不 fork 协议、绝不先行改 wire。
- 长期方向:伞仓 `docs/NORTH_STAR.md`(相关处按 NS-ID 引用)。
## 构建与测试
<从仓内文件推导的真实命令;未实跑过的标 `(not verified)`——禁止编造命令。>
```
## GOV INDEX 模板(`docs/governance/INDEX.md`,演化项——首条 GOV 出现时才建)
```markdown
# Governance INDEX — 域登记表
> 路由判据(更新契约,不按主题):会原地演进的现行可执行规则 → GOV;只被 supersede 的
> 定格裁决与理由 → ADR;冻结证据快照 → audit;在飞协调物 → orchestration。
> 维护协议:新域先查本表——已有域**增订原篇**(日期戳节),无域才立新号;
> 根 docs/INDEX.md 只挂一行链接到本文件。
| 号 | 域 | 一句话范围 | 文件 |
|---|---|---|---|
| GOV-001 | <域名> | <该域现行规则管什么> | GOV-001-<slug>.md |
```
## GOV 文档模板(`docs/governance/GOV-NNN-<slug>.md`)
文档寿命域可选:结论与原始证据分开存放,由项目明确保留期与 `keep-until`;缓存、依赖、临时目录放在 docs 之外。
寿命扫描只产出待处置候选,不授予自动搬迁或删除权;处置后用既有 docs-check 核指针,不假定 archive 目标可自动愈合。
可选伴随 `cto-orchestration` 提供 Markdown 回执与 living 段的只读候选清单;本 skill 不附带该扫描器,它也不是原始证据或缓存回收器。采用时沿用工具既有退出判据,不另建一套寿命门。
```markdown
# GOV-NNN — <域名>现行规则
> 更新契约:随实证增订原篇(新增日期戳节,不另立新文件);被推翻的条目原地改写并注明
> supersede 来源(ADR/复盘);本文件是该域可执行规则的唯一现行版。
## 现行规则
- <规则 1:判据 + 动作>
## 增订记录
### <YYYY-MM-DD>(<一句话触发事件/实证>)
- <当日新增或改写的条目摘要>
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |