Harrison Halperin

BRIEF.md

role
Standards author & builder
date
2026-02
tags
Standards · Agentic · TypeScript
boundary
Deliberately stops at context shape; compression, storage, and retrieval stay out of scope.

A standard for agent context

An open standard for how AI agents discover, read, and hand off project context, plus schemas and tooling that make it real.

Harrison Halperin

Project brief

Prototype

Problem

Agents repeatedly reread project files and still lose decisions, constraints, and handoff state.

Outcome

An open standard for how AI agents discover, read, and hand off project context, plus the schemas and tooling that make it real.

Evidence

  • Seven optional Markdown sections with glob semantics for scope.
  • Checkpoint and handoff JSON schemas keep structured state portable between tools.

Key decisions

  • Spec layer: Seven optional Markdown sections with glob semantics for scope.
  • Schema layer: Checkpoint and handoff JSON schemas keep structured state portable between tools.
  • Consumer layer: Skills and hooks resolve the active brief without duplicating business logic.
  • Boundary: Deliberately stops at context shape; compression, storage, and retrieval stay out of scope.

the problem

The problem is context drift: agents re-read the same files and still lose the thread.

the spec

I turned informal conventions into a portable spec: seven optional Markdown sections, glob semantics, and JSON Schemas for checkpoints and handoffs. It sits alongside AGENTS.md and MCP rather than replacing them, and deliberately stops short of compression, storage, or retrieval. Agents deserve a real context format is the standards-facing sibling. Compress for agents, not humans is why the handoff shape matters more than prettier prose. It sits in the same family as Modular Orchestration System and ThoughtBuilder.

architecture

BRIEF.md defines how agents discover, read, and hand off project context. The spec feeds reference consumers and session hooks without replacing AGENTS.md or MCP.

Standard to consumers
1BRIEF.md specseven optional sections
2Conventionsbuilt-in defaults
3JSON schemasgatecheckpoint · handoff
4Reference skillscontext manager · bootstrapper
5Session hooksfind · audit at start/end
The spec and schemas sit above reference skills, hooks, and branding surfaces. Each layer reads the same contract.
Session-start resolution
1Session start
2Find briefsearch paths in order
3Manifest checkgate
4Emit contextstdout JSON
5Agent readsinjected context
At session start the hook walks search paths in order, applies built-in conventions on miss, and emits JSON for agent injection.

definitions

Spec layer
Seven optional Markdown sections with glob semantics for scope.
Schema layer
Checkpoint and handoff JSON schemas keep structured state portable between tools.
Consumer layer
Skills and hooks resolve the active brief without duplicating business logic.
Boundary
Deliberately stops at context shape; compression, storage, and retrieval stay out of scope.

conformance

  1. StandardsBRIEF.md is a shared handoff format so discovery survives a fresh agent context.
  2. TypeScriptWhere brief tooling is typed, malformed handoff fields fail before they spread.
  3. SchemasBrief fields are validated so incomplete handoffs fail loud.
  4. AgenticAgents fill structured brief fields; humans own accept/reject of the handoff.
  5. Developer toolsA brief is the inspectable packet between research and implementation.
  6. MCPBrief resources can be exposed through MCP so agents fill a typed handoff packet.
  7. Context engineeringBRIEF.md encodes discovery and handoff shape so agents resume without rediscovering project lore.

references

  1. Modular Orchestration Systemproject
  2. Thoughtbuilderproject
  3. Agents deserve a real context formatwriting
  4. Compress for agents, not for humanswriting
  5. Dual channels and rule layers beat a longer promptwriting

Portfolio graph

Hover nodes · click empty canvas to zoom/pan

Maps how the work here connects. Open the Portfolio graph →

  • Professional
  • Personal
  • Skill
  • Writing