Estaleiro (Drydock)
Assente a quilha do estaleiro: um repositório, um ambiente compartilhado, todo colaborador herda. Esta skill cria a infraestrutura que transforma "todos embarcam" em "todos embarcam na mesma linguagem de design" — ela cria as 5 superfícies, as semeia minimamente, as conecta aos fluxos que as preencherão (o launch escreve CONTEXT/ADR; o C5 sediment do launch e as revisões sedimentam padrões), e relata o que existe, o que foi criado e o que permanece vazio intencionalmente.
Os quatro pilares e onde vivem fisicamente:
| Pilar | Superfícies |
|---|---|
| Contexto (conhecimento compartilhado) | CONTEXT.md (glossário) + docs/business/ + docs/adr/ + wiki do OMC |
| Regras (limites) | CLAUDE.md (entrada fina: convenções, princípios, índice) + docs/standards/ |
| Ferramentas (capacidade combinável) | .omc/skills/ + .mcp.json + scripts/ |
| Padrões (sociedade classificadora) | design-system/ (tokens, componentes, padrões) + docs/standards/ |
Mapa de metáforas: o estaleiro é a instalação compartilhada; a sociedade classificadora (docs/standards/ + design-system/) define as regras que um navio deve cumprir para ser navegável; o drydock assenta a quilha; o launch faz o lançamento.
Quando Usar
- iniciar um repositório que humanos e agentes construirão juntos
- um repositório onde o conhecimento está na cabeça das pessoas e no histórico de chat, em vez de arquivos
- onboarding: um novo colega ou agente deve herdar contexto lendo, não perguntando
Quando Não Usar
- protótipos descartáveis sem colaboradores
- um repositório que já executa esta infraestrutura (use
--check)
Fluxo de Trabalho
1. Detectar (nunca sobrescrever)
Inventarie o que existe antes de escrever qualquer coisa:
CLAUDE.mdpresente?AGENTS.mdpresente? (regra: se algum existir, estenda-o no lugar; crie o ausente como um ponteiro de uma linha para o outro; nunca crie ambos do zero)CONTEXT.md,docs/adr/,docs/standards/,docs/business/,design-system/,.omc/skills/,.mcp.json,scripts/,.gitattributes— quais existem, quais estão faltando?- OMC instalado? — só vale a pena verificar ao executar dentro de uma sessão do OMC; fora dela, pule esta verificação silenciosamente (a infraestrutura funciona com ou sem OMC)
Relate o mapa primeiro, depois aja.
2. Resolver o idioma do documento, depois pergunte apenas o que a detecção não pode responder
O idioma do documento para os arquivos de infraestrutura gerados é uma decisão baseada em arquivo, não um estado de conversa. Use este contrato exatamente:
{
"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>"
]
}
Ordem de resolução:
- Uma escolha humana explícita na invocação atual vence quando válida. Normalize-a para uma tag BCP-47 estável: idioma em minúsculas, script em Title Case, região em maiúsculas. Entrada explícita inválida deve ser perguntada uma vez, em vez de adivinhada.
- Caso contrário, leia
documentLanguagedo frontmatter YAML no topo deCONTEXT.md. Uma tag válida e sem ambiguidade de script é autoritativa para invocações novas de Drydock e Launch. Se a tag persistida for chinês puro ou apenas região, pergunte uma vez neste nível de autoridade; nunca ignore com inferência de fonte. - Se o marcador estiver ausente ou inválido, inspecione fontes canônicas nesta ordem:
CLAUDE.md, depoisREADME.md. Infira apenas quando toda fonte utilizável tiver um idioma dominante inequívoco e todas as fontes utilizáveis concordarem com a mesma tag normalizada. Uma fonte inequívoca é suficiente se a outra estiver ausente ou vazia. - Chinês deve resolver para uma tag explícita qualificada por script:
zh-Hansouzh-Hant(opcionalmente seguido por região).zhpuro e tags chinesas apenas com região são ambíguas e devem ser perguntadas uma vez, em vez de selecionar um acompanhante. A seleção do acompanhante usa o prefixo idioma/script mais longo:zh-Hans-*seleciona o acompanhantezh-Hansezh-Hant-*selecionazh-Hant; preserve a tag normalizada completa (por exemplozh-Hans-CN) emCONTEXT.md. - Fontes utilizáveis ausentes, conteúdo de idioma misto, tags conflitantes, inferência de baixa confiança, entrada explícita inválida ou chinês ambíguo devem acionar uma pergunta de idioma em lote. Não adivinhe. Se nenhuma resposta estiver disponível, pare antes de escrever artefatos localizados.
- Antes de preparar o terreno, escreva a tag resolvida na chave exata de frontmatter estável
documentLanguageemCONTEXT.md(criando ou estendendo seu frontmatter sem traduzir a chave). Este arquivo visível é a autoridade de idioma do relatório de inicialização; nenhum daemon, livro-razão oculto ou estado de tempo de execução é criado.
Apenas texto corrido e rótulos/valores localizáveis seguem o idioma selecionado; chaves estruturais permanecem estáveis no idioma. Mantenha caminhos, comandos de barra, flags, blocos de código, placeholders, chaves de frontmatter e valores semânticos de máquina, chaves YAML/JSON, tokens de ciclo de vida, enums de status, IDs, blockedBy, blocked_by público do Team, e tokens de analisador/controle estáveis byte a byte.
Faça as perguntas restantes somente após o idioma ser resolvido:
- pilha de pacotes/tecnologia (para padrões e sementes de design-system)
- este repositório tem UI? (sem UI → design-system/ é criado como um stub com uma nota, ou pulado se solicitado)
- localização do rastreador de issues (GitHub / GitLab / local
.scratch/) — para o intake V1 do harbor apenas GitHub é suportado; também registre a autoridade de comunicação do mantenedor para intake (comentários de issues, alterações de labels) — consumido pelo mapa do navigator e pela fila de intake do harbor
3. Preparar o terreno (criar superfícies ausentes — sementes renderizam no idioma do documento)
CLAUDE.md # entrada fina — veja semente A
CONTEXT.md # glossário — veja semente B
.gitattributes # * text=auto eol=lf (mata ruído de aviso CRLF no Windows)
docs/adr/0001-adotar-infraestrutura-do-estaleiro.md
docs/standards/architecture.md # semente C
docs/standards/data.md
docs/standards/process.md
docs/business/README.md # semente D
design-system/README.md # semente E (repositórios com UI apenas; stub caso contrário)
design-system/tokens/README.md
.omc/skills/README.md # semente F
.mcp.json # {"mcpServers": {}}
scripts/README.md
Sementes exemplares são acompanhantes de referência, nunca uma carga útil combinada. Selecione exatamente um acompanhante após resolver documentLanguage; não emita cabeçalhos ou rótulos duplicados de outro acompanhante. Use o prefixo idioma/script mais longo: en-* usa inglês, zh-Hans-* usa chinês simplificado e zh-Hant-* usa chinês tradicional, enquanto a Semente B escreve a tag resolvida completa em documentLanguage. Para qualquer outra tag válida, traduza o acompanhante canônico em inglês uma vez, preservando todo token estável acima.
Antes de gerar texto da semente, chame a ferramenta Skill com agent-doc-discipline e aplique suas regras; o texto da semente está pronto apenas quando cada regra é verificável e carrega um "porquê", cada superfície é autodescritiva sem histórico de chat, e as fontes são nomeadas em vez de assumidas. Um colega ou agente deve ser capaz de agir com base no conteúdo da semente apenas lendo.
Semente A — CLAUDE.md, en (entrada fina; estenda no lugar se o arquivo existir):
# <Project> — Estaleiro de Agentes e Humanos
## Convenções do projeto
- <language/framework/package manager/naming — liste o que importa, pule o resto>
## Princípios de arquitetura
- <os 3-5 princípios mais frequentemente violados neste projeto>
## Índice de padrões (texto completo em docs/standards/)
- Arquitetura: docs/standards/architecture.md
- Dados: docs/standards/data.md
- Processo: docs/standards/process.md
## Registros de decisão (texto completo em docs/adr/; itens importantes listados aqui)
- ADR-0001: adotar infraestrutura do estaleiro
## Conhecimento compartilhado
- Glossário: CONTEXT.md ｜ Conhecimento de negócio: docs/business/ ｜ Contexto de decisão: docs/adr/
## Guia do agente
- A entrega segue o fluxo de trabalho canônico plan → execute → review → verify; `/oh-my-claudecode:launch` é um pipeline de entrega governado opcional (opt-in, invocar explicitamente)
- Em conflitos de termos, CONTEXT.md vence; novos termos são registrados no momento em que são estabelecidos
- Capacidade reutilizável vai para .omc/skills/; padrões de UI vão para design-system/
Semente A — acompanhante zh-Hans (estrutura idêntica, selecione uma das duas conforme o idioma do documento):
# <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/
Semente A — acompanhante zh-Hant (estrutura idêntica, renderize apenas esta versão):
# <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/
Semente B — CONTEXT.md (a chave de frontmatter estável é a autoridade de idioma):
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）
- 已解決的歧義:
Semente C — docs/standards/architecture.md (data.md / process.md mesma estrutura; texto renderiza no idioma do documento):
# Padrões de Arquitetura
Escrita em formato de regras, verificável; cada regra carrega um "porquê". Seções vazias são permitidas — o sedimento é gradual.
## Limites de módulo
## Tratamento de erros
## Direção de dependências
Semente D — docs/business/README.md:
# Conhecimento de Negócio
Contexto de decisão e regras de negócio. Sugestão de formato: um artigo responde a uma pergunta de negócio, o parágrafo de abertura explica por que é importante.
Um novo colega (humano ou agente) lendo este diretório deve ser capaz de responder "por que esta direção de produto existe".
Semente E — design-system/README.md:
# Sistema de Design
## tokens/ Tokens de design (cores/tipografia/espaçamento, JSON legível por máquina é preferido)
## components/ Contratos de componentes (propósito, variantes, mau uso)
## patterns/ Padrões de interação (formulários, feedback, carregamento, estados vazios — padrões reutilizados sedimentados)
Semente F — .omc/skills/README.md:
# Skills do Projeto
Capacidades reutilizáveis sedimentadas por este projeto: ferramentas especializadas, modelos de prompt, práticas especializadas.
Uma skill por arquivo `.omc/skills/<nome>.md`, frontmatter deve conter um `id` ASCII estável mais nome + descrição +
**triggers não vazios** (requisito rígido do loader: ausente ou vazio significa que a skill nunca é carregada):
```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.
```
As chaves literais YAML `id`, `name`, `description` e `triggers` nunca são localizadas. `id` e outros valores semânticos de máquina permanecem ASCII e estáveis; os valores de exibição escalares para `name`, `description` e `triggers`, além de cabeçalhos Markdown e texto corrido, podem ser localizados. Um nome de exibição não latino permanece carregável porque o `id` ASCII explícito é estável.
O critério de admissão corresponde ao skillify: se pode ser pesquisado no Google em 5 minutos, não é uma skill;
escreva "a disciplina de decisão específica deste projeto", não tutoriais genéricos.
Semente .mcp.json: {"mcpServers": {}} — servidores são adicionados quando uma integração de ferramenta é realmente necessária, não especulativamente.
4. Conectar o ciclo de governança (isto é o que torna um estaleiro, não uma pasta)
Informe o usuário e confie nestes fluxos para preencher o esqueleto:
- launch escreve vocabulário em CONTEXT.md, ADRs e docs/business/ conforme as decisões são tomadas (rastro de papel)
- C5 sediment do launch / code-review sedimenta padrões de arquitetura, dados e processo com base nas decisões tomadas
...
[truncado para tradução]