| name | architectural-principles |
| description | Shared architectural and engineering principles for planning, implementing, and reviewing code. Single source of truth for SOLID, 12-factor, DRY, KISS, and defensive design. Referenced by Martian Manhunter, Cyborg, and Wonder Woman.
|
| user-invocable | false |
| disable-model-invocation | true |
| last_reviewed | "2026-04-28T00:00:00.000Z" |
Architectural Principles
These are the engineering principles that define what good software looks like in
this factory. Every agent that plans, implements, or reviews code references this
skill. When these principles are updated (manually or via Oracle), changes
propagate to all consuming agents automatically.
This skill defines the what — what good software looks like. Individual agent
skills (implementation-standards, review-criteria, planning-methodology) define
the how — how each agent applies these principles in their specific role.
SOLID Principles
Apply contextually based on your role:
Single Responsibility — Each module, class, or function should have one
reason to change. When planning: decompose tasks so each touches one concern.
When implementing: don't let a file grow to do two unrelated things. When
reviewing: flag files that mix concerns (e.g., a route handler that also
formats emails).
Open/Closed — Software entities should be open for extension but closed for
modification. Prefer adding new files over modifying existing ones when adding
new behavior. When the plan calls for "add a new type of X," check whether the
existing code has an extension point (plugin pattern, strategy pattern, registry)
before modifying the core.
Liskov Substitution — Subtypes must be substitutable for their base types.
If the codebase uses interfaces or abstract classes, new implementations must
honor the full contract — not just the method signatures, but the behavioral
expectations.
Interface Segregation — Don't force consumers to depend on methods they
don't use. Prefer small, focused interfaces over large ones. When planning API
endpoints, each endpoint should do one thing.
Dependency Inversion — Depend on abstractions, not concretions. When the
codebase uses dependency injection, follow that pattern. When it doesn't, don't
introduce it — but do keep high-level modules independent of low-level details
by using clear interfaces between layers.
12-Factor App Principles
Externalize configuration — Values that vary by environment (URLs, ports,
feature flags, API keys, thresholds) belong in environment variables or config
files, never hardcoded in source. If a value could be different in staging vs.
production, it's config.
Treat backing services as attached resources — Databases, caches, queues,
email services are swappable resources. Access them through configuration, not
hardcoded connection strings.
Store nothing in the process — Don't rely on in-memory state persisting
between requests. If state needs to persist, put it in a database or cache.
Logs as event streams — Write logs to stdout. Don't manage log files, log
rotation, or log shipping in application code.
Dev/prod parity — Keep development, staging, and production as similar as
possible. Don't use different databases, different queues, or different patterns
across environments.
DRY — Don't Repeat Yourself
When you see the same logic in two or more places, extract it — but only when the
duplication is real, not coincidental. Two pieces of code that happen to look
similar today but serve different purposes and will evolve differently are not
duplication. Three similar lines of code is better than a premature abstraction.
The test: If changing the logic in one place means you MUST change it in the
other place too (or risk a bug), it's real duplication. Extract it.
KISS — Keep It Simple
The simplest solution that meets the requirement is the right solution. Don't
add layers of abstraction "in case we need them later." Don't use a design
pattern because it's clever — use it because the code demands it.
Complexity is justified only when:
- The requirement is genuinely complex (not when the solution is over-engineered)
- The simpler alternative has a concrete, articulable drawback (not hypothetical)
- The complexity pays for itself in the current iteration (not in a future one)
Migration-First Mindset
Schema changes get migrations. Always. Never work around a schema change with
field mappings, SQL aliases, computed columns, or application-level transforms.
Migrations are not scary — they are the correct, reversible, auditable way to
evolve a schema.
When planning a task that touches data models:
- Include a migration file in the task's file list
- Include migration runner registration (npm scripts, CLI commands)
- Include type/schema updates that match the migration
When implementing: write the migration first, run it, then update the
application code to match.
When reviewing: if a schema change exists without a migration, flag it as
critical.
Configuration Over Hardcoding
Values that could vary by environment, change over time, or differ between
deployments go in configuration — not in source code. This includes:
- API URLs, ports, hostnames
- Feature flags and toggles
- Rate limits, timeouts, retry counts
- Email addresses, notification templates
- Lists of allowed/blocked values
The test: If changing this value requires a code change and redeployment,
it should be config instead.
Data-Driven Over Code-Driven
If something is a list of things that could change — categories, status values,
permission levels, supported formats — make it data, not an enum or switch
statement in code. Data can be updated without redeployment. Code requires a
release.
This doesn't mean every list needs a database table. A config file or constants
file that's easy to update is often sufficient. The point is: don't scatter
these values across business logic where they're hard to find and update.
Defensive Design
Validate at system boundaries — Every input from users, external APIs,
webhooks, or file uploads should be validated. Internal function calls between
trusted modules don't need redundant validation.
Handle edge cases — What happens with empty inputs? Missing data? Null
values? Zero-length arrays? Concurrent access? The code should handle these
gracefully, not crash.
Fail with useful errors — When something goes wrong, the error message
should tell the user (or developer) what happened, what they can do about it,
and where to look for more information. "Internal server error" helps nobody.
"Failed to connect to payment processor — check STRIPE_API_KEY is set" helps
everybody.
Never silently swallow errors — Catch blocks that ignore exceptions are
bugs. If you catch an error, either handle it meaningfully, re-throw it, or
log it. Empty catch blocks are never acceptable.
