Record an ADR: skills are cut by capability, not by role

[dieterbaier]

Problem

The toolkit cuts its skills by lifecycle capability and verifiable outcome —
architecture-impact, bdd-specification, implement-issue-workflow,
pr-review, convergence-check. It deliberately does not cut them by
persona (planner, coder, reviewer), which is the common alternative in
role-based "software factory" agent architectures.

That is a real architectural decision. It constrains how every future skill is
shaped, and it is currently recorded nowhere. AGENTS.md describes the contract
order, README.md presents capabilities, and the skills embody the cut — but no
artifact says why the cut is capability-oriented, or what was rejected.

Anyone adopting the toolkit next to a role-based agent platform will ask this,
and the answer is currently reconstructed from scratch each time.

Proportionality check (#66)

Applying the decision test from #66 — without this record, would a later
contributor probably make a materially different decision?

• Reversal is costly: every skill would have to be re-cut and every
  cross-skill delegation re-wired.
• It constrains multiple future changes: it decides the shape of every skill
  added from here on.
• It establishes a cross-cutting rule: skills describe work, not workers.
• The rejected alternative is plausible and will recur: role-based agent
  architectures are widespread and organisationally attractive.

All four apply. An ADR is the proportionate record, not prose in AGENTS.md.

Decision to record

Skills are cut by lifecycle capability and verifiable outcome, never by persona.

Roles may legitimately exist as an orchestration layer above the toolkit:
separate agents for planning, implementation and review are a sound runtime
choice, and they bring real benefits — context limitation, permission
limitation, and independence. What they must not have is separate process
truth. A role consumes the canonical skills; it does not own a copy of the
lifecycle.

Options the ADR should compare

1. Capability-cut skills, roles as orchestration above (proposed).
2. Persona-cut skill sets — one skill stack per role.
3. Hybrid with per-role copies of shared process rules.

Criteria worth putting in the Pugh matrix: single source of process truth, drift
cost when the lifecycle changes, skill reusability across tasks, independence of
verification, organisational mappability (option 2 genuinely wins here — a role
maps onto a team, a permission set and an audit trail, and the ADR should say so
rather than pretending the rejected option has no merit), and context cost.

Relationship to ADR-005

ADR-005-engine-independent-skills makes the same shape of argument one level
down: skills stay independent of any one AI engine, and engine specifics live
in adapters. This decision keeps them independent of any one agent persona,
with personas living in an orchestration layer.

Decide whether the new ADR refines ADR-005 or stands beside it, and record only
authoritative outgoing relations (see #1).

Consequences to record

• Independence of verification, which the role cut would have provided for free,
  must be modelled explicitly instead — see Model execution independence as a declared property of gate skills #87 on execution
  independence.
• Adapters stay thin and generated; they route, they do not acquire personas.
• A future role-based consumer of the toolkit is supported, not excluded.

Scope

• One ADR under src/docs/arc42/09-architecture-decisions/, authored with
  skills/adr/SKILL.md.
• status: proposed, reviewed: false — AI-assisted, and not accepted
  architecture truth until the accountable owner reviews it.
• Authoritative outgoing relations only; regenerate the derived views and the
  ADR index.
• Reference the canonical rules rather than restating them.
• Do not restate the decision in AGENTS.md or in the skills; if an operational
  rule falls out of it, that rule belongs in general-semantic-contracts.md
  once, and the ADR links to it.

Relationship to other work

• Model execution independence as a declared property of gate skills #87 — the consequence this ADR creates: independence as a declared execution property.
• Document the instruction model in arc42, and decide what the user level is #33 documents the instruction model in arc42 and would reference this
  decision rather than re-argue it; Diagram the instruction model that applies today #30 draws it.
• Add an ADR proportionality gate to the architecture workflow #66 supplies the proportionality test applied above.
• Relationship Strategy: Authoritative Outgoing Relations Only #1 fixes the relation strategy the ADR's metadata must follow.

Acceptance criteria

• An ADR records the capability-over-persona cut, its drivers, the rejected
  options and their honest trade-offs, including where the persona cut is
  genuinely better.
• The relationship to ADR-005 is decided and recorded as an outgoing
  relation.
• The consequence for independent verification is recorded and linked to
  the companion issue.
• Status is proposed and reviewed: false.
• Metamodel validation, generation and render checks pass; the ADR index
  includes the new decision.
• No duplicated decision text in AGENTS.md, README.md or the skills.

Origin

Raised on 2026-09-04 while comparing this toolkit with a role-based
"software factory" agent architecture. The comparison showed the position is
sound but undocumented, and that the argument has to be made from first
principles every time it comes up.

[dieterbaier]

Correction to the framing in this issue

Found while reviewing the ADR in #88. This issue, and the first draft of
ADR-008, treated "role-based" as one position. It is three, and they are
independent:

Question	What it decides
Cut	On which axis process knowledge is decomposed into units: capability or persona.
Allocation	Which units an executing agent receives: whatever the task needs, or a fixed role-specific subset.
Agent decomposition	How many agents execute one change, with which context and which permissions.

The software factory this issue compares against decomposes agents by role
(planner, coder, reviewer). That is the third question. It does not by itself
say anything about the first — a platform can run role-based agents while its
skills stay capability-shaped.

The problem statement above says the toolkit "deliberately does not cut them by
persona … which is the common alternative in role-based software factory agent
architectures". That sentence attributes a position on the cut to a platform
that may only hold one on agent decomposition. The ADR's first draft carried
the same conflation into its rejected Option 2, which would have made the ADR
easy to dismiss by exactly the readers it has to convince.

What this changes

Not the decision. The cut stays capability-oriented, and the position is if
anything stronger: if a role-based platform only decomposes agents, it is not
an alternative to this toolkit at all — it is a layer above it, and Option 1
already describes that arrangement.

The ADR's framing, fixed in 94c1ee2 on #88: Context now separates the
three questions and states that only the cut is decided; Option 2 is renamed
"Skills cut by persona" and says explicitly that role-based agent platforms do
not necessarily imply it; the Pugh commentary attributes each criterion the
persona cut wins to the axis it comes from — organisational mappability follows
from the cut, independence of verification follows from agent decomposition.

One new obligation, recorded as a consequence rather than a new decision:
an orchestration layer that allocates skills per role has to keep each
allocation closed under skill-to-skill delegation. A role holding
implement-issue-workflow also needs everything that skill mandatorily
references, or the gate wiring from #82 breaks silently inside that role's
context. Whether the toolkit should verify this is an open question in the ADR —
features/skill-wiring.feature already resolves that reference graph, but
nothing reads it from an allocation's point of view.

#87 is unaffected and better motivated. Independence is a property of agent
decomposition, which is precisely the axis a role-based platform already
decides. #87 is how the toolkit can require it without prescribing that
structure.

This issue text is left as written; it records the question as it was asked.

[dieterbaier]

Owner review outcome, and one scope change

The owner reviewed ADR-008 on #88 and settled its three open questions. Recorded
here so the scope change lives in the issue rather than only in the diff.

1. refines ADR-005 confirmed. The relation stays as drafted; the review
note asking whether it should be a sibling relation is removed.

2. The independence consequence becomes a risk artifact — this is the scope
change. This issue scoped the work to one ADR and left the question open. The
owner's answer: in a cross-functional team the missing independence is exactly
an exposure to accept and watch, not a reason to separate roles. So the change
now also adds:

• R-007-gate-results-lack-independence — likelihood high, impact medium,
  priority medium. It refines R-001 (narrowing it from artifacts in general to
  gate results, where the mitigation is execution independence rather than a
  lifecycle status marker) and affects QS-004.
• ADR-008 gains an introduces_risk relation to it, and the consequence under
  Negative now references it.
• DOC-11000 registers it, following the pattern used for R-001 … R-006.

R-007 carries the evidence observed on this branch: the provisional Convergence
Check reported converged, and the framing defect fixed in 94c1ee2 was found by
a human reading the ADR, not by the gate.

3. The role-to-skill binding stays outside the toolkit. ADR-008 now says so
in the Decision and shows a short illustration marked explicitly as not a
toolkit format. The illustration allocates an entry skill per role rather
than a list of skills, so everything that skill mandatorily delegates to comes
with it and the allocation is closed under delegation by construction.

That also answers the third question, about whether the toolkit should publish a
machine-readable delegation closure: it should not. An allocation by entry point
inherits the closure, so stating the requirement is enough. The obligation now
recorded under Negative applies only to a platform that chooses to enumerate a
fixed skill list instead.

One question stays open in the ADR: whether that illustration should grow into a
maintained example in this repository.

[dieterbaier]

Second scope change: the ADR is accepted, and the last open question is closed

Recorded here after an independent Convergence Check on #88 found both of these
present in the artifacts but absent from this issue. The acceptance criteria
below are left as written; this comment supersedes two of them.

1. Lifecycle state. This issue's acceptance criteria say:

Status is proposed and reviewed: false.

That no longer holds, by owner decision during review. ADR-008 is
status: accepted, reviewed: true, with the body status Accepted (derived) —
the wording general-semantic-contracts.md reserves for a decision whose
rationale was AI-drafted and whose acceptance is human. All four of its impact
relations were accepted with it.

ADR-008 is currently the only accepted ADR in the repository; ADR-001 … ADR-007
remain proposed / reviewed: false. R-007 also stays proposed: an accepted
decision may introduce a risk whose rating is still under analysis.

2. The last open question is closed. The previous comment ended with:

One question stays open in the ADR: whether that illustration should grow into
a maintained example in this repository.

Answered: no. The decision holds without a maintained example, and an
orchestration layer needs nothing from this repository beyond the skill names it
already reads. ADR-008 now records Open Questions: * None.

Reusing the illustration outside the architecture documentation — where the
audience for this decision actually is — became #91 instead.

Two findings from the same check still need a decision

Both are consequences of the acceptance above, and neither is settled:

• TD-002 in doc-11002-technical-debt.adoc states that the decisions chapter
  "contains proposed ADR files, but those ADRs are not yet human-reviewed or
  accepted". One now is.
• Q-ARCH-006 in doc-005-questions-and-answers.adoc still answers "this is
  not really clear … we will decide", while ADR-008 states that it answers one
  instance of that question.

Left open here rather than fixed, because whether either should be touched is a
judgement the Convergence Check explicitly puts to a human: collateral updates to
unaffected documents are a finding, not tidiness.

[dieterbaier]

Decision on the two open findings: both are fixed

The previous comment left TD-002 and Q-ARCH-006 as findings needing a human
decision. The decision was made: fix both. Recorded here because the branch
already carries the edits, and a scope change belongs in the issue rather than
only in the diff.

TD-002 (doc-11002-technical-debt.adoc) is scoped rather than deleted. It
said the decisions chapter holds proposed ADRs "not yet human-reviewed or
accepted"; one now is, so the sentence had become false while the debt behind it
is unchanged. It now names ADR-008 as accepted and points the debt at the
remainder, and the action column asks for the remaining proposed ADRs.

Q-ARCH-006 (doc-005-questions-and-answers.adoc) keeps its original answer
unchanged and gains a second paragraph recording the one instance that is
settled, with an xref to ADR-008. The general question stays open. Leaving it
untouched would have contradicted ADR-008, which states that it answers an
instance of exactly this question.

Neither edit is collateral tidying: both documents are ones the accepted decision
points at, and both asserted something the repository no longer supports.

One further correction

DOC-09000's documents relation for ADR-008 carried the rationale "The chapter
links to this proposed ADR detail page", copied from the ADR-001 … ADR-007
pattern. ADR-008 is accepted, and the generator renders that string verbatim into
the chapter's impact matrix, so a derived view showed the wrong lifecycle state.
The wording is now status-neutral. The other seven keep theirs, which remains
accurate for them — the pattern will need the same treatment whenever another
ADR is accepted.

All of the above was found by an independent Convergence Check run from a fresh
context, not by the authoring one.