Core Philosophy
Relevant source files
The following files were used as context for generating this wiki page:
OCX is built on the fundamental "Copy. Paste. Own." principle, inspired by the ShadCN model. Unlike traditional package managers that hide code within node_modules, OCX copies components directly into the project's .opencode/ directory. This approach ensures that users have full ownership, auditability, and the ability to customize code freely without being restricted by upstream package updates.
The project enforces high standards of software engineering through two primary sets of guidelines: the "5 Laws of Elegant Defense" for internal logic and the "5 Pillars of Intentional UI" for frontend development. These philosophies are designed to prevent "AI slop"—generic, algorithmically generated code and interfaces—by prioritizing intentionality, simplicity, and bold design choices.
Sources: README.md:104-108, examples/registry-starter/AGENTS.md:6-8, workers/kdco-registry/files/skill/frontend-philosophy/SKILL.md:10-13
The 5 Laws of Elegant Defense
This philosophy serves as the primary guideline for all internal logic, data flow, and backend development. It focuses on creating "Elegant Simplicity" where code guides data so naturally that errors become structurally impossible.
1. The Law of the Early Exit (Guard Clauses)
Deep nesting is identified as a primary source of hidden bugs. Developers must handle edge cases, null values, and errors at the top of functions using guard clauses. This keeps the "happy path" flat and readable.
Sources: workers/kdco-registry/files/skill/code-philosophy/SKILL.md:14-18, examples/registry-starter/AGENTS.md:32-34
2. Make Illegal States Unrepresentable (Parse, Don't Validate)
Instead of repeatedly checking data validity throughout the application, data should be parsed into trusted, typed states at the boundaries (e.g., API entry points or CLI input). Once data enters internal logic, its structure should guarantee its validity.
Sources: workers/kdco-registry/files/skill/code-philosophy/SKILL.md:20-24, examples/registry-starter/AGENTS.md:42-45
3. The Law of Atomic Predictability
Functions should be "Pure" wherever possible, meaning the same input always produces the same output. Hidden mutations and global state changes (such as void functions modifying external variables) are discouraged in favor of returning new data structures.
Sources: workers/kdco-registry/files/skill/code-philosophy/SKILL.md:26-30, examples/registry-starter/AGENTS.md:55-58
4. The Law of "Fail Fast, Fail Loud"
Silent failures are considered a major source of downstream complexity. If a system encounters an invalid state, it must halt immediately with a descriptive error rather than attempting to "patch" or continue with corrupted data.
Sources: workers/kdco-registry/files/skill/code-philosophy/SKILL.md:32-35, examples/registry-starter/AGENTS.md:69-72
5. The Law of Intentional Naming
Code should be self-documenting, reading like an English sentence. Clear naming of variables and functions should reveal intent so effectively that comments become unnecessary for explaining basic logic.
Sources: workers/kdco-registry/files/skill/code-philosophy/SKILL.md:37-40, examples/registry-starter/AGENTS.md:81-84
Logic Flow Diagram
The following diagram illustrates how the 5 Laws transform raw input into a trusted internal state.
The 5 Pillars of Intentional UI
For frontend and visual development, OCX adheres to a philosophy of "Intentional UI" to avoid generic aesthetics.
| Pillar | Principle | Practice |
|---|---|---|
| Typography | Typography with Character | Avoid system defaults (Inter, Arial). Use distinctive typefaces. |
| Color | Committed Color & Theme | Use bold, dominant colors with sharp contrast; avoid rainbow gradients. |
| Motion | Purposeful Motion | Focus on high-impact moments; one orchestrated animation > many transitions. |
| Composition | Brave Spatial Composition | Use generous negative space or controlled density; embrace asymmetry. |
| Atmosphere | Atmosphere & Depth | Layer visual richness using textures, noise, and gradient meshes. |
Sources: workers/kdco-registry/files/skill/frontend-philosophy/SKILL.md:10-40
Implementation in Software Architecture
The OCX codebase applies these philosophies through specific architectural patterns, notably in its plugin system and data handling.
Boundary Parsing with Zod
OCX utilizes Zod schemas extensively to implement the "Parse, Don't Validate" law. For example, in the workspace-plugin.ts, complex markdown plans are validated at the boundary using PlanSchema.safeParse().
// Sources: [workers/kdco-registry/files/plugin/workspace-plugin.ts:200-210]
const result = PlanSchema.safeParse(candidate);
if (!result.success) {
return {
ok: false,
error: formatZodErrors(result.error),
hint: skillHint,
};
}
Profile and Config Cascade
The configuration system follows a strict hierarchy to ensure predictability. Settings cascade from global defaults to profile-specific overrides and finally to local project configurations. This allows for isolated "Ghost Mode" or "Profile Mode" where developers can work in repositories without modifying them.
Sources: AGENTS.md:188-204, README.md:144-152
Auditability and Integrity
Every component added via OCX is version-pinned and verified via SHA-256 hashes. This implements a form of "Defensive Architecture" where the state of the local .opencode directory is always verifiable against the registry lockfile.
Sources: README.md:92-102, README.md:195-200
Philosophy Enforcement
The project treats these philosophies as mandatory requirements for AI agents and human contributors alike. Agents are instructed to load specific "philosophy skills" (e.g., code-philosophy or frontend-philosophy) using the skill tool before starting any implementation task.
Mandatory Verification Checklist
Before any task completion, the following must be verified:
- Guard Clauses: Are all edge cases handled at the top?
- Parsed State: Is data parsed into trusted types at the boundary?
- Purity: Are functions predictable and free of hidden mutations?
- Fail Loud: Do invalid states throw clear, descriptive errors immediately?
- Readability: Does the logic read like an English sentence?
Sources: workers/kdco-registry/files/philosophy/AGENTS.md:3-13, workers/kdco-registry/files/skill/code-philosophy/SKILL.md:43-49
Summary
The Core Philosophy of OCX centers on ownership through local copying and reliability through structural enforcement. By combining the "ShadCN model" of component distribution with the "5 Laws of Elegant Defense" and "5 Pillars of Intentional UI," the project ensures that code remains maintainable, auditable, and visually distinct, even when generated or managed by AI agents.