agentleFS
l-gevityl-gevity/l-gevity-skills/.claude/skills/architecture-as-code/SKILL.md

architecture-as-code

Skill88 starsChanged 3 days agoMITView on GitHub

Stack-agnostic pattern for declaring and enforcing subsystem boundaries via per-subsystem architecture configs merged into import-graph linter rules. TRIGGER when designing/auditing dependency-rule enforcement, deciding what a per-subsystem file should say, placing a rule, debugging a forbidden edge, or extending the assembler. Consume explicit `Enforcement` handoffs from `architecture-guidelines` or `morphogenetic-architecture` by turning enforceable dependency constraints into architecture config rules. SKIP routine edits inside a governed subsystem. For stack implementations see `architecture-as-code-javascript` or `architecture-as-code-python`.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When introducing a new subsystem on a stack that supports this pattern, write its architecture file (plus any afferent rules in the parent) …

    line 206
  2. Distinctive:

    When designing or auditing rules, emit a coder-facing decision record:

    line 270

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Architecture-as-Code (Pattern)

Scope. Stack-agnostic pattern: file format, discovery, assembly, and rule-placement discipline that turn a directory tree into an enforced dependency graph. Implementation is delegated to a per-stack linter (e.g. eslint-plugin-boundaries for JS, import-linter for Python). Does NOT prescribe what the graph should look like — that's architecture-guidelines and morphogenetic-architecture. Does NOT govern code style — that's your project's coding-style convention.

Input Contract. Consume only explicit Enforcement handoffs from architecture-guidelines or morphogenetic-architecture (or an equivalent architecture decision). Translate the named constraint into subsystems entries and forbidden edges. Do not restate or reinterpret architecture doctrine here; if a constraint is not enforceable as an import/dependency rule, return Decision: Defer or Reject rule. Aspect coverage — every subsystem in the governed set must use the mechanism — is never an edge rule: return Decision: Reject rule with Next action: coverage check (defect-shift-left); the mechanism's exclusivity edges are the rule.

Core Directives

  1. Subsystem = directory (or a single file for a facade). Files belong to a subsystem by living under its path / dotted path.
  2. One optional config file per subsystem — declaratively lists the subsystems it contains (its subsystems entries) and its outbound rules. Repo root has one too, same structure.
  3. A subsystem knows itself, not its context. Its own file governs internals (sub-tiers, layering) and outbound dependencies ("what I import") — never inbound ("who imports me") or its place in the wider system, which it does not and should not know. Mechanically: only <own-prefix>-*, specific <own-prefix>-x names, and the anonymous * may appear; any other subsystem name is a violation.
  4. Composition lives on the level that does the composing. Constraints between a subsystem and its peers (afferent — "who may import me" — and cross-subsystem sibling-isolation) live higher up. Constraints among a subsystem's own sub-tiers (internal layering, sub-tier sibling-isolation) live in its own file. Higher-level rules accumulate.
  5. Every subsystem with rules ends with a catch-all bucket. Files matching no declared subsystem are invisible to the linter and silently bypass forbidden edges. A <dir>/** (or whole-package) entry MUST be last in subsystems. This holds inside a subsystem, where the siblings it must not shadow sit at the same depth.
  6. The same catch-all at the repository root inverts. Most import-graph linters match a pattern against a file's path ancestors by default, so a root-level ** matches at the shallowest segment and claims files that deeper, more specific subsystems already own. Declaration order does not break the tie — the catch-all wins from last position against dozens of specific subsystems. Declare the root's real files explicitly with exact-file matching (mode: 'file', single = true) instead.
  7. Coverage is two independent gates: the registry and the rule's file scope. A registry that classifies every file proves nothing when the emitted rule block runs on a subset of the linted source set. The emitted rule MUST cover every linted source file. Narrowing that scope is a bypass, and it is invisible — the tool reports zero violations either way.
  8. A file-existence rule is what catches an undeclared directory. Dependency rules judge edges; a file with no imports, or one reached only from a script tag, template, or config, has no edge to judge. Emit the stack's "every file must match a declared subsystem" rule at error severity next to the dependency rules.
  9. Recursion via discovery. Assembler walks the tree; deeper files are processed first.

1. File schema

Each architecture config declares two optional top-level arrays:

subsystems: [ ... ]   # one entry per subsystem
forbidden:  [ ... ]   # one entry per dependency edge

Concrete encoding (.mjs, .toml, .yaml, …) is stack-specific. Schema is not. Most subsystems don't need their own file — they're declared once in the subsystems list higher up in the tree.

components is accepted as a deprecated alias for subsystems while consumers migrate: an assembler reads subsystems first, falls back to components with a warning, and rejects a file that carries both. This is the expand step of an expand/contract change (evolutionary-database-design); the contract step — dropping the alias — lands in a later major release once no known consumer file still writes it, never on a date.

[!NOTE] <own-prefix> is the shared prefix of the subsystem names a config file declares — e.g. core- for core-facade, core-tier1, core-other. A single-entry subsystem just uses the bare name.

2. Subsystems — declared as patterns

FieldRequiredPurpose
nameyesSubsystem id referenced from forbidden edges.
patternyesSelector for the subsystem's files (stack-specific syntax).
mode / singlenoSwitches from ancestor matching to exact-file / exact-module matching (a facade, a repository-root file).
capturenoPath-segment captures for parametric rules.

Order matters within a file: narrowest first (file-mode → sub-directories → catch-all). Across files: deeper-first (so a subsystem's own file overrides its ancestor's catch-all).

[!IMPORTANT] Matching mode decides what ordering can do. Order only breaks ties between candidates the matcher considers together. Under the default ancestor matching a shallow pattern wins at its own shallow segment, before any deeper subsystem is tried — so a shallower entry declared last still beats a specific entry declared first. A file that a shallower pattern would otherwise swallow needs exact-file matching, not a better position in the list. Repository-root files always do.

3. Forbidden — dependency edges

{ from: <spec>, to: <spec>, except?: [...], except_to?: [...], why: '...' }
from / to acceptsMeaning
"service"Single subsystem name.
["app", "service"]Multiple subsystem names.
"*"Every registered subsystem.
"core-*"Prefix wildcard — every subsystem starting with core-.
{ captured = ... }Parametric (uses captures from a capture-enabled entry).

except subtracts from a wildcard from; except_to from a wildcard to. Strings in either may be prefix wildcards. why is the violation message emitted to developers.

Canonical examples (encoding-neutral)

# Afferent — higher level. Only the orchestrator may import the facade.
{ from: '*', except: ['orchestrator', 'core-*'], to: 'core-facade',
  why: 'Only the orchestrator may import the core facade.' }

# Efferent — own file. Self-contained.
{ from: 'core-*', to: '*', except_to: ['core-*'],
  why: 'Core purity: no imports outside the core subsystem.' }

# Internal layering — own file. Sub-tier names share the prefix.
{ from: 'core-tier3', to: 'core-tier1',
  why: 'Tier 3 must go through tier 2; direct tier-1 access is forbidden.' }

# Parametric — higher level. Sibling sub-domains may not import each other.
{ from: { type: 'domain-handler', captured: { domain: '*' } },
  to:   { type: 'domain-handler', captured: { domain: '!{from.captured.domain}' } },
  why:  'Cross-domain import: extract shared helpers to a sibling shared/ subsystem.' }

# Aspect ownership — higher level. Only the mechanism reaches the aspect's
# internals; the provider SDK behind it is package policy (stack-specific).
{ from: '*', except: ['audit-mechanism'], to: 'audit-internal-*',
  why: 'The audit aspect has one mechanism; every other subsystem routes through it.' }

4. Where each rule lives

Rule typeLives in
Afferent ("who may import me?")Higher level (composer).
Efferent ("what may I import?")Own file.
Cross-subsystem sibling-isolationHigher level (composer).
Internal layeringOwn file.
Sub-tier sibling-isolationOwn file.

Higher-level rules accumulate. Place each rule where the composition it expresses lives — sub-tier sibling-isolation in the subsystem's own file (it composes its sub-tiers); encapsulation between the subsystem and its peers higher up (where the subsystem is composed with peers).

[!IMPORTANT] A subsystem's own file MUST reference only its own-prefix names (<own-prefix>-* or <own-prefix>-x) and *. Naming any other subsystem is a violation — that knowledge belongs higher up.


5. The assembler

A small script, run at lint time, discovers every per-subsystem file deeper-first, concatenates their subsystems and forbidden entries, expands wildcards against the live registry, emits the stack's native lint config, and invokes the linter. The generated config is a git-ignored build artifact; the per-subsystem files are the source of truth. Read references/assembler.md before building, adapting, or debugging an assembler or its emitted rule block: it holds the pipeline, the fields every emitter must forward, the rule block's file scope, and where the file-existence rule is emitted.


6. Timing — rules first for new subsystems

When introducing a new subsystem on a stack that supports this pattern, write its architecture file (plus any afferent rules in the parent) before its implementation code. Catching the first wrong import on day 1 is the point; retrofitted rules either rubber-stamp accidents or trigger unbounded refactors. The PR that adds the subsystem contains the rules first, the implementation second.

Spike escape-hatch. Code explicitly marked as a spike or throwaway prototype may skip rules. The spike must be deleted or rewritten rules-first before merging to main — a spike that crosses the merge boundary ungoverned becomes the next round of "we'll add the rules later" code that never gets the gate.


7. Anti-patterns + pre-merge audit

Anti-patternFix
A subsystem's own file names another subsystem.Move higher, or rewrite with <own-prefix>-* + *.
Hardcoded list of "all other subsystems".Use '*' + except / except_to.
Renaming a subsystem without updating consumers.Use prefix wildcards (<prefix>-*) so renames stay local.
Subsystem has rules but no catch-all bucket.Add the whole-subsystem entry as the last subsystems row.
A file carries both subsystems and components.Keep one key; the assembler rejects both — two lists for one registry is the same-scope duplication that hides drift.
Dynamic / unresolved imports evade rules.Make imports static and resolvable, or document the loophole and ban the dynamic style where possible.
Rule block scoped to a subset of the linted source set.Apply the rule to every linted source file; the registry cannot fire on a file the rule never sees.
A ** catch-all at repository root in ancestor/folder matching mode.It captures files at the shallowest segment and overrides specific subsystems regardless of order. Declare the root's files with file-mode entries instead.
Relying on dependency rules to catch an undeclared directory.Use the file-existence rule; a file with no imports has no edge to judge.
Assembler maps a subset of the schema's subsystem fields.Forward every field, mode included — a dropped field silently deletes that part of the schema.

Before merge:

  • No other-subsystem name appears in any subsystem's own architecture file.
  • subsystems ordered narrowest-first; constrained subsystems end with a catch-all.
  • New architecture files use subsystems; the components alias appears only in files not yet migrated, and never beside subsystems.
  • The emitted rule block's file scope equals the linted source set.
  • Every file at repository root belongs to a declared subsystem.
  • The assembler forwards every field the subsystem schema defines, mode included.
  • Every name in forbidden resolves to a registered subsystem, and every subsystem pattern matches at least one file.
  • Lint violation count matches baseline (or new violations reflect intentional changes).
  • The subsystem registry the assembler builds lists every governed subsystem: it is the population an aspect coverage check enumerates.

[!IMPORTANT] A passing lint is not evidence of coverage. The violation count does not move when a directory the linter cannot see is added — it stays at zero because the question was never asked. The scope, root-file, and assembler-field checks above all fail this way, so verify them against the generated config and a positive signal: count the files the emitted rule classifies and compare that with the file count of the linted source set. Reading the lint result proves nothing about either gate.

[!NOTE] The "no other-subsystem name" check is mechanical — a small AST/TOML walk over each architecture file could enforce it as a meta-lint. Until then, the manual checklist is the gate.


8. Output Contract

When designing or auditing rules, emit a coder-facing decision record:

Scope:          <repo / package / subsystem path>
Stack:          JavaScript | Python | Other
Input:          <Enforcement handoff consumed, or none>
Decision:       Add config | Update config | Reject rule | Defer | Blocked
Config files:   <eslint.architecture.mjs / architecture.toml / generated config>
Subsystems:     <names or patterns added/changed>
Forbidden edges:<from -> to rules added/changed>
Verification:   <lint command / meta-lint / Not run + reason>
Next action:    <specific edit, rule, test, or owner question>

9. Implementations

This skill defines the pattern. Concrete implementations live in sibling skills:

StackConfig fileLint toolSkill
JavaScripteslint.architecture.mjsESLint + eslint-plugin-boundariesarchitecture-as-code-javascript
Pythonarchitecture.tomlimport-linter (over Grimp)architecture-as-code-python

Adapting to a new stack: pick an import-graph linter that supports forbidden edges between named subsystem sets, then write a small assembler that emits its native config. Everything in §§ 1–6 transfers; only step 4 of §5 (emit) and step 5 (invoke) are stack-specific.

10. See also

  • architecture-guidelines — first-principles rules this pattern enforces.
  • morphogenetic-architecture — the placement, locality, interface-direction, and static-topology rationale this enforces.
  • defect-shift-left — §6.2 (ADR → executable architectural rule) names this pattern.
  • gate-lifecycle — keeps a rule proven and its effective scope measured after it lands.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.