Team recap command for artifact-tools

At a glance

1New command

5Files touched

4Decisions

1Open item

/artifact-tools:team-recap joins the plugin as a third way to write up a session. It ships as a thin wrapper over the existing recap machinery rather than as a new component, so the plugin’s blocking secret scan stays in exactly one place. A new test guards against a failure the wrapper pattern invites: three commands writing to one file, and a copied one quietly publishing over another’s page.

What changed

For everyone

A session recap the whole team can read

The plugin already had two framings: one written for code reviewers, one for product and stakeholders. Neither targets a mixed audience, and neither asks for anything visual. The new command does both — one page carrying a stat strip, a card per change, diagrams of anything whose shape changed, a before-and-after table, decisions with the options that lost, learnings, open items, files touched, and a glossary of every internal term it uses.

How to reach it

/artifact-tools:team-recap                 # the newest session
/artifact-tools:team-recap <session-id>    # a specific one

For maintainers

A guard against overwriting a page that was already shared

The plugin’s smoke test gained a twelfth check: each of the three recap writers must declare its own distinct republish key. Adding a fourth by copying an existing one now fails the test instead of silently taking over another recap’s published link — a bug that stays invisible until someone opens a link you sent last week and finds the wrong document.

How it works now

All three framings funnel into the same scan gate. That is the whole reason the new one is a command and not a fourth skill — a new skill would have meant a second copy of the gate.

Three keys, one file. All three commands read and write the same record for a given session, so each needs its own key inside it. A copied wrapper that forgets to rename its key republishes over whichever page already owned it.

Before and after

	Before	After
Recap framings	Reviewer recap, product doc	Plus a whole-team visual recap
Audience assumed	One or the other — engineer or non-engineer	Both, in a single document
Visuals	None specified	Diagrams required where structure or flow changed, each captioned
Diagram technology	n/a	Mermaid only — the artifact security policy blocks external scripts and assets
Adding a fourth wrapper	Copy one; a duplicated key still passes tests	A duplicated key fails the smoke test
Plugin version	1.4.0	1.5.0

Decisions

A command wrapping the existing skill, not a fourth skill

The expensive and risky parts of a recap — locating the transcript, extracting it without flooding the working context, the blocking secret scan, publishing, verifying the page actually rendered — are already written. A new skill would have duplicated all of it, and duplicating a security gate is the specific thing worth never doing.

Rejected: a standalone team-artifact skill. Roughly four times the material for the same output, with two copies of the gate.

Mermaid diagrams, no charting library

Published pages render mermaid natively, and a strict security policy blocks external scripts, stylesheets, fonts, and remote images outright. There was no library option to weigh — the built-in feature is also the only one that works.

Its own republish key, `team-artifact-url:`

The session record’s filename is fixed per session, so all three commands land on the same file. A shared key would mean whichever command ran second republished over the first one’s page.

The test hardcodes which file owns which key

The first version tried to infer ownership from the prose of each file. It failed on the first run, because every file deliberately names the other keys in its don’t-write warning. Replacing the inference with a fixed map of file to expected key is shorter, has no parser to maintain, and still catches the realistic bug.

Learnings

A pattern-match over prose is a parser, and a parser inside a test is a liability

The ownership-inference check was written, run, and thrown out inside a single iteration. The failure was immediate and unambiguous, which is the good case; the lesson is that the blunt hardcoded assertion should have been the first attempt, not the second.

A test that has never failed has not been tested

The new check was verified by copying the plugin to a temporary directory, corrupting the new command so it reused the product key, and confirming the assertion fired. Passing on correct input proves nothing by itself.

Three variants sharing one state file is a real hazard, not a hypothetical one

It only surfaces after a link has been shared and gone stale — exactly the kind of failure that needs a mechanical guard rather than a warning in a document.

Open items

The command has not yet been run as a command

This page is the first exercise of the workflow it describes, and it was carried out by hand from the command’s own instructions — a newly written command file is not loaded as a slash command in the session that created it. A fresh session should invoke /artifact-tools:team-recap directly to confirm it dispatches, then run it a second time to confirm the republish key sends the update to this same page rather than minting a new link.

One thing that run will also settle: the extractor names the session record after the session id, and the repository’s filename rule rejects that name. This record was renamed by hand to add-team-recap-command-session.md.

Files touched

The command

kit/plugins/artifact-tools/commands/team-recap.md new Audience rules, the visual constraints, the nine sections, where the page gets filed, and the republish key.

The guard

tests/plugins/test-artifact-tools.sh Twelfth check — the three recap writers must declare distinct republish keys.

Metadata and docs

.claude-plugin/marketplace.json 1.4.0 to 1.5.0. Adding a command is a minor bump.
kit/plugins/artifact-tools/CHANGELOG.md The 1.5.0 entry.
kit/plugins/artifact-tools/README.md Features table, usage examples, directory tree, and a section describing the command.
CLAUDE.md The repository’s plugin table now names the command.

Glossary

Artifact: A self-contained web page published from a working session. Private by default; the author chooses whether to share the link.
Command: A plugin part invoked by name, as /plugin:command. A skill, by contrast, activates on its own when a request matches its description.
Content security policy: The browser rules that stop a published page loading anything from an outside server. It is why diagrams use a built-in feature rather than a downloaded library.
Marketplace: The registry listing every plugin in this repository with its version. It is what people install from.
Mermaid: A plain-text way of writing diagrams. Published pages turn it into graphics with no extra tooling.
Republish key: A line in a session’s saved record holding the address of an already-published page, so running a command again updates that page instead of creating a second one.
Scan gate: The mandatory secret scan that runs before anything is published. A finding stops the publish outright; there is no override.
Semantic versioning: The convention behind 1.4.0 to 1.5.0 — the middle number rises when something is added, the last when something is fixed.
Session record: The committed Markdown file summarising a session, kept with the project’s plans. It is the durable copy; the published page is rendered from it.
Smoke test: A fast script checking that a component’s basic structure is intact. This plugin’s now runs twelve such checks.

Rendered by /artifact-tools:team-recap · source: docs/plans/sessions/add-team-recap-command-session.md
Live version: claude.ai/code/artifact/a38b5451