diff --git a/AGENTS.md b/AGENTS.md index 6211cf2..fa54dad 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,8 +4,8 @@ This file is for coding agents working in this repository. Keep it practical: follow the project conventions, avoid speculative dependencies, and produce reproducible data work. -For Claude Code / Cursor harness specifics (worktrees, ship routing), see -[`CLAUDE.md`](CLAUDE.md). +Harness specifics (worktrees, ship routing, `.venv` resolver) are in +[Harness: ship, worktrees, commands](#harness-ship-worktrees-commands). ## Agent skills @@ -24,7 +24,7 @@ duplicated in this repo; use the installed host skills. ## Project baseline - Implementation checkout: a dedicated **worktree**, never the root checkout - and never `main`. Root/`main` are inspect-only (see `CLAUDE.md`). + and never `main`. Root/`main` are inspect-only (see [Worktree Policy](#worktree-policy)). - Project name: Dados Financeiros Abertos. - Distribution/package slug: `openfindata`. - Import package and CLI remain `findata` for compatibility. @@ -171,3 +171,73 @@ matrix, templates, and examples of source/technical lines. - Do not tag a release until tests and adversarial review are clean. - When handing off to another agent, summarize: what changed, why, verification, risks, and the next executable step. + +## Harness: ship, worktrees, commands + +### Ship / PR + +Use a skill **`openfindata-ship`** como primeira ação sempre que o request for +publicar código: commit, push, abrir/atualizar PR, ready-for-review, ou +endereçar comentários cujo resultado mude código. + +Fonte canônica (somente no repo): + +```text +docs/agents/openfindata-ship/SKILL.md +``` + +Inspeção read-only de PR pode usar `gh` direto. No momento em que edição, +push ou criação de PR entram em cena, volte para `openfindata-ship`. + +PyPI e tags de release exigem aprovação humana explícita: ship nunca publica +pacote sozinho. + +### Worktree Policy + +#### Branch naming + +- Claude / Cursor: `claude/` ou `cursor/` +- Codex: `codex/` +- Slug descreve a feature (ex.: `agent-quality-workflows`), não categoria genérica + +#### Estrutura + +- `.claude/worktrees/*`: worktrees do Claude Code +- `$HOME/.cursor/worktrees/*`: worktrees do Cursor +- `.worktrees/codex-*`: worktrees do Codex +- **Root checkout = inspeção apenas.** Nunca implementar, commitar ou fazer push do root. +- **`main` = integração;** nunca mutar código diretamente nela. + +Depois de pull/merge que altere `.githooks/*` ou `scripts/git/guardrails.sh`, +rode `bash scripts/git/install-hooks.sh` antes de confiar nos hooks locais. + +#### Bypass (emergência) + +Só com intenção explícita do operador: + +```bash +OPENFINDATA_GUARDRAILS_BYPASS=1 git commit ... +``` + +Não use bypass como atalho de rotina. + +### Comandos úteis + +```bash +bash scripts/git/install-hooks.sh +bash scripts/ship/preflight.sh +bash docs/agents/openfindata-ship/scripts/readiness.sh +.venv/bin/findata serve --reload # ou scripts/dev_server.sh +``` + +#### Python / `.venv` (contrato único) + +Resolver usado por `scripts/ship/preflight.sh` e `scripts/git/guardrails.sh`: + +1. `/.venv/bin/python` se existir; +2. senão `/.venv/bin/python` (venv criado no clone raiz); +3. senão `python3` no `PATH`. + +Comandos documentados como `.venv/bin/...` significam “o interpretador desse +resolver”, não “somente um `.venv` local à worktree”. Preferência: criar o +venv no root uma vez (`CONTRIBUTING.md`) e reutilizá-lo nas worktrees. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 5e8684a..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,96 +0,0 @@ -# openfindata: Claude Code / Cursor harness - -> Convenções universais de código vivem em [`AGENTS.md`](AGENTS.md). Este arquivo -> cobre só o que é específico do harness: worktrees, ship skill, gotchas. -> Não duplique convenções de código aqui. - -> **Source of truth for:** harness, worktree policy, ship routing. -> **Companion:** [`AGENTS.md`](AGENTS.md), [`docs/agents/`](docs/agents/). - -## Fonte de verdade - -| O que | Onde | -|---|---| -| Convenções de código (universal) | [`AGENTS.md`](AGENTS.md) | -| Agent skills / workflows | [`AGENTS.md`](AGENTS.md) → [`docs/agents/`](docs/agents/) | -| Gates locais | [`docs/agents/quality.md`](docs/agents/quality.md) | -| MCP trust | [`docs/agents/mcp-trust-review.md`](docs/agents/mcp-trust-review.md) | -| Contribuição humana | [`CONTRIBUTING.md`](CONTRIBUTING.md) | - -## Ship / PR - -Use a skill **`openfindata-ship`** como primeira ação sempre que o request for -publicar código: commit, push, abrir/atualizar PR, ready-for-review, ou -endereçar comentários cujo resultado mude código. - -Fonte canônica (somente no repo): - -```text -docs/agents/openfindata-ship/SKILL.md -``` - -Inspeção read-only de PR pode usar `gh` direto. No momento em que edição, -push ou criação de PR entram em cena, volte para `openfindata-ship`. - -PyPI e tags de release exigem aprovação humana explícita — ship nunca publica -pacote sozinho. - -## Worktree Policy - -### Branch naming - -- Claude / Cursor: `claude/` ou `cursor/` -- Codex: `codex/` -- Slug descreve a feature (ex.: `agent-quality-workflows`), não categoria genérica - -### Estrutura - -- `.claude/worktrees/*`: worktrees do Claude Code -- `$HOME/.cursor/worktrees/*`: worktrees do Cursor -- `.worktrees/codex-*`: worktrees do Codex -- **Root checkout = inspeção apenas.** Nunca implementar, commitar ou fazer push do root. -- **`main` = integração;** nunca mutar código diretamente nela. - -Depois de pull/merge que altere `.githooks/*` ou `scripts/git/guardrails.sh`, -rode `bash scripts/git/install-hooks.sh` antes de confiar nos hooks locais. - -### Bypass (emergência) - -Só com intenção explícita do operador: - -```bash -OPENFINDATA_GUARDRAILS_BYPASS=1 git commit ... -``` - -Não use bypass como atalho de rotina. - -## Comandos úteis - -```bash -bash scripts/git/install-hooks.sh -bash scripts/ship/preflight.sh -bash docs/agents/openfindata-ship/scripts/readiness.sh -.venv/bin/findata serve --reload # ou scripts/dev_server.sh -``` - -### Python / `.venv` (contrato único) - -Resolver usado por `scripts/ship/preflight.sh` e `scripts/git/guardrails.sh`: - -1. `/.venv/bin/python` se existir; -2. senão `/.venv/bin/python` (venv criado no clone raiz); -3. senão `python3` no `PATH`. - -Comandos documentados como `.venv/bin/...` significam “o interpretador desse -resolver”, não “somente um `.venv` local à worktree”. Preferência: criar o -venv no root uma vez (`CONTRIBUTING.md`) e reutilizá-lo nas worktrees. - -## Skills no repo - -| Skill | Path | -|---|---| -| Ship | `docs/agents/openfindata-ship/SKILL.md` | -| MCP trust reviewer | `.claude/skills/mcp-trust-reviewer/SKILL.md` | - -Skills de harness global (adversarial-review, deslop, handoff, tdd, …) não são -duplicadas neste repo. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f484901..c75a19c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,7 +37,7 @@ permitidas. | Claude / Cursor | `claude/` ou `cursor/` | `.claude/worktrees/*` ou `$HOME/.cursor/worktrees/*` | | Codex | `codex/` | `.worktrees/codex-*` | -Ver [`CLAUDE.md`](CLAUDE.md) e [`docs/agents/openfindata-ship/`](docs/agents/openfindata-ship/). +Ver [`AGENTS.md`](AGENTS.md#harness-ship-worktrees-commands) e [`docs/agents/openfindata-ship/`](docs/agents/openfindata-ship/). Gate local canônico antes de publicar: diff --git a/docs/agents/domain.md b/docs/agents/domain.md index 491e4a6..f4d053f 100644 --- a/docs/agents/domain.md +++ b/docs/agents/domain.md @@ -13,7 +13,6 @@ antes de explorar ou alterar o código. - **[`docs/RESOLVER.md`](../RESOLVER.md)** — registry/resolver para lookups de agente. - **[`docs/CHART_STANDARDS.md`](../CHART_STANDARDS.md)** — contrato informacional de gráficos. - **`docs/source-notes/`** — notas por fonte (`basedosdados`, `yahoo`, `advfn`, …). -- **[`CLAUDE.md`](../../CLAUDE.md)** — worktrees e roteamento de ship (Claude/Cursor). Se um documento **obrigatório de política/segurança** estiver ausente (`SOURCES_WITH_AUTH.md`, `MCP_SURFACE.md`, `AGENTS.md`), pare com @@ -26,7 +25,6 @@ canônica mais próxima em silêncio. Não invente glossário paralelo. ```text / ├── AGENTS.md -├── CLAUDE.md ├── CONTRIBUTING.md ├── src/findata/ │ ├── sources// diff --git a/docs/agents/orientation.md b/docs/agents/orientation.md index 9fff499..930da6f 100644 --- a/docs/agents/orientation.md +++ b/docs/agents/orientation.md @@ -10,7 +10,7 @@ mortos, fronteira atual, openfindata, findata. - Produto e escopo: [`README.md`](../../README.md), [`MANIFESTO.txt`](../../MANIFESTO.txt). - Convenções universais de código e gates: [`AGENTS.md`](../../AGENTS.md). -- Harness Claude (worktrees, ship): [`CLAUDE.md`](../../CLAUDE.md). +- Harness (worktrees, ship): [`AGENTS.md`](../../AGENTS.md#harness-ship-worktrees-commands). - Contribuição humana: [`CONTRIBUTING.md`](../../CONTRIBUTING.md). - Superfície MCP curada: [`docs/MCP_SURFACE.md`](../MCP_SURFACE.md). - Padrões de gráfico: [`docs/CHART_STANDARDS.md`](../CHART_STANDARDS.md). @@ -30,7 +30,7 @@ mortos, fronteira atual, openfindata, findata. | Code mode no MCP? | Opt-in via `FINDATA_MCP_CODE_MODE=1`; off por default | `docs/MCP_SURFACE.md`, `mcp_app.py` | | Charts: quais deps de plot? | Não adicionar matplotlib/pandas/plotly etc. só para gráfico | `AGENTS.md`, `docs/CHART_STANDARDS.md` | | Publicar no PyPI? | Só com aprovação humana explícita | `AGENTS.md` | -| Onde agentes implementam? | Worktree dedicada; root/`main` são inspect-only | `CLAUDE.md`, `docs/agents/openfindata-ship/` | +| Onde agentes implementam? | Worktree dedicada; root/`main` são inspect-only | `AGENTS.md`, `docs/agents/openfindata-ship/` | ## O que morreu e por quê diff --git a/docs/agents/quality.md b/docs/agents/quality.md index 2b39ecf..7eac8f6 100644 --- a/docs/agents/quality.md +++ b/docs/agents/quality.md @@ -13,7 +13,7 @@ bash scripts/ship/preflight.sh Equivalente expandido (mesmo conjunto que o preflight `--push`). Interpretador: worktree `.venv`, senão `.venv` na raiz do repo comum, senão `python3` — ver -`CLAUDE.md` § Python / `.venv`. +`AGENTS.md` § Python / `.venv`. ```bash # Prefer: bash scripts/ship/preflight.sh