drydock

Que fait drydock ?

Pose la quille du chantier naval (shipyard) : un dépôt, un harnais partagé, chaque contributeur en hérite. Cette compétence échafaude l'environnement qui transforme « tout le monde livre » en « tout le monde livre sur le même langage de conception » — elle crée les 5 surfaces, les initialise de manière minimale, les connecte aux flux qui les remplissent (launch écrit CONTEXT/ADR ; le passage C5 sediment de launch et les revues sédimentent les normes), et rapporte ce qui existe, ce qui a été créé et ce qui reste intentionnellement vide.

Les quatre piliers et leur emplacement physique :

Pilier	Surfaces
Contexte (arrière-plan partagé)	CONTEXT.md (glossaire) + docs/business/ + docs/adr/ + wiki OMC
Règles (limites)	CLAUDE.md (entrée légère : conventions, principes, index) + docs/standards/
Outils (capacité composable)	.omc/skills/ + .mcp.json + scripts/
Normes (la société de classification)	design-system/ (jetons, composants, motifs) + docs/standards/

Carte métaphorique : le chantier naval est l'installation partagée ; la société de classification (docs/standards/ + design-system/) définit les règles qu'un navire doit respecter pour être en état de naviguer ; drydock pose la quille ; launch expédie le navire.

Quand l'utiliser

• en démarrant un dépôt sur lequel des humains et des agents construiront
• un dépôt où la connaissance vit dans les têtes des gens et l'historique des discussions plutôt que dans des fichiers
• intégration (onboarding) : un nouveau coéquipier ou agent doit hériter du contexte en lisant, pas en demandant

Quand ne pas l'utiliser

• prototypes jetables sans collaborateurs
• un dépôt exécutant déjà ce harnais (utiliser --check à la place)

Workflow

1. Détecter (ne jamais écraser)

Inventorier ce qui existe avant d'écrire quoi que ce soit :

• CLAUDE.md présent ? AGENTS.md présent ? (règle : si l'un des deux existe, l'étendre sur place ; créer le fichier manquant comme un pointeur d'une ligne vers l'autre ; ne jamais créer les deux à partir de zéro)
• CONTEXT.md, docs/adr/, docs/standards/, docs/business/, design-system/, .omc/skills/, .mcp.json, scripts/, .gitattributes — lesquels existent, lesquels manquent ?
• OMC installé ? — ne vérifier que lors de l'exécution dans une session OMC ; en dehors, ignorer cette vérification silencieusement (le harnais fonctionne avec ou sans OMC)

Rapporter d'abord la carte, puis agir.

2. Résoudre la langue du document, puis ne demander que ce que la détection ne peut pas répondre

La langue du document pour les fichiers de harnais générés est une décision sauvegardée dans un fichier, pas un état de conversation. Utiliser exactement ce contrat :

{
  "schemaVersion": 1,
  "authority": { "path": "CONTEXT.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": [
    "CONTEXT.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>"
  ]
}

Ordre de résolution :

1. Un choix humain explicite dans l'invocation en cours l'emporte s'il est valide. Le normaliser en une balise BCP-47 stable : minuscules pour la langue, Majuscule pour l'écriture (script), majuscules pour la région. Une entrée explicite invalide doit être demandée une fois plutôt que devinée.
2. Sinon, lire documentLanguage dans le frontmatter YAML en haut de CONTEXT.md. Une balise valide et non ambiguë en termes d'écriture fait autorité pour les nouvelles invocations de Drydock et Launch. Si la balise persistée est un chinois nu ou seulement régional, demander une fois à ce niveau d'autorité ; ne jamais le contourner par une inférence de source.
3. Si le marqueur est absent ou invalide, inspecter les sources canoniques dans cet ordre : CLAUDE.md, puis README.md. Inférer uniquement lorsque chaque source utilisable a une langue dominante non ambiguë et que toutes les sources utilisables s'accordent sur la même balise normalisée. Une source non ambiguë suffit lorsque l'autre est manquante ou vide.
4. Le chinois doit être résolu en une balise explicite d'écriture : zh-Hans ou zh-Hant (éventuellement suivie d'une région). Le zh nu et les balises chinoises seulement régionales sont ambigus en termes d'écriture et doivent être demandés une fois plutôt que de sélectionner un compagnon. La sélection du compagnon utilise le préfixe langue/écriture le plus long : zh-Hans-* sélectionne le compagnon zh-Hans et zh-Hant-* sélectionne zh-Hant ; préserver la balise normalisée complète (par exemple zh-Hans-CN) dans CONTEXT.md.
5. Des sources utilisables manquantes, du contenu multilingue, des balises conflictuelles, une inférence de faible confiance, une entrée explicite invalide ou un chinois ambigu en termes d'écriture doivent déclencher une question de langue groupée (une seule question). Ne pas deviner. Si aucune réponse n'est disponible, s'arrêter avant d'écrire des artefacts localisés.
6. Avant l'échafaudage, écrire la balise résolue dans la clé de frontmatter stable exacte documentLanguage dans CONTEXT.md (créer ou étendre son frontmatter sans traduire la clé). Ce fichier visible est l'autorité linguistique du rapport d'initialisation ; aucun daemon, registre caché ou état d'exécution n'est créé.

Seuls les textes en prose et les étiquettes/valeurs localisables suivent la langue sélectionnée ; les clés structurelles restent stables dans la langue. Les chemins, commandes slash, indicateurs (flags), blocs de code, espaces réservés, clés de frontmatter et valeurs sémantiques machine, clés YAML/JSON, jetons de cycle de vie, énumérations d'état, identifiants, blockedBy, blocked_by public de l'équipe, et jetons d'analyseur/contrôle restent stables octet par octet.

Ne poser les questions restantes qu'après la résolution de la langue :

• stack technique/package (pour les normes et les graines du design-system)
• ce dépôt a-t-il une UI ? (pas d'UI → design-system/ est créé comme un stub avec une note, ou ignoré sur demande)
• emplacement du traqueur de tickets (GitHub / GitLab / local .scratch/) — pour l'arrivée V1 du port, seul GitHub est supporté ; enregistrer également l'autorité de communication du mainteneur pour l'arrivée (commentaires de tickets, changements d'étiquettes) — consommé par la carte de navigation du navigateur et la file d'attente d'arrivée du port

3. Échafauder (créer les surfaces manquantes — les graines sont rendues dans la langue du document)

CLAUDE.md                      # entrée légère — voir graine A
CONTEXT.md                     # glossaire — voir graine B
.gitattributes                 # * text=auto eol=lf  (élimine le bruit d'avertissement CRLF sur Windows)
docs/adr/0001-adopt-shipyard-harness.md
docs/standards/architecture.md # graine C
docs/standards/data.md
docs/standards/process.md
docs/business/README.md        # graine D
design-system/README.md        # graine E (dépôts UI uniquement ; stub sinon)
design-system/tokens/README.md
.omc/skills/README.md          # graine F
.mcp.json                      # {"mcpServers": {}}
scripts/README.md

Les exemplaires de graines sont des compagnons de référence, jamais une charge utile combinée. Sélectionner exactement un compagnon après avoir résolu documentLanguage ; ne pas émettre de titres ou d'étiquettes en double provenant d'un autre compagnon. Utiliser le préfixe de langue/écriture le plus long : en-* utilise l'anglais, zh-Hans-* utilise le chinois simplifié et zh-Hant-* utilise le chinois traditionnel, tandis que la graine B écrit la balise résolue complète dans documentLanguage. Pour toute autre balise valide, traduire le compagnon canonique anglais une fois tout en préservant chaque jeton stable ci-dessus.

Avant de générer le texte en prose des graines, appeler l'outil Compétence avec agent-doc-discipline et appliquer ses règles ; le texte en prose des graines est prêt uniquement lorsque chaque règle est vérifiable et comporte un « pourquoi », chaque surface se décrit d'elle-même sans historique de discussion, et les sources sont nommées plutôt que supposées. Un coéquipier ou un agent doit pouvoir agir sur le contenu de la graine simplement en lisant.

Graine A — CLAUDE.md, en (entrée légère ; étendre sur place si le fichier existe) :

# <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>

## Standards index (full text in docs/standards/)
- Architecture: docs/standards/architecture.md
- Data: docs/standards/data.md
- Process: docs/standards/process.md

## Decision records (full text in docs/adr/; load-bearing ones listed here)
- ADR-0001: adopt shipyard harness

## Shared background
- Glossary: CONTEXT.md ｜ Business knowledge: docs/business/ ｜ Decision context: docs/adr/

## 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 CONTEXT.md wins; new terms are recorded the moment they settle
- Reusable capability goes to .omc/skills/; UI patterns go to design-system/

Graine A — compagnon zh-Hans (structure identique, sélectionner un selon la langue du document) :

# <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>

## 规范索引（全文在 docs/standards/）
- 架构规范: docs/standards/architecture.md
- 数据规范: docs/standards/data.md
- 流程规范: docs/standards/process.md

## 决策记录（全文在 docs/adr/，此处只列 load-bearing 的）
- ADR-0001: adopt shipyard harness

## 共享背景
- 术语: CONTEXT.md ｜ 业务知识: docs/business/ ｜ 决策背景: docs/adr/

## Agent 指南
- 交付遵循 canonical 工作流 plan → execute → review → verify；`/oh-my-claudecode:launch` 是可选的受治理交付管道（opt-in，需要时显式调用）
- 术语冲突以 CONTEXT.md 为准；新术语当场补录
- 可复用能力沉淀到 .omc/skills/；UI 模式沉淀到 design-system/

Graine A — compagnon zh-Hant (structure identique, ne rendre que cette version) :

# <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>

## 規範索引（全文在 docs/standards/）
- 架構規範: docs/standards/architecture.md
- 資料規範: docs/standards/data.md
- 流程規範: docs/standards/process.md

## 決策記錄（全文在 docs/adr/，此處只列 load-bearing 項目）
- ADR-0001: adopt shipyard harness

## 共享背景
- 詞彙: CONTEXT.md ｜ 業務知識: docs/business/ ｜ 決策背景: docs/adr/

## Agent 指南
- 交付遵循 canonical 工作流 plan → execute → review → verify；`/oh-my-claudecode:launch` 是可選的治理交付管道（opt-in，必須明確呼叫）
- 術語衝突以 CONTEXT.md 為準；新術語確定時立即補錄
- 可重用能力沉澱到 .omc/skills/；UI 模式沉澱到 design-system/

Graine B — CONTEXT.md (la clé de frontmatter stable est l'autorité linguistique) :

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.

## <term>
- Definition:
- Boundary: (is X, not Y)
- Resolved ambiguity:

zh-Hans :

---
documentLanguage: zh-Hans
---

# 术语表

一条术语一个条目：定义、边界、一个已解决的歧义。术语敲定的当下写入。词汇对所有 spec、ticket、代码命名具有法律效力。

## <term>
- 定义:
- 边界: （是 X，不是 Y）
- 已解决的歧义:

zh-Hant :

---
documentLanguage: zh-Hant
---

# 詞彙表

每個術語一個條目：定義、邊界、一個已解決的歧義。術語確定時立即寫入。這裡的詞彙是所有 spec、ticket 與程式碼命名的準則。

## <term>
- 定義:
- 邊界: （是 X，不是 Y）
- 已解決的歧義:

Graine C — docs/standards/architecture.md (data.md / process.md même forme ; le texte en prose est rendu dans la langue du document) :

# Architecture Standards

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

## Module boundaries
## Error handling
## Dependency direction

Graine 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".

Graine 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)

Graine 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.

Graine .mcp.json : {"mcpServers": {}} — les serveurs sont ajoutés lorsqu'une intégration d'outil est réellement nécessaire, pas par spéculation.

4. Câbler la boucle de gouvernance (c'est ce qui en fait un chantier naval, pas un dossier)

Informer l'utilisateur et s'appuyer sur ces flux pour remplir le squelette :

• launch écrit le vocabulaire de CONTEXT.md, les ADR et docs/business/ au fur et à mesure que les décisions se stabilisent (trace écrite)
• launch C5 sediment / code-review sédimente les normes dans docs/standards/ et design-system/ (motifs émergents)
• le port (harbor) ingère les tickets entrants et les traduit en unités de travail exploitables
• le navigateur (navigator) utilise CONTEXT.md et docs/adr/ pour le contexte de planification

5. Rapport d'initialisation

Après l'échafaudage produire un rapport qui liste :

• ce qui existait avant (immuable)
• ce qui a été créé (nouveau)
• ce qui reste vide intentionnellement (par ex. design-system/ dans un dépôt backend, .mcp.json sans serveurs)
• la langue résolue et sa source (choix explicite / CONTEXT.md / inférée)

🛳️  Shipyard initialized for <Project>
   Document language: <tag> (from <source>)
   Existing (preserved):  CLAUDE.md, docs/adr/
   Created:              CONTEXT.md, docs/standards/, design-system/
   Empty (intentional):  .mcp.json (no tools yet)

Rapport minimal ; l'utilisateur peut ensuite lancer launch ou travailler directement.

Contrat d'entrée (Entry contract)

Aucune compétence ne doit lire de l'état (state) avant que drydock ait produit le rapport d'initialisation (bootstrap report). Entre l'initialisation de drydock et ce rapport, drydock est le seul écrivain ; après, il peut y avoir des lecteurs. S'arrêter avant d'écrire si le rapport n'est pas disponible. Ce contrat d'entrée empêche les courses (races) et les lectures partielles de harnais.

Mise à jour (Update)

Réexécuter drydock avec --check. Il n'écrit rien ; il audite la dérive et rapporte les différences avec le plan initial par rapport de harnais :

🛳️  Drydock check for <Project>
   Matches plan:    6 of 7 surfaces
   Missing:         docs/standards/process.md  (should exist — was created then deleted?)
   Plan deviation:  design-system/ exists but this project has no UI (re-evaluate)
   Language drift:  zh-Hans → en (CONTEXT.md language changed; re-scaffolding recommended)