Architecture Blueprint Skill

Generates standardized blueprint markdown files by extracting data from the architecture documentation and filling organizational templates. Detects the language of the architecture docs, selects the matching-language template, and produces output files written to the same directory as ARCHITECTURE.md.

Available templates:

Automatic Workflow Detection

This skill activates automatically when the user's message contains any of:

• "generate blueprint", "create blueprint", "architecture blueprint"
• "datos de iniciativa", "business blueprint", "application blueprint"
• "blueprint files", "fill blueprint", "generate initiative data"

Action when detected: proceed directly to Step 0.

Prerequisites

Before running, verify:

• ARCHITECTURE.md exists at the project root (or subdirectory — detect its location)
• docs/ directory exists with at least docs/01-system-overview.md

If ARCHITECTURE.md is not found:

❌ ARCHITECTURE.md not found.
   Generate architecture documentation first with /skill architecture-docs.

Step 0: Resolve Plugin Directory

Resolve $plugin_dir to locate the templates:

Step A — Development mode (glob):

Glob: **/solutions-architect-skills/skills/architecture-blueprint/BUSINESS_TEMPLATE_EN.md

If found, strip /skills/architecture-blueprint/BUSINESS_TEMPLATE_EN.md to get plugin_dir.

Step B — Marketplace fallback:

plugin_dir=$(bun ~/.claude/plugins/marketplaces/shadowx4fox-solution-architect-marketplace/skills/architecture-compliance/utils/resolve-plugin-dir.ts)

Step 0.5: Detect Architecture Language

Read the first 30 lines of docs/01-system-overview.md and scan for language indicator keywords:

English indicators: "Executive Summary", "System Overview", "Problem Statement", "Business Value", "Architecture Principles", "Key Metrics", "Solution"

Spanish indicators: "Resumen Ejecutivo", "Descripción del Sistema", "Planteamiento del Problema", "Valor de Negocio", "Principios de Arquitectura", "Métricas Clave", "Solución"

Decision rules:

• If 3+ English indicators found → lang = en
• If 3+ Spanish indicators found → lang = es
• If ambiguous (fewer than 3 matches in either language) → ask the user:
  Copy

  🌐 Could not confidently detect architecture language.
  Use which template language? [en = English / es = Spanish]
  

• If the user explicitly passes a language flag (e.g., "generate blueprint in spanish", "use english template") → override detection with the specified language

Step 1: Detect Mode

Determine which blueprints to generate based on the user's request:

Step 2: Load Templates

Load the template(s) required for the selected mode and detected language from $plugin_dir:

Business template:

• lang = en → $plugin_dir/skills/architecture-blueprint/BUSINESS_TEMPLATE_EN.md
• lang = es → $plugin_dir/skills/architecture-blueprint/BUSINESS_TEMPLATE_ES.md

Application template:

• lang = en → $plugin_dir/skills/architecture-blueprint/APPLICATION_TEMPLATE_EN.md
• lang = es → $plugin_dir/skills/architecture-blueprint/APPLICATION_TEMPLATE_ES.md
• If the file does NOT exist → skip Application generation and display:
  Copy

  ℹ️  Application template ([lang]) not yet configured. Skipping Application blueprint.
     To add it: place APPLICATION_TEMPLATE_EN.md or APPLICATION_TEMPLATE_ES.md in skills/architecture-blueprint/
  

Step 3: Load Architecture Context

Read the following files (load all — they are small enough to fit in context):

If additional docs/ files are needed for specific template fields, load them on demand (e.g., docs/07-security-architecture.md for security-related fields, docs/09-operational-considerations.md for deployment/location and debt fields).

Also check for a PO Spec file at the project root (glob: **/PRODUCT_OWNER_SPEC*.md, **/PO_SPEC*.md) — if found, load it as a supplementary source for business context fields.

Step 4: Fill Template Fields

For each <placeholder> in the template:

1. Search the loaded architecture docs for data matching the field's intent
2. If found → replace the entire <placeholder> (angle brackets included) with the extracted value — verbatim, no paraphrasing
3. If NOT found → replace with:
   Copy

   NOT FOUND — suggest: [recommended section or keyword to check, e.g., "add to docs/01-system-overview.md under Deployment"]
   

4. Preserve all template formatting — only replace content inside < > angle brackets; never alter surrounding text, markdown structure, heading levels, bold/italic markers, or static prose

Field Mapping: Business Template (EN and ES)

Field Mapping: Application Template (EN and ES)

Design Drivers

Architecture Decisions

For each ADR found in adr/ADR-*.md, extract one entry per ADR. If multiple ADRs exist, generate one block per ADR:

If NO ADR files found: fill each placeholder with NOT FOUND — suggest: create ADRs using /skill architecture-definition-record.

Capacity Sizing

Architecture Risks and Debt

Compliance Contract — Approvals

For each of the 10 compliance areas, extract the Status and Observations from compliance-docs/COMPLIANCE_MANIFEST.md.

Compliance area mapping (ES name → EN name → contract file pattern):

Status mapping from manifest score:

• Score ≥ 8.0 → Cumple / Compliant
• Score 5.0–7.9 → No cumple / Non-compliant
• Contract missing or score = N/A → No aplica / Not applicable

Observations: Extract the top gap or note from the manifest's observations column, if present. If not present: write NOT FOUND — suggest: run /skill architecture-compliance to generate contracts.

If compliance-docs/COMPLIANCE_MANIFEST.md does not exist: fill all statuses with NOT FOUND — suggest: run /skill architecture-compliance to generate compliance contracts.

Step 5: Determine Output Directory

The output directory is the same directory that contains ARCHITECTURE.md:

• If ARCHITECTURE.md is at project root → write to ./
• If ARCHITECTURE.md is in a subdirectory (e.g., projects/foo/ARCHITECTURE.md) → write to projects/foo/

Output filenames include the language suffix:

• Business (EN): BLUEPRINT_BUSINESS_EN.md
• Business (ES): BLUEPRINT_BUSINESS_ES.md
• Application (EN): BLUEPRINT_APPLICATION_EN.md
• Application (ES): BLUEPRINT_APPLICATION_ES.md

Step 6: Write Output Files

Write each filled template to its output path using the Write tool.

If the output file already exists, display:

⚠️  BLUEPRINT_BUSINESS_EN.md already exists. Overwrite? [Yes/No]

Wait for confirmation before overwriting.

Step 7: Summary Report

After writing, display the fill summary:

═══════════════════════════════════════════════════════════
BLUEPRINT GENERATION COMPLETE
═══════════════════════════════════════════════════════════

🌐 Language detected: English (en)

📄 BLUEPRINT_BUSINESS_EN.md → [output_dir]

Field Fill Summary:
✅ Filled (N):
   - Headquarters: [extracted value]
   - Domain: [extracted value]
   - The what / The how / The why: [extracted values]
   ...

⚠️  NOT FOUND (N) — requires manual input:
   - Tribe → suggest: add to docs/01-system-overview.md
   - Cell → suggest: add to docs/01-system-overview.md
   - Product Owner → suggest: add to PRODUCT_OWNER_SPEC.md
   - All architect names/emails → suggest: add to docs/01-system-overview.md
   - All URLs → suggest: add to docs/10-references.md
   ...
═══════════════════════════════════════════════════════════