How to Write a Flow Mesh Provider

This guide walks you through creating a custom provider for Flow Mesh.

Overview

A provider connects an external system (e.g., Jira, Notion, Todoist) to Flow Mesh. Every provider implements 8 slots:

Slot What Required?
1. Identity Name, icon, color, role ✅
2. Auth Credentials, validation ✅
3. Discovery List projects/teams/vaults ✅
4. Mapping Link mesh to external entity ✅
5. Outbound Create/update/close tasks ✅
6. Inbound Poll or webhook for changes ✅
7. UI Setup fields, status check Optional
8. Dependencies Binary deps (e.g., CLI tools) Optional

Quick Start

package myprovider

import (
    "github.com/philoveracity/flow-mesh/internal/provider"
)

type Provider struct {
    provider.BaseProvider // Provides no-op defaults for slots 7-8
    apiKey string
}

func New(cfg map[string]string) *Provider {
    return &Provider{apiKey: cfg["api_key"]}
}

// Slot 1: Identity
func (p *Provider) Name() string        { return "my-provider" }
func (p *Provider) DisplayName() string  { return "My Provider" }
func (p *Provider) Icon() string         { return "M12 2L2 7v10l10 5 10-5V7z" }
func (p *Provider) Color() string        { return "#FF6B6B" }
func (p *Provider) Role() provider.Role  { return provider.RoleTracker }
func (p *Provider) Description() string  { return "My custom provider" }

// Slot 2: Auth
func (p *Provider) AuthFields() []provider.Field {
    return []provider.Field{
        {Key: "api_key", Label: "API Key", Type: provider.FieldPassword, Required: true},
    }
}
func (p *Provider) ValidateAuth() error { /* test connection */ }
func (p *Provider) EnvVars() []provider.EnvVar { /* env var overrides */ }

// ... implement remaining slots

Provider Roles

Role What Examples
RoleSource Where code/agents work git-beads, git-plain
RoleTracker Where PM tracks work Asana, Linear, Jira, GitHub Issues
RoleKnowledge Where docs live Obsidian, Notion, filesystem
RoleChat Where team communicates Discord, Slack, Teams

One provider per role per mesh. If you need both Jira (tracker) and Notion (knowledge) in one mesh, that's fine — different roles.

Canonical Types

Status

StatusBacklog    = "backlog"
StatusTodo       = "todo"
StatusInProgress = "in_progress"
StatusReview     = "review"
StatusDone       = "done"

Priority

PriorityCritical = "critical"
PriorityHigh     = "high"
PriorityMedium   = "medium"
PriorityLow      = "low"

Map your system's status/priority to these canonical types. See githubprov or linearprov for examples.

Inbound Modes

Mode When Example
InboundWebhook System pushes to you Asana, Linear, GitHub
InboundPoll You poll the API Todoist, any REST API
InboundFileWatch Watch filesystem Obsidian, git-plain

Testing

Every provider should have:

  1. Identity tests: Name, role, description correct
  2. Auth tests: ValidateAuth with good/bad credentials
  3. Mapping tests: Status/priority normalization round-trips
  4. Outbound tests: CreateTask/UpdateTask (mock API or tempdir)
  5. Inbound tests: Poll returns correct events

See internal/provider/obsidianprov/obsidian_test.go for a complete example.

Registering Your Provider

Add to buildProviderRegistry() in internal/api/api.go:

case "my-provider":
    prov = myprovider.New(provCfg.Config)

Provider Quality Tiers

Tier Badge Criteria
Official ✅ Maintained by Flow Mesh team, full test suite
Verified ☑️ Community-built, reviewed, tests pass
Community 🏷️ Self-published, not reviewed

Existing Providers

Provider Role Status Tests
Asana Tracker ✅ Official 8
Discord Chat ✅ Official 6
Git-Beads Source ✅ Official 18
GitHub Issues Tracker ✅ Official 15
Slack Chat ⚠️ Provider OK, Transport stub 10
Linear Tracker ✅ Official 10
Obsidian Knowledge ✅ Official 13
Git-Plain Source ✅ Official 11
Filesystem Knowledge ✅ Official 6
Jira Tracker 🏷️ Stub —
Notion Knowledge 🏷️ Stub —
ClickUp Tracker 🏷️ Stub —
Trello Tracker 🏷️ Stub —
Todoist Tracker 🏷️ Stub —

Generated from the Flow Mesh repository by scripts/build-docs-site.sh. If a page is wrong here, the file it was rendered from is wrong.