Reference
Specifications.
Nothing in T25 is decided in a lost conversation. Every work slice leaves a trail of three pieces: a spec that describes the design, a plan that describes execution and, when the decision is structural, an ADR. Everything is versioned with the code.
How the trail is organized
| Piece | Where | What it answers |
|---|---|---|
| Design spec | docs/superpowers/specs/ | What will be built and why this way. |
| Execution plan | docs/superpowers/plans/ | In what order, in how many steps and with what verification. |
| ADR | docs/adr/ | The structural decision, the alternatives and what was accepted. |
| Modules | docs/modules/ | How a subsystem works inside today. |
Specs and plans are named by date, YYYY-MM-DD-topic, so the folder reads like a timeline: the newest file for a topic is the newest state of that design.
Architecture decisions
The four ADRs recorded so far, all about the execution plan:
| ADR | Decision |
|---|---|
| 0001 | PostgreSQL as the transactional source of truth for the control plane. |
| 0002 | The protocol between the control plane and worker. |
| 0003 | How each phase's artifacts are stored. |
| 0004 | How a worker proves who it is before receiving a lease. |
What is done and what remains
Two files, and the difference between them matters more than it seems:
- LEFTOVERS.md is the list of what remains, with what is already done next to what is not. It is the right place to check before assuming a capability exists.
- STATUS.md is the journal of what shipped, in order. It tells you when and why something changed, not what exists today.
An item appearing in STATUS does not mean the whole slice is ready. It means that increment shipped. LEFTOVERS answers the question, "does this exist?".
Living reference
When the question is about the system as it is now, not how it got there:
ARCHITECTURE.md
Layers, a code-guided tour, a file map and complexity hotspots.
DOMAIN.md
Business domains, flows and the delivery-process glossary.
API.md
REST routes, SSE streams and response formats.
Landscape
The comparable SWE factories this project uses as reference.
The repository's own recommendation: read the landscape before proposing an architectural change. Many decisions that look open have already been compared with what exists elsewhere.