Skip to content

Where Knowledge Lives — and How Agents Use Gas City Primitives

Read this before writing any document, creating any formula, or repeating any procedure.

Source: BLU authority note, 2026-09-21 (bead bc-pk2k). Verbatim, not paraphrased.

Law 1: Where Knowledge Lives

THIS WORKSTATION IS NOT AUTHORITY. It is ephemeral, it is one machine, and it is temporary.

Location Status Rule
~/.claude / ~/.gemini / any local dotfile ❌ FORBIDDEN for doctrine Hidden, single-machine, ephemeral, invisible to every other agent and to CI
Scratch files ❌ STAGING ONLY Nothing routes it, nothing indexes it. Not the durable home
Session transcripts ❌ NOT STATE A chat receipt is not state
BluCity-Docs ✅ ENGINEERING AUTHORITY Cross-project standards, doctrine, policy, canonical knowledge that outlives any one project
project .agents/ ✅ PROJECT OPERATING CONTEXT Lives IN the repository it governs, travels with the code
Gas City Beads ✅ DURABLE WORK RECORD The execution ledger — not prose, not a transcript
Gas City Formulas ✅ DURABLE METHOD Repeatable procedure, not a session memory
Gas City Orders ✅ DURABLE TRIGGER Recurring work — not a remembered habit

If two projects would both need it → BluCity-Docs.
If it governs one project → .agents/ in that repo.
If it is how work is done → Formula.
If it recurs → Order.
Never a dotfile. Never scratch as the authority.

Law 2: Use Gas City Primitives

2.1 Gas City is the execution layer — not a session habit

Primitive What it does When to use
Bead Remembers work Every piece of work that matters
Formula Remembers the method Any repeatable multi-step procedure
Order Automates when Formulas run Any recurring trigger (cron, event, cooldown)
Mail Coordinates between agents Cross-agent handoffs and findings
Session Executes (then disappears) On-demand work sessions — workers are NOT always-on
Event Proves what happened Observation, not authority

Stop inventing when an answer already exists. If a Formula already encodes the method, execute it. If an Order already triggers it, trust it. Do not re-derive.

2.2 Session discipline

  • On-demand sessions are created for work and die when idle. This is correct behavior.
  • Always-on sessions are declared as named sessions and stay available for conversation.
  • Coordinators are always-on. Workers are not.
  • STOP KEEPING EVERY WORKER ALIVE IN A TERMINAL.

2.3 Session routing rule

BEFORE ROUTING, CHECK SESSION AGE AND SIZE. Route to a NEW session, not the one that answers fastest.

A fast reply from a session that has been running for hours means it has all the context — and that is a trap, not a signal. The over-long session answers fastest because it has accumulated state. That selects for the most exhausted session every time.

When an agent says it needs to rotate, that is a stop condition, not a negotiation.

Authority Order (binding)

When sources conflict, apply this order. Stop inventing when an answer already exists.

  1. UPSTREAM DOCS — Gas City docs, Drupal core and contrib, the Drupal AI Initiative. If upstream defines it, upstream wins.
  2. BluCity-Docs — THE BIBLE after upstream. Bluefly engineering authority: standards, doctrine, product direction, ADRs.
  3. CURRENT SOURCE AND RUNTIME — outranks stale prose when they conflict. A live response beats documentation about a binary.
  4. Everything else is derived and non-authoritative: session transcripts, local dotfiles, scratch files, memory.

When they conflict: record the contradiction, do not silently average it.

Tag evidence as:

PROVEN_IN_RUNTIME
CURRENT_SOURCE
CANONICAL_POLICY
CURRENT_PRODUCT_DIRECTION
ASPIRATIONAL
HISTORICAL
NOT_ESTABLISHED

Trust Boundary

This belongs in every Pack and Formula review:

  • City config and imported Packs → TRUSTED CODE
  • Bead titles, descriptions, mail, formula vars, merge request text, API request fields → UNTRUSTED DATA

NEVER CONCATENATE BEAD TEXT OR MAIL INTO A SHELL COMMAND.
Pass through argv, stdin, JSON, environment, or typed API parameters.

The Structural Defect This Doctrine Fixes

"I have been writing doctrine into Beads all day that should have been read out of BluCity-Docs first. That is the same failure as rebuilding a formula that already existed, one layer up." — BLU, 2026-09-21

The defect is not incidental — it is structural: - A session with 200k+ context answers fastest - The coordinator routes to whoever replies first - This selects for the most exhausted session every time - The session was applying the coordinator's own standard back at the coordinator

The fix is this document existing, indexed, and read at session start — not re-derived each time.

Acceptance Criteria (from bead)

  • No agent writes doctrine to a local dotfile
  • Recurring work exists as an Order rather than a remembered habit
  • Deterministic detection is exec; models are invoked only after evidence says judgment is needed
  • Every closed material Bead states its capability impact