A scaffolding for designing human-AI collaboration architecture. Fork it, fill it in, make it yours.
The files here are templates with guidance you replace with your own context as the practice develops. The architecture deepens through use, not through pre-filling.
Companion site: aiharness.design
CLAUDE.md Boot file — the centerpiece. Governance, constraints,
session modes, pointers. Keep under 200 lines.
identity.md AI identity document. Written by the AI, about itself,
in the context of your collaboration. Starts blank.
field-notes.md Relational texture. Moments that earned their place.
Starts blank.
reference/
conventions.md On-demand context for style, code, vocabulary, framing.
skills/
trace/SKILL.md Generate session traces. Enhanced with Sense MCP.
mode/SKILL.md Declare working mode. Enhanced with Vibe Harness.
reflect/SKILL.md Mid-session drift check. Enhanced with both.
handoff/SKILL.md End-of-session handoff. Enhanced with both.
traces/
TRACE_TEMPLATE.md Session artifact template. Compression summary,
decisions, residue.
memory/
MEMORY.md Persistent cross-session learning. Updated by the AI.
hooks/
context-monitor.py Autonomic reflex — warns when context window is filling,
blocks tool calls at critical threshold.
config/
modes.md Guide to designing working modes for your practice.
sense.toml Template config for Sense MCP (optional infrastructure).
1. Fork or copy this directory into your project root.
2. Edit CLAUDE.md. Replace the guidance comments with your content. Start with:
- One sentence about what the work is
- Two or three non-defeasible constraints
- Keep the metabolic asymmetry constraint — it applies to everyone
3. Leave identity.md and field-notes.md blank. They develop through work. After 3-5 real sessions, ask the AI to draft its identity document.
4. Create your first trace. After a significant session, copy TRACE_TEMPLATE.md and fill it in. The residue section is the most important part.
5. Try the skills. Type /trace, /mode, /reflect, or /handoff in Claude Code. They work immediately — no infrastructure required. If you later add Sense MCP or Vibe Harness, the same skills get richer automatically.
6. Optionally, set up the context monitor hook. See the setup instructions in hooks/context-monitor.py. Requires Claude Code.
7. Work. Add reference files as conventions emerge. Memory populates as patterns stabilise. The boot file stays lean.
This starter is the design layer — file structures and guidance. The infrastructure layer (semantic retrieval, mode-aware search, metabolic tracking) is separate tooling that plugs in as your practice matures:
- Sense MCP — Semantic retrieval across your corpus. Makes traces findable. Mode-aware: what surfaces depends on what you're doing.
- Vibe Harness — Metabolic governance. Tracks working modes, pacing, and transition friction. The modes in your boot file start as guidance; Vibe Harness makes them operational.
- Hence — Defeasible logic coordination. Plans that adapt. Agent spawn for scoped tasks. The deliberate end of the three-speed coordination model.
None of these are required. The boot file, traces, and memory work without them. They make the architecture load-bearing at scale.
The architecture coordinates at three speeds, like biological motor control:
| Speed | What | Example |
|---|---|---|
| Hooks | Autonomic reflexes. Run without conscious direction. | Context monitor blocks tool calls when context is full. |
| Skills | Learned motor patterns. Invoked by gesture. | /trace generates a session artifact. /reflect checks for drift. Four included, progressively enhanced. |
| Plans | Deliberate coordination. Formal, multi-step. | A Hence plan that spawns functional agents for parallel work. |
Hooks and skills ship with the starter. Plans come when the work demands coordination across agents or sessions.
- Boot, don't dump. The governance file is a boot sequence, not a knowledge base.
- Function over form. The pattern specifies what each component does, not how it looks.
- Coherence over coordination. Shared meaning persisting across sessions, not just task management.
- Metabolic constraint as governor. The human's nervous system is the rate-limiting constraint.
- Defeasible governance. Some rules bend with good reason. Some never do. Know which is which.
- Stigmergic memory. Sessions leave traces. Future sessions find relevant traces through search.
- Relational infrastructure. Identity and relationship are structural. They carry the collaboration across sessions.
AGPL-3.0. The design patterns are open practice — use them, adapt them, teach them. If you build a network service on this, share your modifications.
Sense MCP and Vibe Harness carry their own licenses (ESL-A). Hence is Apache 2.0.
Published by Mathew Mytka and Kairos. Part of the aiharness.design project.
"Cognition emerges through relationship. The tools we build participate in the fields they measure."