Duet
Run a Duet. One manager, several workers.
A worker needs room to build. A manager needs enough distance to question the approach and check the result. Duet gives those responsibilities a place in your project.
Start with one worker and one small story, then add pairings when the first can return a result reliably.
Written guide · 8 to 10 min read
Follow along
- 1.
Choose the work and name the roles
Pick an existing story with a small, testable outcome. An empty-state improvement or a focused bug fix makes a useful first exercise. This guide takes about eight to ten minutes to read; implementing and reviewing the story will take its own time.
Open a manager session and a worker session in the appropriate project or worktree. The manager scopes the work, reviews the evidence, and keeps the project ledger: the stories, decisions, issues, and handovers in .story/. The worker plans, implements, tests, and reports findings for the manager to record.
Tell both sessions who holds each role, which story they may work on, and which actions are authorized. Confirm the actual client task identities and checkouts. A display name such as API worker helps you recognize a session, but does not identify it reliably enough for the pairing record.
Agree on shared resources early. If tests share a database, simulator, or limited memory, name the jobs that must run one at a time and what to do when one fails. These are project decisions, not resources Duet automatically allocates.
- 2.
Connect Storybloq and record the pairing
If Storybloq is not installed and connected, run the commands below. Setup installs the skill, registers MCP, and configures supported client hooks. It is a machine-level step, not something to repeat in every session.
Load the project with /story in Claude Code or $story in Codex. Ask the coordinating session to enter Duet with the worker you selected and read the current Duet procedure. These are instructions to your agent, not shell commands.
The manager creates or reads an arrangement containing the story or issue scope, one manager, and one worker. It records the agreed gates and what to do if the other side becomes unreachable. Each additional worker gets a separate pairing with the manager.
Run storybloq arrangement list from the project to inspect the records. Have the manager show you the selected arrangement, its participants, and its scope before continuing. Use storybloq arrangement --help and storybloq arrangement coordinate --help for CLI options. Your agent should follow the installed Duet procedure and the operation schemas exposed by its MCP tools.
$npm install -g @storybloq/storybloq@latest$storybloq setup --client all$storybloq arrangement list - 3.
Prove that a result can come back
Each session checks the tools it can actually call. Receiving a message does not prove it can send one. An arrangement records who is participating; it does not create a messaging channel.
Before assigning work, the manager sends a challenge identifying the project, both tasks, and the coordination session. Storybloq supplies a nonce, a fresh value that the worker must return. The manager observes that matching return before recording readiness. An accepted outgoing send or a local acknowledgment is not enough.
The worker can reply directly when it has a callable sender. Otherwise, the manager can collect its matching final output if the client supports that route. If neither route can be demonstrated, resolve the limitation before dispatching.
Completion handling differs by client. Claude Code uses a worker-turn-end notification when the installed harness provides one, or another demonstrated collection mechanism. In Codex Desktop, the manager uses bounded completion waits and retains its collection cursor while work is open. Do not assume that a successful message proves an idle session will wake later.
- 4.
Dispatch one clear assignment
Give the worker an assignment ID, scope, allowed actions, acceptance criteria, return route, and next review gate. Record unanswered questions and resource holds before they become things someone has to remember. Keep the same assignment ID in questions, progress reports, and results.
For an empty-calendar story, ask for a plan before code changes. Acceptance could require a clear message when no appointments are available, preservation of the selected date, and unchanged behavior when appointments exist. Ask for a failing test of the empty case and the relevant regression checks. Set plan review as the next gate.
Arm the client's completion backstop for every dispatch: the notification or wait that lets the manager collect the worker's next result. The worker ends each turn with a deliverable, a question, or the words “turn ending, continue needed” and the current scope.
The worker includes the assignment ID in its final output and uses the same report ID for direct-message and final-output copies of one result. The manager can then reconcile the copies without treating them as separate completed work.
- 5.
Review the plan, then the actual work
Have an independent reviewer check the plan before implementation. Use the project's configured review tools and record what the reviewer received, its findings, and the outcome. A manager acknowledgment and an independent review are separate pieces of evidence.
After the plan is approved, the worker demonstrates the relevant failing test, implements the change, and runs the agreed checks. An independent code review then examines the result. Requested changes mean fixing the work and reviewing the revised package.
The manager reads the actual diff and test output before accepting it. Check the base commit, the changed files, and any remaining caveats. Byte-review is our shorthand for inspecting that code and evidence rather than accepting a summary of them.
Where an arrangement uses gate acknowledgments, Storybloq can bind one to the plan's exact bytes or a staged Git tree and its parent commit. It also records whether independent-review evidence accompanies the acknowledgment. That makes the decision inspectable; it does not prove the change is correct.
For this first exercise, stop with the reviewed package ready for your inspection. Committing, pushing, merging, and deploying follow the owner's existing authorization. Pairing sessions does not grant those permissions.
- 6.
Keep enough of the record to resume
The manager records the outcome, unanswered questions, evidence locations, and next step. A worker's message is an input to the project record, not its replacement. Keep the durable decisions and evidence references in that record and in handovers too.
Tracked arrangements live under .story/arrangements/. Local coordination runtime lives at .story/duet-sessions/<arrangementId>/state.json. The arrangement keeps a checkpoint for recovering assignments and obligations; client collection cursors remain local. These paths describe the records, not files you need to create by hand.
Before an interruption or a large next step, ask both sessions to name what they owe and what they are waiting for. Put those obligations in the handover. Follow the context-pressure signals your client provides instead of assuming every installation measures them in the same way.
On return, the manager reads the record and collects outstanding results before dispatching new work. Missing or corrupt runtime requires the documented recovery procedure: reconcile the checkpoint with task history and the handover, then restore the return route. It does not mean nothing is in flight.
- 7.
Practice one recovery, then add a worker
Pause after a reviewed result and resume from the written record. The manager should be able to identify the worker, assignment, last accepted result, and next gate without reconstructing them from memory.
If the return route is stale, verify the task identity and demonstrate a supported route again. If a failure is called pre-existing, reproduce it on the agreed base commit in a separate checkout. An earlier commit on the worker's own branch may be the wrong comparison.
A worker owes a message after a stop longer than 30 minutes. While active, the manager asks for status after 60 minutes without meaningful worker activity. These are working rules, not an unattended watchdog guarantee. Record resource holds and retry decisions so the next session does not repeat the same expensive failure.
Once one pairing can complete and recover cleanly, add a second worker with its own arrangement and scope. The manager coordinates dependencies and reviews what comes back. More workers help when the assignments can move independently and each result still gets attention.