Guias — agents-lab
Guias práticos para usar, operar, manter e distribuir a stack. Para escolher por perfil de leitura, use Start Here.
Índice
Instalação e Configuração
| Guia | Descrição |
|---|---|
| recommended-pi-stack.md | Stack curada @aretw0/pi-stack — o que inclui, como instalar, filosofia |
| terminal-setup.md | Configuração de terminal por plataforma — Windows Terminal, Ghostty, WezTerm, VS Code |
| monitor-overrides.md | Configuração provider-aware dos monitors (Copilot/Codex), diagnóstico e sincronização de overrides |
| testing-isolation.md | Testando extensões e temas em isolamento — flags --no-*, PI_CODING_AGENT_DIR |
| pi-platform-compatibility.md | Compatibilidade de plataforma (Windows/Linux/macOS) |
| devcontainer-factory-contract.md | Contrato mínimo para fábrica devcontainer-first, wrapper de operador/agente e CI first-party |
Contribuição e Release
| Guia | Descrição |
|---|---|
| publishing.md | Workflow de release — changesets, versionamento lockstep, publish via tag |
| ROADMAP.md | Direção macro da 0.8.0; estado diário continua em .project/* |
Operação da stack
| Guia | Descrição |
|---|---|
| token-efficiency.md | Diretivas de eficiência de tokens (T1–T11), segurança (S1–S3) e calibração de monitores |
| consumption-visibility-surfaces.md | Mapa das superfícies reais de consumo/quota na stack completa (usage, session-breakdown, quota-visibility) |
| budget-governance.md | Budget envelope por execução, governança de colônia com maxCost, paridade e isolamento |
| quota-visibility.md | Como auditar consumo/cota local, projetar burn semanal e exportar evidência para contestação |
| stack-sovereignty-user-guide.md | Guia operacional da soberania da stack (owners, defaults seguros, convivência) |
| subagent-readiness-gate.md | Gate para decidir delegação/subagentes com sinais reproduzíveis |
| swarm-preflight-15m.md | Checklist curto antes de lançar swarm com budget e contexto sob controle |
Operação do control plane
| Guia | Descrição |
|---|---|
| web-session-gateway.md | Gateway web first-party para observabilidade local da sessão (health/state/prompt) |
| control-plane-ux-curation.md | Padrão de UX do control-plane (TUI+WEB): densidade adaptativa, anti-clutter e checklist de resize |
| control-plane-evolution-playbook.md | Playbook de evolução em fases: single control-plane -> delegação descartável -> federação multi-control-plane |
| primitive-growth-sanity-plan.md | Plano de crescimento com sanidade: primitive-first, anti-gordura, orçamento de dívida e ladder de promoção segura |
| control-plane-operating-doctrine.md | Doutrina operacional do control-plane unattended: quando continuar, parar, reduzir gordura e escalar canários |
| control-plane-glossary.md | Glossário canônico do control-plane para reduzir alcunhas, aliases e progresso vazio |
| unified-dogfood-isolation.md | Runbook para dogfood em ambiente isolado com TUI + WEB unificados |
| colony-runtime-recovery.md | Como localizar artefatos de colony (state/worktree/branch) e recuperar contexto após parada |
| colony-provider-model-governance.md | Governança de provider/model para colony e multi-agentes (usuário + dev) |
| swarm-cleanroom-protocol.md | Protocolo cleanroom para runs de swarm (pre-run, execução, promoção, reconciliação) |
| unattended-swarm-execution-plan.md | Plano de execução unattended por lotes P0 (OpenAI-only) com go/no-go e rollback |
Manutenção distribuível
Estes guias descrevem manutenção que pode acompanhar a stack ou inspirar outros projetos. Se um guia for necessário para uma skill ou extensão instalada via pacote, ele deve estar listado em scripts/sync-package-docs.mjs.
| Guia | Descrição |
|---|---|
| scheduler-governance.md | Governança forte de ownership/lease do scheduler para evitar conflito entre sessões |
| extension-acceptance-checklist.md | Checklist para aceitar nova extensão sem aumentar fragmentação |
| dependency-upstream-governance.md | Governança para atribuir mudanças entre stack local, upstream Pi e dependências antes de decidir assimilate|hold|reject |
| host-disk-recovery.md | Recuperação dry-first de disco, cache e artefatos de sandbox sem perder continuidade |
| session-triage.md | Triagem de sessões/eventos recentes para transformar histórico em backlog revisável |
| i18n-intents.md | Runbook de intents soft/hard de internacionalização para comunicação e artefatos |
| mermaid-authoring.md | Regras portáveis para escrever Mermaid em Markdown, GitHub, Jekyll, Astro e Obsidian |
Manutenção do laboratório
Estes guias existem para manter este monorepo, seus fluxos de release, seu site e seu histórico. Não entram em pacotes distribuídos salvo decisão explícita de promoção para a seção distribuível.
| Guia | Descrição |
|---|---|
| first-party-assimilation-notes.md | Memória técnica de capacidades suprimidas por conflito para futura centralização first-party |
| ci-governance.md | Troubleshooting dos gates de soberania no CI (annotations, registry, criticality, owner) |
| lab-user-surface-parity.md | Higiene de paridade entre superfícies do laboratório e distribuídas para usuários |
| github-repo-presence.md | Checklist de presença pública do repositório no GitHub: metadata, README e drift de docs/MDT |
| doc-drift-mdt.md | Contrato advisory para MDT/doc-drift: check first, escopo pequeno e integração futura com CI |
| agents-lab-editorial-pipeline.md | Pipeline/template editorial para release notes e posts separando nossa stack, upstream Pi, deps e curadoria |
| skill-guide-parity.md | Protocolo de paridade guide-skill para discoverability e controle de drift documental |
Evidência selecionada
Research não é guia operacional por padrão. Estas páginas ficam aqui apenas como atalhos para planejamento de release e devem ser promovidas para guides, primitives ou architecture quando virarem contrato estável.
| Documento | Uso |
|---|---|
| 0.8 readiness map | Estado verificável e próximos passos da 0.8.0 |
| 0.8 local-safe compounding lane | Resumo da lane de estabilização 0.8 |
| 0.8 delegation long-run runway | Runway de delegação/long-run para evolução controlada |
| 0.8 local-safe slice validation matrix | Matriz de validação para fatias locais |
| 0.8 local-safe rollback cookbook | Cookbook de rollback local-safe |
Embedding e Integração
| Guia | Descrição |
|---|---|
| pi-embedding-cli.md | Como integrar pi em projetos CLI externos — config embedding, extension bundle, subprocess bridge |
Migração e Filosofia
| Guia | Descrição |
|---|---|
| copilot-to-pi-migration.md | Guia incremental de transição do Copilot para Pi |
| workspace-philosophy.md | Filosofia do workspace como superfície compartilhada |
Pré-requisitos Gerais
Para desenvolvimento deste monorepo:
- Node.js >= 22; Node 24 recomendado para desenvolvimento diário
- pnpm via Corepack
- devcontainer recomendado para paridade local
Para uso público da @aretw0/pi-stack fora do monorepo:
- Pi instalado pelo método oficial atual
- Chave de API ou login de pelo menos um provider suportado
Instalação Rápida
# Instalar a stack curada publicada
npx @aretw0/pi-stack
# Ou instalar a partir do repositório
pi install https://github.com/aretw0/agents-lab