arc42-toolkit

arc42 Toolkit

Provider-agnostic arc42 documentation skills for AI coding assistants — Claude Code, GitHub Copilot, Cursor, Codex, and any LLM tool that reads markdown.

Create professional software architecture documentation through guided, interactive AI conversations. Each of the 12 arc42 sections is covered by a dedicated skill that asks the right questions first, generates a structured draft, then iterates until you are satisfied.

---

Features

• 14 interactive skills — one per arc42 section, plus quality review and consistency linting
• Provider-agnostic — works with Claude Code, GitHub Copilot, Cursor, Codex, and any LLM tool
• Ask-first approach — every skill gathers your project details before generating anything
• Three depth levels — LEAN, ESSENTIAL, or THOROUGH, chosen per section based on your needs
• C4 PlantUML diagrams — toolkit default notation for architecture diagrams, stored as separate .puml files, never inlined (official arc42 is format-agnostic — any notation works)
• Q42 quality model — 492 quality attributes across 8 properties integrated into relevant skills
• Cross-section consistency — skills check related sections and flag contradictions
• Automated consistency linting — catch IF-xx, QS-xx, ADR, and RISK-xx mismatches before they accumulate
• Standards-based — grounded in arc42.org, docs.arc42.org, and quality.arc42.org

---

What is arc42?

arc42 is the proven, open-source template for software architecture documentation created by Dr. Gernot Starke and Dr. Peter Hruschka. Used in thousands of projects worldwide, it provides a pragmatic, tool-agnostic approach.

Core philosophy:

• Document economically but continuously
• "Painless documentation" — only what stakeholders truly need
• All sections are optional — use what fits your project
• Suitable for agile and traditional environments

Toolkit recommendation: Start with Section 1.2 (Quality Goals) — it anchors all architectural decisions that follow.

---

Quick Start

1. Install the toolkit

Claude Code

claude plugin install MSiccDev/arc42-toolkit

Skills are available as slash commands immediately.

GitHub Copilot CLI

copilot plugin install arc42-toolkit

If the arc42-toolkit marketplace is not yet registered, add it first:

copilot plugin marketplace add MSiccDev/arc42-toolkit
copilot plugin install arc42-toolkit

OpenAI Codex

Register the repository as a marketplace source once, then install the plugin from the Codex app:

codex plugin marketplace add MSiccDev/arc42-toolkit --ref main

After registration, restart Codex, open Plugins, choose the arc42 Toolkit marketplace, and install arc42-toolkit.

If you open this repository directly in Codex, the repo-local .agents/skills/ symlinks also expose the skills without plugin installation.

Cursor, Copilot Chat, and other tools

Clone or copy into your project:

git clone https://github.com/MSiccDev/arc42-toolkit.git

Or copy AGENTS.md, the skills/ directory, and the .agents/ symlink into your existing project.

Windows / ZIP installs: If symlinks are unavailable, create a directory junction instead: mklink /J .agents skills (Windows CMD) — or simply copy the skills/ directory to .agents/.

2. Start with Section 1

Invoke the skill for your AI tool:

Tool	Command
Claude Code	/arc42-section-01
GitHub Copilot Chat	#arc42-section-01
Cursor	Reference skills/arc42-section-01/SKILL.md in context
Codex	Use $arc42-section-01 after installing the plugin, or open the repo directly

3. Answer the questions

The skill asks about your project — requirements, stakeholders, quality goals. No generation happens until you have answered.

4. Review and iterate

The skill produces a draft, runs a built-in quality checklist, and asks what you want to refine. Repeat until satisfied.

5. Continue section by section

Use the same pattern for each section you need. The /arc42-review skill validates any section or the full document at any time.

---

Repository Structure