adotar-keelson

Adotar keelson

Porte um fluxo disciplinado orientado a issues — enquadrar → planejar → implementar → abrir mudança → gate → fechar, com autonomia tática (o agente faz os movimentos mecânicos) e um loop humano estratégico (escala no momento em que um movimento toca o design, plano ou estratégia original) — para este repositório, contra seu rastreador e SDLC.

Você produz duas coisas no repositório alvo:

1. AGENTS.md — um substrato organizado em questionário ao qual as skills deferem.
2. Um pacote de skills do ciclo de vida — as ideias adotadas, escritas como skills do próprio repositório em linguagem simples (elas nomeiam ações; leem as amarrações do rastreador de AGENTS.md, nunca as codificam).

Tudo o que você precisa está nesta pasta de skill: templates/AGENTS.client.md, templates/lifecycle/*.md, references/tracker-notes.md. Preencha, não invente.

1 · Como conduzir a entrevista

Esta é uma sessão de configuração, não um sim/não rápido. Espere ≈8–20 rodadas — menos para um repositório simples, mais para um complexo; use quantas forem necessárias para tornar o fluxo inequívoco. Não tenha pressa; a recompensa é um AGENTS.md com o qual o usuário realmente concordou.

• Um tópico por rodada. Diga o que o fluxo de referência faz, então faça o usuário decidir para o repositório dele. Não silencie as chamadas consequenciais e siga em frente — superfície a escolha e obtenha um aceno explícito antes de avançar.
• O usuário é dono do fluxo. Os padrões do keelson são um ponto de partida, não a resposta. Quando eles estiverem em dúvida, ofereça a opção conservadora, marque-a para revisitar, não a enterre.
• Descubra antes de propor. Conduza as rodadas de descoberta primeiro; aprenda o que eles têm, falta ou querem — então proponha apenas as ideias que se encaixam nas lacunas.
• Registre enquanto avança; confirme no final. A rodada final reproduz cada decisão para um único aceno antes de você escrever algo.

2 · As rodadas

Descoberta primeiro, depois uma rodada por pilar, depois as famílias opcionais que a descoberta superou, então padrões + entrega, então confirme. Cada rodada nomeia a(s) skill(s) que configura e os placeholders (§3) que preenche. Mescle rodadas para um repositório simples, divida-as para um complexo.

Descoberta

• D1 · Mapa SDLC. Perguntas abertas: quais etapas/pilares de entrega existem hoje (triagem → design → construção → revisão → QA → release → operações)? Quais são sólidos, quais são ad-hoc ou ausentes, quais eles querem que o keelson estabeleça ou aperte? Isso direciona quais ideias você subsequentemente propõe — ouça antes de prescrever.
• D2 · Rastreador e vocabulário. Rastreador; como chamam um item de trabalho / uma mudança / o quadro; as colunas de {{status_field}} e o momento do ciclo de vida que cada uma mapeia.
• D3 · Repositório e branching. {{default_branch}}, {{branch_pattern}}, {{isolation}} (worktree ou só branch), {{merge_style}}, mono- vs polirrepositório.

Pilares — decida como cada um funciona (adote a skill + capture suas convenções)

• P1 · Triagem / enquadramento (enquadrar-mudança) — toda mudança começa como uma {{issue}} rastreada? o que ela deve conter (contexto / fora-de-escopo / aceitação)?
• P2 · Planejamento e onde o plano reside (planejar-o-trabalho) — quando um plano é necessário, e onde é arquivado: num comentário da {{issue}}, num doc de design no repositório, numa página wiki, ou no corpo da {{change}}? → {{plan_location}}.
• P3 · Documentos e registros de decisão — o(s) lar(es) dos docs: {{docs_root}} no repositório, wiki externo (ex.: Confluence/Notion), ou misto → {{docs_system}}; ADRs — usado, e onde ({{adr_dir}})? a regra de atualização de doc (quais mudanças devem atualizar quais docs, mesma {{change}}).
• P4 · Disciplina de implementação (implementar-mudança) — código + doc + testes juntos? nunca codificar (superfície em config)? escopo limitado à {{issue}}?
• P5 · Abertura de mudanças (abrir-mudança) — {{change_title_format}}, vincular a {{issue}} no corpo, {{size_cap}} + {{oversize_label}}, autorevisão.
• P6 · Gates de qualidade CI (via tune-gates G1) — {{quality_gates}}; de propriedade da CI (não pré-execute antes de abrir), com exceção de verificação local durante depuração de CI vermelha.
• P7 · Fluxo de status (rastrear-status) — quando o status se move e quem o move; quadro vs. etiquetas como fonte da verdade; fechar apenas com evidência citada.
• P8 · Regra de pickup (pegar-proximo-trabalho) — a ordenação de backlog/prioridade para reivindicar a próxima {{issue}}.

Famílias opcionais — proponha apenas o que D1 superou; adote ou pule com o usuário

• O1 · Marcos / releases (fechar-marco) — estágios / marcos / épicos / sprints com critérios de saída? modelo de release? → {{milestone}}.
• O2 · Gates de verificação (via tune-gates G2) — um artefato revisável → review-gate; uma {{source_of_truth}} canônica → o par source-change-gate + source-sync-gate; múltiplos {{targets}} → parity-gate. tune-gates é dono das rodadas de gate, regras de seleção e templates — execute-o para este pilar; ele retorna o conjunto adotado para a escrita unificada (§4).
• O3 · Consistência de documentação e atualizações de fonte — sync-docs (reconciliar após lotes) e update-source-of-truth (fluir uma mudança de fonte da verdade através do loop).

Disciplina — o loop humano

• H1 · Fronteira tática vs. estratégica — o cerne. Faça o usuário traçar a linha: quais movimentos o agente faz autonomamente vs. quais devem escalar para reconhecimento.
• H2 · Incerteza e precedência (responder-a-incerteza) — resolvendo ambiguidade e conflitos de doc; perguntar vs. prosseguir de forma conservadora.
• H3 · Follow-ups, arte anterior, operações (esculpir-followup, verificar-arte-anterior, automatizar-ou-runbook) — adotar cada?

Padrões e entrega

• S1 · Padrões de engenharia — apresente os padrões da InnoVestrum embutidos em templates/AGENTS.client.md → Padrões de engenharia; adote como estão, corte ou estenda.
• S2 · Onde as skills são escritas — Claude .claude/skills/, Codex .agents/skills/, ou ambos; um AGENTS.md existente → mescle nele, não sobrescreva.

Confirmar

• C1 · Reproduzir e confirmar. Resuma cada decisão, as ideias adotadas vs. puladas, e qualquer lacuna que o usuário escolheu deixar aberta. Obtenha um aceno final — então preencha e escreva.

3 · Placeholders (as únicas coisas que você preenche)

Apenas convenções de repositório são placeholders; verbos de ação permaneçam simples. Resolva cada um; não deixe nenhum sem preencher.

• Vocabulário — {{tracker}}, {{issue}} / {{issues}}, {{change}}
• Quadro — {{board}}, {{status_field}}, colunas usadas: {{status.planning}} · {{status.in_progress}} · {{status.in_review}} · {{status.done}} · {{status.blocked}} · {{status.deferred}} (omitir não usado)
• Branch / mudança — {{default_branch}}, {{branch_pattern}}, {{change_title_format}}, {{merge_style}}, {{isolation}}
• Documentos / decisões — {{docs_system}} (repo / wiki / misto), {{docs_root}}, {{plan_location}}, {{adr_dir}} (qualquer pode ser nenhum)
• Escopo / gates — {{size_cap}} + {{oversize_label}}, {{milestone}}, {{source_of_truth}}, {{target}} / {{targets}}, {{quality_gates}} (qualquer nenhum)

4 · Preencher e escrever

1. AGENTS.md do cliente. Renderize templates/AGENTS.client.md: substitua cada placeholder, mantenha apenas seções adotadas, incorpore os padrões de S1, e dobre a seção do rastreador escolhido de references/tracker-notes.md sob ## Notas do rastreador. Escreva na raiz do repositório (ou mescle no arquivo existente).
2. Skills do ciclo de vida. Para cada ideia adotada, renderize templates/lifecycle/<nome>.md (placeholders + descrição do frontmatter) e escreva em cada diretório de skill do cliente como <dir>/<nome>/SKILL.md. As skills de gate + o substrato §8/§3 seguem tune-gates §4 — sua seleção (P6/O2) decide quais gates são adotados; renderize apenas esses.
3. Ideias puladas → não escreva a skill, não deixe sua seção no AGENTS.md.

5 · Verificar e devolver

• Faça grep nos arquivos escritos por {{ — zero placeholders restantes.
• Cada ideia adotada tem tanto uma seção no AGENTS.md quanto uma skill escrita; os {{status.*}} / {{change}} / {{plan_location}} etc. de cada skill escrita correspondem à entrevista.
• Recapitule: rastreador, os pilares SDLC adotados vs. deixados ao usuário, arquivos escritos e qualquer decisão ainda sinalizada para revisitar. Aponte-os para o novo AGENTS.md para ler primeiro.

Armadilhas

• Faça o usuário decidir; não defina automaticamente as chamadas consequenciais. Vocabulário, colunas de status, onde planos e documentos residem, a linha tática/estratégica — estas são do usuário para definir. Um AGENTS.md definido silenciosamente é algo com o qual ninguém concordou.
• O pacote é selecionável, gates mais que tudo. Escreva apenas ideias adotadas; um repositório backend sem fonte canônica e um alvo pula os gates de fonte e paridade completamente. As regras de seleção de gate — e a armadilha "nunca escreva um gate com uma amarração nula" (sem source-change/source-sync-gate quando {{source_of_truth}} é nenhum; sem paridade para um único {{target}}) — residem em tune-gates; aplique-as, não as rederive aqui.
• Não transcreva comandos de um rastreador nas skills. Nomeie a ação; as amarrações vivem uma vez, em AGENTS.md → Notas do rastreador. Prestes a escrever gh/glab numa skill? Pare — empurre para a nota do rastreador.
• Os padrões são o piso, não decoração — o pacote defere a eles para qualidade de código; não os reafirme dentro das skills.
• Segure cada linha escrita à regra de ouro (keelson AGENTS.md): apenas lacunas, armadilhas, apontadores. Uma skill preenchida que explica como abrir um PR em geral está errada; nomeie o passo e difira o resto.