This document defines canonical terms used throughout Code Principles. Components MUST use these terms consistently.
A technology-specific policy component that refines general engineering rules for a programming language, runtime, framework, platform, or closely related ecosystem.
An adapter does not define the primary project type.
Examples:
- TypeScript language adapter;
- Python language adapter;
- React framework adapter;
- Drupal framework adapter.
The permitted scope of structural change for the current task.
Canonical values:
preserve-existing— preserve established boundaries and patterns; make only required local changes;incremental-improvement— allow bounded refactoring around the affected area;redesign-allowed— allow broader restructuring when justified;greenfield— permit selection of new architecture;unknown— no reliable information.
The primary kind of software deliverable being created or modified.
Examples include application, library, service, plugin, CLI, data pipeline, worker, embedded system, or infrastructure tool.
Artifact type is not the same as language, framework, runtime, or repository type.
The primary project profile selected for the current task. It establishes default quality priorities and core skill modes.
The system normally selects one base profile and composes additional concerns through modifiers and adapters.
A point where ownership, trust, lifecycle, representation, or change responsibility differs.
Common boundaries include:
- external input to internal types;
- browser code to server code;
- application to database;
- domain logic to infrastructure;
- public API to private implementation;
- process to process;
- module to module;
- managed resource to owning component.
A boundary should not be introduced merely to create more layers.
The declared expectations for preserving existing consumers and observable behavior.
Compatibility may apply to:
- source API;
- binary ABI;
- serialized data;
- network protocol;
- database schema;
- CLI interface;
- configuration format;
- extension hooks;
- observable behavior.
The strength of evidence supporting a context decision.
Canonical values:
explicit;observed;inferred-high;inferred-low;unknown.
A requirement that limits acceptable solutions.
Constraints may concern:
- correctness;
- security;
- latency;
- throughput;
- memory;
- determinism;
- reliability;
- accessibility;
- compatibility;
- deployment;
- language or framework support.
A reusable, language-agnostic unit of engineering decision guidance with a coherent responsibility, explicit modes, conflicts, and verification rules.
A core skill is broader than a single slogan but narrower than a complete project profile.
A resolved engineering choice recorded in the policy because it materially affects implementation or review.
Examples:
- use strict boundary validation;
- preserve public API compatibility;
- keep state local to a component subtree;
- stream records instead of loading the complete dataset;
- preserve the existing modular architecture.
The ordered priority used to resolve competing instructions. Higher-precedence rules override lower-precedence defaults.
The density, interaction, volatility, and importance of business rules, invariants, workflows, and domain terminology.
Repository size, class count, or number of database tables does not by itself determine domain complexity.
The normalized set of facts, constraints, technologies, project characteristics, and confidence levels used by the orchestrator.
A set of selected rules, modes, adapters, modifiers, overrides, and prohibitions governing a task.
The audience and stability expectations of a software boundary.
Canonical values:
private-local;team-internal;organization-internal;external-integration;public-api;public-library;extension-platform;unknown.
Data that crosses a trust or representation boundary and cannot be assumed valid solely because internal code expects a type.
Examples:
- HTTP request data;
- files;
- database rows created by older versions;
- queue messages;
- webhook payloads;
- environment variables;
- command-line arguments;
- user-controlled browser state;
- third-party SDK responses.
An adapter that refines policy according to a framework's lifecycle, dependency model, state model, extension points, caching, rendering, or testing conventions.
A strong but defeasible engineering default. A heuristic should normally use SHOULD, not MUST.
Examples:
- prefer composition over inheritance;
- keep functions focused;
- favor immutable values;
- colocate behavior with the data it governs.
A contract whose consumers can normally be updated atomically within the same controlled change.
Internal does not necessarily mean unimportant, but it usually permits more refactoring freedom than a public contract.
An adapter that refines policy according to language semantics and ecosystem conventions.
Typical concerns include:
- static and runtime typing;
- ownership and resource lifetime;
- exceptions or explicit error values;
- concurrency;
- module visibility;
- packaging;
- binary compatibility;
- reflection and metaprogramming.
A named configuration of a skill representing a coherent policy variant.
Example modes for abstraction guidance:
conservative;balanced;extensible-library.
Modes allow the same skill to support different project contexts without duplicating the skill.
A cross-cutting policy component activated by a concern that applies to several project types.
A modifier changes priorities or rules without becoming the primary project profile.
Examples:
public-api;security-sensitive;memory-sensitive;real-time;accessibility-required.
A behavior, responsibility, or design ambition explicitly excluded from a component's scope.
Non-goals prevent broad prompts from expanding into universal architecture rules.
A rule expressed using MUST, SHOULD, or MAY and intended to affect model behavior.
Any externally detectable result of a component, including undocumented behavior that consumers may rely on.
Observed behavior matters especially for public APIs because of Hyrum's Law.
The policy-routing component that detects context, selects profiles, modifiers, and adapters, resolves conflicts, and produces a resolved policy.
The orchestrator is not a universal coding-style skill.
An explicit instruction that changes a selected default.
Overrides may come from:
- current user request;
- repository configuration;
- organization policy;
- task-specific constraints.
A general engineering idea used to guide decisions, such as KISS, DRY, YAGNI, information hiding, or dependency inversion.
A principle is not automatically a standalone skill.
A language-independent policy component describing priorities and default skill modes for a class of software project.
Examples:
reusable-library;fullstack-web-application;legacy-modernization.
The lifecycle condition of the software.
Canonical values:
prototype;greenfield;active-product;mature-system;legacy-modernization;maintenance-only;unknown.
A quality the conflicting rule is intended to preserve.
Examples:
- correctness;
- security;
- simplicity;
- maintainability;
- extensibility;
- performance;
- compatibility;
- reliability;
- testability;
- usability.
Conflict resolution should compare protected attributes rather than principle names alone.
An intentionally supported interface consumed outside the implementation's atomic change boundary.
A public API may include:
- functions, methods, classes, or types;
- HTTP or RPC contracts;
- events and messages;
- configuration files;
- plugin interfaces;
- CLI commands and output formats;
- database or serialized formats;
- documented extension behavior.
Language-level public visibility does not automatically mean stable public API.
The final, task-scoped composition of context, profile, modifiers, adapters, skill modes, overrides, conflicts, decisions, and prohibitions.
Validation performed while the program is running against actual data.
Static type checking does not replace runtime validation for external input.
The degree to which profile selection is automatic or user-controlled.
Canonical values:
automatic-with-visible-result;propose;manual.
A reusable instruction unit with a defined scope, metadata, activation rules, modes, conflicts, examples, and verification checklist.
The orchestrator is itself a skill of type orchestrator. Core engineering skills use type core-skill.
A configuration that selects a non-default mode for a skill.
A decision that materially affects architecture, compatibility, security, correctness, resource use, or future change cost and should therefore be visible or recorded.
The intentionally supported subset of externally accessible behavior governed by a compatibility policy.
Languages, frameworks, runtimes, package managers, databases, build tools, deployment environments, and other implementation technologies relevant to the task.
A concise explanation of significant context and policy choices shown to the user. It is not necessarily the complete internal resolved policy.
The authoritative machine-readable definition of one named engineering concept. It may represent a principle, heuristic, technique, method, property, law, pattern, or umbrella concept.
The generated human-readable view of the canonical principle registry. It is a project deliverable but not a second normative source.
The context-specific operational meaning selected by a Core Skill and resolved policy without changing the canonical definition.
A common but rejected application of a principle that the active policy explicitly prevents.
A runtime or content dependency on a Skill maintained outside this repository. Such dependencies are prohibited for normative project behavior.