mirror of
https://github.com/JimLiu/baoyu-skills.git
synced 2026-08-08 01:43:03 +08:00
feat: add baoyu-diagram skill and baoyu-article-illustrator ink-notes style (v1.99.0)
- baoyu-diagram: new skill for generating publication-ready SVG diagrams (flowchart, structural, illustrative) with embedded styles and auto dark-mode - baoyu-article-illustrator: add ink-notes style and mono-ink palette with presets for before/after, manifesto, and framework diagrams
This commit is contained in:
Jim Liu 宝玉
@@ -0,0 +1,38 @@
|
||||
# AI pattern catalog
|
||||
|
||||
Pre-planned diagram starters for recurring multi-agent coordination shapes — research orchestrators, message buses, shared-state stores, agent-with-skills composition. Each file here is a thin wrapper around one specific pattern: a one-line description, the diagram type baoyu prefers for it, the ramp palette that works, a reference mermaid block (industry-standard shorthand you can sanity-check against), and a pre-cooked baoyu SVG plan that saves you a planning pass.
|
||||
|
||||
## How to use this directory
|
||||
|
||||
1. **Check the index below** for a pattern name matching the user's topic. Exact matches are rare — usually the user says *"agents coordinating through a shared channel"* and you recognize *message-bus*, or *"agents building on each other's findings in a store"* and you recognize *shared-state*.
|
||||
2. **If a pattern matches**, open its file and read end-to-end. The mermaid block tells you *what* to draw (structurally), the baoyu SVG plan tells you *how* (coordinates, widths, arrow routing).
|
||||
3. **If no pattern matches**, fall back to the normal Step 4 planning flow in `SKILL.md`. Do not force a near-miss — two coordination patterns that share a surface name often have different topologies (message bus ≠ shared state, even though both put a central element between agents).
|
||||
|
||||
The mermaid reference is **authoritative for structure**, not for rendering. Never emit mermaid as the final output; always convert to a hand-written baoyu SVG using the plan in the same file.
|
||||
|
||||
## Scope
|
||||
|
||||
This directory covers **AI-system topologies**, not generic software patterns. For flowchart / sequence / structural / illustrative / class diagram techniques, stay in the top-level references files. If an AI-system pattern needs a technique that isn't documented in those files yet, add the technique upstream — not here.
|
||||
|
||||
## Index
|
||||
|
||||
| Pattern | Default type | One-line hook |
|
||||
|--------------------------|-----------------|-----------------------------------------------------------------------------------------------------|
|
||||
| [multi-agent-research](multi-agent-research.md) | flowchart | Lead agent + memory sidecar + parallel search subagents (each looping) + citation stage (Anthropic) |
|
||||
| [message-bus](message-bus.md) | structural | N agents coordinate via a central publish/subscribe bar — no direct agent-to-agent edges |
|
||||
| [shared-state](shared-state.md) | structural | N peer agents read/write a central store — no orchestrator, findings immediately visible to all |
|
||||
| [agent-skills](agent-skills.md) | structural | Agent loop + runtime + MCP servers (left) + skills library on filesystem (right) — composition view |
|
||||
| [contextual-retrieval](contextual-retrieval.md) | flowchart | Contextualizer LLM prepends 50–100 tokens to each chunk → dual-track (embedding + BM25) + rank fusion |
|
||||
|
||||
## Adding a new pattern
|
||||
|
||||
Keep each file under ~80 lines. A pattern file has six sections in this order:
|
||||
|
||||
1. **Name + 1-line description**
|
||||
2. **Default diagram type** — plus when to pick an alternate type
|
||||
3. **Palette** — which ramps, tied to which roles
|
||||
4. **Sub-pattern** — the specific section in a top-level reference file that does the heavy lifting
|
||||
5. **Mermaid reference** — the canonical industry-standard sketch, in a ` ```mermaid` block
|
||||
6. **Baoyu SVG plan** — node list with widths, arrow list, viewBox dimensions, any gotchas
|
||||
|
||||
When you add a new pattern, update this README's index table in the same commit. Do not create orphan files — if you can't write a one-line hook for the index, the pattern isn't well-defined yet.
|
||||
@@ -0,0 +1,92 @@
|
||||
# Agent with skills
|
||||
|
||||
**One-line description.** The architectural snapshot of a general-purpose agent composed of four layers — **agent loop** (reasoning), **agent runtime** (code + filesystem), **MCP servers** (outbound connectors to external tools and data), and a **skills library** (local, progressively-disclosed domain expertise on the filesystem). This is the "Skills: the complete picture" diagram from Anthropic's skills blog post — the shape that explains *why you stop building specialized agents and start shipping skills to one general agent*. It is a **system composition** diagram, not a workflow: it answers "what the agent is", not "what it does next".
|
||||
|
||||
## Default diagram type
|
||||
|
||||
**Structural — central hub with bilateral satellite groups.** Single agent box in the middle with a visible interior loop glyph; MCP servers stacked vertically on the **left**; skills stacked vertically inside a **filesystem container** on the **right**. The left/right split is the point: *left is network-reachable tools, right is on-disk expertise*.
|
||||
|
||||
Alternate types:
|
||||
- **Before/after poster flowchart** (two stacked frames, per `flowchart.md` → "Poster flowchart") when illustrating the evolution from specialized-per-domain agents → general agent + skills. This is Anthropic's Figure 1 / Figure 2 shape.
|
||||
- **Flowchart with a loop container** when the user wants to show activation order (loop → read skill → call MCP → write file → loop). The structural snapshot loses sequencing; the flowchart gains it.
|
||||
|
||||
## Palette
|
||||
|
||||
Three role ramps + gray. This is a structural diagram where the two satellite groups must be visually distinct:
|
||||
|
||||
- **`c-gray`** — filesystem container, title bar, legend, arrow labels.
|
||||
- **`c-teal`** — agent (central hub). Teal anchors the LLM/reasoning role.
|
||||
- **`c-purple`** — MCP servers. Shared across all three (homogeneous satellite group — instances of one role do not get distinct colors).
|
||||
- **`c-coral`** — skills. Shared across all three; coral reads as Anthropic's own skills brand-orange and sits opposite the MCP group.
|
||||
|
||||
This is a **category coloring**, not a rainbow: one ramp per satellite *group*, not per satellite. The structural radial-star rule in `structural.md` ("satellites stay neutral gray") is deliberately overridden here because we have **two distinct kinds of satellite** that the reader must tell apart at a glance.
|
||||
|
||||
Legend is required.
|
||||
|
||||
## Sub-pattern
|
||||
|
||||
`structural.md` → **Radial star topology** as the base (hub with satellites, bidirectional arrows), extended to an **asymmetric two-group** variant: left group is a loose stack (no container), right group is wrapped in a `structural.md` → **Container box** to show the filesystem boundary. The agent's interior loop uses `glyphs.md` → **terminal-icon** plus a hand-drawn circular arrow pair around it (the "reason · act" cycle) — this is what distinguishes the agent visually from its satellites.
|
||||
|
||||
## Mermaid reference
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph MCP
|
||||
M1[MCP server 1]
|
||||
M2[MCP server 2]
|
||||
M3[MCP server 3]
|
||||
end
|
||||
A[Agent<br/>reason · runtime]
|
||||
subgraph Filesystem
|
||||
S1[Skill A]
|
||||
S2[Skill B]
|
||||
S3[Skill C]
|
||||
end
|
||||
M1 <--> A
|
||||
M2 <--> A
|
||||
M3 <--> A
|
||||
A <--> S1
|
||||
A <--> S2
|
||||
A <--> S3
|
||||
A -. reason · act loop .-> A
|
||||
```
|
||||
|
||||
Two subgraphs flanking a central hub plus a self-loop on the hub is the defining shape. Drop either subgraph and the pattern collapses into something else — a plain tool-calling loop (if you drop skills) or a read-only retrieval shape (if you drop MCP).
|
||||
|
||||
## Baoyu SVG plan
|
||||
|
||||
Central agent with an interior loop glyph; three MCP servers stacked on the left; three skills stacked inside a filesystem container on the right.
|
||||
|
||||
- **viewBox**: `0 0 820 460`
|
||||
- **Agent (hub)** — `c-teal`, `x=310 y=110 w=200 h=240`, large central box:
|
||||
- Title *Agent* at `(410, 140)` class `th`.
|
||||
- Interior loop glyph centered at `(410, 230)`: a `terminal-icon` at `(398, 218)` (24×24 from `glyphs.md`), with two curved arrows forming a circle around it — `path d="M 370 230 A 40 40 0 1 1 450 230" class="arr" marker-end="url(#arrow)"` plus the mirror arc below. This is the reason-act loop made visible.
|
||||
- Subtitle *reason · runtime* at `(410, 310)` class `ts`.
|
||||
- **MCP server stack** (3 boxes, `c-purple`, single-line title, same size):
|
||||
- *MCP server 1*, `x=60 y=140 w=170 h=52`.
|
||||
- *MCP server 2*, `x=60 y=210 w=170 h=52`.
|
||||
- *MCP server 3*, `x=60 y=280 w=170 h=52`.
|
||||
- **Filesystem container** — `rect x=570 y=100 w=220 h=260 rx=16` class `box`, title *Filesystem* at `(680, 128)` class `th`, centered.
|
||||
- **Skills stack** inside the filesystem (3 boxes, `c-coral`, single-line title, same size):
|
||||
- *Skill A*, `x=600 y=150 w=160 h=52`.
|
||||
- *Skill B*, `x=600 y=216 w=160 h=52`.
|
||||
- *Skill C*, `x=600 y=282 w=160 h=52`.
|
||||
|
||||
**Arrow plan.** Six bidirectional pairs, three per side. Each pair uses two single-headed arrows offset 8px perpendicular to direction (same rule as `structural.md` → "Radial star → Arrow pairs"):
|
||||
|
||||
- MCP server *n* ↔ Agent: short horizontal channel from `(230, y_center)` to `(310, y_center)` and back, where `y_center ∈ {166, 236, 306}`. Both solid `arr`.
|
||||
- Agent ↔ Skill *n*: short horizontal channel from `(510, y_center)` to `(600, y_center)` and back, where `y_center ∈ {176, 242, 308}`. Arrows cross the filesystem container edge — that crossing is semantically important and must not be hidden.
|
||||
|
||||
No external self-loop arc on the agent — the interior loop glyph (`terminal-icon` + circular arrows) already carries that meaning, and an exterior arc would collide with the MCP/skills channels.
|
||||
|
||||
**Legend** (bottom, required):
|
||||
|
||||
```
|
||||
[■] Agent [■] MCP server [■] Skill [▭] Filesystem [↔] bidirectional channel
|
||||
```
|
||||
|
||||
**Gotchas.**
|
||||
- Never color the 3 MCP servers differently from each other, nor the 3 skills. Each group is a homogeneous tier; per-item coloring turns an architecture diagram into a role diagram.
|
||||
- Keep the filesystem container around the skills. Dropping it makes skills look like peers of MCP servers and erases the "local, progressively disclosed from disk" property that is the whole reason skills are not MCP servers.
|
||||
- Convention: **MCP on the left, skills on the right**, matching Anthropic's own materials. Flipping the sides loses a free point of recognition.
|
||||
- If the user wants to show **progressive disclosure** (metadata → SKILL.md → references/), add a nested three-tier rect *inside each skill box* — that is an extension of this pattern, not an alternate type.
|
||||
@@ -0,0 +1,98 @@
|
||||
# Contextual retrieval
|
||||
|
||||
**One-line description.** Anthropic's preprocessing recipe for RAG: before chunks are embedded and indexed, an LLM (the *contextualizer*) reads the whole document together with each chunk and emits 50–100 tokens of situating context that gets prepended to the chunk. The contextualized chunk then feeds **both** a semantic index (embedding model → vector DB) and a lexical index (TF-IDF → BM25). At runtime the query hits both indices, results merge through rank fusion, and the top-K chunks go to the generative model. The diagram's job is to show the contextualizer as the distinctive new step and the dual-track preprocessing it feeds.
|
||||
|
||||
## Default diagram type
|
||||
|
||||
**Flowchart (poster style) with two stacked phases.** The pattern has a name, a clear preprocessing / runtime split, a fan-out into parallel tracks, and a distinctive new step — that's poster flowchart territory. A flat linear chart would smear the two phases and hide what's new. Stack the phases vertically with eyebrow dividers; each phase reads left-to-right.
|
||||
|
||||
Alternate types:
|
||||
- **Structural — subsystem containers side by side** when contrasting contextual retrieval against plain RAG (two siblings, each a mini pipeline). See `structural.md` → "Rich interior for subsystem containers".
|
||||
- **Preprocessing-only flowchart** when the runtime story isn't needed — drop phase 2 and end at the two indices.
|
||||
|
||||
## Palette
|
||||
|
||||
Three accent ramps plus gray, under the poster-flowchart 4-ramp exception (ramps encode role *categories*, not sequence):
|
||||
|
||||
- **`c-gray`** — corpus, query, rank fusion, top-K chunks, response. Neutral data / IO.
|
||||
- **`c-purple`** — Claude in both its roles: contextualizer and generative model. One ramp for both anchors the "same Claude, two prompts" story without adding a fourth color.
|
||||
- **`c-teal`** — semantic track (embedding model + vector DB).
|
||||
- **`c-amber`** — lexical track (TF-IDF + BM25 index).
|
||||
|
||||
Do **not** color the contextualizer and generative model differently — doing so implies different models or different roles, but the whole point is the same Claude doing both jobs.
|
||||
|
||||
## Sub-pattern
|
||||
|
||||
`flowchart.md` → **Poster flowchart pattern** (eyebrow-divided phases, ≤4 ramps for role categories) + **Fan-out + aggregator (simple mode)** applied twice: the contextualizer splits into two tracks that never reconverge in phase 1, and query + both indices converge at rank fusion in phase 2.
|
||||
|
||||
## Mermaid reference
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph Preprocessing
|
||||
C[Corpus] -- chunks --> CTX[Contextualizer · Claude]
|
||||
CTX -- context + chunk --> EM[Embedding model]
|
||||
CTX -- context + chunk --> TF[TF-IDF]
|
||||
EM --> VDB[(Vector DB)]
|
||||
TF --> BM[(BM25 index)]
|
||||
end
|
||||
subgraph Runtime
|
||||
Q[User query] --> RF[Rank fusion]
|
||||
VDB --> RF
|
||||
BM --> RF
|
||||
RF --> TK[Top-K chunks] --> GM[Generative model · Claude] --> R[Response]
|
||||
end
|
||||
```
|
||||
|
||||
Defining edges: `CTX --> EM` *and* `CTX --> TF` (the contextualized chunk goes to both tracks) plus `VDB --> RF` *and* `BM --> RF` (both indices feed fusion). Drop either pair and the diagram collapses into plain RAG or embedding-only retrieval.
|
||||
|
||||
## Baoyu SVG plan
|
||||
|
||||
Two stacked phases with eyebrow labels and a thin horizontal divider between them.
|
||||
|
||||
- **viewBox**: `0 0 680 540`
|
||||
- **Phase 1 eyebrow** — *Preprocessing · Runs once per corpus update* at `(40, 50)`, class `eyebrow`.
|
||||
|
||||
Phase 1 interior:
|
||||
- **Corpus** — `c-gray`, `x=40 y=80 w=100 h=56`, two-line (*Corpus*, *Documents*).
|
||||
- **Contextualizer** — `c-purple`, `x=180 y=72 w=260 h=72`, multi-line (*Contextualizer*, *Claude*, *50–100 tokens per chunk*). Visibly the largest box — it's the pattern's signature step.
|
||||
- **Embedding model** — `c-teal`, `x=140 y=180 w=160 h=48`, single-line.
|
||||
- **TF-IDF** — `c-amber`, `x=380 y=180 w=160 h=48`, single-line.
|
||||
- **Vector DB** — `c-teal`, `x=140 y=260 w=160 h=56`, two-line (*Vector DB*, *Semantic index*).
|
||||
- **BM25 index** — `c-amber`, `x=380 y=260 w=160 h=56`, two-line (*BM25 index*, *Lexical index*).
|
||||
|
||||
**Phase 1 arrows:**
|
||||
- *Corpus → Contextualizer*: `(140, 108) → (180, 108)`, label *chunks* at `(160, 102)`.
|
||||
- *Contextualizer → Embedding model*: L-bend `(260, 144) → (260, 160) → (220, 160) → (220, 180)`, label *context + chunk* at `(170, 164)` `text-anchor="end"`.
|
||||
- *Contextualizer → TF-IDF*: L-bend `(360, 144) → (360, 160) → (460, 160) → (460, 180)`, label *context + chunk* at `(470, 164)` `text-anchor="start"`. (Both arrows labeled — the reader must see that *both* tracks receive the contextualized chunk.)
|
||||
- *Embedding model → Vector DB*: straight vertical `(220, 228) → (220, 260)`.
|
||||
- *TF-IDF → BM25 index*: straight vertical `(460, 228) → (460, 260)`.
|
||||
|
||||
- **Phase divider** — dashed line `x1=40 y1=340 x2=640 y2=340`, class `arr-alt`.
|
||||
- **Phase 2 eyebrow** — *Runtime · Per user query* at `(40, 362)`, class `eyebrow`.
|
||||
|
||||
Phase 2 interior (single horizontal row at y=400–456):
|
||||
- *User query* `c-gray` `x=40 w=100`, *Rank fusion* `c-gray` `x=160 w=100`, *Top-K chunks* `c-gray` `x=280 w=100` (two-line with subtitle *Top 20*), *Generative model* `c-purple` `x=400 w=140` (two-line with subtitle *Claude*), *Response* `c-gray` `x=560 w=80`. All `y=400 h=56`.
|
||||
|
||||
**Phase 2 arrows** (straight horizontal, 20px gaps between boxes at y=428): query→fusion, fusion→top-K, top-K→generator, generator→response.
|
||||
|
||||
**Cross-phase arrows** (indices into rank fusion):
|
||||
- *Vector DB → Rank fusion*: vertical drop `(200, 316) → (200, 400)` — lands inside rank fusion's top edge (x=160–260).
|
||||
- *BM25 index → Rank fusion*: L-bend `(460, 316) → (460, 372) → (220, 372) → (220, 400)`. The 20px x-offset from the Vector DB arrow keeps the two inbound arrows from stacking.
|
||||
|
||||
Both cross-phase arrows are solid `.arr` — they're the main data flow, nothing alternate.
|
||||
|
||||
**Legend** (bottom, required — 3 accent ramps encode category):
|
||||
|
||||
```
|
||||
[■] Claude (contextualizer + generator) [■] Semantic track [■] Lexical track
|
||||
```
|
||||
|
||||
Place at `y=510`, centered at `x=340`.
|
||||
|
||||
**Gotchas.**
|
||||
- Both tracks must show they receive the *contextualized* chunk — label both outgoing arrows from the contextualizer. If only one is labeled, readers assume the other track still uses raw chunks.
|
||||
- Do not draw the contextualizer as a self-loop on the Corpus. It's a distinct LLM step that runs once per chunk with whole doc + chunk as input, conceptually closer to an orchestrator than an inline transform.
|
||||
- Keep rank fusion gray, not amber — it merges two tracks but it's a structural aggregator, not an accent role. Giving it amber visually absorbs it into the lexical track.
|
||||
|
||||
**Reranker variant.** The reranking extension inserts a **reranker** box between *Rank fusion* and *Top-K chunks*. Insert `Reranker` at `x=280 y=400 w=120 h=56` (shift Top-K, generator, response right by 140 and widen the viewBox to 820). Annotate the reranker's input arrow with *top 150* and its output with *top 20* — the winnowing ratio is the whole point.
|
||||
@@ -0,0 +1,73 @@
|
||||
# Message bus
|
||||
|
||||
**One-line description.** N agents coordinate through a shared publish/subscribe channel rather than talking to each other directly. Each agent subscribes to the topics it cares about and publishes events others may handle. Unlike orchestrator-subagent (central router) or shared-state (central store), the bus carries *events in flight* — agents react to what's happening, not to what's been accumulated. Canonical use cases: event-driven pipelines, security-ops triage → investigation → response, growing agent ecosystems where new capabilities plug in without rewiring.
|
||||
|
||||
## Default diagram type
|
||||
|
||||
**Structural — bus topology.** The defining visual is a central horizontal bar with agents fanning out above and below, each linked by a pair of offset arrows (publish down, subscribe up). A flowchart would force one specific event sequence, but the whole point of a bus is that the workflow emerges from events; a structural diagram shows the coordination shape without committing to a single path.
|
||||
|
||||
Alternate types:
|
||||
- **Sequence** when the user wants to show one specific event cascade (alert arrives → triage classifies → network agent investigates → response agent acts) with explicit ordering. Use 4–5 lifelines, not the bus geometry.
|
||||
- **Flowchart** only if the pipeline really is fixed, in which case it's not a message bus — it's just a linear workflow.
|
||||
|
||||
## Palette
|
||||
|
||||
- **`c-gray`** — the event source / external input (the thing that only publishes, never subscribes). Neutral because it's outside the coordinated agent set.
|
||||
- **`c-teal`** — the agent role for all subscribed agents. One shared ramp because every agent on the bus is a peer; coloring them differently implies a hierarchy that the pattern explicitly rejects.
|
||||
- **`c-amber`** — the bus bar itself. Amber is the convention for "the shared channel everyone looks at" per `structural.md` → "Bus topology sub-pattern".
|
||||
|
||||
Do **not** rainbow the agents by role (network / identity / response / enrichment → four different ramps). The reader should feel the agents are interchangeable peers that differ only in what topics they subscribe to, not in what kind of thing they are.
|
||||
|
||||
## Sub-pattern
|
||||
|
||||
`structural.md` → **Bus topology sub-pattern** + `glyphs.md` → **Publish/subscribe arrow pair**. This pattern is the flagship use case for both; the bus topology section is written with this diagram in mind and `layout-math.md` → "Bus topology geometry" has the fixed coordinates.
|
||||
|
||||
## Mermaid reference
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
S[Alert source] -- publish --> B[[Message bus]]
|
||||
B -- subscribe --> T[Triage agent]
|
||||
T -- publish --> B
|
||||
B -- subscribe --> E[Enrichment agent]
|
||||
E -- publish --> B
|
||||
B -- subscribe --> N[Network agent]
|
||||
B -- subscribe --> I[Identity agent]
|
||||
B -- subscribe --> R[Response agent]
|
||||
```
|
||||
|
||||
The `[[bus]]` notation stands in for a central bar — mermaid can't draw the real geometry. What matters structurally is that every agent talks only to the bus, never agent-to-agent, and that most agents both publish *and* subscribe (the source is the exception).
|
||||
|
||||
## Baoyu SVG plan
|
||||
|
||||
Bus bar centered horizontally; 3 agents on top, 3 agents on bottom. Uses the Anthropic security-ops example labels verbatim — swap them for the user's domain when adapting.
|
||||
|
||||
- **viewBox**: `0 0 680 500`
|
||||
- **Bus bar** — `c-amber`, `x=40 y=280 w=600 h=40 rx=20`. Label *Message bus (publish/subscribe)* at `(340, 304)`, class `th`, centered.
|
||||
- **Top row** (3 boxes, centers at `x = 170, 340, 510`, `w=140 h=60`, `y=80`, two-line):
|
||||
- *Alert source*, **`c-gray`**, subtitle *External events* — the only pure publisher. Mark it gray to distance it from the coordinated agent set.
|
||||
- *Triage agent*, `c-teal`, subtitle *Classifies severity*.
|
||||
- *Enrichment agent*, `c-teal`, subtitle *Gathers context*.
|
||||
- **Bottom row** (same centers, `y=400`, `h=60`):
|
||||
- *Network agent*, `c-teal`, subtitle *Investigates traffic*.
|
||||
- *Identity agent*, `c-teal`, subtitle *Checks credentials*.
|
||||
- *Response agent*, `c-teal`, subtitle *Triggers actions*.
|
||||
|
||||
**Publish/subscribe arrow pairs** (use the glyph template verbatim, 8px offset):
|
||||
|
||||
- For each agent centered at `agent_cx`, with top agents at `agent_y_bottom=140` and the bus top at `bar_y_top=280`, draw two vertical lines:
|
||||
- Publish: `(agent_cx − 8, 140) → (agent_cx − 8, 280)` with arrowhead.
|
||||
- Subscribe: `(agent_cx + 8, 280) → (agent_cx + 8, 140)` with arrowhead.
|
||||
- For bottom agents, `agent_y_top=400`, `bar_y_bottom=320`, mirror: Publish goes down from agent to bus, Subscribe goes up from bus to agent. (Yes — publish on a bottom agent still goes *out of* the agent toward the bus, which is visually upward.)
|
||||
- **Gotcha — Alert source exception.** Alert source is a pure publisher; draw only its Publish arrow (`(162, 140) → (162, 280)`) and omit the Subscribe return. Do *not* draw a subscribe arrow with no label, and do not put a "(source)" parenthetical in the subtitle — the gray ramp + missing return arrow is the signal.
|
||||
- **Labels.** Only label the Publish/Subscribe arrows for one representative agent (e.g., Triage), not all six. With six pairs on one diagram, labeling every pair becomes text soup — a single labeled example plus the legend below is enough.
|
||||
|
||||
**Legend.** Required because the two arrow directions encode distinct semantics and the color-off source agent needs a key:
|
||||
|
||||
```
|
||||
[↓] Publish [↑] Subscribe [■] Event source [■] Subscribed agent [■] Bus
|
||||
```
|
||||
|
||||
Place at `y=480`, `text-anchor="middle"` at `x=340`.
|
||||
|
||||
**When to drop to 2+2 or go up to 4+4.** The 3+3 layout is the sweet spot. With 2 agents per row use `w=180` centered at `x=180, 500`. With 4 per row use `w=110` centered at `x=120, 260, 420, 560` and drop the Publish/Subscribe *labels* entirely — four pairs plus labels per row is too dense. Beyond 8 total agents, the diagram is telling you the ecosystem has outgrown a single-canvas structural view; consider grouping agents by topic or splitting into two diagrams.
|
||||
@@ -0,0 +1,84 @@
|
||||
# Multi-agent research
|
||||
|
||||
**One-line description.** A lead agent plans a research task, persists its plan to a memory sidecar, spawns a row of parallel search subagents (each running its own search-and-think loop over a different aspect of the question), synthesizes their findings, then hands the synthesized draft to a dedicated citation subagent that attributes sources before the final report goes back to the user. This is Anthropic's Research-feature shape. The parts that distinguish it from a plain orchestrator fan-out are the **memory sidecar**, the **per-subagent iteration loop**, and the **post-processing citation stage**.
|
||||
|
||||
## Default diagram type
|
||||
|
||||
**Structural flowchart — central orchestrator with two flanking peers plus a subagent row.** The topology has one big star (the lead agent) with a memory store on one side and a citation subagent on the other, and a row of interchangeable search subagents underneath. A plain fan-out misses memory; a vertical queue-backed worker pool misses the pre/post peers. Draw the lead agent large and central, flank it with memory + citations, and put search subagents in a horizontal row below.
|
||||
|
||||
Alternate types:
|
||||
- **Sequence** when the user wants to show turn order — `LeadResearcher → Memory (save plan) → Subagent1/2 (parallel dispatch) → LeadResearcher (synthesize) → CitationAgent → User`. This is the shape of the process diagram in Anthropic's own post.
|
||||
|
||||
## Palette
|
||||
|
||||
Four role ramps (at the `design-system.md` limit for multi-agent diagrams):
|
||||
|
||||
- **`c-gray`** — user box, final report, structural labels.
|
||||
- **`c-teal`** — lead agent / orchestrator. The primary role anchors the strongest color.
|
||||
- **`c-purple`** — search subagents, **all the same color**. Instances of one role share a ramp; they are interchangeable workers, not distinct actors.
|
||||
- **`c-coral`** — citation subagent. Distinct from the search pool because it is a different specialist running at a different stage.
|
||||
- **`c-amber`** — memory store. Amber is the standing convention for a retriever/store sidecar, which also prevents readers from mistaking memory for a third agent role.
|
||||
|
||||
Legend is required — three distinct non-gray role ramps plus the store color.
|
||||
|
||||
## Sub-pattern
|
||||
|
||||
`flowchart.md` → **Fan-out + aggregator (simple mode)** for the lead ↔ subagents channel, plus `flowchart.md` → **Self-loops** (borrowed from the state-machine section) on each search subagent to show its internal search/think iteration. The flanking peers (memory, citation) are **bidirectional satellites** off the lead agent — not part of the fan-out.
|
||||
|
||||
## Mermaid reference
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
U[User query] --> L[Lead agent<br/>orchestrator]
|
||||
L <--> M[(Memory<br/>plan + context)]
|
||||
L <--> C[Citation subagent]
|
||||
L --> S1[Search subagent A]
|
||||
L --> S2[Search subagent B]
|
||||
L --> S3[Search subagent C]
|
||||
S1 --> L
|
||||
S2 --> L
|
||||
S3 --> L
|
||||
S1 -. search + think .-> S1
|
||||
S2 -. search + think .-> S2
|
||||
S3 -. search + think .-> S3
|
||||
L --> R[Final report]
|
||||
R --> U
|
||||
```
|
||||
|
||||
The distinctive edges vs. a plain orchestrator fan-out: the bidirectional `L <--> M` sidecar, the `L <--> C` post-processor, and the three self-loops on the search subagents.
|
||||
|
||||
## Baoyu SVG plan
|
||||
|
||||
Central lead agent with two flanking peers on the top row and three parallel search subagents in a row below. User box on the far left.
|
||||
|
||||
- **viewBox**: `0 0 820 460`
|
||||
- **User** — `c-gray`, `x=30 y=150 w=120 h=64`, two-line (*User*, *Submits query*).
|
||||
- **Lead agent** — `c-teal`, `x=310 y=90 w=260 h=180`, multi-line block:
|
||||
- Title *Lead agent* at `(440, 120)` class `th`.
|
||||
- Subtitle *(orchestrator)* at `(440, 140)` class `ts`.
|
||||
- Tool stack at y=178, 198, 218, 238, class `ts`, centered: *Tools:*, *search · MCP · memory*, *run_subagent*, *complete_task*.
|
||||
- **Citations subagent** — `c-coral`, `x=170 y=156 w=120 h=60`, two-line (*Citations*, *subagent*).
|
||||
- **Memory** — `c-amber`, `x=590 y=156 w=200 h=60`, two-line (*Memory*, *plan + context*).
|
||||
- **Search subagent row** (3 workers, all `c-purple`, same size):
|
||||
- *Search subagent A*, `x=200 y=340 w=160 h=64`, two-line (*Search subagent*, *Aspect A*).
|
||||
- *Search subagent B*, `x=390 y=340 w=160 h=64`, two-line (*Search subagent*, *Aspect B*).
|
||||
- *Search subagent C*, `x=580 y=340 w=160 h=64`, two-line (*Search subagent*, *Aspect C*).
|
||||
|
||||
**Arrow plan.**
|
||||
- User ↔ Lead — stacked request/response pair: `user → lead` solid `arr` `M 150 174 L 310 174` labeled *query*; `lead → user` dashed `arr-alt` `M 310 198 L 150 198` labeled *final report*.
|
||||
- Lead ↔ Citations — short bidirectional pair on lead's left edge: `M 290 180 L 310 180` (in), `M 310 204 L 290 204` (out). Both solid `arr`.
|
||||
- Lead ↔ Memory — matching pair on lead's right edge: `M 570 180 L 590 180`, `M 590 204 L 570 204`.
|
||||
- Lead → each subagent — vertical L-bends from lead's bottom edge `(y=270)` via a shared channel at `y=305`. Dispatch arrows anchor on lead at `(360, 270)`, `(470, 270)`, `(520, 270)` and land at each subagent's top-center `(280, 340)`, `(470, 340)`, `(660, 340)`. Middle arrow is straight; outer two L-bend through the channel.
|
||||
- Subagent → Lead — matching return arrows offset 16px to the right of each dispatch arrow, using `arr-alt` to mark the return.
|
||||
- **Self-loop on each search subagent** — per `flowchart.md` → Self-loops, a short arc off the right edge: `M {x+w} {y+16} C {x+w+24} {y+8}, {x+w+24} {y+h-8}, {x+w} {y+h-16}` class `arr`, with a `ts` label *search + think* at `({x+w+28}, {y+h/2})`. Repeat for all three subagents. This is the key visual that distinguishes research subagents from plain workers.
|
||||
|
||||
**Legend** (bottom, required):
|
||||
|
||||
```
|
||||
[■] Lead agent [■] Search subagent [■] Citation subagent [■] Memory [──] dispatch [- -] return
|
||||
```
|
||||
|
||||
**Gotchas.**
|
||||
- Do not color the 3 search subagents differently — they are one pool, not three roles. Rainbow-ing them turns a homogeneous worker pool into a role fan-out and misrepresents the pattern.
|
||||
- Keep memory amber even though it is a peer of lead — the store convention keeps readers from reading it as a third agent.
|
||||
- The citation subagent runs *at the end* logically, but the architecture view draws it as a peer of the lead agent (not a downstream successor), matching Anthropic's own diagram. If the user asks for the turn-order view instead, switch to the sequence alternate.
|
||||
@@ -0,0 +1,64 @@
|
||||
# Shared state
|
||||
|
||||
**One-line description.** N peer agents coordinate by reading and writing a persistent shared store — database, filesystem, document — with no central orchestrator, router, or message bus between them. Each agent checks the store for relevant findings, acts on what it sees, and writes its own contributions back. Findings are immediately visible to every other agent; the store becomes an evolving knowledge base. Canonical use case: a research synthesis system where an academic-literature agent, industry-reports agent, patent agent, and news agent all build on each other's discoveries in real time.
|
||||
|
||||
## Default diagram type
|
||||
|
||||
**Structural — radial star.** The point of the pattern is *no central coordinator* — the hub is a passive store, not an active router. A radial star diagram puts the store in the center and the agents around it, with bidirectional read/write channels on every spoke. A flowchart would smuggle in an implied order; a bus topology would suggest events in flight rather than accumulated state.
|
||||
|
||||
Alternate types:
|
||||
- **Illustrative** when the user wants a *cross-section* metaphor — concentric layers, store as a well, agents as drawers dipping in. Rarely the right call for production docs but occasionally useful for teaching the intuition.
|
||||
- **Structural (subsystem)** when the user is contrasting shared-state with a different pattern (agent teams, message bus) — in that case use the two-sibling container layout and make this pattern's side a mini radial star inside the right container. See `structural.md` → "Rich interior for subsystem containers".
|
||||
|
||||
## Palette
|
||||
|
||||
- **`c-amber`** — the shared state hub. This is the one place in the diagram that "everybody is looking at," and amber is the documented convention for shared-state hubs per `structural.md` → "Radial star topology sub-pattern".
|
||||
- **`c-gray`** — the peripheral satellite agents. They are peers doing the same *kind* of work (read + write), and the pattern's whole argument is that they're interchangeable. Giving each satellite its own ramp is rainbow coloring that implies a hierarchy that doesn't exist.
|
||||
- **`c-teal`** — acceptable *instead of* gray for all satellites together (single ramp for "agent peer"), when the diagram needs to distinguish the agents from other gray scaffolding elsewhere on the canvas. Never mix gray and teal satellites in the same diagram — it looks like two tiers.
|
||||
|
||||
Never promote one satellite to a different ramp "to show the primary agent". If one agent really is primary, the topology isn't radial star — it's orchestrator-subagent or agent-teams.
|
||||
|
||||
## Sub-pattern
|
||||
|
||||
`structural.md` → **Radial star topology sub-pattern**. The central hub carries a `doc-icon` glyph from `glyphs.md` → "Document & terminal icons" to signal it's a store (not just an abstract coordinator). `layout-math.md` → "Radial star geometry (3 / 4 / 5 / 6 satellites)" has the fixed coordinate table for N=3 through N=6.
|
||||
|
||||
## Mermaid reference
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[Academic agent] <--> S[(Shared state store)]
|
||||
I[Industry agent] <--> S
|
||||
P[Patent agent] <--> S
|
||||
N[News agent] <--> S
|
||||
```
|
||||
|
||||
The defining shape is the bidirectional double-headed arrow between every satellite and the store, with *no arrows between satellites*. Any agent-to-agent edge turns the topology into a mesh and is a signal to switch patterns.
|
||||
|
||||
## Baoyu SVG plan
|
||||
|
||||
N=4 radial star with a doc-icon hub. Uses the Anthropic research-synthesis example labels verbatim — swap them for the user's domain.
|
||||
|
||||
- **viewBox**: `0 0 680 560`
|
||||
- **Hub (shared state store)** — `c-amber`, `x=260 y=280 w=160 h=80 rx=10`.
|
||||
- Title *Shared state* at `(340, 302)`, `th`, centered.
|
||||
- Subtitle *Database / filesystem / doc* at `(340, 320)`, `ts`, centered.
|
||||
- `doc-icon` glyph at `translate(328, 328)` (bottom-center of hub rect). Copy the 5-line doc-icon path from `structural.md` → "Hub content" verbatim — it's the worked example for exactly this diagram.
|
||||
- **Satellites** (4, all `c-gray`, `w=160 h=60`, two-line):
|
||||
- *Academic agent*, `x=60 y=120`, subtitle *Literature search*.
|
||||
- *Industry agent*, `x=460 y=120`, subtitle *Market reports*.
|
||||
- *Patent agent*, `x=60 y=460`, subtitle *Patent filings*.
|
||||
- *News agent*, `x=460 y=460`, subtitle *Current coverage*.
|
||||
|
||||
**Bidirectional arrow pairs** (use the pre-computed N=4 endpoints from `layout-math.md` → "Radial star geometry"):
|
||||
|
||||
- TL Academic: outbound `(224, 176) → (264, 276)`, inbound offset perpendicular by 8.
|
||||
- TR Industry: outbound `(456, 176) → (416, 276)`, inbound offset.
|
||||
- BL Patent: outbound `(224, 464) → (264, 364)`, inbound offset.
|
||||
- BR News: outbound `(456, 464) → (416, 364)`, inbound offset.
|
||||
- Label each pair with a single `ts` *Read / write* next to the satellite end (not between the two offset lines — the 8px gap is too narrow). For the top satellites, place the label just below the satellite box at `y ≈ 198`. For the bottom satellites, just above at `y ≈ 448`.
|
||||
|
||||
**Centered banner for termination rule.** Shared-state systems cycle indefinitely without an explicit termination condition. Drop a small centered `ts` caption at the top of the canvas — `y=60`, `text-anchor="middle"` at `x=340` — naming the rule the system uses: *Until convergence (no new findings for N cycles)*, *Until time budget exhausted*, or *Until a designated terminator agent signals done*. This is not ornamental — a shared-state diagram without a termination line misrepresents the pattern. See the blog's "reactive loops" failure mode.
|
||||
|
||||
**Legend.** Not needed — the single accent color on the hub and the shared gray on satellites self-document. If you used `c-teal` satellites instead of gray, still no legend: one ramp on all peers means "they're all the same role", which is the whole message.
|
||||
|
||||
**When to use N≠4.** Stick to N=4 unless the source explicitly names a different count. N=3 when the user names three investigators, N=5–6 for larger ecosystems. Beyond 6 satellites, switch to the bus topology pattern — a shared store with 8+ agents suggests event-driven coordination, not accumulated state.
|
||||
Reference in New Issue
Block a user