Agent Playbook

Agent Playbook is AgentKube's practical repository for portable Agent Operational Contracts, agent-design practices, and local authoring tools.

Its own contribution is not another coding harness. It makes the behavioral shape of an agent explicit before a runtime is chosen: what context is loaded, which boundaries apply to tools, how work loops and stops, how task dependencies are represented, and which evidence survives a handoff.

The Agulater Model

Agulater is the repository's authoring and audit tool. It produces a compact .agents/ kit whose top-level agulater.json is an AgentOperationalContract:

agulater.json
  -> context contract     what is loaded, when, and what is compacted
  -> harness contract     host boundary, tool mode, checkpoints
  -> loop contract        orient, plan, act, verify, stop or handoff
  -> graph contract       task and context dependencies
  -> capability contract  progressive skills
  -> evidence contract    evaluation and handoff artifacts

The contract closes the references between those files and declares core invariants. bun run audit verifies that closure locally. This is the part Agent Playbook owns: a portable, inspectable representation of agent operating behavior, independent of any one harness.

Start Here

• Agent Operational Contract explains the model and its invariants.
• Practices explains the underlying patterns and tradeoffs.
• Examples contains a complete generated research agent.
• Templates contains small pieces for manual adoption.
• Tools generates and audits an editable .agents/ kit.

Fast Path

Generate a supervised coding-agent kit:

bun run agulater -- --name "Repository Partner" --domain "TypeScript services" --profile coding --output workspace/repository-partner
bun run audit -- --path workspace/repository-partner

The result has a host-visible bootstrap and a closed portable contract:

AGENTS.md                   # root bootstrap for compatible harnesses
.agents/agulater.json       # Agent Operational Contract
.agents/AGENTS.md           # portable operating instructions
.agents/harness.json        # context, tool, loop, and checkpoint policy
.agents/graphs/*.json       # task and context dependency graphs
.agents/skills/*/SKILL.md   # progressive, on-demand capabilities
.agents/context/*.md        # durable, working, and handoff context layers

Run bun run studio for a local browser-based authoring surface when a form, file preview, and folder export are more convenient than the CLI.

Dogfooding

This repository is itself an Agulater kit. Its root AGENTS.md and .agents/ directory were created with the safe --adopt mode, then tailored to this project. The package test command validates both the TypeScript implementation and the repository's own contract:

bun run test

When changing generated structure, keep the generator, this root kit, the research example, audit, and practice documentation in sync. A passing contract audit is evidence that the representation remains closed; it is not evidence of runtime execution.

External References

Pi is one useful external reference for layered context, progressive skills, compaction, session branching, and lifecycle hooks. It is not the target implementation or semantic authority for this repository. See Reference Boundaries for the deliberate separation between source practices and the Agulater contract model.

Scope Boundary

Agent Playbook describes and generates agent configuration. It does not grant tools, execute tasks, call models, create hidden memory, or replace a coding harness. A host runtime remains responsible for actual permissions, execution, trust decisions, and session persistence.

The generated contract is neither an APS artifact nor a runtime configuration format. It is a standalone playbook representation that adapters may map to a specific runtime later.

Design Principles

1. A contract, not an oversized prompt, is the center of the agent definition.
2. Context is layered and loaded on demand; stale transcript is not memory.
3. Host authority stays external to the agent contract.
4. Every action path reaches verification or an explicit stop state.
5. Handoff and evaluation are evidence, not invisible conversation state.
6. External systems inspire patterns; they do not determine our representation.