---
id: chunkmap-agent-blackboard
name: ChunkMap Agent Blackboard
version: 1.0.0
tags: [agentic, multi-agent, blackboard, dag, orchestration, state-schema]
related_skills:
  - chunkmap-policy-to-pipeline
  - chunkmap-persuasion-flow
---

# ChunkMap Agent Blackboard

**Purpose:** Provide multi-agent swarms with a **shared semantic schema** (blackboard) and **DAG prompt-trees** so agents do not lose the thread, invent cross-purposes, or diverge from a shared mental model.

## When to use / audience

Use when **two or more agents** must collaborate on a workflow and intermediate state must be auditable and consistent.

**Audience:** agent orchestrators, framework builders, systems engineers.

Pair with [chunkmap-policy-to-pipeline.md](./chunkmap-policy-to-pipeline.md) when agents must evaluate versioned policy chunks.

## Inputs required

| Input | Required | Notes |
|---|---|---|
| Root mission | Yes | One sentence the entire DAG serves |
| Success artifacts | Yes | Named outputs that prove completion |
| Specialist roles | Yes | Agent nodes (keep ≤7 top-level) |
| Source systems / tools | Yes | What each agent may read |
| Hard constraints | Yes | e.g. “no invented SLAs; cite blackboard only” |
| Policy / checklist chunks | Optional | For compliance-style agents |

## Step-by-step procedure (ChunkMaps method)

### 1. Chunk up to the root mission

One ROOT sentence + success set + global constraints:

```text
ROOT: <mission>
Success = { artifact_a, artifact_b, ... }
Constraint = <non-negotiables>
```

### 2. Chunk across into specialist agents

Sibling nodes under ROOT (≤7). Each node is a bounded chunk: mission slice, inputs, tools, write contract, exit criteria.

```text
ROOT
├── A1 <role> - <job>
├── A2 <role> - <job>
└── An <role> - <job>
```

### 3. Define DAG edges (order + data flow)

- Edges encode dependencies; **never cycles**.
- No agent writes before its parents complete.
- Name the **payload chunk** on each edge (e.g. `facts[]`, `flags[]`).

| From | To | Payload chunk |
|---|---|---|
| A1 | A2, A3 | `facts[]` + source IDs |
| … | … | … |

### 4. Publish the shared blackboard (state schema)

This is the swarm’s **single mental model**. All agents read/write only allowed fields.

```text
state = {
  mission: string,
  facts: [{id, claim, source, confidence}],
  flags: [{id, policy, severity, related_facts[]}],
  plan_steps: [{id, owner, day_range, depends_on[]}],
  open_questions: [string],
  status: { A1, A2, A3, ... }
}
```

Customize field names per domain; keep **IDs + provenance** mandatory for claims.

### 5. Chunk down each agent prompt

Per node:

```text
YOU ARE: <role> (node <id>)
READ ONLY: <state paths>
WRITE ONLY: <state paths>
DO NOT: <forbidden inventions>
STEPS:
  1. ...
  2. ...
  3. Exit when <criteria>
```

### 6. Run the DAG; reject illegal writes

Orchestrator rules:

1. Drop writes outside WRITE ONLY paths.
2. Drop claims not backed by allowed sources → force repair chunk: *“Cite fact IDs or move to open_questions.”*
3. Requeue failed nodes; do not let downstream agents consume tainted state.

## Output schema / templates

### Blackboard schema (YAML-friendly)

```yaml
mission: ""
facts:
  - id: F-001
    claim: ""
    source: ""
    confidence: 0.0
flags: []
plan_steps: []
open_questions: []
status:
  A1: pending   # pending | running | done | failed
```

### Node card template

```markdown
## Node <id> - <role>
- Depends on:
- Reads:
- Writes:
- Tools:
- Exit criteria:
- Prompt body:
```

### Edge list

```markdown
| From | To | Payload | Gate |
```

## Worked mini-example: Customer onboarding swarm

**ROOT:** Produce an auditable onboarding pack for Customer X  
**Success:** `{context_brief, compliance_flags, 30-day_plan, handoff_memo}`  
**Constraint:** no invented SLAs; cite only blackboard facts

```text
ROOT
├── A1 Researcher   - extract facts from CRM + kickoff notes
├── A2 Compliance   - map facts to policy checklist
├── A3 Planner      - draft 30-day plan from approved facts
└── A4 Writer       - assemble handoff memo from A1-A3 outputs
```

Edges: A1→A2/A3/A4 (`facts[]`); A2→A3/A4 (`flags[]`); A3→A4 (`plan_steps[]`); A4→ROOT (`handoff_memo`).

**A2 Compliance prompt pattern:** READ `state.facts` only; WRITE `state.flags` + `open_questions`; emit flag or “clear” with cited fact IDs.

**Illegal write example:** A3 invents an SLA not in `facts` → orchestrator drops write and requeues with repair chunk.

## Guardrails / failure modes

| Failure | Fix |
|---|---|
| Chatty free-for-all (no schema) | Freeze blackboard schema before run |
| Cyclic dependencies | Redesign DAG; break cycles with explicit human gate |
| Context ballooning | Per-node READ ONLY subsets; do not load full corpus |
| Silent invention | Reject uncited claims; use open_questions |
| Too many top agents | Merge roles; respect 7±2 |
| Status never updates | Orchestrator owns `status` transitions |

## Related skills / site articles

- Related skill: [chunkmap-policy-to-pipeline.md](./chunkmap-policy-to-pipeline.md) (policy chunks as A2 inputs)
- Related skill: [chunkmap-persuasion-flow.md](./chunkmap-persuasion-flow.md) (human-facing handoff memo narrative)
- Site (TEMP): [agent_orchestrators_chunkmaps.html](../agent_orchestrators_chunkmaps.html), [what_is_a_chunk_map.html](../what_is_a_chunk_map.html), [index.html#agentic-age](../index.html#agentic-age)