Skip to content

Documentation Boundary Law

The Golden Rule: If this repository disappeared tomorrow, who would need this information? * Only developers/operators of this project → PROJECT * Every Bluefly project → ENGINEERING STANDARD * People performing a repeatable operational procedure → PLAYBOOK * People defining what Bluefly sells/builds → PRODUCT * People needing durable supporting information → REFERENCE * We don't know yet / we're investigating → RESEARCH * An agent currently executing work → GAS CITY / BEADS * Evidence about a specific implementation/change → PROJECT + GITLAB

BluCity-Docs Breakdown

  • Engineering-Standard/: Normative rules across all projects (MUST, SHALL).
  • Playbooks/: Operational methods (how we accomplish standard things).
  • products/: Product definition/authority (not implementation debris).
  • reference/: Durable non-normative context (glossaries, protocols).
  • research/: Not yet promoted to authority.
  • LEDGER IS DEAD. No more BluCity-Docs/ledger. Operational evidence belongs in the project, Gas City, or GitLab.

Standard Project Contract

Every Bluefly repository converges on: 

project/
├── README.md
├── AGENTS.md
├── CLAUDE.md
├── llms.txt
├── CHANGELOG.md
├── OWNERSHIP.md
├── .agents/ (reusable project rules/context only)
├── docs/ (architecture, decisions, ops, reference)
└── .gitlab/
No vendor sprawl: .cursor, .codex, GEMINI.md, etc., do not become independent systems. CLAUDE.md is a tiny adapter pointing to AGENTS.md.

Metadata Requirement

All governed documents MUST use standardized YAML frontmatter validated by GitLab CI. Required fields: title, type, status, authority, owner, scope, created, updated, review_by, supersedes, tags.