@mrclrchtr/supi-claude-md 0.1.0

package/skills/claude-md-revision/references/quality-criteria.md

@@ -0,0 +1,114 @@
+# CLAUDE.md Quality Criteria
+
+## Scoring Rubric
+
+### 1. Commands/Workflows (15 points)
+
+**15 points**: All essential commands documented with context
+- Build, test, lint, deploy commands present
+- Development workflow clear
+- Common operations documented
+
+**12 points**: Most commands present, some missing context
+
+**8 points**: Basic commands only, no workflow
+
+**4 points**: Few commands, many missing
+
+**0 points**: No commands documented
+
+### 2. Architecture Clarity (15 points)
+
+**15 points**: Clear codebase map
+- Key directories explained
+- Module relationships documented
+- Entry points identified
+- Data flow described where relevant
+
+**12 points**: Good structure overview, minor gaps
+
+**8 points**: Basic directory listing only
+
+**4 points**: Vague or incomplete
+
+**0 points**: No architecture info
+
+### 3. Non-Obvious Patterns (15 points)
+
+**15 points**: Gotchas and quirks captured
+- Known issues documented
+- Workarounds explained
+- Edge cases noted
+- "Why we do it this way" for unusual patterns
+
+**10 points**: Some patterns documented
+
+**5 points**: Minimal pattern documentation
+
+**0 points**: No patterns or gotchas
+
+### 4. Conciseness (15 points)
+
+**15 points**: Dense, valuable content
+- No filler or obvious info
+- Each line adds value
+- No redundancy with code comments
+
+**10 points**: Mostly concise, some padding
+
+**5 points**: Verbose in places
+
+**0 points**: Mostly filler or restates obvious code
+
+### 5. Currency (15 points)
+
+**15 points**: Reflects current codebase
+- Commands work as documented
+- File references accurate
+- Tech stack current
+
+**10 points**: Mostly current, minor staleness
+
+**5 points**: Several outdated references
+
+**0 points**: Severely outdated
+
+### 6. Actionability (15 points)
+
+**15 points**: Instructions are executable
+- Commands can be copy-pasted
+- Steps are concrete
+- Paths are real
+
+**10 points**: Mostly actionable
+
+**5 points**: Some vague instructions
+
+**0 points**: Vague or theoretical
+
+### 7. Auto-Delivered Overlap (10 points)
+
+Score this criterion after a **context baseline review**: compare the CLAUDE.md against what a SuPi-enabled PI session likely already has from `code_intel brief` and other known injected context.
+
+**10 points**: Almost no overlap. Any overlap is tiny and clearly justified by human-only reasoning.
+
+**7 points**: Some overlap, but the file still adds meaningful unique guidance (for example, a partially redundant structure section that keeps ownership rules or a concise "start here" note).
+
+**4 points**: Significant overlap — package tables, root project-structure trees, architecture overviews, or dependency graphs duplicate the baseline context and should be compressed.
+
+**0 points**: Large sections are almost entirely duplicated generated context (module lists with descriptions, dense dependency tables, long root directory trees).
+
+**What is NOT overlap:** Gotchas specific to a package's behavior; cross-package patterns that aren't discoverable from manifests; commands and workflows; human-curated "Start Here" guidance with reasoning; concise structure notes that explain boundaries, ownership, initialization order, or important exceptions; and sections classified as **unique** during the baseline review.
+
+**What IS overlap:** Monorepo package tables where every row is `{name, description, path}`; root-level "Modules" or "Packages" sections with >5 entries; the **fully redundant** portion of a section during baseline review; root `## Project structure` / `## Architecture` trees that mostly restate folders, packages, or module layout already visible from `code_intel brief`; high-level architecture overviews that don't add relationships, gotchas, conventions, or exceptions beyond what's in `package.json`; and dependency graphs that could be generated from `pnpm-workspace.yaml`.
+
+## Assessment Process
+
+1. Read the CLAUDE.md file completely.
+2. If SuPi is active, perform a **context baseline review** first: compare against `code_intel brief` and other known injected context, then classify sections as **fully redundant**, **partially redundant**, or **unique**.
+3. Cross-reference with the actual codebase: run documented commands (mentally or actually), check that referenced files exist, and verify architecture descriptions.
+4. Score each criterion, calculate the total, assign the grade, list the specific issues, and propose concrete improvements.
+
+## Red Flags
+
+Watch for commands that would fail (wrong paths, missing deps), references to deleted files or folders, outdated tech versions, template copy without customization, generic advice, stale `TODO` items, duplicate info across multiple CLAUDE.md files, sections that duplicate `code_intel brief` output, and structure sections where the redundant tree/inventory portion should be separated from the unique guidance portion.

package/skills/claude-md-revision/references/templates.md

@@ -0,0 +1,300 @@
+# CLAUDE.md Templates
+
+## Key Principles
+
+- **Concise**: Dense, human-readable content; one line per concept when possible
+- **Actionable**: Commands should be copy-paste ready
+- **Project-specific**: Document patterns unique to this project, not generic advice
+- **Current**: All info should reflect actual codebase state
+
+---
+
+## Recommended Sections
+
+Use only the sections relevant to the project. Not all sections are needed.
+
+### Commands
+
+Document the essential commands for working with the project.
+
+```markdown
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `<install command>` | Install dependencies |
+| `<dev command>` | Start development server |
+| `<build command>` | Production build |
+| `<test command>` | Run tests |
+| `<lint command>` | Lint/format code |
+```
+
+### Architecture
+
+Describe the project structure so Claude understands where things live.
+
+```markdown
+## Architecture
+
+```
+<root>/
+  <dir>/    # <purpose>
+  <dir>/    # <purpose>
+  <dir>/    # <purpose>
+```
+```
+
+### Key Files
+
+List important files that Claude should know about.
+
+```markdown
+## Key Files
+
+- `<path>` - <purpose>
+- `<path>` - <purpose>
+```
+
+### Code Style
+
+Document project-specific coding conventions.
+
+```markdown
+## Code Style
+
+- <convention>
+- <convention>
+- <preference over alternative>
+```
+
+### Environment
+
+Document required environment variables and setup.
+
+```markdown
+## Environment
+
+Required:
+- `<VAR_NAME>` - <purpose>
+- `<VAR_NAME>` - <purpose>
+
+Setup:
+- <setup step>
+```
+
+### Testing
+
+Document testing approach and commands.
+
+```markdown
+## Testing
+
+- `<test command>` - <what it tests>
+- <testing convention or pattern>
+```
+
+### Gotchas
+
+Document non-obvious patterns, quirks, and warnings.
+
+```markdown
+## Gotchas
+
+- <non-obvious thing that causes issues>
+- <ordering dependency or prerequisite>
+- <common mistake to avoid>
+```
+
+### Workflow
+
+Document development workflow patterns.
+
+```markdown
+## Workflow
+
+- <when to do X>
+- <preferred approach for Y>
+```
+
+---
+
+## Template: Project Root (Minimal)
+
+```markdown
+# <Project Name>
+
+<One-line description>
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `<command>` | <description> |
+
+## Architecture
+
+```
+<structure>
+```
+
+## Gotchas
+
+- <gotcha>
+```
+
+---
+
+## Template: Project Root (Comprehensive)
+
+```markdown
+# <Project Name>
+
+<One-line description>
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `<command>` | <description> |
+
+## Architecture
+
+```
+<structure with descriptions>
+```
+
+## Key Files
+
+- `<path>` - <purpose>
+
+## Code Style
+
+- <convention>
+
+## Environment
+
+- `<VAR>` - <purpose>
+
+## Testing
+
+- `<command>` - <scope>
+
+## Gotchas
+
+- <gotcha>
+```
+
+---
+
+## Template: Package/Module
+
+For packages within a monorepo or distinct modules.
+
+```markdown
+# <Package Name>
+
+<Purpose of this package>
+
+## Usage
+
+```
+<import/usage example>
+```
+
+## Key Exports
+
+- `<export>` - <purpose>
+
+## Dependencies
+
+- `<dependency>` - <why needed>
+
+## Notes
+
+- <important note>
+```
+
+---
+
+## Template: Monorepo Root
+
+```markdown
+# <Monorepo Name>
+
+<Description>
+
+## Packages
+
+| Package | Description | Path |
+|---------|-------------|------|
+| `<name>` | <purpose> | `<path>` |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `<command>` | <description> |
+
+## Cross-Package Patterns
+
+- <shared pattern>
+- <generation/sync pattern>
+```
+
+> ⚠️ **When SuPi is active:** The `## Packages` table in this template is auto-generated by `code_intel brief` on the first turn. Consider omitting it or replacing it with `## Start Here` and `## Cross-Package Patterns` sections that capture conventions not visible in manifests.
+
+---
+
+## Template: SuPi-Optimized Project Root
+
+For projects using SuPi extensions (`code-intelligence`, `claude-md`). Omits sections that extensions auto-deliver and favors compressed human-only guidance after a baseline overlap review.
+
+```markdown
+# <Project Name>
+
+<One-line description — what makes this project unique>
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `<command>` | <description> |
+
+## Start Here
+
+- <where to begin for the most common task>
+- <entry point or file to read first>
+
+## Cross-Package Patterns
+
+- <pattern that isn't obvious from code>
+- <convention that required a decision>
+
+## Gotchas
+
+- <non-obvious thing that causes issues>
+- <ordering dependency or prerequisite>
+
+## Workflow
+
+- <when to do X>
+- <preferred approach for Y>
+```
+
+**What's intentionally absent:**
+- `## Modules` / `## Packages` — `code_intel brief` generates this
+- Large root `## Project structure` / `## Architecture` directory trees that just restate the workspace layout
+- `## Dependencies` table — derivable from `package.json`
+
+If you keep any structure section in a SuPi-enabled root doc, make it short and opinionated: explain where to start, why boundaries exist, or which exception matters. After the baseline review, split the redundant tree/inventory portion from the unique guidance portion instead of keeping both together. Do not paste the tree unless the tree itself carries human-only meaning.
+
+---
+
+## Update Principles
+
+When updating any CLAUDE.md:
+
+1. **Be specific**: Use actual file paths, real commands from this project
+2. **Be current**: Verify info against the actual codebase
+3. **Be brief**: One line per concept when possible
+4. **Be useful**: Would this help a new Claude session understand the project?

package/skills/claude-md-revision/references/update-guidelines.md

@@ -0,0 +1,218 @@
+# CLAUDE.md Update Guidelines
+
+## Core Principle
+
+Only add information that will genuinely help future Claude sessions. The context window is precious - every line must earn its place.
+
+## What TO Add
+
+### 1. Commands/Workflows Discovered
+
+```markdown
+## Build
+
+`npm run build:prod` - Full production build with optimization
+`npm run build:dev` - Fast dev build (no minification)
+```
+
+Why: Saves future sessions from discovering these again.
+
+### 2. Gotchas and Non-Obvious Patterns
+
+```markdown
+## Gotchas
+
+- Tests must run sequentially (`--runInBand`) due to shared DB state
+- `yarn.lock` is authoritative; delete `node_modules` if deps mismatch
+```
+
+Why: Prevents repeating debugging sessions.
+
+### 3. Package Relationships
+
+```markdown
+## Dependencies
+
+The `auth` module depends on `crypto` being initialized first.
+Import order matters in `src/bootstrap.ts`.
+```
+
+Why: Architecture knowledge that isn't obvious from code.
+
+### 4. Testing Approaches That Worked
+
+```markdown
+## Testing
+
+For API endpoints: Use `supertest` with the test helper in `tests/setup.ts`
+Mocking: Factory functions in `tests/factories/` (not inline mocks)
+```
+
+Why: Establishes patterns that work.
+
+### 5. Configuration Quirks
+
+```markdown
+## Config
+
+- `NEXT_PUBLIC_*` vars must be set at build time, not runtime
+- Redis connection requires `?family=0` suffix for IPv6
+```
+
+Why: Environment-specific knowledge.
+
+## What SuPi Extensions Already Deliver
+
+When auditing or updating CLAUDE.md in a project using SuPi extensions, these sections are redundant because they're auto-injected on every session:
+
+| Extension | What It Injects | When |
+|-----------|----------------|------|
+| `supi-code-intelligence` | Workspace module graph (names, descriptions, paths, dependency edges) | First `before_agent_start` per session |
+| `supi-claude-md` | Subdirectory `CLAUDE.md` files wrapped in `<extension-context>` | On `read`/`edit`/`lsp`/`tree_sitter` to subdirectories |
+| `supi-core` | `findProjectRoot`, `walkProject`, XML `<extension-context>` tagging | Available to all extensions |
+
+**Implication:** A root CLAUDE.md doesn't need to document what `code_intel brief` would say. Focus instead on:
+- Commands and workflows
+- Cross-package conventions and patterns
+- Gotchas that aren't in code
+- Human-curated guidance ("start here for X")
+
+When SuPi is active, do a quick baseline review first: compare the CLAUDE.md against `code_intel brief` and other known injected context, then separate each section into overlap vs unique value. If a root `## Project structure` / `## Architecture` section mostly restates the workspace tree, treat that portion as redundant and keep only the orientation, boundary rules, or exceptions that the generated overview cannot supply.
+
+## What NOT to Add
+
+### 1. Obvious Code Info
+
+Bad:
+```markdown
+The `UserService` class handles user operations.
+```
+
+The class name already tells us this.
+
+### 2. Generic Best Practices
+
+Bad:
+```markdown
+Always write tests for new features.
+Use meaningful variable names.
+```
+
+This is universal advice, not project-specific.
+
+### 3. One-Off Fixes
+
+Bad:
+```markdown
+We fixed a bug in commit abc123 where the login button didn't work.
+```
+
+Won't recur; clutters the file.
+
+### 4. Verbose Explanations
+
+Bad:
+```markdown
+The authentication system uses JWT tokens. JWT (JSON Web Tokens) are
+an open standard (RFC 7519) that defines a compact and self-contained
+way for securely transmitting information between parties as a JSON
+object. In our implementation, we use the HS256 algorithm which...
+```
+
+Good:
+```markdown
+Auth: JWT with HS256, tokens in `Authorization: Bearer <token>` header.
+```
+
+## Diff Format for Updates
+
+For each suggested change:
+
+### 1. Identify the File
+
+```
+File: ./CLAUDE.md
+Section: Commands (new section after ## Architecture)
+```
+
+### 2. Show the Change
+
+```diff
+ ## Architecture
+ ...
+
++## Commands
++
++| Command | Purpose |
++|---------|---------|
++| `npm run dev` | Dev server with HMR |
++| `npm run build` | Production build |
++| `npm test` | Run test suite |
+```
+
+### 3. Explain Why
+
+> **Why this helps:** The build commands weren't documented, causing
+> confusion about how to run the project. This saves future sessions
+> from needing to inspect `package.json`.
+
+## What NOT to Add (SuPi Projects)
+
+In addition to the existing guidelines, avoid these when SuPi is active:
+
+**Redundant: Package/module inventory**
+```markdown
+Bad:
+## Packages
+| Package | Description | Path |
+|---------|-------------|------|
+| `api` | REST API | `packages/api/` |
+
+Better: Skip entirely, or if relationships are non-obvious:
+## Cross-Package Patterns
+The `api` package must be initialized before `worker` due to shared DB migrations.
+```
+
+**Redundant: High-level dependency graph**
+```markdown
+Bad:
+## Dependencies
+- `api` depends on `db`, `auth`
+- `web` depends on `api`
+
+Better: Skip — `code_intel brief` shows this live.
+```
+
+**Partially redundant: Root project structure section with both overlap and unique value**
+```markdown
+Overlap portion:
+## Project structure
+- `apps/web` — frontend
+- `apps/api` — backend
+- `packages/db` — shared database code
+- `packages/ui` — shared components
+
+Keep portion:
+- `packages/db` owns schema changes; app packages consume generated clients only
+- API request flow starts at `apps/api/src/routes/` and drops into `packages/db/`
+
+Better rewrite:
+## Start Here
+- Web changes usually start in `apps/web/src/app/`
+- API request flow starts at `apps/api/src/routes/` and drops into `packages/db/`
+
+## Cross-Package Patterns
+- `packages/db` owns schema changes; app packages consume generated clients only
+```
+
+## Validation Checklist
+
+Before finalizing an update, verify:
+
+- [ ] Each addition is project-specific
+- [ ] No generic advice or obvious info
+- [ ] Commands are tested and work
+- [ ] File paths are accurate
+- [ ] Would a new Claude session find this helpful?
+- [ ] Is this the most concise way to express the info?
+- [ ] No overlap with SuPi auto-delivered content (when SuPi is active)