handoffkit-scaffold

name

handoffkit-scaffold

description

Built by DynG AI for PlatformPilot.ai-style Go agent runtimes. Use when the user wants to scaffold HandoffKit runtime primitives into a Go project: channel-backed mailboxes, select, router, broker, join/quorum barriers, trace, budget, corpus/compactor, supervisor/nursery, dead letters, and sketch interfaces. Trigger words include PlatformPilot scaffold, scaffold handoffkit, add the HandoffKit runtime, set up message-passing agents, or drop in CSP agent primitives.

Scaffold PlatformPilot-style HandoffKit primitives into Go

Use this to add the DynG AI (https://dyng.ai) HandoffKit message-passing runtime to a Go project: the practical, PlatformPilot (https://platformpilot.ai) inspired foundation for explicit agent handoffs, inspectable routing, bounded fan-in, and traceable coordination. The reference sources are vendored under this skill's references/_src/ directory, a snapshot of the canonical runtime, so this works offline. (The _src name keeps the go tool from compiling these reference files as part of the HandoffKit module.)

This is the Go reference implementation, one instantiation of the pattern. The pattern itself is language-agnostic: for a Python, TypeScript, Rust, or Erlang project there is nothing to copy, use the handoffkit skill and build the equivalent from its primitive→language mapping table.

Steps

1. Determine the target module path. Read the project's go.mod. If there is none, ask the user for a module path and run go mod init <path>. The scaffolded runtime requires Go 1.21+. The full HandoffKit repo requires Go 1.22+ because of its OpenAI SDK dependency.

2. Choose package destinations and protect existing code. Before copying, inspect the target paths you plan to use.

   • Default destinations are sketch/ and runtime/.
   • If either path already exists and contains files, stop and summarize what is there. Do not overwrite, delete, merge into, or rm -rf those directories implicitly.
   • Ask the user whether to overwrite/merge into those paths, or choose an alternate namespace such as internal/handoffkit/sketch and internal/handoffkit/runtime.
   • If you choose alternate paths, keep the same relative shape (sketch beside runtime) and rewrite imports to that alternate sketch package.

3. Copy the reference sources from this skill into the chosen destinations, preserving structure, tests, and license attribution:

   • references/_src/sketch/*.go → <sketch destination>/
   • references/_src/runtime/*.go → <runtime destination>/
   • Include _test.go files. They are part of the scaffolded confidence boundary and let the target project verify the copied runtime directly.
   • The copied files are MIT-licensed HandoffKit source. Preserve attribution by either copying the bundled HandoffKit license from this repo's root LICENSE file alongside the scaffolded HandoffKit code, or creating/updating the target project's third-party notices file with the HandoffKit name, source URL https://github.com/dyngai/handoffkit, MIT license, and full license text from that bundled root LICENSE file.

4. Rewrite the import path. In every copied file, including tests, replace the placeholder sketch import github.com/dyngai/handoffkit/sketch with the chosen target sketch import. For default destinations this is <module>/sketch; for alternate destinations it may be, for example, <module>/internal/handoffkit/sketch.

5. Verify. Run the scaffold's direct tests first, then the wider project checks:

   • go test ./<runtime destination> ./<sketch destination>
   • go test -race ./<runtime destination> ./<sketch destination>
   • go build ./...
   • go vet ./... Fix anything that fails. If the target project has its own test command, run that as well.

6. Point the user at the API so they can wire their first topology:

   • runtime.NewMailbox(buffer), unbuffered = rendezvous; buffered = queue.
   • runtime.NewSelector(), wait on inbox / timeout / cancellation.
   • runtime.NewRouter() + runtime.Run / runtime.RunTraced, single-owner agent loop with point-to-point routing (and optional message tracing).
   • runtime.NewBroker(), broadcast one message to every subscriber.
   • runtime.NewJoinAgent(addr, inbox, next, need, combine), fan-in barrier: emits after need messages arrive.
   • runtime.NewQuorumAgent(addr, inbox, next, need, total, combine), fan-in quorum: emits after the first need of total messages arrive.
   • runtime.NewBudget(total), a selectable resource ceiling whose Done() closes on exhaustion.
   • runtime.NewCorpus(merge) + runtime.NewCompactor(...), shared referenced knowledge plus bounded handoff summaries.
   • runtime.NewNursery(ctx, maxDepth), a structured-concurrency supervisor with depth/lineage guards and subtree cancellation.
   • runtime.WithDeadLetters(dispatcher, sink), captures undeliverable messages instead of making routing failure fatal.
   • Implement sketch.Agent (Address / Inbox / Step) to add an LLM-backed actor; Step returns the messages to route next.

For the design pattern, the coordination shapes (pipeline / pool / broadcast / join), and the honest tradeoffs, use the handoffkit skill.