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:

Ambiguous Cases

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:

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:

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 docs/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 solutions-architect-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:

Type canonical values (C4 L2 set):

Multi-system grouped tables:

• Multi-system architecture: 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)
• Single-system architecture: Single table with no system header, no system descriptor file

C4 L1 System descriptor files (multi-system only):

• 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 descriptor → NOT in table, linked from header
  • README.md = index file → managed by this skill

Technology column — IcePanel bracket convention:

Use brackets around the technology with version: [Spring Boot 3.2], [PostgreSQL 16], [React 18 SPA]

Column extraction rules:

What belongs here vs. elsewhere:

Workflow

Step 1 — Detect mode

Check if docs/components/README.md exists:

• Does not exist → CREATE mode (new architecture or post-migration)
• Exists → UPDATE mode (add / remove / update / sync)

Step 2 — Scan component files

Read every .md file in docs/components/ except README.md. Sort by filename prefix ascending (01, 02, 03 …).

For each file extract: section number, component name, file link, type.

Validate naming convention: Every component file MUST follow NN-kebab-case-name.md — lowercase, hyphens only, no spaces, no uppercase, no underscores. If any file violates this convention, warn the user:

⚠️  Component file naming violation (must be lowercase kebab-case):
  docs/components/03-PaymentService.md → rename to 03-payment-service.md

Offer to rename the file automatically.

Step 3 — Apply requested change

When creating a new component file (add): always convert the component name to lowercase kebab-case for the filename. Examples: "Payment Service" → NN-payment-service.md, "CRM Domain Service" → NN-crm-domain-service.md, "Redis Cache" → NN-redis-cache.md. The display name in the # Heading inside the file keeps its natural casing (e.g., # Payment Service).

Step 4 — Regenerate docs/components/README.md

Write the full file using the Format Specification above.

If the user requests extra columns (technology, cost, etc.): decline and explain that additional data belongs in the individual component files or in a dedicated supplementary document. The index table schema is fixed by this skill.

Step 5 — Verify output

Before finishing, confirm:

• Line 1 is the managed-by HTML comment
• Table has exactly 5 columns: #, Component, File, Type, Technology
• All .md files in docs/components/ (except README.md) are represented in the table
• No component appears twice
• Breadcrumb is [Architecture](../../ARCHITECTURE.md) > Components
• Sections appear in order: Components table → Key Relationships → Related Documentation

Migrate Workflow — C4 Multi-System Migration

Trigger: User invokes with migrate, or asks to "convert to C4 structure" or "restructure components into systems".

Prerequisite: docs/components/ exists with at least one .md file (besides README.md). If no component files exist, abort:

⚠️ No component files found in docs/components/. Nothing to migrate.

Reference: Load C4-MIGRATION-REFERENCE.md from this skill's directory for type mapping tables, ownership heuristics, and cross-reference patterns.

Phase M1 — Detect & Scan

M1.1 Check C4 compliance: Scan docs/components/ for subdirectories with .md files. If subfolders already exist AND all Type values are canonical → report "Already C4-compliant. Use sync instead." Offer to proceed anyway for partial re-migrations.

M1.2 Scan all component files: Read every .md file in docs/components/ (excluding README.md). For each file, extract:

• heading — first # heading
• heading_has_section_number — starts with digits + dot (e.g., ## 5.1 ...)
• type_raw — value of **Type:** field
• type_is_canonical — matches C4 L2 types
• technology_raw — value of **Technology:** field
• technology_has_brackets — wrapped in [...]
• location — value of **Location:** (may be absent)
• team_owner — value of **Team Owner:** (may be absent)
• has_c4_header — file contains all 5 C4 metadata fields

Present scan summary with issue counts.

Phase M2 — Classify Systems

M2.1 Apply ownership heuristics (from C4-MIGRATION-REFERENCE.md):

• **Location:** services/... → internal
• Technology says "managed by domain service team" → external
• No Location AND no Version → likely external
• **Bounded Context:** grouping → same system

M2.2 Present classification to user:

🔍 C4 Level 1 — System Classification (Migration)

  1. task-scheduling-system — 9 containers (6 Apps, 3 Stores)
  2. bian-domain-services (external) — 3 API Services

Please confirm, adjust system names, or reassign components.

Wait for user confirmation.

M2.3 Confirm focus system (if multiple internal systems):

🔎 Which system is the main focus? (Listed first in README.md)

Phase M3 — Migrate Metadata (per file)

M3.1 Fix headings: Strip section number prefixes, enforce H1. Record old→new heading text (needed for anchor slug updates in M5).

M3.2 Fix Type values: Use the auto-map table in C4-MIGRATION-REFERENCE.md. For unmapped types, prompt user with the 8 canonical options.

M3.3 Fix Technology format: Wrap in IcePanel brackets. Strip tier/SKU/pricing details. Keep primary tech + version.

M3.4 Add C4 metadata header (if missing): Insert after Type/Technology fields:

**C4 Level:** Container (L2)
**Deploys as:** [infer or placeholder]
**Communicates via:** [infer or placeholder]

Present Phase 3 summary with all fixes applied.

Phase M4 — Create Folders & Move Files

M4.1 Create system subfolders: docs/components/<system-name>/ (kebab-case).

M4.1b Create C4 L1 system descriptor files: For each system, write docs/components/<system-name>.md at the root using the L1 system file format (C4 Level: System L1, Type: Internal/External, Owner, Container table, System Boundaries, Communication). Populate from architecture docs context.

M4.2 Detect project type: Check if .git/ exists in project root.

• Git repo → use git mv (preserves history)
• Non-git → Read source file content → Write to new path → delete original

M4.3 Move files: For each component, move to its system subfolder.

M4.4 Renumber within folders: If numbering has gaps after grouping, renumber contiguously (01, 02, 03...) within each system folder.

M4.5 Build MOVE MANIFEST: Complete mapping of old paths → new paths. This drives all reference updates in Phase M5.

M4.6 Update breadcrumbs in moved files:

• Old (flat): [Architecture](../../ARCHITECTURE.md) > [Components](README.md) > Name
• New (multi): [Architecture](../../../ARCHITECTURE.md) > [Components](../README.md) > [System](.) > Name

Phase M5 — Update References (CRITICAL)

This is where manual migrations break. Every markdown reference to a moved component must be updated.

M5.1 Build search patterns: From the MOVE MANIFEST, generate search patterns for each moved file across all possible relative path forms.

M5.2 Scan ALL markdown files in: docs/, adr/, docs/handoffs/, compliance-docs/, ARCHITECTURE.md

M5.3 For each reference found, classify:

• Markdown link [text](path) → compute new relative path → update automatically
• Plain text (path in prose without link syntax) → LOG for manual review, do NOT auto-update

M5.4 Update anchor slugs: If headings changed in M3 (e.g., #51-job-scheduler-service → #job-scheduler-service), find and update all anchor references.

M5.5 Update cross-system references: Component files referencing files in different system folders need relative paths through ../other-system/.

Present Phase M5 summary: links updated count, anchor slugs updated, plain-text references logged.

Phase M6 — Regenerate README.md

Use the existing Format Specification in multi-system mode:

• Focus system listed first
• ### [System Name](system-name.md) header linked to system descriptor file before each system's table
• 5-column table with updated file paths including system folder prefix
• Renumbered # column contiguous within README

Phase M7 — Update ARCHITECTURE.md

Update Section 5 description to reflect system count:

| S5 | Component Details | [docs/components/README.md](...) | N systems, M containers |

Phase M8 — Verify & Report

M8.1 Orphaned path check: Grep all .md files for old flat component paths not updated.

M8.2 Link validation: Every file in system folders has a README row; every README row has a file.

M8.3 Diagram update prompt:

⚠️ Component migration detected — diagrams may be out of date.
Update now? [Yes/No]

If No → add <!-- DIAGRAM UPDATE PENDING: C4 migration (YYYY-MM-DD) --> to docs/03-architecture-layers.md.

M8.4 Final report:

═══════════════════════════════════════════════════════════
C4 MIGRATION — COMPLETE
═══════════════════════════════════════════════════════════
Systems: N (M internal, K external)
Files moved: X
Metadata fixes: Y (headings, types, technology, C4 headers)
References updated: Z markdown links, W anchor slugs
Plain-text refs logged: N (manual review recommended)
═══════════════════════════════════════════════════════════

Step 6 — Update architecture documentation

Runs for: add, remove, update operations only. Skip for sync and migrate (migrate handles its own architecture updates in Phase M7).

Step 6a — Load Context Anchor

Required by the architecture-docs Context-Efficient Workflow for any edit to docs/components/*.md files.

Load in this order:

1. Universal Foundation: docs/01-system-overview.md + docs/02-architecture-principles.md
2. Section-Specific Parents: docs/03-architecture-layers.md (layers/tiers the component belongs to) + docs/components/README.md (component index)
3. Relevant ADRs: Read the ARCHITECTURE.md navigation table; match ADR titles against the component name and type — load any matched ADRs

Step 6b — Post-Write Alignment & Traceability Audit

Run the 5-check audit on the modified or newly created component file:

• Check A — Principle traceability: Component design does not contradict Section 3 (Architecture Principles)
• Check B — Metric consistency: Any numeric values (throughput, latency, SLO) match Section 1 Key Metrics
• Check C — ADR alignment: Component does not contradict decisions in the loaded ADRs
• Check D — Parent section alignment: Component maps to a valid layer defined in docs/03-architecture-layers.md
• Check E — Source citation audit: Numeric values, technology names, and architecture patterns have source cross-reference links; unverifiable claims are marked <!-- TODO: Add source reference -->

Silent pass if all checks clear. Report only when misalignment or missing citations are detected.

Step 6c — Update all downstream architecture sections (S6–S11)

Read each downstream file and update it to reflect the component change:

Per-operation rules:

• add: Insert references to the new component in each section where it is architecturally relevant. If a section has no applicable content for this component type (e.g., a stateless utility service has no S10 scaling entry), leave it unchanged and note it in the propagation report.
• remove: Remove all references to the deleted component from each section. Flag any flows, integration points, or operational runbooks that depended exclusively on this component as orphaned (mark with <!-- ORPHANED: <component-name> removed — update required -->).
• update: Update all references to reflect the changed component details (new name, changed type, modified endpoints, revised responsibilities). Replace stale references; do not duplicate them.

Apply source-attribution conventions throughout:

• Cross-reference links to the component file: (see [Component Name](../components/NN-name.md))
• Unverifiable claims: <!-- TODO: Add source reference -->

Step 6d — Update ARCHITECTURE.md navigation index

Applies to add and remove only (skip for update):

• add: Verify the new component file appears in the Section 5 row of the ARCHITECTURE.md navigation table. If missing, add the row.
• remove: Verify the removed component no longer appears in the Section 5 row. If still present, remove the row.

Step 6e — Prompt for diagram update

Component changes affect the High-Level Architecture diagram and potentially Data Flow diagrams. Present:

⚠️  Component change detected — architecture diagrams may be out of date.

Affected diagrams:
- High-Level Architecture → docs/03-architecture-layers.md  [REQUIRED diagram]
- Data Flow Diagrams → docs/04-data-flow-patterns.md  [REQUIRED diagram]

Update architecture diagrams now? [Yes/No]

• If Yes: invoke the architecture-docs skill with diagram update intent — Workflow 8 runs in update mode (existing diagrams are replaced, Step 5a detects and inventories them, all source-traceability and canonical-location rules apply)
• If No: log a <!-- DIAGRAM UPDATE PENDING: <component-name> <operation> (YYYY-MM-DD) --> comment at the top of docs/03-architecture-layers.md so the outstanding update is traceable

Step 6f — Change Propagation Report

Present the downstream impact summary:

═══════════════════════════════════════════════════════════
CHANGE PROPAGATION — DOWNSTREAM IMPACT REPORT
═══════════════════════════════════════════════════════════

Component: <component-name> (<operation>: add | remove | update)

Sections updated:
→ docs/04-data-flow-patterns.md (S6) — [summary of change]
→ docs/05-integration-points.md (S7) — [summary of change]
→ docs/06-technology-stack.md (S8) — [summary of change]
→ docs/07-security-architecture.md (S9) — [summary of change]
→ docs/08-scalability-and-performance.md (S10) — [summary of change]
→ docs/09-operational-considerations.md (S11) — [summary of change]

Sections with no applicable content for this component:
ℹ️  [list sections where no update was needed, with reason]

[remove only] Orphaned references requiring manual review:
⚠️  [list any flows or runbooks that exclusively referenced the removed component]
═══════════════════════════════════════════════════════════

User Flows

Flow A — New architecture (first time)

1. architecture-docs skill creates ARCHITECTURE.md + docs/ structure including component files
2. User invokes this skill with sync
3. Skill scans docs/components/*.md, extracts data, creates README from scratch

Flow B — Post-migration

1. MIGRATION agent splits a monolithic ARCHITECTURE.md into docs/ files
2. At end of migration, invoke this skill with sync to create or verify README
3. Managed-by comment is written at line 1

Flow C — Ongoing maintenance

1. Developer adds/changes/removes a docs/components/NN-*.md file
2. Invoke this skill — README is regenerated with the change reflected
3. 5-column format is enforced on every write
4. Architecture documentation sections (S6–S11) are updated with component references
5. ARCHITECTURE.md navigation index is updated (add/remove only)
6. Diagram update prompt is presented; pending updates are tracked with a comment marker

Flow D — Rejected direct edit

1. User or Claude tries to edit docs/components/README.md directly
2. CLAUDE.md project rule redirects to this skill

Flow E — C4 Multi-System Migration

1. User has existing flat docs/components/ with non-C4 metadata
2. User invokes this skill with migrate
3. Skill runs Phases M1–M8: scan → classify systems → fix metadata → move files → update references → regenerate README → update ARCHITECTURE.md → verify
4. User confirms system classification (Phase M2) and ambiguous type mappings (Phase M3)
5. File moves use git mv if git repo detected, otherwise Read→Write→delete
6. References across docs/, adr/, handoffs/, compliance-docs/ are updated automatically
7. Final report shows all changes with any items needing manual review