Zachary F. Mainen · HAAK · Architecture 19 · March 2026

Agent Coordination

Multiple Claude Code sessions run concurrently across different projects. Each session is encapsulated — no awareness of other sessions, no shared state, no coordination. The human is the only shared…

#Problem

Multiple Claude Code sessions run concurrently across different projects. Each session is encapsulated — no awareness of other sessions, no shared state, no coordination. The human is the only shared context. This creates three failures: (1) duplicated or conflicting work, (2) knowledge trapped in one session that another needs, (3) the human forgetting which session is doing what.

The solution must use existing HAAK infrastructure — no new file types, no databases, no ambient state.

#Design

#Boards

A board is a 00-board.md file in any domain directory. It is the domain's shared memory — timestamped, attributed posts visible to agents with access to that domain. Separate from index.md to preserve index purity (architecture 08 — information serving different functions must live in different containers).

Agent-owned vs project-owned: Boards and working notes are agent artifacts, not project artifacts. A "private notebook" is what an agent does on a board — it is not a research thread. Research threads track ideas; boards track agent state. Do not create project threads for agent-internal concepts.

# Board

- [2026-02-26 11:45] @architect: Schema change — added `trial_type` to sessions table
- [2026-02-26 09:00] @editor: R2 complete for ms-inscription, needs PI review
- [2026-02-26 12:30] @zach: All sessions: new figures go in `fig0N/` subdirectories

Rules. Any domain (any folder with index.md) can have a 00-board.md. Posts are append-only within a session. Each post carries: ISO timestamp, agent attribution (@agent or @zach), message. Archival: when board exceeds 20 posts, oldest posts move to 00-board-archive.md in the same directory. The board is not listed in the index Contents — it is infrastructure, like .claude/, not content.

Ontological grounding. A board post is a material-token within a domain-instance. The board itself is a pattern: the recurring structure of inter-agent communication. Reading a board is a method. Posting to a board is a method. Access to both is governed by policy.

#Permissions (deferred)

The full POSIX-like permission model — agents as users, groups bundling domain + method access, propagation by subsumption — is designed but deferred. The ontological mapping is clean (Correspondence I), but enforcement in Claude Code is advisory, not structural: agents can physically read any file on disk regardless of policy. Real enforcement requires either Agent SDK-level context control or /read skill mediation, both of which add complexity that isn't justified until a concrete harm (e.g., context leakage between confidential reviews) demands it.

Current policy: all boards are public. Any agent can read any 00-board.md. The human (@zach) posts to any board. Agents post to boards in their working domain. This solves the coordination problem (cross-session awareness) without the enforcement problem.

The full permission spec (access levels, agent types, groups, propagation rules, method-level access control) is preserved below for when it's needed.

<details> <summary>Full permission model (not yet active)</summary>

Three permissions per agent per domain: r (read board + contents), w (post to board), x (execute methods). Three agent types: super (root — architect, zach), standard (user — editor, writer, librarian), restricted (guest — reviewer). Groups bundle domain + method access. Propagation by subsumption: parent access grants child access, children can narrow but never widen. Methods also carry group-level access policies — an agent needs both group-level method permission AND domain-level x to run a method in a domain.

</details>

#Registry

The registry maps agents to project assignments and board subscriptions. It lives at .claude/agents/registry.yaml.

agents:
  architect:
    projects: ["**"]           # activates anywhere
    boards: ["**"]             # reads all boards

  editor:
    projects: [projects/**]
    boards: [projects/**, strategy/]

  reviewer:
    projects: [projects/**]
    boards: [projects/**]

  writer:
    projects: [projects/**]
    boards: [projects/**, ontology/, foundations/]

  librarian:
    projects: [projects/**]
    boards: [projects/**, strategy/]

  auditor:
    projects: [patterns/**]
    boards: ["**"]

Project assignment determines which agent identity activates for a given cwd. Board subscriptions determine which 00-board.md files are collected and injected into context on session start. Both use glob patterns resolved relative to the HAAK root.

#Discovery

Agents learn about boards through three mechanisms:

  1. Agent profiles (.claude/agents/*.md): each agent's profile includes an instruction to read 00-board.md in its working domain and parent domains on session start.
  2. /read skill: already navigates the index hierarchy. Extended to surface 00-board.md alongside index.md when entering a directory.
  3. Registry subscriptions: the boards: field in registry.yaml declares which domains' boards an agent should proactively read, beyond its immediate cwd.

The 00- prefix ensures boards sort adjacent to the index in any directory listing. Agents navigating via ls or /read encounter the board naturally — no special discovery mechanism needed.

#Session protocol

On session start:

  1. Match cwd to agent (via registry or description matching)
  2. Resolve agent's board subscriptions from registry
  3. Read 00-board.md files from subscribed domains
  4. Inject board contents into session context (via hook or CLAUDE.md include)

During session:

  • Agent can post to boards in domains where it has w
  • /board post <domain>: <message> appends a timestamped entry
  • /board read [domain] shows boards in accessible scope

On session end:

  • Optionally post a session summary to relevant domain board(s)

#Relation to existing architecture

  • 06_agent-architecture: This extends scoping from confidential/non-confidential binary to a full permission model. The five base agents remain; their access is now formalized.
  • 08_encapsulation: Boards are separated from navigation (last section in index, below Contents/Details). Agent access boundaries prevent context leakage between unrelated domains.
  • 18_agent-governance: The permission model implements the governance framework's policy hierarchy. Groups are policy scopes. The registry is a constitution fragment.
  • Ontology Correspondence I (POSIX): Direct instantiation. Agents are users, groups are groups, domains are directories, permissions propagate by subsumption, the registry is /etc/passwd + /etc/group.

#Open questions

  • Board granularity: Which directories actually get boards in practice? Likely: haak/ root (global announcements), each active project, strategy/. Unlikely: every leaf directory. Let usage determine.
  • Session-to-agent mapping: Automatic (cwd-based via registry) vs. explicit (/agent assume editor)? Top-level sessions in haak/ are probably always the architect. Sessions in project subdirectories could be editor, writer, or reviewer depending on task.
  • Injection mechanism: Session-start hook that reads registry + collects 00-board.md files and prepends to context? Or simpler: agent reads boards on demand via /board read?

architecture · 2026-02-26 · zach + claude

Architecture 19 — Agent Coordination — 2026 — Zachary F. Mainen / HAAK