---
name: mcaf-architecture-overview
description: "Create or update `docs/Architecture.md` as the global architecture map for a solution. Use when bootstrapping a repo, onboarding, or changing modules, boundaries, or contracts. Keep it navigational and use `references/overview-template.md` for scaffolding."
compatibility: "Requires repository write access; produces Markdown docs with Mermaid diagrams."
---

# MCAF: Architecture Overview

## Trigger On

- create the first repo-wide architecture map
- modules, boundaries, interfaces, or ownership changed
- onboarding is slow because there is no short "start here" system map

## Value

- produce a concrete project delta: code, docs, config, tests, CI, or review artifact
- reduce ambiguity through explicit planning, verification, and final validation skills
- leave reusable project context so future tasks are faster and safer

## Do Not Use For

- recording a single architecture decision with alternatives
- writing feature-level behaviour details

## Inputs

- current solution layout and entry points
- existing ADRs, feature docs, and boundary docs
- the nearest `AGENTS.md` files

## Quick Start

1. Read the nearest `AGENTS.md` and confirm scope and constraints.
2. Run this skill's `Workflow` through the `Ralph Loop` until outcomes are acceptable.
3. Return the `Required Result Format` with concrete artifacts and verification evidence.

## Workflow

1. Start from the current `docs/Architecture.md`; if it is missing, scaffold it from `references/overview-template.md`.
2. Build a short navigational overview:
   - system or module map
   - key boundaries and contracts
   - scoping hints
   - links to ADRs, feature docs, and high-signal code paths
3. Use only real names from the repo. No placeholders like "Module A".
4. Prefer Mermaid diagrams plus a tiny link index over long prose.
5. Split diagrams by boundary if the map becomes noisy.

## Deliver

- `docs/Architecture.md`
- a short architecture map that routes the reader to deeper docs

## Validate

- diagram nodes use real repo names
- every important box or boundary links to deeper material
- the file stays navigational instead of becoming an inventory dump
- the overview lets a new agent scope work without reading the whole repo

## Ralph Loop

Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.

1. Brainstorm first (mandatory):
   - analyze current state
   - define the problem, target outcome, constraints, and risks
   - generate options and think through trade-offs before committing
   - capture the recommended direction and open questions
2. Plan second (mandatory):
   - write a detailed execution plan from the chosen direction
   - list final validation skills to run at the end, with order and reason
3. Execute one planned step and produce a concrete delta.
4. Review the result and capture findings with actionable next fixes.
5. Apply fixes in small batches and rerun the relevant checks or review steps.
6. Update the plan after each iteration.
7. Repeat until outcomes are acceptable or only explicit exceptions remain.
8. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.

### Required Result Format

- `status`: `complete` | `clean` | `improved` | `configured` | `not_applicable` | `blocked`
- `plan`: concise plan and current iteration step
- `actions_taken`: concrete changes made
- `validation_skills`: final skills run, or skipped with reasons
- `verification`: commands, checks, or review evidence summary
- `remaining`: top unresolved items or `none`

For setup-only requests with no execution, return `status: configured` and exact next commands.

## Load References

- use `references/overview-template.md` only when scaffolding the file

## Example Requests

- "Create an architecture overview for this repo."
- "Update the overview after splitting the API and worker."
- "Make onboarding easier by adding a real module map."