Referência
Especificações.
Nada na T25 foi decidido em conversa perdida. Toda fatia de trabalho deixa um rastro de três peças — uma spec que descreve o desenho, um plano que descreve a execução e, quando a decisão é estrutural, uma ADR. Tudo versionado junto do código.
Como o rastro é organizado
| Peça | Onde | O que responde |
|---|---|---|
| Spec de desenho | docs/superpowers/specs/ | O que vai ser construído e por que assim. |
| Plano de execução | docs/superpowers/plans/ | Em que ordem, em quantos passos, com que verificação. |
| ADR | docs/adr/ | A decisão estrutural, as alternativas e o que foi aceito. |
| Módulos | docs/modules/ | Como um subsistema funciona por dentro, hoje. |
Spec e plano são nomeados por data — AAAA-MM-DD-assunto — então a pasta se lê
como linha do tempo: o arquivo mais recente de um assunto é o estado mais recente daquele
desenho.
Decisões de arquitetura
As quatro ADRs registradas até aqui, todas sobre o plano de execução:
| ADR | Decisão |
|---|---|
| 0001 | PostgreSQL como fonte transacional do control plane. |
| 0002 | O protocolo entre control plane e worker. |
| 0003 | Como os artefatos de cada fase são armazenados. |
| 0004 | Como um worker prova quem é antes de receber uma lease. |
O que está feito e o que falta
Dois arquivos, e a diferença entre eles importa mais do que parece:
- LEFTOVERS.md é a lista do que ainda falta, com a coluna do que já foi feito ao lado do que não foi. É o lugar certo para checar antes de assumir que uma capacidade existe.
- STATUS.md é o diário do que já saiu, em ordem. Serve para saber quando e por que algo mudou, não para saber o que existe hoje.
Um item aparecer no STATUS não significa que a fatia inteira está pronta — significa que aquele incremento saiu. Quem responde "isto existe?" é o LEFTOVERS.
Referência viva
Quando a pergunta é sobre o sistema como ele está agora, e não sobre como se chegou nele:
ARCHITECTURE.md
Camadas, tour guiado pelo código, mapa de arquivos e pontos de complexidade.
DOMAIN.md
Domínios de negócio, fluxos e o glossário do processo de entrega.
API.md
Rotas REST, stream SSE e formatos de resposta.
Landscape
Contra quais fábricas de SWE comparáveis o projeto se calibra.
A recomendação do próprio repositório: antes de propor uma mudança arquitetural, leia o landscape. Muita decisão que parece em aberto já foi comparada contra o que existe lá fora.