STD-REPO-002 — Bluefly Project Context Contract

Scope: Every active Bluefly source repository. Authority: Canonical. Enforced by shared CI component (gitlab_components/jobs/validate-project-context.yml). Enforces: §9–§16, §23–§26, §50, §52 of the Bluefly Repository Context and Documentation Convergence Directive. Companion playbook: project-context-convergence Companion formula: blucity-packs/formulas/project-context-converge.yaml

---

1. Fundamental Knowledge Placement Rule

For every document, file, instruction, rule, or evidence, ask:

If this repository disappeared tomorrow, who would still need this information?

Only developers/operators of this project
    → PROJECT REPOSITORY

Every Bluefly project
    → BluCity-Docs / Engineering-Standard

People executing a repeatable operational procedure
    → BluCity-Docs / Playbooks

Agent currently executing work
    → Gas City / Beads

Evidence about a specific implementation/change
    → Project + GitLab + receipt

Reusable Agent / Skill / Plugin
    → AgenticTools (agents / skills / plugins)

Reusable Gas City configuration
    → BluCity-Packs or DrupalWorks

Governed human/customer context
    → ContextControl

This placement test is binding. When in doubt, route to the narrowest correct owner.

---

2. Required Project Structure

Do not create empty directories to satisfy aesthetics. A directory exists only when the project actually uses that capability.

project/
├── README.md             ← required
├── AGENTS.md             ← required
├── CLAUDE.md             ← required (thin adapter only — see §5)
├── llms.txt              ← required (discovery index — see §6)
├── OWNERSHIP.md          ← required
├── CHANGELOG.md          ← required where release lifecycle justifies it
│
├── docs/                 ← required if project has architecture / decisions
│   ├── README.md
│   ├── architecture/
│   ├── decisions/
│   ├── operations/
│   └── reference/
│
├── .agents/              ← required if agents operate in this repo
│   ├── README.md
│   └── context/          ← see §7
│
└── .gitlab/              ← required
    └── merge_request_templates/

Vendor files (GEMINI.md, .codex, .cursor, .opencode) are conditional — create only when the project's active tooling requires them. They are adapters, not authorities (see §5.4).

---

3. README.md Contract

Every repository must have a concise human entry point. README must establish:

NAME
ONE-SENTENCE PURPOSE
OWNER
PROJECT TYPE
STATUS
WHAT IT OWNS
WHAT IT DOES NOT OWN
QUICK START
TEST / VALIDATION COMMAND
RELEASE / DEPLOYMENT SUMMARY
PROJECT DOCS ENTRY POINT  → docs/
AGENT ENTRY POINT         → AGENTS.md
UPSTREAM / DOWNSTREAM DEPENDENCIES

Do not embed entire architecture in README. Link to docs/.

---

4. AGENTS.md Contract

AGENTS.md is the canonical project-local AI and developer instruction entry point. It must be small.

Must contain:

project identity
project boundary
what this repo owns
what it does not own
source-of-truth locations
where architecture lives (→ docs/architecture/)
where project decisions live (→ docs/decisions/)
how to build / test / validate
GitLab target branch and release rules
work authority reminder (Beads / Gas City)
organizational context retrieval instructions (→ BluCity-Docs, not copied text)
generated-file warning where applicable

Must NOT contain:

entire Engineering Standard pasted in
all Gas City documentation
hundreds of lines of generic Bluefly law
full agent persona definitions
shared Skills or Plugins
live Bead backlog
temporary handoff state
incident transcripts
session memory

Rule: AGENTS.md tells the agent WHERE authority lives. It does not copy authority into itself.

---

5. AI File Contracts

5.1 CLAUDE.md — Compatibility Adapter

CLAUDE.md is a thin compatibility adapter. Target length: ≤ 20 lines.

# Claude Code

Read AGENTS.md first. AGENTS.md is the authoritative repository instruction entry point.

Use project-local docs/ for project-specific context.
Use the governed BluCity-Docs retrieval path for organizational standards.

Do not treat this file as an independent source of architecture,
policy, work state, agent identity, or operational truth.

If Claude Code requires generated compatibility content, generate it from AGENTS.md. Do not author duplicate policy manually in CLAUDE.md.

5.2 GEMINI.md — Compatibility Adapter

Same contract as CLAUDE.md. Thin adapter only. Create only if Gemini tooling is actively used in this repository.

5.3 Other Vendor Files (.codex, .cursor, .opencode)

• Create only when the project's active tooling requires them.
• Content must be generated from AGENTS.md + canonical context, not independently authored.
• Classified as: GENERATED=YES, AUTHORITATIVE=NO, SOURCE_AUTHORITY=AGENTS.md.
• Never contain duplicate Bluefly policy, doctrine, or architecture.

5.4 Vendor File Enforcement Rule

VENDOR_FILE_AUTHORING=MINIMAL
VENDOR_POLICY_AUTHORITY=NO
VENDOR_ARCHITECTURE_AUTHORITY=NO

A vendor file that accumulates original doctrine is a standard violation. Fix by moving content to AGENTS.md or docs/ and leaving a pointer.

---

6. llms.txt Contract

Every meaningful project must expose a compact llms.txt. Its job is discovery, not memory.

It must identify:

project purpose
README
AGENTS.md
architecture index (→ docs/architecture/)
decisions index (→ docs/decisions/)
API / reference entry points
important source directories
upstream standards references (link to BluCity-Docs, do not copy)

llms.txt must not duplicate the entire docs corpus. It is a map.

---

7. .agents/context/ Contract

project/.agents/context/ holds project-specific machine-consumable context that agents need to act correctly in this repository.

Required file: .agents/context/README.md — must answer four questions:

WHAT IS THIS CONTEXT?
WHO OWNS IT?
HOW FRESH IS IT? (updated_at)
WHERE DOES ITS SOURCE TRUTH LIVE?

Permitted content:

architecture-map.md         ← system overview, runtime model, integration boundaries
project-boundaries.md       ← what this repo owns and does not own
testing-context.md          ← test matrix, validation commands
integration-context.md      ← external dependencies and integration notes
project-glossary.md         ← project-specific terms only

Prohibited:

Doctrine copied from BluCity-Docs
Shared Agent definitions (→ AgenticTools/agents)
Shared Skills (→ AgenticTools/skills)
Shared Plugins (→ AgenticTools/plugins)
Runtime caches or generated indexes as authority
Agent transcripts or session memory
Live Bead state (→ Gas City)

---

8. Document Metadata Standard

Governed project Markdown documents that participate in generated indexes must use standardized front matter:

---
title:
document_id:
type:          # architecture | decision | standard | playbook | reference | runbook | audit
authority:     # canonical | project-local | generated | historical
owner:
scope:
created_at:
updated_at:
review_by:
supersedes:
superseded_by:
tags: []
---

Rules: - UPDATE updated_at on every substantive change. - DO NOT alter created_at. - status: superseded or status: archived documents must declare superseded_by. - Draft, research, generated, superseded, and archived material cannot override a current canonical source.

---

9. Duplication Law

For every duplicate or near-duplicate found:

SOURCE_A=
SOURCE_B=
EXACT_DUPLICATE=
UNIQUE_CONTENT_A=
UNIQUE_CONTENT_B=
CANONICAL_OWNER=
DISPOSITION=    # MERGE_INTO_CANONICAL | PROJECT_LOCALIZE | PROMOTE_TO_STANDARD |
                # SUPERSEDE | DELETE_AFTER_PROOF

Two copies of the same doctrine are two authorities. Do not leave both.

---

10. Stale Context Law

Every context-bearing document must answer:

WHO OWNS THIS?
WHAT IS ITS AUTHORITY?
WHEN WAS IT LAST UPDATED?
WHAT SUPERSEDES IT?
WHEN SHOULD IT BE REVIEWED?

A document that cannot answer these questions is unclassified. Classify it or delete it.

---

11. Context Budget Rule

Agents must be able to operate a repository without loading all of BluCity-Docs.

Targets:

AGENTS.md         = concise routing map (≤ 150 lines for most repos)
CLAUDE.md         = tiny adapter (≤ 20 lines)
llms.txt          = discovery index (≤ 50 lines)
project docs      = targeted retrieval on demand
shared standards  = retrieved from BluCity-Docs on demand via QMD / ContextControl
vendor projections = minimal / generated

Do not copy 5,000-line policy files into every project. Do not require a new developer or agent to load all of BluCity-Docs to understand one repository.

---

12. Knowledge Promotion Lifecycle

LOCAL FINDING
    ↓
PROJECT DOCUMENT / BEAD
    ↓
PROVEN REUSABLE?
    NO → stays project-local
    YES ↓
CLASSIFY
    ↓
Engineering Standard / Playbook / Product / Reference
AgenticTools / Gas City Pack or Formula
ContextControl governed context

After promotion, the project document links to the canonical rather than duplicating it.

---

13. Enforcement

This standard is enforced by:

1. Shared CI component: blueflyio/gitlab_components — jobs/validate-project-context.yml
2. Gas City Formula: blucity-packs/formulas/project-context-converge.yaml
3. Manual convergence playbook: project-context-convergence

Violations are Beads, not comments. Create a Bead, implement the fix, close on CI green.