@uniswap/ai-toolkit-nx-claude 0.5.7-next.9 → 0.5.8

package/README.md

@@ -4,57 +4,55 @@ This package provides Nx generators for setting up and managing Claude Code conf
 
 ## Installation
 
-This package is published to GitHub Packages and requires authentication to access. Ensure you have a GitHub personal access token with appropriate scopes configured in your npm settings. More information available in the root README.md file.
-
-````bash
+This package is published to a private npmjs package registry and requires authentication to access. See the [root README.md file](../../README.md) for instructions on how to install it via NPM, or run it locally
 
 ## Usage
 
 ### Run Default Generator
 
 ```bash
-npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest
-````
+bun nx run @uniswap/ai-toolkit-nx-claude:nx-claude:exec
+```
 
 ### Run Specific Generators
 
-Each generator can be run directly using colon syntax:
+Each generator can be run directly desired generator's subcommand:
 
 ```bash
 # One-shot installer for Claude Code configs
-npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest init
+bun nx run @uniswap/ai-toolkit-nx-claude:nx-claude:exec init
 
 # Install notification hooks
-npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest hooks
-
-# Setup shell proxy for GitHub registry routing
-npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest setup-registry-proxy
+bun nx run @uniswap/ai-toolkit-nx-claude:nx-claude:exec hooks
 
 # Install and configure Claude Code addons
-npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest addons
+bun nx run @uniswap/ai-toolkit-nx-claude:nx-claude:exec addons
 
 # Add a new command to packages
-npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest add-command
+bun nx run @uniswap/ai-toolkit-nx-claude:nx-claude:exec add-command
 
 # Add a new agent to packages
-npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest add-agent
+bun nx run @uniswap/ai-toolkit-nx-claude:nx-claude:exec add-agent
 ```
 
 ### List Available Generators
 
 ```bash
-npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest --list
+bun nx run @uniswap/ai-toolkit-nx-claude:nx-claude:exec --list
 ```
 
 ## Available Generators
 
 - **init** - One-shot installer for Claude Code configs
 - **hooks** - Install Claude Code notification hooks
-- **setup-registry-proxy** - Setup shell proxy for routing @uniswap/ai-toolkit\* packages to GitHub registry
 - **addons** - Install and configure Claude Code addons including MCP servers
 - **add-command** - Add a new Claude Code command to existing or new packages
 - **add-agent** - Add a new Claude Code agent to existing or new packages
 
 ## Building
 
-Run `nx build ai-toolkit-nx-claude` to build the library.
+Run `bun nx build ai-toolkit-nx-claude` to build the library.
+
+## Testing
+
+Run `bunx nx test ai-toolkit-nx-claude` to test this library

package/dist/cli-generator.cjs

@@ -30,7 +30,7 @@ var fs = __toESM(require("fs"));
 async function handleNxExecution(generatorName, args) {
   if (args.includes("--help") || args.includes("-h")) {
     console.log(
-      `Usage: npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest ${generatorName}`
+      `Usage: npx @uniswap/ai-toolkit-nx-claude@latest ${generatorName}`
     );
     console.log(
       `
@@ -68,18 +68,10 @@ function handleExecutionError(error, generatorName) {
     );
     console.error("You do not have permission to access this package.");
     console.error(
-      "\nThis package is restricted to members of the Uniswap GitHub organization."
+      "\nThis package requires a read-only npm token to access the private npmjs registry."
     );
     console.error("\nTo gain access:");
-    console.error(
-      "1. Verify you are a member of the Uniswap organization on GitHub"
-    );
-    console.error(
-      '2. Check that your npm token has the required "read:packages" scope'
-    );
-    console.error(
-      "\nFor more information, see: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-to-github-packages"
-    );
+    console.error("1. See the top-level README for setup instructions.");
     console.error(
       "\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501"
     );
@@ -94,11 +86,7 @@ function handleExecutionError(error, generatorName) {
     console.error("\nThis may be because:");
     console.error("1. The package has not been published yet");
     console.error(
-      "2. You are not authenticated properly (check your GitHub PAT)"
-    );
-    console.error("\nTry running:");
-    console.error(
-      '  echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> ~/.npmrc'
+      "2. You are not authenticated properly (check the top-level README for NPM authenticationsetup instructions)"
     );
     console.error(
       "\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501"
@@ -140,7 +128,6 @@ async function runGeneratorDirectly(generatorName, args) {
     const generatorFunctionMap = {
       init: "initGenerator",
       hooks: "hooksGenerator",
-      "setup-registry-proxy": "setupRegistryProxyGenerator",
       addons: "addonsGenerator",
       "add-command": "addCommandGenerator",
       "add-agent": "addAgentGenerator"
@@ -340,10 +327,8 @@ function isInAiToolkitRepo() {
   return isInAiToolkit;
 }
 var GENERATORS = {
-  init: "One-shot installer for Claude Code configs",
-  hooks: "Install Claude Code notification hooks",
-  addons: "Install and configure Claude Code addons including MCP servers",
-  "setup-registry-proxy": "Setup shell proxy for routing @uniswap/ai-toolkit* packages to GitHub registry"
+  "default-install": "Recommended setup with pre-selected components",
+  "custom-install": "Choose exactly what to install"
 };
 var ALL_GENERATORS = isInAiToolkitRepo() ? {
   ...GENERATORS,
@@ -394,22 +379,16 @@ async function main() {
       console.log(`  ${name.padEnd(25)} ${description}`);
     });
     console.log("\nUsage:");
-    console.log(
-      "  npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest [generator]"
-    );
+    console.log("  npx @uniswap/ai-toolkit-nx-claude@latest [generator]");
     console.log("\nExamples:");
-    console.log(
-      "  npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest init"
-    );
-    console.log(
-      "  npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest hooks"
-    );
+    console.log("  npx @uniswap/ai-toolkit-nx-claude@latest default-install");
+    console.log("  npx @uniswap/ai-toolkit-nx-claude@latest custom-install");
     process.exit(0);
   }
   if (processedArgs.includes("--help") || processedArgs.includes("-h")) {
     if (generatorName) {
       console.log(
-        `Usage: npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest ${generatorName}`
+        `Usage: npx @uniswap/ai-toolkit-nx-claude@latest ${generatorName}`
       );
       console.log(
         `
@@ -417,15 +396,13 @@ This command runs the nx-claude ${generatorName} generator.`
       );
     } else {
       console.log(
-        "Usage: npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest [generator]"
+        "Usage: npx @uniswap/ai-toolkit-nx-claude@latest [generator]"
       );
       console.log("\nRun without arguments for interactive mode.");
     }
     console.log("\nTo see all available generators, run with --list");
     console.log("\nTo run a specific generator:");
-    console.log(
-      "  npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest [generator]"
-    );
+    console.log("  npx @uniswap/ai-toolkit-nx-claude@latest [generator]");
     console.log("\nOptions are handled interactively during execution.");
     console.log("\nFor more information, see the package documentation.");
     process.exit(0);
@@ -437,11 +414,23 @@ This command runs the nx-claude ${generatorName} generator.`
   if (!generatorName) {
     console.error("\n\u274C No generator specified.");
     console.error(
-      "\nUsage: npx --@uniswap:registry=https://npm.pkg.github.com @uniswap/ai-toolkit-nx-claude@latest [generator]"
+      "\nUsage: npx @uniswap/ai-toolkit-nx-claude@latest [generator]"
     );
     console.error("\nRun with --list to see available generators.");
     process.exit(1);
   }
-  await handleNxExecution(generatorName, processedArgs);
+  if (generatorName === "default-install") {
+    await handleNxExecution("init", [
+      ...processedArgs,
+      "--install-mode=default"
+    ]);
+  } else if (generatorName === "custom-install") {
+    await handleNxExecution("init", [
+      ...processedArgs,
+      "--install-mode=custom"
+    ]);
+  } else {
+    await handleNxExecution(generatorName, processedArgs);
+  }
 }
 main().catch(console.error);

package/dist/content/agents/agnostic/claude-docs-initializer.md

@@ -0,0 +1,458 @@
+---
+name: claude-docs-initializer
+description: Discover repository structure and create initial CLAUDE.md documentation at all appropriate levels
+---
+
+# Claude-Docs Initializer Agent
+
+## Mission
+
+Perform deep repository analysis to understand structure, patterns, and architecture, then create comprehensive CLAUDE.md documentation files at all appropriate levels. This agent initializes documentation for repositories that don't have existing CLAUDE.md files.
+
+## Inputs
+
+- `target`: Natural language description of what to document
+  - Example: "the Next.js frontend application located in /app/frontend, focusing on user-facing pages and components"
+  - Example: "the authentication system across the entire codebase"
+  - Example: "the Express backend API in /backend, including all routes and middleware"
+  - Example: "create the repository root CLAUDE.md summarizing the entire project architecture"
+  - Example: "document the shared UI components library in /packages/ui with focus on the design system"
+
+- `siblingContext`: Natural language description of what other agents are documenting
+  - Example: "Other agents are documenting: the admin dashboard components, the backend API documentation, and the database schema documentation"
+  - Example: "Another agent is documenting the user-facing frontend pages while you focus on admin pages"
+  - Example: "No other agents are running" (for single-agent mode)
+  - Example: "Level 1 agents are documenting: frontend user pages, frontend admin pages, backend services"
+
+- `completedContext`: (Optional) Natural language findings from completed sibling agents - ONLY provided for area root or repository root documentation
+  - Example: "The frontend user pages use React Query for data fetching, follows atomic design patterns, has 47 components. The admin section uses Redux for state management with 23 components."
+  - Example: "The backend API has 23 RESTful endpoints, uses JWT authentication with refresh tokens, implements rate limiting with Redis, follows a layered architecture pattern."
+  - Example: "Frontend findings: Uses Next.js App Router with RSC, Tailwind for styling, custom hooks for business logic. Backend findings: Express with TypeScript, PostgreSQL with Prisma ORM, organized in controllers/services/repositories pattern."
+
+## Process
+
+### 1. Parse Target Scope
+
+Interpret the natural language target to understand:
+- **Extract paths**: Identify any specific directories mentioned (e.g., "/frontend", "/app/pages")
+- **Understand scope**: Parse descriptors like "user-facing", "admin", "API routes", "shared components"
+- **Determine level**: Identify if this is for:
+  - Leaf documentation (specific module/feature within an area)
+  - Area root documentation (e.g., "frontend root", "backend root")
+  - Repository root documentation (entire project overview)
+- **Set boundaries**: Based on description, determine which directories to analyze and document
+
+### 2. Respect Sibling Boundaries
+
+From siblingContext, understand coordination requirements:
+- **Parse sibling work**: Identify what other agents are handling
+- **Prevent overlap**: Ensure no duplicate CLAUDE.md creation
+- **Stay in bounds**: Only create documentation within assigned target
+- **Coordination awareness**: If creating leaf docs, be aware of which area root will consolidate your findings
+
+### 3. Incorporate Completed Context (Area/Repository Root Only)
+
+If completedContext is provided (only for consolidation phases):
+- **Parse findings**: Extract key discoveries from completed agents
+- **Identify patterns**: Look for common patterns across different areas
+- **Build narrative**: Create cohesive story incorporating all findings
+- **Cross-reference**: Connect related concepts across different areas
+- **Synthesize**: Don't just list findings, create unified architectural understanding
+
+### 4. Repository Discovery & Analysis
+
+**Two-Phase Discovery Approach**:
+
+**Phase 1: Git-Based Discovery (Primary Method)**:
+If the repository is a git repository (check for .git directory):
+- Use `git ls-files` to get all tracked files (automatically excludes node_modules, dist, etc.)
+- Find package boundaries: `git ls-files | grep 'package\.json$'` for Node.js projects
+- Find other project files: `git ls-files | grep -E '(project\.json|go\.mod|Cargo\.toml|pyproject\.toml|pom\.xml)$'`
+- Analyze directory structure: `git ls-files | sed 's|/[^/]*$||' | sort -u` to get unique directories
+- Sample files for pattern detection: `git ls-files | grep -E '\.(ts|tsx|js|jsx|py|go|rs|java)$' | head -1000`
+
+**Phase 2: Fallback Manual Discovery (Only if not a git repo)**:
+
+**⚠️ CRITICAL: NEVER use find commands without proper exclusions!**
+- **WRONG**: `-not -path "./node_modules/*"` (only excludes top-level)
+- **CORRECT**: `-not -path "*/node_modules/*"` (excludes ALL nested node_modules)
+
+Use Glob/Grep with explicit exclusions:
+- **MUST exclude these patterns**:
+  - `**/node_modules/**` (for Glob)
+  - `*/node_modules/*` (for find command)
+  - `**/dist/**` or `*/dist/*`
+  - `**/build/**` or `*/build/*`
+  - `**/.next/**` or `*/.next/*`
+  - `**/.nuxt/**` or `*/.nuxt/*`
+  - `**/coverage/**` or `*/coverage/*`
+  - `**/.git/**` or `*/.git/*`
+  - `**/vendor/**` or `*/vendor/*`
+  - `**/.cache/**` or `*/.cache/*`
+  - `**/tmp/**` or `*/tmp/*`
+  - `**/.turbo/**` or `*/.turbo/*`
+  - `**/out/**` or `*/out/*`
+- Search for package boundaries with exclusions
+- Limit search depth to avoid excessive exploration
+
+**Technology Detection**:
+- Programming languages used
+- Frameworks and libraries
+- Build tools and bundlers
+- Testing frameworks
+- CI/CD configuration
+- Development tools (linters, formatters)
+
+### 5. Identify Documentation Targets
+
+Based on parsed target scope, determine documentation strategy:
+
+**For Leaf-Level Documentation** (e.g., "document the user-facing frontend pages"):
+- Create CLAUDE.md files at multiple levels within target area
+- Include package, module, and feature-level documentation
+- Document based on these criteria:
+  - **Package boundaries**: Any directory with package.json/project.json
+  - **Major modules**: Directories with 5+ source files representing domains
+  - **Feature directories**: Self-contained features with 3+ files
+  - **Complex components**: Component groups with significant logic
+  - **Service layers**: Backend service modules with business logic
+  - **Domain boundaries**: Auth, payments, user management, etc.
+
+**For Area Root Documentation** (e.g., "create frontend root CLAUDE.md"):
+- Create SINGLE CLAUDE.md at the area root directory only
+- Synthesize findings from completedContext
+- Do NOT create subdirectory documentation
+- Focus on architectural overview of the entire area
+
+**For Repository Root Documentation** (e.g., "create repository root CLAUDE.md"):
+- Create SINGLE CLAUDE.md at repository root only
+- Synthesize all area findings from completedContext
+- Provide high-level system architecture
+- Connect patterns across different areas
+
+**NEVER create CLAUDE.md for**:
+- Directories outside your target scope
+- node_modules directories (any level)
+- Build output directories (dist, build, out, .next, .nuxt, .turbo)
+- Cache/temporary directories (.cache, tmp, .turbo)
+- Test-only directories (unless complex test infrastructure)
+- Asset directories (images, fonts, static files)
+- Single-file directories
+- Pure utility/helper directories with < 3 files
+
+### 3. Deep Content Analysis (Per Target Directory)
+
+For each directory that will get a CLAUDE.md:
+
+**Code Analysis** (using git-tracked files only if a git repository):
+- Find entry points in directory: `git ls-files <directory> | grep -E '(index|main)\.(ts|js|tsx|jsx|py|go|rs|java)$'`
+- List all source files: `git ls-files <directory> | grep -E '\.(ts|tsx|js|jsx|py|go|rs|java)$'`
+- Parse main entry points and identify exported APIs
+- Detect architectural patterns (MVC, layered, hexagonal)
+- Analyze component/class structures
+- Map internal dependencies
+- Identify coding conventions and patterns
+
+**Pattern Recognition**:
+- Naming conventions (files, functions, components)
+- Directory organization patterns
+- State management approach
+- Error handling patterns
+- Testing strategies
+- Build and deployment patterns
+
+**Relationship Mapping**:
+- How this module relates to others
+- Dependencies (both internal and external)
+- Consumers of this module's exports
+- Data flow patterns
+
+### 4. Content Generation
+
+Generate CLAUDE.md content based on analysis depth and directory level:
+
+**⚠️ CRITICAL: Timestamp Header**
+
+Every CLAUDE.md file MUST start with a timestamp header as the very first line:
+
+```markdown
+> **Last Updated:** YYYY-MM-DD
+```
+
+- Use current date in ISO format (e.g., 2025-10-02)
+- Place immediately at the top, before any other content
+- Update this timestamp whenever the file is modified
+- This ensures users can immediately see documentation freshness
+
+### For Root CLAUDE.md
+
+```markdown
+> **Last Updated:** YYYY-MM-DD
+
+# CLAUDE.md - [Project Name]
+
+## Project Overview
+[Purpose, description, and key goals]
+
+## Tech Stack
+[Languages, frameworks, tools, package manager]
+
+## Repository Structure
+[Tree view of major directories with brief descriptions]
+
+## Key Modules
+[List of major modules/packages with brief descriptions]
+
+## Development Workflow
+[Commands, scripts, testing, deployment processes]
+
+## Code Quality
+[Linting, formatting, testing setup and requirements]
+
+## Conventions and Patterns
+[Coding standards, naming conventions, project-wide patterns]
+
+## Documentation Management
+[CLAUDE.md management rules - ALWAYS INCLUDE]
+
+<!-- CUSTOM:START -->
+<!-- User additions preserved during updates -->
+<!-- CUSTOM:END -->
+```
+
+#### For Package/Module CLAUDE.md:
+```markdown
+> **Last Updated:** YYYY-MM-DD
+
+# CLAUDE.md - [Package/Module Name]
+
+## Overview
+[Purpose discovered from code analysis]
+
+## Architecture
+[Internal structure based on analysis]
+
+## Key Components
+[Major files/classes/components found]
+
+## API/Exports
+[Public API discovered from exports]
+
+## Dependencies
+[Both internal and external]
+
+## Usage Patterns
+[Common patterns, examples, best practices]
+
+## Development Guidelines
+[Package-specific conventions, testing approach, contribution notes]
+
+<!-- CUSTOM:START -->
+<!-- User additions preserved during updates -->
+<!-- CUSTOM:END -->
+```
+
+#### For Feature/Component CLAUDE.md:
+```markdown
+# CLAUDE.md - [Feature/Component Name]
+
+## Purpose
+[Inferred from code structure and naming]
+
+## Components
+[List of sub-components with descriptions]
+
+## API
+[Props, methods, exports, interfaces]
+
+## Implementation Details
+[Key implementation decisions, patterns used]
+
+## Integration Points
+[How it connects with other parts of the system]
+
+## Usage Examples
+[Code examples showing common use cases]
+
+<!-- CUSTOM:START -->
+<!-- User additions preserved during updates -->
+<!-- CUSTOM:END -->
+```
+
+### 6. Documentation File Creation
+
+**Execution Strategy Based on Target Level**:
+
+**For Leaf Documentation**:
+1. Create multiple CLAUDE.md files within target area where necessary and appropriate
+2. Follow hierarchical order (packages → modules → features)
+3. Each level has appropriate scope without duplication
+4. Skip existing CLAUDE.md files (report in output)
+
+**For Area Root Documentation**:
+1. Create single CLAUDE.md at area root only
+2. Synthesize completedContext from leaf agents
+3. Focus on area-wide architecture and patterns
+
+**For Repository Root Documentation**:
+1. Create single CLAUDE.md at repository root only
+2. Synthesize completedContext from all area agents
+3. Provide system-wide architectural overview
+
+**Cross-Reference Management**:
+- Root mentions packages but doesn't detail them
+- Packages mention modules but don't detail implementations
+- Modules document their specific scope
+- Each level complements rather than duplicates others
+
+## Output
+
+Return comprehensive initialization results:
+```yaml
+success: boolean
+summary: |
+  Natural language summary of what was accomplished
+  Example: "Successfully documented the user-facing frontend pages including 47 components across 12 modules"
+
+targetAnalysis:
+  description: "What was analyzed (e.g., 'Next.js frontend user pages with 150 files')"
+  filesAnalyzed: 150
+  directoriesDocumented: 12
+  complexity: "low|medium|high" # Based on code patterns and business logic
+  keyFindings:
+    - "Uses Next.js App Router with RSC patterns"
+    - "Implements atomic design system with 47 components"
+    - "Heavy use of custom hooks for business logic"
+    - "Follows feature-based folder structure"
+
+createdFiles:
+  - path: "/app/frontend/CLAUDE.md"
+    level: "package|module|feature|root"
+    summary: "Created frontend package documentation with component inventory and architectural patterns"
+
+  - path: "/app/frontend/components/CLAUDE.md"
+    level: "module"
+    summary: "Created component library documentation with design system overview"
+
+coordinationContext: |
+  Natural language string with important findings for sibling agents.
+  Example for leaf agent: "The frontend user pages use a custom authentication hook at /hooks/useAuth that wraps Supabase auth. All API calls go through /lib/api-client with automatic retry logic. The design system is in /components/ui using Tailwind with custom design tokens. Found 47 components following atomic design (atoms, molecules, organisms). State management uses Zustand stores in /stores directory."
+
+  Example for area root: "Frontend architecture: Next.js 14 App Router, TypeScript, Tailwind CSS. Total 234 components split between user pages (47), admin pages (23), and shared UI library (164). Uses React Query for server state, Zustand for client state. All data fetching happens through custom hooks wrapping API client. Follows atomic design and feature-based organization."
+
+  Example for repository root: "Monorepo with clear frontend/backend separation. Frontend uses Next.js with modern patterns. Backend is Express with layered architecture. Database is PostgreSQL with Prisma. Authentication via Supabase. Clear API boundaries with TypeScript types shared via packages."
+
+skippedAreas: # Areas intentionally not documented (respecting siblingContext)
+  - path: "/app/frontend/admin"
+    reason: "Another agent is documenting admin pages"
+  - path: "/backend"
+    reason: "Backend documentation assigned to different agent"
+
+recommendations:
+  - "The /lib/analytics module is growing complex (8 files) and should get its own CLAUDE.md"
+  - "Consider splitting the large UserDashboard component (500+ lines) into smaller pieces"
+
+error: # Only if success: false
+  message: "Error description"
+  details: "Additional context"
+```
+
+## Implementation Commands
+
+### ⚠️ IMPORTANT: Prefer Git Commands Over Find/Glob
+
+**ALWAYS use git ls-files when in a git repository** - it automatically excludes node_modules, build outputs, and other ignored files. Only use find/glob as a last resort for non-git repositories.
+
+### Essential Discovery Commands
+
+**Check if git repository**:
+```bash
+test -d .git && echo "Git repo" || echo "Not a git repo"
+```
+
+**Find all package.json files (git repos)**:
+```bash
+git ls-files | grep 'package\.json$' | grep -v node_modules
+```
+
+**Find all package.json files (non-git fallback)**:
+```bash
+# IMPORTANT: Use "*/node_modules/*" to exclude ALL nested node_modules directories
+find . -name "package.json" -not -path "*/node_modules/*" -not -path "*/dist/*" -not -path "*/.next/*" -not -path "*/build/*" -maxdepth 5
+```
+
+**List all directories with source code**:
+```bash
+git ls-files | grep -E '\.(ts|tsx|js|jsx)$' | xargs dirname | sort -u
+```
+
+**Count files per directory**:
+```bash
+git ls-files | xargs dirname | sort | uniq -c | sort -rn
+```
+
+**Find complex directories (10+ source files)**:
+```bash
+for dir in $(git ls-files | xargs dirname | sort -u); do
+  count=$(git ls-files "$dir" | grep -E '\.(ts|tsx|js|jsx)$' | wc -l)
+  [ $count -ge 10 ] && echo "$dir: $count files"
+done
+```
+
+## Implementation Priorities
+
+1. **Thorough Discovery**: Analyze entire codebase without missing important patterns
+2. **Intelligent Filtering**: Only create CLAUDE.md where truly valuable
+3. **Contextual Content**: Generate content based on actual code analysis, not templates
+4. **Hierarchy Awareness**: Each level has appropriate scope without duplication
+5. **Pattern Detection**: Identify and document discovered conventions
+6. **Completeness**: Don't miss any important modules or features
+
+## Special Considerations
+
+### Monorepo Detection
+Identify monorepo tools and adjust:
+- Nx workspaces: Use project.json boundaries
+- Lerna: Use lerna.json configuration
+- Yarn/npm workspaces: Use workspace configuration
+- Turborepo: Identify pipeline configuration
+
+### Framework-Specific Intelligence
+Recognize and document framework patterns:
+- Next.js: app/pages routing, API routes, middleware
+- React: Component patterns, hooks, context providers
+- Angular: Modules, services, dependency injection
+- Vue: Composition API vs Options API
+- Express/Fastify: Route organization, middleware chains
+- NestJS: Module/controller/service architecture
+
+### Large Repository Handling
+For repositories with 1000+ files:
+- **Always use git ls-files** for file discovery (much faster than find/glob)
+- Sample files for pattern detection: `git ls-files | shuf -n 1000` for random sampling
+- Focus on entry points and exports: `git ls-files | grep -E '(index|main)\.'`
+- Prioritize package boundaries over deep diving
+- Set reasonable depth limits for non-git fallback only
+
+### Performance Optimization
+- Parallel analysis where possible
+- Cache file parsing results
+- Use incremental analysis for large codebases
+- Skip binary and large asset files
+
+## Critical Constraints
+
+**HIERARCHICAL AWARENESS**: This agent operates at different levels based on target:
+- **Leaf Level**: Document specific areas with multiple CLAUDE.md files
+- **Area Root Level**: Create single area overview from leaf findings
+- **Repository Root Level**: Create single system overview from all findings
+- **Boundary Respect**: Never create documentation outside assigned scope
+- **Context Flow**: Leaf agents provide findings for roots to synthesize
+
+**DISCOVERY-DRIVEN**: Unlike the change-driven update agent, this analyzes the existing codebase comprehensively to understand its current state.
+
+**QUALITY OVER QUANTITY**: Better to create fewer, high-quality CLAUDE.md files than many low-value ones.
+
+**NO ASSUMPTIONS**: All content must be derived from actual code analysis, not assumptions or templates.
+
+**HIERARCHY RESPECT**: Each documentation level should complement, not duplicate, other levels.