地址
- 作者仓库星标 2
- 作者仓库 anton
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @wcygan · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# ADR
Anton-local skill for the architectural decision record lifecycle. Owns three workflows: **new**, **list**, **supersede**. ADRs live at `context/adrs/NNNN-kebab-slug.md` and are immutable — once accepted, the body never changes. Supersession is the only way to revise a decision.
## Why this skill exists
Anton needs **one durable home** for architectural decisions so that:
- `cluster-intake-gatekeeper` has somewhere to hand off its ADD/DEFER/REJECT verdicts (instead of stopping at "ADR-ready").
- Future Codex sessions can discover prior decisions automatically via the SessionStart hook (`.Codex/hooks/inject_adr_index.py`) without the operator typing them in.
- `cluster-intake` Step 2 can query past `Reverted` decisions by category instead of grepping a single shared file.
- The operator (and future-Will) can recover *why* the cluster looks the way it does without mining `git log`.
The skill is anton-local and has **no runtime dependency** on `~/.Codex/skills/context-repo-adr` — the format is intentionally compatible with the global context-repo conventions, but invoking this skill never delegates to that one.
## Hard rules
- **ADRs are immutable.** Once an ADR's `status:` is `Accepted` (or `Reverted` / `Rejected` / `Deferred`), the body never changes. The *only* edit allowed on an existing ADR is flipping the `status:` line to `Superseded-by NNNN`. Any other change must go through `supersede`.
- **Numbers are never reused.** The next number is always `max(existing) + 1`, zero-padded to four digits, regardless of whether earlier numbers were superseded.
- **`Status: Reverted`** is anton-specific. Use it for any decision that was once live and is now removed. Standard MADR has no equivalent.
References:
- Field reference and immutability rule → [conventions](references/conventions.md)
- Canonical template for new ADRs → [template](references/template.md)
## Workflow — `new`
Triggered by:
- The user says "create an ADR" / "record this decision" / `/adr new "<title>"`
- `cluster-intake-gatekeeper` hands off an ADD / DEFER / REJECT verdict (the verdict object substitutes for the interactive interview — see "Handoff from intake" below)
### Steps
1. **Allocate the next number.** `Glob('context/adrs/0[0-9][0-9][0-9]-*.md')`. Sort. The next number is `max + 1`, zero-padded to 4 digits. Never reuse a number.
2. **Generate the slug.** Lowercase the title, kebab-case it, drop articles and prepositions, take the first 4–6 meaningful words. Example: "Adopt Cilium over Calico for CNI" → `adopt-cilium-over-calico-for-cni` → file `0018-adopt-cilium-over-calico-for-cni.md`.
3. **Interview the user** (skip this when invoked from intake — see Handoff from intake). Ask only the questions whose answers aren't already known:
- Title (one short sentence)
- One-sentence summary (the blockquote after the H1)
- `status` — usually `Accepted` for forward-looking decisions; `Deferred` / `Rejected` / `Reverted` if known
- `affects` — pick the broadest applicable category from: `storage`, `observability`, `databases`, `registries`, `demos`, `networking`, `security`, `compute`, `all`, or a new category if none fit
- `intent` — `concrete-need` / `learning` / `unknown`
- `supersedes` — list of NNNNs being superseded by this one (usually empty)
- **Context** (1–3 paragraphs — what situation prompts this decision, what forces are in play)
- **Decision** (active voice, one or two sentences — "We will adopt X" / "We will not")
- **Alternatives considered** (do-nothing + 1–2 alternatives, with a one-line "why rejected" each)
- **Consequences** — accepted costs, lessons (if `Reverted`), follow-ups
4. **Write the ADR file** at `context/adrs/NNNN-slug.md` using the shape from [template](references/template.md). Frontmatter is mandatory; missing frontmatter fields default to the template's defaults.
5. **If `supersedes:` is non-empty**, also flip the `status:` line of each superseded ADR to `Superseded-by NNNN`. This is the *only* allowed in-place edit on an existing ADR. Use `Edit` with a precise old/new string for the status line only — never touch the body.
6. **Confirm to the user** with the file path and the new ADR number.
### Handoff from intake
When `cluster-intake-gatekeeper` invokes this skill at the end of its evaluation, it passes the verdict object directly. Map the verdict to ADR fields without re-interviewing:
| Gatekeeper verdict | ADR `status:` | Notes |
|---|---|---|
| Add (concrete need) | `Accepted` | `intent: concrete-need`. Decision section names the hand-off skill (`add-flux-app` / `flux-app-author`). Consequences section includes the Renovate-PR tax line. |
| Add (learning) | `Accepted` | `intent: learning`. Consequences section *must* include the timebox, exit plan, and review date — these are load-bearing under the contained-learning rubric. The frontmatter should add a `review-by:` field with the review date. |
| Defer | `Deferred` | Body holds the exact measurable unblock conditions (what would have to be true to convert to Accepted). |
| Reject | `Rejected` | Body holds the failed gate (1–7) or known-bad pattern, and — if appropriate — whether reframing as a learning intake would change the answer. |
After writing the ADR, return to the gatekeeper with the ADR number so it can include it in its memory append.
## Workflow — `list`
Triggered by:
- `/adr list` or `/adr list --status Reverted` or `/adr list --affects databases`
- `cluster-intake` Step 2 (the removal-detection lookup) — internally invokes this with `--status Reverted --affects <candidate-category>` to find prior reverts
### Steps
1. `Glob('context/adrs/0[0-9][0-9][0-9]-*.md')`.
2. For each file, read the frontmatter and extract `status`, `date`, `affects`, `intent`, and the H1 title.
3. Apply filters:
- `--status <X>` → keep only ADRs whose `status:` matches `X` (case-insensitive)
- `--affects <X>` → keep only ADRs whose `affects:` contains `X`
- With no filter, return all
4. Format as a markdown table sorted by NNNN (columns: #, Title, Status, Date, Affects, Intent).
5. If used as the data source for `cluster-intake` Step 2: also read the matching ADRs' "Re-adoption guidance" section so the intake can surface the conditions under which a re-attempt would be valid.
## Workflow — `supersede`
Triggered by:
- `/adr supersede <NNNN> "<reason>"` — the user wants to revise an existing decision
### Steps
1. **Verify the target exists.** `Read` `context/adrs/NNNN-*.md`. If missing, abort with a clear error.
2. **Verify the target's current status.** If it is already `Superseded-by NNNN`, abort — supersession chains exist (NNNN can be superseded by MMMM which is superseded by PPPP), so the user must supersede the *latest* in the chain.
3. **Author the replacement** by invoking the `new` workflow with `supersedes: [<NNNN>]` pre-populated. Walk the interview as normal.
4. **Flip the old ADR's status line** — and *only* the status line — from `Accepted` (or whatever it was) to `Superseded-by <new NNNN>`. Use `Edit` with the precise old/new strings. Do not touch the body, the date, or any other field.
5. **Confirm to the user** with both ADR numbers (old → new) and the file paths.
## What this skill does NOT do
- Does not write Flux manifests — that is `add-flux-app`.
- Does not run cluster intake — that is `cluster-intake` (which hands off here).
- Does not edit ADR bodies after the fact. Ever. Use `supersede`.
- Does not auto-detect when a decision should be superseded. Manual via `/adr supersede`.
- Does not push, commit, or tag — the user owns git operations.
- Does not delete ADRs. ADRs are append-only forever, even superseded ones.
## Related skills and agents
- `cluster-intake` / `cluster-intake-gatekeeper` — the dominant authoring path. Hand off here on every verdict.
- `add-flux-app` / `flux-app-author` — invoked *after* an `Accepted` ADR that involves new manifests.
- `~/.Codex/skills/context-repo-adr` (user-level) — format-compatible but not invoked at runtime. If the user adopts the full context-repo convention later, the existing ADRs will Just Work.
## Anti-patterns
- **Editing an ADR body to reflect a changed decision.** That's what `supersede` is for. Editing in place destroys the historical record.
- **Re-using a number after a delete.** ADRs are never deleted, so this shouldn't come up — but if it does, allocate the next number, never the gap.
- **Authoring an ADR before the decision is actually made.** ADRs document decisions that happened, not aspirations. If the user is still considering, they're not ready for an ADR.
- **Verbose ADRs.** One screen of body is the target. If the decision genuinely needs more context, link to a doc — don't inline it.
章节与文件索引
按说明文件中的顺序排列。
为什么存在这个技能
硬性规定
工作流程——新
步骤
从入口处移交
文件/命令 -> context/adrs/NNNN-kebab-slug.md · cluster-intake-gatekeeper · .Codex/hooks/inject_adr_index.py · cluster-intake · Reverted · git log · ~/.Codex/skills/context-repo-adr · status:
内容校验值 -> 9f92441e50f2
当前原文的自动摘译,尚未人工审校。
为什么存在这个技能
安东需要一栋耐用的住宅来进行建筑决策,以便:
cluster-intake-gatekeeper有地方可以交出其添加/推迟/拒绝判决(而不是停留在“ADR 就绪”)。未来的 Codex 会话可以通过 SessionStart 挂钩自动发现先前的决策(.Codex/hooks/inject_adr_index.py),无需操作员输入。cluster-intake第2步可以查询过去Reverted按类别做出决定,而不是 grep 单个共享文件。硬性规定
ADR 是一成不变的。一旦 ADR
status:是Accepted(或Reverted/Rejected/Deferred),身体永远不会改变。对现有 ADR 唯一允许的编辑是翻转status:线路到Superseded-by NNNN。任何其他变更都必须经过supersede。数字永远不会重复使用。下一个数字总是max(existing) + 1,用零填充为四位数字,无论之前的数字是否被取代。工作流程——新
触发方式:用户说“创建 ADR”/“记录此决定”/
/adr new "<title>"cluster-intake-gatekeeper移交添加/推迟/拒绝裁决(裁决对象替代交互式访谈 - 请参阅下面的“从入学移交”)步骤
分配下一个数字。
Glob('context/adrs/0[0-9][0-9][0-9]-*.md')。种类。下一个数字是max + 1,补零至 4 位数字。切勿重复使用号码。生成段头。小写标题,采用横写,去掉冠词和介词,取前 4-6 个有意义的单词。示例:“针对 CNI 采用 Cilium 而不是 Calico”→adopt-cilium-over-calico-for-cni→ 文件0018-adopt-cilium-over-calico-for-cni.md。从入口处移交
当
cluster-intake-gatekeeper在评估结束时调用该技能,它直接传递判决对象。将判决映射到 ADR 字段,无需重新访谈:Gatekeeper 判决·ADRstatus:· 备注添加(具体需要)·Accepted·intent: concrete-need。决策部分命名了交接技能(add-flux-app/flux-app-author)。后果部分包括 Renovate-PR 税项。