Beads and WikiTicket Are Not Competitors. They Answer Different Questions.

WikiTicket is the team's record and Beads is the execution graph; they stay distinct, with one human gate between a ready ticket and the beads beneath it.

Rick Hightower

Cover image for “Beads and WikiTicket Are Not Competitors. They Answer Different Questions.” by Rick Hightower

WikiTicket keeps the team's record. Beads keeps the agent's working graph. One human gate sits between them, and every fact has one owner.

Two trackers in one repository feel like a turf war, and most teams pick one and ask it to do both jobs. The result is either an audit trail full of forty-minute tasks, or a swarm that cannot show who approved the work.

In this article: Beads and WikiTicket both live in Git and both track dependencies. You will see which reader each one serves, why ready means two different things, and when discovered work stays a bead or becomes a new ticket.

Two git-native trackers show up in an AI software factory. Both store work in the repository and both track dependencies. They are not competitors.

WikiTicket answers the team: what did we agree to build, who said it was ready, what landed, and why? The reader is a person, or an agent acting for the team, and the record has to survive an audit.

Beads answers execution: given approved work, which small step is claimable right now? The readers are planner and worker agents. The record has to be fine-grained, safe for parallel claims, and free to decay.

A factory needs both, and neither may do the other's job.

What each tool is

Beads (the bd command) is a dependency-aware issue graph for coding agents, created by Steve Yegge in October 2025 and now under gastownhall. It runs on Dolt, Git-style SQL, in a versioned plane (issues, edges, comments, synced) and a clone-local plane (leases, heartbeats, events, never pushed). Hard edges, blocks and parent-child, change what is ready. Soft edges, discovered-from, validates, and supersedes, do not. A precomputed blocked flag lets SQL, not an LLM, decide the frontier. Claims are atomic, leases last five minutes, and crashed workers return their beads. Closed work decays after 30 days. bd prime restores the frontier and standing facts at session start. Version 1.3.4 is the stable baseline.

WikiTicket SDD is a git-native work log. Plans become append-only events, a fold produces current state, and plans and ADRs freeze once accepted. Each ticket links to the plan that produced it and the pull request it landed in. The log publishes to the team's tracker and wiki. WikiTicket calls this fishbowled AI development: the work stays visible.

WikiTicket's README compares the two, and the comparison is fair.

Table: , Beads, WikiTicket SDD. Rows: Built for; Grain; Key query; Definition of ready; Frozen plans and ADRs; Provenance and traceability; Publishes to tracker and wiki; Old work.

The comparison sets the two tools side by side on eight points. The first column names the point of comparison. The Beads column and the WikiTicket SDD column say how each tool handles it.

  • Built for: Beads serves planners and worker agents executing a breakdown. WikiTicket SDD serves the team, and agents acting for it.
  • Grain: Beads is fine-grained, with work packages of 15 to 60 minutes and one reviewable commit each. WikiTicket SDD is coarse, with plans, epics, tickets, pull requests, and releases.
  • Key query: Beads answers "what is claimable right now?" WikiTicket SDD answers "what did we agree, who approved it, and what landed?"
  • Definition of ready: Beads has no field for it, so teams add one by convention with a frozen draft, a gatekeeper, and a human gate. In WikiTicket SDD, ready is a recorded decision: the ticket reviewer, then a named person.
  • Frozen plans and ADRs: Beads has supersedes edges, but no frozen plan of record. WikiTicket SDD writes plans and ADRs once, and supersedes them rather than editing them.
  • Provenance and traceability: Beads traces within its own graph, through discovered-from and validates edges. WikiTicket SDD traces plan to ticket to pull request to release, with citations at a commit.
  • Publishes to tracker and wiki: Beads does not, because it is local-first by design. WikiTicket SDD does, to GitHub today, with guides for Jira, Azure DevOps, and others.
  • Old work: Beads applies semantic decay after 30 days. WikiTicket SDD keeps old work, superseded rather than deleted.

WikiTicket answers the team's questions. Beads answers which small step a worker can claim, and what it may later forget.

Beads has no definition of ready, and it is built to forget.

WikiTicket above, Beads below

Plan mode, Superpowers, GSD, and Spec Kit each emit a task list only the agent can see. WikiTicket's hooks turn those plans into shared tickets, roadmaps, design documents, release notes, and pull-request descriptions. Git is the statement of truth for the human view and the internal view. Beads is the internal view: the breakdown. A planner writes the graph, a gatekeeper checks it, and workers claim one bead at a time, between the ready ticket above and the pull request after.

Keep the picture vertical. WikiTicket above, Beads below, one human gate between.

WikiTicket above, Beads below, one human gate between: the ready ticket, a person's recorded decision, the claimable graph, then a pull request back to WikiTicket.

  1. One owner for each fact. WikiTicket owns scope, the ready decision, status, and links to plans and pull requests. Beads owns packages, edges, and claims. Neither writes the other's facts. One local owner per external key, which WikiTicket already enforces.
  2. The graph starts from a ready ticket, never a vague request. Each package carries a spec reference, design, acceptance criteria, and an estimate. One transaction imports the whole graph, so a half-written plan never exists.
  3. Ready is a human decision, recorded once. The root epic is born frozen. A gatekeeper checks cycles and orphans, lints every package for acceptance criteria and a spec reference, flags estimates over ninety minutes, and checks for duplicates. A person resolves the gate. The decision is an event on the WikiTicket ticket. Only then does the first layer hit the ready frontier.
  4. Link by ID, both ways. The root epic carries the WikiTicket ULID. Validates edges tie tests to the requirements they prove. The pull request carries both IDs.
  5. Status flows one way. Closing every bead produces a pull request. It does not close the ticket. The ticket closes when a person merges in Review, and the event is written in WikiTicket, not in Beads.
  6. Close out before decay. Before the 30-day summaries, write what was built, discovered, and handed back onto the ticket, and send anything reusable to the second brain. Then Beads may forget.

Where each tool shows up

Table: Stage, WikiTicket, Beads. Rows: Shape; Plan; Dispatch; Schedule; Build; Review; Release; Respond; Maintain; Improve.

Each of the ten stages uses the two tools differently. The Stage column names the stage. The WikiTicket column says what WikiTicket records there. The Beads column says what Beads does there, or that it is not used.

  • Shape: WikiTicket records the agreed need, frozen once signed off. Beads is not used.
  • Plan: WikiTicket holds tickets, reviewer comments, and the ready decision. Beads is not used, because the ready ticket is the contract.
  • Dispatch: WikiTicket records which tickets start, and the budget. Beads is not used for team priority.
  • Schedule: WikiTicket records the gate resolution on the ticket. Beads holds the breakdown, the gatekeeper, and the frontier inside an admitted epic.
  • Build: WikiTicket holds the ticket and the pull-request edge. Beads handles atomic claims, leases, one bead per commit, and discovered work.
  • Review: WikiTicket holds the acceptance criteria. Beads holds validates edges from each test to its requirement.
  • Release: WikiTicket holds the release edge and traceability. In Beads, gate beads wait on a merge, CI, or a timer.
  • Respond: WikiTicket holds the refinement ticket linked to the incident. Beads can hold optional investigation steps.
  • Maintain: WikiTicket holds the migration campaign and its tickets. Beads holds one bead per edit site, claimed in parallel.
  • Improve: WikiTicket supplies ticket history and outcomes. Beads supplies discovered-from counts, reclaimed leases, and over-decomposed plans.

Dispatch is the easy mix-up. WikiTicket's ready means a person approved the ticket. The Beads frontier means a package has no open hard blockers. A bd ready across the whole backlog lets agents choose the team's priority. They must not. Dispatch admits the ticket and the budget. The frontier applies only inside that epic.

Schedule and Maintain are where Beads pays off. Packages run 15 to 60 minutes, small enough to review in about ten. A migration is one WikiTicket and hundreds of ordered edit sites, claimed in parallel. The ticket hears about the batch when it is ready for review.

Discovered work is the handoff

Discovered-from files a find without blocking, and the worker stays on task. Extra beads can still stretch a two-hour ticket into two days while the WikiTicket text stays put.

Beads documents three paths. A factory with WikiTicket adds a fourth.

Four paths for discovered work: file it, block on it, supersede a later package, or open a WikiTicket and add no bead.

  1. It does not block. File a discovered-from bead and keep going.
  2. It truly blocks. Add a blocks edge, unclaim, and the new bead becomes ready.
  3. It invalidates a later package. The planner supersedes that package and keeps the audit trail.
  4. It is outside the ticket, or nobody is sure. Add no bead. Open a proposed WikiTicket linked to the run, and send it through the ticket reviewer. If the current ticket cannot finish, stop and hand the question to the engineer, the same way the build loop stops at its limit.

The agent may propose a side. A person waives scope. A high discovered-from count means the ticket was probably not ready, which is what Improve should mine.

One export ticket, both tools

The export ticket is ready in WikiTicket, and Dispatch has admitted it. The planner reads the acceptance criteria and the tenant-isolation ADR, then imports one transaction: query layer, CSV writer, the earlier access check, a validates edge on each test, and large-workspace validation. Query blocks writer; writer blocks tests. The root epic carries the ULID and is born frozen.

The export ticket stays in WikiTicket. The gatekeeper and the engineering lead clear one human gate. Workers claim beads only after that event.

The gatekeeper finds no cycles or orphans. It flags the three-hour package, over the ninety-minute limit. The planner splits it, the gatekeeper passes, and the engineering lead's approval lands on the ticket before anyone claims. Two workers use separate worktrees. A blocking time-zone bug becomes a bead, a blocks edge, and an unclaim. Noisy logging waits. A background job and shared-client changes are out of scope, so the worker opens "Background export job for large workspaces," linked to the run, and adds no bead. The owner narrows the ticket. The planner supersedes the extra package with one that tests the limit. The new ticket goes through the ticket reviewer. Close-out writes the bug, the waiting bead, and the new ticket; the pull request carries both IDs. A month later Beads decays the packages. WikiTicket keeps the record. The second brain keeps the fix.

Caveats, and how to start

This is a pattern, not a shipped integration. WikiTicket ships tracker and wiki guides, plus composition guides for Superpowers, GSD, Spec Kit, and OpenSpec. It does not ship a Beads adapter. Skills and hooks enforce the bridge.

Date what you read. Three storage eras: JSONL in Git, with a SQLite cache and a sync daemon, in late 2025; a mandatory Dolt server from February 2026; embedded Dolt as the default again from April. Most tutorials still describe the first era. On 1.3.4, a dry-run import misses cycles declared inline, swarm validation checks only an epic's direct children, a custom done status does not unblock dependents unless you map it, and compaction corrupts history on clones that pulled migration 62. Pin a version, recheck cycles after every import, and keep the bridge thin.

Beads storage eras from JSONL in late 2025, through a mandatory Dolt server, back to embedded Dolt, with 1.3.4 as the baseline to pin.

Four failure modes show up in practice. One ready call can return hundreds of kilobytes. Micro-beads waste spin-up and test time. Reclaim zombie claims on a timer at twice the lease length. Use the explicit blocked-by form so step one is not blocked on step two.

You may not need both. One person and one agent can live on Beads. A team that must show the work to product, review, and audit can live on WikiTicket, with plans captured as tickets. Add Beads for large features, parallel agents, or big migration batches.

Start with Maintain. One ticket, many beads, one close-out skill: a frozen root epic carrying the ticket ID, the gate recorded on the ticket, out-of-scope finds turned into proposed tickets, and a close-out written before decay. If discovered-from counts and reclaimed leases stay low, extend the pattern to Schedule and Build.

Further reading

Do this today

  • Write which facts WikiTicket owns and which Beads owns. A fact with two writers needs one owner before the next run.
  • Do not let bd ready choose from the whole backlog. Admit a ticket, then claim beads inside it.
  • Record one human gate on the WikiTicket ticket before any bead is claimable.
  • Send out-of-scope discoveries to a proposed WikiTicket. Do not hide them as beads.
  • If you add Beads, start with one Maintain batch and a close-out written before the 30-day decay.

Give every fact one owner

Asked to do both jobs, Beads forgets a decision an auditor still needs, and WikiTicket fills up with steps only a worker needed this afternoon. Keep the record above, the graph below, and a person between them. Link by ID, let status flow from a merged pull request back into WikiTicket, and close out before decay.

Do your agents keep their own task lists today? Where do those lists go when the run ends?


This is Part 16 of "AI Software Factory Series," a 17-part guide to building an AI software factory with human gates.