BRX AI Dev Installer

Instalador oficial do BRX AI Dev Workflow.

Este pacote fornece uma CLI cross-platform para iniciar, configurar, validar e organizar projetos da BRX com desenvolvimento assistido por IA.

Compatível com:

• Windows
• Linux
• macOS
• WSL
• Git Bash
• PowerShell
• Terminal Unix

Visão geral

O brx-ai-dev-installer é responsável por automatizar a criação e configuração de projetos baseados no template oficial da BRX:

brx-ai-dev-template

A ideia é permitir que qualquer projeto novo da BRX já comece com:

• estrutura padrão de documentação;
• arquivos de contexto para agentes;
• BMAD configurado;
• Spec Kit configurado para Claude Code;
• Agent Deck com sessões padrão;
• OpenCode com agentes auxiliares;
• validações básicas do projeto;
• workflow documentado.

Stack do workflow BRX

O instalador prepara o projeto para trabalhar com:

| Ferramenta | Função | |---|---| | Cursor | Editor visual e controle humano | | BMAD | Método macro: visão, PRD, arquitetura, épicos e stories | | Spec Kit | Especificação por feature: spec, plan, tasks e implement | | Gemini CLI | Planejamento, arquitetura e leitura ampla | | Claude Code | Implementação principal | | Codex | Revisão técnica | | Agent Deck | Gerenciamento de sessões de agentes | | OpenCode | Agentes auxiliares, documentação e auditoria |

Diferença entre template e instalador

A BRX usa dois repositórios separados:

brx-ai-dev-template
brx-ai-dev-installer

brx-ai-dev-template

É o repositório base usado para criar novos projetos.

Ele contém:

• AGENTS.md
• CLAUDE.md
• GEMINI.md
• CODEX.md
• docs/brx/*
• opencode.json
• .opencode/agent/*
• .agent-deck/*
• .github/*
• scripts auxiliares
• estrutura inicial de pastas

brx-ai-dev-installer

É este repositório.

Ele contém a CLI que automatiza:

• criação de projeto a partir do template;
• instalação do BMAD;
• inicialização do Spec Kit;
• criação de sessões no Agent Deck;
• validação do ambiente;
• validação da estrutura do projeto.

Instalação

Durante o desenvolvimento local do instalador:

npm install
npm link

Depois disso, o comando ficará disponível localmente:

brx-ai-dev help

Depois de publicado no npm, o uso recomendado será:

npx @brxlabs/brx-ai-dev@latest help

Requisitos

Para usar o workflow completo, o ambiente deve ter:

| Ferramenta | Obrigatória? | Uso | |---|---:|---| | Node.js 18+ | Sim | Executar o instalador | | Git | Sim | Controle de versão | | GitHub CLI (gh) | Sim para new | Criar repositórios a partir do template | | uvx / uv | Sim para Spec Kit | Inicializar Spec Kit | | Gemini CLI | Recomendado | Planejamento | | Claude Code | Recomendado | Implementação | | Codex CLI | Recomendado | Revisão | | Agent Deck | Recomendado | Sessões | | OpenCode | Recomendado | Agentes auxiliares |

Comandos disponíveis

brx-ai-dev new <nome-do-projeto> [--private|--public] [--owner brxlabs]
brx-ai-dev install [--yes]
brx-ai-dev agentdeck
brx-ai-dev doctor
brx-ai-dev verify
brx-ai-dev help

Criar um projeto novo

Use:

npx @brxlabs/brx-ai-dev@latest new crm-brx --private

Esse comando cria um novo repositório no GitHub a partir do template:

brxlabs/brx-ai-dev-template

Exemplo com owner customizado:

npx @brxlabs/brx-ai-dev@latest new crm-brx --private --owner brxlabs

Exemplo público:

npx @brxlabs/brx-ai-dev@latest new crm-brx --public

Fluxo esperado:

1. Criar repositório a partir do template
2. Clonar repositório localmente
3. Entrar na pasta do projeto
4. Rodar instalação BRX
5. Inicializar BMAD
6. Inicializar Spec Kit
7. Criar sessões Agent Deck

Instalar o workflow em um projeto existente

Dentro de um projeto criado a partir do template:

npx @brxlabs/brx-ai-dev@latest install

Esse comando pode:

• criar pastas base;
• remover arquivos locais indesejados, como .DS_Store;
• instalar/inicializar BMAD;
• inicializar Spec Kit com integração Claude Code;
• validar estrutura do projeto;
• criar sessões no Agent Deck.

Modo sem perguntas interativas:

npx @brxlabs/brx-ai-dev@latest install --yes

Validar ambiente

Use:

npx @brxlabs/brx-ai-dev@latest doctor

Esse comando verifica se as ferramentas principais estão instaladas:

• Git
• Node.js
• npm
• npx
• uvx
• GitHub CLI
• Gemini CLI
• Claude Code
• Codex CLI
• Agent Deck
• OpenCode

Exemplo de saída esperada:

✅ Git
✅ Node.js
✅ npm
✅ npx
✅ uvx / uv
✅ GitHub CLI
✅ Gemini CLI
✅ Claude Code
✅ Codex CLI
✅ Agent Deck
✅ OpenCode

Criar sessões no Agent Deck

Use:

npx @brxlabs/brx-ai-dev@latest agentdeck

Esse comando cria quatro sessões padrão:

nome-do-projeto - Gemini Planner
nome-do-projeto - Claude Builder
nome-do-projeto - Codex Reviewer
nome-do-projeto - OpenCode Helper

Com grupo:

nome-do-projeto

Papéis das sessões

Gemini Planner

Responsável por:

• ler contexto amplo;
• validar arquitetura;
• analisar impacto;
• mapear riscos;
• sugerir plano técnico.

Claude Builder

Responsável por:

• implementar tasks aprovadas;
• seguir BMAD + Spec Kit;
• rodar validações;
• corrigir pontos levantados por revisão.

Codex Reviewer

Responsável por:

• revisar diffs;
• identificar bugs;
• validar segurança;
• revisar tipagem;
• checar aderência à spec;
• classificar revisão como aprovado, aprovado com ajustes ou bloqueado.

OpenCode Helper

Responsável por:

• atualizar documentação;
• auditar alinhamento BMAD + Spec Kit;
• dividir tasks grandes;
• ajudar com tarefas auxiliares.

Verificar estrutura do projeto

Use:

npx @brxlabs/brx-ai-dev@latest verify

Esse comando valida se o projeto possui os arquivos e pastas esperados:

• README.md
• AGENTS.md
• CLAUDE.md
• GEMINI.md
• CODEX.md
• opencode.json
• docs/brx
• specs
• _bmad-output
• .agent-deck
• .opencode

Também valida:

• se opencode.json é JSON válido;
• se os arquivos Markdown possuem fences pareadas;
• se a estrutura base do workflow existe.

Como funciona a integração BMAD + Spec Kit

O workflow BRX usa BMAD e Spec Kit juntos.

BMAD

BMAD é usado para a camada macro do projeto:

visão
↓
Product Brief
↓
PRD
↓
Arquitetura
↓
Épicos
↓
Stories
↓
Sprint Planning

Spec Kit

Spec Kit é usado para a execução por feature:

constitution
↓
specify
↓
clarify
↓
checklist
↓
plan
↓
tasks
↓
analyze
↓
implement

Hierarquia

BMAD manda no macro.
Spec Kit manda na execução da feature.
Gemini planeja.
Claude Code implementa.
Codex revisa.
Agent Deck organiza.
OpenCode auxilia.
Cursor aprova.

Comando usado para inicializar Spec Kit

O instalador usa:

uvx --from git+https://github.com/github/spec-kit.git specify init . --integration claude --script sh --force

Esse comando tem como objetivo:

• inicializar o Spec Kit no projeto atual;
• configurar a integração com Claude Code;
• permitir o uso dos comandos /speckit.*;
• usar scripts do tipo sh;
• executar sem confirmação interativa em diretório atual.

Comandos esperados dentro do Claude Code

Depois de inicializar o Spec Kit, o Claude Code deve reconhecer comandos como:

/speckit.constitution
/speckit.specify
/speckit.clarify
/speckit.checklist
/speckit.plan
/speckit.tasks
/speckit.analyze
/speckit.implement

Fluxo recomendado para projeto novo

npx @brxlabs/brx-ai-dev@latest new crm-brx --private
cd crm-brx
cursor .

Depois, no projeto:

npx @brxlabs/brx-ai-dev@latest doctor
npx @brxlabs/brx-ai-dev@latest verify

No Claude Code:

bmad-help

Depois seguir o fluxo BMAD:

bmad-brainstorming
bmad-product-brief
bmad-prd
bmad-create-ux-design
bmad-create-architecture
bmad-generate-project-context
bmad-create-epics-and-stories
bmad-check-implementation-readiness
bmad-sprint-planning

Para cada feature relevante:

/speckit.specify
/speckit.clarify
/speckit.checklist
/speckit.plan
/speckit.tasks
/speckit.analyze
/speckit.implement

Fluxo recomendado para projeto existente

Dentro da pasta do projeto:

npx @brxlabs/brx-ai-dev@latest install

Depois:

npx @brxlabs/brx-ai-dev@latest verify
npx @brxlabs/brx-ai-dev@latest agentdeck

Publicação no npm

Antes de publicar:

npm pack --dry-run

Validar se o pacote inclui apenas:

bin/
README.md
LICENSE
package.json

Fazer login:

npm login

Publicar:

npm publish --access public

Depois de publicado:

npx @brxlabs/brx-ai-dev@latest help
npx @brxlabs/brx-ai-dev@latest doctor

Desenvolvimento local

Clone o repositório:

git clone https://github.com/brxlabs/brx-ai-dev-installer.git
cd brx-ai-dev-installer

Instale/link localmente:

npm install
npm link

Teste:

brx-ai-dev help
brx-ai-dev doctor
brx-ai-dev verify

Estrutura do repositório

brx-ai-dev-installer/
├── bin/
│   └── brx-ai-dev.js
├── README.md
├── package.json
├── .gitignore
└── LICENSE

Comandos internos principais

new

Cria um novo projeto a partir do template BRX.

brx-ai-dev new crm-brx --private

install

Configura o workflow BRX em um projeto existente.

brx-ai-dev install

doctor

Verifica se as ferramentas necessárias estão instaladas.

brx-ai-dev doctor

agentdeck

Cria sessões padrão no Agent Deck.

brx-ai-dev agentdeck

verify

Verifica se a estrutura do projeto está correta.

brx-ai-dev verify

help

Mostra ajuda.

brx-ai-dev help

Segurança

O instalador deve evitar comandos destrutivos.

Ele pode remover apenas arquivos locais conhecidos e seguros, como:

.DS_Store
Thumbs.db
ehthumbs.db
Desktop.ini

O instalador não deve:

• apagar código do projeto;
• apagar .env;
• fazer commit automaticamente;
• fazer push automaticamente;
• publicar no npm automaticamente;
• executar comandos destrutivos sem confirmação.

Boas práticas

Antes de publicar uma nova versão:

node bin/brx-ai-dev.js help
node bin/brx-ai-dev.js doctor
node bin/brx-ai-dev.js verify
npm pack --dry-run

Depois:

npm version patch
npm publish --access public

Roadmap

Possíveis comandos futuros:

brx-ai-dev update
brx-ai-dev doctor --fix
brx-ai-dev init-feature nome-da-feature
brx-ai-dev prompts
brx-ai-dev audit

update

Atualizar arquivos do workflow BRX em projetos antigos.

doctor --fix

Corrigir automaticamente pequenos problemas, como permissões e arquivos locais indesejados.

init-feature

Criar estrutura inicial para uma feature em specs/.

prompts

Exibir prompts padrão para Gemini, Claude, Codex e OpenCode.

audit

Auditar o projeto contra o padrão BRX.

Licença

Uso interno da BRX Labs.

Resumo

O brx-ai-dev-installer é o instalador oficial do padrão de desenvolvimento assistido por IA da BRX.

Ele permite iniciar projetos com um comando:

npx @brxlabs/brx-ai-dev@latest new crm-brx --private

E manter o workflow consistente com:

npx @brxlabs/brx-ai-dev@latest install
npx @brxlabs/brx-ai-dev@latest doctor
npx @brxlabs/brx-ai-dev@latest verify
npx @brxlabs/brx-ai-dev@latest agentdeck