architecture-component-guardian

What this skill does

# Architecture Component Guardian Skill

## Purpose

This skill is the single source of truth for generating and maintaining
`docs/components/README.md`. It enforces a fixed 5-column table schema on every
write and refuses ad-hoc direct edits.

## C4 Model Governance

This skill enforces **C4 Level 2 (Container diagram)** rules from:
```
[plugin_dir]/skills/architecture-docs/references/ICEPANEL-C4-MODEL.md
```
Read that reference for the full C4 model (abstractions, 4 diagram levels, IcePanel conventions). Below are only the **guardian-specific enforcement rules** that extend the C4 reference.

### C4 L2 Canonical Types

The **Type** column accepts exactly these 8 values:

| Type | C4 Category | Description | Examples |
|------|------------|-------------|---------|
| API Service | App | Exposes a request/reply interface (REST, GraphQL, gRPC) | Payment API, Account Service, BFF |
| Web Application | App | Serves a browser-based UI or server-rendered pages | React SPA, Angular portal, Next.js SSR |
| Worker/Consumer | App | Processes work asynchronously — messages, scheduled jobs, background tasks | Kafka consumer, Celery worker, cron scheduler |
| Gateway | App | Routes, authenticates, rate-limits at the edge | Kong, NGINX, AWS API Gateway, Envoy |
| Database | Store | Primary persistence — system of record for a domain | PostgreSQL, MongoDB, SQL Server, DynamoDB |
| Cache | Store | Fast-access temporary data store | Redis, Memcached, Valkey, ElastiCache |
| Message Broker | Store | Async communication backbone — buffers and replays messages | Apache Kafka, RabbitMQ, Azure Service Bus, SQS |
| Object Storage | Store | Unstructured binary/file storage | S3, Azure Blob, MinIO, GCS |

### Ambiguous Cases

| Scenario | Resolution |
|----------|-----------|
| Dual-role: consumer AND exposes API (e.g., History Service) | Classify by **primary external interface** — API exposed → `API Service` |
| In-memory cache inside a service (Caffeine, Guava) | NOT a component — mention in parent service description |
| External managed service (SendGrid, Auth0) | NOT a component — integration reference. If user tracks it, flag as external in system header |
| Sidecar / service mesh proxy (Envoy, Istio) | NOT a component — transparent infrastructure, mention in description |
| Shared library or SDK | NOT a component — technology stack item, not a deployable unit |

### Architecture Type → C4 Translation

**On every invocation** (sync, add, migrate), detect the project's architecture type and load its C4 translation guide. The translation guide defines how that specific architecture maps to C4 levels — this affects what qualifies as a component.

**Step 0: Detect architecture type**

Search for the type metadata comment:
```
Grep pattern: "<!-- ARCHITECTURE_TYPE:"
file: docs/03-architecture-layers.md
```

Extract the type value (e.g., `MICROSERVICES`, `3-TIER`, `META`, `N-LAYER`, `BIAN`).

**Step 0.1: Load the C4 translation guide**

Read the matching translation file from the plugin:
```
[plugin_dir]/skills/architecture-docs/references/{TYPE}-TO-C4-TRANSLATION.md
```

Mapping:
| ARCHITECTURE_TYPE | Translation File |
|-------------------|-----------------|
| MICROSERVICES | `MICROSERVICES-TO-C4-TRANSLATION.md` |
| 3-TIER | `3-TIER-TO-C4-TRANSLATION.md` |
| N-LAYER | `N-LAYER-TO-C4-TRANSLATION.md` |
| META | `META-TO-C4-TRANSLATION.md` |
| BIAN | `BIAN-TO-C4-TRANSLATION.md` |

If `docs/03-architecture-layers.md` doesn't exist or has no type comment, skip translation loading and use the generic C4 L2 rules from `ICEPANEL-C4-MODEL.md` only.

**Step 0.2: Apply type-specific container rules**

The translation guide overrides the generic C4 rules for what counts as a component:

| Architecture Type | Key Translation Rule |
|-------------------|---------------------|
| **Microservices** | Each service = Container (App). Each DB per service = Container (Store). Event bus = Container. API Gateway = Container. |
| **3-Tier** | Backend code (tiers 2+3) = ONE Container. Only the database, cache, and external processes are separate Containers. Do NOT create a component per tier. |
| **N-Layer** | All inner layers (Domain, Application, Use Cases) = C3 level inside one backend Container. Only infrastructure that runs as a separate process (DB, cache, broker) = Container. |
| **META** | Channels (L1) = separate Systems. Layers 2–5 containers grouped by layer. Transversal = vertical column. BIAN SDs at L5 = Containers. |
| **BIAN** | Each BIAN Service Domain = Container (App) labeled with BIAN SD name + `[BIAN V12.0]`. Core systems = external. |

**When validating component entries**, check the Type value against what the translation guide considers a valid C4 L2 container for this architecture. Flag violations:
```
⚠️ Architecture type is 3-TIER but component "Service Layer" looks like an internal code layer (C3), not a deployable container (C2).
The 3-Tier C4 translation says: backend code (tiers 2+3) deploys as ONE container.
```

---

## When to Invoke This Skill

- User adds a new component file to `docs/components/`
- User removes a component file from `docs/components/`
- User updates a component name or type in a component file
- User asks to "sync", "regenerate", or "rebuild" the component index
- After a migration that produces the `docs/components/` structure for the first time
- Any request to modify `docs/components/README.md` directly → redirect here instead
- User asks to "migrate", "convert to C4", or "restructure components" → triggers the C4 multi-system migration workflow

**Do NOT invoke for**: questions about individual components (use `architecture-docs`
skill), compliance generation, presentation creation, or **component development handoffs**
(use `architecture-dev-handoff` skill — it manages `handoffs/` independently).

---

## Format Specification — FIXED, do not alter without updating this skill

The generated `docs/components/README.md` MUST follow this exact structure:

```
Line 1:  <!-- managed by sa-skills:architecture-component-guardian — do not edit manually -->
Line 2:  [Architecture](../../ARCHITECTURE.md) > Components
Line 3:  (blank)
Line 4:  # Component Details
Line 5:  (blank)
Line 6:  <intro paragraph>
Line 7:  (blank)
Line 8:  ## <System Name> Components
Line 9:  (blank)
Line 10: | # | Component | File | Type | Technology |
Line 11: |---|-----------|------|------|------------|
Line 12: | 5.1 | ... | ... | ... |
         ...
         (blank)
         ## Key Relationships
         (blank)
         - bullet list
         (blank)
         ## Related Documentation
         (blank)
         - link list
```

**Table schema — exactly 5 columns, never add or remove:**

| # | Component | File | Type | Technology |
|---|-----------|------|------|------------|

**Type canonical values (C4 L2 set):**

| Type | C4 Category |
|------|------------|
| API Service | App |
| Web Application | App |
| Worker/Consumer | App |
| Database | Store |
| Cache | Store |
| Message Broker | Store |
| Object Storage | Store |
| Gateway | App |

**Multi-system grouped tables:**

- **All architectures**: Use a `### [System Name](system-name.md)` header linked to the system descriptor file before each system's table. File column paths include system folder: `[01-name.md](system-name/01-name.md)`. This applies to both single-system and multi-system architectures — there is no flat layout exception.

**C4 L1 System descriptor files** (all architectures):

- Located at `docs/components/` root: `{system-name}.md` (kebab-case, matches folder name)
- NOT indexed as rows in the README table — they are linked from the `### System Name` section headers
- Contain: C4 Level (System L1), Type (Internal/External), Owner, Container summary table, System Boundaries, Communication patterns
- When scanning `docs/components/`, distinguish files by name pattern:
  - `NN-*.md` (starts with digits) = C4 L2 container → indexed in table
  - `{name}.md` matching a subfolder name = C4 L1 system descr