Coordinate a saved plan

Use bee plan to coordinate dependent steps among already registered sessions. Current Bee includes create, show, next, children, claim, update and comment. It does not launch agents, send assignments automatically or run tests.

Before you start

These examples are verified against released help/source, not executed against a live store. You need an initialized profile, reachable MongoDB, enabled collaboration, a supported live native session with a matching local binding, and a repository checkout. Reuse the profile/session selector from collaboration. A copied public session ID alone grants no access. Seeing help does not confirm that your profile can connect or authenticate. Commands may fail during startup before work is read or saved.

1 · Define the work

Save this as plan.json. Replace demo-team and example.com/team/catalog with the exact configured space and repository identity. Source locations/revisions are declared references; Bee does not fetch or verify their contents. IDs and scope are case-sensitive. Linked worktrees can have a different resolved scope; do not infer Plan access from a roster’s advertised repo name.

Read the actual scope before editing plan.json. The repository value comes from scope in stats; the space comes from configuration. Keep the session selector returned by join for all plan calls.

bee remember stats --json
bee config get collaboration.space

{
  "schemaVersion": 1,
  "revision": 1,
  "id": "catalog-change",
  "title": "Change catalog prices",
  "scope": {
    "space": "demo-team",
    "repository": "example.com/team/catalog"
  },
  "sources": [
    {
      "location": "docs/prices.md",
      "revision": "requirements-v1"
    }
  ],
  "steps": [
    {
      "id": "implement",
      "title": "Implement price change",
      "acceptanceCriteria": [
        {
          "id": "cents",
          "description": "Prices remain whole cents"
        }
      ]
    },
    {
      "id": "verify",
      "title": "Review tests",
      "dependencyIds": [
        "implement"
      ],
      "acceptanceCriteria": [
        {
          "id": "evidence",
          "description": "Review original test artifacts and runner exit"
        }
      ]
    }
  ]
}

2 · Create and inspect

Set CREATE_REQUEST_ID, CLAIM_REQUEST_ID and COMPLETE_REQUEST_ID to different fresh lowercase UUIDs before their first use. Reuse an operation’s exact ID and arguments only when retrying that operation. The shell variables below are examples for POSIX shells.

Generate the request IDs once in Bash/zsh (Python 3 required):

CREATE_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
CLAIM_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
COMPLETE_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"

PowerShell:

$CREATE_REQUEST_ID = [guid]::NewGuid().ToString()
$CLAIM_REQUEST_ID = [guid]::NewGuid().ToString()
$COMPLETE_REQUEST_ID = [guid]::NewGuid().ToString()

bee plan create --file plan.json --request-id "$CREATE_REQUEST_ID" --json
bee plan show catalog-change --json
bee plan next catalog-change --limit 1 --json

show returns the definition and current execution state. For a new untouched example, next proposes implement; it has no dependency. verify becomes ready only after its dependency is reported complete. This is an expected projection from the definition, not a captured live success transcript. next is advisory and reserves no work. It returns up to five steps; inspect hasMore and omission counts.

3 · Claim and report

Use the claim generation returned by claim. Save a single-line UTF-8 summary without leading/trailing whitespace or a newline as summary.txt, for example Implementation ready for review. The following update reports completion; it does not certify it:

bee plan claim catalog-change implement --revision 1 --lease-seconds 300 --request-id "$CLAIM_REQUEST_ID" --json

Before the lease expires, renew with the latest returned claim generation. This needs a new request ID; rereading a plan does not renew it. After renewal, use the returned generation in the final update too.

RENEW_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
bee plan update catalog-change implement --revision 1 --claim-generation <returned-generation> --state renew --lease-seconds 300 --request-id "$RENEW_REQUEST_ID" --json

PowerShell:

$RENEW_REQUEST_ID = [guid]::NewGuid().ToString()
bee plan update catalog-change implement --revision 1 --claim-generation <returned-generation> --state renew --lease-seconds 300 --request-id "$RENEW_REQUEST_ID" --json

Create the summary without a final newline before the completion command:

printf 'Implementation ready for review' > summary.txt

PowerShell:

[IO.File]::WriteAllText((Join-Path (Get-Location).Path 'summary.txt'), 'Implementation ready for review', [Text.UTF8Encoding]::new($false))

bee plan update catalog-change implement --revision 1 --claim-generation <returned-generation> --state reported_complete --summary-file summary.txt --request-id "$COMPLETE_REQUEST_ID" --json

--revision 1 is the immutable definition revision. --if-version N optionally also checks the current aggregate version. Requested claim leases are 30–300 seconds; the registered session lease can shorten the actual duration; reads and retries do not renew them. running/blocked retain the claim, failed/abandoned release it, and reported_complete releases it and enables dependents. renew explicitly extends a live claim. After expiry or rejoin, an old generation cannot complete newly claimed work.

Child plans and immediate dependencies

A child plan has immutable parentId, parentStepId and parentRevision in its definition. children lists immediate children of the selected parent, optionally under one step. It does not recursively list descendants, change the parent’s definition or mark the parent step complete. Follow nextAfter for another bounded page (1–5 rows); a copied cursor is only a pagination position.

bee plan children catalog-change --limit 5 --json
bee plan children catalog-change implement --limit 5 --json
bee plan children catalog-change --after "$NEXT_AFTER" --limit 5 --json

Create a child only with the actual parent ID, step ID and revision in the child’s JSON definition. Read the returned plan and child listing before assigning work. Collaboration describes the active session prerequisite.

Recover without duplicating work

Exit 2 means uninitialized, 3 not found, 4 invalid input/definition, 5 unavailable or an unknown outcome, and 8 a conflict such as a lost claim or blocked dependency. Other rejections can return 1. Inspect the error code as well as the process exit. For outcome_unknown, preserve the exact request ID and payload; a write may already have committed. For a known claim conflict, read current state and obtain valid ownership before a new mutation. Definitions are immutable; update changes execution state, not the plan text.

What completion does not prove

reported_complete is the owner’s report. Acceptance criteria are requirements, not proof that they passed. Current Bee includes diagnostic bee qa assess and explicit bee qa run: the latter executes the supplied check specification and can report verifiedCompletion=true for declared criteria, but its trust is in_process_only and the caller must review check quality and subjective intent. Keep compiler analysis, original runner output, source identity and independent review alongside Plan state. TRX summaries alone do not establish that every required test ran.

Collaboration lifecycle · Coding workflow · Command reference