call-map

---
name: call-map
description: Publishes the call map (a claude.ai canvas, one board per screen with its calls) and the handoff-doc reader (with Swagger and .md downloads) as claude.ai links, and posts each link in the hub messages. Use for /lead-flow:callmap, or after a handoff task's close merges.
---

# Call map

Two claude.ai pages, published from the hub as private artifacts (L-017):

- **The call map:** a canvas made from claude.ai's Design type. One board per screen, its picture
  beside its calls; tapping a call shows Request, Response, Example and Behind.
- **The reader:** the handoff docs by group, with "Download Swagger" and "Download this doc
  (.md)".

The coordinator runs this with `/lead-flow:callmap` after a handoff task's close merges, or when
the lead asks. `<hub>` is the hub's absolute path and `<lead>` is `lead` in `lead-flow.json`.
Check **Refusals** first.

Pick the pass from `callmap/published.json`:

- No file, or no `canvas.url` in it: a **First publish**.
- A `canvas.url`, but `reader.url` is `null`: a first publish that stopped partway. **Resume** it
  on that canvas: read and list it as **Later publishes** says, run Later publishes steps 1 to 8,
  then First publish steps 9 and 10.
- Both urls: a **Later publish**.

The arguments, when given, are the group codes (`HD-6`) the messages announce.

**The release** is the last entry of `callmap.releases` that has a `docs/changes/<release>.md`.
With no such entry but some `docs/changes/*.md`, ask the lead which one is the release's, as
`lead-flow:consumer-docs` does. With no `docs/changes/*.md`, there is none: `changes.url` stays
`null` and the messages say "no route changed".

Every CLI command below exits 2 with `error: …` on a bad hub or config: show the error and stop.

## First publish

1. **Check.**

   ```bash
   python3 "${CLAUDE_PLUGIN_ROOT}/lib/leadflow/cli.py" callmap-check "<hub>"
   ```

   It must print a line starting `OK:`. Exit 1 lists the problems: show them to the lead and stop.
   Fixing a flows file is a handoff task's or the coordinator's work, never this skill's.

2. **Create the canvas.** Call the Artifact tool with `action: "quickstart"`, intent `design` and
   `design_systems: false` (the canvas templates carry their own look, L-008). Create from the
   `type_url` its result names; never hard-code a type link. Publish with that `type_url`, the
   `title` `<project> call map`, no files and `auto_open: "after_first_write"`. Follow the type's
   instructions and read the pages it says to read first. The boards go only under `project/`.

   Write `callmap/published.json` at once with the Write tool, so a stop before step 6 keeps the
   canvas: `canvas.url` the result's url, `canvas.created_at` the output of
   `date -u +%Y-%m-%dT%H:%M:%SZ`, `canvas.assets` `{}`, `reader` `{"url": null, "files": {}}` and
   `changes` `{"url": null}`.

3. **Render the data.**

   ```bash
   python3 "${CLAUDE_PLUGIN_ROOT}/lib/leadflow/cli.py" callmap-render "<hub>" --data-only
   ```

   It writes `callmap/dist/flows.resolved.json` and `callmap/dist/contracts.json`, and must exit 0.

4. **Upload the assets** to the canvas: the Artifact tool's publish with `url` (the canvas url) and
   `asset: true`.
   - The pictures, `<hub>/callmap/shots/*.png`, go with `file_paths`, up to 25 per call.
   - Each JSON file goes in its own call with `file_path`:
     `<hub>/callmap/dist/flows.resolved.json`, then `<hub>/callmap/dist/contracts.json`.
   The paths are absolute: the tool resolves a relative one against the coordinator's cwd, which
   need not be the hub.

   Keep each result's `url` (a `/_blob/…` url) exactly as given, and each file's hash from
   `shasum -a 256 "<file>"`. The boards can fetch only these `/_blob/` urls: the Design type allows
   no other network.

5. **What changed.** When the Claude Docs connector is attached (the host names it first-party),
   publish the release's `docs/changes/<release>.md` there as a doc and keep its link. Otherwise,
   or with no release, the link stays `null`, and the reader shows each `docs/changes/*.md` as a
   doc.

6. **Update `callmap/published.json`** with the Write tool:

   ```json
   {"canvas": {"url": "<canvas url>", "created_at": "<iso time>",
               "assets": {"callmap/shots/<screen id>.png": {"url": "/_blob/…", "sha256": "<hex>"}}},
    "reader": {"url": null, "files": {}},
    "changes": {"url": null}}
   ```

   - `canvas.url` and `canvas.created_at`: as step 2 wrote them. `created_at` is set once there
     and never changes afterwards: the canvas's `createdOnFiles` reads it.
   - `canvas.assets`: one entry per uploaded file, keyed by its hub-relative path, with its `url`
     and `sha256`.
   - `changes.url`: step 5's link, or `null`.
   - `reader.url` and `reader.files` stay empty until step 9.

7. **Render the canvas and the reader.**

   ```bash
   python3 "${CLAUDE_PLUGIN_ROOT}/lib/leadflow/cli.py" callmap-render "<hub>"
   ```

   It fills the asset urls into `callmap/dist/canvas/project/` and builds
   `<hub>/callmap/dist/reader/`.
   It must exit 0. Exit 1 prints each placeholder left unfilled (`<file>: <placeholder>`), which is
   an asset missing from `canvas.assets`: upload it (step 4), record it (step 6) and render again.
   Never publish a board with a placeholder in it.

8. **Publish the boards** to the canvas url, with `root` set to `<hub>/callmap/dist/canvas` and
   `files` listing every `project/…` path under it: `canvas.json`, `Main.dc.html`,
   `Screen.dc.html` and each screen's stub. More than 255 files go over several publishes to the
   same `url`.

9. **Publish the reader.** Load the `artifact-capabilities` skill first. Then publish
   `<hub>/callmap/dist/reader/index.html` as a new artifact, with `root` set to
   `<hub>/callmap/dist/reader/`, `files` listing every other file in that folder (each `.md` doc
   and each `<service>.json`), `capabilities` `{"downloads": true}` and `icon` `book`. The download
   buttons use `downloads`; a viewer who is not signed in gets the copy box instead. Then record in
   `published.json`: `reader.url` (the result's url) and `reader.files` (each path in `files`, with
   its `shasum -a 256`). `index.html` stays out of `reader.files`: it goes as the `file_path` on
   every publish.

10. **Hand over.** Print both links for the lead to share with anyone who has no lead-flow hub:
    the call map (`canvas.url`) and the reader (`reader.url`). Then send the **Messages**.

## Later publishes

The canvas and the reader exist: publish to `canvas.url` and `reader.url`, never to a new
artifact. Before the first publish to each in this session (on a resume, only the canvas):

- read it with the Artifact tool (`action: "read"` and its url): a publish to an artifact this
  session has not read is refused;
- list its files (`action: "list"`, `scope: "files"`, its url). A `files` publish may replace, or
  map to `null`, only the paths this session listed, read or published; this listing is what lets
  steps 7 and 9 do both. Never pass `overwrite_unread` instead.

1. **Check:** `callmap-check`, as in first publish step 1.
2. **Render the data:** `callmap-render "<hub>" --data-only`, as in step 3.
3. **Upload only the changed assets:** a picture or JSON file whose `shasum -a 256` differs from
   its `sha256` in `canvas.assets`, or that has no entry yet (a new picture). Use step 4's calls.
   The two JSON files carry a build time (`built_at`, `generated_at`), so they go up on every
   publish, and the boards that point at them change every time too. Note each replaced asset's
   old `url` before step 5 overwrites it.
4. **What changed:** when the release's `docs/changes/<release>.md` changed, update the same
   Claude Docs doc. A new release gets a new doc and its link.
5. **Update `published.json`:** each changed asset's `url` and `sha256`, and `changes.url` when it
   moved. `canvas.url` and `canvas.created_at` stay as they are.
6. **Render:** `callmap-render "<hub>"`, as in step 7. It must exit 0.
7. **Publish the changed boards.** From the canvas's listing, read its `project/…` files
   (`action: "read"` with `paths`), and compare each with `cmp` against
   `callmap/dist/canvas/project/`. Publish, with first publish step 8's `root`, only the boards
   that differ or are new. A published `project/…` board that render no longer writes (a dropped
   screen) maps to `null`. The type's own files stay as they are.
8. **Delete the replaced assets,** now that no published board points at them. For each old url
   step 3 noted, find its id in an assets listing (`action: "list"`, `scope: "assets"`, the canvas
   url) and remove it (`action: "delete"`, the canvas url, `path` the id). Delete nothing else.
9. **Republish the reader** to `reader.url`. The `file_path` is always
   `<hub>/callmap/dist/reader/index.html`, with `root` `<hub>/callmap/dist/reader/`; `files` lists
   only the other files whose `shasum -a 256` differs from `reader.files`, or that are new. A path
   in `reader.files` that the folder no longer holds maps to `null`. Omit `capabilities`, so
   `downloads` carries over. Then update `reader.files`.

The links stay the same, so step 10 has nothing new to print. Send the **Messages**.

## Messages

Each publish posts its links in the hub messages, so every teammate's next session shows them
(L-019).

**The docs to announce:** the group codes given to `/lead-flow:callmap`, else every doc whose
reader file changed in this publish (on a first publish, every doc). A doc's id in the reader is
its code in lower case (`HD-6` is `#hd-6`). **Refusals** has already checked each given code: it
matches `[A-Z]{1,4}-[0-9]+` and is a `code` in `callmap/groups.json`, so an unknown one never gets
here.

**Nothing to announce** (no code given and no reader doc changed): send no messages, say so, and
commit only `callmap/published.json`, with the subject `docs(callmap): publish`.

**One message per teammate** in `team` in `lead-flow.json`, sent from `<lead>`. A message to `all`
never reaches a peer hub, so never use `all` here. With no `team`, send nothing, and say the lead
shares the links.

- **Subject:** `<CODE>-<n> <title> updated`, with the title from `callmap/groups.json`. Several
  docs share one subject: `HD-6 Basket, HD-7 Checkout updated`.
- **Body:** each doc's reader link with `#<doc id>`, then the canvas link, then the what-changed
  lines (from the release's `docs/changes/<release>.md`; none: "no route changed").

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/lib/leadflow/cli.py" send "<hub>" "<lead>" "<teammate>" <<'LEADFLOW_MSG_END'
<CODE>-<n> <title> updated
Reader: <reader url>#<doc id>
Call map: <canvas url>
<what-changed lines>
LEADFLOW_MSG_END
```

The `LEADFLOW_MSG_END` line must start at column 0. Each send prints the message id; an exit 2
sent nothing: fix it and send again.

**Commit** in the hub, with the subject `docs(callmap): publish <codes>`, where `<codes>` are the
announced codes, comma-separated (`HD-6, HD-7`):

```bash
git -C "<hub>" add callmap/published.json
git -C "<hub>" commit -m "docs(callmap): publish <codes>" -- callmap/published.json
```

Name `messages/<lead>.md` too, after the other path in both commands, only when a send wrote it:
a hub with no `team` has none, and `git add` of a missing path stages nothing and fails. The
paths after `--` keep anything else staged in the hub out of this commit. Never add
`callmap/dist/`: it is generated. **Then ask the lead** whether to push the hub, and
push only on the lead's yes (L-004): `git -C "<hub>" push`. A teammate's coordinator sees the
message after the push and their `sync-peers`; a teammate whose hub is a local path sees it at
once.

## Refusals

Stop before any step, and say why:

- **The call map is off:** run `python3 "${CLAUDE_PLUGIN_ROOT}/lib/leadflow/cli.py" shape "<hub>"`
  first. When it prints `call-map: off`, stop with the one line `call map is off (L-063): skipped`
  and ask nothing. When it exits non-zero, stop and show its message; a config error is never read as `on`. With no record, or no `Call map:` line, `shape` prints `call-map: on` (it reads on):
  nothing is refused for that.
- **A bundled hub:** `lead-flow.json` has a `bundle` key. The call map lives only in the lead's
  hub; tell the teammate that the lead publishes it.
- **No Artifact tool:** Claude Code is not signed in to claude.ai. Say that publishing needs the
  Artifact tool, and to sign in and run `/lead-flow:callmap` again. Never fall back to a local page
  or another host (L-017).
- **Not the coordinator:** only the coordinator publishes. A task session stops and asks the
  lead's coordinator to run `/lead-flow:callmap`.
- **No call map yet:** `lead-flow.json` has no `callmap` key (read it, as for `bundle`), or
  `callmap-check` exits 2 because there is no `callmap/groups.json`. Say which, in one line, and
  publish nothing.
- **An unknown group code:** an argument that does not match `[A-Z]{1,4}-[0-9]+`, or is no `code`
  in `callmap/groups.json`. Name it, and stop before any publish.

• SKILL.md 13 KB
• handoff-task.md 5 KB