Skip to content

setup

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

setup

README.md

Table of Contents generated with DocToc

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.

Skills

Skill Purpose
setup-isolated-setup-install First-time install of the secure agent setup.
setup-isolated-setup-verify Verify the secure setup landed correctly (static checks on settings.json, hooks, pinned versions).
setup-isolated-setup-doctor Diagnose in-session sandbox friction (SSH agent, port bind, docker/podman socket) and map each fail to a catalog entry.
setup-isolated-setup-update Surface drift between the installed setup and the framework's latest.
setup upgrade Pull the framework checkout to latest origin/main.
setup verify Verify the framework is integrated correctly into an adopter tracker.
setup-status Render a Markdown adoption dashboard (install pin, drift, wired agent targets, installed skill families, symlink health) and adjust the wiring in place.
setup-shared-config-sync Commit + push the user's shared Claude config to its sync repo.
setup-override-upstream Promote a local .apache-magpie-overrides/<skill>.md file into a PR against apache/magpie; prompts to remove the override once merged and upgraded.
setup-upstream-fix Turn a framework bug or quirk hit mid-session into a fix PR against apache/magpie, after checking for an existing issue or PR that already covers it.

Deep documentation

  • 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.
  • unadopt.md — counterpart to install-recipes.md: remove the framework artefacts the adopt 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.
  • personal-use-unadopted-repo.md — recipe for using Magpie against a repo that has not adopted the framework: whole-user skill install, one .gitignore line, .apache-magpie-local/ personal config, then run skills as if adopted. No changes to the target repo's committed files (beyond the optional .gitignore line) and no opt-in from teammates required.
  • 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