Skip to content

docs: add /health and /checkpoint to README (v0.16.2.2)#952

Closed
ignsm wants to merge 8 commits intogarrytan:mainfrom
ignsm:docs/checkpoint-health-readme
Closed

docs: add /health and /checkpoint to README (v0.16.2.2)#952
ignsm wants to merge 8 commits intogarrytan:mainfrom
ignsm:docs/checkpoint-health-readme

Conversation

@ignsm
Copy link
Copy Markdown

@ignsm ignsm commented Apr 10, 2026

Summary

Follow-up to #951. Both /health and /checkpoint have been working skills for a while — health/SKILL.md and checkpoint/SKILL.md live on disk, have clean frontmatter with trigger phrases, and ./setup already registers them into ~/.claude/skills/ on every install. But they were completely absent from the README in all three user-facing places: the install command skill list (line 49), the CLAUDE.md example skill list (line 398), and the big skill table (around line 186). New users had no way to discover them.

This PR closes that gap. All three places now mention both skills.

Stacking note

This is a stacked PR on top of #951 (fix/ngrok-external-in-node-bundle). #951 aligned the two README skill-list blocks and added /pair-agent, /plan-devex-review, /devex-review. This PR builds on that cleanup to add the remaining two skills in one coherent pass.

Until #951 merges, this PR's diff will show all 4 commits from #951 plus the 4 new commits here. Once #951 merges to main, GitHub will auto-rebase this PR and only the 4 new commits will remain. No manual rebase needed.

If you want to review just this PR's delta: check commits 12c7bbf1, 0f7e5222, 89fe0a4c, fd6d4f6e.

Bisection

Four clean commits, each independently revertable:

  1. 12c7bbf1docs: add /health and /checkpoint rows to README skill table
    • Adds one row for each skill to the big sprint skill table. /health after /benchmark (both measurement/dashboard tools). /checkpoint after /learn (both session/state persistence tools).
    • Specialist role choices: /health → "Quality Engineer" (sits alongside "Performance Engineer" for /benchmark). /checkpoint → "Session Bookmark" (avoids collision with /learn's "Memory" role since they're adjacent).
    • Voice matches the existing table: one-line role, two-to-three-sentence description emphasizing what the user can DO and the concrete trigger phrase.
  2. 0f7e5222docs: add /health and /checkpoint to both README skill-list blocks
    • Adds both skills to the install command block (line 49) and the CLAUDE.md example block (line 398). Same placement as the table: /health after /benchmark, /checkpoint after /learn.
    • Both blocks now list the same 36 skills in the same order (verified via extracted-list diff).
  3. 89fe0a4cdocs: mark /checkpoint + /health README TODO as done
    • Removes the ## Documentation section from TODOS.md (it existed only to hold this one entry) and moves the entry to ## Completed with a v0.16.2.2 marker.
  4. fd6d4f6echore: bump version and changelog (v0.16.2.2) (VERSION + CHANGELOG.md)

Test Coverage

No new code paths — this is a pure documentation change across 3 files (README.md, TODOS.md, CHANGELOG.md) and a VERSION bump. No application logic, no build scripts, no runtime behavior changes.

Both skills were manually verified to exist and register correctly on the /Users/ignat/GitHub/gstack checkout before writing the table rows:

  • health/SKILL.md lines 1-13 (frontmatter with description, allowed-tools, trigger phrases)
  • checkpoint/SKILL.md lines 1-13 (frontmatter with description, allowed-tools, trigger phrases)
  • ./setup output on the upgrade session that surfaced this gap confirmed both skills land in ~/.claude/skills/checkpoint/SKILL.md and ~/.claude/skills/health/SKILL.md as working top-level slash commands.

Pre-Landing Review

No issues. 5 substantive line edits across README.md (2 new table rows, 2 skill-list string updates) + 14 lines added/removed in TODOS.md + 3 lines in VERSION/CHANGELOG. No attack surface, no runtime effect, no regression risk.

Voice calibration

Both descriptions were written to match the existing skill table voice:

  • Lead with what the user can DO, not with the implementation.
  • Include the concrete trigger phrase in quotes so the reader knows how to activate the skill.
  • Avoid AI vocabulary (no "leverage", "robust", "comprehensive"). No em dashes in the new text (matches CLAUDE.md writing rules).
  • Pick a specialist role that doesn't collide with adjacent table entries. /learn is already "Memory", so /checkpoint is "Session Bookmark". /benchmark is already "Performance Engineer", so /health is "Quality Engineer".

Test plan

  • grep "^## \[" CHANGELOG.md shows contiguous version sequence (verified — 0.16.2.2, 0.16.2.1, 0.16.2.0, 0.16.1.0, ...)
  • Both README skill-list blocks contain the same 36 skills (verified via extracted-list diff: install block and CLAUDE.md example block both produce identical sorted lists)
  • /health and /checkpoint appear in all three places: install block (line 49), CLAUDE.md example (line 398-403), big skill table (after /benchmark and after /learn respectively)
  • Both skills resolve to real SKILL.md files: health/SKILL.md exists, checkpoint/SKILL.md exists, ./setup links both into ~/.claude/skills/ (confirmed from prior setup run on the upgrade session)

🤖 Generated with Claude Code

ignsm and others added 8 commits April 10, 2026 16:47
./setup was emitting a non-fatal but ugly error during the Windows
Node.js fallback bundle step:

  Building Node-compatible server bundle...
  error: cannot write multiple output files without an output directory

Root cause: browse/src/server.ts dynamically imports @ngrok/ngrok for
/pair-agent tunneling. Bun's bundler statically sees the import and
tries to inline ngrok's prebuilt native .node binaries (darwin-universal
19MB + darwin-arm64 9MB + win32-x64 etc.) as separate asset files. But
build-node-server.sh uses --outfile, which only supports a single output
file. Bun fails with "cannot write multiple output files" before writing
anything.

Fix: mark @ngrok/ngrok as --external in the Node bundle build, matching
how we already handle playwright and playwright-core. Windows Node
users who want pair-agent tunneling install @ngrok/ngrok separately —
same model as playwright.

Verified: bash browse/scripts/build-node-server.sh now produces a
clean single server-node.mjs (0.31 MB, 23 modules) with no errors.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
…t /plan-devex-review /devex-review

The README had two separate skill lists that drifted out of sync:

1. Install command block (line 49) listed /connect-chrome (legacy name),
   /plan-devex-review, /devex-review but was missing /pair-agent.
2. CLAUDE.md example block (line 396) listed /open-gstack-browser,
   /pair-agent but was missing /plan-devex-review and /devex-review.

Fix: both lists now contain the same 34 skills in the same order:
- Replace legacy /connect-chrome with canonical /open-gstack-browser
  (the skill was renamed; /connect-chrome is still a symlink alias but
  shouldn't be the advertised name).
- Add /pair-agent to the install block.
- Add /plan-devex-review and /devex-review to the CLAUDE.md example.

Users pasting either block into a new project's CLAUDE.md now get the
full set of available skills without gaps.

Note: /checkpoint and /health are real user-facing skills that exist on
disk and get linked by ./setup but are still not mentioned anywhere in
the README (not in either skill list block, not in the skill table).
Left for a follow-up PR — this one stays narrowly scoped to aligning the
two existing list strings.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Both skills exist on disk, get linked by ./setup, and show up in
~/.claude/skills/ — but they're not mentioned anywhere in the README
(no install-block entry, no CLAUDE.md example entry, no skill table row).

This TODO captures the follow-up PR that would add them in all three
places. Kept out of this branch to preserve narrow scope: the two
skill-list strings are now aligned, but a proper fix for /checkpoint
and /health needs two new rows in the big skill table too, with
descriptions matching the existing table voice.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Both skills exist on disk at health/SKILL.md and checkpoint/SKILL.md,
get registered by ./setup on every install, and show up in
~/.claude/skills/ as working slash commands. But they were completely
absent from the README big skill table — new users had no way to
discover them.

Placement rationale:
- /health slots after /benchmark (both are measurement/dashboard tools
  that produce a score for the codebase).
- /checkpoint slots after /learn (both are session/state persistence
  tools — /learn for cross-session learnings, /checkpoint for within-
  project resume state).

Specialist roles:
- /health → "Quality Engineer" (sits alongside "Performance Engineer"
  for /benchmark and "Staff Engineer" for /review).
- /checkpoint → "Session Bookmark" (avoids collision with /learn's
  "Memory" role since they're adjacent in the table).

Voice matches the existing table: one-line role, two-to-three-sentence
description emphasizing what the user can DO and the concrete trigger
phrase.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Now that the big skill table has rows for both, keep the two skill-list
strings (the install command block and the CLAUDE.md example block)
consistent with the table. Both strings list the same 36 skills in the
same order.

Placement:
- /health slots after /benchmark (same rationale as the table row
  commit: both measurement/dashboard tools).
- /checkpoint slots after /learn (same rationale: session/state tools
  grouped at the end of the list).

Users who paste either block into a new project's CLAUDE.md now get
the full set of 36 skills that ./setup actually installs.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Remove the TODO added in commit 1680079 (the ## Documentation section
holding the single "Add /checkpoint and /health to README" entry) and
move it to the ## Completed section at the bottom with the v0.16.2.2
marker.

This keeps TODOS.md tidy: the ## Documentation section existed only to
hold this one item, so removing it collapses cleanly. The ## Completed
entry documents what shipped so the history is still visible.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
@ignsm
Copy link
Copy Markdown
Author

ignsm commented Apr 10, 2026

Closing this along with its parent #951. The README work from this PR (adding /health and /checkpoint to both skill-list blocks and the big skill table) has been combined with the skill-list alignment from #951 into a single clean README-only PR: #953.

The split into a parent + stacked follow-up didn't make sense once #951 turned out to duplicate open build-fix PRs #924 and #947. #953 is the correct final shape: one branch from fresh main, three bisected commits, no overlap with any build-fix work in flight.

@ignsm ignsm closed this Apr 10, 2026
@ignsm ignsm deleted the docs/checkpoint-health-readme branch April 10, 2026 08:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant