Give each coding agent an explicit bead, dependency-aware ready work, an isolated checkout, and a workflow with the review gates your team already uses. That is enough structure to let agents work in parallel without making merge conflicts and chat handoffs the scheduling system.
Gas City writes the method down as a workflow and runs it on Beads. The coding agents can differ. The work contract does not.
Work through one concrete feature
Suppose the request is to add CSV export to a reporting page. The change touches the API, the web interface, tests, and documentation.
A useful workflow begins with a parent feature bead. Planning turns it into child beads with clear acceptance criteria:
- Implement the export endpoint.
- Add the download control to the reporting page.
- Test the integrated behavior.
- Update the user documentation.
- Review the resulting pull request.
Parent-child structure says these items belong to one feature. Blocking dependencies say when each may start. The test bead waits for the endpoint and interface work. Documentation can begin from the approved behavior, then wait for the public interface to settle. Review waits for every required result.
That difference is easy to miss. Hierarchy organizes the work; dependency edges control execution.
The agent work graph guide covers the relationship types in more detail.
Plan the graph before assigning agents
Planning is where most coordination mistakes become cheap enough to fix.
Each child bead should name the expected result, relevant project scope, and the evidence required to close it. Record decisions that another session will need. If implementation reveals unrelated work, create a new bead with a discovered-from relationship instead of silently expanding the claimed task.
Gas City workflows, technically called formulas, make this graph repeatable. A readable TOML definition declares steps and dependencies. Applying it materializes the steps as beads, after which the work can outlive both the file and the session that started it.
Use the formula guide for maintained syntax. The multi-agent engineering guide explains how to move an existing hand-coordinated method into a city and pack.
Let agents claim ready work
An agent should choose from work it can actually begin. bd ready computes that frontier by excluding items with open blockers. bd ready --claim --json can atomically claim the first matching item.
Atomic claims matter when several agents watch the same queue. One claim wins. The other agents see the updated assignment instead of beginning duplicate work.
Gas City routes materialized workflow steps to configured agents or pools. The orchestrator holds blocked steps, fans out independent ones, and advances the graph as agents close their beads. Beads owns the status and relationships underneath that routing.
The maintained Beads ready reference and coordination guide cover the claim behavior.
Isolate code, share the work graph
The API agent and interface agent should not edit one checkout.
Give each active implementation its own Git worktree and branch. The worktrees isolate code changes while pointing back to the same repository-level Beads workspace. With the default bd work-store provider, issue state lives in Dolt, separate from the Git branch, so agents in linked worktrees see the same claims and dependency graph.
That shared view is the point. Separate checkouts should not create separate accounts of the job.
Gas City registers a project as a rig and scopes configured agents and beads to it. Public-facing explanations can keep saying project or repo; the technical term becomes useful when one city operates across several codebases. The Beads worktree guide documents discovery and synchronization from linked worktrees.
For edits likely to collide during consolidation, Beads also provides a merge slot that serializes the conflict-prone operation. Use isolation for normal parallel work and exclusive access for the narrow section that truly needs it.
Make the handoff part of the work
When the endpoint agent finishes, it should close its bead with a useful reason and leave decisions or integration notes on the record. The interface agent does the same. A handoff written only in a chat transcript is invisible to a fresh session.
Testing unblocks after both implementation beads close. A test agent works from the combined branch or integration workspace defined by the team’s process, runs the required checks, and records the outcome. A failure opens or reopens concrete work rather than sending an unactionable message into a channel.
If an agent crashes, the claimed bead, notes, and blockers remain. The crash recovery guide explains how another session resumes from that state.
Keep the final decision human
The workflow should end at the outcome your team trusts.
For code delivery, that is usually a reviewed pull request ready for human review. The workflow can include agent review before the final gate, but an agent’s approval does not silently change the repository’s merge policy. Security, authentication, billing, and data migrations may need earlier human gates as well.
Imported packs define the factory’s agent roles and formula workflows. That is why a mixed-agent factory works: Claude Code, Codex, Gemini CLI, or another supported harness can fill a configured role without changing the Beads graph.
The mixed-agent guide covers that routing boundary. An AI software factory in practice shows the same coordination primitives inside the public factory the team runs across its repository fleet.
Build the smallest version
Write one plan-implement-review workflow. Give it two implementation beads that can truly run in parallel, one integration test bead blocked on both, and one human review gate.
Run it in a disposable repo first. Confirm that independent agents never share a checkout, blocked work stays out of the ready frontier, implementation notes reach the integration step, and the final gate receives the evidence it expects.
Once that works, add another workflow step only when a real failure demands it. Coordination gets better through fewer implicit assumptions, not a larger cast of agents.
Related articles
- Orchestrating multiple AI agents: Understand the system guarantees behind this repository pattern.
- Why coding agents need a work graph: Learn how hierarchy, blockers, provenance, and readiness differ.
- Use Claude Code, Codex, and Gemini together: Route workflow roles through different coding-agent harnesses.
- An AI software factory in practice: See these coordination primitives operating inside a public, source-visible factory.