This tree is organized by kind of document first (product / architecture / plan /
devlog / audit / guide / runbook / evidence), with a small number of per-surface
folders for modules that own their own contracts (hummingbird/, home-hospital/).
Canon that governs the whole repo lives at the repo root, and only that: README.md (what Zephyrus is) · PRODUCT.md (strategy, users, design principles) · DESIGN.md (visual system) · AGENTS.md (build/deploy/engineering conventions) · CLAUDE.md (token canon + non-negotiables) · AUTHENTICATION.md (current auth flow). Everything else — including deployment runbooks and the business plan — files below.
| Directory | What belongs here | Start here |
|---|---|---|
| product/ | PRDs, master plans, roadmaps, scope, demo narrative | ZEPHYRUS-2.0-PLAN.md, ZEPHYRUS-2.0-BETA-PRD.md |
| architecture/ | Durable system architecture and taxonomies — outlives any one initiative | OCEL-DRG care-pathway measurement, service-line/location taxonomy |
| plans/ | Dated initiative and implementation plans, plus their companion evidence | plans/zephyrus-2.0-beta/ (B0–B8 delivery program) |
| devlog/ | Dated execution logs — what was actually built, verified, and merged | Newest first: governed DRG care pathways |
| audits/ | Audits, reviews, and the instruments used to run them | Comprehensive UX/UI + HFE audit |
| guides/ | Engineering reference and how-to for contributors | coding-standards.md |
| operations/ | Runbooks for running, deploying, and releasing the system | DEPLOY_NOW.md (manual deploy is the only supported path), DEPLOYMENT_CHECKLIST.md, DEVELOPMENT-AND-PRODUCTION-RELEASE-RUNBOOK.md |
| evidence/ | Acceptance/verification artifacts (screenshots, query output, import logs) | evidence/ancillary/ |
| hummingbird/ | Mobile companion app: ADRs, API contracts, design tokens, personas | hummingbird/README.md |
| home-hospital/ | Hospital-at-Home / RPM virtual-ward module | HOME-HOSPITAL-BUILD-PROMPT.md |
| superpowers/ | Skill-authored implementation plans + design specs (stable path, see below) | superpowers/plans/ |
| business/ | Business plan, investor and GTM material, deck build tooling | BUSINESS_PLAN.md, Zephyrus_Investor_Deck_Reconciled.pdf |
| reference/ | External prototypes and third-party inputs we read but do not own | hospital-operations-cockpit/ |
| screenshots/ | App screenshots used by the repo README | — |
| archive/ | Superseded documents, kept for provenance | archive/README.md |
- Kind first. A new Flow-4D plan goes in
plans/, not aflow-4d/folder. Only a module that ships its own contracts or app code earns a per-surface folder (hummingbird/,home-hospital/). - Plans and devlogs pair up. An initiative plan in
plans/gets its execution log indevlog/under the same slug; cross-link them at the top of both files. - Date anything time-bound.
-YYYY-MM-DDsuffix for plans, audits, and devlogs; no date for durable architecture, guides, and runbooks. - Companions travel with their parent. Raw teardown/intel that only exists to support a
plan sits beside that plan (e.g.
EDDY-ABBY-TEARDOWN-EVIDENCE.md); reusable verification artifacts go inevidence/. - Archive, don't delete. When a doc is superseded, move it to
archive/and record what replaced it in archive/README.md.
docs/hummingbird/api-contract/**,capability-*.yaml,role-catalog.v1.json,capability-registry.lock— machine-consumed by codegen, contract tests, and CI.docs/superpowers/plans/**anddocs/superpowers/specs/**— cited by provenance docblocks in ~75 PHP source files. These are the skill-authored implementation plans;plans/holds the hand-authored initiative plans.docs/screenshots/**— referenced by the repo README.md.