Add CLAUDE.md with repo architecture and dev guidance - #8
Conversation
Documents the plugin/config structure, hook config-vs-implementation split, package manager detection, and authoring conventions for future Claude Code sessions working in this repo. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughAdded ChangesRepository Guidance
Estimated code review effort: 1 (Trivial) | ~3 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Line 28: Update the source-code guidance in CLAUDE.md to acknowledge the
substantial inline Node implementations in hooks/hooks.json, including the
PostToolUse PR parser, TypeScript check, and Stop Git scan. State that
scripts/hooks/ is the preferred location for new non-trivial hook logic, or
migrate those existing handlers there while preserving their behavior.
- Around line 47-49: Update the documentation near the statement about agents/,
commands/, rules/, and skills/ to acknowledge the existing cross-file contracts,
including skill, context, and /setup-pm script references. Replace the claim of
no cross-file coupling with guidance to search and update all references before
renaming or moving files, directories, or paths.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| directly executable and prints pass/fail counts; `tests/run-all.js` just shells out to each one in turn and | ||
| aggregates results. | ||
|
|
||
| There is no lint/build/typecheck step — the only "source code" is the hook implementation under `scripts/`. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Correct the documented source-code boundary.
CLAUDE.md says that the only source code is under scripts/ and that non-trivial hook logic uses scripts/hooks/. However, hooks/hooks.json contains substantial inline Node implementations, including the PostToolUse PR parser, the TypeScript check, and the Stop Git scan. Clarify that this is the preferred rule for new hooks, or move these existing handlers into scripts.
Also applies to: 53-65
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` at line 28, Update the source-code guidance in CLAUDE.md to
acknowledge the substantial inline Node implementations in hooks/hooks.json,
including the PostToolUse PR parser, TypeScript check, and Stop Git scan. State
that scripts/hooks/ is the preferred location for new non-trivial hook logic, or
migrate those existing handlers there while preserving their behavior.
| Everything under `agents/`, `commands/`, `rules/`, `skills/` is a leaf config file (or small directory for | ||
| multi-file skills) — there's no cross-file coupling between them beyond naming conventions, so most changes | ||
| are additive and isolated to a single file. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Document the existing cross-file contracts.
The statement that these directories have no cross-file coupling is incorrect. Line 37 documents skill references from commands and agents. Line 43 documents context references from hooks and commands. Lines 78-79 document the /setup-pm reference to scripts/setup-package-manager.js. A rename or move can break these references. Replace this statement with guidance to check references before changing names or paths.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` around lines 47 - 49, Update the documentation near the statement
about agents/, commands/, rules/, and skills/ to acknowledge the existing
cross-file contracts, including skill, context, and /setup-pm script references.
Replace the claim of no cross-file coupling with guidance to search and update
all references before renaming or moving files, directories, or paths.
1 participant
Summary
Test plan
node tests/run-all.jspasses (62/62)Summary by CodeRabbit