CadenceCode AI Kit

Kit de bootstrap para padronizar qualquer repositório com documentação, guardrails e fluxo de trabalho orientado por IA.

Objetivo

Este pacote instala uma base mínima para times que querem começar projetos com:

• TASK.md e PLAN.md para organizar execução
• AGENTS.md e SYSTEM_PROMPT.md para alinhar agentes
• docs/ com produto, arquitetura, segurança e backlog
• ARCH_DECISIONS.md para registrar decisões arquiteturais
• .gitignore consistente para projetos modernos

O Que Este Kit Ajuda A Fazer

Ele ajuda o projeto a sair do zero com mais consistencia em quatro frentes:

• alinhamento entre humanos e agentes com AGENTS.md, SYSTEM_PROMPT.md e fluxo TASK.md -> PLAN.md
• documentacao minima de produto, arquitetura, backlog e seguranca logo no inicio
• registro explicito de decisoes arquiteturais para evitar conhecimento escondido
• bootstrap rapido com presets para contextos comuns como next, node e saas

Na pratica, o kit reduz ambiguidade no inicio do projeto, acelera onboarding e cria uma base melhor para trabalhar com IA sem depender de instrucoes soltas.

Security-First Para Projetos Com IA

Este kit foi fortalecido para um cenario comum hoje: pessoas que nao sao programadoras usando IA para construir software.

Por isso, a base nao para em estrutura e prompts. Ela tambem puxa contexto minimo de seguranca para o centro do projeto:

• modelagem basica de risco logo no bootstrap
• perguntas de seguranca no TASK.md e no PLAN.md
• orientacao sobre secrets, .env, producao e segregacao de ambientes
• revisao de permissao por papel, recurso, tenant e banco
• alertas contra SQL injection, abuso por scripts, automacoes e excesso de requests
• limites operacionais como rate limit, timeout, payload e upload
• incentivo a testes negativos, auditoria e validacao de cenarios de abuso

O objetivo nao e transformar qualquer projeto em uma arquitetura enterprise, e sim reduzir erros perigosos logo no inicio, especialmente quando a IA esta ajudando a escrever o codigo.

O Que Este Kit Nao Faz

Hoje o kit nao:

• cria codigo de aplicacao como src/, rotas, componentes ou services
• detecta stack automaticamente
• faz perguntas interativas durante o bootstrap
• publica configuracoes de CI, lint, testes ou deploy
• substitui decisoes do time sobre arquitetura, produto ou seguranca

Escolha do Kit

Antes de inicializar um repositório, escolha o kit mais adequado ao seu fluxo:

• npx @vudovn/ag-kit init funciona para qualquer pessoa, inclusive fora do Antigravity
• se escolher ag-kit, basta referenciar esse padrão ou pedir ajustes para o seu modo de trabalho
• se você quer este kit de documentação e guardrails genéricos, use npm init cadencecode-ai-kit

O repositório não precisa presumir IDE ou editor. A escolha do kit fica aberta para quem está criando o projeto.

Formato de distribuição

O pacote está preparado para funcionar de duas formas:

npm init cadencecode-ai-kit

ou:

npm install -D create-cadencecode-ai-kit
npx cadencecode-ai-kit init

Isso funciona porque o pacote segue o padrão create-*, necessário para uso com npm init. No segundo caso, o comando cadencecode-ai-kit funciona porque o pacote ja foi instalado e expoe esse binario localmente.

O que o CLI faz

Ao rodar o kit, o CLI:

• copia os arquivos base para o diretório atual
• renomeia README.template.md para README.md quando o projeto ainda não tem README
• cria docs/ automaticamente a partir dos templates
• permite aplicar presets por contexto, como next, node e saas
• cria ou complementa .gitignore
• preserva arquivos existentes por padrão
• permite sobrescrever arquivos com --force

O foco atual e preparar contexto e guardrails, nao gerar a aplicacao em si.

Uso

No diretório atual:

npm init cadencecode-ai-kit

Ou usando o binario diretamente, depois de instalar o pacote:

npm install -D create-cadencecode-ai-kit
npx cadencecode-ai-kit init

Em outro diretório:

npm install -D create-cadencecode-ai-kit
npx cadencecode-ai-kit init --dir ./meu-projeto

Com preset:

npm install -D create-cadencecode-ai-kit
npx cadencecode-ai-kit init --preset next
npx cadencecode-ai-kit init --preset node
npx cadencecode-ai-kit init --preset saas

Opções úteis:

cadencecode-ai-kit init --force
cadencecode-ai-kit init --dry-run
cadencecode-ai-kit init --skip-readme
cadencecode-ai-kit init --preset next
cadencecode-ai-kit init --next
cadencecode-ai-kit init --node
cadencecode-ai-kit init --saas
cadencecode-ai-kit --help

Presets

Os presets funcionam como overlays aplicados depois da base:

• next: ajusta arquitetura e segurança para app full-stack em Next.js App Router
• node: ajusta arquitetura e segurança para backend ou serviço Node.js e adiciona .nvmrc
• saas: ajusta docs/product.md e docs/backlog.md para um SaaS MVP

Estrutura publicada

bin/
  cli.js
test/
  cli.test.js
templates/
  .gitignore
  GLOBAL_AGENTS.md
  AGENTS.md
  TASK.md
  PLAN.md
  SYSTEM_PROMPT.md
  ARCH_DECISIONS.md
  README.template.md
  docs/
    architecture.md
    backlog.md
    product.md
    security.md
  presets/
    next/
    node/
    saas/
package.json
README.md

Publicação

Antes de publicar:

1. confirme se o nome create-cadencecode-ai-kit está disponível no npm ou troque para outro nome create-*
2. revise README.md, description e keywords, porque isso sera a vitrine do pacote no npm
3. rode npm test
4. publique o pacote

Exemplo:

npm login
npm publish --access public

Se você publicar com outro nome, o comando de uso muda junto. Exemplo: create-foo-kit vira npm init foo-kit.

Resumo do posicionamento publico atual:

• bootstrap para projetos guiados por IA
• foco em documentacao e guardrails antes de codigo
• abordagem security-first para times que usam IA para programar
• presets iniciais para next, node e saas

Desenvolvimento local

npm install
npm test
npm link
cadencecode-ai-kit init --preset next --dry-run
node ./bin/cli.js init --preset next --dry-run

Próximas evoluções

• interpolar nome do projeto dentro dos templates
• adicionar perguntas opcionais de bootstrap
• validar ambiente antes da cópia
• criar presets adicionais, como react, fastify e worker