codenerd-builder

name: codenerd-builder description: Build the codeNERD Logic-First Neuro-Symbolic coding agent framework. This skill should be used when implementing components of the codeNERD architecture including the Mangle kernel, Perception/Articulation Transducers, JIT Clean Loop, SubAgents, Modular Tool Registry, Virtual Predicates, TDD loops, Piggyback Protocol, Quiescent Boot, Dream State, Dreamer (Precog Safety), Legislator, Ouroboros Loop, and ConfigFactory. Use for tasks involving Google Mangle logic, Go runtime integration, or any neuro-symbolic agent development following the Creative-Executive Partnership pattern.

codeNERD Builder

Build the codeNERD high-assurance Logic-First CLI coding agent.

Architecture Update (Dec 2024): codeNERD now uses a JIT Clean Loop architecture. Domain shards (coder, tester, reviewer, researcher) have been deleted and replaced by JIT-driven SubAgents. All persona/identity comes from prompt atoms compiled at runtime. Tools are now modular via internal/tools/ and any agent can use any tool via JIT selection.

Quiescent Boot (Dec 2024): Sessions start fresh. Ephemeral facts (user_intent, next_action, etc.) are filtered at kernel boot. Use /sessions to load previous sessions explicitly.

Routing Arbitration (Jun 2026): Interactive-turn routing is now a SINGLE kernel decision. Perception (running on a fast classification model tier — classification_model in config, wired in cmd/nerd/chat/session.go) emits typed facts (user_intent, intent_signal(/is_question), delegation_candidate, multi_step_signal); policy/routing_arbitration.mg derives exactly one route_decision/2 lane: /respond_directly, /clarify, /multi_step, or /delegate. Questions terminate in prose — never shard delegation (wants_direct_answer also guards delegate_task). The pre-perception follow-up substring detector and the perception stability bypass were deleted (they re-routed identical inputs based on hidden session state). Knowledge requests are capped at 2 and synthesized with one follow-up LLM call (synthesizeWithKnowledge) — the pipeline is never re-entered. The verification retry loop (VerifyWithRetry) applies to /mutation intents only. Go's Model.decideRoute (cmd/nerd/chat/delegation.go) ferries facts in and the lane out; legacy Go gates remain only as nil-kernel fallbacks.

Delegation Hardening (Jun 2026): Delegated tasks run with PRESET intents (Executor.ProcessWithIntent): the spawner/JITExecutor carry the routed IntentVerb, so subagents and inline runs never re-perceive the synthetic task string (no extra classification call, no persona roulette). Task intents are asserted under unique /task_intent_N IDs and retracted after the run — subagents never clobber the session's /current_intent on the shared kernel. Inline execution clones the executor (CloneForTask) instead of mutating the shared session executor. The API scheduler wakes waiters in PRIORITY order (interactive clients register PriorityHigh; JITExecutor.ExecuteWithContext propagates spawn priority via CtxKeyPriority). Articulation prompt sections are capped (context facts, findings, replayed user turns).

Stability Notice: This codebase is under active development. Code snippets illustrate architectural patterns but may not match current implementations exactly. Always read the actual source files.

Build Instructions

IMPORTANT: To enable sqlite-vec for vector DB support:

$env:CGO_CFLAGS="-IC:/CodeProjects/codeNERD/sqlite_headers"; go build ./cmd/nerd

Integrated Skills Ecosystem

codeNERD development leverages a constellation of specialized skills:

For complete skill documentation with trigger conditions and integration points, see references/skill-registry.md.

Core Philosophy

Current AI agents make a category error: they ask LLMs to handle everything—creativity AND planning. codeNERD separates these concerns through a Creative-Executive Partnership:

• LLM as Creative Center: Problem-solving, solution synthesis, goal-crafting
• Logic as Executive: Planning, memory, orchestration, safety derive from Mangle rules
• Transduction Interface: NL↔Logic atom conversion channels creativity through formal structure

Architecture Overview

[ Terminal / User ]
       |
[ Perception Transducer (LLM) ] --> [ Mangle Atoms (user_intent) ]
       |
[ Session Executor - The Clean Loop ]
       |
       +-> [ JIT Prompt Compiler ] --> [ Persona Atoms + Context ]
       +-> [ ConfigFactory ] --> [ Tools + Policies from Intent ]
       +-> [ LLM.CompleteWithTools() ]
       +-> [ Constitutional Gate ] --> [ Safety Check ]
       +-> [ Virtual Store (FFI) ] --> [ Tool Execution ]
       |
       +-> [ Spawner ] --> [ SubAgents (JIT-configured) ]
             +-> [ Autopoiesis ] → Ouroboros, Thunderdome
       |
[ Articulation Transducer (LLM) ] --> [ User Response ]

The Clean Execution Loop (replaces old shard spawning)

// internal/session/executor.go - ~50 lines replacing 5000+
func (e *Executor) Process(ctx context.Context, input string) (string, error) {
    // 1. Transducer: NL → intent
    intent := e.transducer.Transduce(ctx, input)
    e.kernel.Assert(intent.ToFact())

    // 2. JIT: Compile prompt (persona + skills + context)
    prompt := e.jitCompiler.Compile(ctx, e.buildContext(intent))

    // 3. JIT: Compile config (tools, policies)
    config := e.configFactory.Generate(ctx, prompt.Result, intent.Verb)

    // 4. LLM: Generate response with tool calls
    response, err := e.llm.CompleteWithTools(ctx, prompt.Prompt, input, config.Tools)

    // 5. Execute: Route tool calls through VirtualStore
    for _, call := range response.ToolCalls {
        if e.constitutionalGate.Permits(call) {
            e.virtualStore.Execute(ctx, call)
        }
    }

    // 6. Articulate: Response to user
    return e.articulator.Emit(response)
}

For detailed architecture, see references/architecture.md.

Neuro-Symbolic Design Principles

The "Mangle as HashMap" Anti-Pattern

CRITICAL: Mangle is for deduction, not data lookup. It has no fuzzy matching.

# WRONG - expecting fuzzy matching
intent_definition("review my code", /review, /codebase).
# User says "inspect my code" → NO MATCH!

Solution: Use vector embeddings for semantic matching, then let Mangle reason over the results.

Functions That Don't Exist

These are commonly hallucinated and will fail silently:

• fn:string_contains ❌
• fn:substring ❌
• fn:regex ❌
• fn:like ❌

Valid: fn:plus, fn:minus, fn:Count, fn:Sum, fn:group_by, fn:collect, fn:list, fn:len.

See mangle-programming skill for complete reference.

Key Components

Perception Transducer

Converts user input to Mangle atoms (user_intent, focus_resolution).

Decl user_intent(ID, Category, Verb, Target, Constraint).

See references/semantic-classification.md.

Articulation & Piggyback Protocol

Dual-channel output: visible surface_response for user + hidden control_packet for kernel.

{
  "surface_response": "I fixed the bug.",
  "control_packet": {
    "mangle_updates": ["task_status(/fix, /complete)"]
  }
}

See references/piggyback-protocol.md.

JIT Prompt Compiler

Dynamic prompt assembly from atomic components:

See prompt-architect skill.

SubAgents (JIT-Driven)

Dec 2024: Domain shards (CoderShard, TesterShard, etc.) have been deleted. SubAgents are now JIT-configured via persona atoms and ConfigFactory.

Key Files:

See references/shard-agents.md for legacy context.

Modular Tool Registry

Dec 2024: Tools are modular and any agent can use any tool via JIT selection.

Location: internal/tools/

Tools are routed via Mangle rules in intent_routing.mg:

modular_tool_allowed(/read_file, Intent) :- user_intent(_, _, Intent, _, _).
modular_tool_allowed(/web_search, Intent) :- intent_category(Intent, /research).

Quiescent Boot & Sessions

Dec 2024: Sessions start fresh. Previous sessions loaded explicitly.

Key Components:

Ephemeral Predicates (filtered at boot):

• user_intent - Current turn's intent
• pending_action - Actions awaiting execution
• next_action - Derived next action
• active_tool - Currently executing tool

Session Commands:

• /sessions - List and select previous sessions
• /load-session <id> - Load specific session
• /new-session - Start fresh (preserves old)

Dreamer (Precog Safety)

Simulates action impact before execution, checking for panic_state derivations.

result := dreamer.SimulateAction(ctx, ActionRequest{...})
if result.Unsafe {
    return errors.New(result.Reason)
}

Autopoiesis System

Self-modification via:

• OuroborosLoop: Tool self-generation with safety checks
• Thunderdome: Adversarial battle arena for generated tools
• NemesisShard: Strategic adversary that breaks patches

See references/autopoiesis.md.

Campaign Orchestration

Multi-phase goal execution with context paging:

See references/campaign-orchestrator.md.

Key Implementation Patterns

Pattern 1: Hallucination Firewall

Every action requires permitted(Action) to derive:

if !k.Mangle.Query("permitted(?)", action.Name) {
    return ErrAccessDenied
}

Pattern 2: OODA Loop

Observe → Orient → Decide → Act
Transducer → Spreading Activation → Mangle Engine → Virtual Store

Pattern 3: TDD Repair Loop

next_action(/read_error_log) :- test_state(/failing), retry_count(N), N < 3.
next_action(/analyze_root_cause) :- test_state(/log_read).
next_action(/generate_patch) :- test_state(/cause_found).

Mangle Logic Files

Core logic files in internal/core/defaults/:

• schemas.mg - Core schema declarations (78KB)
• policy.mg - Constitutional rules (81KB)
• coder.mg, tester.mg, reviewer.mg - Shard logic
• campaign_rules.mg - Campaign orchestration

Logging System

22 categories in .nerd/config.json:

See references/logging-system.md.

Key Implementation Locations

Reference Documentation

Quick Reference

OODA Loop: Observe (Transducer) → Orient (Spreading Activation) → Decide (Mangle) → Act (VirtualStore)

Constitutional Safety: Every action requires permitted(Action) to derive. Default deny.

Fact Flow: User → Transducer → user_intent → Kernel derives next_action → VirtualStore executes → Response