Project Context Loading — Coexistence & Override Rule

This is the foundational rule for all agents in dev-team-agents. Read and apply it before acting on any task.

Core Principle

The dev-team-agents standards are the base layer. Any rule, pattern, or convention defined explicitly in the project overrides our base. We provide the floor — the project sets the ceiling.

This means every agent must:

Load and understand the project's own context
Identify where the project has explicit conventions
Apply project conventions where they exist; apply base standards where they don't

First-Time Setup Guard

Trigger: [DEVTEAM:FIRST_TIME_SETUP] at the start of a session. Stop immediately — before loading any other context or answering the original prompt — and load the full guard: skills/shared/project-context/references/first-time-setup.md

Language Policy

Documents — Always English

All generated documents, code comments, commit messages, and technical output must be written in English.

This applies to:

Architecture documents (docs/development/)
Backlog items, sprint plans, and estimates (docs/backlog/)
API contracts, code standards, design system docs
Changelog entries and PR descriptions

Exception: if the user explicitly requests a document in another language (e.g., "write this in Portuguese"), honor that request for that specific document only. Default always reverts to English.

Conversation — User's Preferred Language

All responses directed at the user — including plans presented for approval, explanations, questions, confirmations, and notifications — must use the language in .dev-team-agents/resolved/preferences.json → language field.

Read this value at the start of every session:

python3 -c \
  "import json; d=json.load(open('.dev-team-agents/resolved/preferences.json')); print(d.get('language','en'))" \
  2>/dev/null || echo "en"

If preferences.json does not exist or is unreadable, default to English and emit a warning notification prompting the user to configure preferences.

This rule applies to: explanations, questions, confirmations, summaries, notifications, and all user-facing text. It does NOT apply to document content, code comments, or commit messages. Writing an English commit or session summary does not switch the conversation: the closing message of a task stays in the user's language. A [DEVTEAM:LANGUAGE] line (restated on every prompt by the UserPromptSubmit hook) carries the same value — follow it.

Fixed messages in commands. Two wordings, two meanings:

Wording	Meaning
`output exactly` / `print exactly`	A fixed message for the user: say exactly that, in the user's language. Code, paths, versions, commands, placeholders, emoji and table structure stay as written
`output verbatim`	Byte-for-byte: a script's output passed through, or any line a later step parses (`PATCHED <path>`). Never translated

A command author picks verbatim only for the second case; helpers/agent-lint.sh fails a command that says output exactly for what a script prints.

Notifications (context window, stale config, tips) are raised by hooks and shown by the desktop app — never print a DEV TEAM AGENTS box. skills/shared/notifier/SKILL.md says what raises what, and how a hook adds a new one.

Mandatory Plan Mode — No Silent Execution

Load skills/shared/plan-mode/SKILL.md before executing any non-trivial task. It owns the full when-a-plan-is-required table, the plan format, and the approval protocol — do not restate it here.

Memory Layers

This is the canonical map of the project's memory. Every artifact below has exactly one job. Agents route by it; they do not restate it.

Layer	Artifact	Holds	Lifespan
Structural	`docs/project.md`, `docs/development/*.md`	Current state: stack, architecture, standards	Rewritten in place — always describes now; a document that no longer does carries the `docs-sync` § Document Lifecycle marker
Episodic	`<memory-dir>/session-summary.md` (`.dev-team-agents/memory-dir` pointer → portable memory)	What happened, in order	Decays (rotation policy below)
Semantic	`docs/wiki/`	What isn't derivable from the code	Permanent; superseded, never deleted
Decisional	ADR directory (`new-adr.sh --dir`) + its `README.md` index	Why a hard-to-reverse choice was made	Permanent and immutable
Mechanical	`graphify-out/graph.json`	Where things are in the code	Regenerated — never hand-written

Routing — which layer gets this?

Three questions, in order. The first "yes" wins:

Is it derivable by reading the code? → None of them. Do not write it down. This is the rule that keeps memory from becoming a second, aging source of truth that contradicts the repository.
Is it a hard-to-reverse choice with non-obvious reasoning? → ADR.
Will it still be true after this sprint? → Wiki if it's knowledge, structural docs if it's current state. If no → session summary, and let it decay.

A single finding lands in one primary layer. It may be referenced from another; it is never copied into one.

/devteam:learn is the promotion path from episodic to the durable layers, and the Promotion Guard below is what stops the episodic layer from expiring with unpromoted knowledge in it.

Context Loading Order

Before starting any task, load context in this order (read what exists — skip what doesn't):

1. README.md                              ← project overview, setup, conventions
2. CLAUDE.md                              ← Claude-specific rules (highest precedence)
3. docs/project.md               ← synthesized project overview; if present, use it to
                                             orient fast before reading individual dev files
4. <memory-dir>/session-summary.md        ← last session's decisions and next steps; read the
                                             most recent entry (top of file). See `layout` below
5. ADR directory (README.md)     ← ADR retrieval index; grep it for the task's keywords —
                                             directory resolved by `new-adr.sh --dir`
6. AGENTS.md                             ← agent-specific instructions for this project
7. .claude/settings.json                 ← Claude Code configuration
8. .agents/ (directory)                  ← project-level agent overrides
9. docs/development/             ← architecture, code-standards, tech-stack
10. docs/backlog/                ← current sprint and task context
11. docs/wiki/README.md          ← retrieval index; grep it for the task's keywords and
                                             open only the entries that match
12. extra context_paths                   ← additional knowledge folders this project declares;
                                             read-only, and only what the task needs

Steps 4 and 12 resolve through the project's own configuration, not a fixed path.

.dev-team-agents/project.json (committed) declares where this project's knowledge lives:

{ "schema": 1, "project_id": "…", "layout": 2, "context_paths": ["docs", "rfcs"] }

context_paths — the first entry is the write root (docs by default, which is what every path above assumes). Any additional entry is an extra knowledge folder, read-only: read from it when the task's subject matter is there, and never write to it. A folder that is not listed is not project knowledge, however suggestive its name.
layout — where the project's own state lives. Layout 1 means .dev-team-agents/user-data/ (both machine-local state and portable memory together). Layout 2 means the data store, with two one-line pointer files: .dev-team-agents/state-dir (machine-local state directory) and .dev-team-agents/memory-dir (portable memory directory). Read the pointers rather than guessing paths; scripts/lib/state.sh already resolves them for every bash caller.

context_paths is topology, not preference — it is committed so every developer on the project reads the same folders. Preferences are personal and never committed; see § User Preferences.

When docs/project.md exists, it provides a pre-synthesized orientation (stack, active areas, key constraints) that reduces the need to read multiple raw files from scratch. Read it at step 3, then load only the specific development/ files relevant to the current task instead of reading the entire directory.

After reading project.md, find its freshness date: the canonical form is  on line 1, but accept a last-updated: YYYY-MM-DD line in either form anywhere in the first five lines — an exact-line-1 match silently skipped every project that wrote the date differently, so a two-month-old overview never warned. If the date is more than 30 days in the past, or no date can be found, include this warning at the top of your first response:

⚠️ project.md may be stale (last updated: YYYY-MM-DD — or "no date found"). Consider running setup-assistant in REFRESH mode to bring it up to date.

When <memory-dir>/session-summary.md exists (path resolved via .dev-team-agents/memory-dir pointer on layout 2, or .dev-team-agents/user-data/ on layout 1), read only the most recent entry (the topmost ## YYYY-MM-DD block). It captures what was done last session, decisions made, and what comes next — use it to avoid re-asking questions that were already resolved.

When the ADR directory exists (docs/development/adrs/, or docs/adr/ in a project that uses it — new-adr.sh --dir resolves it), read its README.md index and match the task's keywords against the Keywords column, exactly as for the wiki below; open the ADRs that hit and skip rows whose status is Superseded unless the task is about the superseded behavior. With no index — and for any ADR file the index has no row for — fall back to listing the files and reading any ADR whose title is relevant. This prevents contradicting or duplicating past architectural decisions. The index format is skills/shared/adr/SKILL.md § ADR Index.

When docs/wiki/README.md exists, read that index — and only that index. Derive two or three keywords from the task (domain nouns, component names, the error being chased) and match them against the Keywords column; open only the entries that hit. Never load the wiki directory: the index exists precisely so that context cost stays flat as the wiki grows. An empty match set is a valid result — proceed without opening anything.

This is the wiki's read path. Writing entries is skills/shared/docs-sync/references/wiki-format.md, which owns the index row format the lookup depends on.

Read each file that exists. Combine the information into a unified understanding of the project before acting.

Trivial-task exception: when the task qualifies as a Small change under skills/shared/plan-mode/SKILL.md § Plan Size (or is a typo fix that needs no plan at all), skip this loading order entirely and load only CLAUDE.md plus the target file. Fall back to the full order the moment the task stops qualifying — the same moment plan-mode's upgrade rule fires.

Focused tier: between a Small change and the full order. It applies when the task stays inside one layer or area the request already names (one feature's backend, one screen, one script), raises no architectural question, and touches no public contract. Load:

Step	Focused load
2, 6, 8	The provider's instruction files (`CLAUDE.md`, `AGENTS.md`) and `.agents/` — project rules and overrides, always in full
1, 3	`docs/project.md`; `README.md` only when `project.md` is absent
4	The most recent session-summary entry
5	The ADR index keyword lookup (titles only when there is no index); open an ADR only when its row names the area
9	Only the `docs/development/` file the layer needs — `code-standards.md` for code — plus every unscoped `reuse-guidelines.md` row and the rows whose `scope` matches the paths you will touch
11	The wiki index keyword lookup, as in the full order

Skip 7, 10 and 12 — unless the task comes from a sprint file, then read that one file. Escalate to the full order the moment the task crosses a second layer, needs a design choice, changes a contract, or a loaded source points somewhere you have not read. When unsure which tier applies, use the full order.

Session Summary — Write Rules

Trigger: you are about to write or trim the session summary file (resolved via .dev-team-agents/memory-dir). Load the full write rules (multi-agent append format, rotation policy, Promotion Guard) before doing so: skills/shared/project-context/references/session-summary-write-rules.md

Contradiction Guard

Automatically enforced by all agents. Load details on-demand: skills/shared/project-context/references/contradiction-guard.md

Wiki Knowledge Base

Every project gets a wiki at docs/wiki/. Load full protocol: skills/shared/project-context/references/wiki.md

Override Logic

When a conflict exists between our base standard and a project convention:

Scenario	Rule
Project CLAUDE.md defines a code style	Use the project's style
Project uses tabs, we recommend spaces	Use tabs
Project has no defined convention	Apply our base standard
Project explicitly states "do not use X"	Never use X, even if we recommend it
Project is ambiguous or silent on a topic	Apply our base standard and note the assumption

Explicit beats implicit. A project convention must be clearly stated to override a base standard — don't infer overrides from one or two examples.

Between project sources

The table above settles base standard against project. Two project sources against each other follow these rules:

Scoped narrows global within the same source. A registry row with a scope (or a section a document explicitly limits to an area) refines a repository-wide rule of the same source for files inside that scope — e.g. a scoped reuse-guidelines.md row over an unscoped one. It says nothing about files outside its scope.
Across sources there is no fixed ranking. The instruction files (CLAUDE.md, AGENTS.md, .agents/), ADRs, specs, and docs/development/ standards never outrank each other by position — a scoped rule in one does not silently beat a global rule in another. When two of them disagree on what a task should do, flag both through the Contradiction Guard and let the user decide. Then update the losing source through its own change process — a superseding ADR (skills/shared/adr/SKILL.md), a spec Amendment Log entry (skills/shared/spec-gate/SKILL.md), an edit to an instruction file or standards doc — so the conflict does not recur.

Immutability Warning

Trigger: a user asks to modify any file inside .dev-team-agents/. Load the full warning text before responding: skills/shared/project-context/references/immutability-warning.md

Applying Combined Context

When base standard and project context are both present, produce output that:

Follows the project's conventions for naming, style, structure, and tools
Fills gaps with our base standards
Explicitly calls out assumptions: "No convention found for X in project context — applying base standard: [rule]"

Example: if the project uses PHPDoc for all methods but our base standard says "only when WHY is non-obvious", follow the project — it has an explicit convention.

Interaction Patterns — Quiz-first Rule

Load skills/shared/interaction-patterns/SKILL.md before asking the user any question.

The skill defines when and how to use the AskUserQuestion tool (quiz format with Yes/No, multiple-choice, or "Other" for open input) instead of plain text prompts. Apply it to every confirmation, choice, and gate in your workflow.

Test Execution — Scoped by Default

Load skills/shared/scoped-test-execution/SKILL.md before running any test command.

This binds every agent, not only the test specialists. If your task ends with you invoking a test runner — implementing, fixing, refactoring, reviewing, or validating — you run only the tests covering the code you touched. The project's full suite runs on one signal and one only: the user asking for it in this session.

Situation	What runs
You changed code and want to verify it	Tests covering the change and its direct dependents
A scoped test failed	Fix it — a failure never authorizes widening the run
The change touches shared code, or the suite is fast	Still scoped. Neither is an escalation signal
The request is vague ("make sure nothing broke")	Still scoped. Offer the full run; do not start it
The user explicitly asked for the whole suite	Full suite
A CI pipeline is executing	Full suite — this rule governs local runs only and never constrains a pipeline

Load the skill for the blast-radius derivation and the per-stack runner filters. Do not work from this table alone.

Quality / Security Scanners

Detect and load the appropriate skill when any scanner config is present:

Detection	Skill to load
`sonar-project.properties`, `.sonarcloud.properties`, or `SONAR_TOKEN` env var	`skills/devops/sonarqube/SKILL.md`

When loaded, the scanner skill governs: quality gate reporting, security hotspot handling, coverage thresholds, and how findings surface in reviews and QA reports.

Development Environment

Detect and load the appropriate skill when the environment signal is present:

Detection	Skill to load
`docker-compose.yml`, `docker-compose.override.yml`, or `compose.yml` at the root	`skills/devops/docker-dev/SKILL.md`

When loaded, that skill governs the command execution contract: every command runs inside the container, which compose form to use, and the explicit-host exception.

Remote Environment Credentials

When a task requires accessing a remote environment (staging, production, QA, etc.):

Load skills/shared/credentials/SKILL.md and follow its instructions
Read credentials from .dev-team-agents/credentials.local.json in the main checkout (resolve its path as skills/shared/credentials/SKILL.md § How to Use describes)
If fields are empty, ask the user for access details
Read-only by default — ask permission before any write/execute operation

This applies to SSH, database, HTTP/HTTPS, Docker, Kubernetes, and any other remote access.

What Counts as "Project Context"

Explicit rules in CLAUDE.md, README.md, AGENTS.md
Existing code patterns (if consistent across 3+ files, treat as a convention)
Linter/formatter config files (.eslintrc, phpcs.xml, .prettierrc, pyproject.toml, etc.)
CI/CD config that enforces checks (failing lint = enforced rule)
Architecture docs in docs/development/

What does not count:

One-off examples in a single file
Commented-out code
TODO comments

project-context

SKILL.mdskills/shared/project-context/SKILL.md