handoffkit-scaffold
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, jo
SKILL.mdplugins/handoffkit/skills/handoffkit-scaffold/SKILL.md
GitHubScaffold 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
Determine the target module path. Read the project's
go.mod. If there is none, ask the user for a module path and rungo mod init <path>. The scaffolded runtime requires Go 1.21+. The full HandoffKit repo requires Go 1.22+ because of its OpenAI SDK dependency.Choose package destinations and protect existing code. Before copying, inspect the target paths you plan to use.
- Default destinations are
sketch/andruntime/. - If either path already exists and contains files, stop and summarize what
is there. Do not overwrite, delete, merge into, or
rm -rfthose directories implicitly. - Ask the user whether to overwrite/merge into those paths, or choose an
alternate namespace such as
internal/handoffkit/sketchandinternal/handoffkit/runtime. - If you choose alternate paths, keep the same relative shape (
sketchbesideruntime) and rewrite imports to that alternate sketch package.
- Default destinations are
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.gofiles. 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
LICENSEfile alongside the scaffolded HandoffKit code, or creating/updating the target project's third-party notices file with the HandoffKit name, source URLhttps://github.com/dyngai/handoffkit, MIT license, and full license text from that bundled rootLICENSEfile.
Rewrite the import path. In every copied file, including tests, replace the placeholder sketch import
github.com/dyngai/handoffkit/sketchwith the chosen target sketch import. For default destinations this is<module>/sketch; for alternate destinations it may be, for example,<module>/internal/handoffkit/sketch.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.
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 afterneedmessages arrive.runtime.NewQuorumAgent(addr, inbox, next, need, total, combine), fan-in quorum: emits after the firstneedoftotalmessages arrive.runtime.NewBudget(total), a selectable resource ceiling whoseDone()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;Stepreturns the messages to route next.
For the design pattern, the coordination shapes (pipeline / pool / broadcast /
join), and the honest tradeoffs, use the handoffkit skill.