Summary
AGENTS.md documents the configuration resolution order but omits .apache-magpie-local/,
the highest-precedence layer. The string does not appear in the file at all, while 59 skill files
already consult that directory. Add it.
Background
.apache-magpie-local/ is the personal, gitignored override layer: a per-person sibling to the
committed .apache-magpie-overrides/. It is read at runtime, it may add a person's paths,
wording or capability enablement, and it cannot weaken the safety, confidentiality or privacy
baseline. PR #841 documented it in tools/spec-loop/specs/adoption-and-setup.md with the
precedence:
.apache-magpie-local/ -> .apache-magpie-overrides/ -> organization defaults -> framework default
AGENTS.md § Configuration resolution order still shows a chain starting at
<project-config>/project.md with no mention of the local layer. Since AGENTS.md is the file
agents load first and presents itself as authoritative on where config values come from, an agent
reasoning about a value's origin does not know the top layer exists.
Note the two chains describe slightly different things — the AGENTS.md one is about
placeholder and dotted-key resolution through project.md and organization manifests, the spec
one is about per-skill override files. Making that relationship clear is part of the job; a bare
insertion into the existing code block may not be the clearest fix, and a short paragraph plus a
pointer to the spec section is equally acceptable.
Where to look
AGENTS.md § Configuration resolution order — the fenced text block showing the chain,
and the paragraphs around it.
tools/spec-loop/specs/adoption-and-setup.md — search for apache-magpie-local; this is the
authoritative description to summarise, including the additive-only guardrail.
skills/pr-management-code-review/SKILL.md § Adopter overrides — a live example of a skill
consulting both layers in the documented order.
Acceptance criteria
Estimated effort
~1 hour for someone new to the codebase.
Getting started
[How to contribute](https://github.com/apache/airflow-steward/blob/main/CONTRIBUTING.md#your-first-contribution)
This issue was drafted with the help of an AI-assisted tool and reviewed by a Magpie maintainer before posting. If anything here is unclear or looks wrong, say so on the issue: a real person is reading.
Summary
AGENTS.mddocuments the configuration resolution order but omits.apache-magpie-local/,the highest-precedence layer. The string does not appear in the file at all, while 59 skill files
already consult that directory. Add it.
Background
.apache-magpie-local/is the personal, gitignored override layer: a per-person sibling to thecommitted
.apache-magpie-overrides/. It is read at runtime, it may add a person's paths,wording or capability enablement, and it cannot weaken the safety, confidentiality or privacy
baseline. PR #841 documented it in
tools/spec-loop/specs/adoption-and-setup.mdwith theprecedence:
AGENTS.md§ Configuration resolution order still shows a chain starting at<project-config>/project.mdwith no mention of the local layer. SinceAGENTS.mdis the fileagents load first and presents itself as authoritative on where config values come from, an agent
reasoning about a value's origin does not know the top layer exists.
Note the two chains describe slightly different things — the
AGENTS.mdone is aboutplaceholder and dotted-key resolution through
project.mdand organization manifests, the specone is about per-skill override files. Making that relationship clear is part of the job; a bare
insertion into the existing code block may not be the clearest fix, and a short paragraph plus a
pointer to the spec section is equally acceptable.
Where to look
AGENTS.md§ Configuration resolution order — the fencedtextblock showing the chain,and the paragraphs around it.
tools/spec-loop/specs/adoption-and-setup.md— search forapache-magpie-local; this is theauthoritative description to summarise, including the additive-only guardrail.
skills/pr-management-code-review/SKILL.md§ Adopter overrides — a live example of a skillconsulting both layers in the documented order.
Acceptance criteria
AGENTS.mdnames.apache-magpie-local/and states that it takes precedence over.apache-magpie-overrides/.confidentiality or privacy baseline).
clear to a reader who knows neither.
prek run --all-filespasses, including the lychee link check if you add links.Estimated effort
~1 hour for someone new to the codebase.
Getting started
[How to contribute](https://github.com/apache/airflow-steward/blob/main/CONTRIBUTING.md#your-first-contribution)
This issue was drafted with the help of an AI-assisted tool and reviewed by a Magpie maintainer before posting. If anything here is unclear or looks wrong, say so on the issue: a real person is reading.