drydock

Drydock

为船厂铺设龙骨：一个仓库、一套共享脚手架，让每位贡献者都能继承它。此技能只播下两个种子（CLAUDE.md 和 GLOSSARY.md），为可识别的旧版术语表 CONTEXT.md 文件提供一次性迁移，并定义首次使用时其他所有表面何时出现。它接通填充这些表面的流程（launch 会写入 GLOSSARY.md 词汇和决策记录；launch C5 会沉淀内容并审查沉淀标准），并报告播下了什么、哪些内容延后以及原因，以及哪些内容是有意跳过的。

四大支柱及其实际存放位置：

支柱	表面
上下文（共享背景）	GLOSSARY.md（术语表）+ docs/business/ + docs/adr/ + OMC wiki
规则（边界）	CLAUDE.md（精简入口：约定、原则、索引）+ docs/standards/
工具（可组合能力）	.omc/skills/ + .mcp.json + scripts/
标准（船级社）	design-system/（令牌、组件、模式）+ docs/standards/

隐喻对照：船厂是共享设施；船级社（docs/standards/ + design-system/）制定船舶适航必须通过的规则；drydock 铺设龙骨；launch 负责启航。

适用场景

• 启动一个人类和 Agent 都会共同参与建设的仓库
• 知识存在于人们的脑海和聊天记录中，而不是文件里的仓库
• 入职引导：新队友或 Agent 应通过阅读而非询问来继承上下文

不适用场景

• 没有协作者的一次性原型
• 已经运行此脚手架的仓库（改用 --check）

工作流

1. 检测（绝不覆盖）

写入任何内容前，先盘点现有内容：

• 是否存在 CLAUDE.md？是否存在 AGENTS.md？（规则：若任一文件存在，就在原处扩展；为缺失的文件创建一个指向另一个文件的单行指针；绝不全新创建两个文件）
• GLOSSARY.md（或可识别的旧版术语表 CONTEXT.md）、docs/adr/、docs/standards/、docs/business/、design-system/、.omc/skills/、.mcp.json、scripts/、.gitattributes——哪些已存在（已采用——会审计其完整性），哪些不存在（未采用——各自会在下文获得首次使用触发条件，绝不推测性创建）？
• 是否安装了 OMC？——仅当在 OMC 会话中运行时才值得检查；在会话外静默跳过此检查（无论是否使用 OMC，此脚手架都能工作）

先报告盘点结果，再采取行动。

2. 确定文档语言，然后只询问检测无法回答的问题

生成的脚手架文件所用的文档语言，是基于文件的决策，而非对话状态。严格遵循以下约定：

{
  "schemaVersion": 1,
  "authority": { "path": "GLOSSARY.md", "frontmatterKey": "documentLanguage" },
  "canonicalSources": ["CLAUDE.md", "README.md"],
  "askOn": ["missing", "mixed", "conflict", "low-confidence", "invalid-explicit", "script-ambiguous"],
  "tagPattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$",
  "scriptVariants": ["zh-Hans", "zh-Hant"],
  "seedCompanionPrefixes": { "en": "en", "zh-Hans": "zh-Hans", "zh-Hant": "zh-Hant" },
  "stableTokens": [
    "GLOSSARY.md", "documentLanguage", "/oh-my-claudecode:launch", "--serial",
    "plan", "execute", "review", "verify", "blockedBy", "blocked_by",
    "pending", "in_progress", "completed", "failed", "ready-for-agent",
    "id", "name", "description", "triggers", "mcpServers", "```",
    "<Project>", "<term>", "<feature-slug>"
  ]
}

旧版术语表迁移（仅限完整运行；--check 绝不重命名或重写任何内容，只会就地审计旧文件）：只有当 CONTEXT.md 的 YAML 前置元数据包含 documentLanguage 键，或其第一行可见的非空行（前置元数据之后，忽略 BOM 和 HTML 注释）是 drydock 术语表种子标题（Glossary、术语表、詞彙表——这些种子早于语言标签），该文件才是旧版术语表；其他任何 CONTEXT.md 都是无关的 Agent 上下文文档，应保持不变。如果仓库中有旧版术语表 CONTEXT.md，但没有 GLOSSARY.md，则在确定语言或搭建任何内容之前，将其重命名为 GLOSSARY.md（若受 Git 跟踪则使用 git mv），逐字节保留其内容和前置元数据。绝不在旧版术语表 CONTEXT.md 旁边新建 GLOSSARY.md；一个船厂只有一个术语表权威来源。无关的 CONTEXT.md 不会阻止创建 GLOSSARY.md，也绝不会被报告为需要移除。如果 GLOSSARY.md 和旧版术语表 CONTEXT.md 同时存在，则以 GLOSSARY.md 为准，并报告遗留的 CONTEXT.md，由人工决定合并或移除。 迁移期间重写 CLAUDE.md：每当 GLOSSARY.md 是术语表权威文件时（上述重命名后，以及 GLOSSARY.md 和旧版术语表 CONTEXT.md 同时存在时），将旧版 CLAUDE.md 中的引用（例如 Glossary: CONTEXT.md 或 On term conflicts CONTEXT.md wins）改为 GLOSSARY.md，确保已安装的说明永远不会指向已重命名或即将删除的文件。此重写属于迁移，而非脚手架步骤。

解析顺序：

1. 当前调用中有效的明确人工选择优先。将其规范化为稳定的 BCP-47 风格标签：语言小写、文字形式首字母大写、地区大写。无效的明确输入必须询问一次，不能猜测。
2. 否则，读取 GLOSSARY.md 顶部 YAML frontmatter 中的 documentLanguage。对于全新的 Drydock 和 Launch 调用，有效且文字形式明确的标签具有权威性。如果持久化标签是裸标签或仅指定地区的中文标签，则在此权威层级询问一次；绝不能用源文本推断绕过它。
3. 如果标记缺失或无效，则按以下顺序检查规范源：CLAUDE.md，然后是 README.md。只有当每个可用源都有一种明确占主导地位的语言，且所有可用源都指向同一个规范化标签时，才进行推断。如果另一个源缺失或为空，一个明确无歧义的源就足够。
4. 中文必须解析为明确指定文字形式的标签：zh-Hans 或 zh-Hant（可选后接地区）。裸标签 zh 和仅指定地区的中文标签无法确定文字形式，必须询问一次，而不能选择对应变体。选择对应变体时使用最长语言/文字形式前缀：zh-Hans-* 选择 zh-Hans 对应变体，zh-Hant-* 选择 zh-Hant 对应变体；在 GLOSSARY.md 中保留完整规范化标签（例如 zh-Hans-CN）。
5. 缺少可用源、内容语言混杂、标签冲突、推断置信度低、明确输入无效，或中文文字形式不明确时，必须一次性提出语言问题。不要猜测。如果没有可用答案，则在写入本地化产物前停止。
6. 在生成脚手架之前，将解析出的标签写入 GLOSSARY.md 中精确且稳定的 frontmatter 键 documentLanguage（创建或扩展 frontmatter，但不要翻译该键）。此可见文件是 init 报告的语言权威；不得创建守护进程、隐藏账本或运行时状态。

只有正文和面向用户的标签/可本地化值遵循所选语言；结构性键保持语言稳定。路径、斜杠命令、标志、代码围栏、占位符、frontmatter 键和机器语义值、YAML/JSON 键、生命周期令牌、状态枚举、ID、blockedBy、公共 Team 的 blocked_by，以及解析器/控制令牌必须逐字节保持不变。

只有在语言确定后，才询问其余问题：

• 软件包/技术栈（用于标准和设计系统种子）
• 此代码库是否有 UI？（仅供参考——design-system/ 遵循与其他内容相同的延迟创建规则：只有在首个 UI 令牌或组件契约值得复用时才创建，绝不创建空壳）
• 问题跟踪器位置（GitHub——V1 仅支持 GitHub，不提供本地备用方案）——同时记录维护者在受理方面的沟通权限（问题评论、标签变更）——供 navigator 的 map home 和 harbor 的 intake queue 使用

3. 搭建脚手架（播种两张面孔——种子内容以文档语言呈现）

Drydock 在第一天恰好写入两张面孔：

CLAUDE.md                      # thin entry — see seed A
GLOSSARY.md                    # glossary and language authority — see seed B

其他所有界面都延后创建：首次使用时才出现，绝不凭空预建。 界面用于承载内容；只有在实际发生相应事项时才首次创建，并填入下方对应的示例。没有首次使用依据的文件，只是伪装成代码库界面的会话内容：

表面	出现时机
docs/adr/	第一个承载重要决策的事项确定时——此时编写 ADR-0001（采用此框架是自然的第一项记录）
docs/standards/	第一条可检查的规则沉淀下来时——例如启动时的 C5 沉淀流程，或重复出现的审查修正（种子 C / C2）
docs/business/	第一条必须在对话结束后保留的业务规则或背景文章出现时（种子 D）
design-system/	第一个值得复用的 UI 令牌或组件契约出现时——仅限 UI 仓库（种子 E）
.omc/skills/	第一个可复用能力通过 skillify 门槛时（种子 F）
scripts/	第一次需要重复使用某项自动化时
.mcp.json	第一次实际接入工具集成时（种子：{"mcpServers": {}}——仅在确实需要工具集成时添加服务，不要预先猜测）
.gitattributes	仓库第一次遇到行尾符变动问题时（种子：* text=auto eol=lf——消除 Windows 上的 CRLF 警告噪声）
场地审核脚本（scripts/shipyard-audit.mjs）	首次运行治理循环时——启动场地门禁或 --check 漂移审核需要机械执行部分；届时添加种子

种子范例是参考配套内容，绝不合并成一个负载。解析 documentLanguage 后，准确选择一个配套版本；不要输出其他配套版本中的重复标题或标签。使用最长匹配的语言／脚本前缀：en-* 使用英语，zh-Hans-* 使用简体中文，zh-Hant-* 使用繁体中文，而种子 B 会将完整解析后的标签写入 documentLanguage。对于其他有效标签，将英语规范配套内容翻译一次，同时保留上述所有稳定令牌。种子 A 和 B 现在编写；种子 C–F 等待其表面首次使用时触发，并在触发时以文档语言呈现。

生成种子文案前，调用 Skill 工具并使用 agent-doc-discipline，遵循其规则；只有在每条规则均可检查且说明缘由、每个表面无需聊天记录即可自明、并且明确列出来源而非默认来源时，种子文案才算就绪。队友或 Agent 应仅通过阅读就能根据种子内容采取行动。

种子 A — CLAUDE.md，en（精简入口；如果文件已存在，则在原处扩展）：

# <Project> — Agent & Human Shipyard

## Project conventions
- <language/framework/package manager/naming — list what matters, skip the rest>

## Architecture principles
- <the 3-5 principles most often violated in this project>

## Shared background
- Glossary: GLOSSARY.md

## Agent guide
- Delivery follows the canonical workflow plan → execute → review → verify; `/oh-my-claudecode:launch` is an optional governed delivery pipeline (opt-in, invoke explicitly)
- On term conflicts GLOSSARY.md wins; new terms are recorded the moment they settle
- When a deferred surface first appears (standards, decision records, business knowledge, project skills, the design system), it gets an index section here at the moment it is created — never before

种子 A — zh-Hans 配套版本（结构一致，根据文档语言二选一呈现）：

# <Project> — Agent & Human Shipyard

## 项目约定
- <language/framework/package manager/naming — list what matters, skip the rest>

## 架构原则
- <the 3-5 principles most often violated in this project>

## 共享背景
- 术语: GLOSSARY.md

## Agent 指南
- 交付遵循 canonical 工作流 plan → execute → review → verify；`/oh-my-claudecode:launch` 是可选的受治理交付管道（opt-in，需要时显式调用）
- 术语冲突以 GLOSSARY.md 为准；新术语当场补录
- 延后面首次出现时（规范、决策记录、业务知识、项目技能、设计系统），在创建的当下于此补一段索引——绝不提前

种子 A — zh-Hant 配套版本（結構一致，只呈現此版本）：

# <Project> — Agent & Human Shipyard

## 專案約定
- <language/framework/package manager/naming — list what matters, skip the rest>

## 架構原則
- <the 3-5 principles most often violated in this project>

## 共享背景
- 詞彙: GLOSSARY.md

## Agent 指南
- 交付遵循 canonical 工作流 plan → execute → review → verify；`/oh-my-claudecode:launch` 是可選的治理交付管道（opt-in，必須明確呼叫）
- 術語衝突以 GLOSSARY.md 為準；新術語確定時立即補錄
- 延後面首次出現時（規範、決策記錄、業務知識、專案技能、設計系統），在建立時於此補一段索引——絕不提前

种子 B — GLOSSARY.md（稳定的 frontmatter 键是语言权威）：

en：

---
documentLanguage: en
---

# Glossary

One entry per term: definition, boundaries, one resolved ambiguity. Agents write here the moment a term is settled. Vocabulary here is law for all specs, tickets, and code naming. Ship-specific terms only: a concept any sea chart carries does not get an entry.

## <term>
- Definition:
- Boundary: (is X, not Y)
- Avoid: (near-synonyms this ship does not use)
- Resolved ambiguity:

zh-Hans：

---
documentLanguage: zh-Hans
---

# 术语表

一条术语一个条目：定义、边界、一个已解决的歧义。术语敲定的当下写入。词汇对所有 spec、ticket、代码命名具有法律效力。只收本船特有的词；海图上都有的通用词不立条目。

## <term>
- 定义:
- 边界: （是 X，不是 Y）
- 禁用: （本船不用的近义词）
- 已解决的歧义:

zh-Hant：

---
documentLanguage: zh-Hant
---

# 詞彙表

每個術語一個條目：定義、邊界、一個已解決的歧義。術語確定時立即寫入。這裡的詞彙是所有 spec、ticket 與程式碼命名的準則。只收本船特有的詞；海圖上都有的通用詞不立條目。

## <term>
- 定義:
- 邊界: （是 X，不是 Y）
- 禁用: （本船不用的近義詞）
- 已解決的歧義:

种子 C — docs/standards/architecture.md（data.md 结构相同；process.md 还会添加 Testing 分卷——参见种子 C2；文案以文档语言呈现）：

# Architecture Standards

Rule-shaped, checkable writing; every rule carries a "why". Empty sections are legal — sediment is gradual.

## Module boundaries
## Error handling
## Dependency direction
## Seams and depth

- A seam is a real boundary two modules already cross in both directions. One adapter is a hypothetical seam; two adapters make it real. (Checkable: count the callers. Why: speculative abstraction is a tax paid before the need exists.)
- A deep module puts much behavior behind a small interface; deepen before widening. (Why: the interface is the permanent tax.)
- Logic lives behind the seam that owns its data; stable dependencies point inward. (Why: logic that reaches across a boundary it does not own couples every caller to the wrong neighbor.)

种子 C2 — docs/standards/process.md，Testing 分卷（在仓库测试代码时呈现；文案以文档语言呈现）：

## Testing

- Tests enter through the interface only: assert observable behavior at the seam. Reaching past the seam — querying the store directly, reading internal state — is false confidence. (Why: a test that survives refactors describes behavior, not plumbing.)
- Expected values come from an independent source of truth: a known-good literal or a worked example from the spec. (Why: a test that recomputes its expectation the way the code does can never disagree with the code.)
- One slice at a time: one failing test, one minimal implementation, repeat. Bulk-writing all tests first tests the imagination, not the behavior. (Why: the loop is a feedback engine; batching cuts the feedback.)
- Refactoring happens at the review axis, not inside the red-green loop. (Why: the loop answers "is the behavior right"; mixing redesign in hides regressions.)
- Tests open only at seams the reviewing captain approved. (Why: unapproved seams spend effort where the risk is not.)

种子 D — docs/business/README.md：

# Business Knowledge

Decision background and business rules. Format suggestion: one article answers one business question, opening paragraph states why it matters.
A new teammate (human or agent) reading this directory should be able to answer "why does this product direction exist".

种子 E — design-system/README.md：

# Design System

## tokens/    Design tokens (colors/type/spacing, machine-readable JSON preferred)
## components/ Component contracts (purpose, variants, misuse)
## patterns/  Interaction patterns (forms, feedback, loading, empty states — sediment reused patterns)

种子 F — .omc/skills/README.md：

# Project Skills

Reusable capabilities sedimented by this project: specialized tools, prompt templates, specialized practices.
One skill per file `.omc/skills/<name>.md`, frontmatter must contain a stable ASCII `id` plus name + description +
**non-empty triggers** (loader validation hard requirement: missing or empty means the skill is never loaded):

```markdown
---
id: project-release-check
name: project-release-check
description: Apply this repository's release readiness rules
triggers:
  - "project release check"
---

# Project Release Check

Follow the repository-specific release checklist and report evidence.
```
The literal YAML keys `id`, `name`, `description`, and `triggers` never localize. `id` and other machine-semantic values stay ASCII and stable; the scalar display values for `name`, `description`, and `triggers`, plus Markdown headings and prose, may localize. A non-Latin display name remains loadable because the explicit ASCII `id` is stable.
Bar for admission matches skillify: if it can be Googled in 5 minutes it is not a skill;
write "this project's specific decision discipline", not generic tutorials.

破坏性操作防护预设。 按需启用时，drydock 会植入一个钩子预设，将破坏性 git 操作——push、force-push、hard reset、clean 和删除分支——设为必须明确批准后才能执行。它以普通、可检查的仓库配置形式安装（仓库可以读取和审核的钩子条目，与仓库其他钩子位于同一处，例如 Agent 框架的 settings hooks 或 git pre-push 钩子），绝不会成为隐藏的强制执行层：报告中会列出规则，移除该条目则是明确的人工操作。此预设保护的是已搭建的框架，而不是 Agent——不会有任何 Agent 会话意外终结仓库历史。种子结构：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "<confirm-before-destructive-git>",
        "description": "Block push, force-push, reset --hard, clean, and branch -D behind explicit approval"
      }
    ]
  }
}

匹配器和命令由仓库自行选择钩子机制——drydock 负责植入结构和规则列表，确认命令则放在 Tools 支柱（scripts/）中，供仓库读取和审核。 提交时质量门预设。 按需，drydock 还会植入一个提交时钩子预设，在提交生效前运行仓库自身的检查——lint、类型检查和测试套件，并分别接入仓库已有的入口（Tools 支柱的 scripts/、包管理器的标准命令）。形式与护栏预设相同：普通、可检查的仓库配置，会列入报告，只有明确的人为操作才能移除。质量门是接入提交边界的仓库现有检查——drydock 不会自行添加任何检查器；如果仓库没有成熟的检查命令，则会创建脚手架，并将命令留待人来指定。

4. 接通治理循环（这正是它成为造船厂而非文件夹的关键）

告知用户，并依靠以下流程填充各个面向（每个流程也包含其所填充表面的首次使用触发条件）：

• launch 会随着术语逐渐确定，将词汇写入 GLOSSARY.md；在第一个承载重要决策落地时创建 docs/adr/；在第一篇必须在对话结束后留存的业务文章出现时创建 docs/business/（留痕）
• launch C5 sediment / code-review 会将反复出现的修正沉淀到 docs/standards/（在第一条规则沉淀时创建）和 CLAUDE.md 原则中
• 任何人都可以向 .omc/skills/ 添加项目技能（在添加第一个技能时创建）——门槛在于 skillify 质量门，而非权限
• wiki（OMC）会累积会话知识；任何被引用两次的内容都应提升到 docs/business/（在提升第一篇文章时创建）

让「先动手」保持一致的规则：启动无需许可；落地必须进入造船厂的一个舱位。 无法说明某项变更会落入哪个舱位（或明确不落入任何舱位），就是一个危险信号。

5. 报告

• 已植入（两个面向）/ 已扩展 / 已推迟（各自附首次使用触发条件）/ 有意跳过（各自说明原因）
• 将解析出的文档语言写入 GLOSSARY.md frontmatter documentLanguage: <tag>，并注明它来自明确选择、持久化标记，还是一致推断
• 说明两个已植入面向接下来需要的人类内容（通常是 CLAUDE.md 约定和 GLOSSARY.md 首批术语）
• 提醒：随时使用 --check 重新运行，以查看文件系统与 harness 之间的偏差

--check 模式

将实际仓库状态与 shipyard map 进行差异比对；要求具备 day-one 门面 CLAUDE.md 和 GLOSSARY.md（在迁移之前，可接受可识别的旧版术语表 CONTEXT.md），然后仅报告已采用的可选表面上的完整性问题（缺少可选表面不代表已采用，因此不属于缺失），以及缺少或无效的术语表 documentLanguage 标签、指向失效路径的 CLAUDE.md 部分、代码中未使用的 GLOSSARY.md 术语，以及从未被引用的标准。对每项发现，注明置信度（可通过机械方式检查时为 high，启发式判断时为 low），以及在排除用户明确声明的临时／草稿仓库后，该项是否可采取行动。Launch 的 yard gate 会将高置信度且可采取行动的发现视为阻断项；低置信度或明确归类为误报的发现，以及用户声明的临时／草稿范围内的发现，仅可通过有意的逐次调用声明予以覆盖（见 /oh-my-claudecode:launch）。/oh-my-claudecode:ask-navigator 也可以在梳理尚不明朗的工作时以仅报告模式运行此审计：发现会原样记录在 map 的 Notes 中（绝不会被吞掉），并且仍会作为有效发现纳入 launch yard gate。

结构化退出约定（版本 2）。 此审计的机械检查子集可执行：node scripts/shipyard-audit.mjs [repoRoot] 会在标准输出中输出 JSON（在标准错误中输出人工可读摘要），包含 contractVersion: 2，并检查必需的基础门面（CLAUDE.md 加上 GLOSSARY.md，或可识别的旧版术语表 CONTEXT.md）、重复的术语表权威来源、缺少／无效的 documentLanguage 标签、CLAUDE.md 中的失效路径、项目技能触发条件，以及意图状态。缺少可选表面不构成发现；shipyard.surface.missing.* ID 已弃用，使用方必须采用新约定，而不能依赖旧版发现类别。发现项使用共享字段：severity（high/medium/low/info）、confidence（high/low）、actionable、id、evidence 和 advice。退出码 0 = 无问题，1 = 存在高置信度且可采取行动的发现，2 = 调用错误。启发式类别（代码中未使用的术语、从未被引用的标准）按设计保留在此说明文本层——其置信度按构造即为 low，脚本绝不会生成无法通过机械方式验证的发现。只读。