gormes-references

name	gormes-references
description	Find Go donor/reference implementations for Gormes. Use when stuck on implementation shape, checking donor provenance, or comparing Go agent donors.

Gormes References

Repository Branch Rule

For Gormes work, stay on the existing development branch. Do not create or use feature branches, short-lived branches, or git worktrees. If the checkout is not on development, stop before editing and switch safely or report the blocker.

Use this skill whenever you are about to write Gormes Go code and you are not sure which shape to use, which library to consult, or how a similar agent system solved the same problem. It is a research/lookup skill — not a planner, builder, or TDD skill. After consulting references, hand off to gormes-builder / gormes-tdd-slice for implementation.

When To Use

Trigger this skill when:

• you are about to call a Go stdlib API and want to see how a similar agent system structured it (HTTP client, OAuth, SSE, SQLite, MCP);
• a Gormes test or production failure surfaces a behavior gap and the implementation shape is unclear;
• the implementation seam needs OAuth / token-pool / provider-error / retry / streaming / tool-runtime / memory-store / await-user-reply / artifact-tracking;
• you are tempted to invent a new abstraction and there is probably already a working version in a donor;
• the failure mode looks like one of the Recurring Pitfalls in an available GORMES-PROVIDER-PATTERN-REFERENCES.md donor note.

Skip this skill when:

• the problem is upstream Hermes Python parity (use gormes-parity-auditor first);
• the problem is provider/auth/runtime specifically (use gormes-provider-parity — it is the focused superset);
• you already know the donor file and just need to write the test/code (use gormes-tdd-slice);
• the question is about external library/framework documentation (use Context7 MCP per repo policy).

Mission

Reduce token waste, copy-paste errors, and re-invented abstractions by routing every Gormes implementation question to the smallest set of donor files that answer it.

Hermes Python remains the parity contract. Go donors are how Gormes shapes Hermes parity in idiomatic Go. The local Hermes source is normally ./hermes-agent inside this repository; fall back to ../hermes-agent only when absent. Resolve it as $HERMES_SRC before reading upstream behavior.

Permission Map (2026-04-29)

Donor	Permission for Gormes
goclaw (CC BY-NC 4.0 in upstream)	Code permitted — Juan granted explicit permission. Port with provenance comment.
nanobot (Apache 2.0)	Patterns + adapted code with attribution
plandex (MIT/AGPL — verify per file)	Patterns; copy code only after per-file license check
engram (MIT)	Patterns + adapted code with attribution
trpc-agent-go (Apache 2.0)	Patterns + adapted code with attribution
adk-go (Apache 2.0)	Patterns + adapted code with attribution
axe (MIT)	Patterns + adapted code with attribution
agentcontrolplane, uzi	Patterns only; no code copy without review

When porting code (any donor), add a provenance comment on the receiving Gormes file:

// Adapted from <donor>/path/to/file.go::SymbolName
// Reason: <why we needed this shape>

Convert types and imports to Gormes-native names; never let donor symbol names leak into Gormes' public API.

Workflow

1. Identify The Problem Class

Pick exactly one and continue:

• Provider / auth / streaming / quota / retry → use gormes-provider-parity (focused superset). If an available donor note maps provider files, use it after resolving the donor root.
• MCP / tool host / runtime wiring / tool-result truncation → see "Runtime & tools" donor map below.
• Memory / Goncho / SQLite + FTS5 / write-queue / relations → see "Memory & Goncho" donor map.
• Channels / await-user-reply / callbacks / workflow primitives → see "Channels & workflow" donor map.
• Small utilities (token budget, artifact tracker, path sanitization) → see "Utility primitives" donor map.
• None of the above → use the fallback grep below.

2. Read Hermes Python First

Even when Gormes ships its own Go implementation, the user-facing behavior must match Hermes. Anchor the parity target before reading donors:

• $HERMES_SRC/AGENTS.md
• relevant subsystem under $HERMES_SRC/

If Hermes has no analog (e.g. a brand-new Gormes-only seam), record this explicitly in the receiving row's provenance.origin_type: gormes.

3. Read The Donor File End-To-End

Open the donor file once and skim it whole before extracting any pattern. Donor files often hide invariants in helpers (e.g. path sanitization, header construction, jittered backoff) that are easy to miss when grepping.

4. Adapt, Don't Adopt

Translate the donor pattern into Gormes-native names, types, and tests. Never:

• import donor packages into Gormes;
• keep donor symbol names in public Gormes APIs;
• skip Gormes tests because the donor is tested;
• adopt donor UX/config choices that contradict Hermes parity.

Always:

• add a provenance comment naming the donor file/function;
• write Gormes RED tests covering the ported behavior;
• run focused gates per row + go test ./... + go run ./cmd/progress validate.

5. Hand Off

After lookup, hand off to:

• gormes-tdd-slice for the red-green-refactor loop;
• gormes-builder to land the row;
• gormes-interface-designer if the package boundary is now clearer but not finalized.

Donor Maps By Subsystem

When present, a provider/auth/streaming donor note named GORMES-PROVIDER-PATTERN-REFERENCES.md is the focused lookup surface. Resolve the donor root first; the maps below cover everything else.

Runtime & tools

Gormes problem	Donor file	Pattern
Wire a runtime with explicit dependency layering	nanobot/pkg/runtime/runtime.go	Options.Merge + Complete defaults + explicit wiring of LLM client, tool registry, sampler
Build a tool service with before/after hooks	nanobot/pkg/tools/service.go, nanobot/pkg/tools/flows.go	Tool registry + filter gates + hook ordering
Truncate large tool outputs while persisting full bytes	nanobot/pkg/agents/truncate.go	maxToolResultSize, sanitized session-local artifact path, short text pointer
Estimate image tokens by decoded dimensions	nanobot/pkg/agents/tokencount.go	WebP decode, per-provider estimate, conservative fallback
Loop / sequential / parallel workflow agents	adk-go/agent/workflowagents/..., examples under adk-go/examples/workflowagents/...	Workflow primitives without rewriting kernel
Tool filtering (include/exclude by channel/trust/toolset)	axe/internal/... (filter helpers), nanobot/pkg/tools/flows.go	Pre-call gate, declarative filter

Memory & Goncho

Gormes problem	Donor file	Pattern
SQLite + FTS5 memory store	engram/internal/persistence/store/store.go	DDL, indexes, migration helpers
Memory relation/conflict vocabulary	engram/internal/persistence/store/relations.go	related, conflicts_with, supersedes, compatible, scoped, not_conflict
Deterministic serialized MCP write queue	engram/internal/mcp/write_queue.go	Mutex-serialized queue, cancel-before-start, evidence vocabulary
MCP activity/audit logging	engram/internal/mcp/activity.go	Audit shape, redaction, append-only file

Channels & workflow

Gormes problem	Donor file	Pattern
Await-user-reply / pause-and-resume	trpc-agent-go/agent/await_user_reply.go	Resume-token contract, callback-context shape, no-leak design
Provider/agent callback pipeline	trpc-agent-go/model/callbacks.go, trpc-agent-go/agent/callbacks.go	Before/after split from core turn
Per-session worker fan-out	uzi (patterns only)	Tmux fanout, isolated session state; do not use git worktrees for Gormes work

Utility primitives

Gormes problem	Donor file	Pattern
Bounded token-budget tracker	axe/internal/budget/budget.go	Per-turn counter, reset, overflow signal
Artifact tracker with sanitized paths	axe/internal/artifact/tracker.go	Path-traversal guard, append-only registry
Test-budget / agent-step counter	axe/internal/budget/budget_test.go	Test shape Gormes can mirror

Provider / auth / streaming

If a resolved donor root includes GORMES-PROVIDER-PATTERN-REFERENCES.md ("Quick Lookup: Problem → Donor File"), consult it for OAuth, token refresh, error classification, retry/backoff, drift, and stream-error mapping.

Fallback Grep

When the table doesn't list the problem:

# Resolve an available donor root before searching. Adjust the pattern to match
# your problem (function name, header, error code, struct field).
DONOR_ROOT="$(for p in ./references/go-agent-os ../references/go-agent-os "$GORMES_GO_AGENT_OS_REFS"; do [ -n "$p" ] && [ -d "$p" ] && { printf '%s\n' "$p"; break; }; done)"
if [ -z "$DONOR_ROOT" ]; then
  echo "no go-agent-os donor root found; route to gormes-skill-manager or gormes-context-sourcing"
else
  grep -rn "<symbol-or-concept>" "$DONOR_ROOT"/{goclaw,nanobot,plandex,engram,trpc-agent-go,adk-go,axe} 2>/dev/null | head -20
fi

If the grep returns nothing useful, escalate to gormes-skill-manager to decide whether the missing donor is a real gap (file a new reference clone request) or whether Gormes needs a from-scratch interface (route to gormes-interface-designer).

Validation

This is a research skill, so validation focuses on the implementation that follows:

• Every ported snippet has a // Adapted from … provenance comment.
• The receiving Gormes test exists before the implementation lands (RED).
• go test ./<receiving-package> -count=1 is green.
• go test ./... -count=1 and go run ./cmd/progress validate pass before commit.
• No donor symbol name appears in Gormes' exported API (go doc ./<package> | grep -iE "(goclaw|nanobot|plandex|engram|trpc|adk|axe)" returns nothing).

Final Report Shape

problem_class:
hermes_parity_target:
donor_files_consulted:
adaptation_applied:
provenance_comment:
gormes_tests_added:
hand_off_skill: gormes-tdd-slice | gormes-builder | gormes-interface-designer