ADR-0024: Writers as skills, reviewers as agents for governance artifacts

Status: accepted | Date: 2026-02-11

References: ADR-0023

Context

Context

govctl manages three governance artifact types — RFCs, ADRs, and work items. We need to add AI-assisted capabilities for both creating (writing) and reviewing these artifacts.

Per ADR-0023, the assets/ directory is organized into commands/, skills/, and agents/ subdirectories. Skills and agents are synced to .claude/skills/ and .claude/agents/ respectively.

Problem Statement

Each artifact type needs writing guidance (structure, conventions, quality patterns) and review criteria (completeness checks, quality gates). The question: should each capability be a skill (augments the main agent inline) or an agent (runs as isolated subagent with its own system prompt)?

Key Distinction

• Skills run in the main agent’s context. They have full access to the conversation and codebase. They augment what the main agent knows.
• Agents run in isolated contexts with custom system prompts. They receive delegated tasks and return results. They have no access to the main conversation.

Constraints

• Skills MUST be <250 lines per SKILL.md (progressive disclosure via references/)
• Agents MUST have focused system prompts
• Each capability should follow “one skill, one capability” principle
• The existing /discuss and /gov commands orchestrate workflows that need writing knowledge

Decision

Decision

Writers are skills. Reviewers and auditors are agents. Seven items total:

Skills (in assets/skills/)

Agents (in assets/agents/)

Rationale

1. Writers need conversation context. An RFC writer must know why the user is creating the RFC — what problem, what constraints, what existing artifacts relate. Skills run inline and have full context.

2. Reviewers benefit from cognitive isolation. When the main agent writes an artifact and then reviews it, confirmation bias is unavoidable. An isolated review agent has no memory of authoring — it evaluates purely on quality criteria.

3. Compliance checking is auditing, not writing. The compliance-checker agent cross-references source code against normative RFC clauses (MUST/MUST NOT) and ADR decisions. It is distinct from artifact reviewers — those check if an artifact is well-written, this checks if code follows what artifacts specify. Isolation ensures no “I wrote this code so it must conform” bias.

4. Seven separate, not consolidated. Each capability is genuinely different. Each stays well under 250 lines. The ~15% shared knowledge (govctl commands, [[ref]] syntax) is 3-5 lines of duplication — not worth coupling distinct capabilities to eliminate.

Integration

• /discuss and /gov commands will reference writer skills for quality guidance
• Review agents can be invoked at quality gates (e.g., after drafting, before finalization)
• compliance-checker can be invoked during /gov Phase 4 (testing) or on demand
• sync-assets.sh already syncs both skills/ and agents/ directories

Consequences

Consequences

Positive

• Writers augment the main agent with domain knowledge while preserving conversation context
• Reviewers provide unbiased quality checks through cognitive isolation
• Compliance checker catches spec violations that govctl check cannot (it validates references exist; the agent validates semantic conformance)
• Seven focused items follow “one skill, one capability” — each stays under 250 lines
• Future artifact types get their own skill + agent pair without touching existing files
• sync-assets.sh already supports the directory structure (ADR-0023)

Negative

• 7 files to maintain (mitigation: each is small and focused, changes are rare)
• ~15% knowledge duplication across items (mitigation: 3-5 lines per file, not worth abstracting)
• Review/audit agents lack conversation context (mitigation: they evaluate on merit, which is the point)
• Compliance checking is inherently imprecise — agent may flag false positives (mitigation: output is advisory, not blocking)

Neutral

• Existing /discuss and /gov commands continue to work unchanged initially; skills/agents integration is additive
• govctl check continues to handle structural validation; compliance-checker handles semantic validation — complementary, not competing

Alternatives Considered

All skills: Make both writers and reviewers skills. Rejected: reviewers lose cognitive isolation, confirmation bias when main agent reviews its own work.

All agents: Make both writers and reviewers agents. Rejected: writers lose conversation context, cannot access why the user is creating the artifact.

4 consolidated items (governance-writer + wi-writer, governance-reviewer + wi-reviewer): Rejected: RFC and ADR capabilities are genuinely different, merging creates a skill that branches on artifact type — special cases we want to eliminate.

2 consolidated items (one writer, one reviewer): Rejected: work items differ fundamentally from RFCs/ADRs, no shared domain knowledge worth coupling.