Instalação

Não há nada para instalar para começar um projeto. ai-core-kit é um padrão forkável, não uma dependência que você adiciona a um arquivo de pacotes. Você cria um projeto novo em folha diretamente dos templates congelados do kit — sem precisar de fork — com um único comando.

Esta página cobre os pré-requisitos e os dois pontos de entrada equivalentes. O Início rápido percorre uma execução completa de ponta a ponta.

Pré-requisitos

Você precisa de muito pouco. O motor de render é determinístico e leve em dependências por design.

Essa é a lista inteira. Não há pip install, nenhuma toolchain Node para construir um filho, e nenhum LLM no loop de render — as mesmas respostas sempre produzem o mesmo projeto. O Python 3 é necessário apenas em tempo de execução se você optou pelo hook do portão de contrato ou pelo agregador de telemetria; você não precisa dele só para fazer o scaffold.

O kit deliberadamente evita um pré-requisito de “runtime Python + dependências em toda máquina” — exatamente por isso ele não usa copier/cookiecutter. Veja Motor de render.

Os dois pontos de entrada (escolha um)

Ambos rodam a mesma entrevista que começa pelo arquétipo e escrevem o mesmo project.manifest.yaml. Diferem apenas em onde você responde às perguntas.

A. npx @arthurghz/create-ack — CLI sem fork (recomendado)

O caminho principal. Inicia um projeto filho autônomo a partir dos templates congelados — sem fork, sem cópia da árvore .claude/ da META, sem LLM no loop.

# faz o scaffold de um novo projeto em ./my-product/
npx @arthurghz/create-ack@latest my-product --archetype fullstack

Fixe @latest para que cada execução baixe a CLI publicada mais nova. Prefere instalada? npm i -g @arthurghz/create-ack@latest coloca um binário create-ack no seu PATH, e create-ack update verifica sozinho se há uma versão mais nova. A CLI é a espinha dorsal — o scaffold e toda visão de telemetria vivem atrás dela (veja Comandos).

<product-name> deve ser kebab-case minúsculo (^[a-z][a-z0-9-]*$). Flags úteis (todas reais — veja create-ack --help):

Omita --archetype (e os outros presets) para ser perguntado interativamente sobre cada um.

B. Fork + /ack-init — a entrevista dentro do Claude

O equivalente conversacional para quem já está trabalhando dentro do Claude Code. Faça o fork do kit, abra o fork e execute o slash command:

# depois de fazer o fork do ai-core-kit no GitHub:
git clone https://github.com/<you>/<your-new-project>.git
cd <your-new-project>
# então, dentro do Claude Code:
/ack-init

/ack-init conduz a entrevista idêntica de forma conversacional e renderiza no mesmo repositório. Depois que ele roda, o scaffold, a ferramenta .claude/ e o project.manifest.yaml vivem nesse repositório — você nunca copia arquivos do kit à mão.

Qual devo usar? Prefira npx @arthurghz/create-ack — é sem fork, mais rápido e o caminho canônico. Recorra ao /ack-init quando você quiser especificamente que a entrevista rode dentro de uma sessão do Claude Code (ou você já fez o fork do kit).

A guarda fail-closed

Ambos os pontos de entrada recusam fazer scaffold sobre o próprio kit. O create-ack detecta os sentinelas da META (templates/archetypes/, docs/BOOTSTRAP.md, bootstrap/ack.bootstrap.yaml) e um project.manifest.yaml pré-existente, e aborta antes de escrever qualquer coisa; o /ack-init recusa de forma rígida se rodado no repositório ai-core-kit original.

Esta é a metade fail-closed em tempo de autoria do modelo de segurança do kit: um estado inicial inválido aborta antes de um único byte ser escrito (invariante I6). A metade de runtime é fail-open — um manifesto corrompido ou ausente no momento do consumo rebaixa o portão de contrato para o modo off e nunca trava uma sessão.

Próximo

Você tem o Node ≥ 18 (e, opcionalmente, o Claude Code / Python 3). Continue para o Início rápido para rodar a entrevista e ver o que chega primeiro: as specs.