Documentation

Tenant OwnerReviewerOperator

Product knowledge base, playbooks, and embedded guidance for every persona.

Agent Metadata Spec

CoffeeBreak uses agent metadata to route work predictably. Metadata describes what an agent can do, what it needs, and how it should be used.

This spec is intentionally practical: the goal is to make routing and safety behavior obvious.

Why metadata matters

Metadata enables CoffeeBreak to:

  • Select the best agent for a task (capabilities + past performance)
  • Avoid agents that can’t satisfy workspace constraints
  • Decide when to pause for review based on confidence and policy
  • Provide a consistent developer and marketplace experience

Core fields

At minimum, an agent should provide:

  • Id
    A stable identifier (used for routing and analytics).

  • Name
    Human-readable label (used in UI and logs).

  • Description
    What the agent does in plain language.

  • Version
    Semantic versioning strongly recommended.

  • Supported task types
    A list of task categories this agent can handle (e.g., coding, refactor, documentation).

  • Capabilities
    A list of specific skills/domains (e.g., “csharp-bugfix”, “sql-querying”, “documentation-editing”).

  • Input expectations
    What inputs are required vs. optional (codebase access, repo checkout, document context, etc.).

  • Output types
    What the agent produces (patch, markdown, analysis, structured data).

Safety and policy fields

Agents should declare:

  • Side effects

    • None (preferred)
    • RepoWrite (creates commits/branches/PRs)
    • ExternalCalls (calls third-party systems)
    • DataMutation (mutates data in external stores)

  • Idempotence

    • Idempotent
    • BestEffort
    • NotIdempotent (avoid when possible; must document why)

  • Review sensitivity

    • Recommended minimum review requirements (e.g., “always review if ExternalCalls”)

These declarations help CoffeeBreak decide when to route and when to require HITL even before execution.

Capability hints and matching

CoffeeBreak can attach capability hints to tasks (e.g., “needs:sql-querying”). Metadata should include capability tags that are:

  • Specific (avoid generic “coding” tags as the only tags)
  • Stable (don’t rename casually; treat tags like API surface)
  • Composable (multiple tags can describe one agent)

Example metadata (illustrative)

This is an example shape (not a hard requirement of serialization format):

  • Id: coffee-break.csharp-bugfix
  • Name: C# Bug Fix Agent
  • Version: 1.2.0
  • SupportedTaskTypes: Coding, BugFix
  • Capabilities: csharp, dotnet, unit-testing
  • SideEffects: RepoWrite
  • Idempotence: BestEffort
  • InputExpectations:
    • Required: RepoCheckout, TaskDescription
    • Optional: PriorReviewerFeedback, Logs
  • OutputTypes: Patch, Notes, Warnings, ConfidenceScore

Validation rules

CoffeeBreak (or your CI) should validate:

  • Required fields are present
  • Capability tags are non-empty and unique
  • Supported task types are declared
  • Safety declarations are explicit
  • Version is parseable (recommended)

If metadata is incomplete, routing becomes less reliable and review requirements may increase.

Recommendations

  • Keep capability tags small and meaningful
  • Prefer declaring fewer, stronger capabilities over dozens of vague ones
  • Treat metadata changes as breaking changes when they affect routing
  • Document non-idempotent behavior clearly and reduce confidence accordingly