The workspace
is the product.
Models are rented. Harnesses are swappable. What compounds is the place they work in: its instructions, memory, procedures, structure, and the colleagues beside them.
Seven acts · about forty-five minutes · press → to begin, G for the guide
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
This deck argues one thing: the quality of agent work is mostly decided outside the model. It is decided by the workspace the agent runs in: what it can read, what it can run, what it must not do, and what it leaves behind for the next session.
How to read this guide
Narration mode follows the deck. Each scene has a short explanation, the steps to build that piece yourself, a prompt you can paste into Claude Code or Codex, the skills that do the work, and references. Paragraphs marked with a beat light up as the diagram advances.
Start here. This opening scene names the through-line: a workspace is the durable operating context around a model, not a replacement for judgment or verification.
- Use → to step, G to toggle this guide, L for the scene ledger.
- Every prompt has a copy button. They assume a git repository you are allowed to change.
- Paths like
AGENTS.mdare relative to the root of a workspace repository built this way. Skill paths such asskills/knowledge/kgare relative to the skills repository (cloned atskills/in this workspace).
Set it up
- Start in a repository you are allowed to inspect.
- Read its local instructions before proposing a change.
- Keep a path and command receipt for every factual claim.
Prompt
Read this repository's AGENTS.md or CLAUDE.md, then give me a one-screen map of what an agent can read, run, change and leave behind. Cite every item by path. Do not change files or run destructive commands.Skills
- checkit
skills/research/checkit, verify sources before they count - dogfood
skills/governance/dogfood, exercise a change and keep a receipt
References
- Effective context engineering for AI agents (Anthropic)
- Claude Code best practices (Anthropic)
Give the agent a filesystem and a shell.
A model guesses when it can't look. A workspace lets it look, run, and write down what it found.
Explicit. Every input is a file you can open, diff and cite.
Open. Bash runs whatever the harness allows: search, tests, scripts.
Durable. What it learns is written back, so the next run starts ahead.
Structure and philosophy decide how it works there. That is harness engineering.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
A language model fills gaps with plausible text. Give it a filesystem and a shell and most gaps become lookups: it can open the file, run the test, grep the history, and write down what it found.
What you're seeing
Chat only. Questions go in, answers come out. Some answers wander off the line and dissolve: claims nothing could check.
Filesystem and shell. The same agent reads from a workspace tree, runs commands in a terminal and writes a note back (gold). Answers leave with citations.
Set it up
- Run the agent inside a repository, not in a chat window: Claude Code, Codex CLI or any harness with file and shell tools.
- Put the context it needs in files it can find: an
AGENTS.mdat the root, docs next to the code they describe. - Allow read-only commands broadly (
rg,git log, tests) and gate destructive ones (see “Hooks turn recall into a reflex”). - Ask for citations: every claim should name the file or command output it came from.
Prompt
Before answering, look. Search this repository with rg for the terms in my question, open the files that matter, and run any command that would confirm the answer. Cite each claim as path:line or as the command you ran. If something cannot be checked, say so instead of guessing. Write anything worth keeping to notes/FINDINGS.md.Skills
- checkit
skills/research/checkit, verify sources before they count - dogfood
skills/governance/dogfood, exercise the change and keep a receipt
References
Seven questions. One system.
Each layer answers one question an agent asks before it can do useful work.
Workspaces
Where does it live? Primer, policy, record and sandbox.
Context
What reaches the window, and how hooks make recall a reflex.
Second brain
How the graph is structured, read and grown.
Skills
How we do this kind of work, loaded on demand.
Structure
Which bytes it may touch, and where they go.
Fleets
Who else is here, and who checks whom.
Leadership
What all of this asks of people.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Seven parts, each answering one question an agent implicitly asks before it can do useful work.
The map. The tiles are a reading order: establish the place, compose context, make knowledge readable, package procedures, isolate work, govern the fleet, then decide where human attention belongs.
- Workspaces: where does the agent live?
- Context: what reaches its window, and when?
- Second brain: what does the place know, and how is it read and grown?
- Skills: how is this kind of work done here?
- Structure: which bytes may it touch?
- Fleets: who else is working, and who checks whom?
- Leadership: what does this ask of people?
The thread under the tiles is the argument: these are one system. A skill without the graph is guesswork; a graph without hooks is never read; a fleet without structure overwrites itself.
Set it up
- Choose one small repository and one bounded task.
- Map its instructions, active records, skills and checks before adding automation.
- Improve one layer at a time and keep the evidence with the change.
Prompt
Assess this repository against seven layers: workspace, context, knowledge, skills, structure, fleet and leadership. For each layer, cite the evidence you found, name one missing or weak mechanism, and recommend the smallest safe next step. Do not edit files.Skills
- checkit
skills/research/checkit, establish evidence before recommendations - audit-harness-usage
skills/tooling/audit-harness-usage, measure token use and cost across harness traces
References
AGENTS.md, workspace routes and constraintsdocs/references/agent-operating-protocols.md, the operating primitives
Workspaces
Where does the agent live?
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Act I establishes the place itself: what persists, which layers agents read, what stays swappable, and where data and records belong.
Act scenes
- A folder is not a workspace
- Six layers an agent reads before it writes
- Sandbox, harness, wire
- Medallion layers in the filesystem
- Worked example: a review system
Read next
Continue to A folder is not a workspace to distinguish a task directory from a place that retains governed context.
A folder is not a workspace.
The difference is what survives the session.
A working directory and a toolset for one agent on one task.
Useful. But context evaporates when the session ends, and the next agent starts cold.
A governed place that many agents work through.
Instructions, policy, memory, skills and a record outlive every session, so each run leaves the place a little smarter.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
An agent workspace is a folder and a toolset for one agent on one task. An agentic workspace is a governed place many agents work through, where instructions, policy, memory, skills and a record outlive every session.
What you're seeing
Agent workspace. One agent docks at a folder, builds context, and loses it when the session ends. The retained counter stays at zero.
Agentic workspace. Agents dock into rings (primer, policy, skills, memory, record). Each leaves a deposit in memory and a tick in the record. Retained grows with sessions.
Set it up
- Make one repository the place: it holds instructions, policy, knowledge, skills and the session record.
- Decide what every session must leave behind: a session log, a decision, a note with sources.
- Make leaving it automatic (a Stop hook, “Hooks turn recall into a reflex”), not a matter of remembering.
Prompt
Turn this repository into an agentic workspace. Propose (do not write yet) the minimum layout: an AGENTS.md primer, a policy file for hard gates, a folder for knowledge entries with front matter, a skills folder, and a docs/conversations folder for session records. For each, give its path, its one job, and what writes to it. Keep it to one screen.Skills
- handoff
skills/orchestration/handoff, write a useful session handoff - dogfood
skills/governance/dogfood, exercise a change and keep a receipt
References
AGENTS.md, workspace primerdocs/conversations/Conversations.md, session record index
Six layers an agent reads before it writes.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Six layers, read top-down before the agent writes anything, written bottom-up as work happens.
Read path. The first three layers constrain and route the work before tools run: primer, policy and on-demand procedures.
Write path. Knowledge, the work record and the product surface collect evidence after the agent has acted.
The layers
- Primer
AGENTS.md≡CLAUDE.md: philosophy, hard boundaries and read routes. Route to protocols instead of inlining them, so it stays short enough to be read every time. - Policy
.control/policy.yaml: gates as data that hooks and CI enforce. - Skills
skills/<category>/<name>/SKILL.mdin the skills repository: procedures loaded on demand. - Knowledge
research/entities/plus a compileddocs/knowledge-index.md. - Record
docs/conversations/and.control/initiatives/: what happened and what is in flight. - Work: product repositories, worktrees and sandboxes, where bytes change.
Set it up
- Keep
AGENTS.mdcanonical and copy it toCLAUDE.md(cp AGENTS.md CLAUDE.md), so every harness reads the same primer. - Write the primer as a routing table: "when X, read Y". Measure it: if it is longer than a screen or two, move detail into the routed files.
Prompt
Draft AGENTS.md for this repository as a routing primer, under 300 lines. Sections: philosophy (4 rules), non-negotiable boundaries, a "when / read" table pointing at real files in this repo, and completion checks (the exact commands to run before calling work done). Link to protocols; do not inline them. Then show me the table of files it routes to and whether each exists.Skills
- role-x
skills/orchestration/role-x, route work to the right local context - kg
skills/knowledge/kg, load graph context by topic
References
Sandbox, harness, wire.
Three layers, three different answers. Buy the box, swap the brain, and don't bet on the wire yet.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
An agent runtime splits into three layers with three different build-or-buy answers.
- Sandbox: an isolated VM with a persistent volume. Buy it.
- Harness: the agent loop (Claude Code, Codex, Gemini CLI, your own). Keep it swappable.
- Wire: how a person on a phone or desktop reaches a remote agent. The agent-client protocol (ACP) is stdio-first; its remote transport is still a draft. Keep it thin.
What you're seeing
Claude Code. One harness around the same filesystem, tools and integration rail.
Codex. A second harness proves why the integration should not depend on one product's internals.
Gemini CLI. A third harness uses the same stable surfaces: files, a CLI and MCP.
Your own. The loop can change without replacing the sandbox or the wire.
Set it up
- Expose your system through an MCP server (for remote, authenticated access) and a CLI (for local, scriptable access). Every harness can call both.
- Do not build on one harness's internal APIs. A mod or plugin that only one harness runs ties you to it.
- Pick a sandbox with snapshots and a persistent volume, and treat its disk as the agent's working memory.
Prompt
List every place this project integrates with a specific agent harness (config files, plugins, hooks, SDK calls). For each, say whether the same capability could live behind an MCP server or a CLI that any harness can call, and what moving it would take. Do not change anything.Skills
- harness-engineering-playbook
skills/governance/harness-engineering-playbook, evaluate harness boundaries
References
- Agent Client Protocol: transports
- Model Context Protocol
- Vercel Sandbox
- E2B
- Entity:
research/entities/concept/agent-harness-three-layer-split.md
Medallion layers live in the filesystem.
Each workspace keeps its own bronze, silver and gold as plain folders. A shared ledger records what was decided.
bronze/ Inputs as received. Append-only, hashed, never edited.
silver/ Typed and validated. Every value cites its bronze source.
gold/ Decisions and definitions the organization trusts.
Files are the agent's working memory. The ledger is the organization's.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Agents are best at files: grep, diff, read, write. So the data layers live as folders inside each workspace's filesystem, and only the record leaves.
What you're seeing
One workspace. Inputs land in bronze/ untouched. The agent produces typed, cited records in silver/. Decisions and definitions land in gold/, and each one appends a block to the ledger.
Many workspaces. Each sandbox keeps its own medallion folders and ontology. All of them write to one shared ledger, the system of record.
Set it up
- Make
bronze/append-only and hash every input on arrival. - Require every
silver/value to cite its bronze source (file, page, span). - Write to the ledger from code, not from the model: activities, approvals, gold definitions.
Prompt
Design a medallion layout for this workspace's data as folders: bronze/ (inputs as received, append-only, sha256 recorded), silver/ (typed records, each with a citation back to bronze), gold/ (decisions and definitions). Specify the ledger table that records activities, approvals and gold definitions, and which component writes each row. Output a tree and a table schema.Skills
- checkit
skills/research/checkit, preserve source evidence during intake - cross-review
skills/governance/cross-review, review the boundary design independently
References
docs/references/workspace-context.md, privacy and storage boundariesresearch/entities/concept/agent-harness-three-layer-split.md, the runtime boundary
A review system, built on the pattern.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
An architecture pattern from a real review system, with the domain removed: one sandbox per case, readers that only extract, code that decides, a ledger that remembers.
What you're seeing
Sandbox. One microVM per case with a persistent volume. The medallion folders live inside it. The agent may write only scratch, notes and proposals.
Readers. The harness agent runs the review skill (the skill is the workflow) and launches one reader subagent per document. Each returns typed claims with verbatim quotes and locations.
Judges. Code checks every quote against its source. An unverifiable claim stays a claim and can only push the outcome toward manual review. No decider sees raw document text.
Ledger. Activities, approvals and gold definitions go to one shared Postgres ledger outside every sandbox.
Why it holds
Untrusted text never reaches the component that decides. The model's job is reading; the code's job is judging; the ledger's job is remembering. Each boundary can be tested on its own.
Set it up
- Give each case an isolated working directory and read-only input mount.
- Make extraction output typed claims with source locations.
- Verify claims with deterministic code before rules or approval use them.
- Append activities and approvals outside the case workspace.
Prompt
Write a review skill for documents in bronze/. For each document, launch one reader subagent with read-only tools. It returns claims as JSON: {field, value, quote, page, bbox}. Then run a deterministic verifier that checks each quote occurs verbatim in the source; unverified claims keep status "claimed". Only verified claims reach the rules. Record every step in the ledger. Show the skill file and the verifier's tests.Skills
- skillify
skills/tooling/skillify, turn a proven procedure into a tested skill - cross-review
skills/governance/cross-review, a different model reviews the verifier
References
research/entities/concept/agent-harness-three-layer-split.md, the architecture boundarydocs/references/workspace-context.md, privacy and workspace limits
Context
What reaches the window, and when?
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Act II explains what reaches the model window, how to make recall automatic, and when to use files, graph links, vectors or live tools.
Act scenes
- How an agent's context is built
- Hooks turn recall into a reflex
- Files first. Vectors when words diverge.
Read next
Continue to How an agent's context is built to identify the always-on layers before adding more context.
How an agent's context is built.
Everything the model knows this turn is what reached the window. The workspace decides what reaches it.
Hover any layer of the window. Each one has a source on disk, a moment it loads, and a budget.
Less guessing is the product of more grounded layers, not of a bigger model.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
The model knows only what reached its context window this turn. A workspace decides what reaches it, from where, and when.
What you're seeing
Bare session. The harness system prompt and your message. Everything else is filled in by the model: the hatched block.
Workspace session. Layers arrive from disk: the primer at boot, the memory index, SessionStart hook output, one line per installed skill, the intake hook on every prompt, then tool results as the agent reads files and runs commands. The proportions are illustrative.
The layers and their sources
- Primer:
CLAUDE.md/AGENTS.md, loaded at session start. - Memory index: one line per fact file (in Claude Code,
~/.claude/projects/<project>/memory/MEMORY.md), facts loaded on demand. - Hook output: text a hook prints is added to context (SessionStart, UserPromptSubmit).
- Skill descriptions: each skill's front matter description is present up to a listing budget (past it, skills show as bare names); bodies load when triggered.
- Tool results: what the agent reads and runs. Usually the largest layer, and the one you shape with good files.
Set it up
- Budget the always-on layers. Primer, memory index and skill descriptions are paid on every turn.
- Move anything conditional into something that loads on demand: a routed doc, a skill body, a hook that only fires on a matching prompt.
- Measure: count tokens in the always-on layers and keep a ceiling.
Prompt
Inventory what loads into your context in this workspace before I type anything: the primer files, memory index, hook output, skill descriptions. For each, give the path, an approximate token count, and whether it must be always-on. Propose cuts that move conditional material into on-demand files. Change nothing yet.Skills
- role-x
skills/orchestration/role-x, load task-specific context on intake - kg
skills/knowledge/kg, load graph evidence on demand
References
Hooks turn recall into a reflex.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Three levers put knowledge in front of the agent, in increasing order of force. The primer asks. A skill knows how. A hook runs every time, without the model deciding.
The stations
Primer. CLAUDE.md routes: "What do we know? → kg skill → /kg load <topic> --terms <synonyms>". It is reasoning-enforced: the model may skip it.
SessionStart. Five workspace hooks run before the first prompt: skill freshness, git identity, auth preflight, lens coverage and skill sync. Plugin and user-level hooks add more; the bstack plugin's hook injects the board facts and the self-improvement metric.
UserPromptSubmit. The intake hook routes every prompt to a lens and injects its quality bar, the graph's constraints and the most relevant entities. This is recall without asking.
PreToolUse. Before Bash, Write and Edit, a control gate checks .control/policy.yaml, a regression gate and a file-write safety check run. In Claude Code, a PreToolUse hook that exits with code 2 blocks the call.
Stop. The bridge hook writes the session to docs/conversations/ and stamps provenance, so the next session can search it.
Set it up
- Register hooks in
.claude/settings.jsonunderhooks: event, optional tool matcher, command. - Keep hook output short and specific: a handful of entity claims with paths, not whole files.
- Make a gate's failure message say what to do instead.
Prompt
Add a UserPromptSubmit hook to .claude/settings.json that runs scripts/kg-intake.sh. The script reads the prompt from stdin JSON, extracts 3 to 6 key terms, scores docs/knowledge-index.md rows by matches in slug, tags and core_claim, and prints the top 5 as "- claim · [path]" under a heading "Task-relevant knowledge". It must finish under 300 ms and print nothing when nothing matches. Add a test with two sample prompts.Skills
- role-x
skills/orchestration/role-x, the lens router behind the intake hook - kg
skills/knowledge/kg, the loader the hook and the primer point to - harness-engineering-playbook
skills/governance/harness-engineering-playbook, design executable boundaries
References
- Claude Code hooks reference
- Registered hooks:
.claude/settings.json; gate:scripts/control-gate-hook.sh; bridge:scripts/conversation-bridge-hook.sh
Files first. Vectors when words diverge.
At 1,430 entities the compiled catalog is about 260K tokens: it fits a 1M-token window, so the catalog routes and the model reads. Add vectors when vocabulary diverges or the catalog outgrows the window.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Retrieval is a toolbox the agent composes through bash and tools, not one database you bolt on.
What you're seeing
A query fans out to eight retrievers and the results come back merged into a cited answer.
Local. ripgrep for exact text, the compiled front-matter index for routing, graph hops along related: links, and body search when catalog hits are weak.
Semantic. Embeddings in a vector store find the same idea in different words, and reach corpora larger than the window. They return similar, not true: cite the source passage.
Live. MCP servers and APIs for state that changes: trackers, cloud resources, mail, the web.
When to add vectors
At our size (1,430 entities) the compiled catalog is about 260K tokens and fits a 1M-token window: the catalog routes, the model reads the entities it picked, and an embedding index would be one more thing to keep fresh. The entity bodies themselves (about 2.3M tokens) do not fit; that is what routing is for. Add vectors when vocabulary diverges (users and documents use different words), when the catalog outgrows the window, or for external document sets you do not curate.
Set it up
- Keep canonical material in files with stable paths.
- Build a compact index for routing, then load source bodies only after a hit.
- Add a semantic retriever only when exact terms and graph links miss known relevant material.
Prompt
Answer my question using every retrieval path available here, in this order: rg over the repo, the knowledge index (docs/knowledge-index.md), one hop of related: links from the top hits, then any MCP or web source if the answer depends on current state. For each claim, cite the path or URL you actually opened, and list the paths you tried that returned nothing.Skills
- kg
skills/knowledge/kg, load graph context and related entities - checkit
skills/research/checkit, verify source material before it counts - bookkeeping
skills/knowledge/bookkeeping, capture supported findings durably
References
- Entity:
research/entities/pattern/llm-as-index-architecture.md - ripgrep
- Model Context Protocol
Second brain
How is knowledge read, and how does it grow?
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Act III makes knowledge useful: measure whether it is read, keep claims and receipts in markdown, route with an index, and promote repetition carefully.
Act scenes
- Most second brains are write-only
- Front matter is the API
- An entity is a claim with receipts
- The knowledge loop
- Insight hardens into mechanism
Read next
Continue to Most second brains are write-only to start with the recall measure instead of the entry count.
Most second brains are write-only.
of 565 agent sessions in the seven days to 2026-10-26 loaded the knowledge graph (5 sessions). Capture is easy. Recall is the product.
measured 2026-10-26 · session telemetry
Put recall on the startup path.
The primer routes to it. An intake hook surfaces matching entities. /kg load runs before planning. And when reads lag, prune production. Don't add more writers.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
It is easy to build a second brain that only gets written. The measure that matters is how often agents read it at the moment they need it.
What you're seeing
Today. Many write paths (bookkeeping, ingestion, hooks) and one thin read path. In the week measured (2026-10-26), 0.9% of 565 sessions loaded the graph.
Wired at intake. Every session gets a read path: the primer routes to it, the intake hook surfaces entities, and /kg load runs before planning.
Set it up
- Instrument reads, not just writes: log each
/kg loadand each hook injection. - Put recall on the startup path (“Hooks turn recall into a reflex”).
- When reads lag, slow writers down. More entries nobody reads add cost and noise.
Prompt
Measure how this workspace's knowledge base is actually used. From the harness transcripts (for Claude Code, ~/.claude/projects/<project>/*.jsonl), count sessions in the last 7 days that loaded the graph (/kg load, reads under research/entities/) versus sessions that wrote to it. Report the ratio, the five most-read and five never-read entities, and one change that would raise reads.Skills
- kg
skills/knowledge/kg, load relevant graph context - bookkeeping
skills/knowledge/bookkeeping, score and maintain entities
References
docs/knowledge-index.md, compiled graph catalogdocs/conversations/Conversations.md, session record index
Front matter is the API.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Plain markdown stays canonical. Front matter turns each file into a record that tools and agents can query without a database.
What you're seeing
Files. The folder is the first index: research/entities/<type>/<slug>.md. Each card is one entity, filed under its type.
Index. A compiler reads every front matter block, and each file becomes one row of docs/knowledge-index.md: type, slug, claim. The catalog is cheap enough to load at the start of a task.
Edges. Each row buds a node, and related: wikilinks grow into the edges between them. The catalog stays: the graph is compiled from the same files, not kept in a separate store. This is a real 13-entity slice of the graph around llm-as-index-architecture, with its 23 real links.
Synonyms. aliases: hang off their entity. /kg load "knowledge graph" --terms "no embeddings retrieval" --expand 1 scores its words against aliases as well as slugs, ranks this entity first and, with --expand 1, pulls one hop of neighbours with it.
A minimal schema
---
id: pattern/llm-as-index-architecture
type: pattern # concept | pattern | tool | question | …
status: entity # candidate until scored
core_claim: "One falsifiable sentence."
tags: [architecture-decision, knowledge-graph]
aliases: [kg routing, no embeddings retrieval]
related: ["[[knowledge-graph]]", "[[bstack-engine]]"]
sources:
- url: https://…
note: "Read verbatim YYYY-MM-DD: the passage that supports the claim"
created: YYYY-MM-DD
updated: YYYY-MM-DD
---Set it up
- Make the markdown file and its front matter the canonical source.
- Validate required fields and links in CI or before publishing.
- Regenerate the catalog from files instead of hand-editing it.
Prompt
Write scripts/build_index.py: walk research/entities/**/*.md, parse the YAML front matter, and write docs/catalog.md (in a repo that has no catalog yet) with a header (entity count, edge count, dangling links) and one row per entity: type, slug, core_claim, tags, path. Fail on missing core_claim or type. Add tests with a valid file, a missing field and a dangling related: link.Skills
- bookkeeping
skills/knowledge/bookkeeping, score, promote, index and lint - kg
skills/knowledge/kg, load by topic with synonyms
References
docs/knowledge-index.md, generated catalogresearch/entities/, canonical entity markdown
An entity is a claim with receipts.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
An entity is a single falsifiable claim with the evidence that supports it, scored before it is promoted and linked to what it depends on.
What you're seeing
The entity file. The card is canonical markdown with a compact front matter record, not a row trapped in a database.
One falsifiable sentence. core_claim is a claim, not a summary. It can be wrong, which is what makes it useful.
Read verbatim, dated. Each source carries the passage actually read and the date. A citation you did not open is worth half.
Scored before promotion. Novelty, specificity and relevance. Below the bar, it stays a candidate.
Typed links become edges. The graph on the right is a real neighbourhood of this entity, found through related-neighbour traversal. Hover a node to read its slug.
Set it up
- Write one claim that an informed reader could dispute.
- Record the source passage actually read and its date.
- Score it before promoting it, then add only existing related links.
Prompt
Turn this finding into a knowledge entity: write one falsifiable core_claim, list each source with the exact passage you read and today's date, score novelty, specificity and relevance from 0 to 3 with one line of reasoning each, and link 2 to 4 related entities that already exist (check with rg). If the total is under 5, keep status: candidate.Skills
- bookkeeping
skills/knowledge/bookkeeping, score, link and lint the entity - kg
skills/knowledge/kg, discover existing related entities
References
- The entity shown:
research/entities/concept/agent-harness-three-layer-split.md - Catalog:
docs/knowledge-index.md(1,430 entities, 6,076 edges)
The loop that makes knowledge readable.
Memory holds facts about the owner. The graph holds claims about the world. The ledger holds what is in flight.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
The knowledge loop has six stations. Skipping any one of them is how a graph goes stale or goes unread.
The stations
Capture. /checkit <artifact> ingests a link, paper or repo and verifies every source before it counts.
Score. bookkeeping run scores and promotes. Below the bar, a finding stays a candidate.
Link. Edges are explicit [[relations]]; bookkeeping lint catches dangling links before publishing.
Index. One compiled catalog, docs/knowledge-index.md. Entities stay canonical markdown.
Load. /kg load <topic> --terms <synonyms> at intake, reporting what it missed.
Act. Outputs cite entities; new findings re-enter at capture.
Three stores, three jobs
Memory holds facts about the owner. The graph holds claims about the world. The ledger holds what is in flight. Mixing them is how private preferences end up in shared knowledge, or stale status ends up in memory.
Set it up
- Capture only source-backed material.
- Score and lint before an entry becomes durable graph knowledge.
- Load the compact catalog at intake and cite the full entity when using it.
Prompt
Trace one finding through this repository's knowledge loop: identify the source capture, score or candidate state, related links, catalog row, and one session where it was loaded. Report missing stations and propose the smallest repair. Do not edit files.Skills
- checkit
skills/research/checkit - bookkeeping
skills/knowledge/bookkeeping - kg
skills/knowledge/kg
References
docs/knowledge-index.md, compiled catalogdocs/references/workspace-context.md, knowledge-layer boundaries
Insight hardens into mechanism.
Promote on the third instance, with a concrete mechanism, an invariant and a failure mode. Name what the new rule retires.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
This is how the agent gives back. Insights climb a ladder from observation to mechanism, and each step up trades flexibility for force.
The levels
Observation. Most things noticed in a session stay there. The session record keeps them searchable.
Memory fact. One file per fact about the owner or the work, indexed, checked against current state before reuse.
Entity. A claim about the world with sources, scored and linked.
Skill. A procedure that recurred: a description that routes, a deterministic core, evals that prove it triggers.
Hook, policy or test. A rule that must never be broken stops depending on memory. It executes.
The promotion rule
Promote on the third instance, with a concrete mechanism, an invariant and a named failure mode. Every promotion names what it retires, so the system does not only grow.
Set it up
- Keep a dated record of the separate instances.
- State the mechanism, invariant and failure mode before creating a permanent rule.
- Give the new mechanism an executable check where possible.
Prompt
Look back over the last two weeks of session records in docs/conversations/. Find corrections or rules that came up three or more times. For each, propose the lowest level that would make it stick (memory fact, entity, skill, hook, policy or test), the mechanism, the invariant it enforces, how it could fail, and what existing rule or note it replaces.Skills
- skillify
skills/tooling/skillify, turn a working session into a tested skill - bookkeeping
skills/knowledge/bookkeeping, promote supported findings into entities
References
docs/references/agent-operating-protocols.md, Crystallize (P16)research/entities/, durable, cited findings
Skills
How is this kind of work done here?
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Act IV packages repeatable work as procedures, keeps deterministic work testable, and keeps the skill roster small enough to route.
Act scenes
- A skill is a procedure
- Skill, CLI, MCP
- Author once, fan out, ration
Read next
Continue to A skill is a procedure to see how progressive disclosure keeps procedures available without loading them all.
A skill is a procedure,
not a prompt.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
A skill is a folder: a SKILL.md whose front matter description routes, a deterministic script core, references loaded on demand, and evals.
What you're seeing
Installed skills' descriptions sit in context, up to a listing budget (the thin bars). A request is matched against them; the winner's body loads, and its scripts and references load only if needed.
Write the description like a trigger spec
---
name: kg
description: >-
Load knowledge-graph entities relevant to a topic from research/entities.
USE WHEN: "what do we know about X", planning that needs prior findings,
before /checkit. NOT FOR: owner preferences (memory), live project status
(initiative ledger).
---Set it up
- Put deterministic work in
scripts/with tests; keep judgment in the body. - Add evals in both polarities: prompts that must trigger it and prompts that must not.
- Keep the body under a few hundred lines; move detail to
references/.
Prompt
Create a skill at skills/<category>/<name>/ for the procedure we just did. SKILL.md with name and a description that says USE WHEN and NOT FOR; the deterministic steps as scripts/<name>.py with tests; an evals file with 5 prompts that should trigger it and 5 that should not. Run the tests and show the results.Skills
- skillify
skills/tooling/skillify, distill a session into a tested skill - role-x
skills/orchestration/role-x, test whether the description routes correctly
References
Skill, CLI, MCP.
One knows. One does. One reaches.
A skill that drives a small CLI beats a wide MCP surface: fewer tools in context, and a core you can test.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Three ways to give an agent a capability. They compose; they do not compete.
All. The diagram shows the decision surface: use no extra mechanism for a one-off, then add only the smallest durable capability the work requires.
Skill: knows. Repeatable judgment and steps, loaded when the description matches.
CLI: does. Deterministic, local, testable work. Pipes into other tools. Lives in the skill's scripts/ or on PATH.
MCP: reaches. Remote systems with authentication, shared across every harness. Each tool definition costs context, so keep the surface small.
Rule of thumb
A skill that drives a small CLI beats a wide MCP surface for local work: fewer tools in context and a core you can unit-test. Reach for MCP when the system is remote, needs auth, or should be shared by several harnesses. A one-off needs neither: just ask.
Set it up
- Write the deterministic local operation as a command with tests.
- Wrap judgment about when and how to use it in a skill.
- Expose remote, authenticated state through the narrowest MCP tool surface.
Prompt
I want the agent to be able to <capability>. Recommend skill, CLI, MCP server or a combination, using these criteria: is it local and deterministic (CLI), does it need judgment about when and how (skill), does it touch a remote authenticated system or need sharing across harnesses (MCP). Give the smallest design and what each piece contains.Skills
- skillify
skills/tooling/skillify, package a repeated procedure - harness-engineering-playbook
skills/governance/harness-engineering-playbook, assess the integration boundary
References
Author once. Fan out. Ration hard.
- One canonical source, in its own repo.
- Install once, symlink into every harness. Never copy.
- New skills ship evals: it fires when it should and stays quiet when it shouldn't.
- Retire before you add. The roster is a budget.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Author skills once, install them once, and symlink them into every harness. Then ration: more skills is not more capability.
What you're seeing
Fan out. One canonical repository is the source. In this workspace 31 harness folders (.claude, .windsurf, .kiro and others) point at one .agents/skills install. Keep that install a link to the canonical repo, not a copy: copies drift.
Ration. Measured on 2026-08-23: with 457 skills installed, the harness kept full descriptions for 26. The rest were bare names, and a bare name cannot trigger itself. More skills made each one less likely to fire.
Set it up
- One source repository for skills, versioned and reviewed like code.
- Install to one folder and symlink; never copy, or versions drift.
- Keep a roster file of required skills and retire before you add.
Prompt
Audit the skills installed for this workspace: count them per harness folder, find copies that are not symlinks to the canonical install, find duplicates with overlapping descriptions, and list skills with no eval file. Propose a roster of at most 30 that covers the work in the last month of session records, and what to retire.Skills
- skillify
skills/tooling/skillify, maintain tested procedures - role-x
skills/orchestration/role-x, evaluate whether descriptions route to the right procedure
References
- Required roster:
bstack/references/companion-skills.yaml
Structure
Which bytes may the agent touch?
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Act V separates shared governance from sovereign product repositories and gives every concurrent writer an isolated tree.
Act scenes
- One place, many repos
- One writer per tree
Read next
Continue to One place, many repos to map what belongs in shared governance and what remains with a product.
One place, many repos.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
One governance repository is the place. Product repositories nest inside it and keep their own CI. Worktrees are created per task and thrown away.
What you're seeing
Shared. The governance repo is the core: primer, policy, lenses, skills, graph and record, one copy that every agent reads and that is reviewed like code.
Sovereign. 66 product repos orbit it (42 under apps/, 13 under core/, 11 under work/). Each has its own history and release cadence; most carry their own CI and local AGENTS.md. The pulses are their own checks, on their own clocks. Governance reaches them along the spokes, product code never flows back into the core.
Disposable. A worktree buds off a repo for one task, works, comes back through review, merges (gold) and is swept. The counter keeps running: created, merged, swept.
The layout
workspace/ governance repo
├─ AGENTS.md ≡ CLAUDE.md one primer, every harness
├─ .control/ policy · initiatives · asks
├─ roles/ lenses: context per kind of work
├─ skills/ canonical skills (own repo)
├─ research/entities/ the graph, as markdown
├─ docs/ sessions · plans · handoffs · ADRs
├─ apps/ core/ work/ … product repos, own CI
└─ .worktrees/ one per task, disposableRules
- Shared: the primer, policy, lenses, skills, graph and record. One copy, reviewed like code.
- Sovereign: each product repo has its own CI, release cadence and local AGENTS.md. Agents read that file first when working there.
- Disposable: worktrees branch from main, merge back through review, and are swept after merge.
Set it up
- Keep shared instructions and records in the governance repository.
- Give every product repository its own local instructions and delivery checks.
- Create worktrees from the correct product base, not from an assumed workspace root.
Prompt
Propose the folder layout for a governance workspace that holds these product repos: <list>. Show the tree, which directories are their own git repositories, which files every agent reads first, and where session records, plans, handoffs and ADRs live. Flag anything in the current tree that would conflict.Skills
- role-x
skills/orchestration/role-x, choose the local context for the task - handoff
skills/orchestration/handoff, preserve the cross-context work record
References
docs/references/workspace-context.md, conventions and boundariesroles/_index.md, lens routing
One writer per tree.
Parallel agents never share a checkout. They share main, through review.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Parallel agents never share a checkout. Each works in its own worktree and meets the others only on main, through review.
One writer per tree. The lanes represent separate checkouts, not tabs in one mutable directory. Their common meeting point is a reviewed change, not a shared working tree.
Rules, each learned the hard way
- Branch is the first action. After checking out main, create the branch before touching a file.
- Reviewers read; they never write. A reviewer that "reproduces" by editing the live tree corrupts the writer's work.
- A live thread's worktree is the thread. Removing it breaks the session bound to it.
- Unfinished work becomes a draft PR, never a silent salvage into another branch.
- Janitor after merge, dry run first. Sweep merged branches and worktrees; never touch protected or unrelated work.
Set it up
- Create the branch and worktree before the first edit.
- Assign one writer to each tree and give reviewers read-only scope.
- Check status before every commit and use a dry run before cleanup.
Prompt
Create a worktree for this task: git worktree add .worktrees/<slug> -b <type>/<slug> origin/main. Work only inside it. Before committing, show git status and confirm every changed file belongs to this task. When the PR merges, list what the janitor would remove (dry run) and wait.Skills
- p9
skills/orchestration/p9, watch CI instead of polling - cross-review
skills/governance/cross-review, keep writing separate from review
References
docs/references/agent-operating-protocols.md, Hygiene (P10) and Janitor (P8).control/policy.yaml, delivery gates
Fleets
Who else is here, and who checks whom?
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Act VI assigns durable responsibilities, preserves continuity across contexts, and puts review and capacity limits between parallel work and delivery.
Act scenes
- Roles, not agents
- Spawn, reuse, or hand off
- Governance that scales with the fleet
Read next
Continue to Roles, not agents to give each participant a responsibility and an explicit non-responsibility.
Roles, not agents.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Scale with roles, not with more agents. Each role has a job and, more importantly, something it must never do.
Owner. Sets intent, answers asks, holds human-only gates. Must not become the bottleneck for routine merges on green.
Meta-orchestrator. Watches orchestrators and capacity on a fixed tick, at most one intervention per tick. Does not do workers' work.
Orchestrator. Owns one initiative: plans, dispatches bounded tasks, integrates results. Never merges its own work without independent review.
Worker. One bounded task in an isolated worktree; returns a PR and receipts.
Reviewer. A different model or provider than the writer; scores against a rubric and binds the verdict to a commit.
Sensor. Observes and files: capacity, drift, stalls. Never acts on what it measures.
How it runs here
Orchestrators and workers run as T3 Code threads and delegated child tasks with their own worktrees. Earlier Paseo-hosted sessions are history.
Set it up
- Give every task one owner and one bounded output.
- Separate the writer, reviewer and observer roles.
- Define the stop condition and the evidence a worker must return.
Prompt
For this initiative, define the owner, orchestrator, worker, reviewer and sensor roles. For each, state one bounded responsibility, what it must never do, the evidence it produces, and the handoff point to the next role. Do not create tasks yet.Skills
- cross-review
skills/governance/cross-review, make review independent of authorship - handoff
skills/orchestration/handoff, preserve state between bounded tasks
References
bstack/references/delegation.md,bstack/references/orchestrator-tick.mddocs/maestro-orchestration-loop.md
Spawn, reuse, or hand off.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Four questions choose the mechanism for the next piece of work.
What you're seeing
Independent of what I know? Spawn. A child task takes the work to its own worktree with a fresh context, which also keeps it from anchoring on your conclusion, and comes back with a receipt.
Needs my context? Keep it. The task joins this session and the context arc grows; a fork copies the same context into a new thread when you want two lines of work.
Outlives this context window? Write a brief: progress, checks, stop conditions. This session can end; a successor reads the brief and carries on.
Only the owner can decide? File an ask with its context: summary, options with trade-offs, a recommendation, sources. The answer comes back to the session that asked.
Why sessions roll over. Each dot is one of 838 main sessions. The 158 that ran past 400K tokens grow and turn amber: they carried 87% of the cost.
Why sessions roll over
In a 30-day sample (measured 2026-10-10), 158 of 838 main sessions ran past 400K tokens and carried 87% of the cost. Long sessions hand off to a successor with a handoff document instead of growing forever.
The five artifacts
- Handoff: narrative for the next agent (
docs/handoffs/). - Handback: a message for the human.
- Brief: machine state for a persistent loop.
- Ask: one decision, with its context.
- Receipt: evidence that it works.
Set it up
- Use a fresh isolated task for independent work.
- Write a handoff before a task needs more context than the current session can safely carry.
- Escalate only decisions that cannot be resolved from the recorded evidence.
Prompt
We are near the end of this context. Write a handoff to docs/handoffs/YYYY-MM-DD-<arc>.md: a three-line TL;DR, the current state (branch, PRs with SHAs, what is verified and what is not), the first action for the next session, and open asks with your recommendation.Skills
- handoff
skills/orchestration/handoff - persist
skills/orchestration/persist
References
docs/conversations/Conversations.md, conversation index.control/asks/, decisions that need owner authority
Governance that scales with the fleet.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Governance has to scale with the number of agents, or it becomes the bottleneck.
What you're seeing
Pace. A capacity governor reads measured account headroom and sets the lanes: several on green (five in the configured non-Claude green fallback; actual limits depend on the provider and meta setpoints), one on amber, none on red. The dial shows the pattern; the setpoints move. Work queues at the dial instead of failing mid-run.
Review. Substantive PRs get an independent review before merge; governance changes need all three strata: a different vendor's model, a fresh-context devil's advocate, and composed review skills. Rejections arc back to the fleet as fixes; the writer never certifies its own work.
Policy. An executable gate checks CI, a review verdict pinned to the commit, and resolved threads. A PR missing one waits at the gate (amber). Merged work runs on the gold line.
Sensors. Sensors watch main and file tickets back to the fleet. They observe and record; agents act on what they file.
Principles
- The writer cannot certify its own work.
- Policy is executable; prose is advice.
- Sensors observe and file; agents act.
- Pace from measured capacity, not hope.
Set it up
- Set capacity from a measured limit, not a fixed agent count.
- Require review from an independent model or fresh context.
- Put the final merge decision behind executable policy checks.
Prompt
Review this PR as an adversarial reviewer from a different model than the author. Score it 0 to 10 on: no over-engineering, no template paste, correct contracts at boundaries, failure modes named, tests cover the change. Grade each finding BLOCKER, MAJOR or MINOR with the input that reproduces it. Bind your verdict to the commit SHA.Skills
- cross-review
skills/governance/cross-review - dogfood
skills/governance/dogfood
References
.control/policy.yaml(merge gates),METALAYER.md
Leadership
What does this ask of people?
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Act VII makes human judgment the scarce resource: use loops for repeated work, clear contracts for delegation, narrow asks and shared standards.
Act scenes
- The unit of work is now a loop
- Everyone leads a fleet
- Attention is the new ration
- Bars rise in the open
Read next
Continue to The unit of work is now a loop to distinguish a one-off task from a learning cycle with evidence.
The unit of work is now a loop.
When an attempt costs minutes, making gets abundant and deciding gets scarce.
Every question is something you can start today.
Every repeated task is something you can automate or improve.
Every piece of work leaves the system better: a note, a skill, a check.
The question moves from “can I do this?” to “should this exist, and how will I know it's right?”
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
From The New Dynamics of Agentic Leadership: when an attempt costs minutes, the unit of work stops being a task and becomes a loop.
Task. Someone decides it is worth doing, a ticket waits in a queue, one person attempts it once.
Loop. State an intent, let agents act in parallel, look at what came back, sharpen the intent, run again. Making becomes abundant; deciding becomes scarce.
The new baseline
- Every question is something you can start today.
- Every repeated task is something you can automate or improve.
- Every piece of work leaves the system better: a note, a skill, a check.
- Time agents free up is reinvested on purpose.
Set it up
- State an observable intent for the loop.
- Run a bounded attempt, capture the evidence and update the next attempt from it.
- Stop when the evidence condition is met or a named escalation is required.
Prompt
Turn this recurring task into a bounded loop. Define its intent, one reversible first iteration, the evidence to collect, the decision that updates the next iteration, a cost ceiling, and the condition that stops or escalates it. Do not start the loop yet.Skills
- agentic-leadership
skills/strategy/agentic-leadership, the source of this act: five-term contract, attention rationing, ask template (published in broomva/skills; rungit -C skills pullif your checkout lacks it, then link it into your harness's skills folder) - persist
skills/orchestration/persist, carry bounded loop state across contexts - decision-log
skills/strategy/decision-log, preserve the decision that changes the next run
References
- The New Dynamics of Agentic Leadership (X article)
docs/references/agent-operating-protocols.md, Persist (P12) and Orchestrate (P19)
Everyone leads a fleet.
What each person brings to their fleet is taste and judgment: knowing what good looks like, and deciding what to accept.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Every delegated piece of work, to an agent or a person, runs under a five-term contract.
Intent: the outcome and why it matters. Keep it stable; if it is wrong, say so and propose a better one.
Bounds: what may be decided without asking, the budget, and what cannot be undone.
Evidence: the observable check that means done. Reasoning is not evidence.
Escalation: when to stop and ask. Every ask carries context, options, a recommendation and a safe default.
Review: who judges the result before it ships. You do not certify your own work.
Set it up
- Write the intent and boundary before dispatch.
- Name an observable check that the worker cannot self-certify.
- Define the escalation and review owner before work begins.
Prompt
Before you start, write the contract for this work in five lines: Intent (observable outcome and why), Bounds (what you may do without asking; what needs a yes; the budget), Evidence (the check that means done), Escalation (when you stop and ask), Review (who judges before it ships). If a term is missing, propose it, then wait for my confirmation only if it involves cost or anything irreversible.Skills
- agentic-leadership
skills/strategy/agentic-leadership, the source of this act - decision-log
skills/strategy/decision-log, record the decision boundary - cross-review
skills/governance/cross-review, keep final judgment independent
References
.control/asks/, decision records with options and recommendationsdocs/references/agent-operating-protocols.md, Dep-Chain (P14) and Cross-Review (P20)
Attention is the new ration.
Reversible drafts, research, branches: act and note it.
Costly long compute, many iterations: only inside a budget.
Irreversible or external spend, publish, merge outside policy, contact: a yes first, every time.
The measure of an autonomous system isn't how much it does without you. It's how precisely it calls you.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Attention is fixed. The job of an autonomous system is to spend it only where it is needed.
Every thread pings you. Forty threads each wanting a look will consume a day.
The gate calls you. Actions are classified. Reversible work proceeds and is noted. Costly work runs only inside a budget. Irreversible or external work waits for a yes. Only a short, ordered list reaches the human.
The measure of an autonomous system isn't how much it does without you. It's how precisely it calls you.
Set it up
- Classify planned actions before they begin.
- Record a budget for costly work.
- Batch only the decisions that need owner authority, with options and a reversible default.
Prompt
Classify every action in your plan as reversible (act and note), costly (needs a budget) or irreversible/external (needs my explicit yes). Do all reversible work now. Then send me one ordered list of decisions, the one that unblocks the most first, each with context, two or three options, your recommendation and what you will do if I do not answer.Skills
- agentic-leadership
skills/strategy/agentic-leadership, the source of this act - decision-log
skills/strategy/decision-log, preserve decision context and alternatives - persist
skills/orchestration/persist, keep a bounded work state without repeated asks
References
.control/asks/DECISION-LAYER.md, decision-record contract.control/policy.yaml, executable safety boundaries
Goalposts teach waiting. Bars rise in the open.
People learn to wait when proposals get overridden, the leader decides anyway, the bar moves silently, or a failed attempt costs more than a passive miss.
Make everything queryable: decisions, standards and why they changed live in the same shared graph that people and agents read.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
In agentic work the bar is supposed to rise. What matters is who moves it, and whether everyone can see it move.
Goalpost. Success is redefined privately, after the work. People learn that any attempt may be judged by a rule that does not exist yet, so they wait.
Bar. Capability changes, the standard rises, and the reason is written into shared, queryable context. People and agents read the same standard, so they look ahead.
Waiting is often learned
People learn to wait when their proposals get overridden, the leader decides anyway, the bar moves silently, or a failed attempt costs more than a passive miss.
Make everything queryable
Decisions, standards and why they changed live in the same graph the agents read (Act III). That closes the loop between grounding agents and leading people.
Set it up
- Record the current standard, source and evidence in a durable file.
- State the event that changed the standard.
- Link the decision from the work and knowledge records that rely on it.
Prompt
Write a decision record for this changed standard: the prior bar, the new bar, the evidence that required the change, affected work, exceptions, review date and links to the source records. Do not treat an unverified observation as a standard.Skills
- agentic-leadership
skills/strategy/agentic-leadership, the source of this act - decision-log
skills/strategy/decision-log, record decisions with context - bookkeeping
skills/knowledge/bookkeeping, link durable claims to their evidence
References
docs/knowledge-index.md, queryable knowledge catalogdocs/references/agent-operating-protocols.md, Audience (P18) and Bookkeeping (P6)
Better agents come from better harnesses.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Harness engineering is the discipline of everything around the model. It is where reliability comes from, and where work compounds as models change. The model at the centre never changes in this picture; the outcome meter beside it is illustrative, not measured.
Model and loop. The model proposes; the loop runs tools and feeds results back.
Tools. A filesystem and a shell first; MCP for remote systems.
Context. Primer, memory, hooks, skills and the graph decide what reaches the window.
Guards. Policy gates, permissions and hooks make boundaries executable.
Evals and review. Tests, receipts and a different model judging before merge.
Workspace. The outermost ring: it holds all of the above and keeps what every session learns.
Set it up
- Inventory the outer rings before replacing the model or adding prompts.
- Make every boundary observable with a path, command or interaction receipt.
- Strengthen the smallest weak ring, then run the check that proves it changed.
Prompt
Audit this workspace's harness ring by ring: tools (what the agent can run), context (what loads and when), guards (what is executable versus prose-only), evals and review (what checks run before merge), and the workspace record (what each session leaves). For each ring, name the weakest point and the smallest change that would strengthen it.Skills
- harness-engineering-playbook
skills/governance/harness-engineering-playbook - audit-harness-usage
skills/tooling/audit-harness-usage, measure what the harness costs in tokens across traces
References
- Effective context engineering for AI agents
docs/references/agent-operating-protocols.md, empirical and review requirements
Twenty primitives. One loop.
Give agents a place before you give them more autonomy.
Make the graph readable at intake, or stop writing to it.
Scale with roles, isolation and review. Not with more prompts.
Local paths and workspace measurements are dated author-workspace examples, not files shipped in this package. See resources.md for public tools and setup.
Everything in this deck reduces to twenty primitives. Each runs when its trigger applies.
The loop. The operating vocabulary: small disciplines with explicit triggers, rather than one vague instruction to be careful. This deck reads them in five phases. Orient: Snapshot, Bridge, Lens, Freshness, Dep-Chain. Bound: Gate, Hygiene, Tickets, Orchestrate. Act: Fanout, Wait, Persist, Audience. Verify: Empirical, Cross-Review, Pipeline. Learn: Bookkeeping, Crystallize, Dream, Janitor.
The thesis. The loop resolves into one orb. The closing cards reduce the deck to place, recall and governed collaboration: the workspace is the product.
Three takeaways
- Give agents a place before you give them more autonomy.
- Make the graph readable at intake, or stop writing to it.
- Scale with roles, isolation and review, not with more prompts.
Set it up
- Choose one repository and one small, reversible improvement.
- Define its evidence check before editing.
- Run the check, record the receipt and use it to choose the next improvement.
Prompt
Set up this repository as an agentic workspace in five small PRs: (1) an AGENTS.md routing primer and a CLAUDE.md copy; (2) a policy file plus a PreToolUse gate for destructive commands; (3) research/entities/ with a front-matter schema and an index builder; (4) a UserPromptSubmit hook that injects the top matching entities; (5) a Stop hook that writes each session to docs/conversations/. One PR at a time, with tests and a receipt for each.Skills
- dogfood
skills/governance/dogfood, verify changes by use - cross-review
skills/governance/cross-review, obtain independent judgment before delivery
References
AGENTS.md(primitives and routes),bstack/references/primitives.mddocs/references/agent-operating-protocols.md- Speaker script and sources:
docs/keynote/agent-workspaces/script.md