architecture-blueprint

What this skill does

# 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**:
| Language | Business | Application |
|----------|----------|-------------|
| English (`en`) | `BUSINESS_TEMPLATE_EN.md` | `APPLICATION_TEMPLATE_EN.md` *(pending)* |
| Spanish (`es`) | `BUSINESS_TEMPLATE_ES.md` | `APPLICATION_TEMPLATE_ES.md` *(pending)* |

---

## 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: **/{sa-skills,solutions-architect-skills}/skills/architecture-blueprint/BUSINESS_TEMPLATE_EN.md
```
The brace expansion matches both marketplace installs (`sa-skills/` in `~/.claude/plugins/cache/...`) and local dev clones (historical repo folder `solutions-architect-skills/`). If found, strip `/skills/architecture-blueprint/BUSINESS_TEMPLATE_EN.md` to get `plugin_dir`.

**Step B — Marketplace fallback**:
```bash
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:
  ```
  🌐 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:

| User says | Mode |
|-----------|------|
| "business" / "negocio" | Business blueprint only |
| "application" / "aplicación" / "app" | Application blueprint only |
| (default — no qualifier) | Both blueprints |

---

## 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:
  ```
  ℹ️  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):

| File | Content Used |
|------|-------------|
| `docs/01-system-overview.md` | Executive Summary, System Overview, Key Metrics, Business Value, Deployment |
| `docs/02-architecture-principles.md` | Architecture Principles |
| `docs/03-architecture-layers.md` | Architecture layers and component grouping |
| `docs/components/README.md` | Component index (names and types) |
| `ARCHITECTURE.md` | Navigation index, metadata, ADR table |
| `docs/08-scalability-and-performance.md` | Capacity sizing: users, TPS, storage, scaling strategy *(Application template)* |
| `adr/ADR-*.md` | Architecture decisions, alternatives, criteria, assumptions *(Application template)* |
| `compliance-docs/COMPLIANCE_MANIFEST.md` | Compliance status per contract area *(Application template — optional)* |

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:
   ```
   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)

| EN Placeholder | ES Placeholder | Intent | Primary Source | Fallback |
|---|---|---|---|---|
| `<City, other locations>` | `<Quito, otras sedes>` | Physical location / deployment region | `docs/09-operational-considerations.md` → deployment region or cloud region | `docs/01-system-overview.md` → Deployment section |
| `<Business domain – Per capability map>` | `<Dominio de negocio – Según mapa de capacidades>` | Business domain | `docs/01-system-overview.md` → System Overview or Business Value section | PO Spec → Business Context |
| `<Cross-cutting project, Regulatory project, Product increment project, Project>` | `<Proyecto transversal, Proyecto regulatorio, Proyecto incremento producto, Proyecto>` | Project classification type | `docs/01-system-overview.md` → Problem Statement or Business Value | PO Spec → Business Objectives |
| `<Tribe Name>` | `<Nombre de Tribu>` | Tribe name (org structure) | Architecture docs do not typically contain this | `NOT FOUND — suggest: add to docs/01-system-overview.md under Team/Org section` |
| `<Cell Name>` | `<Nombre de Célula>` | Cell name (org structure) | Architecture docs do not typically contain this | `NOT FOUND — suggest: add to docs/01-system-overview.md under Team/Org section` |
| `<Product owner name> <email>` | `<Nombre del dueño de producto> <email>` | Product Owner name and email | PO Spec if available | `NOT FOUND — suggest: add to PRODUCT_OWNER_SPEC.md` |
| `<Tribe lead name> <email>` | `<Nombre de líder de tribu> <email>` | Tribe Lead | Architecture docs do not typically contain this | `NOT FOUND` |
| `<Technical tribe lead name> <email>` | `<Nombre de líder técnico de tribu> <email>` | Technical Tribe Lead | Architecture docs do not typically contain this | `NOT FOUND` |
| `<Assigned enterprise architect> <email>` |