C4 Model

c4-model

Produces a canonical-C4 LikeC4 model — Context and Container views by default, Deployment optional. Refuses every LikeC4 feature that would push the diagram beyond Simon Brown's canonical C4. The canonical-C4 features used here are stable across LikeC4 versions; re-validate with npx likec4 validate to confirm against your installed version.

What this skill makes

• A model.c4 file containing the specification + the model
• A <system>.c4 file scoped to the single system in focus
• A views.c4 file with one Context view and one Container view (optionally one Deployment view)
• A likec4.config.js file

What this skill refuses

The refusals are the point. An architect who wants full LikeC4 freedom should not use this skill.

Vocabulary

• Actor — a Person in C4 terms (a human role). Render outside the system boundary.
• External system — a system the team does not own. Render outside the system boundary.
• System — the one bounded product in focus. Exactly one per file.
• Container — a runnable/deployable unit inside the system in focus. Not a code class.
• Relationship — directed edge with a one-line description; the description is required.

Hard rules

1. Every relationship has a one-line description. No description → no edge. 2. Element names match what the architect confirmed in discovery. Don't translate, abbreviate, or pluralize. 3. No invented styling unless the architect explicitly requests it. 4. Exactly one `system` definition per `.c4` file.

Locked specification block

Use this specification block verbatim. Do not edit, extend, or rename.

specification {
  element actor {
    style {
      shape person
    }
  }
  element externalSystem {
    style {
      color secondary
    }
  }
  element system
  element container

  relationship uses
  relationship reads
  relationship writes
  relationship publishes
  relationship consumes

  tag open-question {
    style {
      color red
      border dashed
    }
  }
}

Open-question convention

For elements or relationships that exist but have unresolved details:

• Add the tag #open-question
• Prefix the description with OPEN Q<N>: matching the entry number in docs/architecture/open-questions.md
• The style renders red + dashed — visually obvious

Example:

container payments-service "Payments Service" "OPEN Q7: tech stack unconfirmed" {
  #open-question
}

The eight phases

Phase 1 — Intake

If docs/architecture/discovery-brief.md exists with CONFIRMED elements, use it directly — do not re-ask. Otherwise walk the architect through each element one at a time (one question per turn, same discipline as adr-discovery).

Phase 2 — Locate or scaffold

Glob **/*.c4 and **/likec4.config.*. Two cases:

• Files exist: read them. Identify the system in focus. Add to the existing model if the architect confirms scope.
• No files: scaffold model.c4, <system>.c4, views.c4, likec4.config.js at the architect's chosen path (default likec4/ at the repo root).

Phase 3 — Generate DSL

Three blocks in model.c4:

1. Specification — verbatim from the locked block above. 2. Model — actors and external systems at top level; containers nested inside the system block. See references/likec4-dsl-cheatsheet.md. 3. Views — in views.c4: one context view (the system + its actors + external systems), one container view (containers inside the system), optionally one deployment view.

Phase 4 — Canonical-C4 lint

Before validation, run the 11-item checklist:

Print PASS or FAIL with a numbered list of violations. Do not proceed on FAIL.

Phase 5 — Show diff, not apply

Render the proposed file changes as a diff, hunk by hunk. Per-hunk approval. Do not write files until the architect approves.

Phase 6 — Validate syntax

Run npx likec4 validate. If validation fails, surface the error to the architect — do not auto-fix.

Phase 7 — Render guidance

Tell the architect how to view the diagram. Do not start a server uninvited.

To view: npx likec4 start    # interactive browser at http://localhost:5173
To serve: npx likec4 serve   # static export

Phase 8 — Drift check

Glob ADR directories (docs/adr/, docs/decisions/, docs/architecture/decisions/, **/adr/*.md; also check legacy architecture/decisions/). For each ADR, compare component names mentioned in the text against names in the LikeC4 model. Report name mismatches as drift candidates — let the architect choose which side is canonical. Do not auto-rename either side.

DSL notes

For complex DSL questions (scoped views, extend, deployment specs), consult references/likec4-dsl-cheatsheet.md. For features that fall outside canonical C4, refer the architect to the upstream LikeC4 documentation rather than implementing them in this skill.

References

• references/likec4-dsl-cheatsheet.md — minimal cheat-sheet of canonical-C4 LikeC4 DSL
• references/canonical-c4-refusals.md — verbatim refusal scripts for the disallowed features
• The adr-discovery skill — upstream source of confirmed elements and relationships
• The adr-critique skill — downstream consumer for drift detection against ADRs

Canonical-C4 refusal scripts

When an architect asks for a LikeC4 feature outside the canonical-C4 subset, the skill refuses with one of these scripts. Use them verbatim — vague refusals leak into the model.

Component view

Architect says: "Add a component view inside the API container."

Refuse with:

Component views belong at a deeper level than ADRs work at. The C4 Component level is for inside-the-codebase structure — classes, modules, packages. ADRs record which containers exist and why, not their internal shape. If you need a class/module diagram, use a code-level tool (Mermaid in source, structurizr, or a code-graph generator) outside this skill.

Dynamic / sequence view

Architect says: "Show me the runtime sequence for placing an order."

Refuse with:

Dynamic views are not part of the canonical-C4 subset this skill produces. Sequence and runtime flows belong in a sequence diagram (PlantUML, Mermaid sequence) alongside the relevant ADR — not in the C4 model. The C4 model captures structure; sequences capture behavior. Keeping them in separate artifacts keeps both readable.

Custom element kind

Architect says: "Add a new element kind for lambda (or queue, database-table, etc.)."

Refuse with:

Canonical C4 has four element kinds: Person, Software System, Container, Component. Adding <kind> makes the diagram unrecognizable as C4. Use container and put <kind> in the technology attribute:

>

```c4

orders-queue = container "Orders Queue" "Decouples checkout from fulfillment" {

technology "<kind>"

}

```

Custom relationship kind

Architect says: "Add a mirrors (or replicates, proxies, caches) relationship kind."

Refuse with:

The canonical relationship vocabulary is small on purpose: uses, reads, writes, publishes, consumes. Pick the closest canonical kind and put the specifics in the one-line description:

>

```c4

primary -> replica "Mirrors writes asynchronously for read scaling"

```

>

A larger vocabulary makes every diagram a custom DSL that future readers must learn.

Custom style

Architect says: "Make the database containers blue and the queues yellow."

Refuse with:

Custom styling makes the diagram look like a corporate slide instead of a C4 diagram. Canonical C4 relies on shape (Person) and the externalSystem color distinction; adding more colors trains readers to look at the styling instead of the structure. If brand-styled diagrams matter more than canonicality, use LikeC4 directly outside this skill.

Nested systems

Architect says: "Put system B inside system A."

Refuse with:

C4 has Context (systems + actors) and Container (one system's internals). Nesting systems-in-systems collapses the levels and makes the diagram impossible to read at a glance. If A and B genuinely share scope, model them as one system with multiple containers. If they're independent, model them as two separate .c4 files and link via externalSystem references.

Multiple systems in focus

Architect says: "Put both the shop system and the analytics system in this one model."

Refuse with:

One system in focus per .c4 file is the canonical-C4 rule. The shop's containers and the analytics platform's containers are different "Container views" — two diagrams, not one. The connection between them is captured by an externalSystem reference in each file.

Standalone container or actor outside any system

Architect says: "Add a container at the top level, not inside a system."

Refuse with:

Containers are inside a system by definition. A free-floating container has no boundary — it's not a C4 element. If it's a third-party service, model it as externalSystem at the top level. If it's owned by the team, it belongs inside the system in focus.

Inline style on a single element

Architect says: "Just make this one container red."

Refuse with:

Per-element styling is the gateway to custom-styling everything. The only sanctioned per-element style is the #open-question tag for unresolved elements — that's enough signal. If the element needs more emphasis, the description should carry the message; styling is a decoration, not a decision.

How to deliver a refusal

• Open with the refusal — do not pad with "I understand," "great idea," or "good thinking."
• Cite the rule briefly.
• Offer the canonical alternative concretely (with a DSL snippet when possible).
• Do not negotiate the rule. Negotiation here is how the diagram becomes non-canonical over weeks.

If the architect insists on a refused feature after the alternative is offered, the appropriate response is: "That's outside this skill's scope. Use LikeC4 directly for that."

LikeC4 DSL cheat-sheet (canonical-C4 subset)

A minimal cheat-sheet of the LikeC4 DSL constructs c4-model uses. Anything not listed here is either disallowed (see canonical-c4-refusals.md) or out of scope for this skill — consult upstream LikeC4 documentation for those features.

Targets LikeC4 v1.47+.

File layout

likec4/
  model.c4         # specification + model
  <system>.c4      # system-scoped extension (optional split)
  views.c4         # context + container views
  likec4.config.js # minimal config

A single-file model is also valid; put everything in model.c4.

Specification (the locked block)

The specification is fixed by c4-model. See the locked block in SKILL.md. Do not add element kinds, relationship kinds, or styles beyond what is in that block.

Model — actors and external systems

model {
  customer = actor "Customer" "End user placing orders"

  payment-gateway = externalSystem "Payment Gateway" "Third-party charge processor"
}

• Identifier (customer) is lowercase, hyphenated.
• Display name is title-cased in quotes.
• The third quoted string is the one-line description (required).

Model — the system and its containers

Exactly one system block per file:

model {
  customer = actor "Customer" "End user placing orders"

  shop = system "Shop" {
    web = container "Web App" "User-facing frontend" {
      technology "Next.js"
    }
    api = container "API" "Backend HTTP API" {
      technology "Node.js / Fastify"
    }
    db = container "Primary Store" "Order and user data" {
      technology "Postgres"
    }
  }
}

• technology attribute holds the tech stack — do not invent a new element kind for it.
• Containers are nested inside the system block.

Relationships — five kinds only

customer -> shop.web "Browses catalog and places orders"

shop.web -> shop.api "Calls REST endpoints"
shop.api reads shop.db "Reads order and user data"
shop.api writes shop.db "Writes new orders"

shop.api publishes events "Emits OrderPlaced events"
analytics consumes events "Consumes OrderPlaced for reporting"

Allowed verbs in the canonical subset:

Every relationship requires the trailing quoted description. No description → no edge.

Tags

api = container "API" "Backend HTTP API" {
  technology "Node.js / Fastify"
  #open-question
}

Only the canonical-C4 tag open-question is in scope for this skill. Other tags are out of scope.

Views

Three view kinds permitted by this skill:

views {
  view context-of-shop of shop {
    include shop, customer, payment-gateway
    title "Context -- Shop"
  }

  view containers-of-shop of shop {
    include shop, shop.*
    title "Containers -- Shop"
  }

  // Optional, only on architect request:
  view deployment-of-shop of shop {
    include shop, shop.*
    title "Deployment -- Shop"
  }
}

• View identifiers follow the same lowercase-hyphenated convention.
• include lists exactly the elements the view should render.
• No style blocks inside the view — canonical styling only.

Config

likec4.config.js:

export default {
  name: "shop-architecture",
  sources: ["model.c4", "views.c4"],
};

Keep it minimal. Adding plugin configuration, custom themes, or output transforms is out of scope.

CLI commands the skill uses

Never run start or serve without architect consent; they bind a port.