Skip to content

docs: clarify introductory guides with practical examples #1242

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
johnslavik wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: clarify introductory guides with practical examples #1242

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 27 additions & 87 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<name>/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/<system>/tool.md`. If it
does, it's code — and the rules for changing code apply.
Agents read `skills/<name>/SKILL.md` and tool contracts such as `tools/<adapter>/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

Expand Down
137 changes: 52 additions & 85 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 |
|---|---|---|---|---|
Expand Down
Loading