iara-pwa/AGENTS.md
Francisco Solla ac8efb816e
All checks were successful
Agent PR Ready + auto-merge / ready-automerge (pull_request) Has been skipped
CI / checks (pull_request) Successful in 13s
CI / deploy (pull_request) Has been skipped
Promote plan-issue Related on main merge / plan-issue-ready (pull_request) Has been skipped
Main merge flips claimed issues to done + in-prod / issue-done (pull_request) Successful in 4s
CI / checks (push) Successful in 13s
CI / deploy (push) Successful in 6s
feat(agentes): contrato MCP do repo — opencode.jsonc desligando postgres/stalwart dos globais + seção Harness no AGENTS.md (I3)
2026-08-18 11:38:56 -03:00

104 lines
6.4 KiB
Markdown

# Iara — convenções de trabalho para agentes
**Iara** é um chat PWA local-first para falar com assistentes de IA (gateways
compatíveis com o protocolo ZeroClaw). Vite + React + TypeScript + assistant-ui
+ Tailwind v4 + vite-plugin-pwa. Sem backend próprio: o estado do cliente vive
no dispositivo (localStorage); o único servidor externo é o gateway WS do
usuário.
## Stack e scripts
- **Runtime:** bun (também há `node` para os scripts de agente — são ESM puros).
- `bun run dev` — dev server; `bun run build` — `tsc -b && vite build` (build de produção em `dist/`); `bun run preview` — servir o build.
- `bun run gate` — gate local: `lint` (oxlint) + `build` (typecheck + build). Rode antes de push.
- `bun run test:e2e` — **e2e Playwright; roda SÓ no CI, nunca local** (decisão do fluxo: não rodar e2e local para não divergir do CI).
## Arquitetura do código
- `src/lib/ws.ts` — protocolo WebSocket `zeroclaw.v1` (tipos de mensagens, conecta em `<gateway>/ws/chat?token=&agent=&name=`). **Contrato**: mudar tipos de protocolo é breaking.
- `src/lib/messages.ts` — normalização/montagem de mensagens.
- `src/lib/settings.ts` — config local (URL/key/agente/STT/TTS) em localStorage.
- `src/lib/voice.ts` — STT/TTS opcional (Web Speech + endpoints configuráveis).
- `src/components/Chat.tsx` — thread + composer (assistant-ui primitives).
- `src/components/Settings.tsx` — tela de configuração.
- `src/components/ApprovalCard.tsx` — card de aprovação (`approval_request` → `approval_response`).
- `vite.config.ts` — base `/_app/` (servido pelo gateway do ZeroClaw), PWA manifest + service worker, background sync do WS.
**Invariantes:** local-first (nada de servidor para estado do cliente); token
nunca logado/commitado; aprovações nunca auto-aprovadas; copy pt-BR /
identificadores em inglês; assets offline em `globPatterns` do PWA.
## Harness do agente
- **Skills:** `.agents/skills/` — fluxo custom + pack de engenharia (fonte de
verdade: `skills-lock.json`; detalhes no Workflow de trabalho).
- **MCPs:** contrato em `opencode.jsonc` na raiz — seleção sobre os globais
(`~/.config/opencode/opencode.jsonc`). Em uso: `forgejo`, `playwright`,
`jina`. Desligados no repo: `postgres` (sem backend; global aponta pro banco
do teqo) e `stalwart` (e-mail pessoal). `penpot`/secrets do teqo nunca
entram. MCP novo ou re-habilitado passa por lá, com comentário registrando o
porquê.
## Workflow de trabalho (fluxo tipo teqo)
**Pack de skills de engenharia:** em `.agents/skills/` (além das 5 de fluxo custom), com proveniência/hashes em `skills-lock.json` na raiz — fonte de verdade; upgrade deliberado via `npx skills update -y`.
Issues do Forgejo (`git.solla.dev/amana/iara-pwa`) são a fonte canônica de
spec/status/deps/prio. Estado em labels: `ready | in-progress | blocked | done`
(+ `in-prod`). Frontmatter no body da Issue:
```yaml
---
id: I7
depends: [I3]
serializes: []
priority: P1
---
Plano: [`docs/plans/<slug>.md`](docs/plans/<slug>.md)
```
Ciclo completo (detalhes nas skills `plan-issue` / `work-issue`):
1. **`/plan-issue`** (num worktree `bun run worktree plan`) → plano de intenção em `docs/plans/<slug>.md` + Issue `blocked` (`bun run agent:register --plan`) → PR `Related #N` → merge → `bun run agent:ready -- --issue N` (ou o CI promove sozinho).
2. **`bun run worktree next`** → claima a próxima Issue `ready` (label `in-progress`), cria worktree `~/.worktrees/iara/<code>-<slug>` de `origin/main`, roda `bun install` e abre o opencode com `/work-issue --issue N`.
3. **`/work-issue`** → plano de implementação (`docs/plans/<slug>-impl.md`), pausa para aprovação humana, execução.
4. **`/simplify`** (skill `code-simplification`) → 3 reviews locais paralelos no diff.
5. **`capture-review-debts`** → triagem + débitos (`bun run agent:register` / `agent:file-miss`).
6. **PR Ready** `Closes #N` com auto-merge (`bun run pr -- --automerge`) → CI (lint+build+e2e) → merge → `done`/`in-prod` → deploy.
### Comandos de agente (bun)
| Comando | O que faz |
| ------- | --------- |
| `bun run worktree next/plan/new/kill` | fila → worktree da Issue / planejamento / neutro / destruir |
| `bun run issue next\|all` | próxima claimável / overview (read-only) |
| `bun run agent:claim` | claima a próxima `ready` (não usar em sessão — `worktree next` já claima) |
| `bun run agent:register` | cria Issue rastreável (com `--plan` nasce `blocked`) |
| `bun run agent:ready` | promove `blocked` → `ready` (plano em main) |
| `bun run agent:file-miss` | registra défice do fluxo de agentes |
| `bun run agent:status` | grafo/overview read-only |
| `bun run pr -- --head <b> --body "Closes #N" --automerge` | cria PR e mergea quando os checks passarem |
**O comando de terminal `worktree` é o roteador global** (`~/.config/shell/worktree.sh`): descobre o projeto pelo diretório atual (`git rev-parse`) e roda o script do projeto; config por projeto em `.forgejo/worktree.env` (commitado, sem secrets).
## CI (Forgejo Actions — `.forgejo/workflows/`)
- `ci.yml` — em push (main) e PR: job `checks` (lint + build + **e2e** Playwright) e job `deploy` (só main, `needs: checks`, rsync para o homeserver).
- `issue-done-on-main-merge.yml` — PRs mergeadas com `Closes #N` flipam a Issue para `done`/`in-prod` (`scripts/forgejo-issue-transition.mjs`).
- `plan-issue-ready-on-main-merge.yml` — PRs com `Related #N` promovem `blocked` → `ready` (`scripts/agent-promote-related-on-merge.mjs`).
- `agent-pr-ready-automerge.yml` — marca Ready e mergea quando `checks` ficar green (safety net do auto-merge).
**Sem branch protection server-side em `main`** (espelha o teqo): o gate de merge é o
próprio script de auto-merge (`pr.mjs --automerge` / `forgejo-pr-automerge.mjs`),
que espera os status checks ficarem green antes de mergear; o deploy é gated pelo
`needs: checks` do `ci.yml`.
**e2e só no CI** — nunca rode `bun run test:e2e` local como parte do fluxo normal.
## Regras de entrega
- **Gate antes de push:** `bun run gate` limpo. CI roda lint+build+e2e de novo no PR.
- **PR nunca draft** para entrega; `Closes #N` no body; auto-merge armado.
- **Nunca editar Issue `in-progress`** de outra sessão; débito vira Issue nova com `depends` no pai.
- **Planos imutáveis** para Issues `in-progress`/`done`/`in-prod` — refino = sucessor.
- **Sem `git push` nu** com o fluxo de agente — use o fluxo do PR (a branch é do worktree).