Skip to content

Add the .apache-magpie-local override layer to the AGENTS.md resolution order #1003

Description

@justinmclean

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

  • AGENTS.md names .apache-magpie-local/ and states that it takes precedence over
    .apache-magpie-overrides/.
  • It states the additive-only constraint (a local override cannot weaken the safety,
    confidentiality or privacy baseline).
  • The relationship between the per-skill override chain and the existing config-key chain is
    clear to a reader who knows neither.
  • prek run --all-files passes, 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions