Overview
The role-system-architect skill codifies exactly one boundary per layer: which module may import which; cross-layer edges are rejected in CI by AST validation before any call-site is preserved by a barrel facade.
When to Use
- When decomposing oversized monolithic god-files or tangled modules into domain submodules.
- When establishing or auditing layer boundaries (e.g. Domain -> Application -> Infrastructure -> Presentation).
- When detecting and eliminating circular import dependencies in Python, TypeScript, or Go codebases.
- When designing distributed or decoupled event-driven architectures (pub/sub, event brokers, CQRS).
- When making high-stakes technical decisions requiring structured trade-off analysis and rollback criteria.
- When standardizing public REST, GraphQL, or RPC API contracts across services.
When NOT to Use
- When implementing specific isolated bug fixes or localized unit tests (use
development/role-software-engineer).
- When writing E2E browser automation scripts or load test harnesses (use
development/role-qa-automation-engineer).
- When managing CI/CD deployment pipelines, container runtimes, or Kubernetes manifests (use
devops/role-devops-sre-engineer).
- When auditing codebases for external security exploits or vulnerabilities (use
cybersecurity/role-security-engineer).
Deterministic Dispatch Matrix
| Architectural Challenge / Objective |
Delegated Child Skill |
Primary Architectural Output |
| Enforcing strict layer boundaries and preventing circular imports |
development/ast-architectural-guard |
AST import graph validator and CI boundary gate |
| Breaking down oversized monolithic god-files (>800 lines) |
development/godfile-ratchet-split |
Domain submodules behind barrel facade with line-cap ratchet |
| Standardizing REST/RPC resource modeling and pagination |
development/api-design |
OpenAPI spec, uniform envelope, and idempotent endpoints |
| Evaluating complex technical options under uncertainty |
mindset/decision-frameworks |
Weighted decision matrix with explicit rollback trigger |
| Designing asynchronous, decoupled pub/sub event systems |
development/event-driven |
Message schema definitions, dead-letter queues, idempotent consumers |
| Deconstructing novel problems down to fundamental truths |
mindset/first-principles-thinking |
Core constraint decomposition and assumption audit |
Workflow
Phase 1: Domain Mapping & Boundary Definition
- Identify core entities, bounded contexts, and trust boundaries.
- Formulate explicit layer hierarchy (Presentation -> Application Service -> Domain Model -> Infrastructure).
- If tackling novel architectural constraints, dispatch to
mindset/first-principles-thinking.
Phase 2: Invariant Specification & Decision Framing
- Quantify architectural constraints (max module line count, prohibited cross-domain imports, latency budgets).
- For architectural trade-offs (e.g. monolithic vs microservices, SQL vs NoSQL, sync vs async), dispatch to
mindset/decision-frameworks to document non-negotiable tradeoffs and rollback criteria.
- Design API contracts and resource models using
development/api-design.
Phase 3: Modular Decomposition & Refactoring
- When decomposing monoliths, dispatch to
development/godfile-ratchet-split.
- Extract domain logic into focused leaf modules while preserving all existing exports through a backward-compatible barrel facade.
- Lock module line count using a ratchet test that fails if lines increase in subsequent commits.
Phase 4: AST Guard & Dependency Verification
- Dispatch to
development/ast-architectural-guard to build automated import rule checkers.
- Assert zero circular dependencies and verify that lower layers never import from upper layers.
- If async decoupling is required, structure event emitters and consumers via
development/event-driven.
Phase 5: Architectural Gate Enforcement & Handoff
- Integrate architectural lint checks into the CI test pipeline.
- Verify that 100% of existing call-sites remain intact without deprecation friction.
- Deliver comprehensive architectural specification with machine-verifiable gates.
Anti-Rationalization Table
| Architecture Excuse |
Flawed Rationalization |
Required Architectural Discipline |
| "Circular imports are fine if deferred" |
"Python lets us import inside the function body." |
Deferred imports mask structural design rot. Refactor shared types into leaf contracts. |
| "A 3,000-line file is easier to navigate" |
"Everything is in one place, just use Cmd+F." |
Monoliths hide tight coupling and cause merge contention. Split into submodules with ratchet caps. |
| "We will document the architecture in Confluence" |
"Engineers just need to read the wiki." |
Architectural rules in wikis are ignored. Enforce boundaries with automated AST checks in CI. |
| "Microservices will solve our spaghetti code" |
"Separating into repositories forces modularity." |
A distributed monolith is strictly worse. Achieve clean bounded contexts in code first. |
| "We don't need an event schema registry" |
"Just send JSON payloads; consumer can unpack it." |
Schema-less events cause runtime drift. Define strict versioned event contracts. |
Implementation Examples
AST Layer Boundary Checker (Python)
import ast
import os
import sys
from typing import Dict, List, Set
class LayerBoundaryValidator(ast.NodeVisitor):
"""Enforces that domain models never import infrastructure or presentation modules."""
FORBIDDEN_IMPORTS: Dict[str, Set[str]] = {
"domain": {"infrastructure", "presentation", "api", "controllers"},
"application": {"presentation", "controllers"},
}
def __init__(self, current_layer: str):
self.current_layer = current_layer
self.violations: List[str] = []
def visit_Import(self, node: ast.Import):
for alias in node.names:
self._check(alias.name, node.lineno)
self.generic_visit(node)
def visit_ImportFrom(self, node: ast.ImportFrom):
if node.module:
self._check(node.module, node.lineno)
self.generic_visit(node)
def _check(self, module_name: str, lineno: int):
forbidden = self.FORBIDDEN_IMPORTS.get(self.current_layer, set())
root_pkg = module_name.split(".")[0]
if root_pkg in forbidden:
self.violations.append(
f"Line {lineno}: Layer '{self.current_layer}' cannot import '{module_name}'"
)
def validate_layer(file_path: str, layer: str) -> List[str]:
with open(file_path, "r", encoding="utf-8") as f:
tree = ast.parse(f.read(), filename=file_path)
validator = LayerBoundaryValidator(layer)
validator.visit(tree)
return validator.violations
if __name__ == "__main__":
sample_code = "from infrastructure.database import db_conn\nclass User: pass"
tree = ast.parse(sample_code)
v = LayerBoundaryValidator("domain")
v.visit(tree)
assert len(v.violations) == 1
print("Layer boundary validation successful:", v.violations[0])
Ratchet Line-Ceiling Test (Bash)
#!/usr/bin/env bash
set -euo pipefail
TARGET_MODULE="src/services/order_service.py"
MAX_ALLOWED_LINES=350
ACTUAL_LINES=$(wc -l < "$TARGET_MODULE")
echo "Checking ratchet line ceiling for $TARGET_MODULE..."
echo "Current: $ACTUAL_LINES lines | Max Allowed: $MAX_ALLOWED_LINES lines"
if [ "$ACTUAL_LINES" -gt "$MAX_ALLOWED_LINES" ]; then
echo "ERROR: Ratchet ceiling breached! $ACTUAL_LINES > $MAX_ALLOWED_LINES."
echo "Decompose functions into submodules before committing."
exit 1
else
echo "SUCCESS: Module complies with architectural ratchet limits."
fi
Verification Checklist
npm install -g cli-tool
1---2name: role-system-architect3description: Use when orchestrating system architecture, modular decomposition, domain4 boundary enforcement, AST layer guards, and long-term evolutionary design decisions.5domain: development6author: oyi777version: 1.0.08category: development9tags:10- architecture11- system-design12- ast-guard13- modularity14- refactoring15license: MIT16subdomain: system-architecture17triggers:18- system architect role19- domain boundaries20- circular dependency21- god file split22- layer boundary audit23- monolith decomposition24- ast import guard25- modular decomposition26- architecture decision27- domain modeling28metadata:29 source: https://skillmd.com/skills/oyi77/role-system-architect30---3132## Overview3334The `role-system-architect` skill codifies exactly one boundary per layer: which module may import which; cross-layer edges are rejected in CI by AST validation before any call-site is preserved by a barrel facade.3536## When to Use3738- When decomposing oversized monolithic god-files or tangled modules into domain submodules.39- When establishing or auditing layer boundaries (e.g. Domain -> Application -> Infrastructure -> Presentation).40- When detecting and eliminating circular import dependencies in Python, TypeScript, or Go codebases.41- When designing distributed or decoupled event-driven architectures (pub/sub, event brokers, CQRS).42- When making high-stakes technical decisions requiring structured trade-off analysis and rollback criteria.43- When standardizing public REST, GraphQL, or RPC API contracts across services.4445## When NOT to Use4647- When implementing specific isolated bug fixes or localized unit tests (use `development/role-software-engineer`).48- When writing E2E browser automation scripts or load test harnesses (use `development/role-qa-automation-engineer`).49- When managing CI/CD deployment pipelines, container runtimes, or Kubernetes manifests (use `devops/role-devops-sre-engineer`).50- When auditing codebases for external security exploits or vulnerabilities (use `cybersecurity/role-security-engineer`).5152## Deterministic Dispatch Matrix5354| Architectural Challenge / Objective | Delegated Child Skill | Primary Architectural Output |55|---|---|---|56| Enforcing strict layer boundaries and preventing circular imports | `development/ast-architectural-guard` | AST import graph validator and CI boundary gate |57| Breaking down oversized monolithic god-files (>800 lines) | `development/godfile-ratchet-split` | Domain submodules behind barrel facade with line-cap ratchet |58| Standardizing REST/RPC resource modeling and pagination | `development/api-design` | OpenAPI spec, uniform envelope, and idempotent endpoints |59| Evaluating complex technical options under uncertainty | `mindset/decision-frameworks` | Weighted decision matrix with explicit rollback trigger |60| Designing asynchronous, decoupled pub/sub event systems | `development/event-driven` | Message schema definitions, dead-letter queues, idempotent consumers |61| Deconstructing novel problems down to fundamental truths | `mindset/first-principles-thinking` | Core constraint decomposition and assumption audit |6263## Workflow6465### Phase 1: Domain Mapping & Boundary Definition66671. Identify core entities, bounded contexts, and trust boundaries.682. Formulate explicit layer hierarchy (Presentation -> Application Service -> Domain Model -> Infrastructure).693. If tackling novel architectural constraints, dispatch to `mindset/first-principles-thinking`.7071### Phase 2: Invariant Specification & Decision Framing72731. Quantify architectural constraints (max module line count, prohibited cross-domain imports, latency budgets).742. For architectural trade-offs (e.g. monolithic vs microservices, SQL vs NoSQL, sync vs async), dispatch to `mindset/decision-frameworks` to document non-negotiable tradeoffs and rollback criteria.753. Design API contracts and resource models using `development/api-design`.7677### Phase 3: Modular Decomposition & Refactoring78791. When decomposing monoliths, dispatch to `development/godfile-ratchet-split`.802. Extract domain logic into focused leaf modules while preserving all existing exports through a backward-compatible barrel facade.813. Lock module line count using a ratchet test that fails if lines increase in subsequent commits.8283### Phase 4: AST Guard & Dependency Verification84851. Dispatch to `development/ast-architectural-guard` to build automated import rule checkers.862. Assert zero circular dependencies and verify that lower layers never import from upper layers.873. If async decoupling is required, structure event emitters and consumers via `development/event-driven`.8889### Phase 5: Architectural Gate Enforcement & Handoff90911. Integrate architectural lint checks into the CI test pipeline.922. Verify that 100% of existing call-sites remain intact without deprecation friction.933. Deliver comprehensive architectural specification with machine-verifiable gates.9495## Anti-Rationalization Table9697| Architecture Excuse | Flawed Rationalization | Required Architectural Discipline |98|---|---|---|99| "Circular imports are fine if deferred" | "Python lets us import inside the function body." | Deferred imports mask structural design rot. Refactor shared types into leaf contracts. |100| "A 3,000-line file is easier to navigate" | "Everything is in one place, just use Cmd+F." | Monoliths hide tight coupling and cause merge contention. Split into submodules with ratchet caps. |101| "We will document the architecture in Confluence" | "Engineers just need to read the wiki." | Architectural rules in wikis are ignored. Enforce boundaries with automated AST checks in CI. |102| "Microservices will solve our spaghetti code" | "Separating into repositories forces modularity." | A distributed monolith is strictly worse. Achieve clean bounded contexts in code first. |103| "We don't need an event schema registry" | "Just send JSON payloads; consumer can unpack it." | Schema-less events cause runtime drift. Define strict versioned event contracts. |104105## Implementation Examples106107### AST Layer Boundary Checker (Python)108109```python110import ast111import os112import sys113from typing import Dict, List, Set114115class LayerBoundaryValidator(ast.NodeVisitor):116 """Enforces that domain models never import infrastructure or presentation modules."""117 118 FORBIDDEN_IMPORTS: Dict[str, Set[str]] = {119 "domain": {"infrastructure", "presentation", "api", "controllers"},120 "application": {"presentation", "controllers"},121 }122 123 def __init__(self, current_layer: str):124 self.current_layer = current_layer125 self.violations: List[str] = []126 127 def visit_Import(self, node: ast.Import):128 for alias in node.names:129 self._check(alias.name, node.lineno)130 self.generic_visit(node)131 132 def visit_ImportFrom(self, node: ast.ImportFrom):133 if node.module:134 self._check(node.module, node.lineno)135 self.generic_visit(node)136 137 def _check(self, module_name: str, lineno: int):138 forbidden = self.FORBIDDEN_IMPORTS.get(self.current_layer, set())139 root_pkg = module_name.split(".")[0]140 if root_pkg in forbidden:141 self.violations.append(142 f"Line {lineno}: Layer '{self.current_layer}' cannot import '{module_name}'"143 )144145def validate_layer(file_path: str, layer: str) -> List[str]:146 with open(file_path, "r", encoding="utf-8") as f:147 tree = ast.parse(f.read(), filename=file_path)148 validator = LayerBoundaryValidator(layer)149 validator.visit(tree)150 return validator.violations151152if __name__ == "__main__":153 sample_code = "from infrastructure.database import db_conn\nclass User: pass"154 tree = ast.parse(sample_code)155 v = LayerBoundaryValidator("domain")156 v.visit(tree)157 assert len(v.violations) == 1158 print("Layer boundary validation successful:", v.violations[0])159```160161### Ratchet Line-Ceiling Test (Bash)162163```bash164#!/usr/bin/env bash165set -euo pipefail166167TARGET_MODULE="src/services/order_service.py"168MAX_ALLOWED_LINES=350169170ACTUAL_LINES=$(wc -l < "$TARGET_MODULE")171172echo "Checking ratchet line ceiling for $TARGET_MODULE..."173echo "Current: $ACTUAL_LINES lines | Max Allowed: $MAX_ALLOWED_LINES lines"174175if [ "$ACTUAL_LINES" -gt "$MAX_ALLOWED_LINES" ]; then176 echo "ERROR: Ratchet ceiling breached! $ACTUAL_LINES > $MAX_ALLOWED_LINES."177 echo "Decompose functions into submodules before committing."178 exit 1179else180 echo "SUCCESS: Module complies with architectural ratchet limits."181fi182```183184## Verification Checklist185186- [ ] Domain boundaries and layer hierarchies formally identified.187- [ ] No circular imports exist between modules or packages.188- [ ] Monolithic god-files disassembled into focused leaf modules behind barrel facades.189- [ ] Automated AST lint rules integrated into CI to prevent boundary regression.190- [ ] Architectural decisions documented with explicit trade-offs and rollback criteria.191- [ ] Backward compatibility verified for all existing import paths and public interfaces.192193`npm install -g cli-tool`