The path of a task Each step below is a module of the repository, with its real file name. Whoever writes a change does not review it, and nothing stays Done without a receipt. The plain-text summary is in docs/ARQUITETURA.md.
Request: WhatsApp, panel or Linear
Everything becomes an issue in Linear. From the panel, the action writes the request into the command inbox the WhatsApp bot also reads; in Linear, a webhook tells the hub when someone speaks on the issue.
- WhatsApp
- Panel
- Linear
- issue
View the code: hub/linear.py hub/acoes.py deploy/linear-webhook.py
Plan
The agent starts by commenting a short plan on the issue. Plan items carry a check command (check:) that code runs, and anything that leaves for a third party (email, post, money) becomes a proposal only the owner can approve.
- request
- short plan
- items with a check
- proposal, if it leaves the house
View the code: hub/plano_itens.py hub/propostas.py hub/tarefas.py
Issue in the queue, tick per account
A cron every 5 minutes (tick) reads the scheduled tasks, enqueues what is due and starts at most one item per free account, by priority and arrival. Two accounts never take the same item or enter the same repository.
- tarefas/*.md
- queue
- 5-minute tick
- free account
View the code: hub/agenda.py deploy/agenda.py
Accounts and lanes
Each agent account has its own login, a lock (one job at a time), a pause when the usage limit is reached and a usage log. The lane says what it takes: construtor (builder: tracker requests), operador (operator: scheduled routines), revisor (reviewer) and codex (requests labelled for Codex). When one account's quota runs out, the work goes to another.
- construtor
- operador
- revisor
- codex
View the code: hub/conta.py hub/roteamento.py hub/esteira.py
Execution in its own worktree
Every task runs in a git worktree of its own, never in the base clone. A global memory budget limits how many sessions open at once, because several builds together have taken a server down.
- base clone
- task worktree
- commits
- own branch
View the code: hub/linear.py hub/memoria.py hub/repos.py
Pull request and review by another model
The pull request is reviewed by a different model from the one that wrote it: Codex reviews what Claude did, and Claude reviews the codex/ branches. The review comments findings on the tip commit; a serious finding goes back to the author, who fixes it and pushes again. The Codex-side script is not in the public repository yet.
- PR
- Codex review
- findings
- fix
- new review
View the code: hub/revisor_merge.py hub/revisar_codex.py
Local CI and merge
Tests run on a machine of your own, not in a hosted CI; a red main becomes an incident. The merge is mechanical, with no model in the middle: issue marked for merge, pull request open, CI green and the tip commit's review without a serious finding.
- local CI
- review without serious finding
- mechanical merge
View the code: scripts/checar.sh hub/main_vermelho.py hub/automerge.py
Waiting outside the session
The agent never polls CI or a deploy: it records the wait and ends the session, and the hub wakes it when the status changes. Stuck work has an alarm and a time and attempt budget, and a cap on runs per task pauses the loop.
- records the wait
- ends the session
- status changes
- hub wakes the task
View the code: hub/esperas.py hub/retomada.py hub/parada.py
Deploy and watchdog
After the merge, the watchdog checks each app's latest deploy. A deploy stuck past its limit is cancelled and redone once; a deploy with an error is redone once; if the second one fails, it opens an issue in the repository with the end of the log.
- merge
- deploy
- watchdog
- redo once
- issue with the log
View the code: hub/vigia_deploy.py
Done gate with a receipt
An issue stays Done only if every cited pull request is merged and live (the commit in production is checked), what the acceptance asked for exists (attachment, video, PDF, notice), the URLs open and the last comment leaves no open item ("Missing", "I will be back") without pointing to another issue. If something is missing, the issue goes back to In Progress with the reason, or becomes "Stuck: needs the owner" if it depends on them. The audit that created the gate found 873 Done issues, 9 with an open pull request, 7 with only closed ones and 187 with a pending note in the last comment.
- Done
- receipt checks
- passed: stays Done
- missing: reopens with the reason
View the code: hub/recibo.py hub/portao_done.py hub/portao.py
Watchdog and debugger
Every failure becomes an incident with the failure class and the part of the harness that changes, and goes into the repair log. The debugger tracks failures per repository, opens one pull request per error class and marks red as resolved only when the source confirms it.
- failure
- incident
- debugger
- fix PR
- log
View the code: hub/debugger.py hub/incidentes.py hub/consertos.py
Recipe library and "does this already exist"
Before dispatching, the hub looks for recipes similar to the task using BM25 (exact words) and embeddings (meaning), merges the lists with RRF and pastes up to three into the prompt. A pull request that used a recipe cites the file in its body, and the hub counts the use. The same hybrid search covers memories, plans, issues and recipes in the second brain.
- task
- BM25 + vector
- up to 3 recipes in the prompt
- PR cites the recipe
- use counted
View the code: hub/biblioteca_indice.py hub/biblioteca_uso.py hub/grafo.py
Memory
The owner's decisions live in memory files, one note per fact, with one index per project. A gate checks that no pointer broke and no decision of the owner disappeared, and the second-brain map shows the relations between repositories, domains, routines and decisions.
- decision
- memory note
- index
- gate checks
- map
View the code: hub/memorias.py hub/cerebro.py hub/grafo.py