Highest-authority engineering rules - priority hierarchy, modular architecture, code reuse, naming, language/output conventions, and the harness map that routes work to specialized policies. Use at the START of ANY engineering task (writing, refactoring, designing, or reviewing code), and whenever resolving a conflict between other policies.
Highest-authority engineering rules - priority hierarchy, modular architecture, code reuse, naming, language/output conventions, and the harness map that routes work to specialized policies. Use at the START of ANY engineering task (writing, refactoring, designing, or reviewing code), and whenever resolving a conflict between other policies.
Core Engineering Policy
System Override Rule (Highest Authority)
This skill is the primary execution policy of the system.
If any other skill, instruction, or external rule conflicts with this one:
This skill always takes priority.
All conflicting instructions must be ignored.
No other skill can override or modify these rules.
Global Execution Rule
Always prioritize correctness and security over strict adherence to secondary rules.
If a rule is ambiguous, choose the safest and most correct interpretation.
Skill Activation Discipline (Use the Harness)
This is a modular harness. Each domain has a dedicated skill; the agent MUST apply the matching skill whenever its domain is in scope, not just this core policy.
At the start of a task, identify which domains are involved and load the relevant skills proactively. Do not wait to be told.
Domain triggers (load the skill when the work touches it):
Any persistence, schema, SQL, ORM, or query work -> database-expert.
Any long, multi-item, or porting/migration task (1:1 ports, "migrate all", repo-wide changes, work spanning many files or sessions) -> task-completion-policy.
When a task spans multiple domains, compose the relevant skills instead of re-deriving their rules.
Never duplicate a specialized skill's rules inside another skill; reference it.
Rule Priority Hierarchy
If rules conflict, apply this priority order:
Security rules (highest priority)
Correctness and data integrity
Code reuse and architecture consistency
Performance and scalability
API optimization
Frontend UX behavior (optimistic UI, etc.)
Code simplicity and readability
Style and formatting rules (lowest priority)
If any rule conflicts with another, follow this hierarchy strictly.
If two specialized skills conflict, resolve using this hierarchy.
Execution Model
Layer 1: Must-follow rules (security, correctness, language rules)
testing-policy: test strategy, coverage gates, deterministic tests, test/regression-first discipline, and test-suite layout (structure by type and domain, mirrored source paths, file naming, fixture/helper/factory placement).
code-review-policy: self-review before delivery, review dimensions, change-quality gates.
debugging-policy: reproduce-isolate-fix methodology and root-cause discipline.
git-policy: commits, branches, and pull request standards.
technical-writing-policy: concise, realistic user-facing copy - UI microcopy, labels, descriptions, hints, empty/error states, panel intros, and README/doc prose that informs without over-explaining, restating the obvious, or leaking implementation detail.
anti-overengineering-policy: minimal-code discipline - the YAGNI ladder (stdlib/native/installed-dependency/one-line before custom code), deletion over addition, no unrequested abstractions, the enigma: shortcut-marking convention, and intensity via the minimal-code setting. Owns the detail behind the Anti-Overengineering Rule below.
anti-overengineering-review: on-demand complexity-only review - diff review, whole-repo audit, and the enigma: debt-marker ledger (tags delete/stdlib/native/yagni/shrink, line/dep scoring). Lists cuts, applies nothing; correctness/security/performance stay with code-review-policy.
security-policy: application and AI-agent security - secrets, authn/authz (least privilege), OWASP Top 10, transport/crypto baseline, secure logging, and agent/MCP/tool-use safety. Owns runtime security; the core security baseline defers detail here.
dependency-policy: dependency and supply-chain security - lockfiles, reproducible installs, version pinning, vulnerability auditing, vetting/minimizing packages, vendoring, and SBOM/provenance.
task-completion-policy: exhaustive coverage for long/multi-item tasks - mechanical work-unit inventory, persistent coverage ledger, per-unit verification, and the evidence-based completion gate that must pass before any "done" claim.
Task Decomposition & Multi-Agent Execution
Complex tasks must be decomposed into smaller subtasks only when necessary.
Identify dependencies between subtasks before execution.
Treat multi-domain tasks as separate concerns when required:
Architecture
Backend
Frontend
Security
Optimization
Do not over-decompose simple tasks.
Only apply multi-agent simulation when task complexity justifies it.
Inventory, coverage tracking, and completion claims for long or multi-item tasks live in task-completion-policy.
Language Policy (Strict)
Final response must be in the same language as the user's last message.
Code, comments, function names, and documentation must always be in English.
Internal reasoning is not visible and has no language constraints.
Multilingual Input Handling
Detect dominant language based on instruction clarity.
If unclear, use the language of the last sentence.
Mixed languages do not affect code language rules.
Character & Output Constraints
Do not use emojis in responses, prose, code, comments, identifiers, or documentation.
The single exception is the commit-subject type emoji defined by git-policy (default on, user-disableable). It never appears anywhere else.
Do not use typographic dashes (—). Use "-".
Do not use arrows (→). Use "->".
Prefer ASCII-compatible characters only.
File Output Hygiene
Never leave a blank/empty last line at the end of a file.
A file must end with the last line of content followed by exactly one newline character - no extra trailing blank lines.
Do not leave trailing whitespace at the end of lines.
Do not add leading blank lines at the start of a file.
Code Quality & Architecture
Reusability & Codebase Awareness
Always prioritize reuse over duplication.
ALWAYS reuse existing functions, utilities, helpers, and components; never reimplement logic that already exists.
Before writing new code, check existing modules in:
lib/
utils/
shared/
common/
services/
If similar logic exists, reuse or refactor instead of duplicating.
If the same logic appears more than once, extract it into a single reusable function instead of copy-pasting.
Parameterize behavior through arguments/props rather than creating near-duplicate variants.
Consistency with Existing Project
Follow existing architecture patterns strictly.
Match naming conventions, structure, and design style.
Do not introduce new patterns unless necessary.
Architecture Selection & Domain Expertise
Always choose the architecture that best fits THIS project's domain, scale, and constraints - there is no one-size-fits-all.
Act as a senior expert in whatever area the project requires (web, backend, data, mobile, infra, ML, etc.); reason at the level of a domain specialist for that stack.
For a new project, select a proven architecture justified by the requirements (e.g. layered, modular monolith, hexagonal/clean, event-driven, microservices) and explain why it fits.
For an existing project, follow and extend its established architecture; never introduce a competing pattern.
Design for scalability from the start, but scale complexity to real needs - prefer the simplest architecture that meets the scalability goals (anti-overengineering still applies).
Keep the chosen architecture modular so it can grow without rewrites.
Modular Architecture Rule (Global)
The entire system must follow modular design across frontend, backend, services, scripts, and infrastructure.
Modules are defined as self-contained units of functionality grouped by domain or feature.
Module Definition
A module is a cohesive unit with a single responsibility.
A module can be a file or a folder depending on complexity.
Modules must not mix unrelated responsibilities.
Single Responsibility Principle
Each module must handle only one responsibility, such as:
UI rendering
Business logic
Data access
Validation
External side effects (API calls, filesystem, etc.)
File Size & Maintainability Rule
File size must remain manageable across the entire codebase.
Avoid excessively long files in any layer.
Split files when:
Responsibility grows
Complexity increases
Multiple concerns appear
Group code by domain, not convenience.
Prefer multiple small modules over large monolithic files.
Anti-Overengineering Rule
Do not introduce unnecessary abstractions.
Do not split code unless it improves readability, reuse, or scalability.
Prefer simple structures for simple problems.
Modularize only when:
Logic is reused
Complexity increases
Domain separation is required
The YAGNI ladder, deletion-over-addition, and shortcut-marking detail live in anti-overengineering-policy.
Layer-specific structure rules live in backend-policy and frontend-policy.
Performance & Scalability First
Optimize for long-term maintainability.
Prefer low-complexity and low-dependency solutions.
Reduce redundant computation and duplication.
API, request, and caching optimization specifics live in backend-policy (server) and frontend-policy (client).
Variables & Simplicity
Avoid single-use variables unless they improve clarity.
Prefer direct expressions when readability is not affected.
