docs: slim root CLAUDE.md, move detail to scoped CLAUDE.mds + skills#38
Merged
Conversation
Root CLAUDE.md is loaded every turn — make it an index + cross-cutting invariants, not a reference manual. - New scoped CLAUDE.mds (auto-loaded by Claude Code in their dirs): - src/fetchers/CLAUDE.md — hard invariants + security checklist - src/mcp/CLAUDE.md — stdio/lock/error-envelope invariants - New pupila-* skills under .claude/skills/ (ship with the repo): - pupila-fetchers — adding a fetcher, tier-S slugs, upstream issues - pupila-mcp-tools — 4-step recipe for adding an MCP tool - pupila-filters — tuning weights, _signals debugging, scoring tiers - pupila-ai-review — review pipeline, brief lever, AI Apply - .gitignore: keep .claude/ local-only except pupila-* skills (ship) - Root CLAUDE.md: drop ~600 lines moved into the above; add a "Where things live" index pointing to each
The skill and the scoped CLAUDE.md split the same concern by audience (procedure vs invariants) but always fire together — every tool change edits files in src/mcp/ anyway. Consolidating into the scoped CLAUDE.md removes the "Hard invariants (refresher)" duplication and gives one auto-loading home for both.
No content removed. Stack, repo layout, and code-level docs converted from bullets/ASCII tree to tables for scanability. New 'Orchestrator flow' section walks the `pnpm run dev` pipeline step-by-step instead of leaving it implicit. Stale test count (192) fixed to 330.
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.
Summary
Root
CLAUDE.mdis loaded into every session's context. It had grown into a reference manual (~600 lines covering fetcher steps, MCP invariants, filter tuning, AI review internals). This PR slims it to index + cross-cutting invariants and pushes the detail to where it's actually needed.CLAUDE.mds (auto-loaded by Claude Code only when working in that directory):src/fetchers/CLAUDE.md— hard invariants + security checklist (fetchers must never throw, safe HTTP wrappers,isSafeUrl,stripHtml, etc.)src/mcp/CLAUDE.md— stdio/JOB_ID/lock/error-envelope invariantspupila-*skills under.claude/skills/(committed so contributors get them):pupila-fetchers— adding a fetcher, tier-S slugs, known upstream issuespupila-mcp-tools— 4-step recipe for adding an MCP toolpupila-filters— tuning weights,_signalsdebugging, scoring tiers referencepupila-ai-review— review pipeline, brief lever, AI Apply, provider-switching.gitignore— keep.claude/local-only by default but allow.claude/skills/pupila-*/to ship.CLAUDE.md— drops ~600 lines, adds a "Where things live" index pointing into each scoped file or skill. While editing, fixed a few stale facts (TypeScript 6 not 5.9, Vitest 4 / 330 cases not Vitest 3 / 192, pre-commit also runslint:ui-patterns, CI has 7 gates incl. bundle-size).Test plan
pnpm run lint— cleanpnpm run typecheck— cleanpnpm run lint:ui-patterns— cleanavailable-skillsafter install)