Add /artifact-tools:eng-recap — the third recap command over the session-artifact pipeline (its fourth framing, counting the skill's own), written for the engineer who has to touch the code next — and register it across the marketplace, tests, and docs.
The two existing recap commands both spend their space translating for non-engineers, which leaves no room for the code paths, tradeoffs, and test coverage a maintainer needs. This adds a third recap command that inverts that rule. We will know it worked when the artifact-tools smoke test passes with eng-recap in its republish-key map.
Read and implement all steps in the plan at docs/plans/add-eng-recap-command.md — Give engineers a recap written for them. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-eng-recap-command.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
More ways to run this plan — goal & workflow prompts, file path
Achieve this goal: Give engineers a recap written for them. The plan at docs/plans/add-eng-recap-command.md describes one approach — use it as reference, but optimize for the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-eng-recap-command.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
add-eng-recap-command.html
docs/plans/add-eng-recap-command.html
docs/plans/add-eng-recap-command.md
Context
The story behind this plan — what prompted the work and why it matters now.
artifact-tools ships two recap commands over one pipeline: product-doc
(stakeholders) and team-recap (whole team, mixed audience). Neither serves an
engineering reader, because both are bound by a translate-for-non-engineers
rule. team-recap states it outright: "Lead every section with the
plain-language statement, then the technical detail. Never the reverse." That
rule is correct for its audience and is exactly what crowds out code paths,
invariants, and rejected tradeoffs.
Decision-complete proposal: docs/proposals/add-eng-recap-command.md. Its five
locked decisions are inputs to this plan, not open questions.
Risk — republish-key collision. All recap writers share one per-session
record under {plansDirectory}/sessions/, distinguished only by a frontmatter
key. A fourth writer that reuses a sibling's key silently republishes over that
sibling's live page. Mitigation: eng-artifact-url: is unique, the command
carries an explicit never-write warning naming the other three keys, and
Step 2 extends the existing test that enforces this.
Risk — context blowout from the diff read. Decision 4 has eng-recap read
diff hunks, which no sibling does. An uncapped gh pr diff on a large PR
consumes the context the recap itself needs. Mitigation: a documented
cap-and-summarize policy modelled on diff-artifact's, asserted by a test.
Files that change
Every file this plan touches, and what happens to each one.
`kit/plugins/artifact-tools/commands/eng-recap.md`new the command file; framing overrides only, no new pipeline`tests/plugins/test-artifact-tools.sh`modified extend checks 7 and 8, add a diff-cap check`.claude-plugin/marketplace.json`modifiedartifact-tools1.6.0 → 1.7.0 and its description`kit/plugins/artifact-tools/CHANGELOG.md`modified[1.7.0]entry`kit/plugins/artifact-tools/README.md`modified Commands table, Usage block, Plugin Structure tree,### eng-recap (command)section`CLAUDE.md`modified theartifact-toolsrow in the reference-implementations table
Steps
The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.
kit/plugins/artifact-tools/commands/eng-recap.md with frontmatter (description, allowed-tools: Skill, Bash) and a body that overrides only framing: Source (session default; PR via #n/URL/--pr n, behind the same gh auth status + git remote get-url origin | grep -qi 'github\.com' preflight emitting PR_MODE_OK/PR_MODE_UNAVAILABLE before any gh pr view), Audience (assume the vocabulary; lead with the technical fact — the inverse of team-recap's rule, stated as such), Sections (At a glance — a stat strip of changes shipped, files touched, decisions, and open items, plus two or three sentences on where the work landed; Architecture and code paths; Decisions with rationale; Tradeoffs and rejected options; Learnings; Tests and verification; Review follow-ups and tech debt; Files touched), Visual requirements and Destination (copied from team-recap: mermaid in <pre class="mermaid">, the SVG-inlining procedure, save-artifact handoff, stem eng-recap / pr-<number>-eng), and Republish key (eng-artifact-url: plus a "Never write" line naming artifact-url:, product-artifact-url:, and team-artifact-url:).
head -6 shows a valid frontmatter block, and grep -c 'eng-artifact-url' kit/plugins/artifact-tools/commands/eng-recap.md returns at least 2.gh pr diff for at most 20 files, fall back to --name-only for the remainder, and report how many files were summarized rather than read — commit bodies still lead for the why, hunks only supply the what.
eng-recap departs from both siblings, and an uncapped diff read reintroduces exactly the context blowout session-artifact avoids by refusing to read the JSONL directly.--name-only fallback in the same section.tests/plugins/test-artifact-tools.sh: add "commands/eng-recap.md": "eng-artifact-url" to check 7's owners map, raise check 8's assert found >= 2 to >= 3 with a message naming all three PR-mode commands, and add a new check asserting eng-recap.md documents both a numeric diff cap and the --name-only fallback.
bash tests/plugins/test-artifact-tools.sh prints PASS with a higher check count than before.eng-artifact-url to team-artifact-url in eng-recap.md, run the suite, confirm it FAILs on the key collision, then revert.
git diff --stat kit/plugins/artifact-tools/commands/eng-recap.md empty relative to step 2's state.artifact-tools to 1.7.0 in .claude-plugin/marketplace.json, extend its description to mention the engineering recap, and add a [1.7.0] Added entry to kit/plugins/artifact-tools/CHANGELOG.md in Keep a Changelog form, naming the command, its sections, the eng-artifact-url: key, and the diff budget.
python3 -c "import json;print([p['version'] for p in json.load(open('.claude-plugin/marketplace.json'))['plugins'] if p['name']=='artifact-tools'])" prints ['1.7.0'], and BASE_REF=main node scripts/check-plugin-versions.mjs passes.kit/plugins/artifact-tools/README.md in all four places it lists commands — the Commands table row, the Usage block, the Plugin Structure tree comment, and a new ### eng-recap (command) subsection after ### team-recap (command) — then update the artifact-tools row in the root CLAUDE.md reference-implementations table.
grep -c 'eng-recap' kit/plugins/artifact-tools/README.md returns at least 4, and grep -c 'eng-recap' CLAUDE.md returns at least 1.Tests
The tests that prove the change does what it promises.
/artifact-tools:eng-recap exists as a complete, registered, collision-free command — the plan's stated objective. File: tests/plugins/test-artifact-tools.sh; Type: smoke; Asserts: commands/eng-recap.md exists with valid frontmatter, carries all eight agreed section headings, owns eng-artifact-url and warns against writing all three sibling keys, guards its gh calls behind the preflight, and documents the 20-file diff cap with its --name-only fallback; and that artifact-tools is registered at a version matching the CHANGELOG. Run: bash tests/plugins/test-artifact-tools.shtests/plugins/test-artifact-tools.sh; Targets: check 7's owners map across session-artifact/SKILL.md, product-doc.md, team-recap.md, eng-recap.md; Key cases: each writer declares its own key; each sibling key it mentions sits under a never-write warning; a command whose key is swapped for a sibling's fails the check.tests/publish/test-check-plugin-versions.mjs; Targets: scripts/check-plugin-versions.mjs; Key cases: artifact-tools at 1.7.0 is accepted against a 1.6.0 base; an unbumped 1.6.0 is rejected.Definition of done
The plan counts as done when every statement below is true — check each one off as you verify it.
Final check
One last pass to confirm the whole change works end to end.
End-to-end, in order:
1. bash tests/plugins/test-artifact-tools.sh — PASSes, with a check count higher than the pre-change run.
2. BASE_REF=main node scripts/check-plugin-versions.mjs — passes, confirming the bump is visible to the guard that gates merges.
3. Break it deliberately: swap eng-artifact-url for team-artifact-url in eng-recap.md and re-run the suite. It must FAIL on the key collision. Revert. This is the step that proves the new coverage is real rather than decorative.
4. Load the plugin (claude --plugin-dir ./kit/plugins/artifact-tools) and confirm /artifact-tools:eng-recap is listed alongside /artifact-tools:product-doc and /artifact-tools:team-recap.
5. Read eng-recap.md end-to-end against team-recap.md and confirm it overrides framing only — no duplicated transcript extraction, scrub gate, or publish logic.
Wrapping up
Three gates that must all pass before this plan is marked completed.
Completion Report
- Verification step 4 (
claude --plugin-dir ./kit/plugins/artifact-tools, confirm the command is listed) - verified by proxy, not directly. Launching an interactive Claude Code session was not available in this run, so the check was made structurally instead: all three command files under
commands/parse to valid frontmatter with adescription, which is what plugin loading reads. Every acceptance criterion was verified directly; this one verification step was not.