diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2cc1c061..152242a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,96 +36,36 @@ # Contributing -Thanks for helping improve this repository. It is the **generic, -project-agnostic framework** for agent-assisted repository -maintainership across ASF projects (and equally for any non-ASF -open-source community that wants in). The framework is named -**Apache Magpie** — see [`MISSION.md`](MISSION.md) for the -project's motivation, scope, and design commitments. - -Before sending a patch, please skim this file end-to-end: it lays -out the layering the repository depends on, the cross-cutting -concerns every change must respect, and the dev loop CI enforces. -A patch that ignores any of these is hard to land no matter how -correct it is in isolation. +Apache Magpie contains reusable skills, tool adapters, and documentation for agent-assisted project maintenance. +Project-specific configuration belongs in the adopting project's repository, not in the framework. + +For a first patch, start with [Getting set up](#getting-set-up) and [Making changes](#making-changes). +The sections below describe the repository layout, requirements for skill and tool changes, and the checks CI runs. +See [`MISSION.md`](MISSION.md) for the project's scope and design commitments. ## English as code -The most important thing to understand about this repository, -before you make any change, is that **English is the primary -programming language here**. Not as metaphor — as engineering. - -Sixty-some years ago, COBOL was designed around an ambitious idea: -let programmers write business logic in something close to plain -English (`MULTIPLY HOURS-WORKED BY HOURLY-RATE GIVING GROSS-PAY`), -on the theory that the compiler should meet humans halfway. The -idea was sound; the implementation wasn't. Compilers of the 1960s -could parse the syntax but not the meaning, so COBOL ended up -verbose, brittle, and still requiring programmer discipline to -write code the compiler could actually run. The full-English -vision was abandoned, and for the next half-century, programming -languages drifted in the *opposite* direction — more terse, more -rigorous, more demanding of the human, on the assumption that the -human would always be the one meeting the machine halfway. - -**We have come full circle.** Today's interpreters can read -English. A modern coding agent — Claude Code, Codex, Gemini CLI, -any of the runtimes listed in -[Agent harnesses](#agent-harnesses) — reads a plain-English -description of a workflow (*"sweep the inbox since last week, -classify each message against the six triage classes, draft a -confirmation reply for each one that needs one"*) and executes -it. The compiler is now sophisticated enough that the -English-as-code vision actually works. COBOL was right about -where things should go; it was sixty years early on the question -of what would interpret it. - -This repository is built on that observation. The skill files -under `skills//SKILL.md` are **programs**. They are -written in English. They are executed by an agent. They have -inputs, outputs, control flow, error handling, edge cases, and -unit tests (the eval suite under [`tools/skill-evals/`](tools/skill-evals/)). -A `SKILL.md` is no less code than a `.py` file — it is code at a -**higher abstraction level**, interpreted by a more capable -interpreter. - -Traditional programming languages (Python and Groovy in this -repo) still have their place. They handle the deterministic -pieces where bit-exact output matters more than judgement — CVE -JSON emission, OAuth dance, archive parsing, dashboard rendering. -Those live under [`tools/`](tools/) as ordinary code with -ordinary tests. But they are the *minority* of the surface area. -The bulk of what this project does — assess a security report, -classify a PR, mentor a contributor, allocate a CVE — is encoded -in English-language skill files. That is the project's bet, and -it is the bet you need to internalise before contributing. - -Four practical consequences: - -- **A change to a skill file is a code change.** Treat it like - one. Run the eval suite. Think about boundary conditions. Add - the equivalent of a regression test (an eval fixture) for the - bug you fixed. The fact that the file ends in `.md` does not - make it a doc — it makes it a program with a markdown syntax. -- **A change to a tool's `tool.md` is a code change.** Tool - contracts in markdown are read by the skills at runtime; - rewording the contract is rewording the API. -- **English code uses semantic line breaks ([SemBr](https://sembr.org)).** - Most programming language styles format one statement per line. - Because Magpie skills and documents are programs written in English, they follow the same convention: lines break at natural linguistic boundaries (one sentence per line, or at clause boundaries where appropriate). - This makes single-sentence edits produce single-line git diffs without rewrapping entire paragraphs. -- **You author both layers agentically** — see - [Authoring with an agent](#authoring-with-an-agent) below. The - loop is the same whether the artefact is an English skill file - or a Python bridge, because the meta-level operation (state - intent, iterate, probe edges, test) is the same. Only the - feedback signal differs — eval suite for the English layer, - `pytest` / `mypy` / `ruff` for the traditional-language layer. - -Read the rest of this guide with that frame in mind. When -something looks like "just documentation", check whether it -sits under `skills/` or `tools//tool.md`. If it -does, it's code — and the rules for changing code apply. +Agents read `skills//SKILL.md` and tool contracts such as `tools//tool.md` at runtime. +Changing these files can change which inputs an agent accepts, how it classifies a report, or when it asks for confirmation. +Treat behavioural edits as code changes, even though the files are Markdown. + +For example, changing a triage instruction from "propose a label" to "apply a label" changes a write boundary. +It needs the same review as a code change that replaces a preview with an API write. +A link correction in a reader-facing guide does not change that boundary. + +| Change | Required follow-through | +|---|---| +| Skill behaviour | Run the affected [eval suite](tools/skill-evals/README.md); add a regression fixture for a bug fix. | +| Tool contract loaded by skills | Check the callers and run their affected eval suites. | +| Python or Groovy implementation | Run the relevant package's tests and configured static checks. | +| Reader-facing prose with no behavioural effect | Check accuracy, links, and formatting. | + +Python and Groovy tools implement deterministic operations such as CVE JSON generation, OAuth authentication, archive parsing, and dashboard rendering. +Skills describe workflows that require interpretation, such as assessing a report or drafting a response. + +Use [semantic line breaks](https://sembr.org) in both skills and documentation: one sentence per line, or a break at a clause boundary when useful. +This keeps a sentence edit from rewrapping the surrounding paragraph. +See [Authoring with an agent](#authoring-with-an-agent) for the development workflow for both layers. ## What this framework is diff --git a/README.md b/README.md index 0a27a1bf..cc4ae2c7 100644 --- a/README.md +++ b/README.md @@ -24,106 +24,82 @@ [![Magpie](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/apache/magpie/main/assets/badge.json)](https://magpie.apache.org/) -**Adopt a Magpie.** Magpie is a curated set of skills for the AI agent you -already use — Claude Code, Codex, Gemini CLI, Copilot and others — that take -on the repetitive parts of running an open-source project: triaging issues and -pull requests, reviewing code, mentoring contributors, drafting fixes, and -handling security reports end to end. - -**Three things make it different from a folder of prompts:** - -- **Nothing is sent in your name.** Every comment, email, label and PR is - *drafted* by the agent and posted by a person. There is no autonomous mode. -- **The agent is confined before it reads anything real.** A filesystem and - network sandbox, a credential-stripped environment, and a deterministic - guard that inspects each shell command *before* it runs and denies the ones - that break a hard rule — not a prompt asking it nicely. -- **It is an Apache project, not a product.** Apache-2.0, vendor-neutral - across agents, no account and no service in the middle. Telemetry is opt-in - per project and off by default — install it and never run a skill, and it - generates no outbound traffic at all. - -Magpie is currently in development for ASF projects + Python Core team -friendlies. Testers welcome! +Apache Magpie provides skills for AI agents that assist with open-source project maintenance. +The skills cover issue and pull-request triage, code review, contributor mentoring, fix drafting, and security-report handling. +They work with Claude Code, Codex, Gemini CLI, Copilot, and other agents; support varies by [adapter](docs/adapters/README.md). + +Skills propose actions for human review. +Posting comments, changing labels, and other shared-state changes require explicit confirmation. +Autonomous operation is disabled. + +The [secure setup](docs/setup/secure-agent-setup.md) provides filesystem and network isolation, a credential-stripped environment, and command guards where the agent supports them. +These protections require setup; installing a skill family alone does not enable them. + +Magpie is licensed under Apache-2.0 and requires no Magpie account or hosted service. +Project telemetry is opt-in and disabled by default. +The framework is under development, with current testing focused on ASF projects and Python Core contributors. ## See it in action -One security report, start to finish — installed from the marketplace, the -agent sandboxed and guarded, then the report imported, triaged against the -project's history, fixed, and published as a CVE: +This example follows a security report from installation and secure setup through intake, triage, fix drafting, and CVE publication. ![Installing Magpie from the marketplace, running the secure-agent and privacy setup, then importing two security reports, triaging one as a high-severity path traversal and the other as not a vulnerability, drafting the fix as a scrubbed public PR, and publishing the CVE](assets/quickstart/demo.svg) -*Illustrative — a written transcript, rendered deterministically, not a -recording.* The [**interactive version**](https://magpie.apache.org/#see-it-in-action) -on the project site steps through the same story with the full output of each -command. - -> [!IMPORTANT] -> The motivation, scope, and design commitments behind this work -> live in [`MISSION.md`](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 install. +*Illustrative transcript, not a recording.* +The [interactive version](https://magpie.apache.org/#see-it-in-action) lets you step through each command and its output. +For the project's scope and design commitments, see [`MISSION.md`](MISSION.md). ## Install -**Start here → [Quick start](docs/quick-start.md)** — a handful of commands, -in the agent you already use. Nothing is written to your repository. +Follow the [quick start](docs/quick-start.md) for your agent. +For example, in Claude Code: ```text /plugin marketplace add apache/magpie # Claude Code -/plugin install magpie-setup@apache-magpie # install this one first -/plugin install magpie-agent-guard@apache-magpie # the baseline: -/plugin install magpie-utilities@apache-magpie # take all three -/plugin install magpie-pr-management@apache-magpie # + the families you need +/plugin install magpie-setup@apache-magpie # install first +/plugin install magpie-agent-guard@apache-magpie # command guard +/plugin install magpie-utilities@apache-magpie # skill index and authoring tools +/plugin install magpie-pr-management@apache-magpie # PR triage and review ``` -Those first three are the **baseline** — and the same set a project commits as -its floor when it adopts Magpie, so taking them is taking what a project would -recommend to every contributor. After that, install **one plugin per family you -actually want**: every installed skill costs context on every turn, used or -not (~0.2–2.0k tokens a family), so there is deliberately no -install-everything plugin. +The first three plugins are the recommended baseline. +Add a plugin for each family you need. +Installed skill descriptions consume context even when unused, approximately 0.2–2.0k tokens per family; there is no combined install-everything plugin. + +After installing `magpie-setup`, you can also request families in plain language: -Once `magpie-setup` is in, you never type these again — ask in plain language -(*"install the Magpie families for PR review"*) and the setup skill runs the -installs for you. +> Install the Magpie families for PR review. -Codex, VS Code / Copilot, and Gemini are one-liners too — the -[quick start](docs/quick-start.md) has all four, plus what to run next to put -the agent in its sandbox. Nothing is committed to your repository. +Plugin installation is per-user and does not modify your repository. +Project configuration, isolation, and privacy setup are separate steps covered in the quick start. -**Fallback — the pinned snapshot install.** Use it when a marketplace is not -an option or not enough: your agent has no plugin mechanism, you need the -signed ASF source release rather than a git clone, or the project wants every -contributor and CI job pinned to one committed version with drift detection. +**Pinned-snapshot alternative.** Use a snapshot if your agent has no plugin mechanism, you need a signed ASF source release, or contributors and CI jobs must use a committed version pin with drift detection. 1. [Download / pin a release](https://magpie.apache.org/downloads/) 2. Set up the symlinks and git-ignores — see - [`docs/setup/install-recipes.md`](docs/quick-start/other-install-methods.md) + [other installation methods](docs/quick-start/other-install-methods.md) 3. Ask your agent to complete the install: `/magpie-setup install` -The two are complementary, not exclusive. +You can use personal marketplace plugins alongside a project's pinned snapshot. ## Usage -Magpie is used by interacting with your AI agents. You'll use plain-language -prompts like +Ask your agent for a task, including the repository and scope when needed: -> review PR #5193 +> Summarize the open PR backlog for this repository. Do not post comments or change labels. -or +For a named skill, use the command supplied by your install method. +For example, a marketplace install provides: -> triage the latest security reports - -or skill calls starting with a slash, like +```text +/magpie-repo-health:dependency-audit +``` -> /magpie-repo-health:dependency-audit +This audit reports dependency vulnerabilities and proposed upgrades without changing manifests or lock files. +Review the report before deciding which upgrades to make. +If project configuration is missing, the skill starts the setup flow before running the audit. -(the family-plugin form, assuming the recommended marketplace install above — -see [Skill names differ by install method](docs/setup/marketplace.md#skill-names-differ-by-install-method) -if you're on the pinned-snapshot fallback instead). +See [skill names by install method](docs/setup/marketplace.md#skill-names-differ-by-install-method) for pinned-snapshot commands. ## Update / maintain @@ -148,21 +124,12 @@ if you're on the pinned-snapshot fallback instead). ## Skill families -The following skill families ship in the framework, all at `experimental` or -`stable`, and each skill declares its family in a `family:` frontmatter -key. On the recommended marketplace install, you choose families by which -per-family plugin(s) you install (see [Install](#install) above) — install -or uninstall a plugin at any time to add or drop a family. On the -pinned-snapshot fallback, `/magpie-setup` offers the **opt-in** families — -and the optional **MCP servers** (`ponymail`, `apache-projects`, -`gmail-plaintext`) — in a single install choice, and symlinks for the picked -families land in the skill directory. Either way, 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`](docs/modes.md) for what each mode -means and which modes are still proposed vs. shipping today. +Marketplace installs select families by plugin; pinned-snapshot installs select them through `/magpie-setup`. +The `setup` and `utilities` families are included in the baseline. +The snapshot setup also offers optional MCP servers: `ponymail`, `apache-projects`, and `gmail-plaintext`. + +The **Modes** column uses the [agent-assistance taxonomy](docs/modes.md). +Family guides document each skill's maturity and requirements. | Family | Type | Modes | Purpose | Detail | |---|---|---|---|---| diff --git a/docs/index.md b/docs/index.md index 9de3f59f..151a5ff8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,36 +7,42 @@ - [What is Apache Magpie?](#what-is-apache-magpie) - [How it works](#how-it-works) - - [Need help with one of these? Adopt a family of skills](#need-help-with-one-of-these-adopt-a-family-of-skills) + - [Skill families](#skill-families) - [Who is this for?](#who-is-this-for) - [Anyone who wants agent help on a repo](#anyone-who-wants-agent-help-on-a-repo) - [Maintainers adopting Magpie for their project](#maintainers-adopting-magpie-for-their-project) - [Security team members](#security-team-members) - [Contributors to the Magpie framework itself](#contributors-to-the-magpie-framework-itself) - [People evaluating whether to adopt](#people-evaluating-whether-to-adopt) - - [People who are concerned for security and privacy when using their agents](#people-who-are-concerned-for-security-and-privacy-when-using-their-agents) - - [Key concepts in 60 seconds](#key-concepts-in-60-seconds) + - [Security and privacy setup](#security-and-privacy-setup) + - [Key concepts](#key-concepts) - [Where to go next](#where-to-go-next) # What is Apache Magpie? -Apache Magpie is an AI assistant for open-source project maintainers. It handles the repetitive parts of running a project — triaging issues, reviewing PRs, onboarding contributors, managing security reports, cutting releases — so maintainers can spend their time on design, relationships, and the work that actually requires a human. +Apache Magpie is a set of skills for AI agents, used to triage issues, review pull requests, mentor contributors, handle security reports, and prepare releases. +Each skill defines a workflow and the points where a person must review or approve its output. +Shared-state changes, such as posting a comment or applying a label, require explicit confirmation. -**The agent proposes. The human decides.** Magpie never merges, never pushes, never sends mail, never flips a label without a maintainer confirming first. +Start with the [quick start](quick-start.md) to install Magpie and configure it for a repository. +The [prerequisites](quick-start/prerequisites.md) list access requirements, including GitHub authentication and mail backends for skills that use them. -**Before you start**, check what the skills need to run — an agent, a mail -backend, tracker access: [prerequisites](quick-start/prerequisites.md). The -[quick start](quick-start.md) is two commands once those are in place. +## How it works ---- +You install a skill family, configure the repository it will work against, and ask your agent to run a task. +The skill reads the relevant data and produces a report, draft, or proposed change. +You can correct the proposal, approve permitted actions, or stop without applying them. -## How it works +For example, ask: -Magpie provides **skills** — step-by-step workflows an AI agent follows. You pick which skills your project uses. The agent reads your issues, PRs, or security reports, does the analysis, and drafts a response. You review it and hit "go" (or don't). +> Summarize this repository's open PR backlog. Do not post comments or change labels. -Five **modes** describe what the agent can do, from low-risk to high: +Use the summary to decide which PRs need review. +Request a review of a specific PR as a separate task. + +Five [modes](modes.md) describe the kinds of assistance: | Mode | What it does | Status | |---|---|---| @@ -44,90 +50,81 @@ Five **modes** describe what the agent can do, from low-risk to high: | **Agentic Mentoring** | Help contributors with conventions, point to examples | Experimental | | **Agentic Drafting** | Write a code fix or a PR for you to review | Stable (security) | | **Agentic Pairing** | Self-review your own code before submitting | Experimental | -| **Agentic Autonomous** | Merge trivial changes without human review | Off (deliberately) | +| **Agentic Autonomous** | Merge trivial changes without human review | Disabled | -Each project picks the modes that fit. You can run just Agentic Triage and nothing else. +Projects opt into the modes they need; using triage does not require enabling drafting or pairing. ---- + -## Need help with one of these? Adopt a family of skills +## Skill families -Magpie's skills ship in **families**. You don't adopt all of them — you pick the ones that match a problem you actually have today. Each family page explains what it does, which skills it includes, and how to turn it on. +Install families by task. +Each family guide lists its skills, configuration requirements, and first-run examples. -Most families work on **any** project, inside or outside the Apache Software -Foundation. The ones marked **🪶 ASF-specific** encode Foundation processes — -the release lifecycle and the contributor-to-committer path — and assume an ASF -adopter profile by default; a non-ASF project can still adopt them through the -adapter/config layer, but they carry ASF assumptions the generic families do not. +Most families are organization-independent. +Families marked **ASF-specific** use Foundation processes by default; other organizations need configuration or adapters for their own release and governance processes. -| If you're dealing with… | Adopt the family | Scope | +| Task | Family | Scope | |---|---|---| -| Setting up agents safely — sandbox, clean environment, privacy routing | [setup](setup/README.md) | Any project | -| Security reports that need careful, audited handling | [security](security/README.md) | Any project | -| A pull-request queue that's out of control | [pr-management](pr-management/README.md) | Any project | -| Catching implementation-detail nits before you open a PR | [pairing](pairing/README.md) | Any project | -| An issue backlog full of duplicates and stale reports | [issue-management](issue-management/README.md) | Any project | -| Repo hygiene slipping — CI runners, dependencies, licenses, flaky tests | [repo-health](repo-health/README.md) | Any project | -| Releases that are a manual, error-prone slog | [release-management](release-management/README.md) | 🪶 ASF-specific | -| New contributors getting stuck and drifting away | [mentoring](mentoring/README.md) | Any project | -| Growing contributors into committers | [contributor-growth](contributor-growth/README.md) | 🪶 ASF-specific | -| Building or maintaining your own skills | [utilities](utilities/README.md) | Any project | - -Start with [`setup`](setup/README.md) regardless — it is the prerequisite every adopter installs first — then add the families above as you need them. - ---- +| Installation, sandboxing, and privacy configuration | [setup](setup/README.md) | Any project | +| Security-report intake, triage, and disclosure | [security](security/README.md) | Any project | +| PR triage, code review, and queue reports | [pr-management](pr-management/README.md) | Any project | +| Local diff review before submitting a PR | [pairing](pairing/README.md) | Any project | +| Issue triage, reproduction, and backlog maintenance | [issue-management](issue-management/README.md) | Any project | +| CI, dependency, licence, and flaky-test audits | [repo-health](repo-health/README.md) | Any project | +| Release candidates, votes, and announcements | [release-management](release-management/README.md) | ASF-specific | +| Newcomer guidance and good-first-issue preparation | [mentoring](mentoring/README.md) | Any project | +| Contributor activity, nominations, and onboarding | [contributor-growth](contributor-growth/README.md) | ASF-specific | +| Skill discovery, authoring, and maintenance | [utilities](utilities/README.md) | Any project | + +Install [`setup`](setup/README.md) first. +The [baseline plugins](quick-start/families.md#start-with-the-baseline) also include `magpie-agent-guard` and `magpie-utilities`. ## Who is this for? ### Anyone who wants agent help on a repo -You work on a project with an issue tracker and/or PR queue, and you want agent assistance with the mechanical parts. You do not need the project's permission, and nothing gets committed. - -→ Start with the [quick start](quick-start.md) — install into your agent in two commands — then [individual use](setup/individual-use.md). If a marketplace is not an option, [other installation methods](quick-start/other-install-methods.md) cover the pinned snapshot install. +Install Magpie for your own use without committing shared configuration. +See the [quick start](quick-start.md) and [individual use](setup/individual-use.md). +If your agent has no marketplace, use one of the [other installation methods](quick-start/other-install-methods.md). ### Maintainers adopting Magpie for their project -You want contributors to arrive with a sensible set of families already enabled, and the repo's own conventions encoded where the skills will read them. - -→ [Team adoption](setup/team-adoption.md) — what a repo commits, how to decide it, and how to keep it current. Adoption is a recommendation to your contributors, not a requirement on them. +Commit a recommended plugin set and shared project configuration. +[Team adoption](setup/team-adoption.md) describes the files involved and how contributors receive updates. +Adoption does not require contributors to use Magpie. ### Security team members -You handle CVE reports and want agent help with the 16-step lifecycle — import, triage, fix, allocate, publish. - -→ Start with [security workflow overview](security/README.md), then [how the security team works](security/how-the-security-team-works.md). +Use the [security workflow overview](security/README.md) for the report-to-publication lifecycle. +[How the security team works](security/how-the-security-team-works.md) covers team responsibilities and onboarding. +Configure privacy controls before loading private reports. ### Contributors to the Magpie framework itself -You want to improve the skills, add tools, or fix bugs in the framework. - -→ Start with [CONTRIBUTING.md](../CONTRIBUTING.md) and the [spec-driven development](spec-driven-development.md) loop. +Start with [CONTRIBUTING.md](../CONTRIBUTING.md) for repository layout, local setup, and requirements for patches. +The [spec-driven development](spec-driven-development.md) guide describes the specification workflow. ### People evaluating whether to adopt -You want to understand the trust model, cost, and governance commitments before deciding. - -→ Read [MISSION.md](../MISSION.md) (the why), [PRINCIPLES.md](../PRINCIPLES.md) (the rules), and [mode economics](mode-economics.md) (what it costs in tokens). - -### People who are concerned for security and privacy when using their agents +Read [MISSION.md](../MISSION.md) for scope, [PRINCIPLES.md](../PRINCIPLES.md) for design requirements, and [mode economics](mode-economics.md) for token-cost estimates. -You would like to use agentic AI but you are concerned about security and privacy - when LLMs / Agent -might get access to your credentials and poison your workstation, or have access to private information -from mailing lists, slack etc. +### Security and privacy setup -→ When you setup Magpie, it will setup your workstation with security guardrail layers that will run your agents in containerized sandbox, and it will setup privacy gateways for the tools your agentic setup will use. Read more details in [Secure agent setup RFC](../docs/rfcs/RFC-AI-0002.md) and [Privacy-aware LLM routing for foundation private information](../docs/rfcs/RFC-AI-0003.md). +Use [secure agent setup](setup/secure-agent-setup.md) to configure filesystem access, network access, and command guards. +Use [privacy setup](setup/privacy-llm.md) to configure which models may receive private content and how third-party personal information is redacted. +Available isolation and guard mechanisms vary by [adapter](adapters/README.md). ---- +## Key concepts -## Key concepts in 60 seconds - -- **Skill** — A markdown file describing one workflow (e.g., "triage a PR"). The agent reads it and follows the steps. -- **Mode** — A risk level (Agentic Triage → Agentic Mentoring → Agentic Drafting → Agentic Pairing → Agentic Autonomous). Projects opt in per-mode. -- **Adopter config** — Your project-specific settings (mailing lists, label schemes, canned responses) in a `/` directory. -- **Sandbox** — The agent runs in a locked-down environment. It can't read your credentials, can't access the network freely, and can't push code. -- **Human-in-the-loop** — Every action visible to others requires explicit maintainer confirmation. No exceptions until Agentic Autonomous (which is off). - ---- +| Term | Meaning | Example | +|---|---|---| +| Skill | A Markdown workflow the agent follows. | Triage an open issue and propose a disposition. | +| Family | A group of related skills installed together. | `pr-management` includes triage, review, and queue statistics. | +| Mode | A category of assistance that a project opts into. | Drafting produces a proposed fix for review. | +| Project configuration | Repository-specific settings resolved through ``. | The upstream repository, label scheme, and canned responses. | +| Sandbox | Restrictions on an agent process's filesystem and network access. | Preventing reads of home-directory credential files. | +| Human-in-the-loop | Explicit approval before a proposed shared-state change. | Reviewing a drafted comment before it is posted. | ## Where to go next diff --git a/docs/quick-start.md b/docs/quick-start.md index 9cc2e624..0af6801d 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -24,191 +24,91 @@ ![The baseline three plugins and one family installed, then a triage run: 38 open PRs, 12 untriaged, with a proposed action for each and a confirmation prompt](../assets/quickstart/install.svg) -*Illustrative. The whole of it: install, run a skill, get an answer you confirm.* +*Illustrative transcript: installation followed by a triage proposal.* -Install Apache Magpie into the agent you already use, in a couple of -commands: one to add the **Apache Magpie Marketplace**, one per family you -want. Nothing is -committed to your repository, and nothing is changed in it. - -**This install is yours, on this machine.** It needs no decision from your -project and no opt-in from your teammates. Committing anything for other -people is a separate act called **adoption** — -[Installation or Adoption?](quick-start/two-ways.md) draws the line. - -**What you get.** 75 skills your agent can run, grouped into 10 **families** — -PR triage and review, issue triage, security-report handling, release -management, contributor mentoring. Install only the families you need; each one -you add costs context in every session — -[what each family solves](quick-start/families.md) lists all ten, after the -install steps. - ---- +This guide covers plugin installation, project configuration, agent isolation, and privacy setup. +You need a supported agent and access to the systems your chosen skills use; see [prerequisites](quick-start/prerequisites.md). +Install only the [families](quick-start/families.md) you need, such as PR management or repository-health audits. ## Installation or Adoption? -**Installing** puts the marketplace and the plugins into your agent and writes -nothing to any repository. That is what the steps below do, and it is all most -people ever need. **Adoption** is the separate, later act of a repo's -maintainers committing a floor that everyone who clones it picks up. - -The two differ in one thing only — whether anything is committed for other -people — and you do not have to choose before installing. -[**Installation or Adoption?**](quick-start/two-ways.md) compares them side by side. +**Installation** adds plugins to your agent on this machine. +**Configuration** supplies the repository-specific values those skills need, using gitignored files for individual use. +**Adoption** commits shared configuration and a recommended plugin set for the project. ---- +For example, you can install PR-management skills and configure them locally to review a repository without changing your teammates' setup. +Only use adoption if the maintainers want to share that configuration. +See the [comparison](quick-start/two-ways.md) for file locations and ownership. ## The walkthrough -Six steps, in order. One and two are the install. Three and four are the -safety layers, and **both are strongly recommended** — Magpie's skills read -issues, pre-disclosure security reports and private mailing lists, so neither -is a nice-to-have. Five and six are what you do with it. +Follow steps 1–5 for individual use. +Step 6 is optional team adoption. +Set up isolation and privacy controls before running skills against external reports or private data. ### Step 1 — install from the Apache Magpie Marketplace -Installing is a **one-time, per-machine** step for whichever agent you use. It -writes nothing to any repository and your teammates are unaffected. +Add the marketplace and install plugins at user scope. +This step does not write to the repository. ![Adding the apache-magpie marketplace, then installing the baseline — magpie-setup, magpie-agent-guard, magpie-utilities — and one family, with nothing written to the repository](../assets/quickstart/step-install.svg) -→ [**Prerequisite: install Magpie from your agent's -marketplace**](setup/marketplace-install.md) has the commands, one section per -agent: Claude Code, OpenAI Codex CLI, VS Code / GitHub Copilot, Google Gemini -CLI, Cursor, `microsoft/apm`, and JetBrains IDEs. - -**Take the baseline — three plugins, strongly recommended on every machine:** - -- **`magpie-setup`** — install this one first; nothing else installs, upgrades, - configures or adopts without it, and it carries the secure-isolation skills - from [Step 3](#step-3--isolate--guard). -- **`magpie-agent-guard`** — the deterministic pre-execution guard, a hook that - inspects each shell command before it runs and denies the dangerous shapes. -- **`magpie-utilities`** — `list-skills` and the small tools you reach for when - you want to know what is actually installed. - -Those three are exactly the **floor** a project commits when it adopts Magpie, -so taking them is taking what a project would recommend to every contributor. - -Then add **one plugin per family you actually want**, against a problem you -have today; you can install more at any time. Pick them from -[What each family solves](quick-start/families.md) — the ten families, with the -problem each one solves. - -Each family's README opens with an **Install & first runs** section — the one -command for that family and a few things to try once it is in: -[setup](setup/README.md#install--first-runs) · -[security](security/README.md#install--first-runs) · -[release-management](release-management/README.md#install--first-runs) · -[pr-management](pr-management/README.md#install--first-runs) · -[issue](issue-management/README.md#install--first-runs) · -[repo-health](repo-health/README.md#install--first-runs) · -[contributor-growth](contributor-growth/README.md#install--first-runs) · -[utilities](utilities/README.md#install--first-runs) · -[mentoring](mentoring/README.md#install--first-runs) · -[pairing](pairing/README.md#install--first-runs) - -**Check what landed** with `/plugin` → *Installed*, filtered to `magpie`: +The [marketplace installation reference](setup/marketplace-install.md) has commands for Claude Code, Codex CLI, VS Code / GitHub Copilot, Gemini CLI, Cursor, `microsoft/apm`, and JetBrains IDEs. -![The Claude Code /plugin Installed tab filtered to magpie: eleven plugins from the apache-magpie marketplace, each marked enabled, with its skill count and how many times its skills have been used](../assets/installed-plugins.png) +Install the three recommended baseline plugins, then add the families you need: -Every row names the marketplace it came from, whether it is enabled, and how -many of its skills you have actually used — which is the honest way to decide -whether a family is earning its always-on context. +| Plugin | Purpose | +|---|---| +| `magpie-setup` | Install first. Provides installation, configuration, upgrades, adoption, and isolation setup. | +| `magpie-agent-guard` | Inspects shell commands before execution and blocks prohibited command patterns on supported agents. | +| `magpie-utilities` | Lists installed skills and provides skill-authoring and framework-maintenance tools. | -> [!IMPORTANT] -> **There is no install-everything plugin, by design.** Every installed skill -> advertises itself to the model on every turn, used or not — all ten families -> at once would be ~8.6k always-on tokens against 0.2–2.0k for a family you -> picked on purpose. See -> [Choosing a plugin](setup/marketplace.md#choosing-a-plugin-which-families). +For PR triage and review, add `magpie-pr-management`. +The [family reference](quick-start/families.md) lists the other choices and links to their first-run examples. -> [!NOTE] -> **Per-family works on every agent listed.** A family plugin carries its -> skills as real directories, so nothing depends on a client following a -> symlink — measured on Codex and Gemini, not assumed. +In Claude Code, open `/plugin`, select *Installed*, and filter to `magpie`: -> [!TIP] -> **Installed a family and want to use it now?** -> [Your first run with a family](quick-start/first-run.md) walks the whole -> thing in terminal steps — the pre-flight stopping, the setup wizard, the -> configuration it scaffolds, and the same command working on the retry. +![The Claude Code /plugin Installed tab filtered to magpie: eleven plugins from the apache-magpie marketplace, each marked enabled, with its skill count and how many times its skills have been used](../assets/installed-plugins.png) ---- +Check that the selected plugins are enabled and come from `apache-magpie`. +Installed skill descriptions consume model context even when unused: approximately 0.2–2.0k tokens per family, or 8.6k for all ten. +See [choosing a plugin](setup/marketplace.md#choosing-a-plugin-which-families) for details. ### Step 2 — run `/magpie-setup` -The marketplace install above is complete on its own: the skills are in your -agent and you can start using them. `/magpie-setup` is what you run next when -you want Magpie wired into a **project** rather than only into your own agent — -a committed floor, project config, or overrides. Committing those for everyone -who clones the repo is **adoption** — -[`setup/team-adoption.md`](setup/team-adoption.md). - -One command. It works out which method fits this checkout, prints the plan it -intends to carry out, and waits: +From the target repository, run setup to inspect the checkout and select the appropriate configuration path: ```text /magpie-setup ``` -**Or just ask for it.** Magpie's skills are model-invoked, so the slash form is -a shortcut, never the only way in — every step on this page has a plain-language -equivalent that works on every harness, including the ones with no slash -commands at all: +You can also ask in plain language: > set Magpie up for this project -Both reach the same skill. Use whichever you prefer; this page shows the slash -form first because it is unambiguous, and the sentence beside it because that -is what most people actually type. +Use plain language if your agent does not support slash commands. ![A `/magpie-setup` run in Claude Code: the picker with the baseline three already ticked, the plugins installed for the user, then the secure-agent setup proposing its changes and waiting for approval before writing anything](../assets/quickstart/magpie-setup.svg) -Nothing is written before you approve it. Afterwards, `/magpie-setup verify` -(*check that Magpie is set up correctly here*) re-runs the health check and -drift detection, and `/magpie-setup:status` (*what Magpie do I have -installed?*) prints what is currently installed. - -Not sure you need this step? [Installation or Adoption?](quick-start/two-ways.md) -draws the line. - -**Every skill configures itself on first use.** You do not have to remember -which projects are set up, or run anything to prepare a family before you use -it: 65 of the 75 skills open with a silent pre-flight — the ten exceptions are -the setup skills themselves, which are what you run to fix whatever it finds. - -The first time you call a skill in a project, that pre-flight works out how -Magpie is installed here and whether this project is adopted. If anything is -unresolved it **stops and proposes `/magpie-setup`** rather than guessing: - -- a pinned-snapshot project whose snapshot was never fetched on this machine, - or that is on a different framework version than the project pins; -- a marketplace install in a project with no `/` directory, - where every `` in the skill is unresolved. - -The alternative to stopping is a skill that runs against the wrong tracker, so -it stops. Once the project is set up the check costs three file checks and -prints nothing, on every invocation thereafter. +Review the proposed setup before approving changes. +For individual use, `/magpie-setup config` writes gitignored configuration to `.apache-magpie-local/`; adoption is a separate command. +After setup, `/magpie-setup verify` checks installation health and drift, and `/magpie-setup:status` lists the installed components. -Each family's README opens with a recording of exactly this — its own first -run, pre-flight and all. [What each family solves](quick-start/families.md) -links to all ten. +Skills also check configuration on first use. +If required project files are missing, they invoke the local configuration flow before continuing. +If a pinned snapshot is missing or differs from the project's pin, they stop for setup or upgrade. +They do not guess the target repository or tracker. ---- +See [your first run with a family](quick-start/first-run.md) for a worked PR-triage example, including the files created and the retry. ### Step 3 — isolate & guard -**Strongly recommended, and part of the default setup rather than a later -hardening pass.** Magpie's skills read issues, pre-disclosure security reports -and private mailing lists, so this belongs in place before you point a skill at -anything real. +Configure isolation before reading external issues or private reports. +The **sandbox** restricts filesystem and network access. +The **action guard** inspects commands and rejects prohibited actions where the agent supports it. -One run installs two different protections: a **sandbox**, which confines what -a command can reach, and the **action guard**, which decides whether a command -runs at all. A sandbox will not stop a legal `gh pr comment` from pinging four -maintainers who did not ask; a guard will not stop a command from reading -`~/.ssh`. +For example, a filesystem restriction can prevent a command from reading `~/.ssh`. +It does not decide whether posting a review comment is appropriate; command guards and human approval address that separately. | Harness | What to run | |---|---| @@ -225,12 +125,10 @@ maintainers who did not ask; a guard will not stop a command from reading ![The secure-agent setup: three proposed changes, a confirmation, then the sandbox, the clean environment and the status line in place](../assets/quickstart/step-isolation.svg) -It surfaces every sudo, shell-rc and settings-file change for approval before -applying it. When it finishes you have a filesystem and network sandbox, a -clean environment with your credentials stripped, the status line below, and -the guard wired in front of every shell command. +The installer asks for approval before privileged operations or changes to shell startup and settings files. +On the Claude Code setup shown here, it configures the sandbox, credential-stripped environment, action guard, and status line. -**The footer tells you which posture you are in, on every render:** +The status line reports the current sandbox state: ![A session where /sandbox reports "Sandbox enabled with auto-allow for bash commands": the terminal footer opens with a yellow `[sandbox-auto]` tag, followed by the project, the branch and the model](../assets/session-sandboxed.png) @@ -242,30 +140,16 @@ the guard wired in front of every shell command. ![A session after /sandbox reports "Sandbox disabled": the footer opens with a bold-red `[NO SANDBOX]` tag ahead of the project, branch and model](../assets/session-no-sandbox.png) -After the tag comes the project, branch, model, and the branch's PR once it has -one — so several sessions across worktrees stay apart. +The footer also identifies the project, branch, model, and PR when available. +Run `/magpie-setup:isolated-setup-verify`, or ask *check my agent isolation*, to check each component. -Confirm the install with `/magpie-setup:isolated-setup-verify` — *check my -agent isolation* — which reports ✓/✗/⚠ for every piece. - -→ **Why each layer exists, and what it does not stop:** -[`setup/secure-agent-internals.md`](setup/secure-agent-internals.md) · -**full install walkthrough:** [`setup/secure-agent-setup.md`](setup/secure-agent-setup.md) · -**what the guard denies and why it is a hook rather than a rule:** -[`tools/agent-guard/README.md`](../tools/agent-guard/README.md) · -**harness coverage:** [adapters matrix](adapters/README.md) — Codex and Cursor -have no action guard today. - ---- +See [secure-agent internals](setup/secure-agent-internals.md) for the limits of each layer and the [action-guard reference](../tools/agent-guard/README.md) for blocked commands. +The [adapters matrix](adapters/README.md) lists agent-specific coverage; Codex and Cursor do not currently have an action guard. ### Step 4 — set up privacy -**Strongly recommended, and the one step about your project's data rather than -your machine.** Step 3 constrains what the agent can reach and what it may run. -Neither half has an opinion about the thing Magpie is actually for: reading a -PMC's private list, or a security report still under embargo, and sending it to -a model. That is a command that *should* run, doing exactly what it was asked — -and exporting somebody else's confidential text while it does. +Configure privacy controls before fetching private reports or mailing-list content. +A sandbox restricts access to data, but does not determine which model may receive data once it has been read. ```text /magpie-setup:privacy-llm @@ -275,112 +159,79 @@ and exporting somebody else's confidential text while it does. ![A privacy-llm run: the LLM stack detected, the matching variant written to the gitignored local directory, the PII redactor proven end to end, and the approved-LLM gate refusing an unregistered local model](../assets/quickstart/step-privacy.svg) -Two mechanisms, separate because they protect different people: - -- **the approved-LLM gate** protects the *project* — a skill refuses to fetch - private-list mail unless every model in the active stack is approved; -- **PII redaction** protects the *third parties a reporter names*, swapping - them for hash-prefixed identifiers before any model sees the text. - -The skill detects your stack rather than interviewing you, writes the matching -variant to the gitignored `.apache-magpie-local/`, then **proves it** by running -both. A gate that says no is the useful output: it names the unapproved model -and leaves your configuration alone until you decide. - -Re-run it after `/magpie-setup upgrade` — what counts as approved can narrow -between versions. +| Mechanism | Behaviour | +|---|---| +| Approved-LLM gate | Refuses to fetch private-list mail unless every model in the active stack is approved. | +| PII redaction | Replaces third-party personal information in reports with hash-prefixed identifiers before model processing. The reporter's own identity and tracker collaborators are exempt. | -→ **The recipes, the variants, and what each mechanism does:** -[`setup/privacy-llm.md`](setup/privacy-llm.md). The approved registry is -**provisional**, pending a ratified ASF Legal policy for AI-assisted handling -of foundation private data; that page carries the full caveat. +The skill detects the active stack, configures the appropriate variant in gitignored `.apache-magpie-local/`, and exercises both mechanisms. +If it reports an unapproved model, resolve the approval or routing issue before retrying the private-data task. +For example, access to a mailbox does not itself authorize sending its private-list messages to a newly configured model. ---- +Re-run privacy setup after `/magpie-setup upgrade`, because the approval policy may change. +See [privacy setup](setup/privacy-llm.md) for recipes and exceptions. +The approval registry is provisional pending a ratified ASF Legal policy for AI-assisted handling of Foundation private data. ### Step 5 — use it ![Listing the installed skills, then a triage pass returning 38 open PRs with a proposed action for each and nothing posted](../assets/quickstart/step-use.svg) -Ask in plain language: - -> review PR #5193 +Start with a bounded task: -> triage the latest security reports +> Summarize the open PR backlog for this repository. Do not post comments or change labels. -or call a skill by name. A marketplace install namespaces skills under the -**plugin** that provides them, as `/:`: +Or invoke a skill by name. +Marketplace commands use `/:`: ```text /magpie-pr-management:triage /magpie-security:issue-triage ``` -`/magpie-utilities:list-skills` — *what Magpie skills do I have?* — prints -everything that is installed. +For triage, expect an assessment and proposed actions, not immediate tracker changes. +You can narrow the next request: ---- +> Review the oldest PR that is waiting for a reviewer. Show me the draft review before posting it. + +Use `/magpie-utilities:list-skills`, or ask *what Magpie skills do I have?*, to list the installed skills. +See [skill names by install method](setup/marketplace.md#skill-names-differ-by-install-method) if you use a pinned snapshot. ### Step 6 — consider adopting Magpie ![An adopt run: three paths staged and not committed, what a contributor gets on clone, and what it does not restrict](../assets/quickstart/step-adopt.svg) -Everything so far was yours alone: the plugins live in your agent, and your -repository has not changed. **Adoption is the separate act of deciding this for -the project** — and it belongs to the repo's maintainers, together, not to -whoever installed first. - -Adopting commits a **floor**: an `.apache-magpie.lock` recording what the -project recommends, and a default plugin set in the repo's -`.claude/settings.json` derived from it. A contributor who clones the repo and -trusts it then arrives with those families already enabled — no install step, -no instructions to follow. It is a floor, never a ceiling: nobody is stopped -from installing more or running a newer Magpie, and a maintainer can reverse -the whole thing in a PR. - -Worth doing once the project — not one maintainer — agrees on what it wants to -recommend. It obliges nobody: a contributor who would rather not use Magpie at -all is unaffected. +Skip this step for individual use. +The preceding setup may have written local configuration, but has not committed a recommendation for your teammates. -The command is `/magpie-setup adopt`, or ask for it — *adopt Magpie for this -repository so everyone gets it on clone*. Nothing runs it for you: unlike -configuration, adoption is never automatic. +When the maintainers agree to adopt Magpie, run `/magpie-setup adopt`. +It prepares a shared configuration directory, an `.apache-magpie.lock` recording the recommended version and families, and agent settings derived from that recommendation. +For Claude Code, those settings live in `.claude/settings.json`. +Review the prepared changes before committing them. -→ [**Team adoption**](setup/team-adoption.md) is the full walkthrough: what -gets committed, how the floor is chosen, and what a contributor sees on clone. -Still deciding? [**Installation or Adoption?**](quick-start/two-ways.md) -compares the two side by side. - ---- +Contributors using the supported plugin setup receive the recommended families when they clone and trust the repository. +They may install additional families, use a newer version, or choose not to use Magpie. +Adoption is never automatic. +See [team adoption](setup/team-adoption.md) for the file layout and contributor experience. ## What each family solves -Skills ship in ten **families**, and you are not meant to take all of them. -[**What each family solves**](quick-start/families.md) lists every one with the -problem it solves and what it offers, so you can pick against a problem you -have today. - ---- +The [family reference](quick-start/families.md) lists the ten families, their tasks, and their outputs. +For example, choose `repo-health` for a dependency audit and `pr-management` for PR review. ## Other installation methods -The marketplace is not the only route. A project can install the framework as a -**pinned snapshot** committed to the repo — the answer when an agent has no -marketplace at all, when you need the signed ASF source release, or when every -contributor and CI job should sit on one committed version. A clone of the -framework itself takes a third route and **self-adopts**. - -→ [**Other installation methods**](quick-start/other-install-methods.md) covers -all three, with the copy-pasteable bootstrap for each. They are complementary, not exclusive: -pin the snapshot for the project and keep the marketplace plugin for yourself -if you prefer. +Use a **pinned snapshot** if your agent has no marketplace, you need a signed ASF source release, or contributors and CI jobs must use the same version. +The version pin is committed; the downloaded snapshot is gitignored. +A framework development checkout uses local self-adoption instead. ---- +[Other installation methods](quick-start/other-install-methods.md) provides the commands for each route. +A personal marketplace install can coexist with a project's pinned snapshot. ## Cross-references - [`docs/index.md`](index.md) — what Magpie is and which skill families exist. - [**The Apache Magpie Marketplace**](setup/marketplace.md) — the full reference: every agent that can add it, per-family plugins, versioning. -- [`docs/prerequisites.md`](quick-start/prerequisites.md) — what individual skills need +- [Prerequisites](quick-start/prerequisites.md) — what individual skills need (GitHub auth, Gmail MCP, browser). - [`docs/setup/README.md`](setup/README.md) — the setup skill family. diff --git a/docs/quick-start/README.md b/docs/quick-start/README.md index 65b40b31..8a302a76 100644 --- a/docs/quick-start/README.md +++ b/docs/quick-start/README.md @@ -11,18 +11,13 @@ # Quick start — reference pages -The [quick start](../quick-start.md) is the walkthrough: decide how you want to -use Magpie, install it, set the project up, then isolate the agent, guard what -it runs and set up privacy — and go. These are the pages it sends you to when -you want more than the step. +The [quick start](../quick-start.md) covers installation, project configuration, isolation, and privacy setup in order. +Use these reference pages for details on a particular step. | Page | What it answers | |---|---| -| [Installation or Adoption?](two-ways.md) | Whether anything gets committed for other people — and who has to agree before you start | -| [Prerequisites](prerequisites.md) | What individual skills need before they will run: agent, mail backend, tracker access, and the few skills with extra requirements | -| [Your first run with a family](first-run.md) | What happens the first time you invoke a family's skill: the pre-flight stopping, the setup wizard, the configuration it scaffolds, and which files that family actually needs | -| [What each family solves](families.md) | All ten families, the problem each one solves, and what it offers | -| [Other installation methods](other-install-methods.md) | The pinned snapshot in three flavours, and the self-adoption path a clone of the framework takes | - -Start at the [quick start](../quick-start.md); come back here when a step -raises a question. +| [Installation or Adoption?](two-ways.md) | Which files stay local, which are shared, and who decides | +| [Prerequisites](prerequisites.md) | Agent, mail-backend, tracker-access, and skill-specific requirements | +| [Your first run with a family](first-run.md) | A PR-triage example with missing configuration, local setup, and a retry | +| [What each family solves](families.md) | The ten families, their tasks, and their outputs | +| [Other installation methods](other-install-methods.md) | Pinned-snapshot installation and framework self-adoption | diff --git a/docs/quick-start/families.md b/docs/quick-start/families.md index 490fce7a..8cfbc1fb 100644 --- a/docs/quick-start/families.md +++ b/docs/quick-start/families.md @@ -14,38 +14,33 @@ ## Start with the baseline -Three plugins are the **strongly recommended** starting set. Take all three, -then add families against a problem you have today: +Install these three recommended plugins, then add the families needed for your tasks: | Plugin | Why it is in the baseline | |---|---| -| `magpie-setup` | **Install this one first — nothing else works without it.** It is what installs, upgrades, configures and adopts everything else, and it carries the secure-isolation skills that sandbox your agent. | -| `magpie-agent-guard` | The deterministic pre-execution guard: a hook that inspects each shell command *before* it runs and denies the dangerous shapes outright. It is not a family and has no skills of its own — it is a safety net under whatever else you install. | -| `magpie-utilities` | `list-skills`, so you can see what is actually installed, plus skill authoring and a path to report framework bugs upstream. Small, and the thing you reach for when something is not behaving. | +| `magpie-setup` | Install first. Provides installation, upgrades, local configuration, team adoption, and agent-isolation setup. | +| `magpie-agent-guard` | Inspects shell commands before execution and blocks prohibited patterns on supported agents. It is a hook plugin, not a skill family. | +| `magpie-utilities` | Lists installed skills, supports skill authoring, and prepares framework bug reports. | -This is not an arbitrary recommendation: it is exactly the set a project -commits as its **floor** when it adopts Magpie -([Installation or Adoption?](two-ways.md)). What a project recommends to -everyone who clones it is what you should have yourself. - -Isolation belongs here too. It is not a plugin but a run — -[Step 3 of the quick start](../quick-start.md#step-3--isolate--guard) -— and it ships inside `magpie-setup`. +Team adoption uses the same baseline as its shared recommendation. +See [installation and adoption](two-ways.md) for the distinction. +Installing `magpie-setup` makes the isolation skills available; run [isolation setup](../quick-start.md#step-3--isolate--guard) to enable the protections. ## The ten families -Skills ship in ten **families**. Install the ones that match a problem you have -today — you are not meant to take all of them. +Choose by the task and output you need. +For example, `pr-management` reviews an open PR, while `pairing` reviews a local diff before you submit it. +`repo-health` audits the repository's dependencies and CI configuration rather than reviewing one change. -| Plugin | Skills | The problem it solves | What it offers | +| Plugin | Skills | Use for | Output or action boundary | |---|---|---|---| -| `magpie-setup` | 10 | Your agent can read every credential on your machine, and you have no way to tell whether it is sandboxed right now. | A filesystem sandbox, a clean-env wrapper, a status line that shows sandbox state, and a red banner before any bypass. Plus install, upgrade, and drift checks. **You must install this one first** — it is what installs everything else. | -| `magpie-security` | 15 | Security reports arrive by mail and must be triaged, fixed, and disclosed on a clock — with nothing leaking early. | A 16-step lifecycle: intake from the mailbox, validity triage, canned responses, fix drafting, CVE allocation, advisory and publication. Drafts land in Gmail; nothing is ever sent for you. | -| `magpie-release-management` | 10 | An ASF release is a long checklist where one missed step invalidates the vote. | RC cut, RC verification (signatures, hashes, LICENSE/NOTICE, no stray binaries), the `[VOTE]` thread, the tally, promotion, `[ANNOUNCE]`, archive sweep, audit log. The agent never holds your signing key and never publishes. | -| `magpie-pr-management` | 8 | The PR queue grows faster than you can read it, and the oldest ones quietly rot. | Queue triage into ready / needs-review / waiting-on-author, deep code review with blocking vs non-blocking findings, reviewer routing, express-lane merge, stale sweep, and queue statistics. | -| `magpie-issue` | 8 | A backlog full of duplicates, unreproducible reports, and issues nobody has read in a year. | Triage with proposed labels, duplicate clustering, reproduction attempts across versions, fix drafting, reassessment of old issues, stale sweep, and backlog stats. | -| `magpie-repo-health` | 7 | Slow rot you only notice when it breaks: vulnerable deps, unpinned actions, licence drift, flaky tests. | Read-only audits for dependency CVEs, dependency licences, LICENSE/NOTICE compliance, Actions workflow security, obsolete runner labels, and flaky-test patterns — plus a skill that fixes what they find. | -| `magpie-contributor-growth` | 6 | Contributors who have earned committership go unnoticed because nobody is tracking the signal. | Activity sweeps against a review threshold, readiness tracking, sentiment signals, nomination briefs for the PMC, and committer / post-vote onboarding checklists. | -| `magpie-utilities` | 5 | You want to write your own skills, or find out what is actually installed. | Skill authoring and restructuring, a state reconciler, a live index of installed skills, and a path to report framework bugs upstream. **In the baseline.** | -| `magpie-mentoring` | 4 | Newcomers open one PR, hit a wall of unwritten conventions, and never come back. | First-contact welcome comments, plain-language explanations of an issue for someone new, good-first-issue authoring, and a sweep that keeps that backlog honest. | -| `magpie-pairing` | 2 | You want the obvious problems found before a reviewer spends their time on them. | A structured self-review of your own diff, and a multi-agent adversarial review that verifies its findings before reporting them. | +| [`magpie-setup`](../setup/README.md) | 10 | Installation, configuration, isolation, and upgrades | Proposed setup changes, installation status, and drift reports. | +| [`magpie-security`](../security/README.md) | 15 | Security-report intake through CVE publication | Triage assessments, tracker updates, fix drafts, and advisory drafts. Outbound messages require review. | +| [`magpie-release-management`](../release-management/README.md) | 10 | ASF release candidates, votes, and announcements | RC checks, vote drafts and tallies, promotion instructions, and audit records. The agent does not hold signing keys or publish releases. | +| [`magpie-pr-management`](../pr-management/README.md) | 8 | Open-PR triage, code review, and queue maintenance | Draft reviews, proposed routing and stale-PR actions, merge proposals, and queue statistics. | +| [`magpie-issue`](../issue-management/README.md) | 8 | Issue triage, reproduction, fixes, and reassessment | Disposition proposals, reproduction evidence, draft fixes, deduplication proposals, and backlog reports. | +| [`magpie-repo-health`](../repo-health/README.md) | 7 | Dependencies, licences, CI workflows, runners, and flaky tests | Read-only audit reports. A separate fix skill handles supplied non-security audit findings. | +| [`magpie-contributor-growth`](../contributor-growth/README.md) | 6 | Contributor activity, nominations, and onboarding | Activity reports, threshold-based readiness tracking, sentiment reports, nomination briefs, and onboarding checklists. | +| [`magpie-utilities`](../utilities/README.md) | 5 | Skill discovery, authoring, and maintenance | Installed-skill index, new or restructured skills, reconciliation, and framework issue reports. | +| [`magpie-mentoring`](../mentoring/README.md) | 4 | Newcomer orientation and good-first-issue preparation | Draft welcome comments, issue explanations, new issue drafts, and backlog suitability assessments. | +| [`magpie-pairing`](../pairing/README.md) | 2 | Local diff review | Structured self-review or independent multi-agent review findings, without posting or modifying code. | diff --git a/docs/quick-start/first-run.md b/docs/quick-start/first-run.md index 1ddbaf4d..4d923799 100644 --- a/docs/quick-start/first-run.md +++ b/docs/quick-start/first-run.md @@ -6,14 +6,14 @@ **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - [Your first run with a family](#your-first-run-with-a-family) - - [1. Run a skill — it notices, and fixes it](#1-run-a-skill--it-notices-and-fixes-it) - - [2. It configures, deriving what it can](#2-it-configures-deriving-what-it-can) - - [3. It writes, and nothing is committable](#3-it-writes-and-nothing-is-committable) + - [1. Run a skill](#1-run-a-skill) + - [2. Review the configuration](#2-review-the-configuration) + - [3. Inspect the local files](#3-inspect-the-local-files) - [4. Run it again](#4-run-it-again) - [5. Only if you are adopting: `/magpie-setup adopt`](#5-only-if-you-are-adopting-magpie-setup-adopt) - - [The other two things the install offers](#the-other-two-things-the-install-offers) + - [Additional integrations](#additional-integrations) - [MCP servers — backends a few skills read through](#mcp-servers--backends-a-few-skills-read-through) - - [Companion skills — other people's packages](#companion-skills--other-peoples-packages) + - [Companion skill packages](#companion-skill-packages) - [What you configured, and what you did not](#what-you-configured-and-what-you-did-not) - [Where to go next](#where-to-go-next) @@ -24,86 +24,90 @@ # Your first run with a family -Installing a family puts its skills in your agent. It does not tell them -anything about your project — which repository, which tracker, which labels -mean "ready for review". A skill that guessed at those would do the wrong -thing confidently, so instead the first one you run stops and says what it -needs. +Installing a family makes its skills available to your agent. +Project configuration supplies the repository, tracker, labels, and other values those skills need. +If required files are missing, the skill starts a local configuration flow before doing the requested work. -This page is that first run, end to end, with `magpie-pr-management` as the -example. Every family works the same way; only the list of files differs, and -each family README carries its own list under *Before the first run*. +This example uses an installed `magpie-pr-management` family in a repository with no Magpie configuration. +For installation commands, see the [marketplace reference](../setup/marketplace-install.md). +Complete the [isolation and privacy setup](../quick-start.md#step-3--isolate--guard) before running against external or private data. -Steps 1 to 4 are the whole flow for one person. Step 5 is the separate thing a -maintainer does for the project, and most readers never need it. +Steps 1–4 configure individual use. +Step 5 is optional team adoption. +The terminal illustrations show example output, not results from your repository. -The starting point is a family already installed — -[Prerequisite: install Magpie from your agent's -marketplace](../setup/marketplace-install.md) if you have not. +## 1. Run a skill -## 1. Run a skill — it notices, and fixes it +From the target repository, enter: -![A triage run whose pre-flight finds no project configuration, names what it would otherwise have to guess, and starts configuring rather than stopping](../../assets/quickstart/walkthrough/1-preflight-stops.svg) +```text +/magpie-pr-management:triage +``` -Sixty-five of the skills open with this check. It costs three file lookups -and, once the configuration resolves, prints nothing at all — you will not see -it again. +![A triage pre-flight detects missing project configuration and invokes the local configuration flow](../../assets/quickstart/walkthrough/1-preflight-stops.svg) -You did not have to run anything: the skill invokes -[`/magpie-setup config`](../../skills/setup/config.md) itself and says so. -That is safe to do unasked because of what `config` touches — gitignored files -in your clone and nothing else. It stages nothing, commits nothing, and -changes nothing any teammate can see. +The pre-flight check invokes [`/magpie-setup config`](../../skills/setup/config.md) when required configuration files are missing. +That flow writes only local, gitignored configuration; it does not stage or commit files. +Triage does not proceed with guessed repository or tracker values. -What it will **not** do is proceed on a guess. It did not label anything, post -anything, or fall back to a default committer team. +Once the required configuration resolves, the pre-flight check completes without prompting. +It runs on subsequent invocations too, so later drift or missing files can still interrupt a task. -## 2. It configures, deriving what it can +## 2. Review the configuration ![What config derived from the repository itself, and the single prompt covering the values it could not](../../assets/quickstart/walkthrough/2-config-wizard.svg) -It reads the skill's declared requirements, derives every value it can from the -repository itself — the `origin` remote, the label taxonomy, the CI checks that -actually run — and asks **one** question covering whatever is left. Skip any of -them; a `TODO` left in place is not an error. +Setup reads the skill's requirements and derives values from the repository where possible: the `origin` remote, existing labels, and configured CI checks. +It groups unresolved values into one prompt. -> [!NOTE] -> **`config` is a finished state, not a step towards adopting.** Most people -> who install Magpie should never run `adopt`. Configuring for yourself is the -> whole flow for individual use; step 5 is for the separate case where you are -> a maintainer deciding for the project — and nothing runs it for you. +Review the derived repository carefully. +For example, if `origin` points to your fork but you intend to triage the upstream project's PRs, supply the upstream repository. +You may leave an unknown value as `TODO`; a skill that needs it must resolve it before using it. -## 3. It writes, and nothing is committable +Local configuration is sufficient for individual use. +You do not need to run `adopt`. + +## 3. Inspect the local files ![The config result: three files written to the gitignored local directory, the exclusion added to .git/info/exclude rather than .gitignore, and a note that a TODO left in place is not an error](../../assets/quickstart/walkthrough/3-scaffolded.svg) -Everything lands in **`.apache-magpie-local/`**, which is yours: +Configuration is written to `.apache-magpie-local/`: | | `.apache-magpie-local/` | `.apache-magpie-overrides/` | |---|---|---| | Written by | `config` | `adopt` | -| Committed | never | yes | +| Tracked by Git | no | yes | | Who sees it | you, in this clone | everyone who clones the repo | -| Needs permission | no | a maintainer decision | +| Decision | individual configuration | maintainer approval for shared configuration | + +**Local configuration takes precedence per file, not per field.** +If both directories contain `project.md`, the skill reads the local file rather than merging the two. +It can still read a different file, such as `naming-conventions.md`, from the shared directory when no local copy exists. -**Local wins, per file.** A skill takes your copy of `project.md` if you have -one and the project's otherwise, deciding file by file — so you can hold one -value of your own and take every other from the project. +Setup adds the local directory to `.git/info/exclude`, leaving the tracked `.gitignore` unchanged. +To inspect the result, run: -Note what it did about `.gitignore`: nothing. `.gitignore` is a committed -file, and a sub-action promising to write nothing anyone else sees must not -open by editing one. The exclusion goes in `.git/info/exclude`, which is -per-clone and never committed. +```bash +git status --short +git check-ignore .apache-magpie-local/project.md +``` -A `TODO` left in place is not an error. The skill that needs a value names it -when it needs it; the skills that do not never look. +In an otherwise clean checkout, the first command should show no tracked changes from configuration. +The second should print the local file's path, confirming it is ignored. ## 4. Run it again ![The same triage command, now passing both pre-flight checks and getting on with the work: 38 open PRs, 12 untriaged, with a proposed action per PR](../../assets/quickstart/walkthrough/4-it-runs.svg) -That is individual use, complete. Nothing was committed, no teammate was -affected, and you did not ask anyone's permission. +Retry the same command: + +```text +/magpie-pr-management:triage +``` + +With configuration resolved, the skill reads the PR queue and presents its assessment and proposed actions. +The illustration's counts are examples; your output reflects the target repository. +Review the proposals before approving any shared-state changes. Which files each family needs is on its README under *Before the first run*: [security](../security/README.md#before-the-first-run) · @@ -117,106 +121,66 @@ Which files each family needs is on its README under *Before the first run*: [pairing](../pairing/README.md#before-the-first-run) · [setup](../setup/README.md#before-the-first-run) -Those tables are generated from the skills themselves, so they cannot drift -from what the skills actually read. +Those tables are generated from the skills' declared requirements. ## 5. Only if you are adopting: `/magpie-setup adopt` ![The adopt wizard promoting two of the three local files to the project, leaving the unfinished one behind, and removing the local copies that are now identical](../../assets/quickstart/walkthrough/5-adopt-promotes.svg) -**Nothing runs this for you, and nothing will ask.** Step 2 mentions in one -line that adoption exists and then drops it — because adopting commits a -recommendation every contributor picks up on clone, and that is a decision the -maintainers take together, not a prompt at the end of a configure run. - -**Skip it unless you are a maintainer deciding for the project.** - -What you already configured is the best starting point, because it is a set of -answers that demonstrably works on this project. `adopt` offers to **promote** -it: copy the files you select into the committed store, leave anything that -still reads `TODO` or looks personal behind, and then drop the local copies -that are now byte-identical — so a correction the project commits later -actually reaches you, instead of being shadowed by your own stale twin -forever. +Skip this step unless the maintainers have decided to share a Magpie setup. +Adoption is never invoked automatically. -A maintainer who knows from the start that they are adopting can go straight -here; `adopt` scaffolds whatever `config` did not. +`/magpie-setup adopt` offers to copy selected local files into `.apache-magpie-overrides/`. +It excludes personal values and unfinished `TODO` entries from promotion. +It also removes local copies that are byte-identical to the shared files, so later shared updates are not hidden by stale local copies. +Review the proposed files before committing them. -→ [**Team adoption**](../setup/team-adoption.md) is the full walkthrough of -what gets committed and what a contributor sees on clone. +You may also run `adopt` without configuring locally first; it scaffolds the missing files. +See [team adoption](../setup/team-adoption.md) for the shared recommendation and contributor setup. -## The other two things the install offers +## Additional integrations -Neither blocks a first run. Both are offered during install, and both are -worth coming back to once the family is doing something for you. +Installation also offers MCP servers and companion skill packages. +MCP requirements depend on the chosen skill; companion packages are optional. ### MCP servers — backends a few skills read through -Some skills read from somewhere the agent cannot reach on its own: a mailing -list archive, a foundation's roster, a mail account. Those come through MCP -servers, and the wizard offers three: +Some skills use MCP servers to access mail archives, rosters, or mail accounts. +The installation flow offers these three: -| Server | What it reads | When you need it | +| Server | Access | When you need it | |---|---|---| | `ponymail` | ASF mailing-list archives | The primary mail-read backend for the `security` and `release-management` families. **Mandatory for ASF projects**; Gmail is the fallback elsewhere | | `apache-projects` | ASF rosters, people and releases, read-only | `contributor-nomination` and the security roster paths. **Mandatory for ASF projects** | -| `gmail-plaintext` | — (it *writes*: plain-text Gmail drafts with no tracking redirects) | Only if you draft mail from the agent. Not ASF-gated | +| `gmail-plaintext` | Creates plain-text Gmail drafts without tracking redirects | Only if you draft mail from the agent. Not ASF-gated | -A skill that needs one and cannot find it says so by name, the same way a -skill names a missing configuration file. Nothing silently degrades to a worse -source. +A skill reports a missing required backend before proceeding. +Register servers per machine; local project configuration does not install them. +See the [installation flow](../setup/marketplace.md#auto-install-arriving-magpie-ready) for registration details. -Registering them is a per-machine step, not a per-project one — like the -plugin install itself, and unlike anything `config` writes. The walkthrough is -in -[`/magpie-setup`'s install flow](../setup/marketplace.md#auto-install-arriving-magpie-ready). +### Companion skill packages -### Companion skills — other people's packages +Companion packages provide additional workflows, such as code scanning or development planning. +They are optional, are not selected by default, and are offered only for agents they support. -Magpie ships skills for maintaining a project. Some of what a maintainer wants -next is not maintenance — scanning your own code for vulnerabilities, or a -method for thinking a change through before writing it — and other people have -built those well. +Some require a third-party marketplace. +For example, Superpowers uses `obra/superpowers-marketplace`; adding that marketplace makes its catalogue available, not just the selected package. +The installation flow identifies the publisher and supplies commands for you to run. +Magpie does not bundle or fetch companion packages automatically. -The install flow offers them, **never pre-ticked**, and only the ones -available on the agent you are running: a package that exists for Claude Code -alone is not offered to a Codex user with a command they cannot run. - -Some of them live in a marketplace that is **not** Magpie's — Superpowers is -published in `obra/superpowers-marketplace`. Taking one of those means adding -that catalogue to your agent, for everything in it and not only the package -you wanted, so the offer says so and the marketplace add is a step of its own. -Magpie never adds one for you: these are commands you run, exactly like the -Magpie install lines. - -None of them is a dependency. Every family works with none installed, Magpie -bundles none and fetches none automatically, and each entry says whose it is -so the choice stays yours. - -→ [**Companion skill packages**](../setup/companion-skills.md) — what each one -adds to which family, and the install command for every agent that has it. +See [companion skill packages](../setup/companion-skills.md) for publishers, purposes, and agent-specific install commands. ## What you configured, and what you did not -**Per machine, once.** The marketplace install, any MCP servers you -registered, and any companion packages. No repository records them, and a -teammate cloning this repo gets none of them — which is why an MCP server a -family depends on is named in that family's prerequisites rather than assumed. - -**Per clone, yours.** Everything `config` wrote, in -`.apache-magpie-local/`. Gitignored, invisible to everyone else, and a -complete end state: a contributor can work this way indefinitely on a -repository that has never adopted Magpie. - -**Per project, committed.** Only if step 5 happened: the floor lock, the -derived wiring, and the project's configuration store. A teammate who clones -an adopted repository skips steps 2 and 3 entirely — the configuration is -already there. - -**Never.** Nothing above pins a version, removes a plugin, or limits what you -install or configure for yourself. The floor is a minimum in both dimensions — -a contributor running a newer Magpie with seven families installed satisfies it -completely and is told nothing. +| Scope | Contents | Shared through Git? | +|---|---|---| +| Machine | Installed plugins, registered MCP servers, and optional companion packages | No; each contributor needs the required backends locally. | +| Clone | `.apache-magpie-local/` configuration and its Git exclusion | No. | +| Project, after adoption | Recommended version and families, derived agent settings, and `.apache-magpie-overrides/` | Yes. | + +A contributor cloning an adopted repository can use its shared configuration without repeating local setup for those files. +They still need the appropriate agent, credentials, and backends. +The marketplace adoption recommendation permits newer versions and additional families; it does not uninstall personal plugins. ## Where to go next diff --git a/docs/quick-start/two-ways.md b/docs/quick-start/two-ways.md index f4d4743a..6530bbe8 100644 --- a/docs/quick-start/two-ways.md +++ b/docs/quick-start/two-ways.md @@ -10,36 +10,29 @@ # Installation or Adoption? -**Installing** puts the **Apache Magpie Marketplace** and the plugins into -your agent and writes -nothing to any repository. That is what the steps below do, it is complete on -its own, and it is all most people ever need. - -From here the two ways to use it differ in one thing only — whether anything is -committed for other people. +**Installation** adds the Magpie marketplace and plugins to your agent. +It does not write to a repository. +Once installed, skills need repository-specific configuration, which can be local to your clone or shared through team adoption. | | [**Individual use**](../setup/individual-use.md) | [**Team adoption**](../setup/team-adoption.md) | |---|---|---| -| Who decides | You | The repo's maintainers | -| What it commits | Nothing — configuration lives in gitignored `.apache-magpie-local/` | The floor, and the project's configuration in `.apache-magpie-overrides/` | -| Which repos | Any — adopted or not, whether or not your teammates use Magpie | The one repo, for everyone who clones it | -| What a teammate sees | Nothing at all | The default families already enabled on arrival | -| Undone by | You, any time | A maintainer, via a PR | - -**Individual use is the default, and it is not a waiting room.** You can work -this way indefinitely, on a repo whose maintainers have never heard of Magpie. -Nothing on this page asks the project for permission — including the -configuration a skill needs, which `/magpie-setup config` writes into a -gitignored directory only your clone sees. A skill that finds it missing runs -that itself. - -**Adoption is a recommendation, not a restriction.** A repo that has adopted -Magpie gives contributors a sensible floor on clone — it never limits what -anyone may install for themselves, and it never obliges a contributor to use -what it recommends. - -Neither one is an install method. Installing is what the -[quick start](../quick-start.md) walks you through; these are what you then do -with it. Follow it either way — [adoption](../setup/team-adoption.md) is a -later, separate act by the repo's maintainers, and nothing in the quick start -requires it. +| Who decides | You | The repository's maintainers | +| Configuration | Gitignored `.apache-magpie-local/` | Committed `.apache-magpie-overrides/` | +| Shared files | None | Recommended version and families, agent settings, and project configuration | +| Scope | Your clone, whether or not the project has adopted Magpie | Contributors who clone the repository | +| Effect on teammates | No shared configuration changes | Recommended families enabled on supported agents after repository trust | +| How to undo | Remove your local configuration or uninstall your plugins | Change the shared configuration through a PR | + +**Example: reviewing PRs on your own.** +Install `magpie-pr-management` and run `/magpie-pr-management:triage`. +If required configuration is missing, the skill invokes `/magpie-setup config`. +The resulting files stay in your clone. +You can keep using this setup without adopting Magpie for the project. + +**Example: sharing a working setup.** +After the maintainers agree on the recommended families and configuration, run `/magpie-setup adopt`. +Review the local files it proposes to promote into shared configuration. +Personal values and unresolved `TODO` entries should not be promoted. + +Adoption does not prevent contributors from installing more families, using a newer version, or choosing not to use Magpie. +Start with the [quick start](../quick-start.md) for installation, or see [team adoption](../setup/team-adoption.md) for the shared-file workflow.