AGENTS.md

README.md is for humans. This file is the always-on agent contract for blueflyio/blu/blucity-docs. Keep it small. Retrieve everything else from llms.txt.

Nested AGENTS.md: closest to the edited path wins for local convention; it may not override this contract, Engineering-Standard, or official upstream. An explicit user prompt overrides all of these.

Canonical source is this GitLab repository on release/v0.1.x. Workstation and NAS checkouts are local views, not authority.

Knowledge Authority & Routing

• Sole Knowledge Authority: BluCity-Docs is the canonical documentation repository. Never store meaningful project documentation in ~/.cursor, ~/.claude, ~/.gemini, agent private memory, /tmp, or random repository roots.
• Knowledge Routing Contract: Mandatory compliance with Engineering-Standard/standards/core/documentation-governance-standard.md Section 7. Search before writing (qmd query). Extend existing canonical files in place.
• Factory Operating Law: Mandatory compliance with Engineering-Standard/operating-model/factory-operating-contract.md (Gas City Native-First Operating Model).
• Cedar Authorization Law: Mandatory compliance with Engineering-Standard/standards/core/cedar-factory-authorization-standard.md (STD-CEDAR-001). Agent prompts are advisory instructions; Cedar PDP policy gates enforce deterministic machine authorization at mutation boundaries.
• Inference Authority: Engineering-Standard/standards/architecture/inference-topology.md — NAS-first model serving topology, port binding, and LiteLLM gateway contract.
• Model Routing Authority: Playbooks/model-routing-architecture.md — semantic capability classes (chat, reasoning, coding, fast, embedding) and routing rules.
• Durable Executive Index: Engineering-Standard/indexes/BLU-BIBLE.md.

Read order

1. This file
2. The nearest nested AGENTS.md to the files you are changing
3. llms.txt, then only the linked files the task needs
4. Workspace .agents/ for skills — do not delete, flatten, replace, or bypass

Execution

• Agent Execution Lifecycle (STD-LIFECYCLE-001) — the governing procedure for every non-trivial task. 50 steps. Session performs. Bead remembers. Formula encodes HOW. Order decides WHEN. Pack distributes. Rig defines WHERE. Events prove. Ends with: "Preserve the factory improvement, discard the Session."
• GC Law: Before building any custom glue, check GC-CLI-CAPABILITY-MAP. Doctrine: GC-OPERATING-DOCTRINE — "Agents should not merely remember work. Systems should remember what agents owe."
• Search before write. Run QMD (or equivalent) for the proposed filename, subject, and owner before creating anything. Prefer update, merge, curate, or delete over a new file. Use qmd search -c drupal for Drupal topics.
• One Bead / one unit of work: Resolve Rig → gc hook --claim → bd show → create worktree → implement → test → commit → push → MR to release/v0.1.x → fix CI → merge → verify canonical state → promote learning → bd close with evidence → remove worktree. See beads-work-ownership-contract.
• Active lifecycle Bead: bc-9qd (P1) — worktree convergence: classify and retire excess Gas City execution surfaces.
• Continue until verified or blocked by a named external authority. Record a blocker once. Do not poll.

Git / GitLab

Hard completion law (docs agents in scope): git-completion-contract (ES-GITCC).

VALID_COMPLETED_WORK + UNCOMMITTED = FAILURE
VALID_COMPLETED_WORK + UNPUSHED = FAILURE
VALID_COMPLETED_WORK + NO_MR = FAILURE
GREEN_MERGEABLE_MR + NOT_MERGED = FAILURE
MERGED_MR + ABANDONED_WORKTREE = CLEANUP_FAILURE

If you modified tracked source and the change is valid: YOU MUST COMMIT IT. If you committed valid work: YOU MUST PUSH IT. If you pushed a feature branch: YOU MUST OPEN OR UPDATE AN MR TO release/v0.1.x. If the MR is green, approved as required, conflict-free, and acceptance criteria pass: YOU MUST MERGE IT TO release/v0.1.x. Do not merely report that it is ready to merge.