​

Nine Concepts Overview

Last verified against code: 2026-03-01

​

Summary

​

The Primitive Test

1. Atomicity — can it be decomposed into existing primitives? If yes, it’s derived, not primitive.
2. Bitter Lesson — does it become MORE useful as models improve? If it becomes less useful, it fails.
3. ZFC — does Go handle transport only, with no judgment calls? If Go makes decisions, it’s a violation.

​

Layer 0-1: Primitives

​

1. Agent Protocol

• Interface: runtime.Provider with naming and startup hints from internal/agent/
• Implementations: tmux (production), subprocess (remote), k8s (Kubernetes), Fake (test)
• Key insight: The SDK manages agent lifecycle. The prompt defines agent behavior. These concerns never cross.

​

2. Task Store (Beads)

• Interface: beads.Store with Create, Get, Update, Close, List, Ready, Children, ListByLabel, SetMetadata, MolCook
• Implementations: BdStore (production, Dolt-backed), FileStore, MemStore, exec Store
• Key insight: Beads is the universal persistence substrate. All domain state flows through a single interface.

​

3. Event Bus

• Interface: events.Provider with Record, List, LatestSeq, Watch, Close
• Storage: .gc/events.jsonl (JSONL format)
• Key insight: Events are immutable. Seq is monotonically increasing. Watch() provides reactive notification without polling.

​

4. Config

• Entry point: config.Load() / config.LoadWithIncludes()
• Key types: City, Agent, Rig, ProviderSpec, Pack
• Key insight: Config IS the feature flag. An empty city.toml gives Level 0-1. Adding sections activates capabilities. No feature flags, no capability flags — the config presence is sufficient.

​

5. Prompt Templates

• Entry point: renderPrompt() in cmd/gc/prompt.go
• Template data: PromptContext with city, agent, rig, git metadata
• Key insight: All role behavior is user-supplied configuration. The SDK contains zero hardcoded role names.

​

Layer 2-4: Derived Mechanisms

​

6. Messaging

• Mail derivation: beads.Store.Create(Bead{Type:"message"}) → message is a bead. Inbox = query open message beads by assignee. Archive = close the bead.
• Nudge derivation: runtime.Provider.Nudge(text) → text typed into the agent’s session. Fire-and-forget.
• Proof: Mail uses only Bead Store (primitive 2). Nudge uses only Agent Protocol (primitive 1). No new infrastructure.

​

7. Formulas & Molecules

• Formula derivation: Config (primitive 4) resolves formula layers and active files.
• Molecule derivation: Bead Store (primitive 2) holds the root bead and any provider-created step beads.
• Wisp derivation: Molecule + TTL + garbage collection.
• Order derivation: Formula + Event Bus (primitive 3) gate evaluation + Config (primitive 4) scheduling.
• Proof: Uses Config, Bead Store, and Event Bus. No new infrastructure.

​

8. Dispatch (Sling)

• Derivation: Agent Protocol (find/spawn) + Config (select formula)
  • Bead Store (create molecule, convoy) + Agent Protocol (nudge) + Event Bus (log event).
• Proof: Pure composition of primitives 1-4. No new infrastructure.

​

9. Health Patrol

• Derivation: Agent Protocol (primitive 1) for liveness. Config (primitive 4) for thresholds and backoff parameters. Event Bus (primitive 3) for stall publication.
• Proof: Uses Agent Protocol, Config, and Event Bus. The controller drives all operations — no user-configured agent role is required.

​

Layering Invariants

1. No upward dependencies. Layer N never imports Layer N+1.
2. Beads is the universal persistence substrate for domain state.
3. Event Bus is the universal observation substrate.
4. Config is the universal activation mechanism.
5. Side effects (I/O, process spawning) are confined to Layer 0.
6. The controller drives all SDK infrastructure operations. No SDK mechanism may require a specific user-configured agent role.

​

Progressive Capability Model

​

See Also

• Glossary — authoritative definitions of all terms used across the nine concepts
• Primitive Test — the three necessary conditions for adding a new primitive
• CLAUDE.md — project-level design principles and code conventions