# architecture

Adopt this skill: https://proskills.md/skills/other/afonsoft-skills-skills-architecture

Page: https://proskills.md/skills/other/afonsoft-skills-skills-architecture
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/architecture/SKILL.md
size: 8109
upstream: https://github.com/afonsoft/skills/blob/main/skills/architecture/SKILL.md

````text
---
name: architecture
license: MIT
description: "Single owner of everything under docs/architecture/ — ADRs, architecture and design documents, and architecture diagrams. Routes each deliverable to the right engine: /mermaid-architecture for Markdown-native diagrams, /drawio-architecture for editable .drawio diagrams, and the optional archify skill for interactive standalone HTML diagrams (used only when already installed in the environment; never installed at runtime). Use whenever architecture documentation, ADRs, or architecture diagrams must be created or updated."
metadata:
  version: "1.0.0"
  visibility: public
  author: afonsoft
  url: https://github.com/afonsoft/skills
---

# Architecture

The single entry point for **all repository architecture deliverables**. Instead of calling diagram skills directly, agents invoke `/architecture` and this skill routes each deliverable to the right engine. It owns the `docs/architecture/` folder end to end: ADRs, design documents, and every diagram format.

All questions and confirmations directed at the user must be in **Portuguese (pt-BR)**. Internal reasoning and documentation are in English.

## Ownership — `docs/architecture/`

Everything that describes or decides the system's architecture lives here:

```text
docs/architecture/
├── AD-NNNN-<slug>.md                    # Architecture Decision Records
├── architecture-design.md               # Architecture design doc
├── system-design.md                     # System design doc
├── api-design.md                        # API design doc
├── database-design.md                   # Database design doc
├── feature-<name>-design.md             # Feature-scoped design doc
├── system-architecture.md               # Markdown doc with embedded Mermaid
├── <name>_<type>_<title>.mmd            # Mermaid sources
├── <name>_<type>_<title>.drawio         # Editable draw.io sources
├── <name>_<type>_<title>.png|.svg|.pdf  # Exported images
├── <name>.json                          # Archify candidate specs
└── <name>.html                          # Archify interactive HTML artifacts
```

Ensure the directory exists before writing: `mkdir -p docs/architecture`.

> Projects scaffolded by `/scaffold-mvp` may also keep ADRs under `docs/adr/`. Treat `docs/architecture/` as canonical; when `docs/adr/` exists, keep it consistent with the AD index below.

## Engine Routing

Pick the engine by deliverable, never by habit:

| Deliverable | Engine | Why |
| --- | --- | --- |
| ADR (`AD-NNNN`) | this skill (template below) | Structured Markdown decision record |
| Design doc (system / API / DB / feature) | `/mermaid-architecture` assets | Templates live in `mermaid-architecture/assets/` |
| Markdown-native diagram (C4, sequence, flow, ER, state) | `/mermaid-architecture` | Renders in GitHub/Obsidian/wikis, works headless |
| Editable `.drawio` diagram or PNG/SVG export | `/drawio-architecture` | draw.io MCP or desktop CLI; fall back to `/mermaid-architecture` if graphical rendering fails in headless environments |
| Interactive standalone HTML diagram (presentations, explorability, trace motion) | `archify` (optional, only if already installed) | Self-contained HTML + inline SVG with themes and export — see below |
| Evidence-backed audit (delivered state vs code/specs/docs) | `/gap-analysis` | Owned by this skill at the end of the pipeline — see `references/gap-audit-handoff.md` |

**Default order in the Orchestrator pipeline (Phase 5):** `/drawio-architecture` for the editable system diagram → `/mermaid-architecture` for native Markdown diagrams → `archify` for the interactive runtime diagram when installed → `/gap-analysis` for the final evidence-backed audit.

## Guardrails

- **Never install external skills.** Archify is used only when already installed in the environment. If absent, skip it — do not prompt for, suggest, or run any install command — consistent with the orchestrator's "no silent execution" and "trusted delegation only" rules.
- **Graceful degradation.** If archify is absent, deliver the same content through `/mermaid-architecture` (and `/drawio-architecture` when editable output is needed). A missing optional engine never blocks the pipeline.
- **Never bypass the gap-analysis gate.** `gap-analysis` is read-only until the user answers its own pt-BR approval gate. This skill invokes it and reports the outcome; it never pre-approves, answers for the user, or skips the audit silently.
- **Verify before claiming.** Validate Mermaid syntax, `.drawio` XML, and archify receipts with each engine's own validator before reporting success.

## Workflow

0. **Preflight** (optional but recommended): run `scripts/architecture-doctor.sh` for a read-only inventory of `docs/architecture/`, the next free ADR number, engine availability (`mmdc`, `drawio` CLI), and delegated-skill detection (`mermaid-architecture`, `drawio-architecture`, `gap-analysis`, `archify`).
1. **Classify the request**: ADR, design doc, Markdown diagram, editable diagram, or interactive HTML. Multiple deliverables may apply.
2. **ADRs**: check the highest existing `AD-NNNN` number, then write the next one with the template below.
3. **Design docs**: populate the matching template from `mermaid-architecture/assets/` into `docs/architecture/`.
4. **Diagrams**: route per the table. For code-grounded diagrams, extract evidence first (entry points, DI graph, `docker-compose.yml`, Helm/Terraform, CI files).
5. **Verify**: run each engine's validation step; fix and re-run until green.
6. **Gap audit**: invoke `/gap-analysis` per its own contract — pass the delivery context (SPEC paths, commits, files written under `docs/architecture/`) so its AS-IS × TO-BE matrix starts warm. Its approval gate decides whether confirmed gaps become Issues; see `references/gap-audit-handoff.md`.
7. **Report** the files written under `docs/architecture/` and the audit outcome.

## ADR Convention

File name: `docs/architecture/AD-NNNN-<kebab-slug>.md` (sequential, zero-padded — e.g. `AD-0002-postgres-persistence.md`).

```markdown
# AD-NNNN — <Decision Title>

## Context
[Forces at play: constraints, requirements, prior decisions.]

## Decision
[What was decided and the key alternatives rejected.]

## Consequences
- Positive: [...]
- Trade-off: [...]

## Related SPEC
- [.specs/SPEC-{YYYYMMDD}-{slug}.md](../../.specs/SPEC-{YYYYMMDD}-{slug}.md)
```

Keep an index of ADRs at the top of `docs/architecture/README.md` when that file exists; never renumber existing records — supersede them with a new AD.

## Archify (optional, interactive HTML diagrams)

`archify` ([github.com/tt-a1i/archify](https://github.com/tt-a1i/archify)) produces explorable standalone HTML diagrams (inline SVG, dark/light themes, trace motion, PNG/JPEG/WebP/SVG export) from a small typed JSON spec — the right tool when stakeholders need a polished, interactive runtime view rather than a static diagram.

### Step 1 — Detect

Check whether the `archify` skill is already installed in any known skills root:

```bash
for d in ./.agents/skills ~/.agents/skills ~/.claude/skills ~/.devin/skills \
         ~/.config/devin/skills ~/.opencode/skills ~/.config/opencode/skills \
         ~/.cursor/skills ~/.copilot/skills ~/.gemini/skills ~/.codex/skills \
         ~/.codeium/windsurf/skills; do
  [ -f "$d/archify/SKILL.md" ] && echo "FOUND: $d/archify"
done
```

The installed skill is also visible when the agent runtime lists `archify` among available skills.

### Step 2 — Absent means skip (never install)

If not found, do **not** offer, suggest, or run any installation. Fall back to `/mermaid-architecture` and continue — a missing optional engine never blocks the pipeline. If the user wants interactive HTML later, they install `archify` themselves outside this skill's scope.

### Step 3 — Generate (only when already installed)

Invoke the installed `archify` skill with the repository-grounded prompt:

```text
Analyze this repository, then use archify to create a high-level ru
````

## File: README.md
upstream: https://github.com/afonsoft/skills/blob/main/README.md

````text
# Spec Driven

An orchestrator-first collection of Agent Skills for **spec-driven development**: the [`orchestrator`](docs/en/orchestrator.md) skill turns a PRD or idea into approved SPECs, tracked GitHub Issues, TDD-implemented slices, QA gates, and reviewed PRs — across Claude Code, OpenCode, Devin, Cursor, and other runtimes.

[![skills.sh](https://skills.sh/b/afonsoft/skills)](https://skills.sh/afonsoft/skills)
[![Spec Validation](https://github.com/afonsoft/skills/actions/workflows/skills-validate.yml/badge.svg?job=validate-spec)](https://github.com/afonsoft/skills/actions/workflows/skills-validate.yml)
[![Quality Check](https://github.com/afonsoft/skills/actions/workflows/skills-validate.yml/badge.svg?job=validate-quality)](https://github.com/afonsoft/skills/actions/workflows/skills-validate.yml)
[![Security Scan](https://github.com/afonsoft/skills/actions/workflows/skills-validate.yml/badge.svg?job=security-scan)](https://github.com/afonsoft/skills/actions/workflows/skills-validate.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Agent Skills Spec](https://img.shields.io/badge/Agent%20Skills-Spec-blue)](https://agentskills.io)
[![DeepWiki](https://img.shields.io/badge/DeepWiki-afonsoft%2Fskills-blue)](https://deepwiki.com/afonsoft/skills)
[![Made in Brazil](https://img.shields.io/badge/Made%20in-Brazil-green)](https://github.com/afonsoft/skills)
[![Last Commit](https://img.shields.io/github/last-commit/afonsoft/skills)](https://github.com/afonsoft/skills/commits/main)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/afonsoft/skills/pulls)
[![Open Source](https://img.shields.io/badge/Open%20Source-%E2%9D%A4-brightgreen)](https://github.com/afonsoft/skills)

## 🚀 Overview

This repository implements **Spec-Driven Development (SDD)** for AI agents, following the **Agent Skills Specification** (agentskills.io). At the center is the [`orchestrator`](docs/en/orchestrator.md) skill: a control loop that audits preconditions, provisions the agent harness, consolidates domain language into approved SPEC SDDs (`.specs/SPEC-*.md`), fragments work into GitHub Issues, and delegates implementation, review, QA, and documentation to specialized skills — never doing complex work itself.

Every other skill in the catalog is a delegation target in that loop. Instead of generic prompts, each skill provides structured patterns, constraints, and reference materials that allow agents to perform complex software engineering tasks with production-grade quality.

## 🧭 The Orchestrator

The [`orchestrator`](docs/en/orchestrator.md) is the entry point and central control skill for agent-driven projects. Invoke it with `/spec-driven` (alias for `/spec-driven:orchestrator`, or *"use the orchestrator skill"*) and it runs a continuous loop, delegating complex work to specialized skills and persisting state in `.claude/memory/orchestrator_stats.md`.

```mermaid
flowchart TD
    A[Phase -1: Framework Update] --> B[Phase 0: Governance]
    B --> C[Phase 1: Discovery]
    C --> D[Phase 2: Audit]
    D --> E[Phase 3: GitHub Fragmentation]
    E --> F[Phase 4: Implementation Loop]
    F --> G[Phase 5: Verification & QA]
    G --> H[PR / Merge]

    C -->|PRD only| I[/scaffold-mvp\]
    C -->|needs spec| J[/write-specs\]
    D -->|P2 gap| K[/improve-codebase-architecture\]
    E --> L[/create-issues\]
    F -->|per slice| M[/execute-specs\]
    F -->|bug| N[/diagnose\]
    G --> O[/qa-analyst\]
    G --> P[/architecture\]
    G --> R[/gap-analysis\]

    S[/migration-planner\] -.->|domain plans| J
    T[/web-design-guidelines\] -.->|finding groups| J
```

The orchestrator advances automatically between phases once validation passes. It only pauses for escalation gates (security, schema, public APIs, data changes), validation failures, or an explicit user request to stop.

## 🛠️ Skill Catalog & Correlation

The skills are organized around the orchestrator's pipeline: **Harness Engineering**, **Orchestration & Delivery**, **Code Quality & Review**, **Frontend & Design**, **Extensibility & Integration**, and **MCP Integrations**.

### 🏗️ Harness Engineering
*Foundation for creating and managing AI agents.*
- **[`create-agent-harness`](docs/en/create-agent-harness.md)**: The starting point. Use this to bootstrap a complete agent environment (CLAUDE.md, rules, skills) in any repo.
- **[`create-readme`](docs/en/create-readme.md)**: Professionalizes the repository landing page. Generates evidence-based READMEs and SemVer-compliant CHANGELOGs.
- **[`observability-and-instrumentation`](docs/en/observability-and-instrumentation.md)**: Once the harness is set, use this to ensure the agent's actions and the application's behavior are visible and diagnosable in production.

### 🧭 Orchestration & Delivery
*Planning, execution, verification, and documentation for agent-driven projects.*
- **[`orchestrator`](docs/en/orchestrator.md)**: Central control skill. Audits preconditions, creates documentation, reconciles open GitHub Issues, turns gaps into Issues, and coordinates execution, tests, QA, and PR in a continuous loop. Persists state in `.claude/memory/orchestrator_stats.md` and auto-continues to the next slice.
- **[`write-specs`](docs/en/write-specs.md)**: Interviews the user in Portuguese to consolidate domain language and produce an approved `.specs/SPEC-{YYYYMMDD}-{feature}.md` before implementation.
- **[`scaffold-mvp`](docs/en/scaffold-mvp.md)**: Bootstraps a new .NET/Blazor/Angular repository after domain/spec alignment. Installs the agent harness, proposes a productive stack, and generates the initial project skeleton, AD-0001, and stubs.
- **[`create-issues`](docs/en/create-issues.md)**: Turns approved gaps, roadmap, and specs into GitHub Issues with vertical slices and dependency links. Uses the `references/spec-sdd-template.md` structure when creating Issues from SPEC SDDs.
- **[`execute-specs`](docs/en/execute-specs.md)**: Test-driven development using the approved SPEC SDD as the source of truth. Red-green-refactor one vertical slice at a time.
- **[`qa-analyst`](docs/en/qa-analyst.md)**: Full QA cycle — requirements analysis, test planning, test cases, execution, bug reports, and process improvement.
- **[`diagnose`](docs/en/diagnose.md)**: Disciplined diagnosis and re-validation loop for hard bugs and performance regressions — tight feedback loops, ranked falsifiable hypotheses, stack playbooks for .NET/Angular/Python/React, agent self-debug, and AI workflow audit.
- **[`improve-codebase-architecture`](docs/en/improve-codebase-architecture.md)**: Finds architectural deepening opportunities by reading `.claude/CONTEXT.md`, `.claude/MEMORY.md`, and `docs/architecture/`, and produces an HTML report.
- **[`architecture`](docs/en/architecture.md)**: The single owner of `docs/architecture/`. Routes ADRs, design docs, and diagrams to `drawio-architecture`, `mermaid-architecture`, and the optional `archify` skill (interactive HTML, used only when already installed — never installed at runtime), then ends with the `gap-analysis` evidence audit it owns.
- **[`gap-analysis`](docs/en/gap-analysis.md)**: Evidence-backed audit of AS-IS code vs. TO-BE specs/docs. Confirmed gaps become Draft SPECs (`write-specs`), a tracked Epic with slices (`create-issues`), and orchestrated execution (`orchestrator`) — behind an explicit approval gate.
- **[`migration-planner`](docs/en/migration-planner.md)**: Evidence-based legacy → .NET migration planning with the Strangler Fig pattern. Researches the codebase, maps bounded contexts, designs seams (YARP, DI, EF Core dual-write, Blazor/MAUI), writes per-domain plans + roadmap in `migration-plan/`, then converts each domain into Draft SPECs (`write-specs`), a tracked Epic (`create-issues`), and orchestrated execution (`orchestrator`) — behind an explicit approval gate. Default targets: Blazor WebAssembly, .NET MAUI, ASP.NET Core.

### 💎 Code Qualit
````
