Agent Shaker — Roadmap

Agent Shaker is a coordination plane: a self-hosted store of shared truth where AI agents and humans read and write the same projects, agents, tasks, contexts, milestones and standups through MCP and A2A, over the same API. It deliberately does not execute agents and is not a framework.

This roadmap describes what the product needs next, in dependency order, as of main @ 69d064f (2026-10-01; develop, main and feat/vnext all point at this commit, and GitHub shows 1 star). Every task below is scoped to specific files and has a verifiable acceptance criterion. Nothing here is implemented yet; the task IDs are stable and meant to be copied into issues without rewriting.

Where this picks up

Four facts about the current build frame everything that follows.

• The MCP server answers protocolVersion: "2024-11-05", the first revision of the specification. The current revision is 2026-07-28, three major revisions later, and it removed the session model the server still depends on.
• A2A tasks do not execute. cmd/server/main.go builds the task manager with a nil executor, and with a nil executor the manager echoes the incoming message back and marks the task completed. A remote agent delegating work receives a success signal for work that was never performed.
• Exactly one span exists in the codebase (websocket.handle in internal/websocket/hub.go). The OpenTelemetry provider, the W3C propagator and the otelslog bridge are all wired correctly, so the service is instrumentation-ready and uninstrumented.
• The schema has ten tables and none of them records who acted, what a human approved, or what it cost. There is no audit journal, no human principal, no approvals, no usage.

The rest of this document is the work that closes those gaps in an order where each step is cheaper after the one before it.

Milestones at a glance

M5, M6 and M7 are independent of each other and can run in parallel once M3 lands. M9 comes last on purpose: being discovered by an agent host and handing that agent a server that reports synthetic success is worse than not being discovered at all.

M0 — Prerequisites

Not code. These are the items that must be settled before milestone work is worth starting.

M1 — Retire the A2A stub

A product that cannot be trusted about what happened cannot be positioned around trust. This is the smallest task in the roadmap and the one with the highest cost of leaving in place.

The default resolution is open decision 1: keep the inbound direction and the agent card, drop outbound delegation. Maintaining somebody else's execution runtime is not a commitment a single maintainer can keep.

M2 — Humans as a data subject

Authentication today is a shared-secret scheme, and the code says so plainly. There is no "who", which makes attribution, permissions and approval authority impossible to express. daily_standups is the one capability no coordination competitor has, and it is wasted while the data model cannot record a human.

New columns are added alongside the existing ones and old values are preserved: tasks.created_by keeps referencing agents(id) so historical rows stay valid.

M3 — Append-only event journal

Every capability after this one — audit, cost, approvals, meaningful tracing — needs a record of what happened. Retrofitting a journal into a system that has been running is always more expensive than starting it now.

A journal write failing must not fail the business operation. The recorder logs and returns the error to the caller, which may choose to roll back. This is a deliberate trade in favour of read availability, recorded here so it is not later mistaken for an oversight.

M4 — Approvals

Approvals are table stakes everywhere in the category and are absent here. The nearest thing in the codebase is a milestone convention, not an entity, and the UI needs a real record to act on.

The protocol offers a cheaper path to the same outcome. MCP Apps (2026-07-28, SEP-1865) lets a server render an interactive approval card inside the agent's own host, and every UI action travels the same JSON-RPC path — and therefore the same audit and consent path — as a direct tool call. That is a stronger fit for the "one shared truth" thesis than a browser dashboard, and it belongs in M5.

M5 — Target MCP revision 2026-07-28

The current revision is the largest change to the protocol since launch. It is also, for this product, unusually well-timed: the reworked transport is what makes the journal, the approval card and the trace story possible at all.

MCP server-side Tasks is worth evaluating here too: the server may return a task handle from tools/call and the client drives it with get/update/cancel. That is the native way to express a long operation, and it is the honest successor to the A2A task path removed in M1.

The 63 gen_ai.* attribute keys are all still at Development stability, so none of them appear in this plan. Where GenAI semantics are wanted, they are modelled on a private shaker.* schema over the stable OTel core.

M6 — Observability

The infrastructure is already correct and unused. This milestone is instrumentation, not a new dependency.

OTEL_TRACES_SAMPLER stays the single sampling switch: full rate on the demo instance, reduced in production.

M7 — Context retrieval

The product promises that an agent gets fresh context without guessing or scraping. With list_contexts as the only read path and no full-text index, the agent has to pull the list and read everything to find anything.

PostgreSQL full-text search on the simple configuration is the default choice. There is no ratified standard for agent memory to align an embedding scheme with, and embeddings would drag in a model and a vector store for a corpus that is measured in markdown documents.

M8 — Cost tracking

Budgets and per-agent cost are what the mature players in this category converge on, and the existing per-agent and per-task entities make it cheap to add here.

Usage is opt-in. No data means no data, never zero — otherwise a partial reporting regime produces a false picture of agent cost, which is worse than no picture.

M9 — Distribution

This milestone is not a checklist. It is a decision, because the current deployment model and the discovery channel are structurally incompatible.

The official MCP registry is the only route to discoverability, and it accepts only servers whose installation method is publicly available or whose endpoint is publicly reachable. It explicitly does not accept private servers — those reachable by a narrow set of users. Agent Shaker is a self-hosted service behind basic auth with per-instance API keys, so as built it cannot be listed at all.

Either the project runs a public demo instance over HTTPS and opens that channel, or it remains a tool for people who already know it exists. The second option is a legitimate choice, but it should be chosen rather than discovered.

Listing has a second tier worth doing even without a demo instance: submissions to the major vendor directories, which additionally require a privacy policy URL and, for one of them, a reviewed organisation account.

Out of scope, deliberately

• Runtime adapters and agent execution. The two established projects in this category both ship them. They are a support liability across every vendor's API, and declining them is a position worth stating publicly rather than leaving to be inferred.
• Comparison with execution frameworks. Agent Shaker does not run agents, so counting orchestration patterns against LangGraph or the Microsoft Agent Framework compares different layers.
• A full Git integration layer with webhooks and synchronisation. That turns the product into a Git tool. If it happens, it happens as a link on the existing project_repos, not as a data pipeline.
• Multi-tenancy and billing. Single-tenant self-hosting stays the product.
• Onboarding material, templates, tutorials. Worthless before discovery exists; revisit after M9.

Open decisions

Six forks need an owner. The defaults below are what this roadmap assumes unless told otherwise.

1. Outbound A2A delegation — blocks M1. Either implement TaskExecutor as an HTTP adapter to an external runtime, or keep the inbound direction and the agent card and drop outbound delegation. Default: drop it. It is more honest than a synthetic success and removes an obligation to maintain somebody else's execution layer.
2. Key compatibility — blocks M2. Default: the existing API_KEYS setting keeps working as a synthetic principal with full rights, and the move to scoped keys is documented without a deadline.
3. Source of cost data — blocks M8. Default: an opt-in report_usage tool rather than deriving usage from traces.
4. Context search mechanism — Default: PostgreSQL full-text search, no embeddings, for the reason given in M7.
5. Public demo instance — blocks M9. Needs a domain, DNS and secrets from the owner.
6. Transition mode for 2026-07-28 — whether the old session-based semantics are accepted for a while. Default: no. A clean cut is acceptable because the twelve-month deprecation window applies to clients regardless.