Specification: Agentic Docs-as-Code Architecture Pipeline

Overview

This specification establishes an automated, agent-driven software architecture documentation ecosystem. The framework integrates strict structural standards, controlled natural language rules, and autonomous AI maintenance patterns into a unified, version-controlled pipeline.

---

Core Pillars

1. Structural Standard (arc42 & C4 Model)

• System Decomposition: All documentation follows the hierarchical arc42 architecture template, ensuring complete coverage from business goals down to deployment views and quality requirements.
• Visualizations: The C4 model (Context, Containers, Component, Code) is embedded directly into source files using Mermaid.js or Structurizr DSL to maintain living visual artifacts alongside text.

2. Linguistic Standard (ASD-STE100)

• Controlled Vocabulary: All documentation must adhere to ASD-STE100 (Simplified Technical English) principles.
• Clarity Constraints: Sentences remain concise, active voice is strictly enforced, and synonyms are eliminated to ensure absolute zero ambiguity for both human readers and machine interpreters.

3. Agentic Maintenance Pattern (Karpathy-Style Workflow)

• Living Codebase Model: Documentation is treated as a compiled artifact maintained primarily by AI coding agents rather than manual wiki updates.
• Repository Governance: A root-level configuration file (AGENTS.md or CLAUDE.md) acts as the compiler rulebook, dictating formatting, terminology, and structural constraints to any interacting AI agent.

---

Operational Workflow

• Storage: Plain-text documentation sources (AsciiDoc or Markdown) reside in a version-controlled repository structured according to arc42 layouts.
• Execution: Architectural changes trigger targeted agentic instructions. Agents read repository guardrails, update affected multi-file documentation blocks, log corresponding Architecture Decision Records (ADRs), and refresh C4 diagrams in a single pass.
• Publishing: CI/CD automation compiles the source files into a static architecture portal on every commit.

Comments

[Karthi Mahadevan]

Or a simple structure

Repository Initialization Protocol

This protocol establishes the agentic documentation setup within a single repository from scratch, omitting pipeline automation details.

---

Phase 1: Repository Structure Setup

The directory layout is established and the governing configuration file is placed at the root of the repository.

1. Directory Tree

/root-repository
├── AGENTS.md                          <-- Governing agent guardrails
└── docs/
    ├── 01_introduction_and_goals.adoc
    ├── 02_architecture_constraints.adoc
    ├── 03_system_scope_and_context.adoc   <-- Contains initial C4 Context diagram
    ├── 04_solution_strategy.adoc
    ├── 05_building_block_view.adoc        <-- Contains initial C4 Component diagram
    ├── 06_runtime_view.adoc
    ├── 07_deployment_view.adoc
    ├── 08_crosscutting_concepts.adoc
    ├── 09_architecture_decisions.adoc     <-- Baseline ADRs
    ├── 10_quality_requirements.adoc
    ├── 11_risks_and_technical_debt.adoc
    └── 12_glossary.adoc

2. Guardrails File (AGENTS.md)

The rulebook containing ASD-STE100, arc42, and C4 constraints is placed at the repository root to govern any interacting AI agent.

---

Phase 2: Day-One Baseline Generation (Initial Scan)

Because the repository contains existing code but empty documentation files, an initial agentic sweep is executed to generate the baseline documentation.

Initialization Prompt

An AI coding agent (such as Claude Code or an automated terminal runner) is executed within the repository workspace using the following initialization command or prompt:

"Read AGENTS.md. Scan the entire codebase (source files, infrastructure manifests, configuration files, and package dependencies). Perform a comprehensive architectural analysis and populate the empty arc42 documentation files (`docs/01_.adoc through docs/12_.adoc) from scratch. Generate inline C4 Mermaid diagrams in 03_system_scope_and_context.adoc and 05_building_block_view.adoc reflecting the current code state. Document existing architectural decisions in docs/09_architecture_decisions.adoc`. Ensure all generated text strictly complies with ASD-STE100 linguistic constraints."

The agent analyzes the codebase, maps out the architecture, and populates the entire documentation tree in a single session.

[Reid Marlow]

The directory split with arc42 gives an agent clear swimlanes, but the hard operational part is incremental maintenance on routine PRs. If a feature PR touches one service and triggers a broad documentation agent pass across all twelve documents, the model tends to rewrite stylistic phrasing in unchanged files. Mapping specific codebase paths to individual arc42 chapters in the CI trigger keeps the resulting doc diff tight enough that engineers will actually review it.