embed-pi-cli

name	embed-pi-cli
description	Orienta a implementação de integração embedável do pi em projetos CLI externos. Use quando um projeto precisar distribuir configuração pi, publicar extensões customizadas ou invocar pi como subprocesso com governança.

Embed Pi CLI

Use este skill quando o objetivo for tornar um projeto CLI externo capaz de usar as capacidades do pi (orquestração, budget, observabilidade) sem forkar o agents-lab.

Escolha o modelo de integração

Antes de qualquer implementação, identifique qual modelo se aplica:

A — Config embedding (mais simples): o projeto só precisa de uma configuração pré-definida. Distribua .pi/settings.json no repositório.

B — Extension bundle (controle total): o projeto tem comportamentos customizados. Publique um pacote npm com extensões próprias.

C — Subprocess bridge (integração programática): o projeto orquestra pi de fora (CI, pipeline). Invoque pi como subprocesso e consuma sessões JSONL.

D — Message adapter (ex.: Telegram/Matrix/WhatsApp): canal externo envia comandos/steering para o control plane. Trate o canal como UI degradada: ele pode acionar loops, acompanhar checkpoints e receber resumos, mas não é autoridade canônica e não bypassa budget/delivery/verification gates.

Se não tiver certeza, comece com A e evolua para B se precisar de tools/commands próprios.

Referência canônica

Guia completo: docs/guides/pi-embedding-cli.md
Pesquisa técnica: docs/research/pi-embedding-ecosystem-survey.md
Exemplo de extension mínima: packages/pi-stack/extensions/claude-code-adapter.ts

Fluxo recomendado

1) Definir o modelo

Responda:

• O projeto precisa de tools ou commands customizados? → B ou C
• O projeto invoca pi de CI/automação? → C
• Só precisa de configuração? → A

2) Implementar

Para modelo A:

1. Criar .pi/settings.json com packages + config de budgetPolicy e deliveryPolicy
2. Documentar no README: pré-requisitos, pi install, comando de início
3. Testar com PI_CODING_AGENT_DIR=/tmp/teste-isolado pi

Para modelo B:

1. Criar pacote com estrutura packages/meu-pi-stack/
2. Entry point exporta função default(pi: ExtensionAPI)
3. Extensions em extensions/, skills em skills/
4. Publicar como @meu-org/pi-stack e testar com pi install npm:@meu-org/pi-stack

Para modelo C:

1. Usar execFileNoThrow (nunca exec com string interpolada)
2. Isolar sessões com PI_CODING_AGENT_DIR por run
3. Consumir sessões JSONL de ~/.pi/agent/sessions/<workspace-slug>/

3) Aplicar governança

Independente do modelo:

• budgetPolicy.hardCapUsd definido
• deliveryPolicy.mode explícito
• Sessões CI isoladas das sessões do usuário
• Testado com budget baixo antes de runs longas

Para modelo D/message adapter:

• Capability map explícito (supported|degraded|unsupported) entre TUI/Web e o canal.
• Comandos remotos viram intents canônicos (board.execute-task, checkpoint, status) com auditoria; nunca editam .project diretamente.
• Fechamento de task continua exigindo verification e, para no-auto-close/estratégicas, decisão explícita do operador.
• Limitações do canal (mensagem truncada, atraso, falta de rich UI, anexos) têm fallback para TUI/Web/local handoff.

4) Validar

# Verificar que extensões carregam corretamente
pi install ./meu-pacote
pi  # iniciar e checar /doctor

# Verificar isolamento de sessão
PI_CODING_AGENT_DIR=/tmp/pi-test pi --version

# Verificar budget em settings
/colony-pilot status

Armadilhas comuns

Problema	Causa	Solução
Sessões CI aparecem em quota-visibility do usuário	PI_CODING_AGENT_DIR não setado	Setar por run em CI
Extension não carrega após pi install	Entry point não exporta default	Verificar export e build
Budget aberto em automação	hardCapUsd não configurado	Sempre definir cap conservador
Namespace colide com piStack first-party	Chave sob piStack conflita	Usar namespace próprio piStack.meuOrg.*

Entregável esperado

Ao final da implementação, deve existir:

• Evidência de que o projeto funciona com pi install limpo
• Budget policy ativa e testada
• Documentação de setup no README do projeto
• Sessões de teste isoladas e limpas