omniroadmap

OmniRoadmap Core

Core interfaces and canonical types for omniroadmap — a common, tool-agnostic representation of roadmap/product-management data (features, epics, initiatives, releases, objectives) that adapters for specific SaaS tools (Aha!, ProductBoard, ...) convert into.

This package follows the same shape as the omni*-core pattern used elsewhere in this ecosystem (see github.com/plexusone/omnillm-core for the canonical example): a small interface, canonical types, a provider registry, sentinel/structured errors, and a provider/providertest conformance-test suite every adapter runs against itself.

Where adapters live

Unlike omni-openai/omni-anthropic (separate repos wrapping a pre-existing official third-party SDK), the roadmap-tool SDKs in this ecosystem are built from scratch (no official Go SDK exists for Aha!, ProductBoard, or JPD) — so their adapters live as an embedded omniroadmap/ subpackage inside the SDK repo itself, not as a separate repo:

This mirrors elevenlabs-go/omnivoice/ and opik-go/integrations/omnillm/. The batteries-included omniroadmap repo bundles all of them plus the higher-level layers (Dolt store, sync engine, MoSCoW/RICE fieldmap, prism-roadmap export).

Provider interface

type Provider interface {
    Name() string
    Close() error
    Capabilities() Capabilities

    ListItems(ctx context.Context, req *ListItemsRequest) (*ListItemsResponse, error)
    GetItem(ctx context.Context, req *GetItemRequest) (*Item, error)
    ListReleases(ctx context.Context, req *ListReleasesRequest) (*ListReleasesResponse, error)
    ListStatuses(ctx context.Context, req *ListStatusesRequest) (*ListStatusesResponse, error)
    ListCustomFieldDefinitions(ctx context.Context, req *ListCustomFieldDefinitionsRequest) (*ListCustomFieldDefinitionsResponse, error)
}

Read-only in v0.1 — no write verbs yet.

Canonical types

Item, Release, Status, CustomField, CustomFieldDefinition, Person, Link, RICE, and Capabilities live in the provider package. Fields common across source tools are typed; anything provider-specific with no canonical equivalent lives in a Metadata map[string]any passthrough, namespaced by provider (e.g. "aha.progress_source").

Item also carries optional prioritization fields — MoSCoW string (empty = unset) and RICE *RICE (raw numeric inputs). Adapters never populate these (no PM tool exposes them as first-class API fields); they're filled downstream by a per-tenant custom-field mapping layer, since some Aha tenants store MoSCoW/RICE as custom fields.

These types are intentionally not wrappers around github.com/grokify/prism-roadmap's types — prism-roadmap's rmi.RoadmapItem centers on prioritization scoring (MoSCoW, RICE) that source APIs don't expose, and has no source-provenance concept. A separate, optional converter into prism-roadmap types may be added later if something needs it.

Writing an adapter

1. Implement provider.Provider in a omniroadmap subpackage of your SDK repo.
2. Register it from an init():

   func init() {
       _ = omniroadmap.RegisterProvider("aha", func(config any) (provider.Provider, error) {
           client, ok := config.(*aha.Client)
           if !ok {
               return nil, fmt.Errorf("omniroadmap/aha: expected *aha.Client, got %T", config)
           }
           return &Provider{client: client}, nil
       })
   }
   

3. Test it against the shared conformance suite:

   func TestConformance(t *testing.T) {
       providertest.RunAll(t, providertest.Config{
           Provider:        NewProvider(client),
           SkipIntegration: !hasLiveCredentials(),
       })
   }
   

Development

go build ./...
go vet ./...
golangci-lint run ./...
go test ./...