Skip to content
bflo.sh

The design set — written truth, per-file owners

Canonical documents with exactly one owning role each, updated in the same task as the change they describe.

Adapted from the repo's docs/README.md — Part of Internals: the platform's design set, published as content on the platform it describes.

The written source of truth for how this project is designed, decided, and operated. CLAUDE.md at the repo root is the operating constitution; these documents carry the detail. If a document here contradicts code, the document is either updated or the code is wrong — never silently divergent.

Reading order (new engineer or new agent session)

  1. ../CLAUDE.md — operating constitution: layout, roster, rules, working agreement.
  2. architecture.md — what we are building and how it is shaped.
  3. master-blueprint.md — the product design applying the tier model to the personal publishing platform (read after architecture.md).
  4. team.md — who owns what, and how the roster evolves.
  5. orchestration.md — how work moves through the agent team.
  6. rules-of-engagement.md — the three non-negotiable rules and their mechanics.
  7. working-agreement.md — autonomy, version control, verification hand-offs.
  8. adr/ — accepted decisions, newest last.
  9. ui-ux.md — required before any frontend work (normative UI/UX definition).
  10. runbook.md — how to start and run the stack locally (operational).
  11. how-it-works.md — technical walkthrough: write → live data flow, with architecture and sequence diagrams.

Contents

Document Purpose Owner
architecture.md Tier model, backend layering, data flow, environments contract-owner (structure); tier sections by their owners
master-blueprint.md The product design blueprint applying the tier model to the personal publishing platform contract-owner (stewards structure); tier sections by their owners
team.md Roster, responsibilities, ownership map, how to evolve the roster contract-owner
orchestration.md Agent-team orchestration model, Workflow patterns, task/message protocol contract-owner
rules-of-engagement.md Contract-first mechanics, tier direction, coordination and arbitration contract-owner
working-agreement.md Autonomy boundaries, version-control rules, verification hand-offs contract-owner
ui-ux.md UI/UX definition for the reader front-end — normative for all frontend work (Phase 3+) frontend-engineer
runbook.md How to start and run the stack locally: bootstrap, daily commands, verify, troubleshooting platform-engineer
how-it-works.md Technical walkthrough of the write → live data flow (architecture + sequence diagrams), grounded in the shipped code and ADRs contract-owner
adr/ Architecture decision records (start from adr/0000-template.md) contract-owner stewards; anyone drafts

Conventions

  • Documents here are canonical: living documents, updated in the same task as the change they describe.
  • Decisions with lasting consequence (auth model, baseline bumps, breaking contract changes) are recorded as ADRs — numbered, immutable once accepted, superseded rather than edited (adr/README.md).
  • Each document has exactly one owning role; others propose changes via tasks routed through contract-owner.