waggle-protocol

name: waggle-protocol description: > Waggle Protocol v1 specification. Defines the 15 core fields, 9 extended fields, task state machine, dispatch readiness checks, and execution environments. Use this skill when you need to understand the waggle protocol, check field definitions, or verify state transitions. Trigger on: "protocol spec", "waggle spec", "field definitions", "state machine", "task schema", "core fields". user-invocable: true

Waggle Protocol v1

Overview

Waggle Protocol is a specification for independent AI agent instances to coordinate asynchronously through a shared task board.

Agents discover tasks, claim them, execute, and hand off results. The backing data store is irrelevant — any storage that implements this specification's fields and state transitions is a Waggle-compatible task board.

Core Fields

Every Waggle-compatible task board MUST support these 16 fields:

Extended Fields (optional)

Providers MAY support these additional fields. Skills degrade gracefully if absent.

Issuer Auto-Populate Contract (v2.8.1+)

The Issuer core field is always populated by the active provider during task creation. Skills (managing-tasks, ingesting-messages, etc.) MUST NOT pass an Issuer value when invoking the provider's Create Task operation.

Why

Prior to v2.8.1, skills explicitly set Issuer = current_user. Field telemetry showed ~27% of tasks ended up with empty Issuer due to multiple failure paths: scheduled tasks where current_user could not be resolved, third-party automations writing directly to the data store, intake flows omitting Issuer in the create payload, and direct edits in the provider UI. Centralizing Issuer population in each provider eliminates every one of those paths.

Per-provider implementation

Provider preconditions

Providers using template substitution (SQLite, Turso) MUST halt with an error before executing Create Task if current_user.id resolves to the unresolved-identity sentinel "unknown". This enforces "no anonymous tasks" — every Issuer in the data store points to a real identity. (v2.7.x also halted on the literal "local"; v2.8.1 removed "local" from the identity chain entirely — providers now derive id from $WAGGLE_USER_ID → $USER → "unknown", so the only remaining anonymous case is "unknown".)

The Notion provider does not need this check because Notion's API binds created_by to the API token owner, which is always a real user.

Write-once enforcement

Notion's created_by is read-only after creation. SQLite/Turso providers MUST NOT include issuer in their Update Task templates. Delegation (assigning-to-others / delegating-tasks) updates Assignee but never touches Issuer.

Filtering by Issuer

Notion's API filters created_by columns using the created_by:{contains: <user_id>} operator (this is distinct from the people operator used for person columns — the operator key matches the column type). The notion-provider filter recipes in v2.8.1 use this syntax.

SQLite/Turso providers filter via WHERE issuer = '<user_id>' for exact match (the column is now a single-value TEXT, not a JSON array, so the v2.7.x LIKE '%<user_id>%' pattern is unnecessary).

Subtask Hierarchy

Waggle supports a strict 2-level task hierarchy via the Parent Task field.

Constraints

• 2-level limit: A subtask (task with non-null parentTask) MUST NOT have children of its own. Implementations MUST reject attempts to create a 3rd level.
• No circular references: A task cannot reference itself as its parent.

Auto-Cascading Transitions

When all subtasks of a parent reach Done, the parent auto-transitions to Done. When a subtask is added to or re-opened on a Done parent, the parent reverts to In Progress. These are system-initiated transitions that bypass normal validation.

Execution Independence

Subtasks are eligible for execution regardless of their parent task's status. The hierarchy is for progress tracking, not execution gating.

State Machine

Backlog → Ready → In Progress → In Review → Done
                       ↓
                    Blocked

Any → Cancelled

Transition Conditions

Invalid Transitions

All transitions not listed above are invalid. Implementations MUST reject them.

Dispatch Readiness Check

Before transitioning a task from Ready → In Progress, the orchestrator MUST verify:

If any check fails, the orchestrator MUST NOT dispatch. Instead, it should prompt the user to fill the missing information.

Quality Spec (v2.8.0+)

Waggle v2.8.0 introduces a 3-layer quality gate system to ensure agent-reproducible task specs.

Layer 0: Task-Worthiness Advisory

Applied at intake (ingesting-messages Phase A) only. Classifies whether an incoming item is task-shaped.

Waggle never silently discards user-created items. Layer 0 surfaces a suggestion in the intake confirmation table; the user always has the final say via [Create as task] / [Convert to note] / [Discard]. Items chosen as [Create as task] are tagged worthiness:calendar-like or worthiness:info-only and skip Layer 1/2 for the rest of their lifecycle.

Layer 1: Rubric (deterministic)

Applied at every status transition into Ready or beyond. No LLM involvement.

AC rules (each failing rule contributes to verdict):

EP rules:

Layer 2: Intent Reproducibility Check (LLM)

The task-quality-reviewer-agent evaluates a task spec along 5 axes from the perspective of "a new colleague handed only this spec, with access to the team's tools — can they reproduce the issuer's intent?":

Verdict (rules applied in order — first match wins):

• REJECT — ≥1 axis ✗ (fundamental rewrite required)
• NEEDS_REFINEMENT — ≥1 axis △ and no ✗ (specific suggested fixes can elevate to PASS; the number of △ axes is informational only)
• PASS — all 5 axes ◯

Reserved Placeholder Prefixes

Exactly 2 prefixes are reserved at the protocol level:

Skills MUST NOT introduce additional reserved prefixes. Other tags (e.g., worthiness:*) live on the Tags field, not as title or AC prefixes.

Quality Verdict Cache Format (v1)

The Quality Verdict core field stores at most one line in the format:

{verdict} hash=<sha256(Title|Description|AC|EP)[:8]> @<iso8601> v1 [suppressed-until=<iso8601>]

• verdict ∈ PASS, NEEDS_REFINEMENT, REJECT
• hash is a content fingerprint over the first 8 hex chars of SHA-256 of Title|Description|AC|EP (pipe-delimited). Any edit to those fields invalidates the cache automatically.
• suppressed-until (optional) freezes re-review for 7 days after 2 consecutive same-axis failures (anti-grinding guard).
• v1 is the format version. Future versions remain parse-compatible.

Live Reviewer invocation is allowed at: planning-tasks, managing-tasks planning-assisted creation, ingesting-messages Phase A.5, running-daily-tasks Step 2.6, delegating-tasks (cache miss), monitoring-tasks --deep.

Live Reviewer invocation is forbidden at: executing-tasks dispatch (cache-only), managing-tasks pre-Ready status transition (cache-only). These are hot paths.

Findings Persistence

A non-PASS verdict line alone tells a later session that a spec fell short, not why. The gaps and suggested fixes behind a NEEDS_REFINEMENT / REJECT verdict are persisted on the task itself as a Quality Review Findings block inside the Context extended field:

• The block is managed by the verdict pipeline (reviewing-quality skill) — written on non-PASS verdicts, replaced in place on re-review, removed on PASS. Users do not edit it directly.
• It carries the same content hash as the verdict line; a hash mismatch marks the findings as stale and they are ignored.
• Context is not part of the content hash, so managing the block never invalidates the verdict cache.
• Graceful degradation: when a provider does not support Context, findings surface in conversation only and the verdict line still caches.

This is what makes the cache-only hot paths able to present "what to fix" (not just the verdict) when gating a promotion or dispatch. The exact block format is owned by the reviewing-quality skill's reference documentation, kept in sync with this section.

Calibration Requirement

Before a Waggle release that ships the Reviewer agent or Layer 0 classifier, implementations MUST measure agreement against hand-labeled samples. Recommended bar: ≥80% on 30 hand-labeled tasks. Below threshold, the affected layer ships disabled.

Provider Interface

A Waggle provider is any backend that implements the following operations:

Provider Registration

Providers are delivered as separate plugins (e.g., waggle-notion, waggle-sqlite, waggle-turso). Detection happens via <available_skills> on Cowork or installed_plugins.json on CLI/Desktop. See the detecting-provider skill for the detection algorithm.

Execution Environments

See provider-contract/references/environment-detection.md for the full multi-signal Cowork detection logic.

All environments support single-task execution in the current session.

Versioning

This is Waggle Protocol v1. Breaking changes to Core fields or the state machine require a major version bump.