tuannv0069/claude-doc-genome

init-project

propósito

Inicializar o sistema de documentação do agente de um novo projeto a partir de um bundle portátil em um único comando. Após a inicialização, o projeto se mantém usando os padrões implantados (árvore de decisão doc-organization.md §8.3 + meta-padrões portáteis). init é executado uma vez por projeto; update pode ser re-executado posteriormente nesse projeto para puxar arquivos portáteis mais novos do bundle (merge seguro de 3 vias — nunca sobrescreve edições locais não promovidas). check/promote mantêm o próprio bundle e são executados apenas neste repositório mestre.

dependências

• ./portable/rules/ — 7 regras portáteis (sempre carregadas + com escopo de caminho)
• ./portable/agent-guide/ — five-why.md, markdown.md, mermaid.md, orchestration-policy.md, worktree.md (implantar em docs/agent-guide/general/)
• ./portable/skills/ — skill-designer/, skill-writer/, document-writer/ (árvores completas)
• ./portable/agents/ — skill-writer-auditor.md
• ./templates/ — CLAUDE.md.tpl, agent-guide/index.md.tpl, docs/index.md.tpl
• ./VERSION — versão do bundle, incrementada a cada promoção
• scripts/update.mjs (raiz do repositório) — motor para o modo update (merge bundle→live de 3 vias); scripts/sync-version.mjs — sincronização de versão de fonte única

modos

invocação	executa em	ação
/init-project	novo projeto	implantar bundle (fluxo abaixo)
/init-project check	repositório mestre	comparar sha256 bundle ↔ live por §mapa → relatar desvios
/init-project promote	repositório mestre	copiar live → bundle para cada arquivo mapeado, incrementar VERSION
/init-project update	projeto inicializado	puxar arquivos portáteis mais novos bundle → live, merge seguro de 3 vias (manifesto ↔ live ↔ bundle); pular conflitos (fluxo abaixo)

fluxo (init — novo projeto)

1. Escanear projeto: detectar stack + módulos opcionais por coluna de sinal da ## matriz de módulos. Saída: conjunto de módulos proposto + valores de slots descobertos.
2. Entrevista: confirmar conjunto de módulos proposto; perguntar slots não escaneáveis (portas dev em uso, escopo de propriedade, idioma da documentação). Slot não respondível → deixar marcador TODO, nunca inventar um valor; módulo incerto → pular.
3. Copiar portable/ literalmente: portable/rules/* → .claude/rules/; portable/agent-guide/* → docs/agent-guide/general/; portable/skills/* → .claude/skills/; portable/agents/* → .claude/agents/.
4. Renderizar templates: preencher {{slots}} da entrevista em CLAUDE.md, docs/agent-guide/index.md, docs/index.md; slot ausente → manter marcador TODO.
5. Gerar regras opcionais: para cada módulo opcional confirmado, escrever uma regra ajustada ao projeto em docs/agent-guide/general/ conforme rule-writing-standards, e anexar sua linha de gatilho ao CLAUDE.md no mesmo passo — sem template fixo.
6. Escrever manifesto .claude/init-manifest.json: { version, deployedAt, files:[{path,sha256}], templates:[{path,sha256}], modules:[...] } (proveniência; files[] lido por update para detecção de desvios de 3 vias — manter sha256 preciso; templates[] registra o sha .tpl de cada arquivo renderizado — path = caminho do template relativo a templates/, ex. CLAUDE.md.tpl, usado por update para ALERTAR quando um template mudou desde a implantação).
7. Verificar: cada arquivo implantado está no nível correto; cada arquivo de regra/guia do agente possui metadados scope:; CLAUDE.md dentro do orçamento de tokens; cada arquivo sob demanda que afeta comportamento tem uma linha de gatilho ou entrada de roteador (alcançabilidade, arquivo→gatilho); cada gatilho MUST Read em CLAUDE.md resolve para um arquivo implantado (alcançabilidade, gatilho→arquivo — sem gatilho morto); nenhum {{slot}} não renderizado permanece, exceto marcadores TODO intencionais. Concluído = checklist aprovado + manifesto escrito.

mapa bundle ↔ live (check / promote — repositório mestre; update — projeto inicializado)

caminho bundle	caminho live
portable/rules/*	.claude/rules/*
portable/agent-guide/*	docs/agent-guide/general/*
portable/skills/*	.claude/skills/*
portable/agents/*	.claude/agents/*

• check: sha256 cada par → listar discrepâncias. Direção de atualização padrão é live → bundle (promote); corrigir live primeiro, depois promover.
• promote: copiar live → bundle para cada arquivo mapeado, então incrementar a versão via node scripts/sync-version.mjs set <x.y.z> (escreve VERSION canônico + espelha em .claude-plugin/* e no badge README).

fluxo (update — projeto inicializado)

Direção bundle → live (inverso de promote). Toca apenas o conjunto portátil literal; fenótipo renderizado (CLAUDE.md, index.md, guias escritos pelo projeto) está fora do escopo. Invocar update.mjs pelo seu caminho dentro do plugin instalado (ele localiza o bundle a partir de sua própria localização); --project é a raiz do projeto inicializado e padrão é o diretório atual.

1. Simulação: node <plugin>/scripts/update.mjs --project <project-root> → revisar o plano ADD / UPDATE / CONFLICT e o delta de versão.
2. Resolver cada CONFLICT primeiro — conflito = um arquivo portátil editado localmente desde a implantação. Promovê-lo upstream (para que a melhoria entre no bundle) ou sobrescrever manualmente após revisão. Nunca sobrescrever cegamente.
3. Aplicar: node <plugin>/scripts/update.mjs --apply --project <project-root> → escreve ADD + UPDATE, pula conflitos, atualiza version do manifesto + files[].sha256.
4. Apenas aditivo e no lugar — update nunca deleta: um arquivo removido do bundle permanece no projeto, e um arquivo deletado localmente é readicionado. Podar esses manualmente se necessário.
   • templates/* (CLAUDE.md, index.md — fenótipo renderizado) nunca são sobrescritos: seus slots contêm valores específicos do projeto. update apenas emite um AVISO quando um .tpl mudou desde a implantação (sha vs manifest.templates[]); re-renderizar manualmente (diff .tpl vs live, re-aplicar mudanças estruturais, manter valores de slot) ou re-executar /init-project. O AVISO persiste até a próxima inicialização re-gravar o sha do template.
5. Código de saída: 0 = atualizado ou aplicado limpo; 1 = conflitos restantes; 2 = erro de configuração (sem manifesto → projeto não foi inicializado por este plugin).

matriz de módulos

módulo	inclui	implantar quando	sinal de scan (exemplos, não exaustivo)
core	portable/* (todos os 4 grupos) + 3 templates	sempre	—
runtime	agent-guide/general/local-runtime.md + gatilho CLAUDE.md (skill escreve por scan, passo 5)	projeto executa um servidor dev	package.json scripts dev/start, launchSettings.json, configuração vite/next/dotnet/django/cargo
e2e	agent-guide/general/<ferramenta>.md (nomeada conforme ferramenta detectada) + gatilho CLAUDE.md (passo 5)	projeto tem testes E2E de navegador	dependência playwright/cypress/selenium, pasta e2e/, configuração E2E

• Módulo opcional é implantado apenas quando o scan confirma OU o usuário confirma na entrevista — incerto → pular.
• Git: guardrail mínimo (commitar apenas sob solicitação, nunca fazer push) vem em CLAUDE.md.tpl; política detalhada é scope: project — projeto escreve docs/agent-guide/general/git.md sob demanda, adicionando sua linha de gatilho no mesmo commit (alcançabilidade — nunca um gatilho apontando para um arquivo ausente).
• Um módulo pulado necessário depois → projeto escreve a regra por conta própria conforme o padrão implantado. Novo módulo entra no bundle apenas via promote após um projeto real testar o padrão.

regras de independência

• Skill é executado uma vez por projeto; arquivos implantados não referenciam nenhum arquivo deste repositório mestre; regras do projeto nunca nomeiam este skill.
• Autocontido exceto pelo mapa bundle↔live acima, que executa apenas no repositório mestre para check/promote.

exemplos

✅ scan encontra package.json com script "dev" → propõe módulo runtime → passo 5 escreve
   general/local-runtime.md + anexa "servidor dev autoexecutável → MUST Read ..." ao CLAUDE.md
❌ implantar módulo runtime sem sinal de scan e sem confirmação na entrevista (módulo adivinhado)

✅ /init-project check → "DISCREPÂNCIA: portable/rules/doc-organization.md != .claude/rules/doc-organization.md"
   → corrigir live primeiro → /init-project promote
❌ editar portable/* diretamente e então inicializar um novo projeto (bundle diverge silenciosamente do live)

arquivos de referência

• bundle: ./portable/**
• templates: ./templates/**
• versão: ./VERSION