docs: activation guidance, generated catalog, and roadmap#16
Merged
Conversation
… and roadmap A fresh session pointed at the repo loads CLAUDE.md but NOT the plugin components — skills/agents/commands/hooks are inert unless the kit is installed. CLAUDE.md previously described the branch-workflow guards as if always active, which is misleading in a bare repo session. Close the orientation gaps: - CLAUDE.md: new "Activation — installed vs. just open in the repo" section (components are inert until /plugin install; git hooks need `git config core.hooksPath .githooks`). Make the Branch-workflow guards explicitly conditional on the plugin being installed. - docs/CATALOG.md: generated inventory of every skill/agent/command/hook/rule via tests/gen-catalog.py. tests/validate-catalog.sh (wired into run-all.sh + CI) fails if it drifts; refresh with `python3 tests/gen-catalog.py`. - ROADMAP.md: standing north-star (current focus, recently done, candidates, manual follow-ups) so a fresh session has persistent direction, not just conventions. Referenced from CLAUDE.md → Activation. - README: catalog pointer, the installed-vs-open caveat, and a "Developing this repo" setup note. https://claude.ai/code/session_01U6H3oa4GEngboKuc8jvwC3
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes the orientation/legibility gaps surfaced by the question "if I started a fresh session pointed at this repo, would it be clear what to do and what rules/hooks/skills are in place?"
The core finding: being pointed at the repo ≠ having the plugin installed. A bare repo session loads
CLAUDE.mdand.claude/settings.json, but the 134 skills / 39 agents / 59 commands / hooks are inert until the kit is installed as a plugin. YetCLAUDE.mddescribed the branch-workflow guards (no-commit-to-main, auto-PR, auto-merge) as if always active — a trust gap, since Claude might assumemainis protected when it isn't.Changes
Activation clarity (the trust-gap fix)
CLAUDE.md: new "Activation — installed vs. just open in the repo" section — components are inert until/plugin install; the repo-local git hooks needgit config core.hooksPath .githooks.Legibility — generated catalog
docs/CATALOG.md: full inventory (134 skills · 39 agents · 59 commands · 7 hook events · 34 rule files) with one-line descriptions, generated bytests/gen-catalog.py.tests/validate-catalog.sh(inrun-all.sh+ CI) fails if the catalog drifts; refresh withpython3 tests/gen-catalog.py.Standing intent
ROADMAP.md: north-star (current focus / recently done / reviewed-but-unchosen candidates / manual owner follow-ups), referenced fromCLAUDE.md→ Activation.README: catalog pointer, the installed-vs-open caveat, and a "Developing this repo" setup note.
Verification
tests/run-all.shgreen — all six validators pass, including the new catalog freshness check. CI (validate.yml) will run the same suite on this PR.https://claude.ai/code/session_01U6H3oa4GEngboKuc8jvwC3
Generated by Claude Code