architecture-icepanel-sync

What this skill does

# IcePanel Sync Skill (Beta)

Syncs architecture documentation to IcePanel by extracting C4 model elements, generating import YAML, and optionally pushing via the IcePanel REST API.

> **Two modes**: Online (API key present — check, import, drift detect) or Offline (no API key — generate YAML for manual import).

> **Output directory**: `icepanel-sync/` at project root. Always produces `c4-model.yaml` and `sync-report.md`.

---

## Workflow Detection

Detect which workflow the user wants based on their request:

| User Intent | Workflow | Requires API Key |
|-------------|----------|-----------------|
| "sync to icepanel", "icepanel import", "update icepanel" | **Full Sync** (Phase 0 → 1 → 2 → 3) | Optional (offline fallback) |
| "icepanel drift", "check icepanel", "icepanel status" | **Drift Report Only** (Phase 0 → 2 only) | Yes — stop if missing |
| "generate icepanel yaml", "export for icepanel" | **YAML Export Only** (Phase 0 → 1 only) | No |

**Drift Report Only** skips YAML generation and import — it queries IcePanel's current state, compares against architecture docs, and produces `icepanel-sync/drift-report.md`. This is useful for periodic checks without modifying IcePanel.

**YAML Export Only** skips all API interaction — just extracts and generates the import file.

> **Fidelity rule**: All data in the generated YAML comes from architecture docs. Never invent names, descriptions, technologies, or connections not present in the source files.

---

## Phase 0 — Resolve Environment

### Step 0.1 — Resolve Plugin Directory

**Step A — Glob (dev/local mode)**:

Glob for: `**/{sa-skills,solutions-architect-skills}/skills/architecture-icepanel-sync/ICEPANEL_IMPORT_REFERENCE.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-icepanel-sync/ICEPANEL_IMPORT_REFERENCE.md` from the result to get `plugin_dir`.

**Step B — Marketplace fallback**:

If Glob returns nothing, run:

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

If both steps fail, stop and report:
```
Cannot locate plugin directory. Ensure the plugin is installed correctly.
```

### Step 0.2 — Load Reference

Read `$plugin_dir/skills/architecture-icepanel-sync/ICEPANEL_IMPORT_REFERENCE.md` — this contains the YAML schema, type mapping, ID rules, and tag conventions. Keep these rules in context for the entire workflow.

### Step 0.3 — Check Prerequisites

Read these files (stop if any required file is missing):

| File | Required | Purpose |
|------|----------|---------|
| `docs/03-architecture-layers.md` | Yes | C4 diagrams (L1 Context + L2 Container) |
| `docs/components/README.md` | Yes | Component index (Type, Technology) |
| `docs/01-system-overview.md` | No | System name and description enrichment |
| `docs/05-integration-points.md` | No | Connection protocol enrichment |

If `docs/03-architecture-layers.md` is missing:
```
docs/03-architecture-layers.md not found.
Generate architecture documentation first with /skill architecture-docs.
```

If `docs/components/README.md` is missing:
```
docs/components/README.md not found.
Create component index first with /skill architecture-component-guardian sync.
```

### Step 0.4 — Detect Sync Mode

Check for IcePanel configuration:

1. Check environment variables: `ICEPANEL_API_KEY` and `ICEPANEL_LANDSCAPE_ID`
2. If not in env, check for `.env` file at project root — look for these two variables

**If both variables found** → Online mode. Confirm with user:
```
IcePanel API credentials detected. Running in online mode — will check existing objects and import/report drift.
Landscape ID: {ICEPANEL_LANDSCAPE_ID}
```

**If either variable is missing** → Offline mode. Inform user:
```
No IcePanel API credentials found. Running in offline mode — will generate import YAML only.
To enable online sync, set ICEPANEL_API_KEY and ICEPANEL_LANDSCAPE_ID in your environment or .env file.
```

### Step 0.5 — Create Output Directory

Cross-platform Bun helper (replaces `mkdir -p icepanel-sync` — works identically on Linux, macOS, Windows native, WSL, and Git Bash):

```bash
bun [plugin_dir]/scripts/ensure-dir.ts icepanel-sync
```

---

## Phase 1 — Extract C4 Model & Generate Import YAML

### Step 1.1 — Parse C4 Diagrams

Read `docs/03-architecture-layers.md` and extract all Mermaid C4 diagram blocks.

**Extract from `C4Context` blocks:**

Find code fences containing `C4Context`. For each element:

- `Person(id, "name", "description")` → Record as person (used for report only — not imported as model object)
- `Person_Ext(id, "name", "description")` → Record as external person
- `System(id, "name", "description")` → Record as internal system
- `System_Ext(id, "name", "description")` → Record as external system
- `Rel(from, to, "description", "protocol")` → Record as connection. The 3rd parameter (description) carries the verb plus any via-hop / topic / queue / async context; the 4th parameter (protocol) follows the canonical `<PROTOCOL>/<STYLE> [Action Type]` normal form per the Connection Naming Rule in `references/DIAGRAM-GENERATION-GUIDE.md`. The IcePanel `modelConnections.name` field stores the 4th-parameter value verbatim.

**Extract from `C4Container` blocks:**

Find code fences containing `C4Container`. For each element:

- `Container_Boundary(id, "name")` → Record the system boundary ID and name
- `Container(id, "name", "technology", "description")` → Record as app container
- `ContainerDb(id, "name", "technology", "description")` → Record as store container
- `ContainerQueue(id, "name", "technology", "description")` → Record as store container (subtype: message-broker). Exceptional use only — per the Infrastructure-as-via Rule, transit brokers collapse into edge encoding (description + protocol on `Rel()`), not a `ContainerQueue` node
- `Rel(from, to, "description", "protocol")` → Record as connection (merge with L1 connections, deduplicate). Same Connection Naming Rule applies — 4th parameter MUST be the canonical normal form

**Skip**: `%%{init: ...}%%` theme directives, `title` lines, comment lines starting with `%%`.

### Step 1.2 — Enrich from Component Index

Read `docs/components/README.md` and parse the 5-column table(s).

For each row `| # | Component | File | Type | Technology |`:
- Match `Component` name to a container extracted in Step 1.1 (fuzzy match on name)
- Enrich the container with:
  - **Type** → map to C4 type tag (one of 8 canonical types)
  - **Technology** → extract each `[Tech Version]` entry as a technology tag

If the README uses grouped tables with `### System Name` headers, preserve the system grouping to validate parentId assignments.

### Step 1.3 — Enrich from Integration Points (optional)

If `docs/05-integration-points.md` exists, read the integration tables.

For each integration entry, find the matching connection from Step 1.1 and enrich:
- Protocol details → more specific connection name
- Direction (Sync/Async) → connection direction hint
- Auth method → add as tag if relevant

### Step 1.4 — Validate Extracted Model

Run these checks before generating YAML. Collect all findings.

**FAIL checks (block generation):**
- No C4 diagrams found in `docs/03-architecture-layers.md`
- Zero systems extracted
- Zero containers extracted

**WARN checks (generate but report):**
- `Rel()` references an element ID not found in any `Person()`, `System()`, or `Container()` declaration
- A component in `docs/components/README.md` has no matching container in C4 diagrams
- A container has empty technology field
- Duplicate element IDs detected

If any FAIL check triggers, stop and report:
```
Validation failed — cannot generate import YAML:
- {list of FAIL findings}

Fix the architecture documentation and retry.
```

If only WARN checks trigger, cont