feat(taxonomy): split capability into skill + tool axes (RFC-AI-0005)

[potiuk]

What

Reviews the capability taxonomy and fixes the drift spotted in review:
one capability vocabulary was doing two incompatible jobs. It named
a workflow-lifecycle phase (right for skills) but was also stamped on
tools, collapsing 24 of 33 tools into a meaningless capability:setup
and leaving four capabilities (triage/review/fix/reassess) with
zero tools. Implements RFC-AI-0005 (added here).

Two orthogonal axes

• Skill capability capability:* — the lifecycle phase: triage,
  review, fix, intake, reconciliation, resolve, reassess,
  stats, and setup split into platform (the setup-* family)
  and authoring (write-skill, optimize-skill).
• Tool capability — the interface a tool provides:
  contract:<name> when it implements a capability contract under
  tools/<contract>/ (tracker, source-control, mail-archive,
  mail-source, mail-draft, cve-authority, report-relay,
  scan-format, project-metadata), or substrate:<name>
  (analytics, sandbox, action-guard, privacy, framework-dev).
  This kills the capability:setup grab-bag and makes a tool's
  capability equal the contract it implements.

A skill consumes contracts; a tool provides one — the edge the old
single axis couldn't express.

Scope of the change (49 files)

• docs/rfcs/RFC-AI-0005.md — the taxonomy RFC, documenting all
  dimensions (area / capability [two-axis] / kind / mode / organization /
  standalone) + the migration.
• skill-and-tool-validator — ALLOWED_CAPABILITIES → per-axis
  SKILL_CAPABILITIES + TOOL_CAPABILITIES; skill frontmatter validated
  on Axis 1, tool README on Axis 2; token regex widened for
  contract:/substrate: + hyphens; tests updated.
• All 33 tools re-labelled to contract:/substrate: values.
• 10 capability:setup skills re-labelled platform/authoring.
• docs/labels-and-capabilities.md rewritten as two capability
  tables + two maps; AGENTS.md, tools/AGENTS.md,
  docs/adapters/authoring.md, and the write-skill scaffold updated.

Verification

skill-and-tool-validate EXIT 0 (capability-sync passes against the new
two-table maps); validator pytest + mypy green; doctoc / markdownlint /
lychee / placeholder all green.

🤖 Generated with Claude Code

[potiuk]

Hey @andreahlert -> I want to get it merged soon to be able to make last final cleanup of our site. It does not mean that we will not dicuss taxonomy, it's more to get a clean state that we can discuss about it. I have found that by iterating on the website and trying to make it more "user approachable", i was able to modify some of the taxonomy stuff - modes/ capabilities and .... looking at the website - they make awfully lot of sense when cleaned up / organized. And it's way easier to "sell" concept of Magpie when this is cleaned up.

But - it does not mean that the discussion is closed - I would say having a nice, well organized structure and "cleaned up/reviewed refactored taxonomy" will allow us to have a way more meaningful discussion on Taxonomy - approachable by more people, because it wiil not be abstract, but based on something tangible and reasoning about it will be easier (I already found it way easier when I worked on the site).

[justinmclean]

It's a good idea to run the review skill over things before merging.

Code quality / correctness — major

skills/write-skill/SKILL.md (~line 376) — the worked multi-capability example now reads:

setup-isolated-setup-doctor does capability:authoring + capability:reassess

but this same PR relabels that skill's frontmatter to capability:platform + capability:reassess. authoring is reserved for skills that author other skills (write-skill, optimize-skill); the setup-doctor is a platform skill. This is a bad mechanical replacement — setup→authoring where it should have been setup→platform. It matters because it's the example inside the canonical skill-authoring skill, so a contributor copying it mislabels their skill, and the validator won't catch it (it's prose in a skill body, not frontmatter). Fix: capability:platform + capability:reassess.

Code quality / consistency — minor

Stale "nine buckets" count. Splitting setup into platform + authoring makes ten skill capabilities, but three references the PR leaves untouched still say nine: docs/labels-and-capabilities.md (~line 324, "doesn't fit any of the nine buckets cleanly"), and skills/write-skill/SKILL.md (~line 378 "any of the nine buckets at all" and ~line 403 "nine capability buckets"). The PR creates the inconsistency by doing the split, so these should move to "ten" in the same change.
Categories checked, clean

License headers (RFC-AI-0005.md carries the Apache SPDX header; .md exempt regardless), third-party license, compiled artifacts, and the security model (taxonomy-only change, no disclosure-signal or threat-model surface touched) — no findings.

[justinmclean]

Overall this is a good change and the right direction.

The problem it fixes is real. One set of labels was being used for two different things: what a skill does (a step in a workflow) and what a tool is (a piece of plumbing). Those aren't the same kind of thing, so trying to label both the same way pushed most tools into a vague "setup" bucket that didn't tell you anything useful. Splitting them into two separate label systems is the correct fix.

My main concern is the new "substrate" label. Right now, it just means "a tool that doesn't fit one of the named slots," which describes what it isn't, not what it is. It already includes five distinct kinds of tools, and one of them ("framework-dev") covers six tools on its own. There's no rule for what belongs in it or when to add a new type, so over time, it could turn into the same junk drawer the old "setup" label was. Before that happens, it would help to write down what "substrate" is actually for and a simple rule for adding new ones.

Two smaller things. There are now three label prefixes a reader has to keep straight, and a reader has to know which one goes with skills and which goes with tools. That confusion is what probably caused the one labeling mistake I flagged in the review above.

[potiuk]

Absolutely - I plan to start discussion about it today - when i complete the website refresh with all the taxonomy in .. Those are "quick wins" to make our website "complete" and surface some of the things like "Vendor Neutrality" and how it is achieved, and "Organisation agnostic" approach - both important to have "up" on our website with consitent (even if not final) taxonomy once we get announcements. I think I am close to get a landing page and structure that is pretty straightforward and not too confusing what Magpie is and who can use it for what :).

[potiuk]

#645 fix