[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-apache-magpie-setup-override-upstream":3,"mdc-qiypzc-key":40,"related-org-apache-magpie-setup-override-upstream":1857,"related-repo-apache-magpie-setup-override-upstream":2012},{"slug":4,"name":4,"fn":5,"description":6,"org":7,"tags":11,"stars":22,"repoUrl":23,"updatedAt":24,"license":25,"forks":26,"topics":27,"repo":35,"sourceUrl":38,"mdContent":39},"magpie-setup-override-upstream","promote local overrides to upstream","Walk an adopter through promoting a local\n`.apache-magpie-overrides\u002F\u003Cskill>.md` file into a PR\nagainst `apache\u002Fmagpie`. After the PR merges and\nthe adopter runs `\u002Fmagpie-setup upgrade`, the override file\nis no longer needed and the skill prompts for its removal.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},"apache","Apache Software Foundation","https:\u002F\u002Fpexgzepcugksgbtrxkhf.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Forg-logos\u002Fapache.png",[12,16,19],{"name":13,"slug":14,"type":15},"Git","git","tag",{"name":17,"slug":18,"type":15},"Deployment","deployment",{"name":20,"slug":21,"type":15},"Engineering","engineering",61,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie","2026-08-01T05:43:45.698523","Apache-2.0",42,[28,8,29,30,31,32,33,34],"agent-skills","automation","claude-code","cve","security","vulnerability-disclosure","vulnerability-management",{"repoUrl":23,"stars":22,"forks":26,"topics":36,"description":37},[28,8,29,30,31,32,33,34],"Agent-assisted maintainership and development framework for Apache projects — Triage, Mentoring, Drafting (agent-authored fixes with human review), and Pairing (developer-side dev-cycle) skills shipping; Agentic Autonomous (auto-merge) on the roadmap.","https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Ftree\u002FHEAD\u002Fskills\u002Fsetup-override-upstream","---\n# SPDX-License-Identifier: Apache-2.0\n# https:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0\nname: magpie-setup-override-upstream\nfamily: setup\nmode: Meta\ndescription: |\n  Walk an adopter through promoting a local\n  `.apache-magpie-overrides\u002F\u003Cskill>.md` file into a PR\n  against `apache\u002Fmagpie`. After the PR merges and\n  the adopter runs `\u002Fmagpie-setup upgrade`, the override file\n  is no longer needed and the skill prompts for its removal.\nwhen_to_use: |\n  Invoke when the user says \"upstream my override\", \"promote\n  this override to the framework\", \"convert my local\n  modification into a magpie feature\", \"make this override\n  a framework feature\", \"open a PR to apache-magpie for\n  this override\", or similar — typically after running the\n  override locally for a while and deciding the change is\n  worth contributing back.\nargument-hint: \"[skill-name]\"\ncapability: capability:platform\nlicense: Apache-2.0\n---\n\n\u003C!-- SPDX-License-Identifier: Apache-2.0\n     https:\u002F\u002Fwww.apache.org\u002Flegal\u002Frelease-policy.html -->\n\n\u003C!-- Placeholder convention (see ..\u002F..\u002FAGENTS.md#placeholder-convention-used-in-skill-files):\n     \u003Cadopter-repo>           → repo this skill is being run in (an adopter)\n     \u003Coverride-file>          → .apache-magpie-overrides\u002F\u003Cskill>.md being upstreamed\n     \u003Cframework-skill>        → framework skill the override modifies\n     \u003Cframework-clone>        → user's local clone of apache\u002Fmagpie\n                                (separate from .apache-magpie\u002F, which is a gitignored snapshot)\n     \u003Cframework-fork>         → user's GitHub fork of apache\u002Fmagpie\n                                (where the PR branch gets pushed) -->\n\n# setup-override-upstream\n\nThis skill is the path from *local override* to *framework\nfeature*. It takes a single\n`.apache-magpie-overrides\u002F\u003Cskill>.md` file in an adopter\nrepo, walks the user through deciding whether the change is\nworth upstreaming, designs the framework-level abstraction,\nimplements it in `apache\u002Fmagpie`, and opens a PR.\n\nThe override mechanism (per\n[`docs\u002Fsetup\u002Fagentic-overrides.md`](..\u002F..\u002Fdocs\u002Fsetup\u002Fagentic-overrides.md))\nis deliberately *agentic* and *adopter-local*: there's no\nschema, no anchors, no patch tool. That makes overrides\nquick to write but hard to share — every adopter who wants\nthe same behaviour writes their own. **Upstreaming** is the\nescape hatch: when an override stops being project-specific\nand starts looking like a missing feature, the right move\nis a PR that bakes the change into the framework's default,\nmaking every adopter benefit on their next\n`\u002Fmagpie-setup upgrade`.\n\n## Adopter overrides\n\nBefore running the default behaviour documented below, this\nskill consults\n[`.apache-magpie-local\u002Fsetup-override-upstream.md`](..\u002F..\u002Fdocs\u002Fsetup\u002Fagentic-overrides.md) (personal, gitignored) and [`.apache-magpie-overrides\u002Fsetup-override-upstream.md`](..\u002F..\u002Fdocs\u002Fsetup\u002Fagentic-overrides.md) (committed, project-wide)\nin the adopter repo if it exists, and applies any\nagent-readable overrides it finds. See\n[`docs\u002Fsetup\u002Fagentic-overrides.md`](..\u002F..\u002Fdocs\u002Fsetup\u002Fagentic-overrides.md)\nfor the contract — what overrides may contain, hard rules,\nthe reconciliation flow on framework upgrade, upstreaming\nguidance.\n\n**Hard rule**: agents NEVER modify the snapshot under\n`\u003Cadopter-repo>\u002F.apache-magpie\u002F`. Local modifications go in\nthe override file. Framework changes go via PR to\n`apache\u002Fmagpie`.\n\n---\n\n## Snapshot drift\n\nAlso at the top of every run, this skill compares the\ngitignored `.apache-magpie.local.lock` (per-machine\nfetch) against the committed `.apache-magpie.lock` (the\nproject pin). On mismatch the skill surfaces the gap and\nproposes\n[`\u002Fmagpie-setup upgrade`](..\u002Fsetup\u002Fupgrade.md).\nThe proposal is non-blocking — the user may defer if\nthey want to run with the local snapshot for now. See\n[`docs\u002Fsetup\u002Finstall-recipes.md` § Subsequent runs and drift detection](..\u002F..\u002Fdocs\u002Fsetup\u002Finstall-recipes.md#subsequent-runs-and-drift-detection)\nfor the full flow.\n\nDrift severity:\n\n- **method or URL differ** → ✗ full re-install needed.\n- **ref differs** (project bumped tag, or `git-branch`\n  local is behind upstream tip) → ⚠ sync needed.\n- **`svn-zip` SHA-512 mismatches the committed\n  anchor** → ✗ security-flagged; investigate before\n  upgrading.\n\n> **Doubly important here**: the skill is about to design\n> a framework-level abstraction by reading the snapshot's\n> framework skill. If the snapshot is stale, the\n> abstraction may be designed against a version that has\n> already changed upstream. Address drift before\n> proceeding.\n\n---\n\n## Golden rules\n\n**Golden rule 1 — not every override should be upstreamed.**\nMany overrides encode genuinely *project-specific* choices:\nthe wording of a canned response, the project's scope-label\ntaxonomy, milestone-format regex, a tone-of-voice\npreference. These should stay in the adopter repo. The\nskill explicitly walks through this decision and stops\nearly if the change is not generalisable.\n\n**Golden rule 2 — write to `\u003Cframework-clone>`, never to\nthe snapshot.** The framework PR is implemented in the\nuser's local apache-magpie clone (a separate working\ndirectory from the adopter's `.apache-magpie\u002F` snapshot,\nwhich is gitignored and read-only). If the user does not\nhave a clone yet, the skill helps them set one up.\n\n**Golden rule 3 — assistant proposes, user fires.** Per the\nframework convention (see\n[`AGENTS.md`](..\u002F..\u002FAGENTS.md)), every state-changing\naction — clone, branch, commit, push, `gh pr create` — is\nproposed by the skill and only happens on explicit user\nconfirmation. Public PR content is shown to the user before\nit is posted.\n\n**Golden rule 4 — decouple PR from override deletion.**\nOpening the framework PR is one step; deleting the now-\nredundant override file in the adopter repo is a separate\nstep that happens AFTER the PR has merged AND the adopter\nhas run `\u002Fmagpie-setup upgrade` to pick up the framework\nchange. The skill ends with a clear pointer at the\npost-merge cleanup; it does not delete the override\npreemptively.\n\n## Walk-through\n\n### Step 0 — Pre-flight\n\n1. We are in an adopter repo (has\n   `\u003Cadopter-repo>\u002F.apache-magpie.lock` and\n   `\u003Cadopter-repo>\u002F.apache-magpie-overrides\u002F`). If not,\n   stop — the skill is for adopters with at least one\n   override file.\n2. The snapshot is current (no drift per the section\n   above). If drift exists, propose\n   `\u002Fmagpie-setup upgrade` first.\n3. Identify `\u003Cframework-clone>` — the user's local clone\n   of `apache\u002Fmagpie`. Common locations:\n   `~\u002Fcode\u002Fmagpie\u002F`, `~\u002Fwork\u002Fmagpie\u002F`.\n   If not found, surface and ask the user where it is, or\n   help them clone it (`git clone\n   git@github.com:apache\u002Fmagpie.git`). The clone\n   is **separate** from `\u003Cadopter-repo>\u002F.apache-magpie\u002F`\n   (the snapshot).\n\n### Step 1 — Pick the override\n\nList `\u003Cadopter-repo>\u002F.apache-magpie-overrides\u002F*.md`\n(excluding the directory's own `README.md`). For each,\nprint the file name + first headline.\n\n- **Zero overrides** → stop. There is nothing to upstream.\n- **One override** → auto-pick.\n- **Multiple** → ask the user which one to upstream this\n  run. The skill handles one override per invocation\n  (clean PR, clean review).\n\n### Step 2 — Read the override + framework skill\n\nRead the chosen override file. Surface to the user:\n\n- Title + the override headlines (`### Override N — ...`)\n- The \"why\" paragraph if the file has one\n\nThen read the framework skill it modifies, from the\nsnapshot at\n`\u003Cadopter-repo>\u002F.apache-magpie\u002Fskills\u002F\u003Cframework-skill>\u002F`.\nSurface:\n\n- The skill's purpose (frontmatter description)\n- The specific section(s) the override modifies (steps,\n  decision-table rows, golden rules)\n- Any cross-skill references the override depends on\n\nGoal: both the user and the agent should now have a clear\nmental model of *what* the change is and *where* it\napplies.\n\n### Step 3 — Decide if upstreamable\n\nWalk through with the user. Common categories:\n\n- **Project-specific** (canned-response wording, scope\n  labels, milestone formats, tooling assumptions\n  particular to this project) → **stop here**. Suggest the\n  override stay local. Generalising would require the\n  framework to either include the adopter's specifics\n  (defeats project-agnosticism) or expose a config knob\n  that no other adopter would set the same way (bloats the\n  contract).\n- **Missing feature** (the override does something useful\n  that any adopter might want) → **continue**. The\n  framework should learn this behaviour by default, or\n  expose it as an opt-in.\n- **Better default** (the override changes a default the\n  framework currently picks; if a majority of adopters\n  would prefer the override's default, the framework\n  should adopt it) → **continue**. The PR may also keep\n  the old behaviour reachable via a flag.\n- **Refactor a step** (the framework's step is\n  awkward \u002F redundant \u002F has an edge case) → **continue**.\n  The PR fixes the step itself.\n\nIf the user is unsure, lean toward **stop** — keep the\noverride local until a second adopter wants the same thing.\n\n### Step 4 — Design the framework-level abstraction\n\nOnce the user confirms the change is upstreamable, design\nthe framework-side change. Pick one of:\n\n| Shape | When |\n|---|---|\n| **Add a config knob** in `\u003Cproject-config>\u002F` | The change is opt-in per-adopter; default behaviour is unchanged. |\n| **Change a default** | The new behaviour is better for the majority; the framework's existing default becomes a `\u003Cproject-config>\u002F` opt-out. |\n| **Add an optional step** | The change is an *additional* step (not a substitute for an existing one). |\n| **Refactor existing step** | The change rewrites how an existing step works. No new config; the new behaviour is universal. |\n\nSurface the proposal to the user. Iterate. The output of\nthis step is a concrete plan: which framework files to\nmodify, what to add \u002F remove \u002F change, what tests or\nverification the framework already has that may need\nupdating.\n\n### Step 5 — Implement in the framework clone\n\nIn `\u003Cframework-clone>`:\n\n1. `git fetch origin && git checkout -b\n   feat\u002F\u003Cshort-description> origin\u002Fmain`\n2. Apply the changes the design step decided on. Read the\n   surrounding framework code first (the framework's\n   `AGENTS.md`, the relevant supporting files of the\n   modified skill) to match conventions.\n3. Run framework pre-commit:\n   `prek run --all-files`. Fix anything that fires.\n4. Show the user the diff (`git diff`). Get explicit\n   confirmation before committing.\n5. Commit with a message matching the framework's\n   conventions (Conventional-Commits prefix:\n   `feat(skills): ...` for new framework behaviour,\n   `refactor(skills): ...` for restructure, etc.). End the\n   message with a `Generated-by: \u003Cagent> (\u003Cmodel>)` trailer,\n   where `\u003Cagent>` and `\u003Cmodel>` are the actual agent and\n   model you are running as (e.g. `Claude (Opus 4.8)`,\n   `OpenCode (Big Pickle)`) — do not hardcode either, per\n   the framework's no-coauthored-by hook.\n\n### Step 6 — Open the PR\n\n1. `git push -u \u003Cfork-remote> feat\u002F\u003Cbranch>`. If no fork\n   remote is configured, surface and help the user add one\n   (`git remote add fork \u003Cuser>\u002Fmagpie.git`).\n2. Draft the PR title + body. Include:\n   - **Summary** — what the change is, in 1–3 bullets.\n   - **Motivation** — link to the originating override\n     file in the adopter repo (the user's project), with\n     enough context that the framework reviewer\n     understands the use case without reading the full\n     override.\n   - **Migration path for existing adopters** — if the\n     change introduces a new config knob, explain the\n     default; if it changes a default, explain how\n     adopters opt out.\n   - **Test plan** — what the user verified locally.\n3. **Confirm with the user before posting**. Show the\n   exact title + body. Wait for \"OK to post\" \u002F \"yes\" \u002F\n   \"send\" \u002F similar before running `gh pr create`.\n4. **Pick the labels.** Every framework PR carries at least one\n   `family:*` and one `capability:*` label per\n   [`docs\u002Flabels-and-capabilities.md`](..\u002F..\u002Fdocs\u002Flabels-and-capabilities.md).\n   The override is upstreaming a change to skill `\u003Cskill>`, so:\n   - `family:*` — follow the skill's family\n     (`family:pr-management` for `pr-management-*`, `family:security`\n     for `security-*`, `family:setup` for `setup-*`, `family:issue`\n     for `issue-*`, etc.).\n   - `capability:*` — the capability the change is *implementing*,\n     not the file paths touched. Look up the skill's capability in\n     the skill-to-capability map at\n     [`docs\u002Flabels-and-capabilities.md#capability-to-skill-map`](..\u002F..\u002Fdocs\u002Flabels-and-capabilities.md#capability-to-skill-map).\n   - Add `kind:*` and `mode:*` when they apply per the same doc.\n\n   Surface the chosen labels in the confirmation preview alongside\n   the PR title and body, so the user sees them before posting.\n\n5. Write the PR body to a tempfile first, then create the PR:\n   ```bash\n   # Write tool: file_path: \u002Ftmp\u002Foverride-pr-body.md, content: \u003CPR body>\n   gh pr create --repo apache\u002Fmagpie --base main \\\n     --head \u003Cuser>:\u003Cbranch> --title \"...\" --body-file \u002Ftmp\u002Foverride-pr-body.md \\\n     --label \"family:\u003Cfamily>\" --label \"capability:\u003Ccapability>\"\n   ```\n\n### Step 7 — Post-PR cleanup pointer\n\nAfter the PR is open, surface to the user:\n\n```text\nFramework PR opened: \u003CPR URL>\n\nNext steps once it merges:\n\n  1. \u002Fmagpie-setup upgrade   (in \u003Cadopter-repo>)\n     - Bumps the snapshot to the new framework version.\n     - .apache-magpie.lock will reflect the new pin.\n  2. Delete .apache-magpie-overrides\u002F\u003Cskill>.md in \u003Cadopter-repo>\n     - The override is now redundant; the framework does\n       what the override used to do.\n  3. Commit the deletion + the bumped lock together.\n```\n\nThe skill **does not** delete the override file itself —\nthat happens after the PR merges, and the skill cannot\npredict when (or if) the framework reviewers accept the\nPR. Deletion is the user's manual cleanup once the PR\nlands.\n\n## Output to the user (skill end)\n\n```text\n✓ Override picked:        .apache-magpie-overrides\u002F\u003Cskill>.md\n✓ Framework skill:        \u003Cframework-skill>\n✓ Decision:               upstreamable as \u003Cshape from Step 4>\n✓ Framework clone:        \u003Cframework-clone>\n✓ Branch:                 feat\u002F\u003Cshort-description>\n✓ Commits:                \u003Ccount>\n✓ PR opened:              \u003CPR URL>\n\nNext: wait for the PR to merge, then in \u003Cadopter-repo>:\n  \u002Fmagpie-setup upgrade\n  rm .apache-magpie-overrides\u002F\u003Cskill>.md\n  git add -A && git commit -m \"Remove override \u003Cskill>: upstreamed in apache\u002Fmagpie#\u003CN>\"\n```\n\n## Failure modes\n\n| Symptom | Likely cause | Remediation |\n|---|---|---|\n| `\u003Cadopter-repo>` has no `.apache-magpie-overrides\u002F` | not adopted, or adopted without the overrides scaffold | run `\u002Fmagpie-setup adopt` (idempotent) |\n| Step 1 finds zero overrides | nothing to upstream — adopter has no local modifications recorded | stop |\n| `\u003Cframework-clone>` not found | user has not cloned `apache\u002Fmagpie` yet | help them clone, then resume |\n| Framework pre-commit fails after the implementation | the change does not match framework conventions | iterate with the user, re-run pre-commit, do not bypass with `--no-verify` |\n| User decides mid-flow that the override is project-specific after all | wrong call in Step 3 | stop without opening a PR; the override file in the adopter repo is unchanged, no harm done |\n\n## What this skill is NOT for\n\n- Not for *applying* an override at run-time — that is the\n  per-skill pre-flight protocol documented in\n  [`docs\u002Fsetup\u002Fagentic-overrides.md`](..\u002F..\u002Fdocs\u002Fsetup\u002Fagentic-overrides.md).\n- Not for *creating* a new override — that is\n  [`\u002Fmagpie-setup override \u003Cskill>`](..\u002Fsetup\u002Foverrides.md).\n- Not for *upgrading* the snapshot — that is\n  [`\u002Fmagpie-setup upgrade`](..\u002Fsetup\u002Fupgrade.md).\n  Run that BEFORE this skill if drift exists.\n- Not for arbitrary framework PRs unrelated to overrides.\n  This skill is specifically the override → PR flow. Other\n  framework contributions (new skill, new tool, refactor)\n  go through the framework's normal PR workflow.\n\n## Cross-references\n\n- [`docs\u002Fsetup\u002Fagentic-overrides.md`](..\u002F..\u002Fdocs\u002Fsetup\u002Fagentic-overrides.md) — the override contract.\n- [`setup\u002Foverrides.md`](..\u002Fsetup\u002Foverrides.md) — how to *create* \u002F *open* an override.\n- [`setup\u002Fupgrade.md`](..\u002Fsetup\u002Fupgrade.md) — how to upgrade the snapshot post-merge.\n",{"data":41,"body":47},{"name":4,"family":42,"mode":43,"description":6,"when_to_use":44,"argument-hint":45,"capability":46,"license":25},"setup","Meta","Invoke when the user says \"upstream my override\", \"promote\nthis override to the framework\", \"convert my local\nmodification into a magpie feature\", \"make this override\na framework feature\", \"open a PR to apache-magpie for\nthis override\", or similar — typically after running the\noverride locally for a while and deciding the change is\nworth contributing back.\n","[skill-name]","capability:platform",{"type":48,"children":49},"root",[50,58,96,144,151,188,212,216,222,268,273,322,336,339,345,362,388,418,435,441,448,542,548,569,602,608,613,634,647,665,684,690,695,764,776,782,787,901,906,912,924,1034,1040,1501,1507,1512,1522,1534,1540,1549,1555,1709,1715,1787,1793,1851],{"type":51,"tag":52,"props":53,"children":55},"element","h1",{"id":54},"setup-override-upstream",[56],{"type":57,"value":54},"text",{"type":51,"tag":59,"props":60,"children":61},"p",{},[62,64,70,72,77,79,86,88,94],{"type":57,"value":63},"This skill is the path from ",{"type":51,"tag":65,"props":66,"children":67},"em",{},[68],{"type":57,"value":69},"local override",{"type":57,"value":71}," to ",{"type":51,"tag":65,"props":73,"children":74},{},[75],{"type":57,"value":76},"framework\nfeature",{"type":57,"value":78},". It takes a single\n",{"type":51,"tag":80,"props":81,"children":83},"code",{"className":82},[],[84],{"type":57,"value":85},".apache-magpie-overrides\u002F\u003Cskill>.md",{"type":57,"value":87}," file in an adopter\nrepo, walks the user through deciding whether the change is\nworth upstreaming, designs the framework-level abstraction,\nimplements it in ",{"type":51,"tag":80,"props":89,"children":91},{"className":90},[],[92],{"type":57,"value":93},"apache\u002Fmagpie",{"type":57,"value":95},", and opens a PR.",{"type":51,"tag":59,"props":97,"children":98},{},[99,101,112,114,119,121,126,128,134,136,142],{"type":57,"value":100},"The override mechanism (per\n",{"type":51,"tag":102,"props":103,"children":105},"a",{"href":104},"..\u002F..\u002Fdocs\u002Fsetup\u002Fagentic-overrides.md",[106],{"type":51,"tag":80,"props":107,"children":109},{"className":108},[],[110],{"type":57,"value":111},"docs\u002Fsetup\u002Fagentic-overrides.md",{"type":57,"value":113},")\nis deliberately ",{"type":51,"tag":65,"props":115,"children":116},{},[117],{"type":57,"value":118},"agentic",{"type":57,"value":120}," and ",{"type":51,"tag":65,"props":122,"children":123},{},[124],{"type":57,"value":125},"adopter-local",{"type":57,"value":127},": there's no\nschema, no anchors, no patch tool. That makes overrides\nquick to write but hard to share — every adopter who wants\nthe same behaviour writes their own. ",{"type":51,"tag":129,"props":130,"children":131},"strong",{},[132],{"type":57,"value":133},"Upstreaming",{"type":57,"value":135}," is the\nescape hatch: when an override stops being project-specific\nand starts looking like a missing feature, the right move\nis a PR that bakes the change into the framework's default,\nmaking every adopter benefit on their next\n",{"type":51,"tag":80,"props":137,"children":139},{"className":138},[],[140],{"type":57,"value":141},"\u002Fmagpie-setup upgrade",{"type":57,"value":143},".",{"type":51,"tag":145,"props":146,"children":148},"h2",{"id":147},"adopter-overrides",[149],{"type":57,"value":150},"Adopter overrides",{"type":51,"tag":59,"props":152,"children":153},{},[154,156,165,167,176,178,186],{"type":57,"value":155},"Before running the default behaviour documented below, this\nskill consults\n",{"type":51,"tag":102,"props":157,"children":158},{"href":104},[159],{"type":51,"tag":80,"props":160,"children":162},{"className":161},[],[163],{"type":57,"value":164},".apache-magpie-local\u002Fsetup-override-upstream.md",{"type":57,"value":166}," (personal, gitignored) and ",{"type":51,"tag":102,"props":168,"children":169},{"href":104},[170],{"type":51,"tag":80,"props":171,"children":173},{"className":172},[],[174],{"type":57,"value":175},".apache-magpie-overrides\u002Fsetup-override-upstream.md",{"type":57,"value":177}," (committed, project-wide)\nin the adopter repo if it exists, and applies any\nagent-readable overrides it finds. See\n",{"type":51,"tag":102,"props":179,"children":180},{"href":104},[181],{"type":51,"tag":80,"props":182,"children":184},{"className":183},[],[185],{"type":57,"value":111},{"type":57,"value":187},"\nfor the contract — what overrides may contain, hard rules,\nthe reconciliation flow on framework upgrade, upstreaming\nguidance.",{"type":51,"tag":59,"props":189,"children":190},{},[191,196,198,204,206,211],{"type":51,"tag":129,"props":192,"children":193},{},[194],{"type":57,"value":195},"Hard rule",{"type":57,"value":197},": agents NEVER modify the snapshot under\n",{"type":51,"tag":80,"props":199,"children":201},{"className":200},[],[202],{"type":57,"value":203},"\u003Cadopter-repo>\u002F.apache-magpie\u002F",{"type":57,"value":205},". Local modifications go in\nthe override file. Framework changes go via PR to\n",{"type":51,"tag":80,"props":207,"children":209},{"className":208},[],[210],{"type":57,"value":93},{"type":57,"value":143},{"type":51,"tag":213,"props":214,"children":215},"hr",{},[],{"type":51,"tag":145,"props":217,"children":219},{"id":218},"snapshot-drift",[220],{"type":57,"value":221},"Snapshot drift",{"type":51,"tag":59,"props":223,"children":224},{},[225,227,233,235,241,243,252,254,266],{"type":57,"value":226},"Also at the top of every run, this skill compares the\ngitignored ",{"type":51,"tag":80,"props":228,"children":230},{"className":229},[],[231],{"type":57,"value":232},".apache-magpie.local.lock",{"type":57,"value":234}," (per-machine\nfetch) against the committed ",{"type":51,"tag":80,"props":236,"children":238},{"className":237},[],[239],{"type":57,"value":240},".apache-magpie.lock",{"type":57,"value":242}," (the\nproject pin). On mismatch the skill surfaces the gap and\nproposes\n",{"type":51,"tag":102,"props":244,"children":246},{"href":245},"..\u002Fsetup\u002Fupgrade.md",[247],{"type":51,"tag":80,"props":248,"children":250},{"className":249},[],[251],{"type":57,"value":141},{"type":57,"value":253},".\nThe proposal is non-blocking — the user may defer if\nthey want to run with the local snapshot for now. See\n",{"type":51,"tag":102,"props":255,"children":257},{"href":256},"..\u002F..\u002Fdocs\u002Fsetup\u002Finstall-recipes.md#subsequent-runs-and-drift-detection",[258,264],{"type":51,"tag":80,"props":259,"children":261},{"className":260},[],[262],{"type":57,"value":263},"docs\u002Fsetup\u002Finstall-recipes.md",{"type":57,"value":265}," § Subsequent runs and drift detection",{"type":57,"value":267},"\nfor the full flow.",{"type":51,"tag":59,"props":269,"children":270},{},[271],{"type":57,"value":272},"Drift severity:",{"type":51,"tag":274,"props":275,"children":276},"ul",{},[277,288,306],{"type":51,"tag":278,"props":279,"children":280},"li",{},[281,286],{"type":51,"tag":129,"props":282,"children":283},{},[284],{"type":57,"value":285},"method or URL differ",{"type":57,"value":287}," → ✗ full re-install needed.",{"type":51,"tag":278,"props":289,"children":290},{},[291,296,298,304],{"type":51,"tag":129,"props":292,"children":293},{},[294],{"type":57,"value":295},"ref differs",{"type":57,"value":297}," (project bumped tag, or ",{"type":51,"tag":80,"props":299,"children":301},{"className":300},[],[302],{"type":57,"value":303},"git-branch",{"type":57,"value":305},"\nlocal is behind upstream tip) → ⚠ sync needed.",{"type":51,"tag":278,"props":307,"children":308},{},[309,320],{"type":51,"tag":129,"props":310,"children":311},{},[312,318],{"type":51,"tag":80,"props":313,"children":315},{"className":314},[],[316],{"type":57,"value":317},"svn-zip",{"type":57,"value":319}," SHA-512 mismatches the committed\nanchor",{"type":57,"value":321}," → ✗ security-flagged; investigate before\nupgrading.",{"type":51,"tag":323,"props":324,"children":325},"blockquote",{},[326],{"type":51,"tag":59,"props":327,"children":328},{},[329,334],{"type":51,"tag":129,"props":330,"children":331},{},[332],{"type":57,"value":333},"Doubly important here",{"type":57,"value":335},": the skill is about to design\na framework-level abstraction by reading the snapshot's\nframework skill. If the snapshot is stale, the\nabstraction may be designed against a version that has\nalready changed upstream. Address drift before\nproceeding.",{"type":51,"tag":213,"props":337,"children":338},{},[],{"type":51,"tag":145,"props":340,"children":342},{"id":341},"golden-rules",[343],{"type":57,"value":344},"Golden rules",{"type":51,"tag":59,"props":346,"children":347},{},[348,353,355,360],{"type":51,"tag":129,"props":349,"children":350},{},[351],{"type":57,"value":352},"Golden rule 1 — not every override should be upstreamed.",{"type":57,"value":354},"\nMany overrides encode genuinely ",{"type":51,"tag":65,"props":356,"children":357},{},[358],{"type":57,"value":359},"project-specific",{"type":57,"value":361}," choices:\nthe wording of a canned response, the project's scope-label\ntaxonomy, milestone-format regex, a tone-of-voice\npreference. These should stay in the adopter repo. The\nskill explicitly walks through this decision and stops\nearly if the change is not generalisable.",{"type":51,"tag":59,"props":363,"children":364},{},[365,378,380,386],{"type":51,"tag":129,"props":366,"children":367},{},[368,370,376],{"type":57,"value":369},"Golden rule 2 — write to ",{"type":51,"tag":80,"props":371,"children":373},{"className":372},[],[374],{"type":57,"value":375},"\u003Cframework-clone>",{"type":57,"value":377},", never to\nthe snapshot.",{"type":57,"value":379}," The framework PR is implemented in the\nuser's local apache-magpie clone (a separate working\ndirectory from the adopter's ",{"type":51,"tag":80,"props":381,"children":383},{"className":382},[],[384],{"type":57,"value":385},".apache-magpie\u002F",{"type":57,"value":387}," snapshot,\nwhich is gitignored and read-only). If the user does not\nhave a clone yet, the skill helps them set one up.",{"type":51,"tag":59,"props":389,"children":390},{},[391,396,398,408,410,416],{"type":51,"tag":129,"props":392,"children":393},{},[394],{"type":57,"value":395},"Golden rule 3 — assistant proposes, user fires.",{"type":57,"value":397}," Per the\nframework convention (see\n",{"type":51,"tag":102,"props":399,"children":401},{"href":400},"..\u002F..\u002FAGENTS.md",[402],{"type":51,"tag":80,"props":403,"children":405},{"className":404},[],[406],{"type":57,"value":407},"AGENTS.md",{"type":57,"value":409},"), every state-changing\naction — clone, branch, commit, push, ",{"type":51,"tag":80,"props":411,"children":413},{"className":412},[],[414],{"type":57,"value":415},"gh pr create",{"type":57,"value":417}," — is\nproposed by the skill and only happens on explicit user\nconfirmation. Public PR content is shown to the user before\nit is posted.",{"type":51,"tag":59,"props":419,"children":420},{},[421,426,428,433],{"type":51,"tag":129,"props":422,"children":423},{},[424],{"type":57,"value":425},"Golden rule 4 — decouple PR from override deletion.",{"type":57,"value":427},"\nOpening the framework PR is one step; deleting the now-\nredundant override file in the adopter repo is a separate\nstep that happens AFTER the PR has merged AND the adopter\nhas run ",{"type":51,"tag":80,"props":429,"children":431},{"className":430},[],[432],{"type":57,"value":141},{"type":57,"value":434}," to pick up the framework\nchange. The skill ends with a clear pointer at the\npost-merge cleanup; it does not delete the override\npreemptively.",{"type":51,"tag":145,"props":436,"children":438},{"id":437},"walk-through",[439],{"type":57,"value":440},"Walk-through",{"type":51,"tag":442,"props":443,"children":445},"h3",{"id":444},"step-0-pre-flight",[446],{"type":57,"value":447},"Step 0 — Pre-flight",{"type":51,"tag":449,"props":450,"children":451},"ol",{},[452,473,485],{"type":51,"tag":278,"props":453,"children":454},{},[455,457,463,465,471],{"type":57,"value":456},"We are in an adopter repo (has\n",{"type":51,"tag":80,"props":458,"children":460},{"className":459},[],[461],{"type":57,"value":462},"\u003Cadopter-repo>\u002F.apache-magpie.lock",{"type":57,"value":464}," and\n",{"type":51,"tag":80,"props":466,"children":468},{"className":467},[],[469],{"type":57,"value":470},"\u003Cadopter-repo>\u002F.apache-magpie-overrides\u002F",{"type":57,"value":472},"). If not,\nstop — the skill is for adopters with at least one\noverride file.",{"type":51,"tag":278,"props":474,"children":475},{},[476,478,483],{"type":57,"value":477},"The snapshot is current (no drift per the section\nabove). If drift exists, propose\n",{"type":51,"tag":80,"props":479,"children":481},{"className":480},[],[482],{"type":57,"value":141},{"type":57,"value":484}," first.",{"type":51,"tag":278,"props":486,"children":487},{},[488,490,495,497,502,504,510,512,518,520,526,528,533,535,540],{"type":57,"value":489},"Identify ",{"type":51,"tag":80,"props":491,"children":493},{"className":492},[],[494],{"type":57,"value":375},{"type":57,"value":496}," — the user's local clone\nof ",{"type":51,"tag":80,"props":498,"children":500},{"className":499},[],[501],{"type":57,"value":93},{"type":57,"value":503},". Common locations:\n",{"type":51,"tag":80,"props":505,"children":507},{"className":506},[],[508],{"type":57,"value":509},"~\u002Fcode\u002Fmagpie\u002F",{"type":57,"value":511},", ",{"type":51,"tag":80,"props":513,"children":515},{"className":514},[],[516],{"type":57,"value":517},"~\u002Fwork\u002Fmagpie\u002F",{"type":57,"value":519},".\nIf not found, surface and ask the user where it is, or\nhelp them clone it (",{"type":51,"tag":80,"props":521,"children":523},{"className":522},[],[524],{"type":57,"value":525},"git clone git@github.com:apache\u002Fmagpie.git",{"type":57,"value":527},"). The clone\nis ",{"type":51,"tag":129,"props":529,"children":530},{},[531],{"type":57,"value":532},"separate",{"type":57,"value":534}," from ",{"type":51,"tag":80,"props":536,"children":538},{"className":537},[],[539],{"type":57,"value":203},{"type":57,"value":541},"\n(the snapshot).",{"type":51,"tag":442,"props":543,"children":545},{"id":544},"step-1-pick-the-override",[546],{"type":57,"value":547},"Step 1 — Pick the override",{"type":51,"tag":59,"props":549,"children":550},{},[551,553,559,561,567],{"type":57,"value":552},"List ",{"type":51,"tag":80,"props":554,"children":556},{"className":555},[],[557],{"type":57,"value":558},"\u003Cadopter-repo>\u002F.apache-magpie-overrides\u002F*.md",{"type":57,"value":560},"\n(excluding the directory's own ",{"type":51,"tag":80,"props":562,"children":564},{"className":563},[],[565],{"type":57,"value":566},"README.md",{"type":57,"value":568},"). For each,\nprint the file name + first headline.",{"type":51,"tag":274,"props":570,"children":571},{},[572,582,592],{"type":51,"tag":278,"props":573,"children":574},{},[575,580],{"type":51,"tag":129,"props":576,"children":577},{},[578],{"type":57,"value":579},"Zero overrides",{"type":57,"value":581}," → stop. There is nothing to upstream.",{"type":51,"tag":278,"props":583,"children":584},{},[585,590],{"type":51,"tag":129,"props":586,"children":587},{},[588],{"type":57,"value":589},"One override",{"type":57,"value":591}," → auto-pick.",{"type":51,"tag":278,"props":593,"children":594},{},[595,600],{"type":51,"tag":129,"props":596,"children":597},{},[598],{"type":57,"value":599},"Multiple",{"type":57,"value":601}," → ask the user which one to upstream this\nrun. The skill handles one override per invocation\n(clean PR, clean review).",{"type":51,"tag":442,"props":603,"children":605},{"id":604},"step-2-read-the-override-framework-skill",[606],{"type":57,"value":607},"Step 2 — Read the override + framework skill",{"type":51,"tag":59,"props":609,"children":610},{},[611],{"type":57,"value":612},"Read the chosen override file. Surface to the user:",{"type":51,"tag":274,"props":614,"children":615},{},[616,629],{"type":51,"tag":278,"props":617,"children":618},{},[619,621,627],{"type":57,"value":620},"Title + the override headlines (",{"type":51,"tag":80,"props":622,"children":624},{"className":623},[],[625],{"type":57,"value":626},"### Override N — ...",{"type":57,"value":628},")",{"type":51,"tag":278,"props":630,"children":631},{},[632],{"type":57,"value":633},"The \"why\" paragraph if the file has one",{"type":51,"tag":59,"props":635,"children":636},{},[637,639,645],{"type":57,"value":638},"Then read the framework skill it modifies, from the\nsnapshot at\n",{"type":51,"tag":80,"props":640,"children":642},{"className":641},[],[643],{"type":57,"value":644},"\u003Cadopter-repo>\u002F.apache-magpie\u002Fskills\u002F\u003Cframework-skill>\u002F",{"type":57,"value":646},".\nSurface:",{"type":51,"tag":274,"props":648,"children":649},{},[650,655,660],{"type":51,"tag":278,"props":651,"children":652},{},[653],{"type":57,"value":654},"The skill's purpose (frontmatter description)",{"type":51,"tag":278,"props":656,"children":657},{},[658],{"type":57,"value":659},"The specific section(s) the override modifies (steps,\ndecision-table rows, golden rules)",{"type":51,"tag":278,"props":661,"children":662},{},[663],{"type":57,"value":664},"Any cross-skill references the override depends on",{"type":51,"tag":59,"props":666,"children":667},{},[668,670,675,677,682],{"type":57,"value":669},"Goal: both the user and the agent should now have a clear\nmental model of ",{"type":51,"tag":65,"props":671,"children":672},{},[673],{"type":57,"value":674},"what",{"type":57,"value":676}," the change is and ",{"type":51,"tag":65,"props":678,"children":679},{},[680],{"type":57,"value":681},"where",{"type":57,"value":683}," it\napplies.",{"type":51,"tag":442,"props":685,"children":687},{"id":686},"step-3-decide-if-upstreamable",[688],{"type":57,"value":689},"Step 3 — Decide if upstreamable",{"type":51,"tag":59,"props":691,"children":692},{},[693],{"type":57,"value":694},"Walk through with the user. Common categories:",{"type":51,"tag":274,"props":696,"children":697},{},[698,715,732,748],{"type":51,"tag":278,"props":699,"children":700},{},[701,706,708,713],{"type":51,"tag":129,"props":702,"children":703},{},[704],{"type":57,"value":705},"Project-specific",{"type":57,"value":707}," (canned-response wording, scope\nlabels, milestone formats, tooling assumptions\nparticular to this project) → ",{"type":51,"tag":129,"props":709,"children":710},{},[711],{"type":57,"value":712},"stop here",{"type":57,"value":714},". Suggest the\noverride stay local. Generalising would require the\nframework to either include the adopter's specifics\n(defeats project-agnosticism) or expose a config knob\nthat no other adopter would set the same way (bloats the\ncontract).",{"type":51,"tag":278,"props":716,"children":717},{},[718,723,725,730],{"type":51,"tag":129,"props":719,"children":720},{},[721],{"type":57,"value":722},"Missing feature",{"type":57,"value":724}," (the override does something useful\nthat any adopter might want) → ",{"type":51,"tag":129,"props":726,"children":727},{},[728],{"type":57,"value":729},"continue",{"type":57,"value":731},". The\nframework should learn this behaviour by default, or\nexpose it as an opt-in.",{"type":51,"tag":278,"props":733,"children":734},{},[735,740,742,746],{"type":51,"tag":129,"props":736,"children":737},{},[738],{"type":57,"value":739},"Better default",{"type":57,"value":741}," (the override changes a default the\nframework currently picks; if a majority of adopters\nwould prefer the override's default, the framework\nshould adopt it) → ",{"type":51,"tag":129,"props":743,"children":744},{},[745],{"type":57,"value":729},{"type":57,"value":747},". The PR may also keep\nthe old behaviour reachable via a flag.",{"type":51,"tag":278,"props":749,"children":750},{},[751,756,758,762],{"type":51,"tag":129,"props":752,"children":753},{},[754],{"type":57,"value":755},"Refactor a step",{"type":57,"value":757}," (the framework's step is\nawkward \u002F redundant \u002F has an edge case) → ",{"type":51,"tag":129,"props":759,"children":760},{},[761],{"type":57,"value":729},{"type":57,"value":763},".\nThe PR fixes the step itself.",{"type":51,"tag":59,"props":765,"children":766},{},[767,769,774],{"type":57,"value":768},"If the user is unsure, lean toward ",{"type":51,"tag":129,"props":770,"children":771},{},[772],{"type":57,"value":773},"stop",{"type":57,"value":775}," — keep the\noverride local until a second adopter wants the same thing.",{"type":51,"tag":442,"props":777,"children":779},{"id":778},"step-4-design-the-framework-level-abstraction",[780],{"type":57,"value":781},"Step 4 — Design the framework-level abstraction",{"type":51,"tag":59,"props":783,"children":784},{},[785],{"type":57,"value":786},"Once the user confirms the change is upstreamable, design\nthe framework-side change. Pick one of:",{"type":51,"tag":788,"props":789,"children":790},"table",{},[791,810],{"type":51,"tag":792,"props":793,"children":794},"thead",{},[795],{"type":51,"tag":796,"props":797,"children":798},"tr",{},[799,805],{"type":51,"tag":800,"props":801,"children":802},"th",{},[803],{"type":57,"value":804},"Shape",{"type":51,"tag":800,"props":806,"children":807},{},[808],{"type":57,"value":809},"When",{"type":51,"tag":811,"props":812,"children":813},"tbody",{},[814,839,862,885],{"type":51,"tag":796,"props":815,"children":816},{},[817,834],{"type":51,"tag":818,"props":819,"children":820},"td",{},[821,826,828],{"type":51,"tag":129,"props":822,"children":823},{},[824],{"type":57,"value":825},"Add a config knob",{"type":57,"value":827}," in ",{"type":51,"tag":80,"props":829,"children":831},{"className":830},[],[832],{"type":57,"value":833},"\u003Cproject-config>\u002F",{"type":51,"tag":818,"props":835,"children":836},{},[837],{"type":57,"value":838},"The change is opt-in per-adopter; default behaviour is unchanged.",{"type":51,"tag":796,"props":840,"children":841},{},[842,850],{"type":51,"tag":818,"props":843,"children":844},{},[845],{"type":51,"tag":129,"props":846,"children":847},{},[848],{"type":57,"value":849},"Change a default",{"type":51,"tag":818,"props":851,"children":852},{},[853,855,860],{"type":57,"value":854},"The new behaviour is better for the majority; the framework's existing default becomes a ",{"type":51,"tag":80,"props":856,"children":858},{"className":857},[],[859],{"type":57,"value":833},{"type":57,"value":861}," opt-out.",{"type":51,"tag":796,"props":863,"children":864},{},[865,873],{"type":51,"tag":818,"props":866,"children":867},{},[868],{"type":51,"tag":129,"props":869,"children":870},{},[871],{"type":57,"value":872},"Add an optional step",{"type":51,"tag":818,"props":874,"children":875},{},[876,878,883],{"type":57,"value":877},"The change is an ",{"type":51,"tag":65,"props":879,"children":880},{},[881],{"type":57,"value":882},"additional",{"type":57,"value":884}," step (not a substitute for an existing one).",{"type":51,"tag":796,"props":886,"children":887},{},[888,896],{"type":51,"tag":818,"props":889,"children":890},{},[891],{"type":51,"tag":129,"props":892,"children":893},{},[894],{"type":57,"value":895},"Refactor existing step",{"type":51,"tag":818,"props":897,"children":898},{},[899],{"type":57,"value":900},"The change rewrites how an existing step works. No new config; the new behaviour is universal.",{"type":51,"tag":59,"props":902,"children":903},{},[904],{"type":57,"value":905},"Surface the proposal to the user. Iterate. The output of\nthis step is a concrete plan: which framework files to\nmodify, what to add \u002F remove \u002F change, what tests or\nverification the framework already has that may need\nupdating.",{"type":51,"tag":442,"props":907,"children":909},{"id":908},"step-5-implement-in-the-framework-clone",[910],{"type":57,"value":911},"Step 5 — Implement in the framework clone",{"type":51,"tag":59,"props":913,"children":914},{},[915,917,922],{"type":57,"value":916},"In ",{"type":51,"tag":80,"props":918,"children":920},{"className":919},[],[921],{"type":57,"value":375},{"type":57,"value":923},":",{"type":51,"tag":449,"props":925,"children":926},{},[927,936,948,961,974],{"type":51,"tag":278,"props":928,"children":929},{},[930],{"type":51,"tag":80,"props":931,"children":933},{"className":932},[],[934],{"type":57,"value":935},"git fetch origin && git checkout -b feat\u002F\u003Cshort-description> origin\u002Fmain",{"type":51,"tag":278,"props":937,"children":938},{},[939,941,946],{"type":57,"value":940},"Apply the changes the design step decided on. Read the\nsurrounding framework code first (the framework's\n",{"type":51,"tag":80,"props":942,"children":944},{"className":943},[],[945],{"type":57,"value":407},{"type":57,"value":947},", the relevant supporting files of the\nmodified skill) to match conventions.",{"type":51,"tag":278,"props":949,"children":950},{},[951,953,959],{"type":57,"value":952},"Run framework pre-commit:\n",{"type":51,"tag":80,"props":954,"children":956},{"className":955},[],[957],{"type":57,"value":958},"prek run --all-files",{"type":57,"value":960},". Fix anything that fires.",{"type":51,"tag":278,"props":962,"children":963},{},[964,966,972],{"type":57,"value":965},"Show the user the diff (",{"type":51,"tag":80,"props":967,"children":969},{"className":968},[],[970],{"type":57,"value":971},"git diff",{"type":57,"value":973},"). Get explicit\nconfirmation before committing.",{"type":51,"tag":278,"props":975,"children":976},{},[977,979,985,987,993,995,1001,1003,1009,1010,1016,1018,1024,1026,1032],{"type":57,"value":978},"Commit with a message matching the framework's\nconventions (Conventional-Commits prefix:\n",{"type":51,"tag":80,"props":980,"children":982},{"className":981},[],[983],{"type":57,"value":984},"feat(skills): ...",{"type":57,"value":986}," for new framework behaviour,\n",{"type":51,"tag":80,"props":988,"children":990},{"className":989},[],[991],{"type":57,"value":992},"refactor(skills): ...",{"type":57,"value":994}," for restructure, etc.). End the\nmessage with a ",{"type":51,"tag":80,"props":996,"children":998},{"className":997},[],[999],{"type":57,"value":1000},"Generated-by: \u003Cagent> (\u003Cmodel>)",{"type":57,"value":1002}," trailer,\nwhere ",{"type":51,"tag":80,"props":1004,"children":1006},{"className":1005},[],[1007],{"type":57,"value":1008},"\u003Cagent>",{"type":57,"value":120},{"type":51,"tag":80,"props":1011,"children":1013},{"className":1012},[],[1014],{"type":57,"value":1015},"\u003Cmodel>",{"type":57,"value":1017}," are the actual agent and\nmodel you are running as (e.g. ",{"type":51,"tag":80,"props":1019,"children":1021},{"className":1020},[],[1022],{"type":57,"value":1023},"Claude (Opus 4.8)",{"type":57,"value":1025},",\n",{"type":51,"tag":80,"props":1027,"children":1029},{"className":1028},[],[1030],{"type":57,"value":1031},"OpenCode (Big Pickle)",{"type":57,"value":1033},") — do not hardcode either, per\nthe framework's no-coauthored-by hook.",{"type":51,"tag":442,"props":1035,"children":1037},{"id":1036},"step-6-open-the-pr",[1038],{"type":57,"value":1039},"Step 6 — Open the PR",{"type":51,"tag":449,"props":1041,"children":1042},{},[1043,1062,1110,1126,1298],{"type":51,"tag":278,"props":1044,"children":1045},{},[1046,1052,1054,1060],{"type":51,"tag":80,"props":1047,"children":1049},{"className":1048},[],[1050],{"type":57,"value":1051},"git push -u \u003Cfork-remote> feat\u002F\u003Cbranch>",{"type":57,"value":1053},". If no fork\nremote is configured, surface and help the user add one\n(",{"type":51,"tag":80,"props":1055,"children":1057},{"className":1056},[],[1058],{"type":57,"value":1059},"git remote add fork \u003Cuser>\u002Fmagpie.git",{"type":57,"value":1061},").",{"type":51,"tag":278,"props":1063,"children":1064},{},[1065,1067],{"type":57,"value":1066},"Draft the PR title + body. Include:",{"type":51,"tag":274,"props":1068,"children":1069},{},[1070,1080,1090,1100],{"type":51,"tag":278,"props":1071,"children":1072},{},[1073,1078],{"type":51,"tag":129,"props":1074,"children":1075},{},[1076],{"type":57,"value":1077},"Summary",{"type":57,"value":1079}," — what the change is, in 1–3 bullets.",{"type":51,"tag":278,"props":1081,"children":1082},{},[1083,1088],{"type":51,"tag":129,"props":1084,"children":1085},{},[1086],{"type":57,"value":1087},"Motivation",{"type":57,"value":1089}," — link to the originating override\nfile in the adopter repo (the user's project), with\nenough context that the framework reviewer\nunderstands the use case without reading the full\noverride.",{"type":51,"tag":278,"props":1091,"children":1092},{},[1093,1098],{"type":51,"tag":129,"props":1094,"children":1095},{},[1096],{"type":57,"value":1097},"Migration path for existing adopters",{"type":57,"value":1099}," — if the\nchange introduces a new config knob, explain the\ndefault; if it changes a default, explain how\nadopters opt out.",{"type":51,"tag":278,"props":1101,"children":1102},{},[1103,1108],{"type":51,"tag":129,"props":1104,"children":1105},{},[1106],{"type":57,"value":1107},"Test plan",{"type":57,"value":1109}," — what the user verified locally.",{"type":51,"tag":278,"props":1111,"children":1112},{},[1113,1118,1120,1125],{"type":51,"tag":129,"props":1114,"children":1115},{},[1116],{"type":57,"value":1117},"Confirm with the user before posting",{"type":57,"value":1119},". Show the\nexact title + body. Wait for \"OK to post\" \u002F \"yes\" \u002F\n\"send\" \u002F similar before running ",{"type":51,"tag":80,"props":1121,"children":1123},{"className":1122},[],[1124],{"type":57,"value":415},{"type":57,"value":143},{"type":51,"tag":278,"props":1127,"children":1128},{},[1129,1134,1136,1142,1144,1150,1152,1162,1164,1170,1172,1292,1296],{"type":51,"tag":129,"props":1130,"children":1131},{},[1132],{"type":57,"value":1133},"Pick the labels.",{"type":57,"value":1135}," Every framework PR carries at least one\n",{"type":51,"tag":80,"props":1137,"children":1139},{"className":1138},[],[1140],{"type":57,"value":1141},"family:*",{"type":57,"value":1143}," and one ",{"type":51,"tag":80,"props":1145,"children":1147},{"className":1146},[],[1148],{"type":57,"value":1149},"capability:*",{"type":57,"value":1151}," label per\n",{"type":51,"tag":102,"props":1153,"children":1155},{"href":1154},"..\u002F..\u002Fdocs\u002Flabels-and-capabilities.md",[1156],{"type":51,"tag":80,"props":1157,"children":1159},{"className":1158},[],[1160],{"type":57,"value":1161},"docs\u002Flabels-and-capabilities.md",{"type":57,"value":1163},".\nThe override is upstreaming a change to skill ",{"type":51,"tag":80,"props":1165,"children":1167},{"className":1166},[],[1168],{"type":57,"value":1169},"\u003Cskill>",{"type":57,"value":1171},", so:",{"type":51,"tag":274,"props":1173,"children":1174},{},[1175,1244,1272],{"type":51,"tag":278,"props":1176,"children":1177},{},[1178,1183,1185,1191,1193,1199,1200,1206,1208,1214,1215,1221,1222,1228,1229,1235,1236,1242],{"type":51,"tag":80,"props":1179,"children":1181},{"className":1180},[],[1182],{"type":57,"value":1141},{"type":57,"value":1184}," — follow the skill's family\n(",{"type":51,"tag":80,"props":1186,"children":1188},{"className":1187},[],[1189],{"type":57,"value":1190},"family:pr-management",{"type":57,"value":1192}," for ",{"type":51,"tag":80,"props":1194,"children":1196},{"className":1195},[],[1197],{"type":57,"value":1198},"pr-management-*",{"type":57,"value":511},{"type":51,"tag":80,"props":1201,"children":1203},{"className":1202},[],[1204],{"type":57,"value":1205},"family:security",{"type":57,"value":1207},"\nfor ",{"type":51,"tag":80,"props":1209,"children":1211},{"className":1210},[],[1212],{"type":57,"value":1213},"security-*",{"type":57,"value":511},{"type":51,"tag":80,"props":1216,"children":1218},{"className":1217},[],[1219],{"type":57,"value":1220},"family:setup",{"type":57,"value":1192},{"type":51,"tag":80,"props":1223,"children":1225},{"className":1224},[],[1226],{"type":57,"value":1227},"setup-*",{"type":57,"value":511},{"type":51,"tag":80,"props":1230,"children":1232},{"className":1231},[],[1233],{"type":57,"value":1234},"family:issue",{"type":57,"value":1207},{"type":51,"tag":80,"props":1237,"children":1239},{"className":1238},[],[1240],{"type":57,"value":1241},"issue-*",{"type":57,"value":1243},", etc.).",{"type":51,"tag":278,"props":1245,"children":1246},{},[1247,1252,1254,1259,1261,1271],{"type":51,"tag":80,"props":1248,"children":1250},{"className":1249},[],[1251],{"type":57,"value":1149},{"type":57,"value":1253}," — the capability the change is ",{"type":51,"tag":65,"props":1255,"children":1256},{},[1257],{"type":57,"value":1258},"implementing",{"type":57,"value":1260},",\nnot the file paths touched. Look up the skill's capability in\nthe skill-to-capability map at\n",{"type":51,"tag":102,"props":1262,"children":1264},{"href":1263},"..\u002F..\u002Fdocs\u002Flabels-and-capabilities.md#capability-to-skill-map",[1265],{"type":51,"tag":80,"props":1266,"children":1268},{"className":1267},[],[1269],{"type":57,"value":1270},"docs\u002Flabels-and-capabilities.md#capability-to-skill-map",{"type":57,"value":143},{"type":51,"tag":278,"props":1273,"children":1274},{},[1275,1277,1283,1284,1290],{"type":57,"value":1276},"Add ",{"type":51,"tag":80,"props":1278,"children":1280},{"className":1279},[],[1281],{"type":57,"value":1282},"kind:*",{"type":57,"value":120},{"type":51,"tag":80,"props":1285,"children":1287},{"className":1286},[],[1288],{"type":57,"value":1289},"mode:*",{"type":57,"value":1291}," when they apply per the same doc.",{"type":51,"tag":1293,"props":1294,"children":1295},"br",{},[],{"type":57,"value":1297},"Surface the chosen labels in the confirmation preview alongside\nthe PR title and body, so the user sees them before posting.",{"type":51,"tag":278,"props":1299,"children":1300},{},[1301,1303],{"type":57,"value":1302},"Write the PR body to a tempfile first, then create the PR:",{"type":51,"tag":1304,"props":1305,"children":1310},"pre",{"className":1306,"code":1307,"language":1308,"meta":1309,"style":1309},"language-bash shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","# Write tool: file_path: \u002Ftmp\u002Foverride-pr-body.md, content: \u003CPR body>\ngh pr create --repo apache\u002Fmagpie --base main \\\n  --head \u003Cuser>:\u003Cbranch> --title \"...\" --body-file \u002Ftmp\u002Foverride-pr-body.md \\\n  --label \"family:\u003Cfamily>\" --label \"capability:\u003Ccapability>\"\n","bash","",[1311],{"type":51,"tag":80,"props":1312,"children":1313},{"__ignoreMap":1309},[1314,1326,1373,1460],{"type":51,"tag":1315,"props":1316,"children":1319},"span",{"class":1317,"line":1318},"line",1,[1320],{"type":51,"tag":1315,"props":1321,"children":1323},{"style":1322},"--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#546E7A;--shiki-default-font-style:italic;--shiki-dark:#676E95;--shiki-dark-font-style:italic",[1324],{"type":57,"value":1325},"# Write tool: file_path: \u002Ftmp\u002Foverride-pr-body.md, content: \u003CPR body>\n",{"type":51,"tag":1315,"props":1327,"children":1329},{"class":1317,"line":1328},2,[1330,1336,1342,1347,1352,1357,1362,1367],{"type":51,"tag":1315,"props":1331,"children":1333},{"style":1332},"--shiki-light:#E2931D;--shiki-default:#FFCB6B;--shiki-dark:#FFCB6B",[1334],{"type":57,"value":1335},"gh",{"type":51,"tag":1315,"props":1337,"children":1339},{"style":1338},"--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D",[1340],{"type":57,"value":1341}," pr",{"type":51,"tag":1315,"props":1343,"children":1344},{"style":1338},[1345],{"type":57,"value":1346}," create",{"type":51,"tag":1315,"props":1348,"children":1349},{"style":1338},[1350],{"type":57,"value":1351}," --repo",{"type":51,"tag":1315,"props":1353,"children":1354},{"style":1338},[1355],{"type":57,"value":1356}," apache\u002Fmagpie",{"type":51,"tag":1315,"props":1358,"children":1359},{"style":1338},[1360],{"type":57,"value":1361}," --base",{"type":51,"tag":1315,"props":1363,"children":1364},{"style":1338},[1365],{"type":57,"value":1366}," main",{"type":51,"tag":1315,"props":1368,"children":1370},{"style":1369},"--shiki-light:#90A4AE;--shiki-default:#EEFFFF;--shiki-dark:#BABED8",[1371],{"type":57,"value":1372}," \\\n",{"type":51,"tag":1315,"props":1374,"children":1376},{"class":1317,"line":1375},3,[1377,1382,1388,1393,1398,1403,1407,1412,1417,1422,1426,1431,1436,1441,1446,1451,1456],{"type":51,"tag":1315,"props":1378,"children":1379},{"style":1338},[1380],{"type":57,"value":1381},"  --head",{"type":51,"tag":1315,"props":1383,"children":1385},{"style":1384},"--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF",[1386],{"type":57,"value":1387}," \u003C",{"type":51,"tag":1315,"props":1389,"children":1390},{"style":1338},[1391],{"type":57,"value":1392},"use",{"type":51,"tag":1315,"props":1394,"children":1395},{"style":1369},[1396],{"type":57,"value":1397},"r",{"type":51,"tag":1315,"props":1399,"children":1400},{"style":1384},[1401],{"type":57,"value":1402},">",{"type":51,"tag":1315,"props":1404,"children":1405},{"style":1338},[1406],{"type":57,"value":923},{"type":51,"tag":1315,"props":1408,"children":1409},{"style":1384},[1410],{"type":57,"value":1411},"\u003C",{"type":51,"tag":1315,"props":1413,"children":1414},{"style":1338},[1415],{"type":57,"value":1416},"branc",{"type":51,"tag":1315,"props":1418,"children":1419},{"style":1369},[1420],{"type":57,"value":1421},"h",{"type":51,"tag":1315,"props":1423,"children":1424},{"style":1384},[1425],{"type":57,"value":1402},{"type":51,"tag":1315,"props":1427,"children":1428},{"style":1338},[1429],{"type":57,"value":1430}," --title",{"type":51,"tag":1315,"props":1432,"children":1433},{"style":1384},[1434],{"type":57,"value":1435}," \"",{"type":51,"tag":1315,"props":1437,"children":1438},{"style":1338},[1439],{"type":57,"value":1440},"...",{"type":51,"tag":1315,"props":1442,"children":1443},{"style":1384},[1444],{"type":57,"value":1445},"\"",{"type":51,"tag":1315,"props":1447,"children":1448},{"style":1338},[1449],{"type":57,"value":1450}," --body-file",{"type":51,"tag":1315,"props":1452,"children":1453},{"style":1338},[1454],{"type":57,"value":1455}," \u002Ftmp\u002Foverride-pr-body.md",{"type":51,"tag":1315,"props":1457,"children":1458},{"style":1369},[1459],{"type":57,"value":1372},{"type":51,"tag":1315,"props":1461,"children":1463},{"class":1317,"line":1462},4,[1464,1469,1473,1478,1482,1487,1491,1496],{"type":51,"tag":1315,"props":1465,"children":1466},{"style":1338},[1467],{"type":57,"value":1468},"  --label",{"type":51,"tag":1315,"props":1470,"children":1471},{"style":1384},[1472],{"type":57,"value":1435},{"type":51,"tag":1315,"props":1474,"children":1475},{"style":1338},[1476],{"type":57,"value":1477},"family:\u003Cfamily>",{"type":51,"tag":1315,"props":1479,"children":1480},{"style":1384},[1481],{"type":57,"value":1445},{"type":51,"tag":1315,"props":1483,"children":1484},{"style":1338},[1485],{"type":57,"value":1486}," --label",{"type":51,"tag":1315,"props":1488,"children":1489},{"style":1384},[1490],{"type":57,"value":1435},{"type":51,"tag":1315,"props":1492,"children":1493},{"style":1338},[1494],{"type":57,"value":1495},"capability:\u003Ccapability>",{"type":51,"tag":1315,"props":1497,"children":1498},{"style":1384},[1499],{"type":57,"value":1500},"\"\n",{"type":51,"tag":442,"props":1502,"children":1504},{"id":1503},"step-7-post-pr-cleanup-pointer",[1505],{"type":57,"value":1506},"Step 7 — Post-PR cleanup pointer",{"type":51,"tag":59,"props":1508,"children":1509},{},[1510],{"type":57,"value":1511},"After the PR is open, surface to the user:",{"type":51,"tag":1304,"props":1513,"children":1517},{"className":1514,"code":1516,"language":57,"meta":1309},[1515],"language-text","Framework PR opened: \u003CPR URL>\n\nNext steps once it merges:\n\n  1. \u002Fmagpie-setup upgrade   (in \u003Cadopter-repo>)\n     - Bumps the snapshot to the new framework version.\n     - .apache-magpie.lock will reflect the new pin.\n  2. Delete .apache-magpie-overrides\u002F\u003Cskill>.md in \u003Cadopter-repo>\n     - The override is now redundant; the framework does\n       what the override used to do.\n  3. Commit the deletion + the bumped lock together.\n",[1518],{"type":51,"tag":80,"props":1519,"children":1520},{"__ignoreMap":1309},[1521],{"type":57,"value":1516},{"type":51,"tag":59,"props":1523,"children":1524},{},[1525,1527,1532],{"type":57,"value":1526},"The skill ",{"type":51,"tag":129,"props":1528,"children":1529},{},[1530],{"type":57,"value":1531},"does not",{"type":57,"value":1533}," delete the override file itself —\nthat happens after the PR merges, and the skill cannot\npredict when (or if) the framework reviewers accept the\nPR. Deletion is the user's manual cleanup once the PR\nlands.",{"type":51,"tag":145,"props":1535,"children":1537},{"id":1536},"output-to-the-user-skill-end",[1538],{"type":57,"value":1539},"Output to the user (skill end)",{"type":51,"tag":1304,"props":1541,"children":1544},{"className":1542,"code":1543,"language":57,"meta":1309},[1515],"✓ Override picked:        .apache-magpie-overrides\u002F\u003Cskill>.md\n✓ Framework skill:        \u003Cframework-skill>\n✓ Decision:               upstreamable as \u003Cshape from Step 4>\n✓ Framework clone:        \u003Cframework-clone>\n✓ Branch:                 feat\u002F\u003Cshort-description>\n✓ Commits:                \u003Ccount>\n✓ PR opened:              \u003CPR URL>\n\nNext: wait for the PR to merge, then in \u003Cadopter-repo>:\n  \u002Fmagpie-setup upgrade\n  rm .apache-magpie-overrides\u002F\u003Cskill>.md\n  git add -A && git commit -m \"Remove override \u003Cskill>: upstreamed in apache\u002Fmagpie#\u003CN>\"\n",[1545],{"type":51,"tag":80,"props":1546,"children":1547},{"__ignoreMap":1309},[1548],{"type":57,"value":1543},{"type":51,"tag":145,"props":1550,"children":1552},{"id":1551},"failure-modes",[1553],{"type":57,"value":1554},"Failure modes",{"type":51,"tag":788,"props":1556,"children":1557},{},[1558,1579],{"type":51,"tag":792,"props":1559,"children":1560},{},[1561],{"type":51,"tag":796,"props":1562,"children":1563},{},[1564,1569,1574],{"type":51,"tag":800,"props":1565,"children":1566},{},[1567],{"type":57,"value":1568},"Symptom",{"type":51,"tag":800,"props":1570,"children":1571},{},[1572],{"type":57,"value":1573},"Likely cause",{"type":51,"tag":800,"props":1575,"children":1576},{},[1577],{"type":57,"value":1578},"Remediation",{"type":51,"tag":811,"props":1580,"children":1581},{},[1582,1620,1637,1667,1691],{"type":51,"tag":796,"props":1583,"children":1584},{},[1585,1602,1607],{"type":51,"tag":818,"props":1586,"children":1587},{},[1588,1594,1596],{"type":51,"tag":80,"props":1589,"children":1591},{"className":1590},[],[1592],{"type":57,"value":1593},"\u003Cadopter-repo>",{"type":57,"value":1595}," has no ",{"type":51,"tag":80,"props":1597,"children":1599},{"className":1598},[],[1600],{"type":57,"value":1601},".apache-magpie-overrides\u002F",{"type":51,"tag":818,"props":1603,"children":1604},{},[1605],{"type":57,"value":1606},"not adopted, or adopted without the overrides scaffold",{"type":51,"tag":818,"props":1608,"children":1609},{},[1610,1612,1618],{"type":57,"value":1611},"run ",{"type":51,"tag":80,"props":1613,"children":1615},{"className":1614},[],[1616],{"type":57,"value":1617},"\u002Fmagpie-setup adopt",{"type":57,"value":1619}," (idempotent)",{"type":51,"tag":796,"props":1621,"children":1622},{},[1623,1628,1633],{"type":51,"tag":818,"props":1624,"children":1625},{},[1626],{"type":57,"value":1627},"Step 1 finds zero overrides",{"type":51,"tag":818,"props":1629,"children":1630},{},[1631],{"type":57,"value":1632},"nothing to upstream — adopter has no local modifications recorded",{"type":51,"tag":818,"props":1634,"children":1635},{},[1636],{"type":57,"value":773},{"type":51,"tag":796,"props":1638,"children":1639},{},[1640,1650,1662],{"type":51,"tag":818,"props":1641,"children":1642},{},[1643,1648],{"type":51,"tag":80,"props":1644,"children":1646},{"className":1645},[],[1647],{"type":57,"value":375},{"type":57,"value":1649}," not found",{"type":51,"tag":818,"props":1651,"children":1652},{},[1653,1655,1660],{"type":57,"value":1654},"user has not cloned ",{"type":51,"tag":80,"props":1656,"children":1658},{"className":1657},[],[1659],{"type":57,"value":93},{"type":57,"value":1661}," yet",{"type":51,"tag":818,"props":1663,"children":1664},{},[1665],{"type":57,"value":1666},"help them clone, then resume",{"type":51,"tag":796,"props":1668,"children":1669},{},[1670,1675,1680],{"type":51,"tag":818,"props":1671,"children":1672},{},[1673],{"type":57,"value":1674},"Framework pre-commit fails after the implementation",{"type":51,"tag":818,"props":1676,"children":1677},{},[1678],{"type":57,"value":1679},"the change does not match framework conventions",{"type":51,"tag":818,"props":1681,"children":1682},{},[1683,1685],{"type":57,"value":1684},"iterate with the user, re-run pre-commit, do not bypass with ",{"type":51,"tag":80,"props":1686,"children":1688},{"className":1687},[],[1689],{"type":57,"value":1690},"--no-verify",{"type":51,"tag":796,"props":1692,"children":1693},{},[1694,1699,1704],{"type":51,"tag":818,"props":1695,"children":1696},{},[1697],{"type":57,"value":1698},"User decides mid-flow that the override is project-specific after all",{"type":51,"tag":818,"props":1700,"children":1701},{},[1702],{"type":57,"value":1703},"wrong call in Step 3",{"type":51,"tag":818,"props":1705,"children":1706},{},[1707],{"type":57,"value":1708},"stop without opening a PR; the override file in the adopter repo is unchanged, no harm done",{"type":51,"tag":145,"props":1710,"children":1712},{"id":1711},"what-this-skill-is-not-for",[1713],{"type":57,"value":1714},"What this skill is NOT for",{"type":51,"tag":274,"props":1716,"children":1717},{},[1718,1739,1761,1782],{"type":51,"tag":278,"props":1719,"children":1720},{},[1721,1723,1728,1730,1738],{"type":57,"value":1722},"Not for ",{"type":51,"tag":65,"props":1724,"children":1725},{},[1726],{"type":57,"value":1727},"applying",{"type":57,"value":1729}," an override at run-time — that is the\nper-skill pre-flight protocol documented in\n",{"type":51,"tag":102,"props":1731,"children":1732},{"href":104},[1733],{"type":51,"tag":80,"props":1734,"children":1736},{"className":1735},[],[1737],{"type":57,"value":111},{"type":57,"value":143},{"type":51,"tag":278,"props":1740,"children":1741},{},[1742,1743,1748,1750,1760],{"type":57,"value":1722},{"type":51,"tag":65,"props":1744,"children":1745},{},[1746],{"type":57,"value":1747},"creating",{"type":57,"value":1749}," a new override — that is\n",{"type":51,"tag":102,"props":1751,"children":1753},{"href":1752},"..\u002Fsetup\u002Foverrides.md",[1754],{"type":51,"tag":80,"props":1755,"children":1757},{"className":1756},[],[1758],{"type":57,"value":1759},"\u002Fmagpie-setup override \u003Cskill>",{"type":57,"value":143},{"type":51,"tag":278,"props":1762,"children":1763},{},[1764,1765,1770,1772,1780],{"type":57,"value":1722},{"type":51,"tag":65,"props":1766,"children":1767},{},[1768],{"type":57,"value":1769},"upgrading",{"type":57,"value":1771}," the snapshot — that is\n",{"type":51,"tag":102,"props":1773,"children":1774},{"href":245},[1775],{"type":51,"tag":80,"props":1776,"children":1778},{"className":1777},[],[1779],{"type":57,"value":141},{"type":57,"value":1781},".\nRun that BEFORE this skill if drift exists.",{"type":51,"tag":278,"props":1783,"children":1784},{},[1785],{"type":57,"value":1786},"Not for arbitrary framework PRs unrelated to overrides.\nThis skill is specifically the override → PR flow. Other\nframework contributions (new skill, new tool, refactor)\ngo through the framework's normal PR workflow.",{"type":51,"tag":145,"props":1788,"children":1790},{"id":1789},"cross-references",[1791],{"type":57,"value":1792},"Cross-references",{"type":51,"tag":274,"props":1794,"children":1795},{},[1796,1809,1837],{"type":51,"tag":278,"props":1797,"children":1798},{},[1799,1807],{"type":51,"tag":102,"props":1800,"children":1801},{"href":104},[1802],{"type":51,"tag":80,"props":1803,"children":1805},{"className":1804},[],[1806],{"type":57,"value":111},{"type":57,"value":1808}," — the override contract.",{"type":51,"tag":278,"props":1810,"children":1811},{},[1812,1821,1823,1828,1830,1835],{"type":51,"tag":102,"props":1813,"children":1814},{"href":1752},[1815],{"type":51,"tag":80,"props":1816,"children":1818},{"className":1817},[],[1819],{"type":57,"value":1820},"setup\u002Foverrides.md",{"type":57,"value":1822}," — how to ",{"type":51,"tag":65,"props":1824,"children":1825},{},[1826],{"type":57,"value":1827},"create",{"type":57,"value":1829}," \u002F ",{"type":51,"tag":65,"props":1831,"children":1832},{},[1833],{"type":57,"value":1834},"open",{"type":57,"value":1836}," an override.",{"type":51,"tag":278,"props":1838,"children":1839},{},[1840,1849],{"type":51,"tag":102,"props":1841,"children":1842},{"href":245},[1843],{"type":51,"tag":80,"props":1844,"children":1846},{"className":1845},[],[1847],{"type":57,"value":1848},"setup\u002Fupgrade.md",{"type":57,"value":1850}," — how to upgrade the snapshot post-merge.",{"type":51,"tag":1852,"props":1853,"children":1854},"style",{},[1855],{"type":57,"value":1856},"html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"items":1858,"total":2011},[1859,1877,1893,1904,1917,1930,1948,1959,1969,1980,1990,2000],{"slug":1860,"name":1860,"fn":1861,"description":1862,"org":1863,"tags":1864,"stars":1874,"repoUrl":1875,"updatedAt":1876},"datafusion-python","write Apache DataFusion Python code","Use when the user is writing datafusion-python (Apache DataFusion Python bindings) DataFrame or SQL code. Covers imports, data loading, DataFrame operations, expression building, SQL-to-DataFrame mappings, idiomatic patterns, and common pitfalls.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1865,1868,1871],{"name":1866,"slug":1867,"type":15},"Data Analysis","data-analysis",{"name":1869,"slug":1870,"type":15},"Python","python",{"name":1872,"slug":1873,"type":15},"SQL","sql",593,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fdatafusion-python","2026-07-12T08:36:04.957626",{"slug":1878,"name":1878,"fn":1879,"description":1880,"org":1881,"tags":1882,"stars":1890,"repoUrl":1891,"updatedAt":1892},"bydbql","generate and execute BanyanDB BydbQL queries","Generate, validate, and optionally execute read-only BanyanDB BydbQL for STREAM, MEASURE, TRACE, and PROPERTY resources. Use when the user asks to query BanyanDB, translate natural language to BydbQL, inspect BanyanDB schema or data, validate BydbQL, or fetch raw BanyanDB records.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1883,1886,1889],{"name":1884,"slug":1885,"type":15},"Analytics","analytics",{"name":1887,"slug":1888,"type":15},"Database","database",{"name":1872,"slug":1873,"type":15},344,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fskywalking-banyandb","2026-07-12T08:31:01.294423",{"slug":1894,"name":1894,"fn":1895,"description":1896,"org":1897,"tags":1898,"stars":1890,"repoUrl":1891,"updatedAt":1903},"compiling","compile and build BanyanDB projects","Compile and build the SkyWalking BanyanDB project. Use when the user asks to compile, build, or generate code for this project.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1899,1902],{"name":1900,"slug":1901,"type":15},"Build","build",{"name":20,"slug":21,"type":15},"2026-07-12T08:31:06.373309",{"slug":1905,"name":1905,"fn":1906,"description":1907,"org":1908,"tags":1909,"stars":1890,"repoUrl":1891,"updatedAt":1916},"gh-pull-request","create GitHub pull requests for BanyanDB","Create a GitHub pull request for SkyWalking BanyanDB. Use when the user asks to create a PR, submit changes, or open a pull request.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1910,1913],{"name":1911,"slug":1912,"type":15},"GitHub","github",{"name":1914,"slug":1915,"type":15},"Pull Requests","pull-requests","2026-07-12T08:31:03.792415",{"slug":1918,"name":1918,"fn":1919,"description":1920,"org":1921,"tags":1922,"stars":1890,"repoUrl":1891,"updatedAt":1929},"vendor-update","update Go and Node.js vendor dependencies","Upgrade Go\u002FNode.js vendor dependencies and sync tool versions. Use whenever the user says \"upgrade dependencies\", \"update vendors\", \"vendor update\", \"run vendor-upgrade\", \"bump dependencies\", \"update packages\", or asks to run the `vendor-update` Make target. This skill also checks `scripts\u002Fbuild\u002Fversion.mk` after upgrading to see if any tracked tool versions need updating too, and removes stale binaries from `bin\u002F` when versions change.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1923,1926],{"name":1924,"slug":1925,"type":15},"Go","go",{"name":1927,"slug":1928,"type":15},"Node.js","node-js","2026-07-12T08:31:02.555555",{"slug":1931,"name":1931,"fn":1932,"description":1933,"org":1934,"tags":1935,"stars":1945,"repoUrl":1946,"updatedAt":1947},"cayenne-cgen","generate Cayenne entity Java classes","Use this skill whenever the user wants to (re)generate Cayenne entity Java classes from a DataMap. Trigger on phrases like 'generate Java classes', 'regenerate entities', 'run cgen', 'create the entity classes', 'why is the Artist class missing fields', 'where did the `_Abstract*` classes come from', 'sync the entity classes with the model', or any request to materialize Java from the DataMap. Also trigger as a follow-up after modeling changes (someone added an entity, attribute, or relationship and now the Java side is stale). This skill exclusively uses the `mcp__cayenne__cgen_run` MCP tool — it does NOT use `mvn cayenne:cgen` or the Gradle cgen task.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1936,1939,1942],{"name":1937,"slug":1938,"type":15},"Data Modeling","data-modeling",{"name":1940,"slug":1941,"type":15},"Java","java",{"name":1943,"slug":1944,"type":15},"ORM","orm",343,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fcayenne","2026-07-12T08:32:33.575211",{"slug":1949,"name":1949,"fn":1950,"description":1951,"org":1952,"tags":1953,"stars":1945,"repoUrl":1946,"updatedAt":1958},"cayenne-db-import","import database schema into Cayenne DataMaps","Use this skill when the user wants to import database schema metadata into a Cayenne DataMap — the *model\u002Fmapping only*, not names or Java classes. Trigger on phrases like 'reverse engineer the database', 'import the schema', 'generate a DataMap from my DB', 'add the new tables from the DB into the model', 'import the customer table', 'create entities from these tables', or any request to read database metadata to populate or update a DataMap's XML. This is for *full schema* or *bulk table* import; one-off a-la-carte entity additions belong in the cayenne-modeling skill. IMPORTANT — scope: this imports the mapping ONLY; it does not clean up the Object-layer names or (re)generate Java classes. When the user wants their whole project brought in line with the DB ('sync my project with the database', 'my schema changed, update everything', 'update my entities\u002Fclasses from the DB'), that is the end-to-end `cayenne-full-db-sync` skill, which runs this import and then name cleanup and class generation. To regenerate classes alone use `cayenne-cgen`. The skill runs reverse engineering directly via the `mcp__cayenne__dbimport_run` MCP tool when a DBConnector is already configured; otherwise it opens the CayenneModeler GUI via `mcp__cayenne__open_project` to configure the connection first.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1954,1955,1956,1957],{"name":1887,"slug":1888,"type":15},{"name":1940,"slug":1941,"type":15},{"name":1943,"slug":1944,"type":15},{"name":1872,"slug":1873,"type":15},"2026-07-19T05:40:33.655062",{"slug":1960,"name":1960,"fn":1961,"description":1962,"org":1963,"tags":1964,"stars":1945,"repoUrl":1946,"updatedAt":1968},"cayenne-full-db-sync","synchronize Cayenne projects with database","Use this skill when the user wants to bring their WHOLE Cayenne project in line with the database in one shot — the mapping, the Object-layer names, and the generated Java classes together. This is the end-to-end 'sync with the DB' workflow, and it orchestrates three skills in order: `cayenne-db-import` (import schema metadata into the DataMap) → `cayenne-model-naming` (polish the just-imported names) → `cayenne-cgen` (regenerate Java classes). Trigger on holistic phrases like 'sync my project with the database', 'sync with the DB', 'my schema changed, update everything', 'update my entities\u002Fclasses from the database', 'reverse engineer and regenerate the classes', 'import the new tables and rebuild the entities', 'full DB sync', 'bring the model and classes up to date with the DB'. The distinguishing signal is scope: the user wants the whole project (mapping + names + Java code), not just one stage. For the *model\u002Fmapping only* (no name cleanup, no class generation) use `cayenne-db-import`; to (re)generate classes alone use `cayenne-cgen`; to clean names alone use `cayenne-model-naming`. Uses the `mcp__cayenne__dbimport_run` and `mcp__cayenne__cgen_run` MCP tools via the sub-skills; does NOT use Maven or Gradle goals.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1965,1966,1967],{"name":1887,"slug":1888,"type":15},{"name":1940,"slug":1941,"type":15},{"name":1943,"slug":1944,"type":15},"2026-07-19T06:03:49.112969",{"slug":1970,"name":1970,"fn":1971,"description":1972,"org":1973,"tags":1974,"stars":1945,"repoUrl":1946,"updatedAt":1979},"cayenne-model-naming","clean up Cayenne object-layer names","Use this skill to clean up Object-layer names in a Cayenne DataMap — ObjEntity, ObjAttribute, and ObjRelationship names, plus DbRelationship names (the first-class unit of relationship cleanup — every FK has one whether or not an ObjRelationship was generated; the ObjRelationship name is synced to it when one exists) — so they read as descriptive, consistent Java. Trigger on phrases like 'clean up the model names', 'fix the entity names', 'these names look ugly', 'make the names descriptive', 'normalize the ObjEntity\u002Fattribute\u002Frelationship names', 'why is this relationship called team1', 'rename entities to be consistent', 'the import produced Gametype instead of GameType'. Invoke it on an explicit user request, or as a manual follow-up after a `cayenne-db-import` to polish the just-imported additions — it is never triggered automatically. IMPORTANT: this is a LIGHT polish pass — CayenneModeler's reverse-engineering already produces good names for the common case; only improve the specific things its deterministic algorithm cannot (run-together names with no separators like `gametype`, meaningless numbered names like `team1` from multiple relationships between two tables, and a common entity prefix that leaks into relationship names like `aaOrders`). Do NOT rewrite names that are already correct. This is Obj-layer naming polish; for structural model edits use `cayenne-modeling`, and for regenerating classes afterward use `cayenne-cgen`.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1975,1976,1977,1978],{"name":1937,"slug":1938,"type":15},{"name":1887,"slug":1888,"type":15},{"name":1940,"slug":1941,"type":15},{"name":1943,"slug":1944,"type":15},"2026-07-22T05:35:32.342548",{"slug":1981,"name":1981,"fn":1982,"description":1983,"org":1984,"tags":1985,"stars":1945,"repoUrl":1946,"updatedAt":1989},"cayenne-modeler","manage Cayenne projects with CayenneModeler","Use this skill when the user explicitly wants to open CayenneModeler (the GUI) on a Cayenne project, or when the modeling task is inherently visual — reverse engineering (delegated to cayenne-db-import), bulk relationship layout, multi-entity visual refactoring. Trigger on phrases like 'open the Modeler', 'open in CayenneModeler', 'launch the GUI', 'edit visually', 'show me the project in the Modeler'. Do NOT trigger as a fallback for ordinary a-la-carte XML edits — those belong in the cayenne-modeling skill, which is faster and doesn't require the user to context-switch.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1986,1987,1988],{"name":1937,"slug":1938,"type":15},{"name":1940,"slug":1941,"type":15},{"name":1943,"slug":1944,"type":15},"2026-07-12T08:32:37.199428",{"slug":1991,"name":1991,"fn":1992,"description":1993,"org":1994,"tags":1995,"stars":1945,"repoUrl":1946,"updatedAt":1999},"cayenne-modeling","edit and extend Cayenne ORM models","Use this skill whenever the user wants to edit, inspect, or extend the Cayenne ORM model in a project — adding or modifying entities, attributes, relationships, embeddables, named queries, stored procedures, or DataNodes. Trigger on phrases like 'add an ObjEntity', 'add a DbEntity', 'add a relationship', 'expose this column as an attribute', 'create a new DataMap', 'add a named query', 'create an embeddable', 'add a stored procedure', 'change the attribute type', 'mark this column as nullable', 'rename this entity', or any mention of a Cayenne `*.map.xml` or `cayenne-*.xml` file. Also trigger when the user references modeling concepts (ObjEntity, DbEntity, ObjAttribute, DbAttribute, ObjRelationship, DbRelationship, Embeddable, dbEntityName, deleteRule, db-attribute-path, db-relationship-path, defaultPackage) in the context of a Cayenne-using app. This is the *primary* skill for a-la-carte ORM model manipulation — direct XML edits, not the Modeler GUI.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1996,1997,1998],{"name":1887,"slug":1888,"type":15},{"name":1940,"slug":1941,"type":15},{"name":1943,"slug":1944,"type":15},"2026-07-19T05:40:32.6889",{"slug":2001,"name":2001,"fn":2002,"description":2003,"org":2004,"tags":2005,"stars":1945,"repoUrl":1946,"updatedAt":2010},"cayenne-query","write and modify Cayenne database queries","Use this skill whenever the user wants to write or modify a Cayenne query — fetching entities by criteria, joining, prefetching to avoid N+1, ordering, paginating, aggregating, or running raw SQL through Cayenne. Trigger on phrases like 'query for X', 'fetch all artists where ...', 'write an ObjectSelect', 'use SQLSelect', 'use SelectById', 'add a prefetch', 'get distinct values', 'count rows', 'find by ID', 'load by primary key', 'build a Cayenne expression', 'why am I getting N+1', 'how do I paginate', 'select a single column', 'select columns into a DTO', 'named query in the DataMap'. Do NOT trigger for modeling changes (use cayenne-modeling) or runtime bootstrap (use cayenne-runtime).",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2006,2007,2008,2009],{"name":1887,"slug":1888,"type":15},{"name":1940,"slug":1941,"type":15},{"name":1943,"slug":1944,"type":15},{"name":1872,"slug":1873,"type":15},"2026-07-12T08:32:35.072322",108,{"items":2013,"total":2110},[2014,2029,2045,2059,2075,2087,2097],{"slug":2015,"name":2015,"fn":2016,"description":2017,"org":2018,"tags":2019,"stars":22,"repoUrl":23,"updatedAt":2028},"generate-cve-json","generate CVE JSON documents","Generate a CVE 5.x JSON document from an \u003Ctracker> tracking\nissue, ready to paste into the Vulnogram `#source` tab of the ASF CVE tool\nat https:\u002F\u002Fcveprocess.apache.org\u002Fcve5\u002F\u003CCVE-ID>#source. The conversion is\ndeterministic: same issue in, same JSON bytes out. Handles multiple\ncredits (one per line) and multiple references (URLs extracted from the\nissue's \"Public advisory URL\" and \"PR with the fix\" fields; the\n\"Security mailing list thread\" field is treated as internal-only and\nnever exported).\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2020,2023,2025],{"name":2021,"slug":2022,"type":15},"Compliance","compliance",{"name":2024,"slug":32,"type":15},"Security",{"name":2026,"slug":2027,"type":15},"Technical Writing","technical-writing","2026-07-12T08:35:41.218722",{"slug":2030,"name":2030,"fn":2031,"description":2032,"org":2033,"tags":2034,"stars":22,"repoUrl":23,"updatedAt":2044},"magpie-audit-finding-fix","fix findings from code audit tools","For a batch of findings from a non-security audit tool\n(`\u003Caudit-tool>` — ruff \u002F flake8 \u002F mypy \u002F pylint \u002F CodeQL \u002F\nApache Verum \u002F Apache Caer \u002F equivalent; full list in the body)\nagainst `\u003Cupstream>`, draft the smallest fix for each finding.\nRe-runs the tool after each batch to confirm the findings are\ncleared. Produces a commit and a hand-back artefact; never opens\na PR on autopilot or merges.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2035,2038,2041],{"name":2036,"slug":2037,"type":15},"Audit","audit",{"name":2039,"slug":2040,"type":15},"Code Analysis","code-analysis",{"name":2042,"slug":2043,"type":15},"Debugging","debugging","2026-07-12T08:35:13.930479",{"slug":2046,"name":2046,"fn":2047,"description":2048,"org":2049,"tags":2050,"stars":22,"repoUrl":23,"updatedAt":2058},"magpie-ci-runner-audit","audit GitHub Actions workflow runner compatibility","Read-only audit of GitHub Actions workflow runner compatibility\nfor one repository, an explicit repository set, one Apache project\nwith multiple repositories, or the full Apache GitHub org. Finds\nobsolete GitHub-hosted runner labels and macOS runner\u002Ftool\narchitecture mismatches. Produces TSV evidence files; never edits\nworkflows, opens PRs, or posts comments.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2051,2052,2055],{"name":2036,"slug":2037,"type":15},{"name":2053,"slug":2054,"type":15},"CI\u002FCD","ci-cd",{"name":2056,"slug":2057,"type":15},"GitHub Actions","github-actions","2026-07-12T08:34:30.320965",{"slug":2060,"name":2060,"fn":2061,"description":2062,"org":2063,"tags":2064,"stars":22,"repoUrl":23,"updatedAt":2074},"magpie-committer-onboarding","onboard Apache project committers","Post-vote committer and PMC onboarding for Apache projects.\nWalks the nominator through every step from ICLA check to\nwelcome announcement for both incubating podlings and\ngraduated top-level projects.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2065,2068,2071],{"name":2066,"slug":2067,"type":15},"Management","management",{"name":2069,"slug":2070,"type":15},"Operations","operations",{"name":2072,"slug":2073,"type":15},"Process Documentation","process-documentation","2026-07-12T08:33:35.628029",{"slug":2076,"name":2076,"fn":2077,"description":2078,"org":2079,"tags":2080,"stars":22,"repoUrl":23,"updatedAt":2086},"magpie-contributor-activity-sweep","generate contributor activity reports","Read-only GitHub activity card for a named contributor on \u003Cupstream>.\nFetches PR authorship, code-review activity, issues, and PR\u002Fissue\ncomments over a configurable window. Limited to GitHub-visible\nactivity — the body documents the off-GitHub tracks the nominator\nmust supply separately. No readiness verdict is produced; use\ncontributor-nomination for a full nomination brief.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2081,2082,2083],{"name":1884,"slug":1885,"type":15},{"name":1911,"slug":1912,"type":15},{"name":2084,"slug":2085,"type":15},"Reporting","reporting","2026-07-12T08:33:41.715859",{"slug":2088,"name":2088,"fn":2089,"description":2090,"org":2091,"tags":2092,"stars":22,"repoUrl":23,"updatedAt":2096},"magpie-contributor-nomination","generate contributor nomination briefs","Read-only nomination brief for a named GitHub contributor on\n\u003Cupstream>. Aggregates GitHub activity across all contribution\ntracks plus maintainer-supplied off-GitHub signal, and flags\nvendor-neutrality context — the evidence a PMC needs to open\na committer or PMC nomination thread.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2093,2094,2095],{"name":20,"slug":21,"type":15},{"name":1911,"slug":1912,"type":15},{"name":2084,"slug":2085,"type":15},"2026-07-12T08:33:39.211745",{"slug":2098,"name":2098,"fn":2099,"description":2100,"org":2101,"tags":2102,"stars":22,"repoUrl":23,"updatedAt":2109},"magpie-contributor-sentiment","measure contributor sentiment on GitHub repositories","Measures contributor-sentiment signals on \u003Cupstream> over a\nconfigurable window: thread tone (first-response classification),\ntime-to-first-reply (median hours), first-PR retention\n(second-PR rate), and reviewer load (Gini coefficient). Compares\neach signal against a pre-adoption baseline and produces a\nstructured gate report used to decide whether a skill family is\nready to advance from experimental to stable.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2103,2104,2107,2108],{"name":1884,"slug":1885,"type":15},{"name":2105,"slug":2106,"type":15},"Communications","communications",{"name":20,"slug":21,"type":15},{"name":1911,"slug":1912,"type":15},"2026-07-12T08:34:09.204167",71]