How to Integrate Beads into an AI-Orchestrated System for Agentic Task Planning

Modern AI-orchestrated systems tend to accumulate “planning exhaust”: ad‑hoc TODOs in READMEs, a tasks.md in each service, Jira tickets that drift away from reality, and a pile of half-finished notes no one trusts. When you add planner agents into the mix—agents that reason about work, generate subtasks, and coordinate execution—the cost of that fragmentation multiplies. The system needs a single source of truth for tasks that is accessible to both humans and agents, with enough structure to support automation but not so heavy that developers avoid it.

This is where Beads (https://beads.gascity.com) fits nicely as a task management backbone for an orchestration stack: it provides a consistent interface for capturing, organizing, and updating tasks, while your AI orchestration layer supplies the intelligence and automation.

This article walks through an architecture where:

• Your orchestration has a Task Planner agent responsible for decomposing goals into actionable tasks.
• The planner interacts with Beads through a dedicated skill (a tool interface).
• Worker agents execute tasks and report progress back into Beads.
• Developers stop scattering Markdown task files across the repo and instead get a living, queryable task graph.

Along the way, we’ll cover design patterns, a practical skill contract, task lifecycle mechanics, and how this affects delivery quality.

Why Beads as the task system in an AI orchestration stack?

AI orchestration systems typically solve three problems:

1. Planning (turn a goal into tasks),
2. Execution (run tasks via tools/agents),
3. Coordination (state, dependencies, progress, handoffs).

If task state lives in random Markdown files, the system loses coordination: there’s no stable identifier, no uniform schema, no way to enforce lifecycle transitions, and no easy integration point for agents.

A task system like Beads becomes the “coordination substrate” because it can offer:

• Stable task IDs for referencing work in code, commits, PRs, and agent messages.
• Structured fields (status, priority, owner, due dates, labels) that agents can read/write reliably.
• Centralized visibility for humans and agents: the planner can “see” what exists and avoid duplicates.
• Automation hooks: the orchestration layer can build predictable workflows around task creation, transitions, and reporting.

The key is not simply “tracking tasks”, but enabling a closed loop:

Plan → Create tasks → Execute → Report → Replan based on reality

With scattered Markdown, that loop breaks at “create tasks” (no consistent format) and “report” (no canonical destination).

The core architecture: Planner agent + Beads skill + Worker agents

A clean mental model is to treat Beads as a task database with a UI, and your orchestration as the control plane.

Components

1) Task Planner Agent

• Input: high-level goal (e.g., “Add OAuth login”, “Refactor billing pipeline”).
• Reads context: repo structure, existing tasks in Beads, recent changes.
• Outputs: task breakdown with dependencies, acceptance criteria, and suggested execution order.

2) Beads Skill (tool interface)

• Provides structured operations for the planner/agents:
  • list/search tasks,
  • create tasks,
  • update tasks,
  • link tasks (dependencies, parent/child),
  • comment/log progress.

3) Worker Agents

• Pick up tasks from Beads (or assigned via orchestrator).
• Execute: code changes, tests, documentation, deployment steps.
• Report results back into Beads: status updates, notes, links to PRs/commits/build logs.

4) Orchestrator

• Routes tasks to workers, enforces policies (e.g., required reviews), resolves concurrency.
• Maintains run state, retries, tool credentials, and auditing.

The data flow

A typical run looks like this:

1. A user (or CI trigger) submits a goal: “Implement feature X.”
2. Orchestrator asks Planner: “Propose a plan and tasks.”
3. Planner uses beads.searchTasks() to see what already exists and avoid duplication.
4. Planner uses beads.createTask() to create a parent “Epic/Initiative” plus child tasks.
5. Orchestrator assigns tasks to Worker agents.
6. Worker agents execute tasks; they use beads.updateTask() and beads.addComment() to report.
7. Planner periodically re-checks Beads to adjust plan based on what’s done, blocked, or failing.

This turns Beads into the shared memory for the system.

Designing the Beads skill: keep it boring, strict, and predictable

Agent tooling succeeds when it has stable contracts and low ambiguity. The Beads skill should be intentionally limited and explicit—agents shouldn’t be “clicking around” or scraping HTML; they should call a small, well-defined interface.

Below is an example skill contract (pseudo-API). You can adapt it to whatever Beads exposes (API, webhooks, automation endpoints), but the design principles remain the same.

Recommended minimum operations

• search_tasks(query, status?, labels?, assignee?, limit?)
• get_task(task_id)
• create_task(title, description, labels?, priority?, parent_id?, links?, acceptance_criteria?)
• update_task(task_id, status?, title?, description?, labels?, priority?, assignee?)
• add_comment(task_id, comment, artifacts?)
• link_tasks(task_id, links=[{type, target_task_id}])

A strict JSON schema (example)

{
  "tool": "beads.create_task",
  "arguments": {
    "title": "Add OAuth callback route",
    "description": "Implement /auth/callback handler for Google OAuth. Store tokens securely and create session.",
    "labels": ["auth", "backend", "oauth"],
    "priority": "P1",
    "parent_id": "BEADS-123",
    "acceptance_criteria": [
      "Callback exchanges code for tokens",
      "Tokens stored using existing secret storage",
      "Session cookie set with correct flags",
      "Unit tests cover error cases",
      "Docs updated in /docs/auth.md"
    ],
    "links": [
      {"type": "relates_to", "url": "https://github.com/org/repo/issues/77"}
    ]
  }
}

This matters because the planner’s outputs become actionable and auditable. The acceptance criteria become the worker’s checklist, and the orchestrator can even enforce that the criteria are addressed before moving to “Done”.

Task statuses as a lifecycle, not decoration

The biggest improvement you can make is to standardize a small set of statuses and enforce valid transitions. For example:

• Proposed → Ready → In Progress → In Review → Done
• Side states: Blocked, Won’t Do

Your orchestrator should treat status transitions as events:

• When a task moves to Ready, it becomes eligible for assignment.
• When it moves to In Review, the orchestrator triggers a PR review workflow.
• When Blocked, the planner is invoked to either resolve dependencies or propose alternatives.

If Beads supports custom workflows, model these states there; if not, enforce them in your skill layer and store them in fields/labels.

How the planner agent should think: task graphs, not checklists

Planner agents fail when they produce shallow TODO lists. What you want is a task graph: tasks with dependencies, clear deliverables, and verification steps.

A robust planner prompt (conceptually) should push toward:

• identifying unknowns and creating “spike” tasks,
• separating architecture decisions from implementation,
• including test and deployment work,
• capturing cross-cutting changes (docs, monitoring, migration scripts).

Example: from goal to Beads tasks

Goal: “Replace ad-hoc Markdown task tracking with Beads-integrated orchestration.”

The planner might create:

• Epic: “Adopt Beads as orchestration task backend”
  • Task: “Define Beads task schema (fields, labels, lifecycle)”
  • Task: “Implement Beads skill wrapper (search/create/update/comment/link)”
  • Task: “Add task-to-PR linkage convention (e.g., BEADS-123 in branch/PR title)”
  • Task: “Implement worker reporting (auto comment with build logs + commit hash)”
  • Task: “Migrate existing tasks.md files into Beads (script + manual review)”
  • Task: “Add CI policy: reject PRs without Beads task reference (optional)”
  • Task: “Documentation: contributor workflow update”

Notice how this is not just “use Beads”; it’s a system integration plan with enforcement and migration.

Integrating Beads into orchestration: practical patterns

Pattern 1: Treat Beads as the authoritative task store

Avoid duplicating task state inside the orchestrator beyond transient run context. Your orchestrator can cache, but the truth lives in Beads:

• Task descriptions, acceptance criteria, and status are read from Beads.
• Worker results are written to Beads.
• Planner decisions can be justified by task history in Beads.

This reduces drift and gives humans a single place to look.

Pattern 2: Use task IDs as the thread that ties everything together

Adopt a convention:

• Branch names: beads/BEADS-123-add-oauth-callback
• PR title includes BEADS-123
• Commit messages include BEADS-123
• Build artifacts reference BEADS-123

Then automate:

• When a PR opens, the orchestrator posts a comment on the corresponding task with the PR link.
• When CI passes, it updates the task or adds a status comment.
• When merged, it moves task status to Done (or In Review → Done).

This is the antidote to “random MD files”: everything points to a stable task record.

Pattern 3: Planner creates tasks; workers only update and comment

To prevent chaos, separate responsibilities:

• Planner agent is allowed to create_task and link_tasks.
• Worker agents are allowed to update_task (limited fields) and add_comment.

This avoids a scenario where every worker invents new tasks with inconsistent naming and labels. It also makes auditing easier: new tasks represent planning events, not execution noise.

Pattern 4: Use dependencies to manage parallelism safely

AI orchestration often over-parallelizes and causes merge conflicts or architectural inconsistency. Dependencies fix that:

• “Implement schema migration” must complete before “Deploy migration to prod”.
• “Decide token storage mechanism” must complete before “Implement OAuth callback”.

Even if Beads doesn’t natively support dependency edges, you can model them via links/labels and let the orchestrator interpret them.

Pattern 5: Capture “unknowns” explicitly with spike tasks

A planner should create tasks like:

• “Spike: evaluate Beads API/auth approach”
• “Spike: map Beads labels to team workflow”
• “Spike: test rate limits and pagination behavior”

Then mark them Done with findings in a comment. This turns ephemeral exploration into durable project knowledge, without burying it in chat logs or MD files.

Replacing scattered Markdown tasks: what actually improves

Markdown task files feel lightweight, but they become liabilities in multi-service systems:

• They’re not queryable (“show me all blocked tasks across repos”).
• They have no enforced structure.
• They age poorly and lose context.
• They can’t be updated reliably by agents without merge conflicts.

Beads improves three things immediately

1) Discoverability A single system to search beats grep across repositories. Agents can query tasks the same way humans do.

2) Consistency A task template with required fields (title, problem statement, acceptance criteria, status) makes tasks executable. The planner can rely on that structure.

3) Automation You can build workflows: auto-assign, auto-comment, auto-transition, and reporting dashboards. Markdown doesn’t do that without bolting on more tooling.

A subtle but important win: less “orchestration hallucination”

When an agent has no canonical task store, it tends to “invent” tasks or misinterpret stale notes. When it can read Beads and see what’s active, what’s blocked, and what’s done, it plans against reality.

Implementation approach: a step-by-step integration plan

Step 1: Define a task taxonomy (labels, priority, ownership)

Before you write code, decide how you’ll represent work. A practical starting point:

• Labels by domain: frontend, backend, infra, docs, security
• Labels by type: bug, feature, refactor, spike
• Priority: P0–P3
• Status lifecycle as described earlier

Write this down once (ironically, a small doc is fine) and encode it in the planner prompt and validators.

Step 2: Build the Beads skill wrapper with guardrails

Even if Beads offers an API, don’t expose it raw. Wrap it:

• Normalize fields (e.g., priority names, statuses).
• Enforce maximum lengths and required fields.
• Provide idempotency helpers (e.g., “create if not exists” based on fingerprinting).

A useful trick is to add a fingerprint in the task description or metadata, derived from (repo, goal_id, task_type, key_path). Then the planner can re-run without duplicating tasks.

Step 3: Add orchestration policies

Policies turn “task tracking” into “delivery system”:

• Only tasks in Ready are assignable.
• A task must have acceptance criteria to move to Ready.
• A task can’t move to Done unless it has at least one artifact link (PR, commit, build).
• If a task is Blocked, require a comment explaining why and what unblocks it.

These are small rules that prevent the system from becoming a dumping ground.

Step 4: Connect Beads tasks to code changes

Implement PR/commit hooks:

• Parse task ID from branch/PR title.
• Post PR link to the Beads task.
• On merge, transition status and summarize changes.

If you don’t want full automation at first, start with “comment only” and keep transitions manual. The key is establishing the linkage.

Step 5: Migrate existing Markdown tasks

Don’t try to perfectly preserve everything. The best migrations:

• Create a “Migration” epic in Beads.
• For each MD file, create tasks for items still relevant.
• Archive or delete the MD after migration to avoid split-brain.

A small script can help by parsing common checkbox formats and turning them into candidate tasks for human review.

A concrete example: Planner agent using the Beads skill

Imagine the user asks:

“Integrate Beads into our orchestration, add a planner agent that creates tasks, and stop using MD files.”

A planner flow could look like:

1. beads.search_tasks("Beads integration orchestration", status=["Proposed","Ready","In Progress"])
2. If none found:
   • beads.create_task("Adopt Beads for orchestration task management", ...) → returns BEADS-200
   • beads.create_task(..., parent_id="BEADS-200") for each subtask.
3. Link dependencies:
   • Skill call to link “Implement Beads skill wrapper” → blocks “Enable worker agents to fetch tasks”
4. Assign ownership (if Beads supports assignees) or leave unassigned and let orchestrator assign based on capability.

Worker agents then:

• Pull next Ready task,
• Do work,
• beads.add_comment(task_id, "Opened PR ..., CI run ..."),
• beads.update_task(task_id, status="In Review").

This becomes repeatable across all initiatives.

Operational considerations: auth, rate limits, and auditability

Authentication and permissions

Your orchestrator should authenticate to Beads using a service credential with scoped permissions. If Beads supports fine-grained roles, consider:

• Planner: create/update/link tasks
• Workers: update status + comment, not create
• Humans: full access as needed

Store secrets in your existing secret manager; do not embed in agent prompts or logs.

Rate limiting and pagination

Agent loops can be chatty. Your wrapper should:

• Use pagination properly,
• Cache common queries briefly,
• Prefer targeted lookups (get_task) over repeated searches.

Audit trail

One of the best reasons to centralize tasks is accountability. Make sure:

• Every task update includes “who/what” (agent name, run ID).
• Comments include artifacts (PR URL, CI URL, logs, benchmarks).
• The orchestrator logs tool calls in a secure audit sink.

This also helps diagnose “why did the planner create 30 tasks?” after the fact.

What changes for developers day-to-day?

If the integration is done well, developers feel three improvements:

1. Less cognitive load: no hunting for “where are the real tasks?”
2. Fewer interruptions: the planner agent pre-structures work with acceptance criteria, so reviews are easier.
3. Cleaner repositories: fewer stale TODO.md files, fewer conflicting lists across services.

A practical developer workflow becomes:

• Pick a Beads task,
• Create branch with task ID,
• Implement and open PR,
• Let automation update Beads,
• Move on.

Even teams that already use an external tracker benefit because Beads becomes closer to the code and the agent workflows.

Common failure modes (and how to avoid them)

“The planner creates too many tasks”

Fix by:

• enforcing task granularity (e.g., “1–2 days of work per task”),
• using parent/child structure,
• limiting the number of tasks per planning run unless requested.

“Tasks are vague and not testable”

Fix by:

• requiring acceptance criteria before Ready,
• adding a template that includes “How will we verify this?”

“Workers flip statuses incorrectly”

Fix by:

• limiting worker permissions,
• using orchestrator-driven transitions for key states like In Review and Done.

“Beads becomes another tool no one checks”

Fix by:

• making Beads the entry point for work assignment,
• integrating with PRs/CI so it stays current,
• building a simple dashboard view (e.g., Ready/Blocked/In Review).

A good end state: Beads as the living work graph of your system

When Beads is integrated into your orchestration with a planner agent and a disciplined skill interface, you end up with something stronger than “task tracking”:

• a living map of intended work,
• a reliable backlog that an agent can reason over,
• a consistent narrative linking goals → tasks → code → artifacts,
• a scalable alternative to scattered Markdown lists.

And the most important part: planning becomes a first-class, automatable part of development—without turning your repository into a graveyard of half-updated files.