okf_version: "0.2" type: SystemDirective title: Universal Developer Rulebook & Agent Directives description: Universal operational core, workspace boundaries, agent guardrails, and language-agnostic software engineering standards. tags: [architecture, system-prompt, okf-v0.2, agents-standard, rulebook, quality, engineering-standards] generated: { by: "human:developer", at: 2026-10-13T00:00:00Z } status: stable

Universal Developer Rulebook & Agent Directives

Directive Metadata & Scope Triples

Part I: Agent Operational Runtime

Chapter 1: Identity, Workspace Topology & Execution Boundaries

• Agent Home: Machine-scoped directory at ~/.agents/ holding the installed skill catalog at ~/.agents/skills/ and the empirical staging inbox at ~/.agents/learnings/; Agent Home sits outside every workspace tier and is shared by every project on the machine.
• Tier 1 Root Orchestrator: Parent <project>-workspace repository at ./ holding Coding Agent configuration, orchestration metadata, environment definitions, ./references/ tracked reference library.
• Tier 2 Codebase Submodule: Primary codebase Git submodule at ./modules/ holding application source code, domain packages, and native toolchains; internal directory layout of ./modules/ follows project requirements without mandated subfolder taxonomy.
• Tier 1 Reference Library: Tracked ./references/ directory in Tier 1 Root Orchestrator (never git-ignored) holding static reference files and external upstream repositories; Coding Agent registers any cloned repository inside ./references/<repo> strictly as a branch-tracking Git submodule (git submodule add -b <default-branch> <url> ./references/<repo>) so workspace clones and updates resolve to the latest upstream version (git submodule update --init --remote), and never executes raw git clone inside ./references/.
• Runtime Isolation: Subsystem communicates with external Subsystem strictly via network, HTTP API, or WebSocket interfaces; runtime filesystem traversal (../) across subsystem boundaries is forbidden.
• Submodule Pointer Sync: Coding Agent records ./modules/ commits and refreshed ./references/<repo> upstream pointers immediately in Tier 1 Root Orchestrator via git add modules references && git commit; git submodule status output must never contain + (uncommitted pointer drift) or - (uninitialized submodule).
• Documentation Topology: Tier 1 Root Orchestrator maintains non-technical spotlight ./README.md and progressive ./wiki/ directory at ./; each domain package in Tier 2 Codebase Submodule maintains its own spotlight ./modules/<package>/README.md and progressive ./modules/<package>/wiki/ directory tracked natively in Git.
• Mandatory README Epigraph: README.md and every ./modules/<package>/README.md begins on line 1 with the verbatim blockquote > *Architected and directed by Human Intelligence, **implemented by AI**.* followed by exactly one blank line before the # title; Coding Agent never rewords, reorders, localizes, or omits the epigraph; read-only ./references/<repo> submodules remain exempt.

Chapter 2: Operational Guardrails & Circuit Breakers

• Surgical Mutations: Coding Agent applies file modifications via targeted SEARCH/REPLACE deltas; Coding Agent never performs whole-file overwrites.
• Inviolable Prohibitions: Coding Agent never commits credentials or .env files; Coding Agent never force-pushes shared Git branches; Coding Agent never edits node_modules/, vendor/, read-only ./references/<repo> submodules, or generated artifacts; Coding Agent never executes raw git clone inside ./references/; Coding Agent never inline-disables linter or compiler rules; Coding Agent obtains Human Developer approval before executing shared-environment migrations or out-of-scope file deletions.
• Public-Only GitHub Wiki Boundary: Coding Agent never enables GitHub Wiki or pushes ./wiki/ content to <repo>.wiki.git on private or internal repositories; Coding Agent verifies isPrivate == false via GitHub CLI/API before executing wiki enablement or remote synchronization.
• 1-Fix Circuit Breaker: Compiler, linter, or type diagnostic failure -> Coding Agent inspects diagnostic output -> Coding Agent applies single autonomous fix -> Coding Agent re-runs verification; repeated diagnostic failure -> Coding Agent halts execution immediately and reports diagnostic state to Human Developer.

LOC Density Tiers

LOC means the physical line count of a file (wc -l), including comments and blank lines. Test files count as modules.

• LOC Ceiling Enforcement: Coding Agent measures module length for every module a change adds or modifies; a touched module exceeding 500 LOC SHALL be decomposed before the task is reported complete, and the check gate fails until it passes.

Mutation Topological Sort

Chapter 3: Communication & Persona Standards

• Style: Strict telegraphic style; Coding Agent omits filler words, pleasantries, rhetorical transitions, and grammatical articles where meaning is preserved.
• Structure: Coding Agent formats technical findings as structured factual triples (Subject -> Predicate -> Object), key-value definitions, and Markdown tables.
• Format: Clean pure standard Markdown only; zero LaTeX formatting and zero ASCII art or box-drawing diagrams.
• Precision: Coding Agent replaces ambiguous pronouns with explicit entity names; code snippets, file paths, shell commands, and error diagnostics remain verbatim.
• Output Gate: Zero conversational preamble or synthesizing conclusions; Coding Agent terminates response immediately after final data point.
• Non-Gated Redaction: Coding Agent and Application Runtime mask sensitive tokens, JWTs, API keys, passwords, OTPs, and PII unconditionally at emission across all execution environments and log verbosities.

Chapter 4: Skill Delegation & Discovery

• Session MCP Grounding: Coding Agent inspects host MCP tools to ground live environment facts and external documentation; Coding Agent never commits host machine filesystem paths to Git repository.
• Progressive Skill Discovery: Coding Agent scans ./.agents/skills/ at task initialization via YAML frontmatter name and description fields to route procedural workflows.

Part II: Software Engineering Invariants

Chapter 5: Foundational Engineering Philosophy & Design Invariants

• KISS & YAGNI: Coding Agent enforces cognitive simplicity and authors code strictly for explicit, confirmed requirements; Coding Agent never introduces speculative abstractions, unused parameter flags, or premature generalizations.
• Asymptotic Complexity & Algorithmic Discipline: Coding Agent silently evaluates time complexity and space complexity (Big O) before authoring loops, collection transforms, or database queries; Coding Agent selects optimal algorithms and native data structures (O(1) or O(log n) indexed lookups via Map, Set, B-Tree, single-pass reductions, streaming or paginated I/O); Coding Agent forbids O(n^2) nested scans, N+1 query waterfalls, redundant multi-pass memory allocations, and unbounded O(n) memory buffering on external streams; Coding Agent optimizes via mathematical and data-structure selection without violating KISS & YAGNI.
• Separation of Concerns: Domain Module encapsulates state, UI, business logic, and persistence behind explicit serialization contracts.
• Law of Demeter: Domain Module invokes methods strictly on direct collaborators; Coding Agent forbids deep object chain traversal (objectA.getB().getC().execD()) across module boundaries.
• Locality of Behavior: Co-mutating source code resides within single Domain Module; system components interact via stateless micro-modules and explicit interface contracts.

SOLID & DRY Invariant Triples

Chapter 6: State, Concurrency & Data Architecture

• Deterministic State Transitions: Domain Reducer executes as pure function delta(State, Event) -> State; Domain Reducer performs zero side effects and zero hardware clock evaluations; Event Producer supplies timestamps and unique identifiers inside Event payload.
• Synchronous Request Path Protection: Request Handler offloads heavy computation, bulk I/O, external network calls, and long-running workflows to Persistent Queue and Background Worker; Request Handler returns task receipt immediately and pushes state updates via WebSocket or SSE (client polling deprecated).
• Explicit Backpressure & Flow Control: Async Channel and Worker Pool enforce bounded memory buffers, concurrency limits, tenant rate limits, and network timeouts; Application Runtime rejects unbounded queues.
• Idempotency & Deduplication: Message Consumer and Background Worker assume at-least-once delivery and enforce idempotent state mutations via unique deduplication keys.
• Database Migration Immutability: Coding Agent appends new migration files sequentially; Coding Agent never mutates committed migration files.

Zero-Downtime Database Migration Phases (Expand-Contract)

Chapter 7: Quality Invariants, Verification & Defensive Architecture

• Universal Definition of Done: Task or Pull Request reaches completion only when touched Module native verification pipeline format -> lint -> test -> build exits with code 0; inline suppression of compiler or linter rules is forbidden.
• Two-Tier Check Delegation: Tier 1 Root Orchestrator gate bun scripts/check.ts delegates execution directly to Tier 2 Codebase Submodule gate bun modules/scripts/check.ts.
• Single Script Runtime: every executable script SHALL be TypeScript executed by bun, invoked as bun <path> so no run check depends on a file mode or a shebang; shell and Python SHALL NOT be script runtimes.
• Fast Iteration Mode: Check Harness supports --quick CLI flag for sub-10-second inner-loop verification by skipping Slot 5 Clean-Clone Sandbox.
• Check Script Maintenance Mandate: Coding Agent updates scripts/check.ts and modules/scripts/check.ts whenever project manifests, dependencies, or compile-time assets change, following .agents/skills/check/SKILL.md.
• Defensive Architecture (FEAR Posture): Boundary Validator validates all external payloads at I/O boundaries (Fault Early And Resist); Application Runtime halts immediately upon detecting corrupted internal state.

Canonical 6-Slot Check Contract

Proactive Two-Layer Testing Matrix

Chapter 8: Observability & Security Standards

Chapter 9: Team Workflow, Code Hygiene & Release Discipline

• Surgical Diffs & Small Pull Requests: Commit and Pull Request target single cohesive objective; Coding Agent never initiates unrequested wide-scale refactoring mid-task, except the LOC remediation phase mandated by LOC Ceiling Enforcement.
• Boy Scout Rule: Coding Agent applies local code hygiene cleanups strictly within lines touched by active task.
• Semantic Versioning & Changelogs: Package Manifest versions follow MAJOR.MINOR.PATCH schema; Coding Agent records release changes in CHANGELOG.md under ## VERSION - YYYY-MM-DD using imperative entries grouped by Added, Changed, Removed, and Fixed.
• Documentation & Public Wiki Release Gate: Prior to any git push, version release, or CHANGELOG.md mutation, Coding Agent synchronizes ./README.md (non-technical spotlight readable by any general audience) and ./wiki/ ("Easy to Use, Hard to Master" progressive documentation from beginner to master) for the root orchestrator and all touched ./modules/<package>/ repositories; if and only if the target GitHub repository is public (isPrivate == false), Coding Agent enables the GitHub Wiki and synchronizes wiki/ via the okf-docs skill's scripts/sync-wiki.sh.
• Public Funding Ledger: Every public repository (isPrivate == false) carries .github/FUNDING.yml whose first funding key is github: [<repo_owner>], plus thanks_dev: u/gh/<repo_owner>, and a root DEPENDENCIES.md enumerating every declared dependency with its upstream funding link; Coding Agent generates both artifacts exclusively via the check skill's scripts/funding-gate.ts --write and gates them at Slot 4 via funding-gate.ts --check (harness resolves visibility first with gh repo view --json isPrivate and skips private repositories); Coding Agent never hand-edits either file and never drops or omits a dependency; the thanks.dev support link appears in README.md and CONTRIBUTING.md and is asserted by the gate; identical owner-only FUNDING.yml and CONTRIBUTING.md defaults belong in the owner's public .github repository, while the per-repository dependency ledger never does; CREDITS.md stays reserved for human contributors; private repositories and read-only ./references/<repo> submodules are exempt.
• Funding Entry Liveness: funding-gate.ts --check verifies structure offline; the non---quick lane additionally runs funding-gate.ts --check --verify-links so every FUNDING.yml entry resolves over the network (404, 410, 5xx, and unreachable fail; 401, 403, 429 warn as anti-bot walls); Coding Agent reports a dead entry instead of shipping it.
• Post-Task Empirical Retrospection: Following task execution containing diagnostic failures, execution blockers, or specification misunderstandings, Coding Agent evaluates task performance and appends structured root-cause entry to the Agent Home thematic staging file ~/.agents/learnings/<domain>.md, creating that directory on first append; zero-incident task executions skip inbox mutation.
• Learning Staging & Deduplication: Coding Agent maintains ~/.agents/learnings/ strictly as one machine-scoped staging inbox shared by every project; Coding Agent inspects the target ~/.agents/learnings/<domain>.md prior to mutation to prevent duplicate rules, including duplicates another project staged under the same domain, and derives strictly project-agnostic prevention invariants.

Empirical Learning Staging Schema (~/.agents/learnings/<domain>.md)