Table of Contents generated with DocToc

• Labels and capabilities
  • Label dimensions
    • 1. family:* — subject
    • 2. capability — two axes (skills vs tools)
    • Coverage qualifiers
    • 3. kind:* — change type (pre-existing)
    • 4. mode:* — handling mode (pre-existing)
    • Standalone labels
  • Capability to skill map
  • Capability to tool map
  • MCP servers, classified by capability
  • The rule
    • A GitHub issue
    • A pull request
    • A new tool under tools/
    • A new skill under .claude/skills/
    • A new doc under docs/
  • Why this exists

Labels and capabilities

This page is the canonical reference for the label taxonomy used on issues and pull requests in this framework repository (apache/magpie). It also defines the capability model that classifies what each skill or tool in the framework actually does, independent of which subject area it sits under.

Every issue and pull request opened against this repository should carry at least one family:* label and at least one capability:* label. New tools and new skills must declare their capability up front (see The rule).

Scope caveat. This taxonomy applies to this framework repository. Skills that create issues or PRs on an adopter’s tracker (e.g. security-issue-import, security-issue-fix, issue-fix-workflow) use the adopter’s own label scheme — adopters are free to mirror this taxonomy in their own repo but are not required to.

Label dimensions

The repository’s labels fall into four orthogonal dimensions. An issue or PR typically carries one label from each dimension that applies.

1. family:* — subject

What part of the framework does this touch?

2. capability — two axes (skills vs tools)

Per RFC-AI-0005, “capability” is two orthogonal vocabularies, one per entity. A skill carries one or more skill capabilities (capability:*); a tool carries one or more tool capabilities (contract:* or substrate:*). List all that apply; do not pick a single “primary”.

Axis 1 — skill capability (capability:*) — the workflow-lifecycle phase a skill performs:

Axis 2 — tool capability (contract:* / substrate:*) — the interface a tool/adapter provides. contract:<name> implements a capability contract under tools/<contract>/; substrate:<name> is framework substrate:

| contract:mail-archive | contract | Mailing-list / forum archive reads. | | contract:mail-source | contract | Inbound-mail ingestion (mbox / IMAP / …). | | contract:mail-create | contract | Outbound mail composition. Always produces an editable draft; sending is a separate human-approved step on that draft (draft mode = default and the only mode implemented today; send mode declared but unimplemented — no autonomous send). | | contract:cve-authority | contract | CVE allocation / record management / publication. | | contract:report-relay | contract | Inbound security-report relay detection. | | contract:scan-format | contract | Security-scanner report parsing. | | contract:project-metadata | contract | Governance rosters / people / releases. | | substrate:analytics | substrate | Read-only metrics / dashboards / renderers. | | substrate:sandbox | substrate | Agent isolation, egress control, settings audit. | | substrate:action-guard | substrate | Deterministic pre-tool-use command guards. | | substrate:privacy | substrate | PII redaction / approved-LLM gating. | | substrate:framework-dev | substrate | Build / validate / eval the framework itself. |

Coverage qualifiers

Some tool READMEs may declare a Coverage: qualifier next to a capability when the tool intentionally implements only part of a contract.

partial-read-only means the tool implements a read-only subset of named contract operations, but does not satisfy the complete contract and must not be advertised as a complete/selectable backend.

Both capability axes are orthogonal to family:*. A single query can answer “how is our triage stack doing across PR + issue + security?” by filtering on capability:triage alone, without enumerating per-area queries.

Agent-harness support (substrate tools only). A substrate tool that integrates with the agent runtime (a hook, a settings file, a launcher) declares a **Harness:** field naming the harness(es) it supports, or agnostic when it depends on none. This is the agent-harness axis of LLM-integration neutrality and is scored by tools/vendor-neutrality-score — distinct from a tool’s **Runtime:** field, which is its execution environment (e.g. “Python stdlib”). The recognised harnesses are: Claude Code, Codex, Cursor, Gemini CLI, Copilot, OpenCode, Kiro. A tool is harness-neutral when it is agnostic or supports two or more harnesses.

3. kind:* — change type (pre-existing)

4. mode:* — handling mode (pre-existing)

Standalone labels

marketing (branding artefacts), dependencies (dependency-update PRs), python:uv (Python uv-managed code), plus the default GitHub labels (bug, enhancement, documentation, good first issue, etc.).

Capability to skill map

Capabilities for every skill currently in .claude/skills/. Skills with two values (separated by +) carry both labels.

Capability to tool map

Tools under tools/. A tool’s capability is the interface it provides; a tool may carry more than one value (separated by +) when it implements multiple contracts (e.g. tools/gmail provides both mail-source and mail-create).

A tool’s capability is the interface it provides, not which skills happen to consume it (RFC-AI-0005). tools/github provides the contract:tracker interface; tools/cve-tool-vulnogram provides contract:cve-authority; tools/privacy-llm is substrate:privacy. Use a contract:<name> value when the tool implements a capability contract under tools/<contract>/, and a substrate:<name> value for framework substrate. A tool may carry more than one (rare — tools/gmail is the only one today).

MCP servers, classified by capability

Several tools wrap a Model Context Protocol (MCP) server as their concrete backend. An MCP server is not a separate axis — it is classified by the capability its wrapping tool provides; the MCP is just the transport, interchangeable with a CLI or REST backend behind the same contract. A skill never names an MCP server — it targets the capability, and the tool routes to whichever backend the adopter wired in. The framework consumes four:

Non-MCP backends fulfil the same contracts: JIRA is reached over REST and gh is the CLI fallback, both contract:tracker. See docs/prerequisites.md for connection setup.

The rule

When you create any of the following on this repository, declare the capability:

A GitHub issue

Apply at least one family:* AND one capability label — a skill capability (capability:*) for skill work, a tool capability (contract:* / substrate:*) for tool work. If the issue genuinely spans capabilities, apply all that apply.

A pull request

Same: family:* AND the matching capability. Match the capability the change is implementing, not the file paths it happens to touch. A PR that adjusts the validator config to support a new triage rule is capability:triage (the change’s purpose), not substrate:framework-dev (the file it edited).

A new tool under tools/

Declare the tool’s capability in the first paragraph of its README using the line:

**Capability:** contract:NAME

…or substrate:NAME for framework substrate. If the tool serves more than one, list them (contract:a + substrate:b). Pick the contract:<name> that matches the capability contract the tool implements, or the substrate:<name> kind that fits.

A new skill under .claude/skills/

Declare the capability in the skill’s frontmatter:

---
name: my-new-skill
description: |
  ...
capability: capability:NAME
---

The write-skill skill prompts for this on every new-skill scaffold.

A new doc under docs/

Capability-specific docs (e.g. a guide for a single skill family) should link to this page and name the capability in their first paragraph. Cross-cutting docs (MISSION.md, top-level READMEs) need no capability marker.

Why this exists

The original family:* labels split issues by subject — useful for “what part of the codebase is this?” but unable to answer “what kind of thing is this?”. The capability:* dimension fills that gap and is orthogonal: a triage-rule change in PR management (family:pr-management + capability:triage) and a triage-rule change in security (family:security + capability:triage) become trivially findable as a cohort even though they live in different families.

Capability is also a forcing function for skill design: if a new skill doesn’t fit any of the ten skill-capability buckets cleanly, that’s a signal worth inspecting before the skill ships.