Table of Contents generated with DocToc
MISSION.md frames the framework around five toggleable modes of agent-assisted repository maintainership and development: Triage, Mentoring, Drafting (agent-authored fixes with human review), Pairing (developer-side dev-cycle skills with mentorship intrinsic), and Auto-merge (narrowly-scoped fix-and-merge). Each adopting project picks the modes that match its culture and risk tolerance.
This document maps that taxonomy to the skills that currently ship in the framework. It is the honest snapshot — modes that are not yet implemented are listed as such, with a tracking issue or roadmap pointer rather than a placeholder shell. Read MISSION.md for the why of each mode and the sequencing commitments behind them.
| Status | Meaning |
|---|---|
| stable | Implemented, in use by at least one adopter, behaviour expected to remain backward-compatible across minor framework versions. |
| experimental | Implemented but not yet covered by an adopter pilot or contributor-sentiment evaluation; shape may change. |
| proposed | Designed in MISSION.md but no skill yet exists; tracked for future implementation. |
| off | Deliberately not implemented per a MISSION-level sequencing rule (Auto-merge). |
| Mode | Purpose | Status | Skill count |
|---|---|---|---|
| Triage | Issues, security reports, PRs: spot, classify, route, surface duplicates. Every output is a suggestion the human signs off on. | stable (security) / experimental (pr-management, issue-management, contributor-nomination) / proposed (release-management) | 13 + 4 proposed |
| Mentoring | Joins issue and PR threads in a teaching register: clarifying questions, pointers to project conventions, paired examples from prior PRs, hand-off to a human when scope exceeds the agent. | experimental | 1 |
| Drafting | Agent drafts a fix for a well-scoped problem and opens a PR; every PR is reviewed and merged by a human committer. | stable (security-only); experimental (issue-management); release-management family proposed | 2 + 6 proposed |
| Pairing | Developer-side dev-cycle skills with mentorship intrinsic — multi-agent review pipelines, self-review and pre-flight patterns, scoped fix drafting under the developer‘s driver’s seat. | experimental | 1 |
| Auto-merge | Auto-merge restricted to objectively boring change classes (lint, dependency bumps inside an allow-list, license-header insertion, formatting, broken-link repair). | off | 0 |
A few skills sit outside the mode taxonomy by design — see Outside the modes below.
Inbound report and PR triage. The lowest-risk surface and the foundation everything else builds on. Skills propose labels, spot duplicates, link related discussions, classify reports against prior triaged cases, and route to the right human; they do not act without human review.
| Skill | Domain | Status |
|---|---|---|
pr-management-triage | Generic PR queue triage. | experimental |
pr-management-stats | PR-queue reporting (supports triage decisions). | experimental |
pr-management-code-review | Maintainer-facing deep code review. | experimental |
issue-triage | General-issue-tracker triage (per-issue classification + disposition proposal). | experimental |
issue-reassess | Pool-level sweep of resolved / EOL issues for re-assessment. | experimental |
contributor-nomination | Nomination-readiness brief for a named contributor — activity breadth, consistency, and evidence prose for a committer or PMC thread. | experimental |
security-issue-import | Inbound security-report classification + initial routing. | stable |
security-issue-import-from-pr | Open a tracker from a security-relevant public PR. | stable |
security-issue-import-from-md | Bulk-import findings from a markdown report. | stable |
security-issue-deduplicate | Merge two trackers describing the same root-cause vulnerability. | stable |
security-issue-invalidate | Close a tracker as invalid with a polite-but-firm reporter reply. | stable |
security-issue-sync | Reconcile a tracker against its mail thread, fix PR, release train, and archives. | stable |
security-cve-allocate | Allocate a CVE for a tracker (Vulnogram URL + paste-ready JSON). | stable |
release-verify-rc | Read-only pre-flight on a staged RC: signatures against project KEYS, checksums, license headers (Apache RAT), NOTICE/LICENSE diff, no prohibited binaries, version-string consistency. Doubles as a Pairing-mode skill voters run in their own dev loop. | proposed |
release-vote-tally | Parse a [VOTE] thread, classify each reply (+1 / 0 / -1) binding vs non-binding against the PMC roster, propose [RESULT] [VOTE]. Conservative on ambiguous votes, refuses to count. | proposed |
release-archive-sweep | Scan dist/release/<project>/, identify releases past retention, propose the svn mv sequence to archive.apache.org. | proposed |
release-audit-report | Per-release structured report (RM, voters with binding flags, artefacts with sigs and checksums, promote revision, [ANNOUNCE] archive URL) appended to the project's audit log. | proposed |
Three notes on the boundaries:
pr-management-code-review is a deeper variant of triage — the agent reads diff and surrounding code rather than only metadata, but the output is still a suggestion for the human reviewer. It belongs to Triage by the same rule.security-cve-allocate is procedural rather than classificatory (CVE allocation happens after assessment), but it shares Triage's shape: the agent prepares a paste-ready artefact, the human PMC member submits it. Listed here for navigability.release-* Triage skills share the same paste-ready- artefact shape: release-verify-rc reports pass/fail per check, release-vote-tally proposes [RESULT], release-archive-sweep proposes an svn mv sequence, release-audit-report proposes an audit-log append. None of them flip state labels or publish artefacts, see docs/release-management/spec.md § Cross-cutting commitments.Status: experimental. First prototype skill shipped.
MISSION.md § Mentoring names this the highest-value project-side mode and the one off-the-shelf agent tooling skips. The spec — tone guide, hand-off protocol, adopter contract — landed ahead of the skill code so the project's tone choices were reviewable independently from the runtime behaviour.
| Skill | Purpose | Status |
|---|---|---|
pr-management-mentor | Draft a teaching-register comment on a single GitHub issue or PR thread; waits for maintainer confirmation before posting. | experimental |
| Doc | Purpose |
|---|---|
docs/mentoring/README.md | Family overview, current status, planned shape. |
docs/mentoring/spec.md | Full spec: scope, triggers, register, hand-off, adopter knobs. |
projects/_template/mentoring-config.md | Adopter-config scaffold (required before running the skill). |
The prototype ships flagged mode: Mentoring + experimental. Shape may change as adopter pilots and contributor-sentiment evaluation land. The skill is read-only by default and never posts without explicit maintainer confirmation — see pr-management-mentor/SKILL.md for the full contract.
The closest existing surface is pr-management-triage/comment-templates.md, which carries Triage classification responses — informational, not pedagogical. It is not Mentoring.
The agent drafts a fix for a well-scoped problem (a tracked issue, a triaged security report with team consensus on scope, a failing test with an obvious cause, a documentation hole) and opens a PR. Every PR is reviewed and merged by a human committer; the agent never merges its own work.
| Skill | Domain | Status |
|---|---|---|
security-issue-fix | Draft a fix PR in <upstream> from a triaged, CVE-allocated tracker. | stable (security-only) |
issue-fix-workflow | Draft a fix for a triaged general-issue-tracker issue (BUG or FEATURE-REQUEST). | experimental |
release-prepare | Planning issue + version-bump / changelog / NOTICE / LICENSE prep PR (Steps 1-2). Also the post-release -SNAPSHOT bump (Step 14). | proposed |
release-keys-sync | Draft the KEYS diff for a new Release Manager (Step 3). Agent never holds the private key. | proposed |
release-rc-cut | Paste-ready command sequence: signed tag, build, detached signatures, checksums, svn import to dist/dev/ (Steps 4-5). Agent never signs and never imports. | proposed |
release-vote-draft | Draft the [VOTE] email body to dev@<project> (Step 7). Agent never sends. | proposed |
release-promote | Paste-ready svn mv dist/dev → dist/release command set after a passing vote (Step 10). Agent never moves; the human commit is the act of release. | proposed |
release-announce-draft | Draft the [ANNOUNCE] email body for announce@apache.org and the site-bump PR (Step 11). Agent never sends mail and never merges the PR. | proposed |
Generic Drafting is proposed. MISSION.md names lint fixes, audit-tool findings (Apache Verum, Apache Caer, CodeQL, equivalents), failing tests with obvious causes, and documentation holes as in-scope for Drafting beyond the security case. None of those are implemented yet; security-issue-fix is the only Drafting skill shipping in the framework today.
The six release-* Drafting skills above land as a single family (docs/release-management/README.md) once the spec lands. They share the security family's discipline that every state-changing action is a proposal the human executes, see docs/release-management/spec.md § Cross-cutting commitments.
For security-class Drafting PRs, the public surface strips CVE and private context per the project's disclosure policy, so the public surface stays clean until the embargo lifts — see AGENTS.md § Confidentiality for the rules the skill enforces.
Status: experimental. 1 skill.
MISSION.md § Pairing introduces this mode as the developer-side counterpart to the project-side modes. Where Triage / Mentoring / Drafting / Auto-merge describe the agent‘s presence on the project’s own infrastructure, Pairing skills run in the maintainer‘s or contributor’s own dev loop — multi-agent review pipelines, self-review and pre-flight patterns, scoped fix drafting under the developer‘s driver’s seat. Mentorship is intrinsic to Pairing skills: the agent handles the mechanical, implementation-detail review (formatting, conventions, lint-grade nits) so the human conversation between contributor and maintainer — and between peer maintainers — stays on design, reasoning, and the trade-offs the project cares about. Pairing skills are the platform's mechanism for protecting the ASF contribution path (contributor → committer → PMC) against being eroded by automation that replaces, rather than augments, the human-to-human relationships that path is built on.
Pairing skills don't make state changes on behalf of the project; they share the same skill format and security posture as the project-side modes, so a maintainer who already trusts the framework for Triage gets the same posture for the patches they write themselves.
| Skill | Domain | Status |
|---|---|---|
pairing-self-review | Pre-flight self-review of local changes before opening a PR. Read-only; returns a structured report. | experimental |
A multi-agent review pipeline (fans the diff through independent review passes) is the planned follow-on Pairing skill; it shares the self-review report format and follows this one.
Sequencing. Pairing ships before Auto-merge in the project's automation roadmap — full auto-merge of maintainer-driven changes follows only after Pairing has established that human reasoning and relationships, not implementation chatter, are the load-bearing parts of the workflow.
Status: off. Deliberately not implemented.
MISSION.md § Auto-merge holds auto-merge off until Triage, Mentoring, Drafting, and Pairing have been running for two quarters and contributor-sentiment data says the project is healthier, not just faster. Security-class changes are explicitly out of Auto-merge — no auto-merge ever touches anything embargoed or CVE-tagged.
The framework's current .asf.yaml configuration reflects this posture: pull_requests.allow_auto_merge is set to false (.asf.yaml).
When Auto-merge ships, the eligible change classes will be declared per-adopter in <project-config>/ and gated by an allow-list that the framework refuses to grow without an adopter PR.
Several skills are framework infrastructure rather than maintainership modes. They support adoption, isolation, and upgrade flows; they do not act on issues, PRs, or contributor threads on their own.
| Skill | Purpose |
|---|---|
setup-steward | Adopt the framework into an adopter repo; manage the snapshot, symlinks, and overrides. |
issue-reproducer | Per-issue code extraction + execution; produces structured evidence. Read-only on the tracker. |
issue-reassess-stats | Read-only dashboard over reassessment-campaign verdict.json files. |
setup-isolated-setup-install | Install the credential-isolation sandbox harness. |
setup-isolated-setup-update | Update pinned system tools (bubblewrap, socat, agent CLI) past the cooldown window. |
setup-isolated-setup-verify | Read-only health check of the sandbox harness. |
setup-override-upstream | Promote an adopter's local override into a framework PR. |
setup-shared-config-sync | Sync shared configuration across worktrees. |
These ship as a single setup family — see docs/setup/README.md.
A mode moves through four states as it matures:
MISSION.md, no skill code yet. Spec PRs may land before any skill code so tone, scope, and adopter knobs are reviewable in isolation.A mode can be retracted from any state. The retraction triggers MISSION names — sustained negative contributor sentiment, a confidentiality leak, a sandbox bypass that escapes detection — apply per-adopter and per-mode. A retraction in one adopter does not auto-retract in another, but the framework records it for cross-adopter pattern detection.
MISSION.md — the why of each mode, the sequencing commitments, and the privacy/security/vendor- neutrality posture each mode inherits.README.md — adopter-facing skill family table; this document is the maintainer-facing taxonomy view of the same skills.AGENTS.md — repository-level rules every mode inherits (external content as data, polite-but-firm tone, brevity, confidentiality).docs/mode-economics.md — indicative token-cost shape per mode and model class; for maintainers evaluating adoption.