Skip to content

Documentation Production Rule

Knowledge Hierarchy

Bluefly has three knowledge layers. Each layer owns a different level of knowledge. Agents may ONLY author documentation at the correct ownership level.

BluCity-Docs (Organization Knowledge — evergreen)
    ↓
Repository Context (.agents/context/ or repo-local docs)
    ↓
Task Context (Issues, Beads, ADRs, MRs, Scratch)

Authoritative factory ownership for documentation is also stated in the Bluefly Factory Operating Contract (One authority).

Layer 1: BluCity-Docs (Organization Knowledge)

Single source of truth for evergreen engineering knowledge:

  • Engineering Standards
  • Architecture
  • Operating Contracts
  • Runtime Standards
  • Infrastructure Standards
  • Platform Governance
  • Canonical Runbooks
  • Ownership Models
  • Design Decisions
  • Gas City / Pack Architecture (Gas Town is predecessor/pack, not a parallel primitive set)
  • Documentation Standards
  • Security Standards
  • Naming Standards
  • Capability Ownership

Repositories MUST NOT redefine these. They reference them.

Engineering Storage path: BluCity-Docs under Engineering Storage (NAS). Scratch is not Layer 1. Scratch is disposable temporary work.

Chat transcripts, AI memory/context, Cursor/Claude session output, canvases, writing artifacts, generated audit views, and local scratch documents are also not Layer 1 authorities. When they contain durable engineering knowledge, that knowledge must be curated into the existing BluCity-Docs owner document. Do not keep a parallel durable copy merely because an assistant generated it.

Layer 2: Repository Context

Every managed repository MUST contain repository-local implementation knowledge (commonly .agents/context/). This explains the implementation of THAT repository. Never the organization.

Standard files (when the repository uses .agents/context/):

File Purpose
INDEX.md Entry point and file manifest
PROJECT.md Purpose, scope, what repo owns, what it does NOT own
ARCHITECTURE.md Repository architecture only — never enterprise architecture
BOUNDARIES.md Ownership contract: owns, consumes, implements, never-owns
DEPENDENCIES.md External systems, APIs, packs, services, products
COMMANDS.md Canonical build, test, release, development commands
ROADMAP.md Repository-specific future work
KNOWN_ISSUES.md Technical debt, open migrations, current architectural concerns

Repository docs own only: API docs, package usage, repo onboarding, repo config, and repo-specific implementation. Repositories do not own platform architecture.

Layer 3: Task Context and Scratch

Issues, Beads, ADRs in flight, Merge Requests, Scratch content, AI-session output, and generated working artifacts are temporary.

Scratch owns: investigations, migration notes, implementation plans, design exploration, temporary runbooks, execution receipts, research.

These NEVER become permanent doctrine by default. Promote durable findings into BluCity-Docs, then leave Scratch and assistant/session artifacts disposable.

Ownership Decision Tree

Before creating any documentation, agents MUST follow this decision tree:

  1. Search BluCity-Docs for an existing authoritative document on the topic.
  2. If it exists → update, improve, consolidate — do not create another version.
  3. If multiple docs cover the same topic → merge, eliminate duplicates, redirect obsolete docs, archive redundant copies.
  4. If durable knowledge exists only in chat, AI memory, a canvas, Scratch, an MR description, or an agent transcript → curate it into the existing BluCity-Docs owner; do not create a side authority.
  5. Does this repository own only the implementation detail? → YES → Add to repository context.
  6. Is it temporary investigation or a receipt? → Scratch (or the active Bead / MR).
  7. Neither Layer 1 nor Layer 2? → Create a task or ADR proposing the correct owner.

Never create: architecture-v2.md, architecture-final.md, architecture-new.md, architecture-revised.md, or any parallel-named competitor.

Objective: one authoritative document per engineering concept.

No documentation may duplicate another owner.

Placement Rules

  • Evergreen engineering knowledge → BluCity-Docs
  • Temporary work / receipts → Scratch (or Bead / MR evidence)
  • Repository implementation knowledge → owning repository
  • Operational work state → Gas City / Beads
  • Runtime state → the Runtime Platform
  • Secrets → 1Password
  • AI/chat/canvas knowledge with durable value → curate into the existing BluCity-Docs owner, then treat the side artifact as disposable

Prohibited

  • Writing platform architecture into repository READMEs as a second home
  • Writing evergreen contracts into automation memory or agent transcripts
  • Creating competing copies outside BluCity-Docs
  • Treating Scratch content as authoritative without promotion
  • Treating an AI-generated canvas, chat artifact, or assistant memory as a permanent documentation authority
  • Creating a new BluCity-Docs file when an existing owner can be improved instead
  • Saving evergreen documentation, operating contracts, or Engineering Standards under ~/.cursor, any workspace .cursor tree, or any other .cursor path (IDE projection only)

Docs agent completion

Docs agents are in scope of the Git Completion Contract (ES-GITCC).

A drafted page in a worktree is not done. A local commit is not done. A pushed docs branch is not done. An open docs MR is not done. A green docs MR is not done.

If you modified tracked documentation and the change is valid: commit it, push it, open or update an MR to release/v0.1.x, and merge it when CI is green, conflict-free, and acceptance criteria pass. Do not end a docs session with finished valid work uncommitted. That is the same defect as a polecat-done handoff push-step gap.