executus/CLAUDE.md

executus — developer & agent guide

⚠️ This project is vibe-coded (AI-authored, human-steered). See README.md.

executus is a batteries-included base for LLM agent harnesses, layered strictly above majordomo. majordomo is the lean substrate (agent loop, llm types, providers, media, parse/failover/tiering). executus is the opinionated layer majordomo deliberately omits. executus requires no majordomo changes — it decorates llm.Model and wraps majordomo/agent.Agent.

North star

A brand-new project imports executus, does a little setup, and is most of the way to agentic capabilities. The mechanism is one shipped default per seam: executus.New() (once the runtime lands) is agentic with zero host wiring; the same builder lets a serious host swap each default for its own implementation and register its own tools.

Two consumers define the envelope:

• mort (heavy) — Discord, mortbux, media, MySQL/GORM, DB-backed convar config, saved skills, audit, scheduling, run-critic.
• gadfly (light) — a CI PR-reviewer Docker image, env-var configured, running an N-models × M-lenses structured-output swarm. Needs model fleet, lanes, bounded runs, structured output, fan-out, a few read tools — and none of the batteries.

That spread is why executus is tiered: a light host imports core only; a heavy host opts into batteries.

Module & layering

One module gitea.stevedudenhoeffer.com/steve/executus, go.mod = majordomo + stdlib only (no gorm/redis/discordgo/cgo). A second nested module contrib/store carries the SQLite dependency so the core never inherits it.

CORE (majordomo + stdlib):
  config/   ConfigSource seam (+ env default)            [P0 ✓]
  lane/     bounded fair-share worker pool               [P0 ✓]
  fanout/   programmatic N×M swarm                       [P0 ✓]
  deliver/  output egress seam (+ Discard/Stdout)        [P0 ✓]
  identity/ caller identity seams                        [P0 ✓]
  run/      progress bridge now; the executor kernel +   [P0 partial]
            nil-safe Ports + RunnableAgent later         [P2]
  dispatchguard/  loop/depth/fan-out caps                [P0 ✓]
  pendingattach/  attachment dedupe                      [P0 ✓]
  tool/     registry + 3-stage permissions + ssrf/llmmeta [P1]
  model/    config-driven tier resolution over majordomo [P1]
  compact/  context compactor (WithCompactor hook)       [P2]
  tools/{web,net,store,compose,meta,comms}  generic tools [P3]
  structured/  Generate[T] convenience over majordomo    [P1]

BATTERIES (opt-in siblings, each nil-safe + a default):
  persona/   Agent noun + AgentStore seam + yml loader   [P4]
  skill/     rich Skill + SkillStore seam + toml loader  [P4]
  audit/     run-trace Sink (+ Noop/Slog)                [P4]
  critic/    two-tier timeout state machine + Escalator  [P4]
  schedule/  cron runner cores                           [P4]
  checkpoint/ durable resume seam                        [P4]
  budget/    rolling-window tracker (+ NoOp)             [P4]

contrib/store/   SECOND module (+ modernc.org/sqlite):   [P4]
  in-memory + pure-Go SQLite impls of every *Store seam

The one architectural move

The kernel must import no battery. In mort today, agentexec imports agents, agentcritic, and skillaudit directly — those three up-pointing edges get inverted into nil-safe run.Ports interfaces (PaletteSource, Critic, Audit) plus a RunnableAgent DTO. Everything else is wide-but-shallow repackaging.

Invariants (enforced in CI)

• The core module builds with majordomo + stdlib only. go.sum must not contain gorm/redis/discordgo/sqlite/gin.
• No core/* package imports a battery/* package.
• Standard Go gates: go build, go vet, go test -race, go mod tidy clean.

Extraction roadmap

P0 module + zero-coupling moves + core seams (this) → P1 tool registry + model → P2 run kernel + Ports inversion → P3 generic tools + defaults → P4 persona/skill redesign + batteries + SQLite store → P5 gadfly on core (light-tier canary) → P6 rewire mort + tag v0.1.0. The mort-side rewrite reuses mort's existing mort_*_adapters.go wall as the host adapter layer.

Conventions

• Mirror majordomo's house style: gofmt; check errors immediately and wrap with fmt.Errorf("...: %w", err); // Why: comments where rationale isn't obvious; hermetic tests (majordomo's fake provider; no network in the default suite).
• Every seam is an interface with a nil-safe accessor and a shipped default.
• Keep the core seam surface small and stable — push churn into tools and host adapters, not core interfaces.