Override Upstream

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

<!-- Placeholder convention (see ../../AGENTS.md#placeholder-convention-used-in-skill-files):
     <adopter-repo>           → repo this skill is being run in (an adopter)
     <override-file>          → .apache-magpie-overrides/<skill>.md being upstreamed
     <framework-skill>        → framework skill the override modifies
     <framework-clone>        → user's local clone of apache/magpie
                                (separate from .apache-magpie/, which is a gitignored snapshot)
     <framework-fork>         → user's GitHub fork of apache/magpie
                                (where the PR branch gets pushed) -->

setup-override-upstream

This skill turns a local override into a framework feature. It takes one .apache-magpie-overrides/<skill>.md file in an adopter repo, helps the user decide whether the change is worth upstreaming, designs the framework-level abstraction, implements it in apache/magpie, and opens a PR.

Overrides (per docs/setup/agentic-overrides.md) are deliberately agentic and adopter-local: no schema, no anchors, no patch tool. That makes them quick to write but hard to share, since every adopter who wants the same behaviour writes their own. Upstreaming is the escape hatch: when an override starts looking like a missing feature, a PR bakes it into the framework default, and every adopter gets it on their next setup upgrade.

Adopter overrides

<!-- BEGIN MAGPIE BLOCK: adopter-overrides — generated from tools/dev/blocks/adopter-overrides.md -->

Before running its default behaviour, this skill consults setup-override-upstream.md in the personal layer (.apache-magpie-local/ when the project adopted Magpie, falling back to the main checkout's in a linked worktree, or <git-common-dir>/apache-magpie/ when Magpie is only installed; applied first, wins on conflict) and .apache-magpie-overrides/setup-override-upstream.md (committed, project-wide) in the adopter repo, if present, and applies any agent-readable overrides it finds. See docs/setup/agentic-overrides.md for the contract.

Hard rule: agents NEVER modify the snapshot under <adopter-repo>/.apache-magpie/. Local modifications go in the override file; framework changes go via PR to apache/magpie.

<!-- END MAGPIE BLOCK: adopter-overrides -->

---

Golden rules

Golden rule 1 — not every override should be upstreamed. Many overrides encode project-specific choices: canned-response wording, the scope-label taxonomy, a milestone-format regex, a tone-of-voice preference. These stay in the adopter repo. The skill walks through this decision explicitly and stops early if the change does not generalise.

Golden rule 2 — write to <framework-clone>, never to the snapshot. The framework PR is implemented in the user's local apache-magpie clone, a separate working directory from the adopter's gitignored, read-only .apache-magpie/ snapshot. If the user has no clone yet, the skill helps set one up.

Golden rule 3 — assistant proposes, user fires. Per the framework convention (see AGENTS.md), every state-changing action (clone, branch, commit, push, gh pr create) is proposed and runs only on explicit user confirmation. Public PR content is shown to the user before it is posted.

Golden rule 4 — decouple PR from override deletion. Opening the framework PR is one step. Deleting the now-redundant override file is a separate step, AFTER the PR has merged AND the adopter has run setup upgrade to pick up the change. The skill ends with a pointer at that cleanup; it does not delete the override preemptively.

Walk-through

Step 0 — Pre-flight

1. We are in an adopter repo (has <adopter-repo>/.apache-magpie.lock and <adopter-repo>/.apache-magpie-overrides/). If not, stop — the skill is for adopters with at least one override file.
2. The snapshot is current (no drift per the section above). If drift exists, propose setup upgrade first.
3. Identify <framework-clone>, the user's local clone of apache/magpie. Common locations: ~/code/magpie/, ~/work/magpie/. If not found, ask the user where it is, or help them clone it (git clone git@github.com:apache/magpie.git). The clone is separate from <adopter-repo>/.apache-magpie/ (the snapshot).

Step 1 — Pick the override

List <adopter-repo>/.apache-magpie-overrides/*.md (excluding the directory's own README.md). For each, print the file name + first headline.

• Zero overrides → stop. There is nothing to upstream.
• One override → auto-pick.
• Multiple → ask the user which one to upstream this run. The skill handles one override per invocation (clean PR, clean review).

Step 2 — Read the override + framework skill

Read the chosen override file. Surface to the user:

• Title + the override headlines (### Override N — ...)
• The "why" paragraph if the file has one

Then read the framework skill it modifies, from the snapshot at <adopter-repo>/.apache-magpie/skills/<framework-skill>/. Surface:

• The skill's purpose (frontmatter description)
• The specific section(s) the override modifies (steps, decision-table rows, golden rules)
• Any cross-skill references the override depends on

Goal: the user and the agent both know what the change is and where it applies.

Step 3 — Decide if upstreamable

Walk through with the user. Common categories:

• Project-specific (canned-response wording, scope labels, milestone formats, tooling assumptions particular to this project) → stop here. Suggest the override stay local. Generalising would force the framework either to include the adopter's specifics (defeats project-agnosticism) or to expose a config knob no other adopter would set the same way (bloats the contract).
• Missing feature (the override does something useful any adopter might want) → continue. The framework should learn this behaviour by default, or expose it as an opt-in.
• Better default (the override changes a default the framework currently picks; if most adopters would prefer the override's default, the framework should adopt it) → continue. The PR may also keep the old behaviour reachable via a flag.
• Refactor a step (the framework's step is awkward / redundant / has an edge case) → continue. The PR fixes the step itself.

If the user is unsure, lean toward stop — keep the override local until a second adopter wants the same thing.

Step 4 — Design the framework-level abstraction

Once the user confirms the change is upstreamable, design the framework-side change. Pick one of:

Surface the proposal to the user and iterate. The output is a concrete plan: which framework files to modify, what to add / remove / change, and which existing framework tests or verification may need updating.

Step 5 — Implement in the framework clone

In <framework-clone>:

1. git fetch origin && git checkout -b feat/<short-description> origin/main
2. Apply the changes from the design step. Read the surrounding framework code first (the framework's AGENTS.md, the modified skill's supporting files) to match conventions.
3. Run framework pre-commit: prek run --all-files. Fix anything that fires.
4. Show the user the diff (git diff). Get explicit confirmation before committing.
5. Commit with a message matching the framework's conventions (Conventional-Commits prefix: feat(skills): ... for new framework behaviour, refactor(skills): ... for restructure, etc.). Add a Generated-by: <agent> (<model>) trailer with git commit --trailer, where <agent> and <model> are the actual agent and model you are running as (e.g. Claude (Opus 4.8), OpenCode (Big Pickle)). It is the framework repository's own convention (commit-attribution.md), whatever the adopter uses; do not hardcode either value, per the framework's no-coauthored-by hook.