Docs are split by the question they answer:
| Directory | Question | Contents |
|---|---|---|
| adr/ | Why did we choose this? | Architecture Decision Records — immutable once accepted; superseded, never edited |
| design/ | How does it fit together? | Living documents describing the current architecture |
| specs/ | What exactly is the contract? | Precise, testable interface definitions |
| plans/ | When/in what order do we build? | Roadmaps and phase plans; updated as work lands |
- 0001 — Record architecture decisions
- 0002 — Agent-portable instruction surface
- 0003 — Verify gate, risk paths and corrections
- 0004 — Build a native client of Pi Pocket's own API
- 0005 — Organize the window around what needs the owner
- 0006 — Filter notifications in the client
- 0007 — Render terminal history before attaching
- 0008 — Approve and merge as the owner from the desktop
- 0009 — Read check runs only with a token that can
- 0010 — Act as the owner through a GitHub App user token
- 0011 — Act where the owner can bypass, only on rules Pocket proves
- Pocket — the app: its places, a session, notifications, the protocol
- Agent-ready repository
(none yet)
- New docs start from their category's
TEMPLATE.md(in each directory). - New decision → new ADR with the next number; if it reverses an old one, mark
the old one
Superseded by NNNNrather than editing it. - Design docs are updated in place to always reflect reality.
- Specs change only alongside the code that implements them.
- Cross-links between categories are mandatory in both directions — see the documentation rules in AGENTS.md (CLAUDE.md/GEMINI.md are symlinks to it, ADR-0002).
- Adding a doc means adding it to the index above.