cxc-dev-architecture

Dev-Architecture — Module Boundaries & Structural Integrity

C0/C1 work (small local patches): See dev §0.0 Work Classifier + §0.1 Patch Fast-Path before reading references.

dev is canonical: dev §0.2 Rule Classes, §3 Verification Gate, and §5 Safety Rules apply to all work governed by this skill. Read the dev skill first for universal development discipline before applying architecture rules.

Enforces architectural rules that prevent structural decay: circular dependencies, implicit coupling, barrel abuse, and misplaced validation. These rules are mechanical — an AI coding agent can follow them without subjective judgment.

Severity mapping (dev §0.2): Severity: CRITICAL/HIGH ⇒ STRICT; MEDIUM ⇒ DEFAULT.

Modular References

External/current architecture evidence

Architecture rules in this skill are local and mechanical. When an architectural decision depends on current framework guidance, cloud/provider reference architecture, package deprecation, platform limits, or public source evidence, read the active search skill and follow its query-rewrite, source-fetch, and evidence-status rules. Use browser verification only after candidate URLs exist.

1. Module Boundaries

Structural Decision Gate

Severity: HIGH Rule (ARCH-DECISION-01): When changing module boundaries, seams, layering, shared packages, or public exports above C0/C1 local-patch scope, name the structural decision before editing.

Required decision record, inline in the plan or in the repo's ADR/source-of-truth file:

• Context: what pressure forced the boundary change.
• Rejected alternative: at least one plausible option not chosen, with why.
• Chosen move: split, extract, merge, invert dependency, introduce adapter, or change public export.
• Consequences: new dependency direction, public contract impact, migration cost, and follow-up verification.

Route durable, surprising, hard-to-reverse, or cross-team choices to the repo's ADR/current-architecture source of truth instead of leaving them only in chat. dev-scaffolding owns where those durable docs live; this skill owns the boundary decision content.

Pre-Change Structural Map

Severity: HIGH Rule (ARCH-MAP-01): Before recommending or applying a split/extract/merge for boundary work above C0/C1, produce a compact structural map from code evidence.

Map fields:

• Core modules involved.
• Direct dependents and dependencies.
• Current and intended dependency direction.
• Public boundaries touched (index.*, package exports, route/API contracts, CLI entry points).
• Blast-radius class (local module, feature, package, app, cross-app/monorepo).

Do not choose the fix first and backfill the map. The map is the evidence that tells whether the right move is colocation, extraction, dependency inversion, adapter introduction, or no structural change.

Layered Architecture Boundaries

When to Split a Module

Canonical file-size rule: >400 LOC -> split (DEFAULT). Deviations require a stated reason.

Banned Patterns

Module SSOT (Single Source of Truth)

Every concept, constant, type, or configuration value MUST have exactly one canonical owner module.

Deep Modules and Seams

Use this vocabulary when deciding whether an abstraction earns its keep:

Frontend depth means small props/events hiding complex rendering, state management, data transformation, or integration behavior. One adapter usually means hypothetical indirection; two adapters, or a near-term second adapter, is evidence of a real seam. Do not expose internals only for tests; test through the public interface or add a boundary-owned diagnostic hook with production value.

2. Circular Dependency Detection & Prevention

Severity: CRITICAL Rule: No circular dependency may exist between modules. Every detected cycle MUST be resolved before merge.

Required Agent Workflow

Detection commands are ecosystem-specific. See references/circular-dependencies.md for command templates, examples, and verification details.

Banned Patterns

Fix Guidance

3. Implicit Coupling Taxonomy

Severity: CRITICAL Rule: Every coupling instance in a code review MUST be classified by type. Coupling severity determines whether the code can merge.

Coupling Types (ordered by severity, worst first)

Review Decision Matrix

See references/coupling-taxonomy.md for examples, detection signals, refactoring patterns, and banned review responses.

4. Boundary-Only Defensive Programming

Severity: CRITICAL Rule: Validation and defensive checks belong ONLY at system boundaries. Internal module boundaries MUST trust their callers.

Ownership split: placement (validation happens at the boundary, nowhere else) is owned by this section; what the validation schema enforces (content/policy) is owned by dev-security §1.

Validation Location Matrix

Banned Patterns

Allowed Defensive Checks (Exceptions)

Fix Guidance

5. Barrel/Re-export Discipline

Severity: HIGH Rule: Barrel files (index.ts/index.js/init.py) are ONLY allowed at public boundaries — package APIs and feature public boundary exports. Internal convenience barrels are banned.

Barrel Policy Matrix

See references/barrel-discipline.md for import examples, tree-shaking details, ESLint enforcement, and the safe barrel template.

6. Review Integration

Architecture Review Checklist (for code-reviewer)

When reviewing any PR that adds/modifies module structure, verify:

• No new circular dependencies — run madge --circular or equivalent
• Layer violations — no upward imports (infra->domain OK, domain->infra BLOCKED)
• Coupling classified — any new cross-module dependency has coupling type identified
• No CRITICAL/HIGH coupling without justification — Content/Common/Control coupling blocked
• Barrel files — no new internal barrels; existing public barrels use named exports only
• Validation placement — new validation is at system boundary, not internal functions
• Module size — new/modified modules under 400 LOC
• No "utils" growth — shared code placed in domain-specific module, not catch-all utils
• Dependency direction — dependencies point inward toward Domain: outer layers depend on inner layers (Presentation/Application/Infrastructure -> Domain), and inner layers never import outward
• No lazy-import hacks — no require() inside function body to hide circular deps

Automated Enforcement (CI Recommendations)

On Windows without Unix tools, use PowerShell equivalents: Get-ChildItem -Recurse, Measure-Object, Select-String.

Cross-Skill References

• Observability: Trace emission at module boundaries is a production/long-lived-runtime concern (DEFAULT there, not universal). See dev-backend/references/core/observability.md for the canonical OTel setup.
• Security: Validate at every trust/process/external boundary (HTTP entry, IPC, file/CLI input, third-party responses). Intra-trust-domain module calls follow §4 boundary-only defense — do not re-validate already-trusted data. See dev-security/SKILL.md for input validation and auth patterns.
• Coupling and boundary review: see dev-code-reviewer.
• Debugging escalation for boundary or coupling issues: see dev-debugging.
• Infrastructure architecture and deployment boundaries: see dev-devops.

Quick Decision Trees

"Should I create a new module?"

Does the code serve a distinct responsibility? 
  NO  -> Keep in existing module
  YES -> Is it used by 3+ other modules?
    NO  -> Co-locate with primary consumer
    YES -> Create dedicated module with clear interface

"Is this coupling acceptable?"

What type? (see taxonomy above)
  Content/Common -> BLOCK, refactor now
  Control/Stamp/External -> BLOCK unless tech-debt ticket created
  Temporal -> ALLOW with documentation
  Sequential/Functional -> ALLOW

"Where does this validation go?"

Is the data source external (HTTP, file, queue, DB, user input)?
  YES -> Validate here (boundary)
  NO  -> Is this a security-critical path?
    YES -> Validate (defense in depth)
    NO  -> Trust the type system, no validation needed

Structural Index Concept (ARCH-INDEX-01, DEFAULT)

Source: sol research (wednesday-solutions/ai-agent-skills AST dependency graph).

Instead of reconstructing a module map for every task, maintain a lightweight structural index that agents can query:

• Use cxc map <dir> for on-demand symbol-level maps (already shipped).
• For larger repos, consider a persistent dependency graph artifact (e.g., dependency-cruiser JSON, Nx project graph, or a custom SQLite index).
• The index should track: module → exports, module → imports, symbol → callers.
• Freshness: re-generate on significant structural changes (new modules, moved files).
• Query before editing: "what depends on this module?" should be answerable from the index without a full codebase scan.

This is a guidance concept, not a shipped tool. The agent should check for existing index artifacts before running ad-hoc scans.

Architecture Conformance Tests (ARCH-CONFORMANCE-01, DEFAULT)

Source: sol research (HoangNguyen0403/agent-skills-standard compliance auditing).

Architecture rules that exist only as prose are invisible to CI. For C3+ work where boundary violations would cause real harm:

• Generate tool-specific configs from architecture decisions (dependency-cruiser rules, ESLint boundaries plugin, Nx enforce-module-boundaries, Go depguard).
• Include at least one allowed-edge and one forbidden-edge test fixture.
• The CI gate should FAIL on new violations while allowing a baselined set of legacy violations (ratcheting: new cycles fail, old ones are migrated).
• Return a machine-readable report (JSON or SARIF) that agents can consume.