Planning & backlogs

Field contracts and worked examples for the planning & backlogs blocks — converted at build time from the repo's authoring-skill reference. Every example body is YAML; in a real doc the fence language is the block type (for example sequence … ). Schemas are strict — unknown fields are rejected. See the field contract for the at-a-glance shape of all 77 blocks, or the block catalog for live previews.

Planning & meta

userstory — agile story + acceptance criteria + links

links may use ref: doc#id (a real cross-reference) or a plain label.

timeline — phases / roadmap

Items default to the terse [status] date · label · desc form — an optional leading status bracket, then 1-3 ·-separated parts (label alone, or date · label, or date · label · desc):

status is done | current | next | future (colours the dot). The object form ({ label, date, desc, status }) mixes freely with terse items.

changelog — release history

A vertical rail with a dot per release (red for tag: breaking), a mono version pill, the date, and a tag chip. Each item takes an optional keep-a-changelog type (added green · changed blue · fixed amber · removed gray · security red); untyped items get no chip. Newest release first. Use changelog for shipped history; use timeline for phases and plans ahead.

kanban — flexible columns

statustable — task table with an update column + colored status pills

Free cells render under the columns headers (default Task · Update); a final Status column renders each row's status as a colored pill. statuses is your label → color vocabulary. color is an accent name (navy | blue | teal | green | amber | purple | red | gray) or a semantic alias — success → green · error → red · warn → amber · neutral → gray · info → blue. Rows may also use the built-in defaults — in progress (amber) · blocked (red) · completed (green) · todo (gray) · done (green) — matched case-insensitively; any other status (row or subtask) fails avo check, which lists the available labels. A row may nest one level of subtasks (same cells + status shape) — they render indented under their parent with their own pills, and the parent's status stays whatever you set (no roll-up). Short cells pad with empty cells. Use statustable whenever tasks carry a status — define your own vocabulary (e.g. "waiting on vendor"), or lean on the built-in defaults.

Legacy tracker rows. The old tracker type (a fixed todo / doing / done / blocked task list with priority / owner / due) is now a permanent alias for statustable with variant: tracker. Its items[] shape (task* + status todo|doing|done|blocked · priority high|med|low · owner · due) is still accepted in place of rows — you'll meet it in older docs; write rows + statuses in new ones.

risk — a risk register

One row-card per risk. likelihood and impact are low | med | high; severity derives from their product — both high → critical (solid red chip), one high → high, both low → low, everything else medium. status is open | mitigating | accepted | closed (amber / blue / gray / green chip), right-aligned next to the owner. Use risk for a risk register; use statustable for task-level work and swot for strategic position.

cvt — current vs target (before / after)

proscons — pros vs cons (two columns)

Two columns weighing one option. To compare several options each with a verdict, use options; to compare things side by side visually, use gallery.

agenda — meeting agenda

Lists, backlogs & patterns

list — a fancy bullet list (four marker styles)

Each item is a bold lead + optional text. style picks the marker: accent (coloured left bar), check (ticks — done: false shows a hollow grey dot), icon (an icon per item, same set as drivers), or number (auto-numbered badges). accent (per item or block-level) tints the marker. Use list for a polished bullet list; use statustable when items have status/owner/due, drivers for a card grid, or steps in a spec row for an inline pipeline.

stories — a collapsible user-story backlog

Renders every story as a <details> accordion (no JavaScript) in one section — the summary shows the id, title, points, and priority; expanding reveals the narrative, acceptance criteria, and links. open: true starts a story expanded. Use stories for a backlog of many; use a single userstory block when one story deserves its own full section. links[].ref is a real doc#id cross-reference (checked by avo check).

pattern — a design-pattern reference card

A GoF-style card for explaining one pattern (repository, CQRS, saga, hexagonal, strategy…). Pair it with a belogic graph (the structure) and a sequence (the runtime) for a complete pattern tutorial. Only name is required.

gallery — a responsive grid of cells

A real grid (2 columns by default; set cols to 3–4). Each cell is one of three kinds — a plain note, a code snippet, or a nested block (a whole diagram). Mix them freely. The nested block is validated against its own schema, so a diagram-in-a-cell is checked exactly like a top-level one. Reach for gallery (not a multi-block code) when you want cards/diagrams in a grid rather than stacked.

Grid with text — title + caption cells (a comparison, a checklist of points):

Grid with code — each cell a code snippet (a "bug gallery" / spot-the-bug set):

title: Bug gallery
cols: 2
items:
  - { title: "N+1 query", lang: JavaScript, accent: red, caption: "1000 users = 1001 queries. Fix: JOIN.", code: "users.forEach(async u =>\n  await q('...WHERE user_id=?', u.id));" }
  - { title: "Off-by-one", lang: JavaScript, accent: amber, caption: "arr[len] is undefined. Fix: < not <=.", code: "for (let i=0; i<=arr.length; i++)\n  process(arr[i]);" }

Grid with diagrams — each cell a nested block (compare architectures side by side):

title: Pick an approach
cols: 3
items:
  - { title: Monolith, caption: One deployable., block: { type: c4, level: container, nodes: [{ id: u, col: 1, row: 1, kind: person, name: User }, { id: app, col: 2, row: 1, kind: container, family: service, name: App }], edges: [{ from: u, to: app }] } }
  - { title: Microservices, caption: Independent services., block: { type: c4, level: container, nodes: [{ id: gw, col: 1, row: 1, kind: container, family: service, name: Gateway }, { id: a, col: 2, row: 1, kind: container, family: service, name: Orders }], edges: [{ from: gw, to: a }] } }
  - { title: Event-driven, caption: Async via a broker., block: { type: block, nodes: [{ id: p, col: 1, row: 1, kind: producer, name: Producer }, { id: bus, col: 2, row: 1, kind: topic, name: Bus }], edges: [{ from: p, to: bus }] } }

Don't hand-write a pattern from memory — grab a vetted template. Avodado ships a library of 106 common patterns (system-design building blocks, AI / agent patterns, and the GoF code patterns): avo design lists the slugs, avo design <slug> prints a ready pattern card plus a structure diagram to adapt. The full slug list lives in system-design.md beside this file.

Comparing patterns → use a gallery. When the user says "compare X vs Y" (e.g. "adapter vs command", "monolith vs microservices", "REST vs gRPC"), don't write prose or a table — put each side in a gallery cell as a nested block so they sit side by side. Grab each via avo design <slug> and nest its pattern card (or its diagram). Use cols: 2 for two, cols: 3 for three.

title: Adapter vs Command
cols: 2
items:
  - { block: { type: pattern, name: Adapter, category: Structural, intent: "Convert one interface into another a client expects.", participants: [{ name: Target, role: interface the client wants }, { name: Adapter, role: translates calls }, { name: Adaptee, role: existing class }], consequences: { pros: [Reuse incompatible code], cons: [Extra indirection] } } }
  - { block: { type: pattern, name: Command, category: Behavioral, intent: "Wrap a request as an object to queue, log, and undo.", participants: [{ name: Command, role: "execute() / undo()" }, { name: Invoker, role: triggers commands }, { name: Receiver, role: does the work }], consequences: { pros: [Undo + queue + log], cons: [Many small classes] } } }

Field semantics — clarifications

A few fields are easy to misuse. Lock these in.

• userstory.links[].ref is the only field in v1 that creates a real cross-document reference. Other links items render as plain chips.
• userstory.id is what other docs reference. Use a short stable id like US-142, not a sentence.