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 — architecture diagrams as separate .puml files, never inlined
• 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

One mandatory exception: Section 1.2 (Quality Goals) must exist before any other architecture work begins.

---

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

Use the built-in $skill-installer inside Codex and provide the repository URL, or install for your user account:

# User-wide (available in all your projects)
git clone https://github.com/MSiccDev/arc42-toolkit.git ~/.codex/skills/arc42-toolkit

# Project-wide (checked into the repo)
git clone https://github.com/MSiccDev/arc42-toolkit.git .codex/skills/arc42-toolkit

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 / Codex	Reference skills/arc42-section-01/SKILL.md in context

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