Apache Magpie is a project-agnostic framework for agent-assisted repository maintainership and development. It is not an application with a src/ tree — it is a substrate plus a catalogue of agent-readable skills (Markdown + YAML) and deterministic tools (uv/Python). The specs in this directory describe that functionality so the build loop can keep the code in sync with the intended behaviour.
These specs are unordered — the filename is a topic, not a priority. What to build next comes from ../IMPLEMENTATION_PLAN.md, not from any numbering.
Issue/PR ingestion, GitHub write-back, mail threading, audit logging, and pluggable adapters for the systems a project already uses (Gmail, PonyMail, Jira, GitHub, Vulnogram). Per-project configuration declares which modes are on, eligible change classes, reviewers, and where reports come from.
Each mode is an independently toggleable set of skills. Maturity mirrors docs/modes.md:
| Mode | Spec | Maturity |
|---|---|---|
| Agentic Triage | triage-mode.md | stable (security) / experimental (PR, issue, contributor-nomination) |
| Agentic Mentoring | mentoring-mode.md | experimental (5 skills) |
| Agentic Drafting | drafting-mode.md | stable (security) / experimental (issue, audit-finding-fix, release-announce-draft) |
| Agentic Pairing | pairing-mode.md | experimental (2 skills) |
Agentic Autonomous is the fifth MISSION mode but is deliberately off by sequencing policy (
.asf.yamlallow_auto_merge: false) — it has no implementation and nothing to build, so it is documented as a boundary indocs/modes.md, not as a spec here.
| Area | Spec |
|---|---|
| Security-issue lifecycle (the load-bearing use case) | security-issue-lifecycle.md |
| Release-management lifecycle (experimental — all 10 skills shipped) | release-management-lifecycle.md |
| Privacy-LLM gate + PII redaction | privacy-llm-gate.md |
| Agent isolation / layered sandbox | agent-isolation-sandbox.md |
| CVE tooling | cve-tooling.md |
| Security reporting & dashboards | security-reporting.md |
| Adoption & setup | adoption-and-setup.md |
| Adapters (Gmail / maildir / PonyMail / Jira / GitHub / SourceHut / VCS / change-request / mail-source / asf-svn / forwarder-relay / mail-archive / mail-patch / jira-patch / github-body-field / github-rollup) | adapters.md |
| Project-agnosticism (de-ASF coupling) | project-agnosticism.md |
| Meta & quality tooling | meta-and-quality-tooling.md |
| Spec-loop runner (plan/build/update/consolidate + headless harnesses) | spec-loop-runner.md |
| Reviewer routing (experimental, Agentic Triage) | reviewer-routing.md |
| Cross-project skill reconciler (experimental, infra) | skill-reconciler.md |
| Maintainer-education stream (proposed — release-blocking per PRINCIPLE 18) | maintainer-education.md |
docs/rfcs/ holds the normative statement; this spec system respects it as a constraint and never edits it.)git push / gh pr create on autopilot.The build loop (see ../README.md) compares each spec against the code and turns the gaps into work items in the plan — one work item, one branch, one PR.