feat: Deliver the explainer on the tracker item (screenshot + attached HTML)

[tbrownio]

---

type: feature-ticket
id: tracker-explainer-surface
status: ready
zone: 1

Feature: Deliver the explainer on the tracker item (screenshot + attached HTML)

Intent

The user's interface to agent work is the tracker (Linear here) — runs
happen on VMs, so the skills' current alignment surface, opening
refs/explainer.html in a local browser, never reaches them. And on the
tracker itself the explainer exists only as a raw marker-delimited
comment blob. The human view of a work item must live cleanly on the
tracker item: an inline screenshot of the explainer for at-a-glance
reading, plus the self-contained explainer HTML as a downloadable
attachment for full fidelity (in-page nav to appended docs), kept
current as the item accrues plan.md, wrapup.md, and other docs.
Download-and-open is an accepted temporary pain until a self-hosted
viewer exists (Linear TM-393).

Desired end state

• Every published work item shows, on the tracker item itself: an inline
  screenshot image of the current explainer, and the current
  self-contained explainer HTML as a downloadable attachment that renders
  fully offline (master page with in-page navigation to each appended
  doc and back).
• When /do (or any skill) appends a doc to the item's refs, the
  explainer is re-rendered and the screenshot + attachment are replaced —
  one current version on the ticket, never a pile of stale copies.
• Alignment works without a local browser: in Linear-driven sessions the
  draft explainer reaches the user in the session's chat thread and their
  reply is the nod. The local browser auto-open remains (attempted
  everywhere, silently tolerated when no browser exists).
• Agents' machine-readable path is untouched: item.md and refs are still
  harvested from the tracker's marker mechanism, never from the
  screenshot or attachment.

Key architecture directions

• D1 — Linear-class trackers (those with a native upload API) get
  the full treatment: inline screenshot + HTML file attachment. Trackers
  without an upload API (GitHub issues included) keep the existing
  marker-comment mechanism as the documented degraded fallback — no
  screenshot embed is claimed where the API can't deliver one. Wording
  in the synced references stays tracker-neutral ("where the destination
  supports uploads…"); no tracker becomes a hard dependency.
• D2 — Two renditions, one source: the inline screenshot is for
  glanceability, the attached HTML is the full-fidelity view; both are
  regenerated from the same explainer.html on every change. Replacement,
  not accumulation — clean tickets are the point.
• D3 — No external hosting of any kind: no Claude artifacts, no
  third-party file hosts. Content goes only to the tracker the repo
  already publishes to. (Self-hosted viewer is future work, TM-393.)
• D4 — Alignment happens wherever the conversation with the user
  already is. The browser auto-open is attempted everywhere and allowed
  to fail silently (no browser on the daemon/VM — that's fine). In a
  Linear-driven session, the agent posts the explainer rendition into
  the session's chat thread for review — Linear lets the agent message
  the user — and the user's chat reply is the alignment nod the session
  receives; no polling, no draft-status issue created for alignment. No
  path may silently skip the alignment pause itself.
• D5 — The screenshot is best-effort: rendered when a headless
  browser/renderer is available in the environment, skipped (with the
  HTML attachment still delivered) when not. Publish and alignment are
  never blocked by a missing renderer; the reference states the
  capability requirement, not a specific tool, and introduces no new
  hard dependency for consumers.
• D6 — Machine source of truth unchanged: marker-comment harvest of
  item.md/refs stays exactly as is; screenshot and attachment are
  presentation only.

Starting points (non-exhaustive)

• references/html-explainer.md — owns render-and-open today; gains the delivery + regeneration procedure
• references/publish-work-item.md — publish step gains screenshot + attachment; already defines the marker mechanism
• claude/skills/do/SKILL.md — appends docs over the item's life; triggers re-render + replace
• daemon/ — NOT touched; future hosting lives in TM-393

Verification criteria

• AC1 — WHEN a work item publishes to a Linear-class tracker (native
  upload API) per the updated references, the tracker item shall carry
  an inline screenshot of the explainer (when a renderer is available)
  and the self-contained explainer HTML as a downloadable attachment;
  WHEN it publishes to a tracker without an upload API, the existing
  marker-comment mechanism shall carry the explainer unchanged.
• AC2 — WHEN the attached HTML is opened from a fresh download with
  no network, it shall render completely, and each appended doc shall be
  reachable from the master page and link back to it.
• AC3 — WHEN a doc is appended to a published item, the tracker item
  shall show exactly one current screenshot and one current HTML
  attachment reflecting the appended doc (no stale duplicates remain).
• AC4 — WHEN alignment runs in a Linear-driven session, the skill
  shall post the explainer rendition into the session's chat thread and
  proceed to publish only after the user's chat reply confirms; WHEN it
  runs locally, the skill shall attempt the browser open, and a failed
  open shall not abort the flow.
• AC5 — WHEN the synced directories are grepped after the change, no
  consumer-specific names/paths/IDs shall appear and no external hosting
  service shall be referenced.

Verification map

Criterion	Method	Command / flow	✓
AC1	script (live drive)	publish a scratch item to a Linear-class tracker (scratch issue in the user's workspace); inspect via API for image + attachment; confirm marker fallback text for upload-less trackers	[ ]
AC2	script + review	download the attachment, open offline, click through nav both ways	[ ]
AC3	script (live drive)	append a doc to the scratch item, re-publish; count attachments/screenshots via API	[ ]
AC4	review	walk the updated skill text's Linear-session and local branches; confirm no publish path skips alignment and no path aborts on a failed browser open	[ ]
AC5	script	grep synced dirs for consumer identifiers and hosting-service names	[ ]

Out of scope

• Self-hosted / daemon-hosted artifact viewer (Linear TM-393).
• Claude artifacts or any claude.ai upload.
• Invocation-gate changes (separate item: agent-invocable-capture).
• Any daemon/ code change.

Justification

• Why move the human view to the tracker — runs happen on VMs and the
  user's only interface is Linear; the local browser-open never reaches
  them, and the marker-comment blob is unreadable as a human surface.
• Why not Claude artifacts — private-by-default with no programmatic
  sharing, Claude-harness-only, and off-infra copies for every consumer
  (gate round 1 on the combined draft; replacement tracked in TM-393).
• Per-tracker mechanism — resolved by tracker class: native-upload
  trackers (Linear class) get screenshot + attachment; upload-less
  trackers (GitHub issues) keep marker comments as the documented
  degraded fallback. Accepted cost: no glanceable rendition on GitHub.
• Headless alignment loop — the Linear agent-session chat carries the
  draft explainer and the user's in-chat reply is the nod; no polling,
  no draft-status issues, no new confirmation machinery.
• Headless-renderer dependency — screenshot is best-effort; the browser
  open is attempted and silently tolerated when absent; publish and
  alignment never block on a missing renderer. The env-var switch was
  considered and dropped for attempt-and-tolerate.
• Zone 1 held: rewires the alignment checkpoint every consumer inherits
  via sync.

Open questions

• None.

[tbrownio]

2026-07-18 — Agent-invocable planning skills + Claude-artifact viewer layer

Decisions

1. Make create-plan and create-epic agent-invocable. Remove
   disable-model-invocation: true from both; rewrite each frontmatter
   description with real "Use when…" triggers (e.g. a discussion has
   converged on a buildable change / multi-phase workstream and no work
   item exists) plus an anti-trigger so passing ideas don't spawn tickets.
   /do and /prepare-pull-request stay user-gated — they execute and
   ship code; that line was deliberate and stands.

2. The explainer-alignment pause stays as the checkpoint. A
   proactively invoked create-* skill still stops at the explainer for the
   user's nod before publishing. No new confirmation step needed — the
   existing flow already provides it.

3. Tracker abstraction is unchanged. Consumer AGENTS.md
   "Work-item tracking" remains the sole authority (GitHub, Linear,
   whatever). Orchestra itself stays on GitHub issues. We are NOT baking
   Linear into the skills (earlier direction explored and reversed —
   orchestra must not require Linear).

4. New tracker-neutral invariant: the explainer always publishes as a
   Claude artifact, and the artifact URL always rides on the tracker
   item. Whatever the tracker, the skill: renders explainer.html →
   publishes it as a Claude artifact → puts the URL on the work item
   (Linear: attachment/link; GitHub: issue body/comment). The artifact is
   the single human viewing layer: master explainer page with appended
   docs (plan.md, wrapup.md, etc.) embedded as navigable sections
   (client-side hash routing, back-links) — one URL, updated in place as
   docs are appended.

5. Artifact is presentation only; tracker stays source of truth.
   Agents keep harvesting item.md/refs from tracker comments/attachments
   (existing marker mechanism), never from the artifact. The artifact is
   regenerated from refs on every update.

6. Update-in-place requires recording the artifact URL durably — in
   item.md frontmatter (alongside tracker:/github: keys) and on the
   tracker item — so later sessions can redeploy to the same URL.

7. Private-by-default sharing is accepted for now. Claude artifacts
   publish private; the user manually flips sharing per artifact when
   teammates need it. The skill's publish step should nudge once
   ("share this artifact to make the link work for others").
   Future replacement tracked in Linear TM-393: harness-agnostic
   artifact/viewer layer (Codex has no Artifact tool; only Claude runs
   can publish/update the viewer today).

Constraints stated by the user

• Orchestra stays platform/tracker-agnostic; don't "mess with Linear too
  much" — no deep Linear publish-path rework in this change.
• It's fine for this repo to keep using GitHub.
• Manual sharing of artifacts is acceptable for now.

Where the changes land (altitude, not file-by-file)

• claude/skills/create-plan/SKILL.md, create-epic/SKILL.md: frontmatter
  gate removal + trigger descriptions.
• references/html-explainer.md: artifact publish/update step (publish,
  record URL, redeploy on append, share nudge) replacing/augmenting the
  local open step.
• references/publish-work-item.md: tracker-neutral "attach artifact URL
  to the published item" step.
• /do (and any skill appending docs): re-render + redeploy the artifact
  when refs are appended.
• Note: artifact publishing must live in Claude-side skill steps only —
  Codex sub-agents cannot publish artifacts.

Open questions

• None blocking. (Deferred: harness-agnostic viewer — TM-393.)

Addendum (same day, post-Socratic-gate)

The gate pressed on the combined draft; the user redirected:

1. Claude artifacts are dropped entirely. No claude.ai uploads. The
   human view of a work item is delivered on the tracker item itself:
   an inline screenshot (image) of the explainer plus the self-contained
   explainer HTML as a downloadable attachment. Download-and-open is an
   accepted temporary pain.
2. Split into two items (socrates Q2 accepted): Change A = lift the
   invocation gate on create-plan/create-epic; Change B = the
   tracker-surface presentation layer. A ships now; B can follow.
3. New operating constraint stated by the user: agent runs happen on
   VMs and the user's only interface is Linear — opening a local browser
   for alignment does not reach them. Tracker tickets must be clean:
   inline images, links, downloadable files. Change B's design must make
   the tracker the surface, including for alignment when there is no
   local browser.
4. Future: a self-hosted artifact-viewing layer — possibly the
   orchestra daemon hosting files — replaces download-and-open later.
   Folded into Linear TM-393 (which previously proposed replacing Claude
   artifacts; now it's about replacing tracker file attachments).

[tbrownio]

<!doctype html>

<title>Deliver the explainer on the tracker item — Explainer</title> <style> :root { --paper: #FAF8F5; --ink: #1F2328; --ink-soft: #5A5F66; --line: #E4DFD7; --panel: #FFFFFF; --accent: #0E7569; --accent-soft: #E3F0EE; --warn: #B45309; --warn-soft: #F7EBDD; --out: #9F3A38; --out-soft: #F6E8E7; --mono: ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, monospace; --serif: Georgia, "Iowan Old Style", "Times New Roman", serif; --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; } @media (prefers-color-scheme: dark) { :root { --paper: #15191D; --ink: #E8E6E1; --ink-soft: #9BA1A8; --line: #2C3237; --panel: #1C2126; --accent: #2FA79A; --accent-soft: #16302D; --warn: #D98E3D; --warn-soft: #32271A; --out: #CF6F6C; --out-soft: #33211F; } } * { margin: 0; padding: 0; box-sizing: border-box; } body { background: var(--paper); color: var(--ink); font-family: var(--sans); line-height: 1.6; font-size: 16px; } .page { max-width: 720px; margin: 0 auto; padding: 3rem 1.25rem 5rem; } header.masthead { border-bottom: 1px solid var(--line); padding-bottom: 1.75rem; margin-bottom: 2.5rem; } .meta-row { display: flex; flex-wrap: wrap; gap: .5rem .75rem; align-items: center; margin-bottom: 1rem; } .badge { font-family: var(--mono); font-size: .72rem; letter-spacing: .06em; padding: .2rem .55rem; border-radius: 3px; text-transform: uppercase; } .badge.type { background: var(--accent-soft); color: var(--accent); } .badge.status { border: 1px solid var(--line); color: var(--ink-soft); } .badge.zone { border: 1px solid var(--warn); color: var(--warn); background: var(--warn-soft); } h1 { font-family: var(--serif); font-weight: 500; font-size: 2.1rem; line-height: 1.2; letter-spacing: -.01em; text-wrap: balance; margin-bottom: .75rem; } .standfirst { color: var(--ink-soft); font-size: 1.05rem; max-width: 60ch; } section { margin-bottom: 2.75rem; } .eyebrow { font-family: var(--mono); font-size: .72rem; letter-spacing: .1em; text-transform: uppercase; color: var(--accent); margin-bottom: .6rem; } h2 { font-size: 1.25rem; margin-bottom: .75rem; letter-spacing: -.01em; } p { margin-bottom: .9rem; max-width: 65ch; } code { font-family: var(--mono); font-size: .85em; background: var(--panel); border: 1px solid var(--line); padding: .08em .35em; border-radius: 3px; } .before-after { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 1.25rem 0; } @media (max-width: 560px) { .before-after { grid-template-columns: 1fr; } } .panel { background: var(--panel); border: 1px solid var(--line); border-radius: 6px; padding: 1.1rem 1.2rem; } .panel h3 { margin-bottom: .6rem; font-size: .78rem; font-family: var(--mono); letter-spacing: .08em; text-transform: uppercase; color: var(--ink-soft); } .panel.after { border-color: var(--accent); } .panel.after h3 { color: var(--accent); } .panel ul { padding-left: 1.1rem; font-size: .92rem; } .panel li { margin-bottom: .4rem; } .diagram { margin: 1.5rem 0 2.5rem; } .diagram svg { display: block; max-width: 100%; height: auto; } .diagram figcaption { margin-top: .5rem; font-size: .8rem; color: var(--ink-soft); } .pipeline { display: flex; align-items: stretch; margin: 1.5rem 0; overflow-x: auto; padding-bottom: .5rem; } .stage { background: var(--panel); border: 1px solid var(--line); border-radius: 6px; padding: .75rem .9rem; min-width: 130px; flex: 1; } .stage.hot { border-color: var(--accent); background: var(--accent-soft); } .stage .name { font-family: var(--mono); font-size: .78rem; font-weight: 600; margin-bottom: .25rem; } .stage .desc { font-size: .78rem; color: var(--ink-soft); line-height: 1.45; } .arrow { align-self: center; padding: 0 .5rem; color: var(--ink-soft); flex: none; } .strip-note { margin: -.5rem 0 0; font-size: .8rem; color: var(--ink-soft); } .decision { border-left: 3px solid var(--accent); padding: .2rem 0 .2rem 1.1rem; margin-bottom: 1.25rem; } .decision .tag { font-family: var(--mono); font-size: .78rem; font-weight: 700; color: var(--accent); } .decision p { margin: .3rem 0 0; font-size: .95rem; } .decision .rejected { color: var(--ink-soft); font-size: .85rem; } .decision .rejected::before { content: "rejected — "; font-style: italic; } .scope { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; } @media (max-width: 560px) { .scope { grid-template-columns: 1fr; } } .scope .panel.in { border-top: 3px solid var(--accent); } .scope .panel.outof { border-top: 3px solid var(--out); } .scope .panel.outof h3 { color: var(--out); } .shots { margin: 1.75rem 0; } .pair { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; align-items: start; margin-bottom: 2rem; } .pair:last-child { margin-bottom: 0; } @media (max-width: 560px) { .pair { grid-template-columns: 1fr; } } .shot { margin: 0; } .shot figcaption { margin-top: .55rem; font-size: .8rem; color: var(--ink-soft); line-height: 1.4; } .shot.after figcaption { color: var(--accent); } .mock { border: 1px solid var(--line); border-radius: 8px; background: var(--panel); padding: 1.1rem 1.15rem 1.25rem; font-size: .85rem; } .shot.after .mock { border-color: var(--accent); } .mock-eyebrow { font-family: var(--mono); font-size: .64rem; letter-spacing: .08em; text-transform: uppercase; color: var(--ink-soft); margin-bottom: .7rem; } .mock-q { font-weight: 600; font-size: .9rem; margin-bottom: .85rem; } .mock-field { display: flex; justify-content: space-between; align-items: center; gap: 1rem; border: 1px solid var(--line); border-radius: 6px; padding: .6rem .7rem; margin-bottom: .55rem; color: var(--ink-soft); } .mock-field:last-child { margin-bottom: 0; } .mock-field.hl { border-color: var(--accent); } .mock-field .val { color: var(--ink); font-variant-numeric: tabular-nums; } .mock-doc { border: 1px dashed var(--line); border-radius: 6px; padding: 1.5rem .7rem; text-align: center; color: var(--ink-soft); margin-bottom: .7rem; } .shot.after .mock-doc { border-style: solid; border-color: var(--accent); background: var(--accent-soft); color: var(--accent); } .mock-note { font-size: .76rem; color: var(--ink-soft); margin-top: .75rem; } .vgroup { margin-bottom: 1.6rem; } .vgroup-head { font-family: var(--mono); font-size: .72rem; letter-spacing: .06em; text-transform: uppercase; color: var(--accent); margin-bottom: .7rem; } .vlist { list-style: none; } .vlist li { position: relative; padding-left: 1.9rem; margin-bottom: .55rem; font-size: .92rem; line-height: 1.45; max-width: 66ch; } .vlist li::before { content: ""; position: absolute; left: 0; top: .18em; width: 15px; height: 15px; border: 1.5px solid var(--ink-soft); border-radius: 4px; } .dials { border: 1px solid var(--line); border-radius: 8px; background: var(--panel); padding: 1.15rem 1.3rem; } .dial { display: grid; grid-template-columns: 118px 1fr; gap: 1rem; align-items: start; padding: .8rem 0; border-bottom: 1px solid var(--line); } .dial:last-child { border-bottom: none; } .dial-label { font-family: var(--mono); font-size: .72rem; letter-spacing: .05em; text-transform: uppercase; color: var(--ink-soft); padding-top: .3rem; } .dial-opts { display: flex; gap: .45rem; flex-wrap: wrap; align-items: center; } .pill { font-size: .82rem; padding: .32rem .72rem; border-radius: 999px; border: 1px solid var(--line); color: var(--ink-soft); } .pill.on { border-color: var(--accent); background: var(--accent-soft); color: var(--accent); font-weight: 600; } .dial-why { flex-basis: 100%; font-size: .8rem; color: var(--ink-soft); margin: .4rem 0 0; } .dials-note { font-size: .8rem; color: var(--ink-soft); margin: .9rem 0 0; } footer { border-top: 1px solid var(--line); margin-top: 3rem; padding-top: 1.25rem; font-size: .8rem; color: var(--ink-soft); } </style>

feature ready zone 1 — substantial

Deliver the explainer on the tracker item

Runs happen on VMs and the user lives in Linear — so the work item's human view (screenshot + self-contained HTML) must live cleanly on the tracker item and stay current as docs accrue.

agent on VM no user screen explainer.html + appended docs, one page screenshot inline image (new) HTML attachment download → renders offline tracker item the user's interface One source, two renditions: inline screenshot for glanceability, attached HTML for full fidelity — both replaced on every update.

01 · Why

The alignment surface doesn't reach the user anymore

The skills' current step — open the explainer in the local browser — assumes the agent and the user share a machine. They don't: runs execute on VMs and the user's window into the work is the Linear ticket, where the explainer currently appears only as a raw marker-comment blob. The human view has to move to the tracker.

Before

• Explainer opens in a browser nobody is looking at
• On the ticket: raw HTML source in a marker comment
• Appended docs readable only as raw markdown

After

• Ticket shows the explainer as an inline image at a glance
• One attached HTML file renders the full page offline, nav included
• Both replaced on every doc append — always current, never stale piles

linear issue

feat: some work item

comment<!-- ORCHESTRA-ARTIFACT … -->

commentraw explainer.html source

Human view = scrolling raw blobs

Before — schematic mockup: presentation and machine payload are the same raw blob.

linear issue

feat: some work item

🖼 explainer screenshot — inline, readable in the ticket

📎 explainer.htmldownload · opens offline

Marker comments remain underneath for agent harvest

After — schematic mockup: clean ticket; machine payload unchanged beneath.

02 · Direction

Locked decisions

D1

Full treatment (inline screenshot + HTML attachment) for trackers with a native upload API — the Linear class. Upload-less trackers (GitHub issues) keep the existing marker-comment mechanism as the documented degraded fallback. Tracker-neutral wording; no hard dependency.

claiming a screenshot embed on GitHub — its API has no issue-upload path, so the promise couldn't be kept.

D2

Two renditions, one source: screenshot for glanceability, attached HTML for fidelity; both regenerated from the same explainer.html and replaced on every change — clean tickets, no accumulation.

D3

No external hosting: no Claude artifacts, no third-party hosts — content goes only to the tracker the repo already publishes to.

Claude artifacts — private-by-default, Claude-harness-only, off-infra copies for every consumer (see TM-393).

D4

Alignment happens wherever the conversation already is: the browser open is attempted everywhere and silently tolerated when no browser exists (daemon/VM); in a Linear-driven session the agent posts the explainer rendition into the session's chat thread and the user's reply is the nod. No path skips the alignment pause itself.

an env-var headless switch — attempt-and-tolerate needs no configuration and can't be set wrong.

D5

The screenshot is best-effort: rendered when a headless browser is available, skipped (HTML attachment still delivered) when not. Publish and alignment never block on a missing renderer — no new hard dependency for consumers.

D6

Machine source of truth unchanged: marker-comment harvest of item.md/refs stays as is; screenshot and attachment are presentation only.

render

explainer + appended docs, one page

→

screenshot

headless render to image

→

deliver

image inline + HTML attached on the ticket

→

refresh

/do re-renders + replaces on append

→

proven

live drive on a scratch item

Indicative sequence — /do's plan stage owns the real plan.

03 · Scope

In and out

In scope

• references/html-explainer.md — delivery + regeneration procedure
• references/publish-work-item.md — screenshot + attachment at publish
• claude/skills/do/SKILL.md — refresh on doc append

Out of scope

• Self-hosted / daemon-hosted viewer (Linear TM-393)
• Claude artifacts / any claude.ai upload
• Invocation gates (separate item: agent-invocable-capture)
• Any daemon/ code change

04 · Verification

What we'll check

Live drive on a scratch item

• AC1 — Linear-class publish carries inline screenshot (renderer available) + HTML attachment; upload-less trackers keep the marker mechanism unchanged
• AC2 — downloaded HTML renders fully offline; nav to each appended doc and back works
• AC3 — after appending a doc: exactly one current screenshot + one current attachment, reflecting the append

Skill-text invariants (review + greps)

• AC4 — Linear session → explainer posted to the chat thread, publish only after the user's reply; local → open attempted, failed open never aborts; no path skips alignment
• AC5 — synced dirs stay consumer-agnostic; no hosting service referenced

05 · Run config

How /do will run this

Zone

0123

Skill-system change (zones.md's named zone-1 case) — it rewires the alignment checkpoint every consumer inherits.

Derived

dual lanescap 3/3frontend verifier — n/aQA (command-shaped)full dossier

Dials derive from references/zones.md; zone agreed with the user at capture.

zone 1 — substantial · Generated by /create-plan · This page is the alignment surface; item.md remains the contract /do executes against.