@mrclrchtr/supi-claude-md 0.1.0

package/node_modules/@mrclrchtr/supi-core/src/settings-ui.ts

@@ -0,0 +1,226 @@
+// Generic settings overlay for SuPi extensions.
+//
+// Uses pi-tui's SettingsList with scope toggle (Tab), extension grouping,
+// and search. Each extension declares its settings via registerSettings().
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  Input,
+  Key,
+  matchesKey,
+  type SettingItem,
+  SettingsList,
+  Text,
+} from "@earendil-works/pi-tui";
+import {
+  getRegisteredSettings,
+  type SettingsScope,
+  type SettingsSection,
+} from "./settings-registry.ts";
+
+// ── Input submenu component ──────────────────────────────────
+
+/**
+ * Creates a pi-tui Input-backed submenu component with enter-to-confirm
+ * and escape-to-cancel handling.
+ *
+ * @param currentValue - Initial value for the text input.
+ * @param label - Label text displayed above the input.
+ * @param done - Callback invoked with the confirmed value, or undefined on cancel.
+ */
+export function createInputSubmenu(
+  currentValue: string,
+  label: string,
+  done: (selectedValue?: string) => void,
+): {
+  render: (width: number) => string[];
+  invalidate: () => void;
+  handleInput: (data: string) => boolean;
+} {
+  const input = new Input();
+  input.setValue(currentValue);
+
+  return {
+    render: (_width: number) => {
+      const lines = [`  ${label}`];
+      lines.push(...input.render(_width));
+      lines.push("  enter confirm • esc cancel");
+      return lines;
+    },
+    invalidate: () => {
+      input.invalidate();
+    },
+    handleInput: (data: string) => {
+      if (matchesKey(data, Key.escape)) {
+        done();
+        return true;
+      }
+      if (matchesKey(data, Key.enter)) {
+        done(input.getValue());
+        return true;
+      }
+      input.handleInput(data);
+      return true;
+    },
+  };
+}
+
+// ── Types ────────────────────────────────────────────────────
+
+interface OverlayState {
+  scope: SettingsScope;
+  cwd: string;
+}
+
+// ── Pure helpers ─────────────────────────────────────────────
+
+function getScopeLabel(scope: SettingsScope): string {
+  return scope === "project" ? "Project" : "Global";
+}
+
+function buildFlatItems(
+  sections: SettingsSection[],
+  scope: SettingsScope,
+  cwd: string,
+): SettingItem[] {
+  const items: SettingItem[] = [];
+  for (const section of sections) {
+    const sectionItems = section.loadValues(scope, cwd);
+    for (const item of sectionItems) {
+      items.push({
+        ...item,
+        id: `${section.id}.${item.id}`,
+        label: `${section.label}: ${item.label}`,
+      });
+    }
+  }
+  return items;
+}
+
+function findSectionAndId(
+  sections: SettingsSection[],
+  flatId: string,
+): { section: SettingsSection; itemId: string } | null {
+  const dotIndex = flatId.indexOf(".");
+  if (dotIndex === -1) return null;
+  const sectionId = flatId.slice(0, dotIndex);
+  const itemId = flatId.slice(dotIndex + 1);
+  const section = sections.find((s) => s.id === sectionId);
+  if (!section) return null;
+  return { section, itemId };
+}
+
+// ── Component ────────────────────────────────────────────────
+
+interface SettingsOverlayDeps {
+  state: OverlayState;
+  container: Container;
+  settingsList: SettingsList | null;
+  tui: Parameters<Parameters<ExtensionContext["ui"]["custom"]>[0]>[0];
+  theme: Parameters<Parameters<ExtensionContext["ui"]["custom"]>[0]>[1];
+  done: () => void;
+}
+
+function createSettingsList(deps: SettingsOverlayDeps): SettingsList {
+  const sections = getRegisteredSettings();
+  const items = buildFlatItems(sections, deps.state.scope, deps.state.cwd);
+  const onChange = (flatId: string, newValue: string) => {
+    const found = findSectionAndId(sections, flatId);
+    if (found) {
+      found.section.persistChange(deps.state.scope, deps.state.cwd, found.itemId, newValue);
+    }
+    // Re-read all values to reflect persisted changes, but keep the list
+    // instance (and its selectedIndex) intact.
+    const updatedItems = buildFlatItems(sections, deps.state.scope, deps.state.cwd);
+    for (const updated of updatedItems) {
+      const existing = items.find((i) => i.id === updated.id);
+      if (existing && existing.currentValue !== updated.currentValue) {
+        settingsList.updateValue(updated.id, updated.currentValue);
+      }
+    }
+    deps.tui.requestRender();
+  };
+  const settingsList = new SettingsList(
+    items,
+    Math.min(items.length + 4, 20),
+    getSettingsListTheme(),
+    onChange,
+    () => deps.done(),
+    { enableSearch: true },
+  );
+  return settingsList;
+}
+
+function rebuildSettingsList(deps: SettingsOverlayDeps): SettingsList {
+  const settingsList = createSettingsList(deps);
+  deps.settingsList = settingsList;
+
+  deps.container.clear();
+  deps.container.addChild(createHeaderComponent(deps));
+  deps.container.addChild(settingsList);
+
+  return settingsList;
+}
+
+function createHeaderComponent(deps: SettingsOverlayDeps): Text {
+  const { theme, state } = deps;
+  const scopeLabel = getScopeLabel(state.scope);
+  const otherScope = state.scope === "project" ? "Global" : "Project";
+  const headerText = new Text(
+    `${theme.fg("accent", theme.bold("SuPi Settings"))}  ${theme.fg("text", `Scope: ${scopeLabel}`)} ${theme.fg("dim", `(tab → ${otherScope})`)}`,
+    0,
+    0,
+  );
+  return headerText;
+}
+
+function handleScopeToggle(deps: SettingsOverlayDeps): void {
+  deps.state.scope = deps.state.scope === "project" ? "global" : "project";
+  rebuildSettingsList(deps);
+  deps.tui.requestRender();
+}
+
+// ── Entry point ──────────────────────────────────────────────
+
+export function openSettingsOverlay(ctx: ExtensionContext): void {
+  const sections = getRegisteredSettings();
+  if (sections.length === 0) {
+    ctx.ui.notify("No settings registered by SuPi extensions", "info");
+    return;
+  }
+
+  void ctx.ui.custom<void>((tui, theme, _kb, done) => {
+    const state: OverlayState = { scope: "project", cwd: ctx.cwd };
+    const container = new Container();
+
+    const deps: SettingsOverlayDeps = {
+      state,
+      container,
+      settingsList: null,
+      tui,
+      theme,
+      done,
+    };
+
+    rebuildSettingsList(deps);
+
+    const component = {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        if (matchesKey(data, Key.tab)) {
+          handleScopeToggle(deps);
+          return true;
+        }
+        // Delegate input to the settings list (always set after rebuildSettingsList)
+        deps.settingsList?.handleInput?.(data);
+        deps.tui.requestRender();
+        return true;
+      },
+    };
+
+    return component;
+  });
+}

package/node_modules/@mrclrchtr/supi-core/src/terminal.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared terminal title formatting and signaling utilities.
+ *
+ * Centralized place for pi title convention (π prefix), completion (✓)
+ * and waiting (●) indicators, and the audible terminal bell.
+ */
+import path from "node:path";
+
+/** Unicode checkmark shown when the agent finishes a turn. */
+export const DONE_SYMBOL = "\u2713";
+/** Unicode dot shown when waiting for user input. */
+export const WAITING_SYMBOL = "\u25CF";
+
+/** Minimal UI surface needed for title operations. */
+export interface TitleTarget {
+  ui: {
+    setTitle?(title: string): void;
+  };
+}
+
+/**
+ * Format pi's canonical terminal title from session name and cwd.
+ * Falls back gracefully when either is missing.
+ *
+ * @example
+ *   formatTitle("my-session", "/home/projects/foo")  // "π - my-session - foo"
+ *   formatTitle(undefined, "/home/projects/foo")      // "π - foo"
+ *   formatTitle("my-session")                         // "π - my-session"
+ *   formatTitle()                                     // "π"
+ */
+export function formatTitle(sessionName?: string, cwd?: string): string {
+  const base = cwd ? path.basename(cwd) : undefined;
+  if (sessionName && base) return `π - ${sessionName} - ${base}`;
+  if (sessionName) return `π - ${sessionName}`;
+  if (base) return `π - ${base}`;
+  return "π";
+}
+
+/** Sound the audible terminal bell (ASCII BEL). */
+export function signalBell(): void {
+  process.stdout.write("\x07");
+}
+
+/**
+ * Set the terminal title to indicate the agent is waiting for user input.
+ * Prefixes with ● and sounds the terminal bell.
+ */
+export function signalWaiting(ctx: TitleTarget, title: string): void {
+  ctx.ui.setTitle?.(`${WAITING_SYMBOL}  ${title}`);
+  signalBell();
+}
+
+/**
+ * Set the terminal title to indicate the agent turn has completed.
+ * Prefixes with ✓ and sounds the terminal bell.
+ */
+export function signalDone(ctx: TitleTarget, title: string): void {
+  ctx.ui.setTitle?.(`${DONE_SYMBOL} ${title}`);
+  signalBell();
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mrclrchtr/supi-claude-md",
+  "version": "0.1.0",
+  "description": "SuPi claude-md extension — automatic subdirectory context injection for pi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrclrchtr/supi.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "skills",
+    "!__tests__"
+  ],
+  "dependencies": {
+    "@mrclrchtr/supi-core": "workspace:*"
+  },
+  "bundledDependencies": [
+    "@mrclrchtr/supi-core"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "vitest": "^4.1.4",
+    "@mrclrchtr/supi-test-utils": "workspace:*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/claude-md.ts"
+    ]
+  },
+  "main": "src/index.ts"
+}

package/skills/claude-md-improver/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: claude-md-improver
+description: Use this skill to audit and improve CLAUDE.md files in repositories. Use when user asks to check, audit, update, improve, or fix CLAUDE.md files. Scans for all CLAUDE.md files, evaluates quality against templates, outputs quality report, then makes targeted updates.
+tools: Read, Glob, Grep, Bash, Edit
+---
+
+# CLAUDE.md Improver
+
+Audit, evaluate, and improve CLAUDE.md files across a codebase to ensure PI has optimal project context.
+
+## Workflow
+
+### Phase 1: Context Baseline Review
+
+**No file reads in this phase.** Use only what is already loaded in this session's context.
+
+**Purpose:** This baseline review is the primary evidence for scoring Criterion 7 (Auto-Delivered Overlap) in Phase 3. Its goal is to identify which information categories are already delivered automatically by SuPi extensions or native pi, so you do NOT recommend adding that same content to CLAUDE.md. If you skip this step, you will inflate scores and propose redundant additions that already appear in every session.
+
+**Step 1 — Detect auto-injected sources.** Scan the conversation context for:
+
+| Source identifier | What to look for | Typical content |
+|-------------------|------------------|---------------|
+| `supi-code-intelligence` | Workspace module graphs, package lists, dependency arrows, file counts | `## Modules` tables, architecture overviews, root directory trees |
+| `supi-claude-md` | `<extension-context source="supi-claude-md">` blocks | Subdirectory CLAUDE.md/AGENTS.md content already injected below cwd |
+| `native-pi` | Root CLAUDE.md or AGENTS.md loaded into the system prompt | Project-wide instructions from the repository root |
+| Other extensions | `<extension-context source="...">` blocks | Any other extension-injected context |
+
+**Step 2 — Build the baseline.** For each source found, record what it already covers:
+
+| Source | Content Category | Already Covers | Scope |
+|--------|------------------|----------------|-------|
+| `supi-code-intelligence` | Module graph | Package names, descriptions, dependency relationships | **Root-level** |
+| `supi-code-intelligence` | Workspace overview | File counts, root directory tree, top-level landmarks | **Root-level** |
+| `supi-claude-md` | Subdirectory instructions | `packages/*/CLAUDE.md` content injected during this session | **Package-specific** |
+| `native-pi` | Root instructions | `./CLAUDE.md`, `./AGENTS.md` in system prompt | **Root-level** |
+
+Add rows for any additional categories visible in context.
+
+**Step 3 — Classify redundancy risk by scope.** Use the table above to categorize:
+
+- **Root-level high risk** (already auto-delivered; do NOT recommend for root `./CLAUDE.md`):
+  - Package/module inventories (from `supi-code-intelligence`)
+  - Root directory trees and file counts (from `supi-code-intelligence`)
+  - Dependency graphs from manifests (from `supi-code-intelligence`)
+  - High-level architecture without project-specific reasoning (from `supi-code-intelligence`)
+
+- **Package-specific high risk** (already auto-delivered; do NOT recommend for that package's `CLAUDE.md`):
+  - Subdirectory CLAUDE.md/AGENTS.md already injected by `supi-claude-md` during this session
+
+- **Low risk** (not auto-delivered; safe to recommend in CLAUDE.md at any scope):
+  - Commands and workflows
+  - Gotchas and non-obvious patterns
+  - Cross-package conventions not obvious from manifests
+  - Curated "start here" guidance with ownership or boundary reasoning
+  - Project-specific exceptions to generic rules
+
+**Step 4 — Output the baseline.** Produce this structured overview before proceeding to Phase 2:
+
+```markdown
+## Phase 1 Baseline Review
+
+### SuPi Detected: yes / no
+
+### Auto-Injected Content by Source
+
+| Source | Content Category | Already Covers | Scope |
+|--------|------------------|----------------|-------|
+| ... | ... | ... | Root / Package-specific |
+
+### Redundancy Risk Assessment
+
+- **Root-level high risk** (do NOT recommend for root `./CLAUDE.md`):
+  - [List categories]
+- **Package-specific high risk** (do NOT recommend for matching package `CLAUDE.md`):
+  - [List categories]
+- **Low risk** (safe to recommend):
+  - [List categories]
+```
+
+**Note:** This review is intentionally approximate — it compares against the context already visible to you, not the literal hidden system prompt. If no SuPi-delivered context is visible in the conversation, the baseline is empty and this phase is a no-op.
+
+### Phase 2: Discovery
+
+Now read files from disk. Find all CLAUDE.md files in the repository:
+
+```bash
+find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50
+```
+
+**File Types & Locations:**
+
+| Type | Location | Purpose |
+|------|----------|---------|
+| Project root | `./CLAUDE.md` | Primary project context (checked into git, shared with team) |
+| Local overrides | `./.claude.local.md` | Personal/local settings (gitignored, not shared) |
+| Global defaults | `~/.claude/CLAUDE.md` | User-wide defaults across all projects |
+| Package-specific | `./packages/*/CLAUDE.md` | Module-level context in monorepos |
+| Subdirectory | Any nested location | Feature/domain-specific context |
+
+**Note:** PI auto-discovers CLAUDE.md files in parent directories, making monorepo setups work automatically.
+
+### Phase 3: Quality Assessment
+
+For each CLAUDE.md file found in Phase 2, evaluate against quality criteria, incorporating the Phase 1 baseline review results. See [references/quality-criteria.md](references/quality-criteria.md) for detailed rubrics.
+
+**Quick Assessment Checklist:**
+
+| Criterion | Weight | Check |
+|-----------|--------|-------|
+| Commands/workflows documented | High | Are build/test/deploy commands present? |
+| Architecture clarity | High | Can PI understand the codebase structure? |
+| Non-obvious patterns | Medium | Are gotchas and quirks documented? |
+| Conciseness | Medium | No verbose explanations or obvious info? |
+| Currency | High | Does it reflect current codebase state? |
+| Actionability | High | Are instructions executable, not vague? |
+| Auto-delivered overlap | Low | Does it duplicate what SuPi extensions already inject? **Use the Phase 1 Redundancy Risk Assessment as primary evidence.** |
+
+**Quality Scores:**
+- **A (90-100)**: Comprehensive, current, actionable
+- **B (70-89)**: Good coverage, minor gaps
+- **C (50-69)**: Basic info, missing key sections
+- **D (30-49)**: Sparse or outdated
+- **F (0-29)**: Missing or severely outdated
+
+### Phase 4: Quality Report Output
+
+**ALWAYS output the quality report BEFORE making any updates.**
+
+Format:
+
+```
+## CLAUDE.md Quality Report
+
+### Summary
+- Files found: X
+- Average score: X/100
+- Files needing update: X
+
+### File-by-File Assessment
+
+#### 1. ./CLAUDE.md (Project Root)
+**Score: XX/100 (Grade: X)**
+
+**Context Overlap Review:**
+- **Fully redundant (root-level):** [sections already covered by baseline context — applies to root `./CLAUDE.md`]
+- **Fully redundant (package-specific):** [sections already covered by baseline context — applies to that package's `CLAUDE.md`]
+- **Partially redundant:** [sections with overlap plus human-only value]
+- **Unique:** [sections that should stay]
+
+| Criterion | Score | Notes |
+|-----------|-------|-------|
+| Commands/workflows | X/15 | ... |
+| Architecture clarity | X/15 | ... |
+| Non-obvious patterns | X/15 | ... |
+| Conciseness | X/15 | ... |
+| Currency | X/15 | ... |
+| Actionability | X/15 | ... |
+| Auto-delivered overlap | X/10 | ... |
+
+**Issues:**
+- [List specific problems]
+
+**Recommended additions:**
+- [List what should be added]
+
+#### 2. ./packages/api/CLAUDE.md (Package-specific)
+...
+```
+
+### Phase 5: Targeted Updates
+
+After outputting the quality report, ask user for confirmation before updating.
+
+**Update Guidelines (Critical):**
+
+1. **Propose targeted additions only** - Focus on genuinely useful info:
+   - Commands or workflows discovered during analysis
+   - Gotchas or non-obvious patterns found in code
+   - Package relationships that weren't clear
+   - Testing approaches that work
+   - Configuration quirks
+
+2. **Keep it minimal** - Avoid:
+   - Restating what's obvious from the code
+   - Generic best practices already covered
+   - One-off fixes unlikely to recur
+   - Verbose explanations when a one-liner suffices
+
+3. **Show diffs** - For each change, show:
+   - Which CLAUDE.md file to update
+   - The specific addition (as a diff or quoted block)
+   - Brief explanation of why this helps future sessions
+
+**Diff Format:**
+
+```markdown
+### Update: ./CLAUDE.md
+
+**Why:** Build command was missing, causing confusion about how to run the project.
+
+```diff
++ ## Quick Start
++
++ ```bash
++ npm install
++ npm run dev  # Start development server on port 3000
++ ```
+```
+```
+
+### Phase 6: Apply Updates
+
+After user approval, apply changes using the Edit tool. Preserve existing content structure.
+
+## Templates
+
+See [references/templates.md](references/templates.md) for CLAUDE.md templates by project type.
+
+## Common Issues to Flag
+
+1. **Stale commands**: Build commands that no longer work
+2. **Missing dependencies**: Required tools not mentioned
+3. **Outdated architecture**: File structure that's changed
+4. **Missing environment setup**: Required env vars or config
+5. **Broken test commands**: Test scripts that have changed
+6. **Undocumented gotchas**: Non-obvious patterns not captured
+
+## User Tips to Share
+
+When presenting recommendations, remind users:
+
+- **Keep it concise**: CLAUDE.md should be human-readable; dense is better than verbose
+- **Actionable commands**: All documented commands should be copy-paste ready
+- **Use `.claude.local.md`**: For personal preferences not shared with team (add to `.gitignore`)
+- **Global defaults**: Put user-wide preferences in `~/.claude/CLAUDE.md`
+
+## What Makes a Great CLAUDE.md
+
+**Key principles:**
+- Concise and human-readable
+- Actionable commands that can be copy-pasted
+- Project-specific patterns, not generic advice
+- Non-obvious gotchas and warnings
+
+**Recommended sections** (use only what's relevant):
+- Commands (build, test, dev, lint)
+- Architecture (directory structure)
+- Key Files (entry points, config)
+- Code Style (project conventions)
+- Environment (required vars, setup)
+- Testing (commands, patterns)
+- Gotchas (quirks, common mistakes)
+- Workflow (when to do what)

package/skills/claude-md-improver/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.