@biroai/agentdocs

Schema definitions and validators for the AgentDocs format — the three-file convention (brief.md + tasks.yaml + playbooks/) that AI agents use to discover, understand, and orchestrate tools.

This package is the interface layer between:

• Biro — the reference orchestration platform that consumes and publishes AgentDocs
• Tool authors — anyone publishing docs for an API, CLI, SDK, or internal process
• Agent frameworks — Claude Code, Cursor, LangChain, MCP, and any other consumer

Framework-agnostic, transport-agnostic, MIT-licensed.

What's new in 0.2.0

Three additive, fully backward-compatible changes:

• tasks.yaml can now declare an empty actions: []. Useful for scaffolds and drafts. validateTasksDocument emits a warning (not an error) on empty catalogs.
• New optional category field on tasks.yaml — parallel "discipline" axis (process / tool / reference / policy) alongside the existing type "surface kind" (api / cli / sdk / internal / process). Lets platforms round-trip both classifications losslessly.
• parsePlaybookMarkdown(raw) — convenience helper that splits a playbook .md into typed frontmatter + body, validating the frontmatter against playbookMarkdownFrontmatterSchema.

Under the hood, zod-inferred schema shapes are replaced with hand-written interface types — dist/schemas/tasks.d.ts drops from ~1100 lines to ~140. See CHANGELOG.md for details.

Install

pnpm add @biroai/agentdocs
# or npm install / yarn add

Usage

Validate a tasks.yaml document

import { validateTasksDocument } from "@biroai/agentdocs";

const result = validateTasksDocument({
  tool: "stripe",
  type: "api",
  actions: [
    {
      name: "create-charge",
      method: "POST",
      path: "/v1/charges",
      solves: ["payment-processing"],
    },
  ],
});

if (!result.ok) {
  for (const err of result.errors) {
    console.error(`${err.path}: ${err.message}`);
  }
}

Validate a brief.md against a custom token budget

import { validateBriefContent } from "@biroai/agentdocs";

const result = validateBriefContent(briefMarkdown, {
  maxTokens: 1000, // custom — default is 500 per the spec
  maxBytes: 4000,
  maxLines: 40,
  estimateTokens: (s) => Math.ceil(s.length / 4),
});

console.log(result.metrics); // { byteLength, estimatedTokens, lineCount }

Validate a composable playbook DAG

import { validatePlaybookDag } from "@biroai/agentdocs";

const result = validatePlaybookDag({
  playbook: "deploy-to-production",
  inputs: { service: { type: "string", required: true } },
  steps: [
    { name: "build", run: "npm run build" },
    {
      name: "deploy",
      playbook: "deploy-service",
      inputs: {
        service: "{{ inputs.service }}",
        artifact: "{{ steps.build.outputs.artifact }}",
      },
      gate: "must_pass",
    },
  ],
});

if (!result.ok) {
  // Errors cover: duplicate step names, undeclared input refs,
  // unknown step refs, forward-reference ordering violations
  console.error(result.errors);
}

Schemas directly

Need the raw Zod schemas? Import from the schemas subpath:

import {
  tasksDocumentSchema,
  briefContentSchema,
  playbookDagSchema,
} from "@biroai/agentdocs/schemas";

// Use with zod-to-openapi, zod-to-json-schema, or anywhere else

Exports

| Export | Purpose | |---|---| | tasksDocumentSchema | Zod schema for tasks.yaml document root | | briefContentSchema / buildBriefContentSchema(budget) | Token-budgeted schema for brief.md content | | playbookDagSchema | Phase-3 composable DAG playbook | | playbookMarkdownFrontmatterSchema | Phase-1/2 markdown frontmatter | | validateTasksDocument(input) | Cross-field validator with warnings + errors | | validateBriefContent(input, budget?) | Validator with byte/token/line metrics | | validatePlaybookDag(input) | DAG validator with reference-integrity checks | | parsePlaybookMarkdown(raw) | Split a playbook .md into { frontmatter?, body, errors } (new in 0.2.0) |

Full type exports for every schema via TypeScript inference (TasksDocument, Action, Param, PlaybookDag, PlaybookStep, etc.).

Spec principles

1. Static files, not an API — zero latency, works offline, no vendor lock-in
2. Convention over configuration — agents find docs by looking in .agentdocs/
3. Hierarchical retrieval — brief in prompt, catalog on demand, playbook when needed
4. Format over platform — this package is the product; platforms are implementations
5. Build-vs-reuse — solves + alternatives fields make existing tools discoverable
6. Domain-agnostic — format works for code, legal, finance, ops — any domain where agents need to discover and use tools

Evolution path

This package currently ships schemas for:

• Phase 1 — flat markdown playbooks (shipping today)
• Phase 2 — markdown with YAML frontmatter for typed inputs/outputs
• Phase 3 — composable YAML DAG playbooks with gates, conditionals, error handlers, cross-playbook composition

Phase 4 (marketplace) and Phase 5 (execution-trace-driven evolution) are properties of implementations consuming the spec, not of the spec itself.

License

MIT. Fork freely; the spec wins when many implementations compete on quality of the consumer experience.