| name | description |
|---|---|
architectural-discipline |
Ensures all code adheres to the project's core architectural principles — consistency, minimalism, reliability, security, and testability. Use this skill when designing or modifying any system component, service, or feature to maintain architectural integrity and simplicity. |
This skill governs general software craftsmanship and architectural first principles. It is entirely agnostic to specific frameworks, platforms, or project implementations. It defines how we build software (clean architecture, SOLID principles, complexity management) rather than what we are building.
Scope Restriction:
- NO application-specific logic
- NO domain-specific rules
- NO syntax or formatting rules
Evaluate if a solution is proportional to the problem. Deliver the smallest viable solution.
- YAGNI & Scope Control: Implement exactly what's requested. Zero speculative extensibility. Treat feature creep as a design flaw.
- Leverage Existing Systems: Before building custom mechanisms, verify if the underlying platform natively supports it. Do not extend core systems for one-off needs.
- Duplication > Wrong Abstraction: Copying < 20 lines is better than premature abstraction. Inline code unless reused in 3+ places. Multi-file changes for simple tasks are a red flag.
- Build-Time > Runtime: Do not prescribe runtime processing for problems the build system can solve.
- Rule of 3 Steps: Reconsider any simple task that requires more than 3 implementation steps or introduces unprecedented patterns.
⚠️ Complexity Warning: If a solution violates these principles, explicitly state: "Complexity Warning: This solution introduces [X]. A simpler alternative would be [Y]." Let the user choose.
We mandate a regular, predictable, and pattern-based architecture.
- Industry standard design patterns: When a new pattern is required, strictly choose well-known architectural patterns and the original Gang-of-Four (GoF) design patterns.
- SOLID Principles: Strictly adhere to the Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion principles.
- Reuse existing patterns: New solutions MUST reuse existing project patterns as much as possible. Do not invent snowflake architectures.
- Convention over Configuration: We strongly favor standards and predictable naming/structuring conventions over explicit declarative configuration or custom wiring logic.
- Favor Standard APIs: Prefer built-in language and platform APIs over custom implementations or external dependencies.
- Fix the Architecture, Not the Symptoms: If a bug requires complex lifecycle hacking or feels like "whack-a-mole", the architecture is flawed. Resolve root structural issues rather than adding brittle patches.
- Delete Unnecessary Mechanisms: If a feature, component, or logic loop shouldn't exist in the first place, do not patch it. Remove it entirely.
- Functional Core, Imperative Shell: Keep business logic pure, strictly testable, and side-effect free. Isolate I/O, UI, and state management in orchestration layers.
- Environment Agnosticism: Core logic MUST NOT depend on platform-specific
globals (e.g.,
window, storage APIs). - Single Responsibility: Each module must have exactly ONE reason to change.
- No Cross-Cutting Logic: Do not embed cross-cutting concerns (telemetry, logging, UI formatting) within specialized domain modules.
- Maintain clean, acyclic dependency graphs. Avoid circular dependencies. Avoid layering violations.
- Linear Data Flow: Favor unidirectional data execution over complex, bidirectional state synchronization.
- Inversion of Control: Program against interfaces and inject dependencies. Maintain strictly acyclic dependency graphs.
- Pragmatic Coupling: Services explicitly designed to interface with the environment (networking, storage) may couple to platform APIs directly. Don't add abstraction layers just for purity.
- Fail Fast: Validate inputs at system boundaries immediately. Halt on invalid state.
- Idempotency: Design operations to be safe for multiple executions and ensure graceful degradation.
- Least Privilege & Zero Trust: Sanitize all inputs at entry points. Restrict component access to the absolute minimum necessary.
- Defense in Depth: Layer security controls. Never rely on a single validation or authorization point.
- Explicit Trust Boundaries: Clearly define where data crosses security zones (client/server, memory/storage, user input/system state).
- Test Isolation: Tests MUST NOT depend on external state, execution order, or side effects from other tests. Each test must be runnable in isolation.
- Pure Functions First: Design core logic as pure, deterministic functions. Side effects (I/O, state mutation) belong in thin wrapper layers.
- Test at Boundaries: Focus tests on module boundaries and public interfaces. Avoid testing internal implementation details.
- No Production Dependencies in Tests: Test code must not import production secrets, credentials, or environment-specific configuration.
- Halt on Terminal Side Effects: Operations that terminate normal execution flow (redirects, page reloads, process exits) MUST signal callers to immediately halt.
- Return Sentinel Values: Functions triggering terminal operations should
return a boolean or sentinel value. Callers MUST check and halt:
if (await init()) return; - No Code After Navigation: Never execute logic after triggering a redirect/reload. The execution context may be invalid or torn down.