feat(validator): drop mcp from optional frontmatter keys (#828) No skill uses an mcp: frontmatter key; remove it from the optional set so the taxonomy only carries organization as optional. Co-authored-by: Tester <t@example.com>
Table of Contents generated with DocToc
A reusable, project-agnostic framework for ASF-project automation. Currently in development for ASF projects + Python Core team friendlies. Not a public marketplace skill — adoption is by invitation while the framework is pre-release; once we ship via the ASF release policy, the marketplace path opens up. See release-distribution for the canonical distribution mechanism we will adopt.
[!IMPORTANT] The motivation, scope, and design commitments behind this work live in
MISSION.md— the founding mission of the Apache Magpie Top-Level Project, originally filed as its establishment proposal. Read that for the why; this README is the how once you've decided to adopt.
The framework uses a snapshot + agentic-override adoption model. An adopter project commits a single skill — setup — into their repo. That skill manages everything else:
setup downloads the framework into a gitignored <adopter>/.apache-magpie/ directory. The snapshot is a build artefact, not source — refreshed by /magpie-setup upgrade, never committed.setup symlinks the framework's skills (security, pr-management, the rest of setup) under one canonical home — .agents/skills/ (the path shared by Codex, Cursor, Gemini CLI, Copilot, …) — and gives every other agent dir (.claude/skills/, .github/skills/, …) a thin per-skill relay symlink pointing back at the canonical entry. This is the same regardless of how the adopter previously organised those dirs. The symlinks are also gitignored — they ultimately target the gitignored snapshot, so they would dangle on a fresh clone before /magpie-setup runs.<adopter>/.apache-magpie-overrides/<skill>.md, committed in the adopter repo. The framework's skills consult those files at run-time and apply the overrides before executing default behaviour. See docs/setup/agentic-overrides.md for the contract.No git submodules. No marketplace. No vendored copies of framework skills. Just one committed skill (the bootstrap), a gitignored snapshot, and agent-readable override files.
Two phases — a shell bootstrap that gets setup into your repo, then the skill takeover that wires up the rest interactively.
Pick an install method and follow the verbatim recipe in docs/setup/install-recipes.md:
| Method | When to use | Reproducibility |
|---|---|---|
svn-zip | Production once ASF official releases ship to dist.apache.org (signed + checksummed) | Frozen by version |
git-tag | Pin a specific framework version | Frozen by tag |
git-branch (default main) | WIP path — track the framework‘s main directly. The default during the framework’s pre-release phase. | Tracks tip |
Each recipe is a single shell block that:
.apache-magpie/, .apache-magpie.local.lock, and the framework-skill symlinks to .gitignore..apache-magpie/ (gitignored — build artefact, not source).setup skill into the canonical .agents/skills/magpie-setup/ and adds a relay symlink to it from each agent dir you use (.claude/skills/magpie-setup, .github/skills/magpie-setup).After the recipe completes, the framework snapshot is on disk and the bootstrap skill is in your repo.
Tell your agent: “adopt apache/magpie in my repo” (or invoke /magpie-setup directly). The skill walks through the rest:
.apache-magpie.lock (committed) — the project's pin: install method + URL + ref + verification anchor;.apache-magpie.local.lock (gitignored) — what this machine actually fetched + when;security, pr-management) to symlink in;.apache-magpie-overrides/ (committed) for any local workflow modifications;post-checkout git hook so worktrees re-create runtime state automatically;After the skill finishes, you commit the small, focused diff — the bootstrap skill, the .gitignore entries, the two lock files (committed + gitignore exclusion for the local one), the overrides scaffold, the doc note — and you're done. Open a PR.
Future contributors who clone your repo just say “adopt Magpie in this repo” (or invoke /magpie-setup). The skill reads .apache-magpie.lock (already committed) and re-installs to the same version your project pinned. No need to redo the manual recipe — the committed lock is the project's source-of-truth.
Every framework skill compares the gitignored .apache-magpie.local.lock against the committed .apache-magpie.lock at the top of its run. If they have drifted (project lead bumped the pin, or the local install is stale on a main-tracking adopter), the skill surfaces the gap and proposes /magpie-setup upgrade. upgrade deletes the gitignored snapshot, re-installs per the committed pin, refreshes the gitignored symlinks, and reconciles any agentic overrides — see docs/setup/install-recipes.md and skills/setup/upgrade.md for the full flow.
Ten skill families ship in the framework, all at experimental or stable, and each skill declares its family in a family: frontmatter key. At adoption (and on every upgrade), /magpie-setup offers the opt-in families — and the optional MCP servers (ponymail, apache-projects, gmail-plaintext) — in a single install choice; symlinks for the picked families land in the adopter's skill directory. The two always-on families (setup, utilities) are wired unconditionally and never prompted for.
The Modes column maps each family to the MISSION agent-assistance taxonomy — see docs/modes.md for what each mode means and which modes are still proposed vs. shipping today.
| Family | Type | Modes | Purpose | Detail |
|---|---|---|---|---|
| setup | always-on | (infra) | Isolated agent setup, framework adoption + maintenance, shared-config sync. The prerequisite — at minimum the setup skill itself runs out of this family. | 9 skills, docs/setup/ |
| utilities | always-on | (meta) | Framework meta-skills: author skills (write-skill), restructure them (optimize-skill), reconcile skill state (skill-reconciler), and print a live index (list-skills). | 4 skills |
| security | opt-in | Triage, Drafting | 16-step security-issue handling lifecycle — from security@ import through CVE publication, including state sync. Maintainer-only. | 12 skills, docs/security/ |
| pr-management | opt-in | Triage | Maintainer-facing PR-queue management — triage, stats, deep code review, express-lane merge, stale-sweep, reviewer routing, and pre-first-PR checks. | 8 skills, docs/pr-management/ |
| issue | opt-in | Triage, Drafting | General-issue lifecycle: triage, reproduction, fix drafting, reassess, stale-sweep, deduplication, and backlog reporting. | 8 skills, docs/issue-management/ |
| release-management | opt-in | Triage, Drafting | 14-step ASF release lifecycle, planning issue, RC cut + sign, [VOTE] thread, tally, promote, [ANNOUNCE], archive, audit log. Agent never holds the RM's signing key and never publishes the release. Experimental, all 10 skills shipped. | 10 skills, docs/release-management/ |
| repo-health | opt-in | Triage | Read-only repository-health audits: obsolete runner labels, Actions workflow security, dependency vulnerabilities, license/NOTICE compliance, flaky-test patterns, plus audit-finding fixes. | 6 skills, docs/repo-health/ |
| pairing | opt-in | Pairing | Pair a change with a structured self-review or a multi-agent adversarial review before it lands. | 2 skills, docs/pairing/ |
| mentoring | opt-in | Mentoring | Newcomer-facing mentoring — first-contact welcome, newcomer-issue explanations, and good-first-issue authoring + backlog curation. Experimental. | 4 skills, docs/mentoring/ |
| contributor-growth | opt-in | Triage, Mentoring | The path-to-committer track: activity sweeps, nomination briefs, contributor-sentiment signals, readiness tracking, and committer / post-vote onboarding. | 6 skills, docs/contributor-growth/ |
Beyond the in-tree families, an adopter can pull a skill or whole family from a trusted external source — a repo other than apache/magpie that ships Magpie-shaped skills (with their evals and tests). Where a skill directory would sit, a skills/<name>/source.md redirect names a pinned, verified source the adopter has vouched for; /magpie-setup fetches it into the gitignored snapshot and wires it in exactly like a framework skill. Nothing is fetched unless the adopter commits the pin — see docs/skill-sources/, PRINCIPLES.md §13, and RFC-AI-0006.
After the initial adoption, the same skill handles ongoing maintenance:
/magpie-setup upgrade — refresh the snapshot to a newer framework version + reconcile any overrides against the new framework structure./magpie-setup verify — read-only health check (snapshot intact, symlinks live, .gitignore correct, etc.)./magpie-setup override <framework-skill> — open or scaffold an override file for a framework skill.MISSION.md — draft project-establishment proposal: motivation, scope, design commitments, initial PMC composition target.docs/setup/agentic-overrides.md — the contract between adopters who write overrides and framework skills that read them.docs/prerequisites.md — what a maintainer needs installed before invoking any framework skill (Claude Code, Gmail MCP, GitHub auth, browser, uv, etc.).AGENTS.md — agent instructions, placeholder convention, framework conventions.CONTRIBUTING.md — for framework contributors.