Skip to content

docs: kontext dispatch in DESIGN, the README and the pm's skills - #58

Merged
OmarAlex24 merged 1 commit into
dispatch/watcherfrom
dispatch/docs
Nov 17, 2026
Merged

OmarAlex24 merged 1 commit into
dispatch/watcherfrom
dispatch/docs

Conversation

@OmarAlex24

@OmarAlex24 OmarAlex24 commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Top of the kontext dispatch stack: the docs and the pm's skills. It also holds the steps of the real-Boat test, which nothing in this stack has run.

What changed and why

  • DESIGN
    • a new §12.5, "One epic, one sandbox: kontext dispatch": the checks, the steps in order, the watcher, the state, the adapter, and what is not verified against Boat yet;
    • §1 now says kontext dispatches an epic to a sandbox but still does not decide what runs;
    • §12.1 says the same and points at §12.5;
    • a §10 row and an example [dispatch] table in §11.
  • README
    • "One epic, one sandbox" under "Orchestrating several agents": the commands, what the token, the start script and the watcher do, where the state lives, and the [dispatch] table;
    • a pointer from "With a kontext server";
    • "Development" says the dispatch tests use a fake boat and never reach Boat.
  • Skills
    • kontext-orchestrate: in an XL project with a signed plan, the pm launches each wave's epics with kontext dispatch (a new first row in the harness table), and an epic that is one small task gets no sandbox;
    • kontext-pm §10: launching a wave with sandboxes;
    • their new hashes are appended to templates/skill-versions.txt, as for every template change, so older installs are seen as older versions.

Departures from the brief

  • kontext-coordinator.md is unchanged: the prompt points at it and at kontext brief, and it already says what a coordinator in a sandbox needs (ask the pm, close the epic with evidence).

Not verified (no boat command that makes or drives a sandbox was run)

  • the JSON that the real boat new, boat info and boat prompt --json print (the adapter takes the ready event's id, setupStatus/setupError, and conversationId at the top or under data);
  • whether Boat clones the repo before or after the setup script runs (the script waits for the clone either way), and which user and HOME it runs as;
  • whether the -e variables reach the agent's session;
  • whether boat prompt returns 0 when a turn ends normally.

The real-Boat test (the owner's)

Against a local server through boat forward --reverse, never the deployed Worker. Use the stack's binary, not ~/.cargo/bin/kontext, with a kontext config of its own.

  1. Build the top of the stack: cargo build --release, and set kx=<target>/release/kontext. In every shell below: export KONTEXT_CONFIG_DIR=$(mktemp -d) (the same folder) so the real kontext config is never touched.
  2. The server: cd server && npm ci && node dev.mjs --port 8787 --persist <a folder>.
  3. A throwaway project on it: KONTEXT_ADMIN_SECRET=dev-admin-secret $kx init boattest --home <a folder> --server http://127.0.0.1:8787. In its project.toml: owners = ["<you>"], a [[repos]] with a scratch GitHub repo, and [dispatch] with environment = "<a Boat environment that can clone that repo>" (and hours = 1 for a short test). Then $kx --project boattest sync --include-config.
  4. A signed plan with one epic of two small tasks: charter --objective … and sign, goal add … and sign, epic add "Docs" --goal <G> --name docs, two task add … --epic docs --acceptance …, then scope summary --json and scope sign --hash <hash>.
  5. Check a refusal first: $kx --project boattest dispatch nosuch exits 2 with one line.
  6. $kx --project boattest dispatch docs. When it prints sandbox bx_… made, in a second shell: boat forward bx_… --reverse --local 8787 (the start script retries kontext clone for 10 minutes). Watch it print the start script done, the coordinator prompted and the watcher's pid.
  7. Check: boat info bx_… --json shows setupStatus done; inside the sandbox (boat ssh or boat exec) ~/.kontext-dispatch-token is gone, kontext --version is the pinned release, git status in the repo is clean, and kontext brief docs works; $kx --project boattest dispatch status shows the epic running and the watcher alive.
  8. Let the coordinator work. Expected: its tasks close in the ledger, it opens one PR stack in the scratch repo, the epic closes, and within a few seconds the watcher stops the sandbox (boat info shows it stopped, not deleted), revokes the token ($kx --project boattest token list), and dispatch status says closed.
  9. The other paths, each on a fresh epic: interrupt the coordinator with the epic open (it is resumed once with the same conversation, then stuck with a question to the pm under "Questions for pm" in $kx --project boattest --actor agent:pm --role pm resume); kill the watcher, run dispatch status (it says how to restart it), restart it with dispatch watch --detach and see it pick up; dispatch stop <epic>.
  10. Look for the token anywhere it must not be: boat events bx_…, the watcher's log and state.json under $KONTEXT_CONFIG_DIR/dispatch/boattest/: no kxt1..
  11. Clean up: boat stop anything left; the Boat sandboxes' data goes after 14 days.

Test plan

  • cargo fmt --check, cargo clippy --all-targets -- -D warnings and the full cargo test (42 suites, 497 tests, the template-version tests included) passed at this commit (fresh worktree and target dir, before the placeholder edit below; that edit only changed two example lines in README and DESIGN)
  • The new skill hashes are in templates/skill-versions.txt (the install test that requires it passes)
  • The README's sample output was compared by hand with the messages in src/dispatch/mod.rs (the ids are made up)

🤖 Generated with Claude Code

DESIGN gets §12.5 (the checks, the steps, the watcher, the state and the
adapter) and §1, §10, §11 and §12.1 now say kontext dispatches an epic to a
sandbox and what it still does not decide. The README says how to dispatch
and how the tests fake Boat. kontext-orchestrate and kontext-pm launch the
waves of an XL project with `kontext dispatch` and give small epics no
sandbox; their new hashes go in skill-versions.txt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@OmarAlex24
OmarAlex24 marked this pull request as ready for review November 17, 2026 14:30
@OmarAlex24
OmarAlex24 merged commit 27b7d92 into main Nov 17, 2026
1 check passed
@OmarAlex24 OmarAlex24 mentioned this pull request Nov 17, 2026
4 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant