dyngai/handoffkit / plugins/handoffkit/skills/handoffkit-scaffold
handoffkit-scaffold
VerifiedBuilt 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.
references/_src/runtime/corpus.go
View on GitHubpackage runtime
import (
"context"
"fmt"
"sort"
"sync"
"github.com/dyngai/handoffkit/sketch"
)
// MergeFunc reconciles a delta into the value stored for a key. existing is the
// current value and ok reports whether the key was already present.
//
// For concurrent Merges to be conflict-free it must behave as an ASSOCIATIVE,
// COMMUTATIVE, and IDEMPOTENT join over logical values: applying deltas in any
// grouping or arrival order, and replaying a delta, must converge to the same
// result. This is the contract that lets the Corpus be shared state without a
// per-agent lock dance (sketch/handoffkit.go: Corpus).
type MergeFunc func(existing any, ok bool, delta any) (merged any, err error)
// LastWriteWins replaces the stored value with the delta. It is order-dependent
// (NOT associative, commutative, and idempotent), so it is correct only for a
// key with a single writer (for example a per-handoff artifact key minted by
// one agent). Do not use it for a key multiple agents Merge concurrently; use a
// policy such as UnionStrings there.
func LastWriteWins(_ any, _ bool, delta any) (any, error) { return delta, nil }
// UnionStrings merges grow-only string sets (a G-Set): the result is the union
// of the existing set and the delta, sorted for a stable Get. It accepts a
// string or a []string on either side. It is associative, commutative, and
// idempotent, so concurrent Merges of the same key are conflict-free regardless
// of order, the canonical "shared knowledge, reconciled without locks" case.
func UnionStrings(existing any, ok bool, delta any) (any, error) {
set := make(map[string]struct{})
add := func(v any) error {
switch t := v.(type) {
case nil:
case string:
set[t] = struct{}{}
case []string:
for _, s := range t {
set[s] = struct{}{}
}
default:
return fmt.Errorf("handoffkit: UnionStrings needs string or []string, got %T", v)
}
return nil
}
if ok {
if err := add(existing); err != nil {
return nil, err
}
}
if err := add(delta); err != nil {
return nil, err
}
out := make([]string, 0, len(set))
for s := range set {
out = append(out, s)
}
sort.Strings(out)
return out, nil
}
// MemCorpus is an in-memory sketch.Corpus: a namespaced key/value store whose
// writes are reconciled by a MergeFunc. It is the repo's one deliberate use of
// shared state, the blackboard the design keeps for knowledge (knowledge stays
// put and is referenced, not channelled as prose). It is intentionally local and
// small: enough to make MemoryRef resolve and to make merge policy explicit and
// testable.
type MemCorpus struct {
mu sync.RWMutex
merge MergeFunc
data map[sketch.MemoryRef]any
}
// NewCorpus returns a MemCorpus using merge to reconcile writes. A nil merge
// defaults to LastWriteWins (single-writer keys).
func NewCorpus(merge MergeFunc) *MemCorpus {
if merge == nil {
merge = LastWriteWins
}
return &MemCorpus{merge: merge, data: make(map[sketch.MemoryRef]any)}
}
// cloneCorpusValue copies known mutable values before they cross the Corpus
// boundary. Unknown values keep their normal interface semantics.
func cloneCorpusValue(v any) any {
switch t := v.(type) {
case []byte:
return append([]byte(nil), t...)
case []string:
return append([]string(nil), t...)
case []sketch.Turn:
return append([]sketch.Turn(nil), t...)
case []sketch.MemoryRef:
return append([]sketch.MemoryRef(nil), t...)
case sketch.HandoffContext:
t.Thread = append([]sketch.Turn(nil), t.Thread...)
t.Refs = append([]sketch.MemoryRef(nil), t.Refs...)
return t
default:
return v
}
}
// Get returns the value stored at ref. ok is false if the ref was never written.
func (c *MemCorpus) Get(ctx context.Context, ref sketch.MemoryRef) (any, bool, error) {
if ctx == nil {
ctx = context.Background()
}
if err := ctx.Err(); err != nil {
return nil, false, err
}
c.mu.RLock()
defer c.mu.RUnlock()
v, ok := c.data[ref]
if !ok {
return nil, false, nil
}
return cloneCorpusValue(v), true, nil
}
// Merge reconciles delta into ref via the corpus MergeFunc. Concurrent Merges
// are serialized under the lock; the conflict-free property comes from the
// MergeFunc being associative, commutative, and idempotent, not from the lock
// (the lock only guards the map).
func (c *MemCorpus) Merge(ctx context.Context, ref sketch.MemoryRef, delta any) error {
if ctx == nil {
ctx = context.Background()
}
if err := ctx.Err(); err != nil {
return err
}
c.mu.Lock()
defer c.mu.Unlock()
existing, ok := c.data[ref]
merged, err := c.merge(cloneCorpusValue(existing), ok, cloneCorpusValue(delta))
if err != nil {
return err
}
c.data[ref] = cloneCorpusValue(merged)
return nil
}
var _ sketch.Corpus = (*MemCorpus)(nil)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |