Skip to content

docs: document local override precedence #1112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
potiuk merged 1 commit into from
Aug 25, 2026
Merged

docs: document local override precedence #1112

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -317,6 +317,28 @@ Every placeholder and dotted config key then resolves in this order,
→ framework default
```

The chain above resolves placeholders and dotted config keys from the
shared project configuration. It is distinct from the per-skill override
chain used when an adopter tailors a framework workflow:

```text
.apache-magpie-local/<skill>.md
→ .apache-magpie-overrides/<skill>.md
→ organization defaults
→ framework default
```

`.apache-magpie-local/` is the personal, gitignored layer and takes
precedence over the committed `.apache-magpie-overrides/` layer when both
provide the same setting. Both override surfaces are additive only: they
may provide adopter-specific paths, wording, or capability/MCP enablement,
but they cannot weaken the safety, confidentiality, privacy, or
external-content-as-data baseline. See
[`docs/setup/agentic-overrides.md`](docs/setup/agentic-overrides.md) for
the per-skill contract. The per-skill chain does not replace the
`<project-config>/project.md` key-resolution chain above; a skill resolves
configuration keys through that chain and then applies matching overrides.

The organization an `organization:` value names need **not** be in-tree.
The framework ships `organizations/ASF/` and `organizations/independent/`,
but an organization Magpie does not ship is resolved from an
Expand Down