agentleFS
PPrauchnerPPrauchner/ARK-Agent-Rules-Kit/.claude/skills/adopt-repo/SKILL.md

adopt-repo

Skill1 starsChanged 47 days agoMITView on GitHub

Adota um repositório no ARK — cria o .claude/ enxuto que a Instalação global espera (rules do projeto e settings.local.json), preenche CLAUDE.md, CONTEXT.md e docs/agents, e migra projetos que ainda carregam a cópia antiga do kit inteiro. Deriva do código o que o código sabe responder e grelha o resto. Use when adopting an existing repository into the ARK, when CLAUDE.md/CONTEXT.md are missing or empty, or when a repo still has the whole .claude/ kit copied inside it.

  • Reads credentials

8 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use addskill, apply-firmware and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ryanportfolioSkill

    addskill

    Create, import, update, or install repo or personal skills: runtime ownership, resources, discovery checks.

    Also in 6 projects that use this

  • ryanportfolioSkill

    apply-firmware

    Bring current folder (plain folder, existing repo, old or partial firmware copy) up to full Harness Firmware in place. Mirror external repo → adopt-repo.

    Also in 6 projects that use this

  • +10 more from ryanportfolio

The file

Files
SKILL.md

Adopt Repo

O ARK vive no perfil do usuário: skills, comandos e hooks são links para o clone ($ARK_HOME) e valem em qualquer diretório. O que não pode morar no perfil é o que descreve um repositório — e é isso que esta skill cria.

Princípio central: o repositório responde sozinho a stack, comandos e estrutura — derive isso e apenas confirme. O grill é gasto onde o código é mudo: o código mostra class Chapter, mas não diz se você chama aquilo de "capítulo" ou "episódio", nem por que aquela decisão foi tomada.

Regras invioláveis

  1. Nunca sobrescreva. O que já existe é verdade; acrescente apenas o que falta. Rodar duas vezes não pode duplicar seção nem reescrever texto do usuário.
  2. Contradição vai para o grill, não para o seu palpite. Se o CLAUDE.md diz pnpm e o repo tem package-lock.json, pergunte qual vale — não escolha.
  3. Nada de escrever antes de confirmar. Cada artefato é apresentado antes de ir para o disco. Na migração isso vale em dobro: nenhum arquivo é apagado sem a lista aparecer primeiro.

Pré-requisito: $ARK_HOME

A skill copia arquivos do clone do ARK. Sem ele, não há de onde copiar:

echo "$ARK_HOME"

Vazio significa que a Instalação global nunca foi feita nesta máquina. Não adivinhe o caminho e não prossiga: aponte o README e pare — a mesma decisão que o /sync-global já toma.

Os dois ramos

O primeiro passo do recon é olhar se existe .claude/ no repositório. A resposta decide o que a skill faz:

RamoGatilhoO que faz
Adoçãosem .claude/ — o caso normalcria a pasta enxuta e segue para os artefatos
Migraçãocom .claude/ do Modelo de cópia (tem skills/ ou commands/ dentro)enxuga primeiro, depois segue igual

Não existe terceiro caso: .claude/ só com rules/ já é o estado final, e a skill segue direto para os artefatos, completando o que falta.

Os artefatos

#ArtefatoOrigem
1CLAUDE.mdderivado do recon + 1 rodada de conferência
2CONTEXT.mdgrill (glossário de domínio)
3.claude/rules/project-constraints.mdgrill
4.claude/rules/work-calibration.mdgrill
5.claude/rules/<linguagem>-conventions.mdcopiado do $ARK_HOME + confirmação
6docs/agents/*seguindo a setup-matt-pocock-skills
7.claude/settings.local.jsonderivado do settings.local.json.example

code-conventions.md e karpathy-principles.md não entram na lista: são genéricos, e o instalador global já os importa no ~/.claude/CLAUDE.md direto do clone. Copiá-los para o projeto congelaria uma fotografia que nada atualiza.

Workflow

1. Recon

Levante o estado atual antes de perguntar qualquer coisa. Use o checklist de recon — ele diz o que ler por tipo de stack e o que cada sinal significa.

Ao final você deve saber: qual ramo, linguagem(ns) e versão, gerenciador de pacotes, comandos de dev/build/test/lint, estrutura de pastas, e o que já existe dos sete artefatos.

2. Apresentar o mapa da adoção

Mostre em uma tabela o que encontrou e o que falta — o usuário precisa ver o tamanho do trabalho antes de entrar num grill. Confirme a stack detectada; se você errar aqui, tudo depois herda o erro. No ramo de migração, a tabela vem junto com as listas do passo 3.

3. Migração — só no ramo legado

O projeto carrega uma cópia do kit inteiro, feita quando o ARK ainda era distribuído por cópia. Essa cópia agora sombreia o que vem do perfil: skill de mesmo nome dentro do projeto ganha da global, e é a versão velha que roda.

Separe em três listas e mostre as três antes de apagar qualquer coisa:

ListaCritérioAção
Redundantepasta em .claude/skills/, commands/, hooks/, scripts/ cujo nome existe hoje no $ARK_HOMEapagar, após confirmação
Do projetopasta nos mesmos lugares cujo nome não existe no $ARK_HOMEnão apagar — listar e perguntar
Preservadorules/, settings.local.json, current-issue, board.env, .gitignorenão tocar

A lista "Do projeto" é ambígua por natureza: pode ser skill escrita naquele repositório ou resto de um layout que o ARK aposentou. Distinguir os dois não é trabalho de heurística — é pergunta (ADR 0001).

Depois de enxugar: se havia .claude/rules/code-conventions.md com a seção "Restrições deste projeto" preenchida, mova esse conteúdo para project-constraints.md e só então apague o arquivo antigo — o genérico dele agora vem do clone. Seção ainda em <preencher> não é conteúdo: pode ir junto com o arquivo.

Remova também .claude/.template.json: o Marcador de origem existia para o /update-claude, que não existe mais (ADR 0003).

4. Semear o .claude/

Crie o que faltar, copiando do $ARK_HOME:

mkdir -p .claude/rules
cp -n "$ARK_HOME/rules/project-constraints.md" .claude/rules/
cp -n "$ARK_HOME/rules/work-calibration.md"    .claude/rules/
cp -n "$ARK_HOME/.gitignore"                   .claude/

O .gitignore viaja junto porque é ele que mantém settings.local.json fora do git. Sem ele, o primeiro /commit versiona caminhos da sua máquina.

O -n é a regra 1 em forma de flag: arquivo que já existe não é copiado por cima.

5. CLAUDE.md — derivar e conferir

Monte o rascunho a partir do recon: o que o projeto é, stack, comandos, estrutura de pastas e apontadores para CONTEXT.md e docs/adr/. Uma rodada de conferência — não vire isso em entrevista, o repo já respondeu.

Se CLAUDE.md já existir: leia, trate como verdade, e proponha apenas as seções ausentes. Liste as contradições encontradas em vez de resolvê-las sozinho.

6. CONTEXT.md e restrições — grelhar

Aqui sim, invoque a skill grill-with-docs. Ela já entrevista uma pergunta por vez, desafia termos contra o glossário e escreve o CONTEXT.md incrementalmente no formato certo — não reimplemente isso.

Foque o grill no que o código não entrega:

  • Glossário: para cada conceito central que o recon encontrou, qual é o termo de domínio em pt-BR e qual identificador em inglês o representa. Fronteiras entre conceitos parecidos (User × Customer, Chapter × Episode).
  • Restrições deste projeto: o que não pode mudar — dependência que é decisão e não acaso, formato de persistência, exigência de reprodutibilidade, limite de ambiente. Escreva o resultado em .claude/rules/project-constraints.md, substituindo o <preencher>.
  • Calibragem de trabalho: o recon já mostrou a estrutura de pastas — pergunte quantos módulos distintos costumam entrar numa mudança antes de ela virar grande demais, e quais pastas o projeto trata como camadas. Escreva o resultado nas duas seções de .claude/rules/work-calibration.md, substituindo os <preencher>. Deixar vazio é resposta legítima: significa que valem os defaults genéricos.
  • ADRs retroativos: só ofereça quando a decisão for difícil de reverter, surpreendente sem contexto e fruto de trade-off real — os três critérios da grill-with-docs. Não documente retroativamente o que foi acaso.

7. Convenções da linguagem

Um projeto pode ter mais de uma linguagem. Para cada linguagem com código mantido pelo projeto, copie para .claude/rules/ o arquivo dela, se o clone tiver:

cp -n "$ARK_HOME/rules/<linguagem>-conventions.md" .claude/rules/

Conta só o código que o projeto escreve e mantém. Vendorizado e gerado não conta: node_modules/, vendor/, dist/, build/, lockfiles, código gerado por ferramenta.

Linguagem marginal é pergunta, não cópia. Um único script .sh, um .sql solto: pergunte se vale copiar. Cada arquivo em .claude/rules/ é contexto carregado em toda sessão, e o custo só se paga quando a linguagem é trabalhada de verdade. Não há limiar numérico — o que é marginal num repositório é central em outro.

Linguagem sem arquivo no clone: escreva .claude/rules/<linguagem>-conventions.md no mesmo espírito (documentação, tipagem, naming) — direto no projeto; ofereça semeá-lo também no $ARK_HOME se for servir a outros repositórios.

Este arquivo é copiado, e não importado, de propósito: qual linguagem se aplica é conhecimento do projeto, e um import exigiria o caminho absoluto da sua máquina dentro de arquivo versionado. O preço é o conteúdo congelar — aceitável, porque convenção de linguagem quase não muda.

8. docs/agents/ — seguir a setup-matt-pocock-skills

Leia $ARK_HOME/skills/setup-matt-pocock-skills/SKILL.md e execute aquelas instruções nesta sessão. Ela tem disable-model-invocation: true no frontmatter, ou seja, não é invocável pela tool Skill — por isso seguir, e não invocar. Não reescreva o que ela faz.

Este passo não é opcional: sem docs/agents/issue-tracker.md o /afk-queue se recusa a rodar.

9. settings.local.json

Copie $ARK_HOME/settings.local.json.example para .claude/settings.local.json e substitua o caminho placeholder pelo caminho real do repositório. Se o arquivo já existir, não toque nele.

10. Relatório final

Uma tabela com os sete artefatos: criado / completado / já existia / pulado (e por quê). Para as convenções de linguagem, liste à parte quais linguagens foram copiadas, quais foram perguntadas (e a resposta) e quais foram puladas (e por quê). No ramo de migração, some a contagem do que foi apagado e repita a lista "Do projeto" que ficou de pé, que é decisão pendente.

Termine dizendo o que ficou pendente de decisão humana — restrição que o usuário não soube responder na hora vale mais explícita como pendência do que preenchida com um chute.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.