# AICoders Academy · Pi Extensions
Repositório open source oficial da **aicoders.academy** com extensões para a comunidade do [pi coding agent](https://github.com/earendil-works/pi-coding-agent).
> ⚠️ **Segurança:** extensões do pi executam código na sua máquina com as permissões do seu usuário. Instale apenas extensões de fontes confiáveis e revise o código antes de usar.
## Pré-requisitos
- Node.js e npm instalados.
- Pi coding agent instalado e disponível no terminal como `pi`.
- Git instalado para instalar direto deste repositório.
## Instalação rápida
Quando o repositório estiver publicado no GitHub, instale globalmente com:
```bash
pi install git:github.com/vinilana/pi-extensions-aicoders
```
Isso adiciona o pacote em `~/.pi/agent/settings.json` e deixa as extensões disponíveis em todos os projetos.
Para instalar apenas no projeto atual, use `-l`:
```bash
pi install -l git:github.com/vinilana/pi-extensions-aicoders
```
Isso grava em `.pi/settings.json`, permitindo versionar a configuração junto com o projeto.
## Testar sem instalar
Use `-e`/`--extension` para carregar temporariamente:
```bash
pi -e git:github.com/vinilana/pi-extensions-aicoders
```
Ou, após clonar o repositório:
```bash
git clone https://github.com/vinilana/pi-extensions-aicoders.git
cd pi-extensions-aicoders
pi -e .
```
## Instalar a partir de um clone local
```bash
git clone https://github.com/vinilana/pi-extensions-aicoders.git
pi install ./pi-extensions-aicoders
```
Para instalação local ao projeto:
```bash
pi install -l ./pi-extensions-aicoders
```
## Instalar uma extensão manualmente
Você também pode copiar arquivos `.ts` diretamente para os diretórios de auto-descoberta do pi.
Instalação global:
```bash
mkdir -p ~/.pi/agent/extensions
cp extensions/nome-da-extensao.ts ~/.pi/agent/extensions/
```
Instalação local no projeto:
```bash
mkdir -p .pi/extensions
cp extensions/nome-da-extensao.ts .pi/extensions/
```
Depois, reinicie o pi ou execute `/reload` dentro da sessão.
## Tema AICoders Claude
Este pacote também inclui o tema `aicoders-claude`, uma paleta escura,
minimalista e inspirada na experiência limpa do Claude Code.
Após instalar ou carregar o pacote, selecione o tema pelo menu interativo:
```bash
/settings
```
Ou configure diretamente no `settings.json` do pi:
```json
{
"theme": "aicoders-claude"
}
```
Para testar a partir de um clone local sem instalar:
```bash
pi -e .
```
Em seguida, abra `/settings` e escolha `aicoders-claude`.
## Atualizar, listar e remover
```bash
pi list
pi update --extensions
pi remove git:github.com/vinilana/pi-extensions-aicoders
```
## Estrutura do repositório
```text
.
├── extensions/ # Extensões TypeScript do pi
├── themes/ # Temas JSON para a TUI do pi
├── README.md # Documentação do projeto
└── package.json # Manifesto do pacote pi
```
O pi descobre extensões e temas a partir do manifesto `pi` em `package.json`, incluindo `pi.extensions` e `pi.themes`.
## Extensões disponíveis
### Context Feedforward
A extensão `context` cria e utiliza uma base `.context/` inspirada no dotcontext:
- `/dotcontext init` analisa a codebase e gera `docs`, `agents` e `skills` já preenchidos com módulos, contratos, fluxos e comandos detectados, preservando edições manuais;
- `/dotcontext status` mostra o estado da base local;
- `/dotcontext feed <tarefa>` simula quais documentos seriam carregados;
- antes de cada trabalho do agente, a extensão seleciona docs/playbooks/skills relevantes e injeta esse feedforward no prompt do turno.
Após criar `.context/skills`, execute `/reload` para o pi descobri-las também como skills nativas.
### Guardrails
A extensão `guardrails` adiciona confirmações explícitas antes de ações sensíveis:
- acesso ou alteração de `.env`/`.env.*`; a exceção liberada por padrão é `.env.example`;
- escrita em diretórios gerados ou internos como `dist/`, `build/`, `coverage/`, `node_modules/` e `.git/`;
- comandos destrutivos/sensíveis como `rm`, `rmdir`, `find -delete`, `sudo`, `chmod/chown`, `git clean/reset/restore`, redirecionamentos de escrita, builds com emissão e mutações de dependências.
Na confirmação interativa, a ação pode ser liberada uma vez, bloqueada ou marcada com **Sempre permitir esta ação**. A opção "sempre permitir" memoriza a decisão exata na sessão atual e libera automaticamente repetições iguais.
Use `/guardrails` para ver um resumo das regras durante a sessão, `/guardrails list` para listar permissões lembradas e `/guardrails clear` para limpar a memória. Sem UI disponível para confirmar e sem permissão lembrada, a ação é bloqueada por padrão.
### Judges
A extensão `judges` valida se uma tarefa realmente atende à SPEC inicial antes de ser considerada concluída:
- registra a ferramenta `judges_evaluate`, que compara `spec`, `result` e evidências;
- executa judges configuráveis por prompt e, opcionalmente, scripts/testes locais;
- retorna `passed`, pendências e uma `pendingSpec` para continuar o trabalho quando algo faltar;
- pode avaliar automaticamente respostas finais que alegam conclusão;
- integra com o PREVC na etapa **V**, antes de aceitar `mark_validated passed=true`.
Configuração opcional em `~/.pi/agent/judges.json`, `.pi/judges.json` ou `judges.config.json`:
```json
{
"enabled": true,
"model": "active",
"allowScripts": true,
"confirmScripts": true,
"auto": { "enabled": true, "mode": "claim", "onFail": "followUp" },
"judges": [
{
"id": "spec-compliance",
"promptFile": ".pi/judges/spec-compliance.md",
"scripts": [{ "name": "tests", "command": "npm test", "timeoutMs": 120000 }]
}
]
}
```
Por segurança, scripts configurados só rodam com `allowScripts=true` e podem exigir confirmação na UI. Use `/judges status` para inspecionar a configuração carregada.
### PREVC
A extensão `prevc` controla o workflow:
- **P** — Planejar
- **R** — Revisar/aprovar
- **E** — Executar uma fase por vez
- **V** — Validar com evidências e `judges_evaluate`
- **C** — Confirmar e commitar quando aplicável
A implementação oficial está em `extensions/prevc/` e registra:
- comando `/prevc`
- ferramenta `prevc_workflow`
- guardrails para limitar ferramentas por etapa
- integração com `judges_evaluate` na etapa V
- persistência do estado do workflow na sessão
Na etapa **P**, o agente deve apresentar uma **SPEC PREVC** detalhada com
objetivo, escopo, estado atual, requisitos, design técnico, artefatos,
etapas de execução, validações, critérios de aceite e riscos.
A spec também deve perguntar explicitamente:
> Você quer que eu gere um arquivo `.md` como output ao final?
Se a resposta for sim, o agente deve confirmar ou sugerir o caminho/nome do
arquivo Markdown. Se for não, deve registrar que não haverá artefato Markdown
final.
Uso básico:
```bash
/prevc start <objetivo>
/prevc status
/prevc approve
/prevc reject <motivo>
/prevc commit <mensagem>
/prevc stop
```
## Contribuindo
Contribuições da comunidade são bem-vindas. Antes de enviar uma extensão:
1. Coloque o arquivo em `extensions/`.
2. Documente como usar a extensão.
3. Evite segredos, tokens ou credenciais no código.
4. Teste com `pi -e .` antes de abrir um pull request.
## Licença
Este projeto será distribuído como open source. Defina a licença oficial antes da primeira release pública.
Leer el README original