⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.0.0

architecture

afonsoft@afonsoft⭐ 16 stars· last commit 19d ago· 0 open issues

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.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 16 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Spec Driven

An orchestrator-first collection of Agent Skills for spec-driven development: the orchestrator 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 Spec Validation Quality Check Security Scan License: MIT Agent Skills Spec DeepWiki Made in Brazil Last Commit PRs Welcome Open Source

🚀 Overview

This repository implements Spec-Driven Development (SDD) for AI agents, following the Agent Skills Specification (agentskills.io). At the center is the orchestrator 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 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.

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: The starting point. Use this to bootstrap a complete agent environment (CLAUDE.md, rules, skills) in any repo.
  • create-readme: Professionalizes the repository landing page. Generates evidence-based READMEs and SemVer-compliant CHANGELOGs.
  • observability-and-instrumentation: 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: 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: Interviews the user in Portuguese to consolidate domain language and produce an approved .specs/SPEC-{YYYYMMDD}-{feature}.md before implementation.
  • scaffold-mvp: 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: 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: Test-driven development using the approved SPEC SDD as the source of truth. Red-green-refactor one vertical slice at a time.
  • qa-analyst: Full QA cycle — requirements analysis, test planning, test cases, execution, bug reports, and process improvement.
  • diagnose: 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: Finds architectural deepening opportunities by reading .claude/CONTEXT.md, .claude/MEMORY.md, and docs/architecture/, and produces an HTML report.
  • architecture: 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: 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: 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

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/architecture/SKILL.md7.9 KBupstream ↗
    ---
    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
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/afonsoft-skills-skills-architecture.md

// REPO STATS

16 stars
0 open issues
Last commit: 19d ago