Examples

For a guided first task, Start here or choose a workflow. This page is the detailed reference.

Two end-to-end flows and three examples per skill. The walkthroughs use a small sample project — linkfold, a URL shortener — so the decisions feel concrete.

Slash commands are shown in Claude Code form (/bootstrap). On the pi and omp coding agents the same skills are /skill:bootstrap, /skill:new-adr, …; Codex uses $bootstrap; the other hosts use their own slash menu. All skills also auto-trigger from natural-language requests where the host supports it.

A flow from scratch
Retrofitting an existing repo
Skill-by-skill examples
Multi-repo products: topologies A, B, C
Grouping a large catalogue by domain
Portable workspace flows

1. A flow from scratch

Starting from an empty repo.

Step 1 — Bootstrap

/bootstrap

Answer the 10 questions (en-GB · single ADR shape · full lifecycle · use plan/ · single writer · direct-to-main · default git contract · defer optionals · verify gate = npm test · no domain rules). Review the plan, then it writes:

linkfold/
├── AGENTS.md          # hard rules entry point
├── CLAUDE.md          # @AGENTS.md
├── CONVENTIONS.md     # authoring rules
├── INDEX.md           # generated ADR table
├── adr/0000-template.md
├── plan/{todo,done}/
└── _agent/prompts/autonomous.md    # single writer + a gate + plan/

Step 2 — Record the first decision

/new-adr  "store links in Postgres"

Creates adr/0001-postgres-storage.md and regenerates the index:

---
adr: 0001
title: Postgres storage for links
status: Proposed
date: 2026-06-02
---

INDEX.md:
| 0001 | Postgres storage for links | Proposed | 2026-06-02 | — |

Step 3 — Accept and queue the work

Walk the ADR to Accepted (the skill offers this), then:

/new-plan  "implement the links table for ADR 0001"

plan/todo/0001-links-table.md
  Owning ADR : adr/0001-postgres-storage.md
  Scope      : links table + migration
  Exit       : AC1 schema matches ADR · AC2 migration runs clean

Step 4 — Ship it

/ship-item

verify: npm test … OK
fast-forward → main locally
plan/todo/0001-links-table.md → plan/done/2026-06-02-links-table.md  (+ footer naming HEAD SHA)
adr/0001  status: Accepted → Implemented
INDEX regenerated
push → main

Step 5 — Check consistency

/audit

✔ numbering contiguous   ✔ INDEX in sync   ✔ plan coverage
0 blocking · 0 drift · 0 hygiene — clean

Repeat the loop for the next decisions — 0002 custom slugs, 0003 Redis rate limiting, and so on.

2. Retrofitting an existing repo

Starting from a repo that already has code and history.

Step 1 — Bootstrap (existing repo)

/bootstrap

Detected: existing repo (retrofit).
Preserving README.md, CONTRIBUTING.md, docs/.
Writing the convention set — merging, not overwriting.

Step 2 — Backfill from code and history

Accept the offer:

> Backfill ADRs, plan/done, and CONVENTIONS from the existing code
> and commit history? I'll propose drafts; you approve in batches.  [yes]

Proposed ADRs (approve in batches):
  0001  Express HTTP API        Implemented
  0002  Postgres storage        Implemented
  0003  JWT authentication      Implemented
+ matching plan/done/<commit-date>-*.md entries

Step 3 — Codify a de-facto rule

/add-convention  "we already use Conventional Commits — make it a rule"

Assessment: durable, repo-wide → codify.
→ CONVENTIONS.md §Git Contract + AGENTS.md hard rule

Step 4 — Audit the result

/audit

✔ numbering 0001–0003 contiguous   ✔ INDEX in sync
⚠ plan coverage: ADR 0003 has no plan/done entry → offer to create

Step 5 — Carry on forward

New work now follows the same loop: /new-adr → /new-plan → /ship-item.

3. Skill-by-skill examples

Heads-up — skills assess first. new-adr, new-plan, add-convention, brainstorm, and agent-wave open with a brief assessment: an opt-out gate, then one scroll-to-select question at a time, each with a recommended option — you decide, and a fully-specified request lets you skip straight through. The examples below show the intent; in practice the skill confirms scope with you first.

bootstrap

/bootstrap on a fresh repo → 10 questions → full scaffold (see Flow 1).
“set up documentation-led conventions here” on an existing repo → retrofit + backfill offer (see Flow 2).
/bootstrap choosing several writers in separate worktrees + PR integration → _agent/ holds ROLES.md, and a PR-based prompts/autonomous.md where a verify gate and the plan/todo/ queue it walks both exist. No lock ledger and no dashboard: a queue item is claimed by pushing claim/<item-key> — the queue file name without its extension — and opening a draft pull request from it, and what is in flight is read back from the worktrees, those branches, and the open draft PRs.

new-adr

/new-adr "use Postgres for storage" → adr/0001-…, Proposed, INDEX wired.
“new ADR: links support custom slugs” → capability ADR with numbered acceptance criteria (AC1 reserved words rejected, AC2 collision → 409).

“supersede ADR 0003 — move rate limiting to Redis” →

adr/0007-redis-rate-limiting.md  (supersedes: 0003)
adr/0003  status → Superseded    (superseded-by: 0007)

new-plan

/new-plan "queue the work for ADR 0005" → plan/todo/00NN naming owner, scope, exit criteria.
“add a plan item for the Redis limiter, depends on the Redis-client ADR” → item with a depends-on edge so agent-wave won’t start it early.
“backlog: analytics dashboard, tracing ADR 0008” → placed at the right queue position by priority number.

ship-item

/ship-item → ships the lowest-numbered todo through the full completion event (verify → completion commit with todo→done, ADR Implemented, and INDEX → push or PR merge).
“ship plan/todo/0002” → ships a specific item.
“mark the custom-slugs work done” → resolves which item it means, then runs the same event. Stops if the verify gate fails — no partial ship.

add-convention

“add a convention: all timestamps are UTC ISO-8601” → routed to CONVENTIONS.md.
“we should always write tests first” → TDD → an AGENTS.md hard rule plus a CONVENTIONS.md section.
“make ‘no secrets in code’ a rule” → the skill pushes back: already enforced by lint/CI, so it declines to add a duplicate rule (gatekeeper, not stenographer).
“don’t commit automatically at the end of a cycle — wait for operator input” → assessed as a durable workflow rule → an AGENTS.md hard rule plus a CONVENTIONS.md §Git Contract note:
```
AGENTS.md §Hard rules:
- Never commit automatically at cycle end. Pause and wait for explicit
  operator approval before each commit (and before any push).
```

audit

/audit → full punch list: numbering, INDEX sync, plan coverage, required sections, status validity, cross-refs, language, privacy leaks.
“are the ADRs in sync?” → focused numbering + INDEX check.

“check for ADR-privacy leaks before release” →

⚠ src/api/errors.ts:42  "see ADR 0007" in a customer-facing error string

On a catalogue that predates the shape: field, the report ends with one non-failing note and an offer:

ℹ migration available  shape encoded by number range (cutoff in
  CONVENTIONS.md §ADR Shapes; adr/0100-template.md at the boundary)
  — catalogue valid and passing under the range rules
→ migrate onto the declared shape: field?  0101 → 0013, 0102 → 0014,
  0104 → 0015 (capability numbers unchanged)  [y/N]

Answer y and it lands as one commit listing every pair; answer N and the repo carries on unchanged. See USAGE §5b.

brainstorm

/brainstorm "break 'add billing' into ADRs" → candidate ADRs + plan items + suggested ordering; writes nothing until you approve.
“what ADRs do we need for multi-tenant support?” → decomposition with dependency edges between candidates.
“plan the search feature” → proposes the set, then hands approved candidates to new-adr / new-plan.

agent-wave

/agent-wave "3 agents, checkpoint after each wave" → requests up to 3 available worktree subagents, one queue item each, reviews after each wave.
“fan out the next 5 todo items in parallel” → one wave, budget = 5 items.
“run the queue continuously until empty (PR-based)” → continuous mode; CI gates each merge. Reserves disjoint ADR numbers / plan slots per worktree so parallel agents never collide.

Concurrent numbering. ADR/plan numbers are assigned at authoring time, so parallel branches can collide on “next”. docflow keeps the contiguous numbers and closes the race with process guardrails — decide-before-do, check-before-merge (sync + audit + renumber locally), a merge-gate backstop, and claim-before-do (push claim/<item-key> for the item, so the push itself excludes the second writer) — pre-wired only for several-writer (shared-checkout or separate-worktree) or pull-request repos. A single writer on direct-to-main needs none of it. See USAGE → Concurrent ADR/plan creation.

rollup

/rollup (run from the home repo of a federation) → reads federation-index.md, aggregates each member’s INDEX into a derived product-wide roll-up, and reports how many members were aggregated.
“refresh the product-wide ADR view” → regenerates the roll-up; members not checked out are listed as “not aggregated this run” rather than dropped.

Federation. /rollup and the cross-repo /audit checks run from the home repo over the local checkouts named in federation-index.md. See the methodology.

4. Multi-repo products: topologies A, B, C

When one product spans several repositories, bootstrap wires them into a federation. You choose a topology once, when establishing; every repo that joins inherits it. These examples split linkfold into two repos — linkfold-web and linkfold-api (repo-ids web and api).

The federation step (Q11) runs after the standard bootstrap assessment: “Is this repo part of a multi-repo product?” → establish or join → (establish only) topology + identity scheme (default repo-prefixed slug <repo-id>/NNNN-slug).

4A — Topology A: central decisions repo

All product-wide decisions live in one dedicated repo; code repos reference them and never duplicate.

In a fresh decisions repo: /bootstrap → multi-repo yes → establish → topology A. It becomes Role: central and writes federation-index.md + federation.md (Topology: A, Repo id: decisions).
In linkfold-web: /bootstrap → join → supply the home pointer (../decisions) and the topology/identity. It writes only its own federation.md (Role: member) and — per topology A — holds no product-wide ADRs; its adr/ is for local-implementation decisions that reference decisions/0001 etc.
Add web and api rows to decisions/federation-index.md (a deliberate edit in the central repo).
/rollup and /audit run from decisions.

Use A when product-wide decisions need a single, code-free home.

4B — Topology B: distributed + federation

No repo owns product-wide decisions; each repo owns its own catalogue and the roll-up is the only product-wide view.

In linkfold-web (the first repo): /bootstrap → establish → topology B. It becomes Role: coordinator — it holds the member index for membership only, not a privileged catalogue.
In linkfold-api: /bootstrap → join. It owns its ADRs in full (Role: member); nothing is “product-wide” except by cross-repo reference.
Register api in the coordinator’s federation-index.md.
/rollup from the coordinator gives the combined product view — there is no central authority.

Use B when each repo is autonomous and you only need a combined view.

4C — Topology C: home repo + local (recommended default)

One home repo holds product-wide decisions; members keep local decisions alongside and reference the home for product-wide ones.

In linkfold-web (the home): /bootstrap → establish → topology C (default). Role: home; it holds product-wide ADRs and its own local ones.
In linkfold-api: /bootstrap → join. Role: member; it keeps local ADRs and references web/0007 for product-wide decisions.
Register api in linkfold-web/federation-index.md.
A cross-repo decision (say, a shared auth contract web/0007) gets one plan item per affected repo. Its aggregate status shows in the roll-up — “1 of 2 repos” until both ship, then Implemented.
/rollup and /audit run from the home.

Use C — the default — for the common “one lead repo, several services” shape.

Across all three: numbering stays contiguous per repo; the federation identity (<repo-id>/NNNN-slug) is the cross-repo key; cross-repo references resolve through the member index; aggregate status is derived in the roll-up; and no tool writes across a repo boundary — membership and convention drift are reconciled by /audit, not remote-pushed. See the methodology.

5. Grouping a large catalogue by domain

Once linkfold’s catalogue spans distinct areas, enable the domains/ grouping (bootstrap Q7, or later via a bootstrap re-run / new-adr) so readers browse by area instead of scanning the whole numbered list. It is purely a view — every ADR keeps its flat number and its INDEX.md row.

The layout (under the artefact root):

adr/
  0004-oauth-login.md
  0007-api-rate-limiting.md
  0011-stripe-billing.md
  0014-invoice-pdf.md
domains/
  auth/README.md        # indexes 0004, …
  billing/README.md     # indexes 0011, 0014, …
  api/README.md         # indexes 0007, …

A domain README is just a curated index:

# Auth — decisions

| ADR | Title | Status |
|-----|-------|--------|
| [0004](../../adr/0004-oauth-login.md) | OAuth login | Implemented |
| …    |       |        |

In practice:

/new-adr "add SSO via SAML" → with domains/ present, new-adr asks (or infers) the owning domain — auth — mints the next flat number (adr/0017-…), and adds it to domains/auth/README.md.
“new ADR: dunning emails for failed payments”, filed under a domain that doesn’t exist yet → new-adr offers to create domains/dunning/README.md and seeds it with the ADR.
The global INDEX.md still lists all ADRs by number; the domain READMEs are the per-area lens on top.

Not to be confused with per-domain numbering (auth/0001 — rejected; the number stays flat) or the federation (separate repos). This is one repo, one catalogue, viewed by area.

6. Portable workspace flows

When a product spans several repositories, the five workspace commands add a shared memory beside them. Each has a worked step-by-step flow on the Portable workspaces page, covering a greenfield product, a retrofit of existing repositories, migrating a single docflow repository, and mixed, remote-only and federation cases.

The commands run in order:

workspace-setup — create or adopt the workspace home and registry.
workspace-status — read priorities, owners, current authority and blockers (read-only).
workspace-scope — record ideas, decisions, work with deliveries and criteria, and grants from a committed mandate note.
workspace-dispatch — check the grant, native claim, dependencies and resources, then hand off a bounded brief.
workspace-sync — reconcile returned receipts and member state from checked native evidence, then refresh INDEX.md.

Selection and agreement grant no execution authority. A prepared pull request or an unmerged plan item never marks a delivery complete.

← Back to docflow

Final skill results report This run, Overall and Yet to do under Status at a glance. Live ownership, blockers and stop reasons are recorded on the queue item. Wave width adapts to host capabilities; unavailable delegation uses sequential execution. Ready PRs remain live until their checked merge.

Complete adoption workflows

Use the workflow guide hub for existing repositories, existing workspace memory, mixed setups and new projects, plus daily dispatch, receipt checking and recovery. The release notes distinguish package checks from pending native qualification.