AI System Bootstrapper

Bootstrap universal para instalar a estrutura .ai/ em um workspace e conectar Codex, Claude Code e Gemini ao mesmo sistema de regras, hooks, runtime e skills.

Use este pacote quando quiser inicializar um workspace com:

• entrypoints mínimos: AGENTS.md, CLAUDE.md, GEMINI.md
• fonte de verdade em .ai/
• hooks em TypeScript, sem wrapper shell
• seletor interativo de idioma (pt-BR ou en)
• skills base: as-maker, prd, humanizer

Comece Aqui

Na pasta que deve receber o AI System:

npx -y -p ai-system-bootstrapper@latest ai-system-bootstrapper --runtimes all

Para atualizar um workspace existente com a versão mais nova:

npx -y -p ai-system-bootstrapper@latest ai-system-bootstrapper \
  --target /path/do/workspace \
  --runtimes all \
  --force

Nao Use npm i

O npm mostra um card padrão com:

npm i ai-system-bootstrapper

Esse comando só instala o pacote como dependência. Ele não roda o bootstrap.

Use sempre npx:

npx -y -p ai-system-bootstrapper@latest ai-system-bootstrapper --runtimes all

Como Funciona

┌─────────────────────────────┐
│ npx ai-system-bootstrapper  │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│ Seletor de idioma           │
│ pt-BR ou en                 │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│ Templates base + locale     │
│ templates/base              │
│ templates/locales/en        │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│ Workspace alvo              │
│ AGENTS.md / CLAUDE.md       │
│ .ai/                        │
│ .codex / .claude / .gemini  │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│ Runtime hooks               │
│ SessionStart                │
│ UserPromptSubmit            │
│ PreToolUse                  │
└─────────────────────────────┘

Tela Inicial

Em terminal interativo, o CLI mostra a versão, o destino e os runtimes antes de pedir o idioma:

AI System Bootstrapper v0.2.17
Target: /path/do/workspace
Runtimes: codex, claude, gemini
Mode: write

Choose AI System language
Use arrow keys or j/k, then press Enter. Press 1 or 2 for quick select.

> pt-BR Portugues do Brasil selected
  en    English

Se --language for passado, o prompt interativo é pulado.

O Que Ele Instala

| Arquivo | Localização | Função | |---|---|---| | AGENTS.md | raiz | Entry point mínimo para Codex. | | CLAUDE.md | raiz | Entry point mínimo para Claude Code. | | GEMINI.md | raiz | Entry point mínimo para Gemini. | | *.json | .ai/rules/ | Regras universais de workspace, routing e workflow. | | load-rules.ts | .ai/hooks/ | Hook de SessionStart; injeta contexto universal literal. | | user-prompt-submit.ts | .ai/hooks/ | Dispatcher de skills e comandos >> / *. | | enforce-as-maker.ts | .ai/hooks/ | Gate para alterações diretas em skills e agents. | | skill-state.ts | .ai/runtime/ | Biblioteca que lê/grava estado da skill ativa. | | update-check.ts | .ai/runtime/ | Aviso de update do pacote quando configurado. | | SKILL.md, skill.json, tasks/, rules/ | .ai/skills/as-maker/ | Skill para criar, atualizar, validar e migrar skills/agents. | | SKILL.md, skill.json, tasks/, rules/ | .ai/skills/prd/ | Skill para criação de PRDs e scaffold documental. | | SKILL.md, skill.json, tasks/, rules/, references/ | .ai/skills/humanizer/ | Skill para humanização editorial com segurança factual. | | config.toml | .codex/ | Config nativa do Codex apontando para os hooks .ai/. | | settings.json | .claude/ | Config nativa do Claude Code apontando para os hooks .ai/. | | settings.json | .gemini/ | Config nativa do Gemini apontando para os hooks .ai/. |

Skills Base

| Skill | Ativação | Uso | |---|---|---| | as-maker | >>as-maker | Criar, atualizar, auditar, validar e migrar skills/agents. | | prd | >>prd | Criar PRDs com Scope OUT e decisão de stack. | | humanizer | >>humanizer | Humanizar textos preservando fatos, SEO, tom e evidências. |

Separação de comandos:

>>humanizer     ativa ou troca a skill
*quick          executa uma task dentro da skill ativa
texto *humanize executa a task dentro da skill ativa usando o texto como entrada
*status         mostra skill ativa e sessão
*off            desativa a skill persistente

No SessionStart, o hook injeta literalmente as regras universais e os arquivos de sistema. Quando uma skill é ativada, o hook injeta o contrato base. Quando uma task é chamada com *, o hook injeta o conteúdo necessário para aquela operação.

O estado da skill ativa fica em:

.ai/state/skills/<session-id>/state.json

Bundles auditáveis são opcionais e só são gravados quando AI_SYSTEM_DEBUG=1:

.ai/state/context-bundles/

Idiomas

O bootstrap tem dois modos:

• pt-BR: usa templates/base.
• en: aplica templates/locales/en por cima dos arquivos textuais.

Para JSONs, templates/base é o contrato estrutural. O locale mantém apenas overrides de strings em templates/locales/en/_translations.json; os arquivos JSON finais do locale são gerados por npm run locales:sync.

Isso evita tradução automática por substituição de palavras e mantém os mesmos paths, chaves, arrays e contratos nos dois idiomas.

Comandos

Instalar no diretório atual:

npx -y -p ai-system-bootstrapper@latest ai-system-bootstrapper --runtimes all

Instalar em outro diretório:

npx -y -p ai-system-bootstrapper@latest ai-system-bootstrapper \
  --target /path/do/workspace \
  --runtimes all

Instalar sem prompt interativo:

npx -y -p ai-system-bootstrapper@latest ai-system-bootstrapper \
  --runtimes all \
  --language pt-BR

npx -y -p ai-system-bootstrapper@latest ai-system-bootstrapper \
  --runtimes all \
  --language en

Ver plano sem escrever:

npx -y -p ai-system-bootstrapper@latest ai-system-bootstrapper \
  --dry-run \
  --runtimes all

Atualizar workspace existente:

npx -y -p ai-system-bootstrapper@latest ai-system-bootstrapper \
  --target /path/do/workspace \
  --runtimes all \
  --force

Opções

| Opção | Uso | |---|---| | --target <path> | Diretório alvo. Default: diretório atual. | | --dry-run | Mostra o plano sem escrever arquivos. | | --force | Atualiza conflitos criando backup .bak.<timestamp>. | | --runtimes <value> | auto, all, none ou lista codex,claude,gemini. | | --with-gemini | Inclui Gemini além da seleção atual. | | --language <pt-BR\|en> | Define idioma sem prompt interativo. | | --quiet | Reduz output do instalador. | | --self-test | Instala em diretório temporário e valida idempotência. |

Ciclos De Vida

Instalação inicial:

Usuário
  │
  │ npx -p ai-system-bootstrapper@latest ai-system-bootstrapper
  ▼
CLI
  │
  ├─ resolve target/runtimes
  ├─ seleciona idioma
  ├─ renderiza templates
  ├─ cria arquivos ausentes
  └─ preserva conflitos
       │
       ▼
Workspace com AI System instalado

Inicio de sessão:

SessionStart
  │
  ├─ injeta .ai/rules/*.json literalmente
  ├─ injeta .ai/system/config.json literalmente
  └─ injeta .ai/system/manifest.json literalmente

Uso de skill:

Usuário
  │
  │ >>humanizer
  ▼
UserPromptSubmit
  │
  ├─ ativa estado persistente da skill
  ├─ grava estado em .ai/state
  └─ injeta contrato base
       │
       ▼
Sessão passa a operar com humanizer
  │
  │ *quick
  ▼
Hook injeta task + referências necessárias

Idempotência

• Arquivo inexistente: criado.
• Arquivo igual ao template: ignorado.
• Arquivo divergente: conflito, não sobrescreve.
• Com --force: cria backup antes de atualizar.

Esse comportamento permite rodar o bootstrap novamente sem apagar trabalho local por acidente.

Dependências

• Node.js >=22
• Codex, Claude Code ou Gemini CLI se quiser instalar configs desses runtimes

Os hooks chamam TypeScript direto via Node:

node --experimental-strip-types .ai/hooks/load-rules.ts
node --experimental-strip-types .ai/hooks/enforce-as-maker.ts
node --experimental-strip-types .ai/hooks/user-prompt-submit.ts

Desenvolvimento

Validar o pacote:

npm run validate

Sincronizar JSONs de locale depois de editar traduções:

npm run locales:sync

Checar se os locales continuam iguais ao contrato base:

npm run locales:check

Rodar localmente:

node --experimental-strip-types src/cli.ts \
  --target /tmp/ai-system-demo \
  --runtimes all

Publicar no npm:

npm publish --access public