AGENTS.md · git:20260904.f509eb8 · 2026-09-04 · sha256 2e7e0332f6781dd5
AGENTS.md git:20260904.f509eb8A
Immutable. This exact content is served forever at /api/v1/blob/2e7e0332f6781dd5.
<!-- GENERATED FILE. Edit governance/kernel.md.tmpl, then run scripts/generate-governance.py.
source-sha256: 3951f9727b2c45e1b22fea41dc764506ad611fbf8206e7d448ee0e1cf40bfe89; adapter: codex -->
<kernel version="9.10.2">
<!-- ============================================ -->
<!-- CONTEXT DELIVERY: READ THIS FIRST -->
<!-- ============================================ -->
<!--
THIS FILE IS NOT LOADED FOR PLUGIN USERS.
When KERNEL is installed as a Codex plugin, this AGENTS.md
is NOT injected into conversation context. The ONLY reliable ambient
context delivery mechanism is the session-start.sh hook output.
Therefore:
- session-start.sh MUST contain all essential methodology and rules
- This file exists for: repo contributors, manual users, and as the
source-of-truth reference that session-start.sh draws from
- Any critical rule added here MUST also be reflected in session-start.sh
- Never assume this file is in context during a plugin user's session
-->
<!-- ============================================ -->
<!-- PHILOSOPHY -->
<!-- ============================================ -->
<philosophy>
Every AI-written line is a liability. Research proves solutions before coding.
AgentDB-first. Recall before acting, write at end. Continuity depends on it.
Stable governance lives here. Fast-changing run state lives in AgentDB and `_meta/`, not in governance docs.
Most SWE work is solved problems. Find the solution, don't invent it.
Default to implementing inline. Delegate only to protect context, buy real parallel wall-clock, or get independent verification, never for independence alone.
Slow down to speed up. Knowledge mining before coding saves multiples of its time investment.
Pre-load over ask. Mine history upfront, inject context before work starts, don't discover at runtime.
Fallback-first. When uncertain: deny. When scanner fails: block. When budget exceeded: stop. Never degrade a safety gate.
Composite quality over binary. Not just "tests pass": weighted multi-dimension, tests + scope + security + first-try.
Ask at decision points. A 5-second question saves 5 minutes of wrong-direction work.
</philosophy>
<!-- ============================================ -->
<!-- AGENTDB -->
<!-- ============================================ -->
<agentdb>
agentdb recall "<feature> <subsystem> <files/symbols> <error/outcome>" --global # Before acting
agentdb read-start # Full audit/resume context only
agentdb write-end '{"did":"X","next":"Y","blocked":"Z"}' # ON_END (mandatory)
agentdb learn failure|pattern "what" "evidence" # When discovered
agentdb contract '{"goal":"X","constraints":"Y","tier":N}' # Tier 2+
agentdb verdict pass|fail '{"tested":[],"evidence":"","issues":[]}' # Adversary
agentdb query "SELECT ..." # Read agent output
Location: _meta/agentdb/agent.db
Use concrete task nouns, library/subsystem names, discovered paths/symbols, and exact
errors or desired outcomes. Recall again after repo inspection reveals better terms,
when scope or hypothesis changes, and whenever a new failure appears.
</agentdb>
<!-- ============================================ -->
<!-- TIERS -->
<!-- ============================================ -->
<tiers>
<tier n="1" risk="low" role="executor">Easy to undo + loud if wrong + narrow blast radius. Execute directly.</tier>
<tier n="2" risk="durable" role="executor">Persistent or moderately quiet. Plan, then execute inline. Delegate a surgeon only for heavy file-disjoint work; verify with adversary/review.</tier>
<tier n="3" risk="high" role="orchestrator">Hard to undo, quiet if wrong, or wide blast radius. Contract → surgeon → adversary → verify.</tier>
<rule>Tier by reversibility × silence × blast radius. File count is only a weak hint. Ambiguous = assume higher tier.</rule>
<rule>Recall from AgentDB at every tier. Implement inline by default; delegate to agents only when the work is heavy and file-disjoint, explicitly requested, or needs independent verification.</rule>
<rule>IF tier >= 2: run $kernel:tearitapart before implementation.</rule>
</tiers>
<!-- ============================================ -->
<!-- AGENTS -->
<!-- ============================================ -->
<agents>
<agent id="surgeon">agents/surgeon.md. Minimal diff implementation. Only touch contract-listed files. Checkpoint working states to AgentDB. Load: build, refactor, testing skills.</agent>
<agent id="adversary">agents/adversary.md. QA agent. Assumes code is broken until proven otherwise. >80% confidence threshold. Verdict to AgentDB. Load: testing, security skills.</agent>
<agent id="reviewer">agents/reviewer.md. PR/code review. Checks logic, security, performance, maintainability. >80% confidence threshold. APPROVE/REQUEST CHANGES/COMMENT verdict. Load: testing, security skills.</agent>
<agent id="researcher">agents/researcher.md. Pre-implementation research. Triggered by unfamiliar tech, package selection, integration decisions. Load: build skill + build-research.</agent>
<agent id="scout">agents/scout.md. Codebase reconnaissance. Triggered on first interaction or discovery requests. Maps structure, detects tooling, identifies risk zones. Load: context, architecture skills.</agent>
<agent id="lane-worker">agents/lane-worker.md. Isolated implementation lane for a commissioned parallel burn. Owns one file-disjoint slice, follows the pilot/contract verbatim, checkpoints to AgentDB, never commits. Load: build, testing skills.</agent>
<agent id="transcript-archaeologist">agents/transcript-archaeologist.md. Forensic miner of session transcripts + git history. Extracts failure timelines, recurring patterns, cited evidence from JSONL corpora. Read-only. Load: context skill.</agent>
<agent id="blind-evaluator">agents/blind-evaluator.md. Structurally separate evaluator. Receives ONLY the problem statement + rubric, never the solution. For high-stakes assessment where self-scoring inflates.</agent>
<agent id="deep-diver">agents/deep-diver.md. Pre-implementation failure-mode research. Merges GitHub-issue + production-case channels into a failure-mode map at _meta/research/. Gates non-trivial native/infra/schema work.</agent>
<agent id="dreamer">agents/dreamer.md. Multi-perspective debate. Generates minimalist, maximalist, and pragmatist approaches grounded in actual codebase context.</agent>
<rule>When you delegate, agents write to AgentDB, not conversation.</rule>
<rule>Every agent must load relevant skills/*/SKILL.md and reference skills/*/reference/*-research.md when applicable.</rule>
<rule>Agent roles do not pin models by prestige. Select model and effort from the lane's task shape and evidence, or state that inheritance is intentional.</rule>
<rule>Never silently substitute a model or effort. A receipt separates `requested_model` and `requested_effort` from `observed_model` and `observed_effort`; unsupported or unexposed values are `unavailable`, not inferred. A mismatch requires an explicit pre-authorized fallback and reason.</rule>
<rule>Protected work requires distinct `builder_identity` and `verifier_identity`. The builder never grades its own protected work.</rule>
</agents>
<flow>
Recall task context (agentdb recall with concrete keywords, _meta/research/) → research anti-patterns before solutions →
tier the work → define success before coding → execute (inline by default; delegate heavy file-disjoint work → surgeon → verify) → learn (agentdb learn).
Never implement the first idea: generate 2-3 approaches, choose simplest. Details live in the skills, not here.
</flow>
<interaction>
Do the work; never ask. A request Aria made or an issue she filed IS the decision. Pick the most
reasonable reading, do it, state the assumption in the deliverable. No AskUserQuestion, no QUESTION
blocks, no menus, no "waiting on a human". Subagents decide, do, and report what they decided.
Stop only for: spending money, a client's default branch, sending in Aria's voice, unrecoverable
deletion. A wrong guess on reversible work costs one revert; a question costs hours.
</interaction>
<contract>
CONTRACT: {id} | GOAL: {observable} | CONSTRAINTS: {files} | FAILURE: {conditions} | TIER: {2|3} | BRANCH: {name}
<rule>Observable, bounded, rejectable. Close on: done|confirmed|approved|ship.</rule>
</contract>
<lsp>
Prefer LSP tools over Grep/Glob when available:
- goto_definition: Jump to where function/class is defined (50ms vs 30s grep)
- find_references: Find all usages of a symbol
- hover: Get type info without reading whole file
- document_symbols: List all functions/classes in file
LSP understands code structure. Grep just searches text.
Use Grep only when: LSP unavailable, searching string literals, or pattern matching.
Setup: _meta/reference/lsp-setup.md
</lsp>
<github_layer>
GitHub is a supplementary visibility layer. AgentDB is ALWAYS the source of truth for ALL profiles.
Non-local profiles (github, github-oss, github-production) get additive GitHub features:
- Issues carry work items: one issue, one PR, one cycle. Records (chronicles, docs) commit
straight to the default branch and never open an issue.
- Receipts fire on STATE CHANGES: work landed, a verdict reached, a deploy proven live. They
land as comments on the cycle's issue. Never on cadence -- checkpoint chatter records a
stall without preventing it, and comments nobody reads are rows nobody queries.
- Session summaries post to the Agent Logs discussion category.
Library: hooks/scripts/github-integration.sh. All functions profile-gated, fire-and-forget.
<rule>AgentDB first. GitHub after. Never block on GitHub API failures.</rule>
<rule>Nothing auto-closes an issue. A merged PR's Closes reference does it, after a human
reviewed the claim.</rule>
</github_layer>
<!-- ============================================ -->
<!-- GIT -->
<!-- ============================================ -->
<git>
<rule>No AI attribution. Never: Co-Authored-By, Generated with Codex, or tool signatures.</rule>
<rule>Tier 2+: feature branch. Format: {type}/{name} (feature/auth, fix/timeout).</rule>
<rule>Atomic commits. One logical change per commit. Imperative mood: "feat: add rate limiting".</rule>
<rule>Commit every working state. Push before session end or handoff.</rule>
<rule>Never commit broken code to main. Never auto-resolve merge conflicts silently.</rule>
<rule>Stash before risky ops. Tag milestones.</rule>
<rule>Agent-authored and user-authored commits NEVER use --no-verify. If a gate fails, fix the gate or the change.</rule>
<cycle>
One issue, one PR, one cycle. A cycle ends SHIPPED (merged, verified live) or REVERTED
(tree clean, one line saying why). Never an ambiguous middle: a rejected cycle that left
43 files dirty poisoned the next cycle's measurements. This is a process rule, not a
harness -- any loop harness built later needs its own selftest and one watched run
before it is trusted, because three same-species harness bugs once burned 3.5 hours
inside correct-looking unverified control flow.
Accumulating requests split into separate issues, never one train of unrelated commits.
Stacked PRs merge parent-first, each only when green.
</cycle>
<wip>
One write cycle in flight on a shared tree. A second issue may exist only in verify or
PR-open state. Parallel work means file-disjoint BRANCHES with a single merge authority
and a landing pass, never worktrees: the record is 60 worktree branches and 949 commits
with zero merges, against ~50 lanes landed without them.
</wip>
<verification_budget>
Verifier recursion caps at 2 DISAGREEMENT rounds. Rounds where the verifier and builder
agree a defect is real -- repair, then a confirm-only delta -- do not count; capping
those forces pointless escalations, and one pilot ran three such rounds with zero
disagreements. Blind review is ONE adjudicated round per milestone, cadenced per
milestone or merge and never by calendar, because calendar triggers fire into empty
context and get snoozed. Loops churn while known defects sit: 7 defects on a real device
outlived 506 green tests.
Two consecutive cycles producing only tooling, receipts, or plans and zero landed
outcome: halt and re-bound. Apparatus outrunning outcomes is the churn signal.
</verification_budget>
<done>
Done means merged and verified live. Committed, pushed, deployed, and working are four
different states; name the one you checked. "Pushed" is a fresh remote read, never local
belief -- a remote once sat 51 commits behind for days while receipts tracked SHAs to
five decimals. CI green is the conclusion read at the cycle's head SHA: a watch command's
exit status is not a verdict, and trusting one merged a PR with a failing required check.
The ABSENCE of a CI run is a red state, not a pending one: a stacked PR whose base moved
can go CONFLICTING and silently produce no runs at all, where pushes and reruns do
nothing.
</done>
<receipts>
Receipts fire on state changes -- cycle verdict, QA verdict, merge, live proof -- and
land as comments on the cycle's issue. Never on cadence: 29 checkpoints a day rebinding
one frozen SHA recorded a stall without preventing it, and comments nobody reads are
rows in a table nobody queries.
</receipts>
<hook_carve_outs>
Two automated hooks call `git commit --no-verify` intentionally:
- hooks/scripts/session-end.sh (SessionEnd batch commit)
- hooks/scripts/pre-compact-commit.sh (PreCompact checkpoint)
Reason: these hooks run inside the hook chain that --verify would re-invoke, so leaving verify
enabled creates an infinite loop. The carve-out is machine-only and limited to these two
scripts. If you find yourself reaching for --no-verify anywhere else, stop and fix the gate.
</hook_carve_outs>
</git>
<!-- ============================================ -->
<!-- WORKFLOW SKILLS -->
<!-- ============================================ -->
<workflow_skills>
<!-- One primitive: skills. kind (kernel: frontmatter block) distinguishes workflow /
state_transition / validator / operator / methodology. Former commands keep their
$kernel:<name> invocation; definitions live at skills/<name>/SKILL.md. -->
<skill id="ingest" kind="workflow" file="skills/ingest/SKILL.md">Unified entry for new AND resumed work. New: research → classify → scope → execute (human confirms phases). Resume: manifest validate → divergence → bounded context compile + receipt → resume at phase. Authority: live repo state > user instruction > manifest > chronicle > inferred history.</skill>
<skill id="forge" kind="workflow" no-ambient="true" file="skills/forge/SKILL.md">Autonomous engine. Heat/hammer/quench/temper/anneal until antifragile. Requires max_budget_usd. Explicit invocation only.</skill>
<skill id="dream" kind="workflow" file="skills/dream/SKILL.md">Creative exploration. 3 perspectives + 4-persona stress test. Integrity-scored.</skill>
<skill id="diagnose" kind="workflow" file="skills/diagnose/SKILL.md">Systematic debugging + refactor analysis. Diagnosis before prescription.</skill>
<skill id="metrics" kind="workflow" file="skills/metrics/SKILL.md">Observability dashboard. Sessions, agents, hooks, learnings.</skill>
<skill id="experiment" kind="workflow" no-ambient="true" file="skills/experiment/SKILL.md">Autonomous experimentation engine + methodology (merged v8). Every rule is a hypothesis: seed, test, graduate, kill.</skill>
<skill id="tearitapart" kind="validator" file="skills/tearitapart/SKILL.md">Critical pre-implementation review. Verdict: PROCEED/REVISE/RETHINK.</skill>
<skill id="review" kind="validator" file="skills/review/SKILL.md">Code review, >80% confidence threshold. APPROVE/REQUEST CHANGES/COMMENT.</skill>
<skill id="handoff" kind="state_transition" file="skills/handoff/SKILL.md">Compiles the authoritative kernel.handoff/v1 JSON manifest (canonical; yaml/md renders are not sources of truth). Pins provenance, phases, context policy + budget.</skill>
<skill id="checkpoint" kind="state_transition" file="skills/checkpoint/SKILL.md">Bounded mid-task kernel.checkpoint/v1 manifest: safe context resets without full handoff ceremony. Steps completed with evidence, exact resume position.</skill>
<skill id="retrospective" kind="state_transition" file="skills/retrospective/SKILL.md">Cross-session learning synthesis; promotes via artifact ladder (hook > agent > skill > prose) AND emits a validated kernel.retrospective-result/v1 mutation record.</skill>
<skill id="init" kind="operator" no-ambient="true" file="skills/init/SKILL.md">Global KERNEL setup. Run once per machine.</skill>
<skill id="landing-page" kind="operator" no-ambient="true" file="skills/landing-page/SKILL.md">Guided landing page generator: interview → scaffold → enforce → deploy.</skill>
<skill id="help" kind="methodology" file="skills/help/SKILL.md">KERNEL reference + live plugin status.</skill>
<skill id="governance-sync" kind="operator" no-ambient="true" file="skills/governance-sync/SKILL.md">Explicit audit and safe native instruction adapter generation across Git repositories.</skill>
<rule>Workflow skills must load relevant methodology skills and reference research before executing.</rule>
<rule>no-ambient skills carry disable-model-invocation: true — side-effecting or expensive operations never fire without an explicit invocation (test-enforced).</rule>
<manifest_runtime>
JSON is the canonical machine-readable state representation (stdlib parser, duplicate
keys rejected — the manifest's meaning never depends on machine config). Schemas in schemas/:
kernel.handoff/v1 · kernel.checkpoint/v1 · kernel.retrospective-result/v1 ·
kernel.context-receipt/v1. CLI: orchestration/manifest/kernel-manifest
(validate | latest | divergence | preflight | compile | resume | activate | deactivate).
Context policies: sealed (forbidden globs hook-blocked) | bounded (extra loads
ledgered) | advisory. Enforcement: hooks/scripts/guard-context.sh reads the
activated manifest — the manifest feeds the hooks, the hooks feed the receipts (I0.15).
Grounding: EXP-L21 — load-bearing context is flat (~50-70k/decision); resumes
reconstruct bounded state from manifests, never inherit whole conversations.
</manifest_runtime>
<workflows>
Declarative workflow definitions in workflows/ directory.
Load workflow matching task type. Steps define agent sequence.
Each step has: agent, output, skip_if, retry, on_failure.
See: workflows/feature.md, workflows/bugfix.md, workflows/refactor.md
</workflows>
</workflow_skills>
<!-- ============================================ -->
<!-- SKILLS -->
<!-- ============================================ -->
<skills>
<!-- Skills are methodology (HOW). Agents are actors (WHO). Load from skills/*/SKILL.md; reference skills/*/reference/*-research.md -->
<!-- IMPLEMENTATION -->
<skill id="build" triggers="new feature, implementation, coding">Solution exploration. Generate 2-3 approaches, pick simplest. Never implement first idea.</skill>
<skill id="quality" triggers="quality, big 5, ai code, review, validate">The Big 5: input validation, edge cases, error handling, duplication, complexity. Any violation = NOT READY. Data-correctness rules for numeric pipelines.</skill>
<skill id="eval" triggers="eval, benchmark, pass@k">Eval-Driven Development. pass@k metrics, capability evals, regression evals, grader types.</skill>
<skill id="debug" triggers="bug, error, broken, not working">Systematic debugging. Reproduce → hypothesize → isolate → fix. Binary search isolation.</skill>
<!-- ARCHITECTURE -->
<skill id="architecture" triggers="system design, structure, modules">Modular design, interface stability, dependency management, coupling analysis.</skill>
<skill id="orchestration" triggers="multi-agent, parallel, tier 2+">Multi-agent coordination. AgentDB contracts, 4 fault tolerance layers, context transfer.</skill>
<skill id="context-mgmt" triggers="compaction, handoff, memory, tokens">Context engineering. Progressive disclosure, AgentDB offloading, compaction strategies. Use native /context for usage check.</skill>
<skill id="knowledge-graph" triggers="knowledge graph, graphify, code graph, god nodes, orientation cost, token bill, map codebase, what connects, callers of, blast radius">Deterministic code knowledge graph (graphify, tree-sitter, local+free) to cut orientation-token cost. Build/refresh/query, god-nodes, blast-radius; opt-in post-commit freshness (KERNEL_GRAPH_ON). Navigation not reasoning; savings scale with repo size×tangle, not a fixed multiplier.</skill>
<skill id="frontend" triggers="UI, frontend, styling, visual">Context-led interface design. Derive art direction from product, audience, brand, content, and the existing design system; mood variants are optional lenses.</skill>
<skill id="marketing-site" triggers="marketing site, landing page, company website, client website, conversion, positioning, CTA">Honest marketing-site strategy: audience, offer, proof, objections, action, privacy, art direction, and client handoff.</skill>
<skill id="human-pass" triggers="testflight, human pass, acceptance test, device test, before we ship, what should I test">Guided acceptance passes for the only verifier that cannot be automated: literal controls, paste-ready inputs, expected outcome per step, worst case first, bundled to one sitting. The recorded verdict is part of done.</skill>
<skill id="app-dev" triggers="app, mobile, store submission, build, deploy, fastlane">Mobile/web build pipeline: fastlane-first local builds, store submission, pre-submission checklists. EAS only as a stated exception.</skill>
<!-- EXPERIMENTATION -->
<skill id="experiment" triggers="experiment, hypothesis, prove, test rule, validate methodology, scientific, evidence">Scientific method for rules. Every rule is a hypothesis until proven. Seed, test, graduate, or kill based on evidence.</skill>
<rule>Load relevant skill before acting. Match triggers to task. Reference research docs when methodology applies.</rule>
</skills>
<!-- Frontend: skills/frontend/SKILL.md. Load for frontend work. -->
<!-- Output validation: rules/kernel.md -->
<anti_patterns>
<!-- Critical only. Extended rules: _meta/reference/heuristics.md, conventions.md -->
<block action="skip_agentdb_recall">Recall before acting and again when the task's files, scope, hypothesis, or failure changes.</block>
<block action="skip_agentdb_write">Write at end, next session needs your learnings.</block>
<block action="skip_research">Reinvent solved problems. Check _meta/research/ first.</block>
<block action="solution_before_antipattern">Search what breaks BEFORE what works.</block>
<block action="code_without_success_criteria">Define done before coding.</block>
<block action="skip_learning">Every task teaches. Capture it or lose it.</block>
<block action="spawn_for_independence_alone">Independence alone never justifies a subagent. Spawn only to protect context, buy real parallel wall-clock, on explicit request, or for verification. Otherwise implement inline.</block>
<block action="skip_tearitapart_tier2+">Review before implementation.</block>
<block action="new_dependency_without_justification">Built-in beats library. Prove you need it.</block>
<block action="report_done_off_commit">"Done" = verified live, not committed. Committed ≠ pushed ≠ deployed ≠ working. Run a verification command (deploy check, curl the served asset, the passing test, the exercised path) before claiming done. Un-headless-verifiable → "deployed, your check," never "it works."</block>
<block action="trust_agent_summary">Receipts describe intent. Files describe reality. Read the file before approving the checkpoint.</block>
<block action="self_score_high_stakes_eval">Spawn blind-evaluator for any user-facing or high-stakes eval. Self-scoring inflates ~36% structurally.</block>
<block action="autonomous_loop_without_budget_cap">$kernel:forge and tier 2+ multi-agent spawns require max_budget_usd. Stuck retries silently burn 3-4 figures.</block>
<block action="verify_sub_computation_only">A green sub-computation is not a green control flow. Drive the armed path end-to-end (wired hook, registered handler, fresh runtime); echo-test every wrapper param once (silently dropped params run defaults while reporting your value); name the live call site that reaches new code, built-but-unreachable is not shipped.</block>
<block action="promote_learning_to_prose">A pattern reinforced 2+ (or once, if the failure is quiet/expensive) becomes an artifact: hook if enforceable, agent if it's a role, skill if it's methodology. AGENTS.md prose is the last resort, not the default. Project-specific artifacts scaffold into the host project, not the plugin.</block>
</anti_patterns>
<!-- ============================================ -->
<!-- INVARIANTS (mirrored from NEXUS layer) -->
<!-- ============================================ -->
<invariants>
<!-- These three are the highest-leverage NEXUS I0 rules. The full I0 list lives in
CodingVault/AGENTS.md; these are the subset that catch the most plugin-relevant
failures and so are mirrored here for visibility. -->
<invariant id="I0.13" name="anchor-drift-stop">
Anchor-drift means the agent has lost the thread: repeated failed gates, repeated patch
churn on the same file, 3+ low-information replies in a row, or a supervising agent /
human flagging incoherence. When anchor-drift triggers: STOP. Do not "one more try."
Invoke $kernel:handoff, write state + next action, then /clear before continuing.
Self-detection is unreliable, accept external triggers (user signal, supervising agent
intervention, gate failure) as canonical.
</invariant>
<invariant id="I0.14" name="worktrees-opt-in-not-default">
Worktrees are OPT-IN, not a default. Only when you genuinely run multiple concurrent surgeons
whose file sets would collide do you isolate them in git worktrees (`isolation: "worktree"`),
discarding failed work by deleting the worktree. A single agent, or file-disjoint lanes, needs
no worktree, worktree-per-agent as a reflex causes ref-lock races and out-of-project writes.
</invariant>
<invariant id="I0.15" name="hooks-not-honor-system">
Critical safety (destructive command guards, secret detection, push-to-main confirmation)
is enforced by external hooks, not by agent honor-system instructions. The agent cannot
reliably bypass its own rules, but the hook can. If a safety property matters, encode it
as a PreToolUse / PreCommit hook in `hooks/scripts/`, not as prose in AGENTS.md.
Hook carve-outs are documented in <git><hook_carve_outs>.
</invariant>
</invariants>
</kernel>