Waggle provider plugin development guide and interface contract. Defines the required SKILL.md sections, data shapes, naming conventions, and compliance checklist for building a waggle provider plugin. Trigger on: "provider contract", "provider interface", "create provider plugin", "new provider", "provider compliance", "how to build a provider".
Waggle provider plugin development guide and interface contract. Defines the required SKILL.md sections, data shapes, naming conventions, and compliance checklist for building a waggle provider plugin. Trigger on: "provider contract", "provider interface", "create provider plugin", "new provider", "provider compliance", "how to build a provider".
user-invocable
true
Waggle Provider Contract
This document defines the interface contract for building a waggle provider plugin. A provider plugin connects waggle to a specific data store (Notion, SQLite, Turso, etc.) by implementing a standardized set of operations and SKILL.md sections.
How Provider Discovery Works
Waggle core discovers provider skills differently depending on the runtime environment:
Cowork: Provider skills appear in the <available_skills> system prompt block. Each skill is listed with <name>, <description>, and <location>.
CLI / Claude Desktop: Provider skills are registered via installed_plugins.json. The plugin's .claude-plugin/plugin.json declares the plugin metadata.
In all environments, waggle core loads the provider SKILL.md via the Skill tool. ${CLAUDE_PLUGIN_ROOT} in the provider SKILL.md is automatically resolved to the provider plugin's absolute path.
Naming Conventions
Follow these naming rules strictly:
Entity
Pattern
Example
Plugin directory
waggle-{provider}
waggle-sqlite
Setup skill
{provider}-setup
sqlite-setup
Provider skill
{provider}-provider
sqlite-provider
Plugin name in plugin.json
waggle-{provider}
waggle-sqlite
The setup skill MUST be user-invocable: true.
The provider skill MUST be user-invocable: false.
The provider skill MUST operate silently: it returns results to the invoking skill and
produces no user-facing narration of its own (no progress reports, no step announcements).
Only errors, warnings, and prompts required to proceed may surface directly. The invoking
skill owns all user communication — this keeps the user-visible output of a waggle flow
identical regardless of which provider backs it.
The {provider}-provider/SKILL.md file MUST contain all of the following sections with exact headings. Waggle core skills reference these sections by name.
1. Config Retrieval
Retrieve provider configuration (database IDs, constants) and populate the headless_config session variable.
Requirements:
MUST be self-sufficient — do not depend on a local config file as the sole source.
Each provider uses its natural storage for config:
Notion: Search for the "Waggle Config" page, parse JSON code block.
Turso: Read from TURSO_URL and TURSO_AUTH_TOKEN environment variables.
SQLite: Use a default path (~/.waggle/waggle.db) or WAGGLE_SQLITE_PATH env var.
~/.waggle/config.json MAY be used as a local cache for faster startup, but MUST NOT be the only source.
If config is not found, instruct the user to run the {provider}-setup skill, then stop.
The headless_config object MUST include at minimum:
tasksDatabaseId (or equivalent identifier for the tasks data source)
Optional fields:
teamsDatabaseId
intakeLogDatabaseId
2. Schema Validation & Auto-Repair
Verify that all 15 Core fields exist in the backing store. See references/task-schema.md for the complete field list.
Requirements:
On startup, check every Core field exists with the correct type.
If any Core field is missing, automatically repair it — create the field with sensible defaults.
Never ask the user to manually fix the schema.
After repair, re-verify and continue.
3. CRUD Operations
Implement Create, Read, Update, and Delete for tasks.
Requirements:
Create: Accept all Core and Extended fields. Return the created task ID.
Read: Retrieve a single task by ID with all field values.
Update: Update one or more fields on an existing task by ID.
Delete: Delete a task by ID.
Document which MCP tools or API calls are used for each operation.
4. Query Tasks
Filter and sort tasks, returning results in the standard query output format.
Requirements:
Accept filter and sort parameters.
Return { "results": [Task, Task, ...] } — see references/query-output-format.md.
Support filtering by: Status, Priority, Executor, Assignee.
Support sorting by: Priority, Due Date.
Document the query mechanism (API script, SQL query, MCP tool).
Include a "Fetch All Tasks" variant with no filter for view server data push.
Include a "Displaying Task Lists" variant that extracts only display-relevant fields.
5. Identity Resolution
Resolve the current user, team membership, and org members.
Requirements:
Current User: Return { id, name, email }. Provide a fallback using $USER env var if the provider API is unavailable.
Team Membership: Given teamsDatabaseId, determine which teams the current user belongs to. Handle single-team, multi-team (ask user), and no-team cases.
Org Members: List all workspace/org members as { id, name, email }[]. Provide a fallback (empty array) if unavailable.
Self-Task Detection: Describe how to check if a task is assigned to the current user.
6. View Server Data Push
Push task data to the local view server after any task mutation.
Requirements:
Fetch all tasks from the data source.
Transform into the TasksResponse shape: { "tasks": [...], "updatedAt": "<ISO timestamp>" }.
POST to http://localhost:3456/api/data.
Silently skip if the view server is not running (check health endpoint first).
7. On Completion Template
Define the instructions injected into dispatch prompts so dispatched agents know how to report results. See references/dispatch-completion-template.md for the full specification.
Requirements:
Include the task ID placeholder.
Specify how to write results to Agent Output.
Specify how to update Status based on Requires Review.
Specify how to record errors to Error Message.
Use absolute paths for any scripts. MUST NOT use ${CLAUDE_PLUGIN_ROOT}.
8. Error Handling
Define error categories and retry behavior.
Requirements:
Classify errors into retryable (transient network errors, rate limits) and terminal (auth failures, missing permissions, invalid schema).
For retryable errors: specify max retries and backoff strategy.
For terminal errors: specify the user-facing message and recovery action.
Provider API errors MUST NOT crash the skill — handle gracefully and report.
Script Path Convention
Bash scripts in the provider plugin MUST follow these rules:
Use the SCRIPT_DIR pattern for self-referencing paths:
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
MUST NOT use ${CLAUDE_PLUGIN_ROOT} in bash scripts. This variable is only available in the SKILL.md instruction context, not in shell execution.
SKILL.md instructions MUST reference their own scripts using ${CLAUDE_SKILL_DIR}:
${CLAUDE_SKILL_DIR} is the official Claude Code runtime variable for the current skill's own directory; it resolves correctly regardless of working directory and is robust to skill rename/relocation. Never hardcode ${CLAUDE_PLUGIN_ROOT}/skills/<this-skill-name>/... — that pattern silently breaks on rename.
Scripts that call other scripts within the plugin MUST use SCRIPT_DIR-relative paths:
source"${SCRIPT_DIR}/helpers.sh"
Config Storage
Provider configuration is cached per execution environment so bootstrap can skip remote lookups on subsequent sessions:
CLI / Claude Desktop: environment variables in ~/.claude/settings.json (under the env field).
Cowork: a <waggle-config>{json}</waggle-config> block in Global Instructions, since Cowork has no persistent local filesystem.
The legacy ~/.waggle/config.json file is deprecated — use the health-checking skill to migrate.
Query Tasks — filter/sort with { "results": [...] } output format
Identity Resolution — current user, teams, org members, self-task detection
View Server Data Push — TasksResponse shape, POST to localhost:3456
On Completion Template — task ID placeholder, absolute paths, no ${CLAUDE_PLUGIN_ROOT}
Error Handling — retryable vs terminal classification
Script Conventions
All bash scripts use SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" pattern
No ${CLAUDE_PLUGIN_ROOT} in bash scripts
SKILL.md uses ${CLAUDE_PLUGIN_ROOT} for script references
Schema Support
All 15 Core fields supported with correct types
Extended fields supported with graceful degradation if absent
Auto-repair creates missing fields without user intervention
supportsFileHosting declared for the Attachments (file[]) field. Providers with
supportsFileHosting=false accept attachments only as externally-hosted URLs; skills MUST NOT upload local
files to them. See task-schema § Provider Mapping.
Data Format
Query output matches { "results": [Task, ...] } format
Task objects include id and all populated field values
