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:
- Identity tests: Name, role, description correct
- Auth tests: ValidateAuth with good/bad credentials
- Mapping tests: Status/priority normalization round-trips
- Outbound tests: CreateTask/UpdateTask (mock API or tempdir)
- 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 | — |