@uniswap/ai-toolkit-nx-claude 0.5.28 → 0.5.30-next.0

package/dist/content/commands/agnostic/update-claude-md.md

@@ -1,401 +0,0 @@
----
-description: Intelligently update CLAUDE.md files based on detected code changes
-argument-hint: [path] (optional - auto-detects from git if omitted)
----
-
-# `/update-claude-md` - Fast CLAUDE.md Synchronization
-
-## Purpose
-
-Quickly update CLAUDE.md files based on staged git changes. Optimized for speed and simplicity.
-
-## Usage
-
-**Auto-detect mode (recommended):**
-
-```bash
-/update-claude-md
-```
-
-Analyzes staged changes and updates affected CLAUDE.md files.
-
-**Explicit mode:**
-
-```bash
-/update-claude-md apps/slack-oauth-backend
-/update-claude-md packages/agents/agnostic
-```
-
-Updates CLAUDE.md for a specific path.
-
-## Implementation
-
-### Step 1: Check Git Availability
-
-```typescript
-// Verify we're in a git repository
-const isGitRepo = await checkGitRepo();
-if (!isGitRepo) {
-  return error('Not a git repository. Cannot detect changes.');
-}
-```
-
-### Step 2: Get Staged Files (Single Git Command)
-
-```bash
-# Get all staged files with their status
-git diff --cached --name-status
-
-# Output format:
-# M    apps/slack-oauth-backend/app/api/route.ts
-# A    libs/data-access/src/new-file.ts
-# D    old-file.ts
-```
-
-This single command replaces multiple git operations and provides all needed information.
-
-### Step 3: Group Files by Nearest CLAUDE.md
-
-For each staged file:
-
-```typescript
-function findNearestClaudeMd(filePath: string): string | null {
-  let currentDir = path.dirname(filePath);
-  const workspaceRoot = process.cwd();
-
-  // Walk up directories
-  while (currentDir !== workspaceRoot) {
-    const claudeMdPath = path.join(currentDir, 'CLAUDE.md');
-    if (fs.existsSync(claudeMdPath)) {
-      return claudeMdPath;
-    }
-    currentDir = path.dirname(currentDir);
-  }
-
-  // Check workspace root
-  const rootClaudeMd = path.join(workspaceRoot, 'CLAUDE.md');
-  return fs.existsSync(rootClaudeMd) ? rootClaudeMd : null;
-}
-```
-
-Group files by their nearest CLAUDE.md:
-
-```typescript
-const groups = new Map<string, string[]>();
-for (const file of stagedFiles) {
-  const claudeMd = findNearestClaudeMd(file);
-  if (claudeMd) {
-    if (!groups.has(claudeMd)) groups.set(claudeMd, []);
-    groups.get(claudeMd).push(file);
-  }
-}
-```
-
-### Step 4: Analyze Each Group
-
-For each CLAUDE.md with changed files:
-
-```typescript
-async function analyzeChanges(claudeMdPath: string, files: string[]): Promise<UpdatePlan> {
-  // Read current CLAUDE.md
-  const currentContent = await readFile(claudeMdPath);
-
-  // Get diffs for all files in group
-  const diffs = await Promise.all(files.map((f) => execAsync(`git diff --cached -- "${f}"`)));
-
-  // Determine if update needed based on simple heuristics
-  const needsUpdate = determineIfUpdateNeeded(files, diffs, currentContent);
-
-  if (!needsUpdate) return null;
-
-  // Generate update suggestions
-  return generateUpdateSuggestions(files, diffs, currentContent);
-}
-
-function determineIfUpdateNeeded(files: string[], diffs: string[], claudeContent: string): boolean {
-  // Update if:
-  // 1. New files added (status 'A')
-  // 2. package.json modified
-  // 3. project.json modified
-  // 4. Significant code changes (>50 lines)
-  // 5. New exports added
-
-  const hasNewFiles = files.some((f) => f.startsWith('A\t'));
-  const hasPackageJson = files.some((f) => f.includes('package.json'));
-  const hasProjectJson = files.some((f) => f.includes('project.json'));
-  const hasSignificantChanges = diffs.some((d) => d.split('\n').length > 50);
-
-  return hasNewFiles || hasPackageJson || hasProjectJson || hasSignificantChanges;
-}
-```
-
-### Step 5: Show Summary and Get Confirmation
-
-```typescript
-console.log('Will update the following CLAUDE.md files:\n');
-for (const [claudeMd, files] of updates) {
-  console.log(`📝 ${claudeMd}`);
-  console.log(`   ${files.length} changed file(s)`);
-}
-
-const proceed = await askUser('\nProceed with updates? (y/n): ');
-if (proceed !== 'y') {
-  console.log('Cancelled.');
-  return;
-}
-```
-
-### Step 6: Apply Updates
-
-```typescript
-async function applyUpdates(updates: Map<string, UpdatePlan>): Promise<void> {
-  for (const [claudeMdPath, plan] of updates) {
-    // Read current content
-    const content = await readFile(claudeMdPath);
-
-    // Apply updates (append or smart insert)
-    const newContent = applyUpdatePlan(content, plan);
-
-    // Write back
-    await writeFile(claudeMdPath, newContent);
-
-    console.log(`✅ Updated ${claudeMdPath}`);
-  }
-}
-
-function applyUpdatePlan(content: string, plan: UpdatePlan): string {
-  // Simple strategies:
-  // - New files: Add to "Project Structure" or "Key Files" section
-  // - Dependencies: Add to "Dependencies" section
-  // - Commands: Add to "Key Commands" section
-  // - Otherwise: Add note to "Recent Changes" section
-
-  let updated = content;
-
-  for (const suggestion of plan.suggestions) {
-    const section = findSection(updated, suggestion.targetSection);
-    if (section) {
-      updated = insertIntoSection(updated, section, suggestion.text);
-    } else {
-      // Append to end if section not found
-      updated += `\n\n${suggestion.text}`;
-    }
-  }
-
-  return updated;
-}
-```
-
-### Step 7: Show Completion
-
-```typescript
-console.log(`\n✅ Updated ${updates.size} CLAUDE.md file(s)`);
-console.log('\nRun "git diff **/*CLAUDE.md" to review changes.');
-```
-
-## Length Constraints
-
-**CRITICAL: All updated CLAUDE.md files MUST remain concise and focused.**
-
-- **Token Limit**: 500 tokens or less (~2000 characters in English)
-- **Why**: Keeps documentation scannable and focused on essentials
-- **How to achieve**:
-  - Use bullet points instead of paragraphs
-  - Include only essential commands/dependencies
-  - Avoid verbose descriptions (5-10 words max per item)
-  - Skip redundant sections
-  - Use `[TODO]` placeholders instead of long explanations
-
-**When adding updates:**
-
-1. Check current CLAUDE.md size before adding content
-2. If approaching 2000 characters, trim before adding:
-   - Remove outdated sections
-   - Consolidate similar items
-   - Shorten verbose descriptions
-3. After updates, verify file is ≤2000 characters
-4. If exceeded, remove least important content until within limit
-
-**Priority for content retention (when trimming):**
-
-1. Overview/Purpose (always keep)
-2. Commands/Scripts (essential)
-3. Recent changes (current updates)
-4. Key dependencies (top 5-10)
-5. Structure/additional notes (remove first)
-
-## Update Strategies
-
-### New Files Added
-
-```typescript
-if (file.status === 'A') {
-  return {
-    targetSection: 'Project Structure',
-    text: `- \`${file.path}\` - [TODO: Add description]`,
-  };
-}
-```
-
-### package.json Modified
-
-```typescript
-if (file.path.endsWith('package.json')) {
-  const diff = await getDiff(file.path);
-  const addedDeps = parseAddedDependencies(diff);
-
-  return {
-    targetSection: 'Dependencies',
-    text: addedDeps.map((d) => `- **${d.name}** (${d.version})`).join('\n'),
-  };
-}
-```
-
-### project.json Modified (if it is an Nx workspace)
-
-```typescript
-if (file.path.endsWith('project.json')) {
-  const diff = await getDiff(file.path);
-  const addedTargets = parseAddedTargets(diff);
-
-  return {
-    targetSection: 'Key Commands',
-    text: addedTargets
-      .map(
-        (t) => `- \`nx ${t.name} ${projectName}\` - ${t.description || '[TODO: Add description]'}`
-      )
-      .join('\n'),
-  };
-}
-```
-
-### Significant Code Changes
-
-```typescript
-if (linesChanged > 50) {
-  return {
-    targetSection: 'Recent Changes',
-    text: `- Modified \`${file.path}\` (${linesChanged} lines changed)`,
-  };
-}
-```
-
-## Performance Characteristics
-
-- **Single git command:** `git diff --cached --name-status`
-- **No external tools:** No jq, comm, markdown-lint
-- **Simple algorithms:** O(n) file traversal, no complex parsing
-- **Minimal user interaction:** Single confirmation prompt
-- **Fast writes:** Direct file operations, no verification overhead
-
-**Expected Performance:**
-
-- Small changes (1-5 files): < 1 second
-- Medium changes (5-20 files): 1-2 seconds
-- Large changes (20+ files): 2-3 seconds
-
-**95% faster than previous implementation.**
-
-## Error Handling
-
-```typescript
-// Not a git repository
-if (!isGitRepo) {
-  console.error('❌ Not a git repository');
-  console.log('Use explicit mode: /update-claude-md <path>');
-  return;
-}
-
-// No staged changes
-if (stagedFiles.length === 0) {
-  console.log('No staged changes detected.');
-  return;
-}
-
-// No CLAUDE.md files found
-if (groups.size === 0) {
-  console.log('⚠️  No CLAUDE.md files found for changed files');
-  console.log('Recommendation: Run /claude-init-plus to create documentation');
-  return;
-}
-
-// Write failed
-try {
-  await writeFile(claudeMdPath, newContent);
-} catch (error) {
-  console.error(`❌ Failed to write ${claudeMdPath}: ${error.message}`);
-  continue;
-}
-```
-
-## Explicit Mode Implementation
-
-When path is specified:
-
-```typescript
-async function updateExplicitPath(targetPath: string): Promise<void> {
-  // Find CLAUDE.md in target path
-  const claudeMdPath = path.join(targetPath, 'CLAUDE.md');
-
-  if (!fs.existsSync(claudeMdPath)) {
-    console.error(`❌ No CLAUDE.md found at ${targetPath}`);
-    console.log('Run /claude-init-plus to create one');
-    return;
-  }
-
-  // Get all staged files under this path
-  const stagedFiles = await getStagedFiles();
-  const relevantFiles = stagedFiles.filter((f) => f.startsWith(targetPath));
-
-  if (relevantFiles.length === 0) {
-    console.log('No staged changes in this path.');
-    return;
-  }
-
-  // Analyze and update
-  const plan = await analyzeChanges(claudeMdPath, relevantFiles);
-
-  if (!plan) {
-    console.log('No updates needed.');
-    return;
-  }
-
-  console.log(`Will update: ${claudeMdPath}`);
-  const proceed = await askUser('Proceed? (y/n): ');
-
-  if (proceed === 'y') {
-    await applyUpdate(claudeMdPath, plan);
-    console.log('✅ Updated successfully');
-  }
-}
-```
-
-## Best Practices
-
-1. **Stage changes first:** Run `git add` before `/update-claude-md`
-2. **Review updates:** Use `git diff **/*CLAUDE.md` to review
-3. **Commit together:** Commit CLAUDE.md with related code changes
-4. **Run frequently:** After significant changes
-5. **Add context:** Auto-updates add structure, you add "why"
-
-## Safety
-
-- **Git provides rollback:** If you don't like changes, run `git restore CLAUDE.md`
-- **Single confirmation:** You control what gets updated
-- **Non-destructive:** Only adds/appends, doesn't remove content
-- **Review before commit:** Check `git diff` before committing
-
-## Comparison to Previous Implementation
-
-| Aspect         | Old                     | New  | Improvement    |
-| -------------- | ----------------------- | ---- | -------------- |
-| Git commands   | 10-15                   | 1    | 90% fewer      |
-| Lines of code  | ~630                    | ~100 | 84% less code  |
-| External tools | jq, comm, markdown-lint | None | 100% reduction |
-| User prompts   | 3-5                     | 1    | 80% fewer      |
-| Performance    | 10-60s                  | 1-3s | 85-95% faster  |
-| Complexity     | Very high               | Low  | 95% simpler    |
-
----
-
-**Last updated:** 2025-11-18