Arrocha

CLI para preparar projetos com instruções, skills e fluxos de trabalho para:

• OpenAI Codex
• Claude Code
• GitHub Copilot
• OpenSpec

O Arrocha cria uma base padronizada para agentes de IA trabalharem no projeto seguindo as mesmas regras técnicas, visuais e operacionais.

Instalação

Instale globalmente pelo npm:

npm install -g @diegorivelino/arrocha

Confirme a instalação:

arrocha

Para verificar a versão instalada:

npm list -g @diegorivelino/arrocha --depth=0

Uso rápido

Entre na pasta do projeto:

cd caminho/do/projeto

Inicialize o Arrocha:

arrocha init

Valide a instalação:

arrocha doctor

O que o arrocha init faz

O comando:

arrocha init

configura o projeto atual e cria os arquivos que ainda não existem.

Ele não sobrescreve arquivos existentes por padrão.

Também:

• instala as skills locais do Codex;
• instala as skills locais do Claude;
• instala as skills globais do Codex;
• instala as skills globais do Claude;
• instala o OpenSpec, quando necessário;
• inicializa o OpenSpec para Codex e Claude.

Estrutura criada

AGENTS.md
CLAUDE.md

.github/
└── copilot-instructions.md

.arrocha/
├── RULES.md
├── DESIGN.md
└── COMMANDS.md

.agents/
└── skills/

.claude/
└── skills/

.codex/

openspec/

Arquivos de instrução

AGENTS.md

Arquivo principal de instruções para o Codex.

Define:

• regras de resposta;
• forma de trabalhar no projeto;
• uso das skills;
• prioridades técnicas;
• uso do OpenSpec;
• arquivos obrigatórios de referência.

CLAUDE.md

Arquivo principal de instruções para o Claude Code.

Define:

• comportamento padrão;
• uso das skills em .claude/skills;
• prioridades técnicas;
• fluxo com OpenSpec;
• leitura das regras do projeto.

.github/copilot-instructions.md

Arquivo de instruções para o GitHub Copilot.

Orienta o Copilot a:

• respeitar os padrões do projeto;
• seguir as regras do Arrocha;
• manter consistência com Codex e Claude;
• preservar arquitetura, segurança e padrões visuais;
• consultar os arquivos em .arrocha.

.arrocha/RULES.md

Fonte principal das regras do sistema e do projeto.

Pode conter:

• regras de arquitetura;
• segurança;
• permissões;
• banco de dados;
• migrations;
• padrões de implementação;
• integrações;
• regras de negócio;
• restrições do projeto.

.arrocha/DESIGN.md

Fonte principal das regras visuais.

Pode conter:

• cores;
• tipografia;
• espaçamento;
• componentes;
• responsividade;
• dashboards;
• formulários;
• tabelas;
• modais;
• drawers;
• padrões de navegação.

.arrocha/COMMANDS.md

Documenta os comandos oficiais do projeto.

Exemplos:

• instalação;
• execução;
• testes;
• lint;
• banco de dados;
• build;
• deploy;
• tarefas recorrentes.

Skills instaladas

O Arrocha instala as seguintes skills:

rails8
rails-code-audit
frontend-layout
design-system-review
npm-cli-dev
openspec-workflow
pure-ruby
electron-react
caveman

rails8

Para desenvolvimento moderno em Ruby on Rails.

Use para:

• models;
• controllers;
• migrations;
• jobs;
• services;
• Hotwire;
• testes;
• padrões Rails 8.

rails-code-audit

Para auditoria técnica de projetos Rails.

Use para:

• segurança;
• N+1;
• migrations;
• arquitetura;
• qualidade;
• performance;
• testes;
• riscos técnicos.

frontend-layout

Para criação e melhoria de interfaces.

Use para:

• layout;
• UI;
• responsividade;
• formulários;
• dashboards;
• ERB;
• Hotwire;
• React;
• Tailwind.

A skill deve consultar:

.arrocha/DESIGN.md

design-system-review

Para revisão de consistência visual.

Use para:

• cores;
• espaçamento;
• tipografia;
• componentes duplicados;
• responsividade;
• acessibilidade;
• padronização visual.

npm-cli-dev

Para desenvolvimento e manutenção de CLIs npm.

Use para:

• package.json;
• campo bin;
• comandos;
• templates;
• publicação;
• npm link;
• versionamento;
• instalação global.

openspec-workflow

Para mudanças guiadas por especificação.

Use para:

• proposals;
• specs;
• tasks;
• validações;
• mudanças estruturais;
• novas funcionalidades;
• refactors grandes.

pure-ruby

Para projetos Ruby sem Rails.

Use para:

• scripts;
• gems;
• CLIs;
• bibliotecas;
• automações;
• Ruby standard library.

electron-react

Para aplicações desktop com Electron e React.

Use para:

• Electron;
• React;
• Vite;
• IPC;
• preload;
• segurança;
• empacotamento;
• aplicações desktop.

caveman

Skill padrão para respostas muito compactas.

Use para:

• reduzir tokens de saída;
• eliminar explicações desnecessárias;
• responder de forma direta;
• manter comandos, código, caminhos e erros intactos;
• trabalhar em modo técnico e objetivo.

O comportamento exato depende das instruções presentes em:

.agents/skills/caveman/SKILL.md
.claude/skills/caveman/SKILL.md

Onde as skills são instaladas

Skills locais do Codex

.agents/skills/

Skills locais do Claude

.claude/skills/

Skills globais do Codex

~/.agents/skills/

Skills globais do Claude

~/.claude/skills/

As skills locais pertencem ao projeto. As skills globais ficam disponíveis para outros projetos do usuário.

Comandos disponíveis

Ajuda

arrocha

ou:

arrocha help

Inicializar projeto

arrocha init

Cria os arquivos ausentes sem sobrescrever os existentes.

Verificar instalação

arrocha doctor

Verifica se os principais arquivos, pastas, skills e OpenSpec estão disponíveis.

Listar skills

arrocha skill list

Instalar todas as skills

arrocha skill install-all

Atualizar arquivos do projeto

arrocha update

Cria arquivos ausentes sem sobrescrever arquivos existentes.

Atualizar e sobrescrever

arrocha update --force

Esse comando:

• atualiza arquivos existentes;
• cria arquivos ausentes;
• sobrescreve instruções antigas;
• atualiza templates do projeto;
• atualiza skills locais.

Use com cuidado.

Diferença entre init e update

arrocha init

cria arquivos ausentes
mantém arquivos existentes
instala skills
configura OpenSpec

arrocha update

cria arquivos ausentes
mantém arquivos existentes
atualiza apenas o que não exige sobrescrita

arrocha update --force

cria arquivos ausentes
sobrescreve arquivos existentes
atualiza instruções
atualiza templates
atualiza skills locais

Atualizar um projeto existente

Atualize o Arrocha global:

npm install -g @diegorivelino/arrocha@latest
hash -r

Entre no projeto:

cd caminho/do/projeto

Confira as alterações pendentes:

git status

Faça um backup antes de sobrescrever:

git add .
git commit -m "Backup antes de atualizar Arrocha"

Atualize:

arrocha update --force

Valide:

arrocha doctor

GitHub Copilot

O Arrocha cria:

.github/copilot-instructions.md

Esse arquivo deve ser versionado no Git e mantém o Copilot alinhado com Codex e Claude.

OpenSpec

O Arrocha verifica se o comando openspec está instalado.

Quando necessário, instala:

npm install -g @fission-ai/openspec@latest

Depois inicializa:

openspec init --tools claude,codex

O fluxo recomendado é usar OpenSpec para:

• novas funcionalidades;
• mudanças de comportamento;
• refactors grandes;
• alterações estruturais;
• mudanças com impacto em regras de negócio.

Uso com Codex

O Codex deve consultar:

AGENTS.md
.arrocha/RULES.md
.arrocha/DESIGN.md
.arrocha/COMMANDS.md
.agents/skills/

Exemplos:

$rails8 crie o cadastro de clientes seguindo as regras do projeto

$rails-code-audit revise segurança, migrations e consultas N+1

$frontend-layout melhore esta tela seguindo .arrocha/DESIGN.md

$caveman explique somente o erro e a correção

Uso com Claude Code

O Claude deve consultar:

CLAUDE.md
.arrocha/RULES.md
.arrocha/DESIGN.md
.arrocha/COMMANDS.md
.claude/skills/

Exemplos:

/rails8 implemente esta feature seguindo o padrão do projeto

/rails-code-audit revise este módulo

/frontend-layout ajuste esta tela seguindo .arrocha/DESIGN.md

/caveman responda somente com a solução

Desenvolvimento local do Arrocha

Entre no projeto-fonte:

cd ~/projetos/Arrocha-CLI

Crie o link global para desenvolvimento:

npm link

Teste:

arrocha
arrocha skill list

Crie uma pasta temporária:

rm -rf /tmp/teste-arrocha
mkdir -p /tmp/teste-arrocha
cd /tmp/teste-arrocha

Inicialize e valide:

arrocha init
arrocha doctor
ls -la

Confira o Copilot:

ls -la .github
cat .github/copilot-instructions.md

Estrutura do pacote

Arrocha-CLI/
├── bin/
│   └── arrocha.js
├── src/
│   ├── fs-utils.js
│   └── skills.js
├── templates/
│   ├── project/
│   │   ├── AGENTS.md
│   │   ├── CLAUDE.md
│   │   ├── .github/
│   │   │   └── copilot-instructions.md
│   │   └── .arrocha/
│   │       ├── RULES.md
│   │       ├── DESIGN.md
│   │       └── COMMANDS.md
│   └── skills/
│       ├── rails8/
│       ├── rails-code-audit/
│       ├── frontend-layout/
│       ├── design-system-review/
│       ├── npm-cli-dev/
│       ├── openspec-workflow/
│       ├── pure-ruby/
│       ├── electron-react/
│       └── caveman/
├── package.json
└── README.md

Configuração do package.json

O campo bin deve usar um caminho relativo válido:

{
  "bin": {
    "arrocha": "./bin/arrocha.js"
  }
}

O arquivo precisa ser executável:

chmod +x bin/arrocha.js

A primeira linha de bin/arrocha.js deve ser:

#!/usr/bin/env node

Testar antes de publicar

Corrija o package.json:

npm pkg fix

Confira o pacote:

npm pack --dry-run

Verifique se aparecem, entre outros:

bin/arrocha.js
templates/project/AGENTS.md
templates/project/CLAUDE.md
templates/project/.github/copilot-instructions.md
templates/project/.arrocha/RULES.md
templates/skills/caveman/SKILL.md
README.md

Teste o CLI:

node bin/arrocha.js
node bin/arrocha.js skill list

Publicação

Faça login no npm:

npm login

Confirme:

npm whoami

Atualize a versão:

npm version patch

Outras opções:

npm version minor
npm version major

Publique:

npm publish --access public

Não é possível publicar novamente a mesma combinação de nome e versão.

Atualizar a instalação global

npm uninstall -g @diegorivelino/arrocha
npm install -g @diegorivelino/arrocha@latest
hash -r

Teste:

arrocha
arrocha skill list

Desinstalação

Remova o pacote global:

npm uninstall -g @diegorivelino/arrocha

Para remover os arquivos do Arrocha de um projeto:

rm -rf AGENTS.md CLAUDE.md .arrocha .agents .claude .codex openspec
rm -f .github/copilot-instructions.md

Atenção: esses comandos apagam arquivos e pastas do projeto.

Solução de problemas

arrocha: command not found

npm uninstall -g @diegorivelino/arrocha
npm install -g @diegorivelino/arrocha@latest
hash -r

Confira:

which arrocha

ENEEDAUTH

npm login
npm whoami
npm publish --access public

O npm removeu o campo bin

Garanta que o package.json contém:

{
  "bin": {
    "arrocha": "./bin/arrocha.js"
  }
}

Depois:

npm pkg fix
chmod +x bin/arrocha.js
npm pack --dry-run

Pastas ocultas não aparecem

Use:

ls -la

A atualização não alterou os arquivos

Use:

arrocha update --force

Boas práticas

• versione os arquivos do Arrocha no Git;
• faça commit antes de usar --force;
• mantenha .arrocha/RULES.md como fonte principal de regras;
• mantenha .arrocha/DESIGN.md atualizado;
• documente testes e lint em .arrocha/COMMANDS.md;
• use OpenSpec para mudanças grandes;
• execute npm pack --dry-run antes de publicar;
• mantenha Codex, Claude e Copilot alinhados.

Licença

MIT