ADR 018: Agentic Documentation Standard v1.1.0

ADR-018: Agentic Documentation Standard v1.1.0

Status: Accepted Date: 2025-12-22 Deciders: Hal Casteel, CODITECT Core Team Categories: Standards, Documentation, Components, MoE, Quality Assurance

Context

The Consistency Problem

CODITECT has grown to 1,874 components across 7 types:

130 Agents
136 Commands
186 Skills
227 Scripts
41 Hooks
5 Prompts
1,149 Workflows

Critical Issues Identified:

Inconsistent Frontmatter: Only ~60% of docs have YAML frontmatter
Variable Agent Formats: Some agents use frontmatter, others don't
MoE Pattern Fragmentation: Analysts, judges, orchestrators lack unified structure
No Validation Tooling: Conformance is not enforced
Discovery Impairment: Agents cannot efficiently discover component capabilities

The AI-First Imperative

Modern AI agents (Claude, GPT-4, etc.) process component documentation to:

Discover available capabilities
Select appropriate tools/agents for tasks
Compose multi-agent workflows
Validate outputs against specifications

Without standardized frontmatter:

Token waste: Full document parsing vs. summary extraction
Discovery failures: Agents miss capabilities
Composition errors: Wrong agent selection
QA gaps: No machine-readable validation criteria

Alignment with ADR-017

ADR-017 adopted the Agent Skills Framework requiring:

3-Level Progressive Disclosure (20 → 150 → 4000 tokens)
A2A Protocol parity
Composable agent + skills architecture

This ADR extends those principles to all component types with machine-readable frontmatter.

Decision

Adopt the Agentic Documentation Standard v1.1.0 requiring:

Mandatory YAML frontmatter for all components
Type-specific schemas for each component category
MoE role classification for agents
Validation tooling with CI enforcement
Progressive disclosure support via frontmatter levels

Specification

1. Universal Frontmatter Schema (Required Fields)

All components MUST include these fields:

---
# IDENTITY (Required)
title: "Human-Readable Component Name"
component_type: agent | command | skill | script | hook | prompt | workflow | guide | reference
version: "1.0.0"

# CLASSIFICATION (Required)
audience: customer | contributor | both
status: draft | experimental | stable | production | deprecated

# DISCOVERY (Required)
summary: "One-line description (max 100 chars)"
keywords: [keyword1, keyword2, keyword3]

# METRICS (Required for production)
tokens: ~NNNN  # Estimated token count for full document
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

2. Agent-Specific Schema

Agents MUST include additional fields:

---
# ... Universal fields ...

# AGENT IDENTITY
agent_type: specialist | analyst | judge | orchestrator | reviewer | generator
domain: [security, development, qa, devops, documentation, research]

# MoE CLASSIFICATION
moe_role: analyst | judge | orchestrator | specialist | none
moe_capabilities:
  - capability_1
  - capability_2

# INVOCATION
invocation_pattern: "Task(subagent_type='agent-name', prompt='...')"
requires_context: true | false

# CAPABILITIES (Progressive Disclosure)
capabilities:
  level_1: "20-token summary"
  level_2: "150-token description with examples"
  level_3: "Full capability documentation (reference body)"

# INPUTS/OUTPUTS
inputs:
  - name: input_name
    type: string | file | context
    required: true | false
outputs:
  - name: output_name
    type: string | file | artifact

# QUALITY
quality_score: 0-100
last_reviewed: YYYY-MM-DD
---

3. Command-Specific Schema

---
# ... Universal fields ...

# COMMAND IDENTITY
command_name: "/command-name"
aliases: ["/alias1", "/alias2"]

# INVOCATION
usage: "/command-name [options] <arguments>"
examples:
  - command: "/command-name --flag value"
    description: "Example description"

# PARAMETERS
parameters:
  - name: param_name
    type: string | boolean | number | file
    required: true | false
    default: "default_value"
    description: "Parameter description"

# BEHAVIOR
requires_confirmation: true | false
modifies_files: true | false
network_access: true | false
---

4. Skill-Specific Schema

---
# ... Universal fields ...

# SKILL IDENTITY
skill_name: "skill-name"
skill_category: pattern | framework | automation | integration

# PROGRESSIVE DISCLOSURE (per ADR-017)
levels:
  card: "20-token skill card"
  summary: "150-token summary"
  full: "Reference body for full content"

# APPLICABILITY
when_to_use: "Description of use cases"
when_not_to_use: "Anti-patterns and limitations"

# COMPOSITION
composes_with: [skill-1, skill-2]
requires: [dependency-1]
---

5. Script-Specific Schema

---
# ... Universal fields ...

# SCRIPT IDENTITY
script_name: "script-name.py"
language: python | bash | javascript
executable: true | false

# INVOCATION
usage: "python3 scripts/script-name.py [options]"
cli_options:
  - flag: "--option"
    description: "Option description"

# DEPENDENCIES
python_version: "3.10+"
dependencies: [package1, package2]

# BEHAVIOR
modifies_files: true | false
network_access: true | false
requires_auth: true | false

# TESTING
test_script: "scripts/test-script-name.py"
test_coverage: 0-100
---

6. Documentation-Specific Schema

---
# ... Universal fields ...

# DOCUMENT IDENTITY
doc_type: guide | reference | tutorial | spec | adr

# READING GUIDANCE
when_to_read: "When this document is useful"
prerequisites: [doc-1, doc-2]
next_steps: [doc-3, doc-4]

# CONTENT METRICS
tokens: ~NNNN
reading_time: "X minutes"
---

7. MoE Role Definitions

Analyst Agents

moe_role: analyst
moe_capabilities:
  - deep_analysis
  - pattern_recognition
  - evidence_gathering
  - uncertainty_quantification
analysis_domains: [code, security, architecture, performance]
output_format: structured_analysis

Judge Agents

moe_role: judge
moe_capabilities:
  - evaluation
  - scoring
  - verdict_generation
  - consensus_building
judging_criteria: [correctness, completeness, quality, security]
scoring_scale: 0-100
verdict_types: [pass, fail, conditional]

Orchestrator Agents

moe_role: orchestrator
moe_capabilities:
  - task_decomposition
  - agent_selection
  - workflow_coordination
  - result_aggregation
orchestration_patterns: [sequential, parallel, moe_panel]
max_concurrent_agents: N

Validation

Required Tooling

Create scripts/validate-component-frontmatter.py:

#!/usr/bin/env python3
"""Validate component frontmatter conformance."""

REQUIRED_FIELDS = {
    'all': ['title', 'component_type', 'version', 'audience', 'status',
            'summary', 'keywords', 'tokens', 'created', 'updated'],
    'agent': ['agent_type', 'domain', 'moe_role', 'invocation_pattern'],
    'command': ['command_name', 'usage', 'parameters'],
    'skill': ['skill_name', 'skill_category', 'when_to_use'],
    'script': ['script_name', 'language', 'usage'],
    'guide': ['doc_type', 'when_to_read'],
    'reference': ['doc_type']
}

CI Integration

Add to .github/workflows/validate.yml:

- name: Validate Component Frontmatter
  run: python3 scripts/validate-component-frontmatter.py --strict

Conformance Levels

Level	Description	Requirement
L0	No frontmatter	FAIL - Block merge
L1	Universal fields only	WARN - Needs improvement
L2	Type-specific fields	PASS - Acceptable
L3	Full schema + MoE	PASS - Exemplary

Migration Plan

Phase 1: Tooling (Week 1)

Create validation script
Add CI workflow
Create frontmatter templates

Phase 2: Critical Path (Week 2)

Update all agents (130) to L2+
Update all commands (136) to L2+
Update docs/guides (14) to L2+

Phase 3: Full Coverage (Weeks 3-4)

Update skills (186) to L2+
Update scripts (227) to L2+
Update remaining components

Phase 4: Enforcement (Week 5)

Enable strict CI validation
Block non-conforming merges
Generate conformance report

Consequences

Positive

Machine-readable discovery: Agents can parse frontmatter efficiently
Consistent UX: Users see uniform documentation structure
Quality gates: Non-conforming components blocked from merge
MoE optimization: Role-based agent selection improves
Token efficiency: Progressive disclosure reduces context usage

Negative

Migration effort: 1,874 components need review
Maintenance overhead: Frontmatter must be kept current
Learning curve: Contributors must learn schema

Mitigations

Automated migration scripts for bulk updates
Templates for new component creation
Validation runs on save (IDE integration)

Compliance

This ADR is compliant with:

ADR-017: Agent Skills Framework (progressive disclosure)
A2A Protocol: Agent Cards format alignment
MCP Standard: Tool capability declaration patterns

References

ADR-017: Agent Skills Framework Adoption
ADR-014: Component Capability Schema
Anthropic Agent Skills Framework specification
Google A2A Protocol Agent Cards specification

Changelog

Version	Date	Changes
1.1.0	2025-12-22	Initial ADR

Author: CODITECT Core Team Framework: CODITECT v1.7.2 Standard: Agentic Documentation Standard v1.1.0

Context​

The Consistency Problem​

The AI-First Imperative​

Alignment with ADR-017​

Decision​

Specification​

1. Universal Frontmatter Schema (Required Fields)​

2. Agent-Specific Schema​

3. Command-Specific Schema​

4. Skill-Specific Schema​

5. Script-Specific Schema​

6. Documentation-Specific Schema​

7. MoE Role Definitions​

Analyst Agents​

Judge Agents​

Orchestrator Agents​

Validation​

Required Tooling​

CI Integration​

Conformance Levels​

Migration Plan​

Phase 1: Tooling (Week 1)​

Phase 2: Critical Path (Week 2)​

Phase 3: Full Coverage (Weeks 3-4)​

Phase 4: Enforcement (Week 5)​

Consequences​

Positive​

Negative​

Mitigations​

Compliance​

References​

Changelog​