Building Gormes

Building Gormes

Contributor-facing documentation for the Go runtime, roadmap, skill-driven work queue, and upstream-porting research. If you want to use Gormes, start at Start here.

Runtime thesis

Gormes is the production runtime for self-improving agents. Four core systems live inside the binary:

• Learning Loop — detect complex tasks, distill reusable skills, improve them over time (Phase 6).
• Memory — SQLite + FTS5 + ontological graph, with a human-readable USER.md mirror (Phase 3).
• Tool Execution — typed Go interfaces, in-process registry, no Python bounce (Phase 2.A).
• Gateway — one runtime, many interfaces: TUI plus shipped Telegram/Discord, with Slack and long-tail adapters advancing as contract-first Phase 2 slices (Phase 2.B).

Gormes ports upstream contracts, not upstream monoliths. The default rule is Hermes parity for almost every operator-visible surface: config, command tree, slash commands, gateway handlers, provider routing/auth/usage, tool continuations, plugins, skills, cron, status, TUI/API behavior, packaging, and recovery. Go-native divergence is allowed only when it is explicit, tested, and visible to operators. Gormes-owned proves the value of contract-first operations, durable jobs, graph provenance, and skills as auditable runtime knowledge. Gormes absorbs those durable contracts into a small Go runtime instead of copying Python mega-files or TypeScript database gravity.

Section map

Need	Start with	Then use
Start here — plan and prioritize	Implementation Roadmap	Must-Have Features, Gormes Completion Plan, Completion Lane Roadmap
Understand the finish line	Gormes Completion Plan	Must-Have Features, Hermes/Honcho To Gormes Go Runtime Plan, Hermes And Honcho Feature Map, Upstream Coverage Ledger, Swarm Feature Parity Audit, Completion Lane Roadmap, Agent Operating Model
Understand the runtime shape	Core Systems	Architecture Plan, Why Go
Choose implementation work	Agent Queue	Next Slices, Blocked Slices, Umbrella Cleanup
Prepare a skill-builder handoff	Contract Readiness	Progress Schema, Skill Builder Handoff
Port an upstream subsystem	Hermes/Honcho To Gormes Go Runtime Plan	Hermes And Honcho Feature Map, Upstream Coverage Ledger, Swarm Feature Parity Audit, Porting a Subsystem, Upstream Lessons, Testing
Reuse gateway adapter ideas	Gateway Donor Map	Shared Adapter Patterns, then the channel dossier
Find a Go donor for a non-gateway subsystem (runtime, tools, memory, utilities) before writing code	gormes-references skill (docs/development-skills/gormes-references/SKILL.md)	references/go-agent-os/GORMES-PROVIDER-PATTERN-REFERENCES.md for provider/auth/streaming, then gormes-tdd-slice
Continue Goncho/Honcho memory work	Goncho Honcho Memory	Prompts, Tool Schemas
Study operational fleet patterns	Fleet Operational Patterns	Fleet Integration Plan, Implementation Roadmap
Plan fleet-derived features	Fleet Integration Plan	docs/content/building-gormes/architecture_plan/progress.json, Implementation Roadmap

Planning rules

Every subsystem plan answers four questions before implementation:

1. What upstream contract are we porting?
2. Which trust class can call it: operator, gateway, child-agent, or system?
3. How does degraded mode show up in gormes doctor, status, audit, or logs?
4. What fixture proves compatibility without a live provider or platform?

For builder agents, the canonical progress row must also name the execution_owner, slice_size, ready_when, not_ready_when, write_scope, test_commands, and done_signal conditions. Assignable slices are small/medium/large rows; umbrella rows stay inventory until split.

Skill-driven execution contract

Repo-local skills are the executor for this roadmap, not a separate backlog. gormes-builder reads docs/content/building-gormes/architecture_plan/progress.json, uses the generated docs/content/building-gormes/ pages as the human-readable handoff surface, selects one eligible row, and develops the full gormes-agent toward the architecture plan with tests.

The building-gormes docs are therefore part of the control plane. When a phase, subphase, or task is unclear to an agent, fix the canonical progress row and regenerate the derived docs instead of adding private instructions elsewhere. Skills consume the same source of truth contributors read: progress rows for selection, generated pages for operator review, and row metadata for handoff prompts.

The old cmd/planner-loop and cmd/builder-loop executables are removed. Use go run ./cmd/progress validate and go run ./cmd/progress write for progress maintenance, and use go run ./cmd/repoctl ... for repo metadata.

Current queue rule

The generated Agent Queue and Next Slices can be empty even while progress.json still contains planned rows. Empty means no unblocked, non-umbrella row currently satisfies the builder handoff contract; it does not mean Gormes is done.

When the queue is empty, run a gormes-planner pass against the relevant phase or subsystem. The planner should sharpen a planned/draft row until it has source refs, write scope, acceptance, degraded mode, and test commands. Only then should gormes-builder and gormes-tdd-slice implement it. Historical audits and parity matrices are evidence surfaces; progress.json is the dispatch queue.

Contributor path

Use the planning docs in this order:

1. Read Implementation Roadmap for current state, decision trees, and execution horizons.
2. Read Upstream Lessons to understand which contracts Gormes absorbs from Hermes and Gormes-owned.
3. Check Skill Builder Handoff for the skill entrypoint, candidate source, generated docs, tests, and candidate policy.
4. Pick work from Agent Queue for a builder-ready handoff, then use Next Slices for the shorter ranking.
5. Use docs/development-skills/gormes-builder/SKILL.md and docs/development-skills/gormes-tdd-slice/SKILL.md to implement one row; .agents/skills/, .claude/skills/, and .codex/skills/ are symlink loader views.
6. Check Contract Readiness before implementation; an active or P0 row must name its contract, trust class, degraded mode, fixture, source references, and acceptance checks.
7. Check Blocked Slices and Umbrella Cleanup before assigning a row.
8. Use Progress Schema when editing canonical progress.
9. Write the spec/plan from Porting a Subsystem, then implement with the fixture classes in Testing.

Reference groups

Planning: Implementation Roadmap, Must-Have Features, Cross-Project Feature Map, Completion Lane Roadmap, Gormes Completion Plan, Fleet Operational Patterns, Fleet Integration Plan, Agent-Zero Feature Analysis, OpenClaw Platform Parity Audit.

Architecture: Architecture Plan, Hermes/Honcho To Gormes Go Runtime Plan, Hermes And Honcho Feature Map, Upstream Coverage Ledger, Swarm Feature Parity Audit, Core Systems, What Hermes Gets Wrong, Upstream Lessons.

Execution queue: Contract Readiness, Skill Builder Handoff, Agent Queue, Next Slices, Blocked Slices, Umbrella Cleanup, Progress Schema.

Implementation help: Porting a Subsystem, Testing, Gateway Donor Map, Goncho Honcho Memory.