overrides — manage agentic overrides for framework skills

The agentic-overrides mechanism is the framework's answer to "how does an adopter modify a framework skill's behaviour without forking the framework". An override file lives at .apache-magpie-overrides/<framework-skill>.md in the adopter repo (committed). The framework skill consults the file at run-time before executing default behaviour and applies the agent-readable instructions in it.

This sub-action helps the user manage those override files — list them, scaffold a new one, or open an existing one.

The full contract (what an override file may contain, how the framework skill applies it, the hard rules that bound the mechanism) lives in docs/setup/agentic-overrides.md in the framework. This file is the operational helper.

Inputs

• <framework-skill> — required. The skill name to scaffold / open the override for (e.g. pr-management-triage).

Step 0 — Pre-flight

1. The repo must be adopted (see verify.md check 1 + check 5). If not, redirect to /magpie-setup adopt.
2. The named <framework-skill> must exist in the snapshot at <repo-root>/.apache-magpie/skills/<framework-skill>/. If not, name the typo and list the available framework skills.

Step 1 — Resolve the override path

<override-path> = <repo-root>/.apache-magpie-overrides/<framework-skill>.md.

If <override-path> already exists, this is an open operation: surface the file's current content, ask the user what they want to change, walk through the edit. Same as if they had opened the file in their editor — the agent is just doing it agentically.

If <override-path> doesn't exist, this is a scaffold operation: continue to Step 2.

Step 2 — Scaffold a new override

Read the framework skill's structure to know what the override might target — the skill's section headings, golden rules, decision-table rows, etc. Surface these as candidate override anchors.

Ask the user what they want to override:

• "Skip Step N" → invalidate a specific step.
• "Replace Step N with: ..." → replace a step's behaviour.
• "Add a new step before/after Step N: ..." → insert.
• "Always do X regardless of the framework's classification" → pre-empt the framework's decision logic.
• Free-form — the agent interprets at run-time.

Generate the override file with the user's instructions. Use the canonical scaffold below.

Override file scaffold

<!-- SPDX-License-Identifier: Apache-2.0
     https://www.apache.org/legal/release-policy.html -->

<!-- apache-steward agentic override
     Framework skill:    <framework-skill>
     Pinned to snapshot: see ../.apache-magpie.lock for the SHA
                          this override was authored against.
     Applied by:         the framework skill at run-time, before
                          executing default behaviour. -->

# Overrides for `<framework-skill>`

## Why these overrides exist

(One paragraph explaining the local context. Why does this
adopter need to deviate from the framework's default? Future
maintainers — including the agent on a later run — read this
to know whether the override is still relevant.)

## Overrides

### Override 1 — <one-line headline>

(Free-form agent-readable instructions. The framework skill
applies these before running its default behaviour. Be
specific about which step / golden rule / decision-table row
the override targets.)

### Override 2 — <one-line headline>

(...)

Step 3 — Surface the contract reminders

Whenever the skill scaffolds or opens an override file, remind the user:

1. Never modify the snapshot at <repo-root>/.apache-magpie/. Local mods go in this override file.
2. If the override is widely useful, upstream it. Open a PR against apache/airflow-steward implementing the change in the framework skill itself. The framework will then apply the change on every adopter's next /magpie-setup upgrade, and this adopter's override becomes redundant — at which point the user deletes it.
3. Re-anchor on framework upgrades. The skill's upgrade.md sub-action surfaces conflicts when a framework upgrade restructures a skill the user has an override for. Re-anchor when prompted.

Failure modes

• Snapshot missing → redirect to /magpie-setup upgrade.
• Skill name typo → list available skills, ask again.
• The override target is on a framework skill that does not consult overrides → the framework treats overrides as opt-in per skill (each skill that supports overrides documents this in its own SKILL.md). If the named skill doesn't yet support overrides, surface that and suggest opening a framework-side issue requesting the hook.