My personal developer kit: reusable templates and boilerplates, standalone scripts, and AI assets (skills, prompts, agents).
This is the hub — read it when you're unsure where something belongs. It routes; it does not hold facts. Every doc has a type and lives in a bucket.
| Bucket | Answers | Holds |
|---|---|---|
| product/ | Why does it exist / who is it for? | business & problem-space knowledge — the non-code, non-how layer |
| architecture/ | How is it built / secured / governed / tested? | the durable narrative of how the system is; home for subject hubs |
| decisions/ | Why was this choice made? | append-only, backward-looking records — they stop agents from "helpfully" undoing deliberate choices |
| guides/ + runbooks/ | How do I do X? | procedures — guides/ are calm (read in advance), runbooks/ are crisis (read under pressure) |
- Hub — every
README.md. Routes to where facts live; never duplicates them. - Typed — holds one kind of content (a vision, an ADR, a guide…).
- Flat lookup (root) — conventions.md, glossary.md: grep them, don't read them.
- Procedural, run-once — CHECKLIST.md: tick through once when the repo is created, then ignore.
| Area | Where |
|---|---|
| Conventions (enforced rules) | conventions.md |
| Glossary (term → definition) | glossary.md |
| Product — vision, roadmap, domain | product/ |
| Architecture (subject hubs) | architecture/ — ci-cd, security, branch-protection, tests |
| Decisions (ADRs) | decisions/ |
| Guides (calm how-tos) | guides/ — onboarding, deploying, troubleshooting, devcontainers |
| Runbooks (crisis procedures) | runbooks/ |
| Post-generation setup | CHECKLIST.md |
Design intent is at ../DESIGN.md; specs (WHAT to build) in
../specs/ and tests in ../tests/ — all at the repo root.