Table of Contents generated with DocToc

• Setup skill family
  • Install & first runs
    • The first run
    • Before the first run
    • Try these first
  • Security mailing-list configuration
  • Skills
  • Deep documentation
  • Typical lifecycle
  • Cross-references

Setup skill family

Scope. Works on any project, ASF or not — no Apache-Software-Foundation-specific assumptions baked in.

The setup skill family is the prerequisite for running any framework skill. It walks a new adopter (or a fresh dev machine on an existing adopter) through the secure-agent install — pinned system tools, the project-scope .claude/settings.json sandbox block, the claude-iso clean-env wrapper, the user-scope hooks — and through the ongoing housekeeping (verify install drift, pull framework updates, sync shared user-scope config across machines).

Why a dedicated install skill family? The framework‘s other skills run against pre-disclosure CVE content, private mailing lists, and in-flight tracker discussions. Without the layered defence the setup skills install (sandbox + permission rules + clean-env wrapper), a misconfigured agent can leak credentials or pre-disclosure content into the model provider’s training data or into a public PR. The setup family is what makes the rest of the framework safe to use.

[!TIP] Why this family

• Install, upgrade and adopt the framework without hand-editing a settings file
• A sandboxed agent with a clean environment, walked through step by step — nothing runs with sudo behind your back
• One command tells you what is installed, what the project expects, and whether the two agree

Install & first runs

Install just this family — one plugin, 10 skills. Sandbox, clean environment, and the framework's own install/upgrade.

Once you have added the marketplace:

/plugin install magpie-setup@apache-magpie

New to Magpie? The quick start walks the whole path in one place — install, the first /magpie-setup run, and a recording of it happening — plus the other agents and the secure-isolation setup to run next.

The first run

This family is what the other nine defer to. /magpie-setup works out how Magpie should be wired into the checkout in front of it, prints the plan, and waits — the same run the quick start opens with:

Nothing is written before you approve it.

Before the first run

Nothing here has to be configured. These skills read the file below when it exists — yours in .apache-magpie-local/ or the project's in .apache-magpie-overrides/ — and fall back to a documented default when it does not.

Optional. Each has a documented fallback; absent, the skill still runs.

Try these first

Illustrative shapes, not real transcripts — your output will differ. Nothing below sends, merges, or posts anything without you confirming it.

Put the agent in its sandbox.

/magpie-setup:isolated-setup-install

Check it landed.

/magpie-setup:isolated-setup-verify

See what is wired up.

/magpie-setup:status

Security mailing-list configuration

Set security_list in your project manifest to your project‘s private security mailing list. If it is missing, blank, or still a template TODO, security workflows warn and resolve draft CC from security_inbox.foundation_security_address through the normal project/organization/default configuration chain. For ASF adopters the organization supplies security@apache.org; other adopters use their own organization’s configured address. If neither address is configured, drafting is blocked until configuration is corrected.

The selected address and fallback are shown before draft confirmation. This does not configure subscriptions or redirect list searches to the organization's mailbox. Configure mail reads separately; read-only work can continue only when its own prerequisites are met. See the shared security draft CC resolution for the complete rule.

Skills

Deep documentation

• The Apache Magpie Marketplace — the one marketplace the project publishes, and the recommended way to install. Every agent that can add it, which families to pick, pinning, updates, and verification status.
• Your first run with a family — the configuration walkthrough in terminal steps: what stops, what the wizard scaffolds, and which files a family needs before it will run.
• Companion skill packages — third-party skill packages that pair with a Magpie family, and the install command for each agent that has one. None is a dependency.
• secure-agent-setup.md — full install walkthrough. The authoritative reference the setup-isolated-setup-install skill steps through.
• secure-agent-internals.md — how the layered defence works (sandbox + permission rules + clean-env wrapper) and why each layer exists.
• install-recipes.md — copy-pasteable shell recipes (svn-zip / git-tag / git-branch) for bootstrapping setup into a new adopter repo.
• uninstall.md — counterpart to install-recipes.md: remove the framework artefacts the install flow installed. One path, full plan surfaced before any write.
• sandbox-troubleshooting.md — catalog of known sandbox-shaped failure modes (SSH agent / Yubikey unreachable, test port-bind blocked, docker/podman socket denied) with symptom → root cause → settings.json fix for each. The page to grep when a normal-looking operation fails in the sandbox in an unexpected way.
• Individual use — using Magpie on any repo, adopted or not, with nothing committed and nothing asked of teammates. The default, and the half that asks no one's permission.
• Team adoption — what a repo commits so every contributor arrives with a recommended set: the floor lock, the default plugin set, the shared overrides, and keeping them current. The maintainer half of the pair.
• per-role-mcp-access.md — how to enable an MCP server for yourself only (e.g. a release manager enabling a Policy MCP, a security triage member enabling a private CVE database) without touching shared project config: register the server in user-scope Claude settings, then write a personal .apache-magpie-local/<skill>.md override.

Typical lifecycle

new dev machine
  ↓ setup-isolated-setup-install
isolated setup installed
  ↓ setup-isolated-setup-verify (any time, especially after Claude Code upgrade)
verified
  ↓ setup-isolated-setup-update (monthly / after Claude Code upgrade)
drift surfaced
  ↓ setup-upgrade (when framework releases something new)
framework checkout up to date

setup-shared-config-sync is orthogonal — it commits the user's ~/.claude/CLAUDE.md and other shared config to a private sync repo so a fresh dev machine can pick it up (run after editing any file under ~/.claude-config/).

Cross-references

• Top-level README — Install — 3-step bootstrap.
• docs/prerequisites.md — what each framework skill needs (Claude Code, Gmail MCP, GitHub auth, browser, etc.).