Skip to content

BluCity-Docs Standard

Every document has ONE home. If you cannot determine the home from this standard, the document does not belong in BluCity-Docs yet — put it in Scratch/<task>/ and promote it when it is curated.

Directory Map

Directory Purpose Lifecycle
Engineering-Standard/ Canonical standards, architecture, operating model, catalogs, indexes Governed — ADR/STD approval required
Engineering-Standard/standards/ STD-* formal standards Canonical — do not edit without ADR
Engineering-Standard/architecture/ System architecture docs Governed
Engineering-Standard/operating-model/ Agent lifecycle, execution model Governed
Engineering-Standard/indexes/ BLU-BIBLE, catalogs, cross-references Governed
Engineering-Standard/templates/ Standard templates for receipts, beads, docs Governed
ledger/ Operational records — append-mostly, high-volume Evidence lifecycle
ledger/directives/ Operator directives (pre-bead plans, instructions) Active until translated to beads
ledger/evidence/ Execution evidence, verification, measurements Immutable once recorded
ledger/audits/ Audit reports and compliance checks Immutable once recorded
ledger/decision-records/ ADRs — architecture decision records Immutable once accepted
ledger/receipts/ Completion receipts Immutable once recorded
ledger/oracle-platform/ Oracle infrastructure state records Evidence
ledger/parity-check/ Catalog parity snapshots Evidence
playbooks/ Runbooks, procedures, how-to guides Active — update on use
products/ Product-specific documentation Per-product lifecycle
strategy/ Business strategy, GTM, positioning Active — update quarterly
research/ Research notes, explorations Ephemeral — promote or archive
scripts/ Utility scripts (not documentation) Source lifecycle

What Does NOT Belong Here

Content Correct Location
Agent session plans Scratch/<task>/
Agent brain artifacts Nowhere durable — ephemeral
UUID-named files Never — use the naming convention
.DS_Store, Icon\r .gitignore — never tracked
Gemini/Claude recovered files Trash
Agent memory dumps Beads (if work), Trash (if not)
Execution plans per-session Beads, not docs

Naming Convention

All new files: lower-kebab-case.md

Patterns

Type Pattern Example
Dated record YYYY-MM-DD__domain__subject__type.md 2026-10-02__factory__docs-curation__directive.md
Standard STD-DOMAIN-NNN-short-name.md STD-COMM-001-fleet-communication-law.md
ADR ADR-NNNN-short-name.md ADR-0027-upstream-docs-governing-contract.md
Undated doc short-descriptive-name.md contextcontrol-product-plan.md
Playbook domain-action-playbook.md drupal-factory-convergence-playbook.md

Rules

  1. No UPPER_SNAKE for new files. Existing files renamed when touched, not bulk-renamed.
  2. No UUIDs in filenames. Use bead IDs if linking to work.
  3. No spaces in filenames. Use hyphens.
  4. Directories are lower-kebab or CamelCase for products only.

Required Frontmatter

Every .md file MUST have YAML frontmatter:

---
title: "Human-readable title"
type: standard | directive | evidence | audit | receipt | playbook | decision | strategy | research | reference | index
domain: factory | drupal | contextcontrol | infra | governance | protocol | ci | docs
status: draft | active | superseded | archived
bead: "bead-id"          # if linked to work
created: YYYY-MM-DD
updated: YYYY-MM-DD
author: "who wrote it"
---

Required fields

  • title — always
  • type — always
  • status — always
  • created — always

Optional fields

  • domain — when not obvious from path
  • bead — when linked to a work item
  • updated — when modified after creation
  • author — when attribution matters
  • superseded_by — when status is superseded

QMD Indexing

All documents must be discoverable by QMD. This happens automatically if:

  1. The file is in this repository
  2. The file has valid YAML frontmatter
  3. The file is committed (not untracked)

Run qmd status to verify indexing health.

Agent Rules

  1. Search before creating. qmd query "topic" first.
  2. One home per document. If it exists elsewhere, link, don't copy.
  3. Promote, don't dump. Scratch/<task>/ → curate → BluCity-Docs/ with proper frontmatter.
  4. Evidence is immutable. Once in ledger/evidence/ or ledger/receipts/, do not edit. Append corrections as new files.
  5. Standards require governance. Do not edit Engineering-Standard/standards/ without an ADR or operator directive.