Implementation Roadmap

Purpose: This is the single planning entry point for building gormes-agent. It tells you where we are, what is blocked, what comes next, and which document to read for the details. If you are a planner, builder, or reviewer, start here before touching progress.json or writing code.

Relationship to other docs:

• architecture_plan/progress.json = the canonical execution queue (machine-readable)
• Completion Plan = the finish line definition
• Lane Roadmap = lane ownership and exit gates
• Must-Have Features = feature catalogue from 12+ upstream projects
• This document = the human-readable plan that ties them all together

Current State at a Glance

As of April 30, 2026

Overall: 47/78 subphases shipped · 26 in progress · 5 planned · 75 open rows

First closure target: Python-free normal agent turn with local Goncho memory and tested tool-call continuation. This is a dogfood gate, not a reduced finish line.

Product Hardening Borrow List

These are Gormes-owned follow-up slices from the current PicoClaw comparison. They are not Hermes parity blockers, but they matter for distribution quality and constrained-machine adoption.

Document Map

The building-gormes/ directory contains 13 entries. Here is how they relate:

implementation-roadmap.md (this file) ──► decision tree + state + horizons
    │
    ├── must-have-features.md ──► feature catalogue from 12+ upstream projects
    │   └── cross-project-feature-map.md ──► detailed per-project matrix
    │
    ├── architecture_plan/ ──► phases, completion plan, lanes, progress.json
    │   ├── completion-plan.md ──► finish line definition
    │   ├── lane-roadmap.md ──► 6 lanes with exit gates
    │   ├── progress.json ──► canonical machine-readable queue
    │   ├── phase-1-dashboard.md ──► phase intent and boundaries
    │   ├── phase-2-gateway.md
    │   ├── phase-3-memory.md
    │   ├── phase-4-brain-transplant.md
    │   ├── phase-5-final-purge.md
    │   ├── phase-6-learning-loop.md
    │   ├── phase-7-paused-channel-backlog.md
    │   ├── hermes-honcho-feature-map.md ──► upstream → Go package mapping
    │   ├── hermes-honcho-go-runtime-plan.md ──► reconciled implementation plan
    │   ├── upstream-coverage-ledger.md ──► source-class completeness audit
    │   ├── swarm-feature-parity-audit.md ──► sub-agent gap register
    │   └── ... (20+ more reference docs)
    │
    ├── builder-loop/ ──► execution mechanics
    │   ├── agent-queue.md ──► generated: builder-ready rows
    │   ├── next-slices.md ──► generated: ranked shortlist
    │   ├── blocked-slices.md ──► generated: blocked rows with unblock conditions
    │   ├── umbrella-cleanup.md ──► generated: rows needing split
    │   ├── builder-loop-handoff.md ──► skill entrypoint + candidate policy
    │   └── progress-schema.md ──► row schema reference
    │
    ├── core-systems/ ──► stable runtime model
    │   ├── gateway.md ──► platform adapters, command policy, session routing
    │   ├── memory.md ──► recall, graph, search, mirrors, Goncho
    │   ├── tool-execution.md ──► operation registry, schema, trust classes
    │   └── learning-loop.md ──► skill detection, distillation, feedback
    │
    ├── gateway-donor-map/ ──► per-channel adaptation patterns
    │   ├── shared-adapter-patterns.md
    │   └── 15 channel dossiers (telegram, discord, slack, whatsapp, ...)
    │
    ├── goncho_honcho_memory/ ──► memory subsystem deep-dive
    │   ├── 01-prompts.md
    │   ├── 02-tool-schemas.md
    │   ├── 03-honcho-docs-study.md
    │   ├── 04-agent-work-packets.md
    │   └── 05-operator-playbook.md
    │
    ├── upstream-lessons.md ──► durable contracts from Hermes + GBrain
    ├── what-hermes-gets-wrong.md ──► why Gormes exists
    ├── contract-readiness.md ──► row-level handoff contract
    ├── porting-a-subsystem.md ──► contribution path for upstream ports
    └── testing.md ──► test strategy and fixture classes

Rule: If a document contradicts progress.json, progress.json wins. If progress.json contradicts this roadmap, this roadmap wins until a planner updates progress.json.

Decision Tree: What Should I Work On?

Q1: Are you a planner or a builder?

Planner → Go to Agent Queue. If empty, go to Next Slices. If also empty, sharpen a planned row using gormes-planner skill.

Builder → Pick one row from Agent Queue. Read its contract, write_scope, test_commands, acceptance, and done_signal. Use gormes-builder + gormes-tdd-slice skills. Do not invent work outside the row.

Q2: Is the row blocked?

Check Blocked Slices. If your row is listed, read the unblock condition. If you can satisfy it, do so. If not, pick a different row.

Q3: Is the row an umbrella?

Check Umbrella Cleanup. Umbrella rows are inventory only. Split them into small/medium/large rows before building. Use gormes-planner for splitting.

Q4: Do you know which lane the row belongs to?

Use the Lane Roadmap lane crosswalk. Each lane has an exit gate. Know the gate before you start.

Q5: Do you know the upstream contract?

Read Upstream Lessons for durable contracts. Read Hermes And Honcho Feature Map for the upstream → Go package mapping. Read Porting a Subsystem for the contribution path.

Q6: Is the Go shape unclear?

Use gormes-interface-designer skill. Read Go Donor Reference Map for donor file patterns.

Q7: Are you doing memory work?

Read Core Systems: Memory first. Then read Goncho Honcho Memory for the deep-dive.

Q8: Are you doing gateway/channel work?

Read Core Systems: Gateway first. Then read the relevant Gateway Donor Map dossier.

Q9: Are you doing tool/security work?

Read Core Systems: Tool Execution first. Then read Must-Have Features §8.

Execution Horizons

These horizons are derived from the Must-Have Features gap analysis and mapped to progress.json phases/subphases.

Horizon 1: Safety + Provider Completion (Next 30 Days)

Goal: Close the two biggest blockers to a safe, Python-free agent turn.

Exit criterion: gormes doctor reports zero trust-class violations in default registry. All major providers have Go adapters. First Hermes-compatible normal turn runs without Python.

Horizon 2: Production Hardening (Next 90 Days)

Goal: Make Gormes safe and reliable for real-world operation.

Exit criterion: A new user can curl install.sh | bash, run gormes doctor, see green checks for all configured providers, and start a safe normal turn. Loop detection fires on runaway sessions. Token budget prevents surprise bills.

Horizon 3: Memory Differentiation (Next 6 Months)

Goal: Make Goncho meaningfully better than session-based memory.

Exit criterion: Goncho recall quality is measurably better than Hermes’s default memory. Retrieval eval harness runs on every memory change. Skills activate with context-aware metadata. Personality files are operator-editable markdown.

Horizon 4: Capstone Features (Next 12 Months)

Goal: Features that make Gormes uniquely valuable beyond Hermes parity.

Exit criterion: Gormes is not just “Hermes in Go” — it is a demonstrably better agent runtime with compounding skills, proven memory quality, and operator-visible intelligence.

Risk Register

Features or dependencies that could derail the plan:

Weekly Cadence (Recommended)

Monday: Review Agent Queue and Blocked Slices. Pick 1-2 rows.

Tuesday-Thursday: Build rows using gormes-builder + gormes-tdd-slice. Run go test ./... -count=1 and go run ./cmd/progress validate before claiming done.

Friday: Review done signals. Update progress.json evidence. If queue is empty, run gormes-planner pass to sharpen planned rows.

End of Month: Run gormes-parity-auditor pass against one Hermes/Honcho subsystem. Update Cross-Project Feature Map if gaps changed.

Success Metrics

Quick Reference: skill → Document Mapping

Generated: April 30, 2026 Source: progress.json v2.0, must-have-features.md, lane-roadmap.md, completion-plan.md Update rule: Refresh this document when progress.json major state changes or when must-have-features.md is updated.