arc42-docs

name	arc42-docs
description	Use this skill when the user asks to "create architecture documentation", "document the architecture", "arc42", "initialize arc42", "update architecture docs", discusses architecture documentation, or wants to document system design decisions, quality requirements, deployment views, building blocks, or any of the 12 arc42 sections. Also use when the user mentions ADRs (Architecture Decision Records) in the context of arc42.
version	2.0.0

Arc42 Architecture Documentation Skill

Guide for using the arc42-mcp-server MCP server to create and maintain architecture documentation following the proven arc42 template. The server provides 6 tools, supports 11 languages and 2 output formats (AsciiDoc, Markdown).

Prerequisites

The arc42-mcp-server MCP server must be configured and running. See setup instructions for installation and configuration.

---

Workflow: Starting Fresh

1. Load the guide → arc42-workflow-guide — understand the full arc42 structure and what belongs in each section
2. Initialize workspace → arc42-init — creates directory structure with all 12 section files, config.yaml, and README
3. Check status → arc42-status — see current progress, completeness percentage, and which sections need work
4. Generate template → generate-template — get the detailed structure and guidance for a specific section before writing
5. Write content → update-section — write or append content to a section
6. Review content → get-section — read back existing content with metadata (word count, last modified)

Workflow: Existing Documentation

1. Check status → arc42-status — assess current state and identify gaps
2. Read sections → get-section — review what's already documented
3. Generate template → generate-template — understand expected structure for incomplete sections
4. Update sections → update-section — fill gaps or improve existing content

---

Tool Reference

1. arc42-workflow-guide

Load the comprehensive arc42 documentation workflow guide. Always call this first when starting a new documentation effort — it explains what information belongs in each section.

Parameter	Type	Required	Default	Description
language	enum	No	"EN"	Language code: EN, DE, ES, FR, IT, NL, PT, RU, CZ, UKR, ZH
format	enum	No	"asciidoc"	Output format: asciidoc (or adoc), markdown (or md)

Returns: Complete workflow guide text with section explanations, available languages, supported formats, and workspace root path.

2. arc42-init

Initialize the arc42 documentation workspace. Creates arc42-docs/ directory with all 12 section files, config.yaml, README, and a main documentation file.

Parameter	Type	Required	Default	Description
projectName	string	Yes	—	Name of the project being documented
language	enum	No	"EN"	Language code (see above)
format	enum	No	"asciidoc"	Output format: asciidoc/adoc or markdown/md
force	boolean	No	false	Force re-initialization even if workspace already exists
targetFolder	string	No	server default	Absolute path to target folder where arc42-docs/ will be created

Returns: Workspace root path, sections created count, config (including arc42 template reference version, date, and commit SHA).

Created structure:

<targetFolder>/arc42-docs/
├── README.md
├── arc42-documentation.adoc (or .md)
├── config.yaml
├── sections/
│   ├── 01_introduction_and_goals.adoc (or .md)
│   ├── 02_architecture_constraints.adoc (or .md)
│   └── ... (all 12 sections)
└── images/

3. arc42-status

Check documentation completion status. Shows per-section progress with word counts, completeness percentages, and overall progress.

Parameter	Type	Required	Default	Description
targetFolder	string	No	server default	Absolute path to folder containing arc42-docs/

Returns: Project name, initialized state, language and format info, arc42 template reference version, per-section status (exists, word count, completeness 0-100%, last modified), and overall completeness percentage.

4. generate-template

Generate a detailed template for a specific section. Always use this before writing content — it provides the expected structure, subsections, and guidance for what information to include.

Parameter	Type	Required	Default	Description
section	enum	Yes	—	Section ID (see section reference below)
language	enum	No	"EN"	Language code
format	enum	No	"asciidoc"	Output format: asciidoc/adoc or markdown/md

Returns: Complete template content with guidance, section metadata (title, description, order), format details.

5. update-section

Write content to a specific section. Format is auto-detected from existing files or config.yaml.

Parameter	Type	Required	Default	Description
section	enum	Yes	—	Section ID (see section reference below)
content	string	Yes	—	The content to write to the section
mode	enum	No	"replace"	"replace" overwrites, "append" adds to existing content
targetFolder	string	No	server default	Absolute path to folder containing arc42-docs/

Returns: Section title, file path, detected format, word count, and write mode used.

Important: Use mode: "append" when adding ADRs (Section 9) or adding incremental content to avoid overwriting existing entries.

6. get-section

Read content from a specific section, including metadata.

Parameter	Type	Required	Default	Description
section	enum	Yes	—	Section ID (see section reference below)
targetFolder	string	No	server default	Absolute path to folder containing arc42-docs/

Returns: Section content, language, format, title, description, and file metadata (path, last modified timestamp, word count, file size in bytes).

---

The 12 Arc42 Sections

#	Section ID	Name	Key Content
1	01_introduction_and_goals	Introduction and Goals	Requirements overview, quality goals, stakeholders
2	02_architecture_constraints	Architecture Constraints	Technical, organizational, and political constraints
3	03_context_and_scope	Context and Scope	Business context, technical context, external interfaces
4	04_solution_strategy	Solution Strategy	Technology decisions, top-level decomposition, quality approaches
5	05_building_block_view	Building Block View	Static decomposition (Level 1, 2, 3) of the system
6	06_runtime_view	Runtime View	Key scenarios, sequence diagrams, process flows
7	07_deployment_view	Deployment View	Infrastructure, deployment diagrams, node mapping
8	08_concepts	Cross-cutting Concepts	Security, persistence, logging, error handling patterns
9	09_architecture_decisions	Architecture Decisions	ADRs with context, decision, status, and consequences
10	10_quality_requirements	Quality Requirements	Quality tree, quality scenarios
11	11_technical_risks	Risks and Technical Debt	Known risks, technical debt items
12	12_glossary	Glossary	Domain terms and definitions

---

Recommended Documentation Order

Start with the most impactful sections. You do NOT need to document all 12 sections sequentially.

Priority	Section	Why
1st	Section 1 — Introduction and Goals	Always start here: establishes scope, quality goals, and stakeholders
2nd	Section 3 — Context and Scope	Define system boundaries and external interfaces early
3rd	Section 4 — Solution Strategy	Capture key technology and design decisions
4th	Section 5 — Building Block View	Document the system's static structure
5th	Section 9 — Architecture Decisions	Record important ADRs while decisions are fresh
Then	Section 2 — Constraints	Document technical/organizational constraints
Then	Sections 6–8 — Runtime, Deployment, Concepts	Fill in dynamic behavior, infrastructure, cross-cutting concerns
Last	Sections 10–12 — Quality, Risks, Glossary	Complete the documentation

---

Behavioral Guidelines

Before Writing Any Section

1. Generate the template first — call generate-template for the section to understand the expected structure and subsections
2. Ask clarifying questions — never assume project details; ask the user about their specific context, technologies, and decisions
3. Check existing content — call get-section to see if there's already content to build upon
4. Respect the configured format — call arc42-status to check whether the project uses AsciiDoc or Markdown, then write content in that format

Content Quality

• Document WHY, not just WHAT — focus on rationale and trade-offs behind decisions
• Include diagrams — use Mermaid or PlantUML syntax for context diagrams, building block views, deployment views, and sequence diagrams
• Be specific — use concrete technology names, version numbers, and measurable quality attributes
• Keep sections focused — each section has a distinct purpose; avoid duplicating information across sections
• Use proper formatting — match the output format (AsciiDoc uses = headings, admonitions with NOTE:, TIP:; Markdown uses # headings)

ADR Best Practices (Section 9)

• Always use mode: "append" when adding new ADRs to avoid overwriting existing ones
• Always call get-section first to read existing ADRs and determine the next ADR number
• Follow a consistent ADR structure: Title with number, Status, Context, Decision, Consequences (positive and negative)

Using Tool Responses

Every tool response includes:

• success — boolean indicating whether the operation succeeded
• message — human-readable summary of what happened
• data — structured response data (varies by tool)
• nextSteps — array of suggested follow-up actions; use these to guide the user on what to do next

---

Multi-Language Support

11 languages are supported. Set the language during arc42-init; it persists in config.yaml and applies to all subsequent operations.

Code	Language	Code	Language
EN	English	PT	Portuguese
DE	German	RU	Russian
ES	Spanish	CZ	Czech
FR	French	UKR	Ukrainian
IT	Italian	ZH	Chinese
NL	Dutch

Multi-Format Support

Format	Aliases	Extension	Best For
AsciiDoc (default)	asciidoc, adoc	.adoc	Professional docs — supports includes, admonitions, cross-references, TOC generation
Markdown	markdown, md	.md	Simplicity — widely supported, GitHub/GitLab rendering

Set the format during arc42-init. The update-section tool auto-detects the format from existing files or config.yaml. Format aliases (md/adoc) are accepted anywhere a format parameter is used.

---

Examples

See references/examples.md for detailed usage examples covering:

• Starting a new project from scratch
• Documenting a specific section (e.g., deployment view)
• Adding Architecture Decision Records (ADRs) with proper append mode
• Documenting cross-cutting concepts
• Multi-language documentation
• Reviewing and improving existing documentation
• Re-initializing an existing workspace