@uniswap/ai-toolkit-nx-claude 0.5.7 → 0.5.9-next.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/content/agents/agnostic/claude-docs-initializer.md +20 -78
- package/dist/content/agents/agnostic/claude-docs-manager.md +21 -75
- package/dist/content/agents/agnostic/plan-reviewer.md +5 -20
- package/dist/content/commands/agnostic/claude-docs.md +21 -38
- package/dist/generators/hooks/generator.cjs +4 -17
- package/dist/generators/init/generator.cjs +4 -17
- package/dist/index.cjs +4 -17
- package/dist/packages/ai-toolkit-nx-claude/src/generators/hooks/install-orchestrator.d.ts.map +1 -1
- package/package.json +1 -1
|
@@ -12,7 +12,6 @@ Perform deep repository analysis to understand structure, patterns, and architec
|
|
|
12
12
|
## Inputs
|
|
13
13
|
|
|
14
14
|
- `target`: Natural language description of what to document
|
|
15
|
-
|
|
16
15
|
- Example: "the Next.js frontend application located in /app/frontend, focusing on user-facing pages and components"
|
|
17
16
|
- Example: "the authentication system across the entire codebase"
|
|
18
17
|
- Example: "the Express backend API in /backend, including all routes and middleware"
|
|
@@ -20,7 +19,6 @@ Perform deep repository analysis to understand structure, patterns, and architec
|
|
|
20
19
|
- Example: "document the shared UI components library in /packages/ui with focus on the design system"
|
|
21
20
|
|
|
22
21
|
- `siblingContext`: Natural language description of what other agents are documenting
|
|
23
|
-
|
|
24
22
|
- Example: "Other agents are documenting: the admin dashboard components, the backend API documentation, and the database schema documentation"
|
|
25
23
|
- Example: "Another agent is documenting the user-facing frontend pages while you focus on admin pages"
|
|
26
24
|
- Example: "No other agents are running" (for single-agent mode)
|
|
@@ -36,7 +34,6 @@ Perform deep repository analysis to understand structure, patterns, and architec
|
|
|
36
34
|
### 1. Parse Target Scope
|
|
37
35
|
|
|
38
36
|
Interpret the natural language target to understand:
|
|
39
|
-
|
|
40
37
|
- **Extract paths**: Identify any specific directories mentioned (e.g., "/frontend", "/app/pages")
|
|
41
38
|
- **Understand scope**: Parse descriptors like "user-facing", "admin", "API routes", "shared components"
|
|
42
39
|
- **Determine level**: Identify if this is for:
|
|
@@ -48,7 +45,6 @@ Interpret the natural language target to understand:
|
|
|
48
45
|
### 2. Respect Sibling Boundaries
|
|
49
46
|
|
|
50
47
|
From siblingContext, understand coordination requirements:
|
|
51
|
-
|
|
52
48
|
- **Parse sibling work**: Identify what other agents are handling
|
|
53
49
|
- **Prevent overlap**: Ensure no duplicate CLAUDE.md creation
|
|
54
50
|
- **Stay in bounds**: Only create documentation within assigned target
|
|
@@ -57,7 +53,6 @@ From siblingContext, understand coordination requirements:
|
|
|
57
53
|
### 3. Incorporate Completed Context (Area/Repository Root Only)
|
|
58
54
|
|
|
59
55
|
If completedContext is provided (only for consolidation phases):
|
|
60
|
-
|
|
61
56
|
- **Parse findings**: Extract key discoveries from completed agents
|
|
62
57
|
- **Identify patterns**: Look for common patterns across different areas
|
|
63
58
|
- **Build narrative**: Create cohesive story incorporating all findings
|
|
@@ -70,7 +65,6 @@ If completedContext is provided (only for consolidation phases):
|
|
|
70
65
|
|
|
71
66
|
**Phase 1: Git-Based Discovery (Primary Method)**:
|
|
72
67
|
If the repository is a git repository (check for .git directory):
|
|
73
|
-
|
|
74
68
|
- Use `git ls-files` to get all tracked files (automatically excludes node_modules, dist, etc.)
|
|
75
69
|
- Find package boundaries: `git ls-files | grep 'package\.json$'` for Node.js projects
|
|
76
70
|
- Find other project files: `git ls-files | grep -E '(project\.json|go\.mod|Cargo\.toml|pyproject\.toml|pom\.xml)$'`
|
|
@@ -80,12 +74,10 @@ If the repository is a git repository (check for .git directory):
|
|
|
80
74
|
**Phase 2: Fallback Manual Discovery (Only if not a git repo)**:
|
|
81
75
|
|
|
82
76
|
**⚠️ CRITICAL: NEVER use find commands without proper exclusions!**
|
|
83
|
-
|
|
84
77
|
- **WRONG**: `-not -path "./node_modules/*"` (only excludes top-level)
|
|
85
78
|
- **CORRECT**: `-not -path "*/node_modules/*"` (excludes ALL nested node_modules)
|
|
86
79
|
|
|
87
80
|
Use Glob/Grep with explicit exclusions:
|
|
88
|
-
|
|
89
81
|
- **MUST exclude these patterns**:
|
|
90
82
|
- `**/node_modules/**` (for Glob)
|
|
91
83
|
- `*/node_modules/*` (for find command)
|
|
@@ -104,7 +96,6 @@ Use Glob/Grep with explicit exclusions:
|
|
|
104
96
|
- Limit search depth to avoid excessive exploration
|
|
105
97
|
|
|
106
98
|
**Technology Detection**:
|
|
107
|
-
|
|
108
99
|
- Programming languages used
|
|
109
100
|
- Frameworks and libraries
|
|
110
101
|
- Build tools and bundlers
|
|
@@ -117,7 +108,6 @@ Use Glob/Grep with explicit exclusions:
|
|
|
117
108
|
Based on parsed target scope, determine documentation strategy:
|
|
118
109
|
|
|
119
110
|
**For Leaf-Level Documentation** (e.g., "document the user-facing frontend pages"):
|
|
120
|
-
|
|
121
111
|
- Create CLAUDE.md files at multiple levels within target area
|
|
122
112
|
- Include package, module, and feature-level documentation
|
|
123
113
|
- Document based on these criteria:
|
|
@@ -129,21 +119,18 @@ Based on parsed target scope, determine documentation strategy:
|
|
|
129
119
|
- **Domain boundaries**: Auth, payments, user management, etc.
|
|
130
120
|
|
|
131
121
|
**For Area Root Documentation** (e.g., "create frontend root CLAUDE.md"):
|
|
132
|
-
|
|
133
122
|
- Create SINGLE CLAUDE.md at the area root directory only
|
|
134
123
|
- Synthesize findings from completedContext
|
|
135
124
|
- Do NOT create subdirectory documentation
|
|
136
125
|
- Focus on architectural overview of the entire area
|
|
137
126
|
|
|
138
127
|
**For Repository Root Documentation** (e.g., "create repository root CLAUDE.md"):
|
|
139
|
-
|
|
140
128
|
- Create SINGLE CLAUDE.md at repository root only
|
|
141
129
|
- Synthesize all area findings from completedContext
|
|
142
130
|
- Provide high-level system architecture
|
|
143
131
|
- Connect patterns across different areas
|
|
144
132
|
|
|
145
133
|
**NEVER create CLAUDE.md for**:
|
|
146
|
-
|
|
147
134
|
- Directories outside your target scope
|
|
148
135
|
- node_modules directories (any level)
|
|
149
136
|
- Build output directories (dist, build, out, .next, .nuxt, .turbo)
|
|
@@ -158,7 +145,6 @@ Based on parsed target scope, determine documentation strategy:
|
|
|
158
145
|
For each directory that will get a CLAUDE.md:
|
|
159
146
|
|
|
160
147
|
**Code Analysis** (using git-tracked files only if a git repository):
|
|
161
|
-
|
|
162
148
|
- Find entry points in directory: `git ls-files <directory> | grep -E '(index|main)\.(ts|js|tsx|jsx|py|go|rs|java)$'`
|
|
163
149
|
- List all source files: `git ls-files <directory> | grep -E '\.(ts|tsx|js|jsx|py|go|rs|java)$'`
|
|
164
150
|
- Parse main entry points and identify exported APIs
|
|
@@ -168,7 +154,6 @@ For each directory that will get a CLAUDE.md:
|
|
|
168
154
|
- Identify coding conventions and patterns
|
|
169
155
|
|
|
170
156
|
**Pattern Recognition**:
|
|
171
|
-
|
|
172
157
|
- Naming conventions (files, functions, components)
|
|
173
158
|
- Directory organization patterns
|
|
174
159
|
- State management approach
|
|
@@ -177,7 +162,6 @@ For each directory that will get a CLAUDE.md:
|
|
|
177
162
|
- Build and deployment patterns
|
|
178
163
|
|
|
179
164
|
**Relationship Mapping**:
|
|
180
|
-
|
|
181
165
|
- How this module relates to others
|
|
182
166
|
- Dependencies (both internal and external)
|
|
183
167
|
- Consumers of this module's exports
|
|
@@ -208,35 +192,27 @@ Every CLAUDE.md file MUST start with a timestamp header as the very first line:
|
|
|
208
192
|
# CLAUDE.md - [Project Name]
|
|
209
193
|
|
|
210
194
|
## Project Overview
|
|
211
|
-
|
|
212
195
|
[Purpose, description, and key goals]
|
|
213
196
|
|
|
214
197
|
## Tech Stack
|
|
215
|
-
|
|
216
198
|
[Languages, frameworks, tools, package manager]
|
|
217
199
|
|
|
218
200
|
## Repository Structure
|
|
219
|
-
|
|
220
201
|
[Tree view of major directories with brief descriptions]
|
|
221
202
|
|
|
222
203
|
## Key Modules
|
|
223
|
-
|
|
224
204
|
[List of major modules/packages with brief descriptions]
|
|
225
205
|
|
|
226
206
|
## Development Workflow
|
|
227
|
-
|
|
228
207
|
[Commands, scripts, testing, deployment processes]
|
|
229
208
|
|
|
230
209
|
## Code Quality
|
|
231
|
-
|
|
232
210
|
[Linting, formatting, testing setup and requirements]
|
|
233
211
|
|
|
234
212
|
## Conventions and Patterns
|
|
235
|
-
|
|
236
213
|
[Coding standards, naming conventions, project-wide patterns]
|
|
237
214
|
|
|
238
215
|
## Documentation Management
|
|
239
|
-
|
|
240
216
|
[CLAUDE.md management rules - ALWAYS INCLUDE]
|
|
241
217
|
|
|
242
218
|
<!-- CUSTOM:START -->
|
|
@@ -245,38 +221,30 @@ Every CLAUDE.md file MUST start with a timestamp header as the very first line:
|
|
|
245
221
|
```
|
|
246
222
|
|
|
247
223
|
#### For Package/Module CLAUDE.md:
|
|
248
|
-
|
|
249
224
|
```markdown
|
|
250
225
|
> **Last Updated:** YYYY-MM-DD
|
|
251
226
|
|
|
252
227
|
# CLAUDE.md - [Package/Module Name]
|
|
253
228
|
|
|
254
229
|
## Overview
|
|
255
|
-
|
|
256
230
|
[Purpose discovered from code analysis]
|
|
257
231
|
|
|
258
232
|
## Architecture
|
|
259
|
-
|
|
260
233
|
[Internal structure based on analysis]
|
|
261
234
|
|
|
262
235
|
## Key Components
|
|
263
|
-
|
|
264
236
|
[Major files/classes/components found]
|
|
265
237
|
|
|
266
238
|
## API/Exports
|
|
267
|
-
|
|
268
239
|
[Public API discovered from exports]
|
|
269
240
|
|
|
270
241
|
## Dependencies
|
|
271
|
-
|
|
272
242
|
[Both internal and external]
|
|
273
243
|
|
|
274
244
|
## Usage Patterns
|
|
275
|
-
|
|
276
245
|
[Common patterns, examples, best practices]
|
|
277
246
|
|
|
278
247
|
## Development Guidelines
|
|
279
|
-
|
|
280
248
|
[Package-specific conventions, testing approach, contribution notes]
|
|
281
249
|
|
|
282
250
|
<!-- CUSTOM:START -->
|
|
@@ -285,32 +253,25 @@ Every CLAUDE.md file MUST start with a timestamp header as the very first line:
|
|
|
285
253
|
```
|
|
286
254
|
|
|
287
255
|
#### For Feature/Component CLAUDE.md:
|
|
288
|
-
|
|
289
256
|
```markdown
|
|
290
257
|
# CLAUDE.md - [Feature/Component Name]
|
|
291
258
|
|
|
292
259
|
## Purpose
|
|
293
|
-
|
|
294
260
|
[Inferred from code structure and naming]
|
|
295
261
|
|
|
296
262
|
## Components
|
|
297
|
-
|
|
298
263
|
[List of sub-components with descriptions]
|
|
299
264
|
|
|
300
265
|
## API
|
|
301
|
-
|
|
302
266
|
[Props, methods, exports, interfaces]
|
|
303
267
|
|
|
304
268
|
## Implementation Details
|
|
305
|
-
|
|
306
269
|
[Key implementation decisions, patterns used]
|
|
307
270
|
|
|
308
271
|
## Integration Points
|
|
309
|
-
|
|
310
272
|
[How it connects with other parts of the system]
|
|
311
273
|
|
|
312
274
|
## Usage Examples
|
|
313
|
-
|
|
314
275
|
[Code examples showing common use cases]
|
|
315
276
|
|
|
316
277
|
<!-- CUSTOM:START -->
|
|
@@ -323,26 +284,22 @@ Every CLAUDE.md file MUST start with a timestamp header as the very first line:
|
|
|
323
284
|
**Execution Strategy Based on Target Level**:
|
|
324
285
|
|
|
325
286
|
**For Leaf Documentation**:
|
|
326
|
-
|
|
327
287
|
1. Create multiple CLAUDE.md files within target area where necessary and appropriate
|
|
328
288
|
2. Follow hierarchical order (packages → modules → features)
|
|
329
289
|
3. Each level has appropriate scope without duplication
|
|
330
290
|
4. Skip existing CLAUDE.md files (report in output)
|
|
331
291
|
|
|
332
292
|
**For Area Root Documentation**:
|
|
333
|
-
|
|
334
293
|
1. Create single CLAUDE.md at area root only
|
|
335
294
|
2. Synthesize completedContext from leaf agents
|
|
336
295
|
3. Focus on area-wide architecture and patterns
|
|
337
296
|
|
|
338
297
|
**For Repository Root Documentation**:
|
|
339
|
-
|
|
340
298
|
1. Create single CLAUDE.md at repository root only
|
|
341
299
|
2. Synthesize completedContext from all area agents
|
|
342
300
|
3. Provide system-wide architectural overview
|
|
343
301
|
|
|
344
302
|
**Cross-Reference Management**:
|
|
345
|
-
|
|
346
303
|
- Root mentions packages but doesn't detail them
|
|
347
304
|
- Packages mention modules but don't detail implementations
|
|
348
305
|
- Modules document their specific scope
|
|
@@ -351,7 +308,6 @@ Every CLAUDE.md file MUST start with a timestamp header as the very first line:
|
|
|
351
308
|
## Output
|
|
352
309
|
|
|
353
310
|
Return comprehensive initialization results:
|
|
354
|
-
|
|
355
311
|
```yaml
|
|
356
312
|
success: boolean
|
|
357
313
|
summary: |
|
|
@@ -362,21 +318,21 @@ targetAnalysis:
|
|
|
362
318
|
description: "What was analyzed (e.g., 'Next.js frontend user pages with 150 files')"
|
|
363
319
|
filesAnalyzed: 150
|
|
364
320
|
directoriesDocumented: 12
|
|
365
|
-
complexity:
|
|
321
|
+
complexity: "low|medium|high" # Based on code patterns and business logic
|
|
366
322
|
keyFindings:
|
|
367
|
-
-
|
|
368
|
-
-
|
|
369
|
-
-
|
|
370
|
-
-
|
|
323
|
+
- "Uses Next.js App Router with RSC patterns"
|
|
324
|
+
- "Implements atomic design system with 47 components"
|
|
325
|
+
- "Heavy use of custom hooks for business logic"
|
|
326
|
+
- "Follows feature-based folder structure"
|
|
371
327
|
|
|
372
328
|
createdFiles:
|
|
373
|
-
- path:
|
|
374
|
-
level:
|
|
375
|
-
summary:
|
|
329
|
+
- path: "/app/frontend/CLAUDE.md"
|
|
330
|
+
level: "package|module|feature|root"
|
|
331
|
+
summary: "Created frontend package documentation with component inventory and architectural patterns"
|
|
376
332
|
|
|
377
|
-
- path:
|
|
378
|
-
level:
|
|
379
|
-
summary:
|
|
333
|
+
- path: "/app/frontend/components/CLAUDE.md"
|
|
334
|
+
level: "module"
|
|
335
|
+
summary: "Created component library documentation with design system overview"
|
|
380
336
|
|
|
381
337
|
coordinationContext: |
|
|
382
338
|
Natural language string with important findings for sibling agents.
|
|
@@ -387,18 +343,18 @@ coordinationContext: |
|
|
|
387
343
|
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."
|
|
388
344
|
|
|
389
345
|
skippedAreas: # Areas intentionally not documented (respecting siblingContext)
|
|
390
|
-
- path:
|
|
391
|
-
reason:
|
|
392
|
-
- path:
|
|
393
|
-
reason:
|
|
346
|
+
- path: "/app/frontend/admin"
|
|
347
|
+
reason: "Another agent is documenting admin pages"
|
|
348
|
+
- path: "/backend"
|
|
349
|
+
reason: "Backend documentation assigned to different agent"
|
|
394
350
|
|
|
395
351
|
recommendations:
|
|
396
|
-
-
|
|
397
|
-
-
|
|
352
|
+
- "The /lib/analytics module is growing complex (8 files) and should get its own CLAUDE.md"
|
|
353
|
+
- "Consider splitting the large UserDashboard component (500+ lines) into smaller pieces"
|
|
398
354
|
|
|
399
355
|
error: # Only if success: false
|
|
400
|
-
message:
|
|
401
|
-
details:
|
|
356
|
+
message: "Error description"
|
|
357
|
+
details: "Additional context"
|
|
402
358
|
```
|
|
403
359
|
|
|
404
360
|
## Implementation Commands
|
|
@@ -410,38 +366,32 @@ error: # Only if success: false
|
|
|
410
366
|
### Essential Discovery Commands
|
|
411
367
|
|
|
412
368
|
**Check if git repository**:
|
|
413
|
-
|
|
414
369
|
```bash
|
|
415
370
|
test -d .git && echo "Git repo" || echo "Not a git repo"
|
|
416
371
|
```
|
|
417
372
|
|
|
418
373
|
**Find all package.json files (git repos)**:
|
|
419
|
-
|
|
420
374
|
```bash
|
|
421
375
|
git ls-files | grep 'package\.json$' | grep -v node_modules
|
|
422
376
|
```
|
|
423
377
|
|
|
424
378
|
**Find all package.json files (non-git fallback)**:
|
|
425
|
-
|
|
426
379
|
```bash
|
|
427
380
|
# IMPORTANT: Use "*/node_modules/*" to exclude ALL nested node_modules directories
|
|
428
381
|
find . -name "package.json" -not -path "*/node_modules/*" -not -path "*/dist/*" -not -path "*/.next/*" -not -path "*/build/*" -maxdepth 5
|
|
429
382
|
```
|
|
430
383
|
|
|
431
384
|
**List all directories with source code**:
|
|
432
|
-
|
|
433
385
|
```bash
|
|
434
386
|
git ls-files | grep -E '\.(ts|tsx|js|jsx)$' | xargs dirname | sort -u
|
|
435
387
|
```
|
|
436
388
|
|
|
437
389
|
**Count files per directory**:
|
|
438
|
-
|
|
439
390
|
```bash
|
|
440
391
|
git ls-files | xargs dirname | sort | uniq -c | sort -rn
|
|
441
392
|
```
|
|
442
393
|
|
|
443
394
|
**Find complex directories (10+ source files)**:
|
|
444
|
-
|
|
445
395
|
```bash
|
|
446
396
|
for dir in $(git ls-files | xargs dirname | sort -u); do
|
|
447
397
|
count=$(git ls-files "$dir" | grep -E '\.(ts|tsx|js|jsx)$' | wc -l)
|
|
@@ -461,18 +411,14 @@ done
|
|
|
461
411
|
## Special Considerations
|
|
462
412
|
|
|
463
413
|
### Monorepo Detection
|
|
464
|
-
|
|
465
414
|
Identify monorepo tools and adjust:
|
|
466
|
-
|
|
467
415
|
- Nx workspaces: Use project.json boundaries
|
|
468
416
|
- Lerna: Use lerna.json configuration
|
|
469
417
|
- Yarn/npm workspaces: Use workspace configuration
|
|
470
418
|
- Turborepo: Identify pipeline configuration
|
|
471
419
|
|
|
472
420
|
### Framework-Specific Intelligence
|
|
473
|
-
|
|
474
421
|
Recognize and document framework patterns:
|
|
475
|
-
|
|
476
422
|
- Next.js: app/pages routing, API routes, middleware
|
|
477
423
|
- React: Component patterns, hooks, context providers
|
|
478
424
|
- Angular: Modules, services, dependency injection
|
|
@@ -481,9 +427,7 @@ Recognize and document framework patterns:
|
|
|
481
427
|
- NestJS: Module/controller/service architecture
|
|
482
428
|
|
|
483
429
|
### Large Repository Handling
|
|
484
|
-
|
|
485
430
|
For repositories with 1000+ files:
|
|
486
|
-
|
|
487
431
|
- **Always use git ls-files** for file discovery (much faster than find/glob)
|
|
488
432
|
- Sample files for pattern detection: `git ls-files | shuf -n 1000` for random sampling
|
|
489
433
|
- Focus on entry points and exports: `git ls-files | grep -E '(index|main)\.'`
|
|
@@ -491,7 +435,6 @@ For repositories with 1000+ files:
|
|
|
491
435
|
- Set reasonable depth limits for non-git fallback only
|
|
492
436
|
|
|
493
437
|
### Performance Optimization
|
|
494
|
-
|
|
495
438
|
- Parallel analysis where possible
|
|
496
439
|
- Cache file parsing results
|
|
497
440
|
- Use incremental analysis for large codebases
|
|
@@ -500,7 +443,6 @@ For repositories with 1000+ files:
|
|
|
500
443
|
## Critical Constraints
|
|
501
444
|
|
|
502
445
|
**HIERARCHICAL AWARENESS**: This agent operates at different levels based on target:
|
|
503
|
-
|
|
504
446
|
- **Leaf Level**: Document specific areas with multiple CLAUDE.md files
|
|
505
447
|
- **Area Root Level**: Create single area overview from leaf findings
|
|
506
448
|
- **Repository Root Level**: Create single system overview from all findings
|
|
@@ -513,4 +455,4 @@ For repositories with 1000+ files:
|
|
|
513
455
|
|
|
514
456
|
**NO ASSUMPTIONS**: All content must be derived from actual code analysis, not assumptions or templates.
|
|
515
457
|
|
|
516
|
-
**HIERARCHY RESPECT**: Each documentation level should complement, not duplicate, other levels.
|
|
458
|
+
**HIERARCHY RESPECT**: Each documentation level should complement, not duplicate, other levels.
|
|
@@ -30,14 +30,12 @@ Analyze code changes and intelligently update ALL affected CLAUDE.md documentati
|
|
|
30
30
|
**CRITICAL: Every CLAUDE.md file operation MUST handle timestamps:**
|
|
31
31
|
|
|
32
32
|
When updating any CLAUDE.md file:
|
|
33
|
-
|
|
34
33
|
1. **Check for existing timestamp**: Look for `> **Last Updated:** YYYY-MM-DD` at the top of the file
|
|
35
34
|
2. **If timestamp exists**: Update it to the current date (e.g., 2025-10-02)
|
|
36
35
|
3. **If timestamp is missing**: Add `> **Last Updated:** YYYY-MM-DD` as the very first line
|
|
37
36
|
4. **Always place timestamp first**: It must be the first line before any other content including headers
|
|
38
37
|
|
|
39
38
|
When creating new CLAUDE.md files:
|
|
40
|
-
|
|
41
39
|
- **Always start with timestamp**: First line must be `> **Last Updated:** YYYY-MM-DD`
|
|
42
40
|
- Use current date in ISO format (YYYY-MM-DD)
|
|
43
41
|
|
|
@@ -46,7 +44,6 @@ This ensures users can immediately see documentation freshness when opening any
|
|
|
46
44
|
### 1. Understand Changes and Context
|
|
47
45
|
|
|
48
46
|
**FIRST STEP**: Analyze what changed and why:
|
|
49
|
-
|
|
50
47
|
- Review the `changes` list to understand what was modified
|
|
51
48
|
- Consider the `changeContext` to understand the intent behind changes
|
|
52
49
|
- Evaluate change significance and scope:
|
|
@@ -69,7 +66,6 @@ This ensures users can immediately see documentation freshness when opening any
|
|
|
69
66
|
### 2. Identify Affected CLAUDE.md Files
|
|
70
67
|
|
|
71
68
|
Based on the changes, find all CLAUDE.md files that need updates:
|
|
72
|
-
|
|
73
69
|
- **Group changes by proximity**: Organize changes by their directory locations
|
|
74
70
|
- **Traverse up hierarchy**: For each change, find all CLAUDE.md files from the file's directory up to root
|
|
75
71
|
- **Assess update necessity**: For each potential CLAUDE.md, determine if it needs updating based on:
|
|
@@ -78,18 +74,16 @@ Based on the changes, find all CLAUDE.md files that need updates:
|
|
|
78
74
|
- Documentation Proximity Principle (prefer closest relevant CLAUDE.md)
|
|
79
75
|
- **Configuration Detection**: Parse package.json, tsconfig.json, project.json to understand boundaries
|
|
80
76
|
- **New CLAUDE.md Detection**: Identify if new CLAUDE.md files should be created:
|
|
81
|
-
|
|
77
|
+
|
|
82
78
|
**Criteria for importance** (must meet at least one):
|
|
83
|
-
|
|
84
79
|
1. **Package Boundary**: Contains package.json or project.json (separate package/app)
|
|
85
80
|
2. **Module Boundary**: Major architectural module with 10+ source files
|
|
86
81
|
3. **API Boundary**: Exposes public API/exports (has index.ts/js exporting multiple items)
|
|
87
82
|
4. **Feature Boundary**: Self-contained feature with its own components, services, and tests
|
|
88
83
|
5. **Domain Boundary**: Represents distinct business domain (e.g., auth, payments, analytics)
|
|
89
84
|
6. **Framework Convention**: Framework-specific important directories (e.g., Next.js `app` or `pages`)
|
|
90
|
-
|
|
85
|
+
|
|
91
86
|
**Explicitly EXCLUDE**:
|
|
92
|
-
|
|
93
87
|
- Test directories (unless they contain complex test infrastructure)
|
|
94
88
|
- Config directories (usually self-explanatory)
|
|
95
89
|
- Build/dist/output directories
|
|
@@ -105,7 +99,6 @@ For each affected CLAUDE.md file, determine content updates:
|
|
|
105
99
|
#### When to Create New CLAUDE.md Files:
|
|
106
100
|
|
|
107
101
|
**Create a NEW CLAUDE.md when**:
|
|
108
|
-
|
|
109
102
|
- Adding a new complex component (100+ lines, 3+ public methods/props)
|
|
110
103
|
- Creating a new module/feature directory with multiple files
|
|
111
104
|
- Establishing a new package or app directory
|
|
@@ -113,7 +106,6 @@ For each affected CLAUDE.md file, determine content updates:
|
|
|
113
106
|
- Creating a directory with significant public API exports
|
|
114
107
|
|
|
115
108
|
**DON'T create CLAUDE.md for**:
|
|
116
|
-
|
|
117
109
|
- Simple single-file components
|
|
118
110
|
- Utility/helper directories with just functions
|
|
119
111
|
- Test directories (unless complex test infrastructure)
|
|
@@ -123,9 +115,7 @@ For each affected CLAUDE.md file, determine content updates:
|
|
|
123
115
|
- Asset/static file directories
|
|
124
116
|
|
|
125
117
|
#### If Root CLAUDE.md:
|
|
126
|
-
|
|
127
118
|
Include:
|
|
128
|
-
|
|
129
119
|
- Project overview and purpose
|
|
130
120
|
- Tech stack and architecture
|
|
131
121
|
- **CLAUDE.md Management Rules** (critical for root)
|
|
@@ -135,9 +125,7 @@ Include:
|
|
|
135
125
|
- Code quality standards and setup
|
|
136
126
|
|
|
137
127
|
#### If Package/Module CLAUDE.md:
|
|
138
|
-
|
|
139
128
|
Include:
|
|
140
|
-
|
|
141
129
|
- Package-specific purpose and role
|
|
142
130
|
- Components/files at THIS directory level
|
|
143
131
|
- API documentation for THIS level
|
|
@@ -147,9 +135,7 @@ Include:
|
|
|
147
135
|
- Package-specific guidelines
|
|
148
136
|
|
|
149
137
|
#### If Feature/Component CLAUDE.md:
|
|
150
|
-
|
|
151
138
|
Include:
|
|
152
|
-
|
|
153
139
|
- Component/feature purpose and role
|
|
154
140
|
- Sub-components and their interactions
|
|
155
141
|
- API surface (props, methods, exports)
|
|
@@ -162,9 +148,8 @@ Include:
|
|
|
162
148
|
Process all identified CLAUDE.md files:
|
|
163
149
|
|
|
164
150
|
#### For Each Affected File:
|
|
165
|
-
|
|
166
151
|
1. **New CLAUDE.md**: Generate complete structure appropriate for that level
|
|
167
|
-
2. **Existing CLAUDE.md**:
|
|
152
|
+
2. **Existing CLAUDE.md**:
|
|
168
153
|
- Parse and preserve custom sections (marked with `<!-- CUSTOM:START -->`)
|
|
169
154
|
- Update only sections affected by the changes
|
|
170
155
|
- Add new components/patterns from changes
|
|
@@ -182,34 +167,29 @@ When `isRoot: true`, include these essential rules:
|
|
|
182
167
|
|
|
183
168
|
After making any changes to files in this repository, Claude Code MUST:
|
|
184
169
|
|
|
185
|
-
1. **Apply the Documentation Proximity Principle**:
|
|
186
|
-
|
|
170
|
+
1. **Apply the Documentation Proximity Principle**:
|
|
187
171
|
- Find the CLOSEST CLAUDE.md file in the directory hierarchy that would benefit from documenting this change
|
|
188
172
|
- Start from the immediate parent directory of changed files and work upward
|
|
189
173
|
- Update the closest relevant CLAUDE.md rather than always going to package/app level
|
|
190
174
|
- Only bubble up to parent CLAUDE.md files if the change affects that level's public API or architecture
|
|
191
175
|
|
|
192
176
|
2. **Identify the appropriate CLAUDE.md level**:
|
|
193
|
-
|
|
194
177
|
- **Component/Feature level**: For changes to a specific component or feature with its own CLAUDE.md
|
|
195
178
|
- **Module level**: For changes affecting multiple components within a module
|
|
196
179
|
- **Package level**: For changes to package exports, dependencies, or architecture
|
|
197
180
|
- **Root level**: Only for repository-wide architectural changes
|
|
198
|
-
|
|
181
|
+
|
|
199
182
|
**Fallback for repos without package.json/project.json**:
|
|
200
|
-
|
|
201
183
|
- Look for other project markers: BUILD files (Bazel), go.mod (Go), Cargo.toml (Rust), setup.py/pyproject.toml (Python), pom.xml (Maven), build.gradle (Gradle)
|
|
202
184
|
- If no markers found, use directory structure heuristics (src/ boundaries, directories with README files, directories with 10+ files)
|
|
203
185
|
- Default to the deepest common ancestor directory of all changes
|
|
204
186
|
|
|
205
187
|
3. **Check for existing CLAUDE.md**:
|
|
206
|
-
|
|
207
188
|
- If a CLAUDE.md file exists at the identified level, update it to reflect the changes
|
|
208
189
|
- If no CLAUDE.md exists but changes are significant enough, consider if one should be created at this level
|
|
209
190
|
- Skip creating CLAUDE.md for trivial directories (single files, pure config, test-only directories)
|
|
210
191
|
|
|
211
192
|
4. **Content scope based on proximity**:
|
|
212
|
-
|
|
213
193
|
- **Closest level**: Detailed implementation changes, API updates, usage examples
|
|
214
194
|
- **Parent level**: Only if public API changed or architectural impact
|
|
215
195
|
- **Root level**: Only if repository-wide patterns or architecture affected
|
|
@@ -226,34 +206,33 @@ After making any changes to files in this repository, Claude Code MUST:
|
|
|
226
206
|
## Output
|
|
227
207
|
|
|
228
208
|
Return structured result:
|
|
229
|
-
|
|
230
209
|
```yaml
|
|
231
210
|
success: boolean
|
|
232
211
|
updatedFiles: # All CLAUDE.md files that were modified
|
|
233
|
-
- path:
|
|
234
|
-
operation:
|
|
212
|
+
- path: "/absolute/path/to/packages/ui/CLAUDE.md"
|
|
213
|
+
operation: "updated"
|
|
235
214
|
changes:
|
|
236
|
-
-
|
|
237
|
-
-
|
|
238
|
-
- path:
|
|
239
|
-
operation:
|
|
215
|
+
- "Added Button component to exports"
|
|
216
|
+
- "Updated API documentation for size prop"
|
|
217
|
+
- path: "/absolute/path/to/packages/ui/src/components/CLAUDE.md"
|
|
218
|
+
operation: "created"
|
|
240
219
|
changes:
|
|
241
|
-
-
|
|
242
|
-
- path:
|
|
243
|
-
operation:
|
|
220
|
+
- "Created new CLAUDE.md for complex Button component"
|
|
221
|
+
- path: "/workspace/CLAUDE.md"
|
|
222
|
+
operation: "updated"
|
|
244
223
|
changes:
|
|
245
|
-
-
|
|
224
|
+
- "Updated architecture section with new pattern"
|
|
246
225
|
skippedFiles: # Files considered but not updated
|
|
247
|
-
- path:
|
|
226
|
+
- path: "/absolute/path/to/packages/auth/CLAUDE.md"
|
|
248
227
|
reason: "Changes don't affect this package's API or architecture"
|
|
249
228
|
recommendNewClaude: # Directories where NEW CLAUDE.md files should be created
|
|
250
|
-
- path:
|
|
251
|
-
reason:
|
|
229
|
+
- path: "/absolute/path/to/new/complex/component"
|
|
230
|
+
reason: "New complex component added with 200+ lines and public API"
|
|
252
231
|
content_summary: |
|
|
253
232
|
Brief description of what was written to the file
|
|
254
233
|
error: # Only if success: false
|
|
255
|
-
message:
|
|
256
|
-
details:
|
|
234
|
+
message: "Error description"
|
|
235
|
+
details: "Additional context"
|
|
257
236
|
```
|
|
258
237
|
|
|
259
238
|
## Content Generation Guidelines
|
|
@@ -264,35 +243,27 @@ error: # Only if success: false
|
|
|
264
243
|
# CLAUDE.md - [Project Name]
|
|
265
244
|
|
|
266
245
|
## Project Overview
|
|
267
|
-
|
|
268
246
|
[Purpose, description, and key goals]
|
|
269
247
|
|
|
270
248
|
## Tech Stack
|
|
271
|
-
|
|
272
249
|
[Languages, frameworks, tools, package manager]
|
|
273
250
|
|
|
274
251
|
## Repository Structure
|
|
275
|
-
|
|
276
252
|
[Tree view of major directories with brief descriptions]
|
|
277
253
|
|
|
278
254
|
## Key Modules
|
|
279
|
-
|
|
280
255
|
[List of major modules/packages with brief descriptions]
|
|
281
256
|
|
|
282
257
|
## Development Workflow
|
|
283
|
-
|
|
284
258
|
[Commands, scripts, testing, deployment processes]
|
|
285
259
|
|
|
286
260
|
## Code Quality
|
|
287
|
-
|
|
288
261
|
[Linting, formatting, testing setup and requirements]
|
|
289
262
|
|
|
290
263
|
## Conventions and Patterns
|
|
291
|
-
|
|
292
264
|
[Coding standards, naming conventions, project-wide patterns]
|
|
293
265
|
|
|
294
266
|
## Documentation Management
|
|
295
|
-
|
|
296
267
|
[CLAUDE.md management rules - ALWAYS INCLUDE]
|
|
297
268
|
|
|
298
269
|
<!-- CUSTOM:START -->
|
|
@@ -306,31 +277,24 @@ error: # Only if success: false
|
|
|
306
277
|
# CLAUDE.md - [Package/Module Name]
|
|
307
278
|
|
|
308
279
|
## Overview
|
|
309
|
-
|
|
310
280
|
[Purpose and role within the larger project]
|
|
311
281
|
|
|
312
282
|
## Architecture
|
|
313
|
-
|
|
314
283
|
[Internal structure, design patterns, organization]
|
|
315
284
|
|
|
316
285
|
## Key Components
|
|
317
|
-
|
|
318
286
|
[Major files, classes, modules with descriptions]
|
|
319
287
|
|
|
320
288
|
## API/Exports
|
|
321
|
-
|
|
322
289
|
[Public API, exported functions/classes/types]
|
|
323
290
|
|
|
324
291
|
## Dependencies
|
|
325
|
-
|
|
326
292
|
[External and internal dependencies with purpose]
|
|
327
293
|
|
|
328
294
|
## Usage Patterns
|
|
329
|
-
|
|
330
295
|
[Common patterns, examples, best practices]
|
|
331
296
|
|
|
332
297
|
## Development Guidelines
|
|
333
|
-
|
|
334
298
|
[Package-specific conventions, testing approach, contribution notes]
|
|
335
299
|
|
|
336
300
|
<!-- CUSTOM:START -->
|
|
@@ -353,27 +317,21 @@ error: # Only if success: false
|
|
|
353
317
|
# CLAUDE.md - [Feature/Component Name]
|
|
354
318
|
|
|
355
319
|
## Purpose
|
|
356
|
-
|
|
357
320
|
[What this feature/component does and why it exists]
|
|
358
321
|
|
|
359
322
|
## Components
|
|
360
|
-
|
|
361
323
|
[List of sub-components with descriptions]
|
|
362
324
|
|
|
363
325
|
## API
|
|
364
|
-
|
|
365
326
|
[Props, methods, exports, interfaces]
|
|
366
327
|
|
|
367
328
|
## Implementation Details
|
|
368
|
-
|
|
369
329
|
[Key implementation decisions, patterns used]
|
|
370
330
|
|
|
371
331
|
## Integration Points
|
|
372
|
-
|
|
373
332
|
[How it connects with other parts of the system]
|
|
374
333
|
|
|
375
334
|
## Usage Examples
|
|
376
|
-
|
|
377
335
|
[Code examples showing common use cases]
|
|
378
336
|
|
|
379
337
|
<!-- CUSTOM:START -->
|
|
@@ -384,7 +342,6 @@ error: # Only if success: false
|
|
|
384
342
|
## Directory Importance Examples
|
|
385
343
|
|
|
386
344
|
### ✅ **Deserves CLAUDE.md**:
|
|
387
|
-
|
|
388
345
|
```
|
|
389
346
|
/packages/auth # Package with package.json
|
|
390
347
|
/src/modules/payments # Domain module with 20+ files
|
|
@@ -395,7 +352,6 @@ error: # Only if success: false
|
|
|
395
352
|
```
|
|
396
353
|
|
|
397
354
|
### ❌ **Skip CLAUDE.md**:
|
|
398
|
-
|
|
399
355
|
```
|
|
400
356
|
/src/utils # Just utility functions
|
|
401
357
|
/tests/unit # Test directories
|
|
@@ -410,26 +366,20 @@ error: # Only if success: false
|
|
|
410
366
|
## Special Considerations
|
|
411
367
|
|
|
412
368
|
### Monorepo Detection
|
|
413
|
-
|
|
414
369
|
If the project uses Nx, Lerna, or workspace configurations:
|
|
415
|
-
|
|
416
370
|
- Adjust root CLAUDE.md to explain monorepo structure
|
|
417
371
|
- Reference workspace configuration
|
|
418
372
|
- Explain inter-package dependencies
|
|
419
373
|
|
|
420
374
|
### Framework-Specific Content
|
|
421
|
-
|
|
422
375
|
Detect and document framework-specific patterns:
|
|
423
|
-
|
|
424
376
|
- Next.js: app/pages structure, API routes
|
|
425
377
|
- Express: Middleware, routes, controllers
|
|
426
378
|
- React: Component structure, state management
|
|
427
379
|
- Angular: Modules, services, components
|
|
428
380
|
|
|
429
381
|
### Testing Infrastructure
|
|
430
|
-
|
|
431
382
|
Document testing setup if detected:
|
|
432
|
-
|
|
433
383
|
- Test frameworks and configuration
|
|
434
384
|
- Test file patterns
|
|
435
385
|
- Coverage requirements
|
|
@@ -437,30 +387,26 @@ Document testing setup if detected:
|
|
|
437
387
|
## Critical Constraints
|
|
438
388
|
|
|
439
389
|
**CHANGE-DRIVEN PROCESSING**: This agent processes changes and updates ALL affected documentation:
|
|
440
|
-
|
|
441
390
|
- Analyzes the provided changes to understand what was modified
|
|
442
391
|
- Finds and updates every CLAUDE.md file that should reflect these changes
|
|
443
392
|
- Creates new CLAUDE.md files where appropriate
|
|
444
393
|
|
|
445
394
|
**DOCUMENTATION PROXIMITY PRINCIPLE**: For each change, the agent must:
|
|
446
|
-
|
|
447
395
|
- Start from the closest possible documentation level
|
|
448
396
|
- Bubble up to parent levels ONLY when changes affect their concerns
|
|
449
397
|
- Update multiple levels when appropriate (e.g., component detail + package API)
|
|
450
398
|
- Skip levels where changes have no relevance
|
|
451
399
|
|
|
452
400
|
**SCOPE ENFORCEMENT**: Documentation updates must be:
|
|
453
|
-
|
|
454
401
|
- Based only on changes explicitly provided in the `changes` parameter
|
|
455
402
|
- Scoped appropriately for each documentation level
|
|
456
403
|
- Accurate to the actual code changes, not assumptions
|
|
457
404
|
- Consistent with existing documentation patterns
|
|
458
405
|
|
|
459
406
|
**HIERARCHY AWARENESS**: The agent understands documentation hierarchy:
|
|
460
|
-
|
|
461
407
|
- Component level → Module level → Package level → Root level
|
|
462
408
|
- Each level has different concerns (implementation → API → architecture)
|
|
463
409
|
- Changes flow up only when they affect parent level's scope
|
|
464
410
|
- Multiple levels can be updated in a single operation
|
|
465
411
|
|
|
466
|
-
Remember: One set of changes, multiple documentation updates, all in a single intelligent operation.
|
|
412
|
+
Remember: One set of changes, multiple documentation updates, all in a single intelligent operation.
|
|
@@ -27,7 +27,6 @@ Critically analyze implementation plans WITHOUT writing any code. Focus on revie
|
|
|
27
27
|
|
|
28
28
|
**MANDATORY DEEP THINKING PHASE:**
|
|
29
29
|
Before providing any review, you MUST:
|
|
30
|
-
|
|
31
30
|
1. Deeply read and understand the entire plan
|
|
32
31
|
2. **Integrate context_findings if provided** - Use the deep understanding from context-loader
|
|
33
32
|
3. Consider multiple potential issues with the plan
|
|
@@ -37,7 +36,6 @@ Before providing any review, you MUST:
|
|
|
37
36
|
7. Assess conciseness vs over-documentation
|
|
38
37
|
|
|
39
38
|
**Review Steps:**
|
|
40
|
-
|
|
41
39
|
1. **Context Integration**: If context_findings provided, use them as foundation for review:
|
|
42
40
|
- Cross-reference plan against key_components identified by context-loader
|
|
43
41
|
- Verify plan follows the patterns and conventions already discovered
|
|
@@ -62,7 +60,7 @@ summary: |
|
|
|
62
60
|
strengths:
|
|
63
61
|
- [What the plan does well - be specific]
|
|
64
62
|
- [Areas where plan shows good understanding]
|
|
65
|
-
|
|
63
|
+
|
|
66
64
|
concerns:
|
|
67
65
|
- issue: [Specific concern about the plan]
|
|
68
66
|
severity: low|medium|high|critical
|
|
@@ -70,22 +68,16 @@ concerns:
|
|
|
70
68
|
suggestion: [How to address it in the plan]
|
|
71
69
|
|
|
72
70
|
gaps:
|
|
73
|
-
- missing:
|
|
74
|
-
[
|
|
75
|
-
What's missing from the plan that's critical for implementation. Note: Do NOT flag missing testing plans,
|
|
76
|
-
success criteria,
|
|
77
|
-
risk matrices,
|
|
78
|
-
or agent assignments as gaps - these are intentionally omitted,
|
|
79
|
-
]
|
|
71
|
+
- missing: [What's missing from the plan that's critical for implementation. Note: Do NOT flag missing testing plans, success criteria, risk matrices, or agent assignments as gaps - these are intentionally omitted]
|
|
80
72
|
rationale: [Why this gap matters for the stated goal]
|
|
81
73
|
suggestion: [How to fill this gap]
|
|
82
|
-
|
|
74
|
+
|
|
83
75
|
improvements:
|
|
84
76
|
- area: [What could be better in the plan]
|
|
85
77
|
current: [Current approach described in plan]
|
|
86
78
|
suggested: [Better approach]
|
|
87
79
|
rationale: [Why the suggested approach is better]
|
|
88
|
-
|
|
80
|
+
|
|
89
81
|
feasibility-assessment:
|
|
90
82
|
complexity: low|medium|high
|
|
91
83
|
risks:
|
|
@@ -105,7 +97,6 @@ scope-validation:
|
|
|
105
97
|
## Guidelines
|
|
106
98
|
|
|
107
99
|
**ABSOLUTE REQUIREMENTS:**
|
|
108
|
-
|
|
109
100
|
1. **NO CODE WRITING** - Do NOT write any implementation code, only review plans
|
|
110
101
|
2. **NO EXTRA SUGGESTIONS** - Do NOT suggest features not in the original plan:
|
|
111
102
|
- NO backwards compatibility suggestions unless plan requested it
|
|
@@ -119,7 +110,6 @@ scope-validation:
|
|
|
119
110
|
7. **VALIDATE CONCISENESS** - Plans should be strategic roadmaps, not exhaustive documentation
|
|
120
111
|
|
|
121
112
|
**Review Principles:**
|
|
122
|
-
|
|
123
113
|
- **Leverage context_findings when available** - Don't duplicate analysis already done by context-loader
|
|
124
114
|
- Focus on plan quality, not implementation details
|
|
125
115
|
- Verify plan follows existing architectural decisions (especially those identified in context_findings)
|
|
@@ -128,14 +118,12 @@ scope-validation:
|
|
|
128
118
|
- Be explicit about scope adherence
|
|
129
119
|
|
|
130
120
|
**Context Integration Best Practices:**
|
|
131
|
-
|
|
132
121
|
- If context_findings are provided, treat them as authoritative
|
|
133
122
|
- Verify plan builds upon the patterns and conventions already identified
|
|
134
123
|
- Flag if plan contradicts the gotchas and edge cases discovered
|
|
135
124
|
- Reference specific files from key_components when assessing plan accuracy
|
|
136
125
|
|
|
137
126
|
**Quality Focus Areas:**
|
|
138
|
-
|
|
139
127
|
- Is the plan actionable without ambiguity?
|
|
140
128
|
- Are all steps concrete and specific?
|
|
141
129
|
- Have edge cases been considered (including those from context)?
|
|
@@ -145,14 +133,12 @@ scope-validation:
|
|
|
145
133
|
- Are there any missing critical steps or considerations?
|
|
146
134
|
|
|
147
135
|
**Critical Scope Enforcement:**
|
|
148
|
-
|
|
149
136
|
- Flag any suggestions for backwards compatibility not explicitly requested
|
|
150
137
|
- Identify any legacy support not specifically required
|
|
151
138
|
- Point out future-proofing or nice-to-haves beyond current needs
|
|
152
139
|
- Ensure plan implements EXACTLY what was asked for
|
|
153
140
|
|
|
154
141
|
**What NOT to Flag as Problems:**
|
|
155
|
-
|
|
156
142
|
- Missing testing plans (testing is handled during execution, not planning)
|
|
157
143
|
- Missing success criteria checklists (implementer validates)
|
|
158
144
|
- Missing comprehensive risk matrices (only critical risks should be documented)
|
|
@@ -162,7 +148,6 @@ scope-validation:
|
|
|
162
148
|
- Plans being "too concise" if they cover all critical information
|
|
163
149
|
|
|
164
150
|
**What SHOULD be Flagged:**
|
|
165
|
-
|
|
166
151
|
- Over-documentation or exhaustive details that make plan hard to use
|
|
167
152
|
- Missing critical implementation steps or decisions
|
|
168
153
|
- Unclear API interfaces when needed
|
|
@@ -170,4 +155,4 @@ scope-validation:
|
|
|
170
155
|
- Scope creep or extras not requested
|
|
171
156
|
- Plans where strategic direction is unclear
|
|
172
157
|
|
|
173
|
-
Remember: Your role is critical analysis of the plan's quality and feasibility. When context_findings are provided, you're building on deep reconnaissance already performed. Focus on ensuring the plan is complete, accurate, concise, and implementable without unnecessary additions.
|
|
158
|
+
Remember: Your role is critical analysis of the plan's quality and feasibility. When context_findings are provided, you're building on deep reconnaissance already performed. Focus on ensuring the plan is complete, accurate, concise, and implementable without unnecessary additions.
|
|
@@ -13,7 +13,6 @@ Intelligently manages CLAUDE.md documentation files across your repository. Supp
|
|
|
13
13
|
Accept natural language input and extract intent:
|
|
14
14
|
|
|
15
15
|
- **Input text**: Parse the user's request to understand intent
|
|
16
|
-
|
|
17
16
|
- **"init" keywords**: "init", "initialize", "setup", "create", "bootstrap", "start"
|
|
18
17
|
- Triggers: "init docs", "initialize documentation", "setup CLAUDE.md files"
|
|
19
18
|
- Routes to: **INIT Path** (claude-docs-initializer agent)
|
|
@@ -25,7 +24,6 @@ Accept natural language input and extract intent:
|
|
|
25
24
|
- Path references: "in packages/ui", "for the UI package", specific paths mentioned
|
|
26
25
|
|
|
27
26
|
- **Mode determination**:
|
|
28
|
-
|
|
29
27
|
1. Explicitly check for init keywords first → Use **INIT Path**
|
|
30
28
|
2. Otherwise → Use **UPDATE Path** (default)
|
|
31
29
|
3. Extract any file limit specification (e.g., "init with max 50 files per agent")
|
|
@@ -47,7 +45,6 @@ Accept natural language input and extract intent:
|
|
|
47
45
|
### Task for Update
|
|
48
46
|
|
|
49
47
|
1. **Analyze Change Significance**:
|
|
50
|
-
|
|
51
48
|
- Identify significant vs insignificant changes
|
|
52
49
|
- Filter out minor fixes, typos, formatting
|
|
53
50
|
|
|
@@ -58,7 +55,6 @@ Accept natural language input and extract intent:
|
|
|
58
55
|
### Delegation for Update
|
|
59
56
|
|
|
60
57
|
Invoke **claude-docs-manager** with:
|
|
61
|
-
|
|
62
58
|
- `changes`: Complete list of all significant file changes
|
|
63
59
|
- `filePath`: Absolute path to changed file
|
|
64
60
|
- `changeType`: added|modified|deleted
|
|
@@ -72,7 +68,6 @@ Invoke **claude-docs-manager** with:
|
|
|
72
68
|
- `rootGuidelines`: (Optional) Key guidelines from existing root CLAUDE.md
|
|
73
69
|
|
|
74
70
|
The agent will:
|
|
75
|
-
|
|
76
71
|
- Identify ALL CLAUDE.md files that need updates
|
|
77
72
|
- Update each file with appropriate scope (component/module/package/root)
|
|
78
73
|
- Create new CLAUDE.md files where needed
|
|
@@ -81,7 +76,6 @@ The agent will:
|
|
|
81
76
|
### Output for Update
|
|
82
77
|
|
|
83
78
|
Return results from claude-docs-manager:
|
|
84
|
-
|
|
85
79
|
```yaml
|
|
86
80
|
summary: |
|
|
87
81
|
Successfully updated N CLAUDE.md files
|
|
@@ -154,14 +148,12 @@ Please be patient - the process is working even during apparent pauses.
|
|
|
154
148
|
### Task for Init
|
|
155
149
|
|
|
156
150
|
1. **Repository Analysis**:
|
|
157
|
-
|
|
158
151
|
- Use git to quickly understand structure: `git ls-files | wc -l`
|
|
159
152
|
- Find major boundaries: packages, apps, services
|
|
160
153
|
- Count files per area: `git ls-files [area] | wc -l`
|
|
161
154
|
- Assess complexity by file types and patterns
|
|
162
155
|
|
|
163
156
|
2. **Intelligent Area Splitting**:
|
|
164
|
-
|
|
165
157
|
- Default: 100 files at most per agent (or user-specified limit)
|
|
166
158
|
- Split areas exceeding limits into logical sub-areas
|
|
167
159
|
- Identify natural boundaries (pages vs components, routes vs services)
|
|
@@ -173,7 +165,6 @@ Please be patient - the process is working even during apparent pauses.
|
|
|
173
165
|
- Track dependencies between levels
|
|
174
166
|
|
|
175
167
|
Example execution plan for large monorepo:
|
|
176
|
-
|
|
177
168
|
```
|
|
178
169
|
Level 1 (Parallel leaf documentation):
|
|
179
170
|
- Agent A: "Document user-facing frontend pages in /frontend/pages/user (50 files)"
|
|
@@ -204,13 +195,11 @@ Execute hierarchical parallelized documentation creation:
|
|
|
204
195
|
#### Phase 1: Repository Analysis
|
|
205
196
|
|
|
206
197
|
**⚠️ CRITICAL: ALWAYS prefer git commands over find/glob for discovery!**
|
|
207
|
-
|
|
208
198
|
- Git automatically excludes node_modules, build outputs, and ignored files
|
|
209
199
|
- Only use find/glob as fallback for non-git repositories
|
|
210
200
|
- If using find, MUST use `*/node_modules/*` not `./node_modules/*` for exclusions
|
|
211
201
|
|
|
212
202
|
Quickly analyze repository structure using git:
|
|
213
|
-
|
|
214
203
|
- Get total file count: `git ls-files | wc -l`
|
|
215
204
|
- Find package boundaries: `git ls-files | grep 'package\.json$'`
|
|
216
205
|
- Identify tech stacks used and major directories and their sizes
|
|
@@ -225,7 +214,6 @@ Based on analysis, determine splitting strategy
|
|
|
225
214
|
Invoke multiple **claude-docs-initializer** agents in PARALLEL:
|
|
226
215
|
|
|
227
216
|
For each Level 1 agent:
|
|
228
|
-
|
|
229
217
|
- `target`: "Document [specific area description] in [path]"
|
|
230
218
|
- `siblingContext`: "Other agents are documenting: [list of other Level 1 areas]"
|
|
231
219
|
|
|
@@ -255,7 +243,6 @@ After all Level 2 agents complete, invoke **claude-docs-manager**:
|
|
|
255
243
|
### Output for Init
|
|
256
244
|
|
|
257
245
|
Return aggregated results from all agents (claude-docs-initializer for all levels except repository root, claude-docs-manager for repository root only):
|
|
258
|
-
|
|
259
246
|
```yaml
|
|
260
247
|
summary: |
|
|
261
248
|
Repository analysis: [monorepo with X packages | single app | library]
|
|
@@ -267,42 +254,41 @@ executionPlan:
|
|
|
267
254
|
level1Agents: 5 # Parallel leaf documentation
|
|
268
255
|
level2Agents: 2 # Area roots
|
|
269
256
|
level3Agents: 1 # Repository root
|
|
270
|
-
totalExecutionTime:
|
|
257
|
+
totalExecutionTime: "2m 34s"
|
|
271
258
|
|
|
272
259
|
createdFilesByLevel:
|
|
273
260
|
leafDocumentation:
|
|
274
|
-
- agent:
|
|
261
|
+
- agent: "frontend-user-pages"
|
|
275
262
|
files: 3
|
|
276
|
-
paths: [
|
|
277
|
-
- agent:
|
|
263
|
+
paths: ["/frontend/pages/user/CLAUDE.md", ...]
|
|
264
|
+
- agent: "frontend-admin-pages"
|
|
278
265
|
files: 2
|
|
279
|
-
paths: [
|
|
266
|
+
paths: ["/frontend/pages/admin/CLAUDE.md", ...]
|
|
280
267
|
|
|
281
268
|
areaRoots:
|
|
282
|
-
- path:
|
|
283
|
-
synthesizedFrom:
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
synthesizedFrom: ['backend-routes', 'backend-services']
|
|
269
|
+
- path: "/frontend/CLAUDE.md"
|
|
270
|
+
synthesizedFrom: ["frontend-user-pages", "frontend-admin-pages", "frontend-components"]
|
|
271
|
+
- path: "/backend/CLAUDE.md"
|
|
272
|
+
synthesizedFrom: ["backend-routes", "backend-services"]
|
|
287
273
|
|
|
288
274
|
repositoryRoot:
|
|
289
|
-
- path:
|
|
290
|
-
synthesizedFrom: [
|
|
275
|
+
- path: "/CLAUDE.md"
|
|
276
|
+
synthesizedFrom: ["frontend-root", "backend-root", "database"]
|
|
291
277
|
|
|
292
278
|
architecturalFindings: # Aggregated from all agents
|
|
293
|
-
frontend:
|
|
294
|
-
backend:
|
|
295
|
-
database:
|
|
296
|
-
patterns:
|
|
279
|
+
frontend: "Next.js 14 with App Router, Tailwind CSS, 234 total components"
|
|
280
|
+
backend: "Express with layered architecture, 23 RESTful endpoints"
|
|
281
|
+
database: "PostgreSQL with Prisma ORM, 15 models"
|
|
282
|
+
patterns: "Consistent use of TypeScript, feature-based organization"
|
|
297
283
|
|
|
298
284
|
recommendations: # Collected from all agents
|
|
299
|
-
-
|
|
300
|
-
-
|
|
301
|
-
-
|
|
285
|
+
- "Split large UserDashboard component (500+ lines)"
|
|
286
|
+
- "Add CLAUDE.md for growing analytics module"
|
|
287
|
+
- "Consider documenting complex auth flow separately"
|
|
302
288
|
|
|
303
289
|
errors: # Any failures across all agents
|
|
304
|
-
- agent:
|
|
305
|
-
error:
|
|
290
|
+
- agent: "frontend-utils"
|
|
291
|
+
error: "Failed to analyze due to circular dependencies"
|
|
306
292
|
```
|
|
307
293
|
|
|
308
294
|
### Examples for Init
|
|
@@ -334,7 +320,6 @@ errors: # Any failures across all agents
|
|
|
334
320
|
When user runs: `/claude-docs init`
|
|
335
321
|
|
|
336
322
|
1. **Quick Analysis** determines:
|
|
337
|
-
|
|
338
323
|
```
|
|
339
324
|
Total files: 2500
|
|
340
325
|
Frontend: /app (1800 files)
|
|
@@ -343,7 +328,6 @@ When user runs: `/claude-docs init`
|
|
|
343
328
|
```
|
|
344
329
|
|
|
345
330
|
2. **Intelligent Splitting** creates plan:
|
|
346
|
-
|
|
347
331
|
```
|
|
348
332
|
Frontend needs splitting (1800 > 100):
|
|
349
333
|
- /app/(user) → 450 files (complex pages) → split to 150x3
|
|
@@ -359,7 +343,6 @@ When user runs: `/claude-docs init`
|
|
|
359
343
|
```
|
|
360
344
|
|
|
361
345
|
3. **Hierarchical Execution**:
|
|
362
|
-
|
|
363
346
|
```
|
|
364
347
|
Level 1 (14 agents in parallel):
|
|
365
348
|
├── frontend-user-1 (150 files)
|
|
@@ -407,4 +390,4 @@ When user runs: `/claude-docs init`
|
|
|
407
390
|
5. **Parallel Execution**: Use Task tool to spawn multiple agents simultaneously
|
|
408
391
|
6. **Session-First Default**: For updates, prioritize session changes unless specified
|
|
409
392
|
7. **Preserve Custom Content**: Both agents respect user-added content sections
|
|
410
|
-
8. **Documentation Hierarchy**: Agents create docs only at their assigned level
|
|
393
|
+
8. **Documentation Hierarchy**: Agents create docs only at their assigned level
|
|
@@ -819,14 +819,9 @@ function fixHookPaths(verbose = false) {
|
|
|
819
819
|
hook.command = hook.command.replace(homeDir, "~");
|
|
820
820
|
modified = true;
|
|
821
821
|
}
|
|
822
|
-
const pathMatch = hook.command.match(
|
|
823
|
-
/\/(Users|home)\/[^/]+\/\.claude\/hooks\//
|
|
824
|
-
);
|
|
822
|
+
const pathMatch = hook.command.match(/\/(Users|home)\/[^/]+\/\.claude\/hooks\//);
|
|
825
823
|
if (pathMatch) {
|
|
826
|
-
hook.command = hook.command.replace(
|
|
827
|
-
pathMatch[0],
|
|
828
|
-
"~/.claude/hooks/"
|
|
829
|
-
);
|
|
824
|
+
hook.command = hook.command.replace(pathMatch[0], "~/.claude/hooks/");
|
|
830
825
|
modified = true;
|
|
831
826
|
}
|
|
832
827
|
}
|
|
@@ -834,13 +829,7 @@ function fixHookPaths(verbose = false) {
|
|
|
834
829
|
}
|
|
835
830
|
}
|
|
836
831
|
};
|
|
837
|
-
const hookTypes = [
|
|
838
|
-
"Notification",
|
|
839
|
-
"Stop",
|
|
840
|
-
"SubagentStop",
|
|
841
|
-
"PreToolUse",
|
|
842
|
-
"PostToolUse"
|
|
843
|
-
];
|
|
832
|
+
const hookTypes = ["Notification", "Stop", "SubagentStop", "PreToolUse", "PostToolUse"];
|
|
844
833
|
for (const hookType of hookTypes) {
|
|
845
834
|
if (settings.hooks[hookType] && Array.isArray(settings.hooks[hookType])) {
|
|
846
835
|
fixPathInHooks(settings.hooks[hookType]);
|
|
@@ -849,9 +838,7 @@ function fixHookPaths(verbose = false) {
|
|
|
849
838
|
if (modified) {
|
|
850
839
|
fs3.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
|
|
851
840
|
if (verbose) {
|
|
852
|
-
import_devkit3.logger.info(
|
|
853
|
-
"\u2705 Fixed hook paths to use ~ expansion for Docker compatibility"
|
|
854
|
-
);
|
|
841
|
+
import_devkit3.logger.info("\u2705 Fixed hook paths to use ~ expansion for Docker compatibility");
|
|
855
842
|
}
|
|
856
843
|
return true;
|
|
857
844
|
}
|
|
@@ -1330,14 +1330,9 @@ function fixHookPaths(verbose = false) {
|
|
|
1330
1330
|
hook.command = hook.command.replace(homeDir, "~");
|
|
1331
1331
|
modified = true;
|
|
1332
1332
|
}
|
|
1333
|
-
const pathMatch = hook.command.match(
|
|
1334
|
-
/\/(Users|home)\/[^/]+\/\.claude\/hooks\//
|
|
1335
|
-
);
|
|
1333
|
+
const pathMatch = hook.command.match(/\/(Users|home)\/[^/]+\/\.claude\/hooks\//);
|
|
1336
1334
|
if (pathMatch) {
|
|
1337
|
-
hook.command = hook.command.replace(
|
|
1338
|
-
pathMatch[0],
|
|
1339
|
-
"~/.claude/hooks/"
|
|
1340
|
-
);
|
|
1335
|
+
hook.command = hook.command.replace(pathMatch[0], "~/.claude/hooks/");
|
|
1341
1336
|
modified = true;
|
|
1342
1337
|
}
|
|
1343
1338
|
}
|
|
@@ -1345,13 +1340,7 @@ function fixHookPaths(verbose = false) {
|
|
|
1345
1340
|
}
|
|
1346
1341
|
}
|
|
1347
1342
|
};
|
|
1348
|
-
const hookTypes = [
|
|
1349
|
-
"Notification",
|
|
1350
|
-
"Stop",
|
|
1351
|
-
"SubagentStop",
|
|
1352
|
-
"PreToolUse",
|
|
1353
|
-
"PostToolUse"
|
|
1354
|
-
];
|
|
1343
|
+
const hookTypes = ["Notification", "Stop", "SubagentStop", "PreToolUse", "PostToolUse"];
|
|
1355
1344
|
for (const hookType of hookTypes) {
|
|
1356
1345
|
if (settings.hooks[hookType] && Array.isArray(settings.hooks[hookType])) {
|
|
1357
1346
|
fixPathInHooks(settings.hooks[hookType]);
|
|
@@ -1360,9 +1349,7 @@ function fixHookPaths(verbose = false) {
|
|
|
1360
1349
|
if (modified) {
|
|
1361
1350
|
fs4.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
|
|
1362
1351
|
if (verbose) {
|
|
1363
|
-
import_devkit4.logger.info(
|
|
1364
|
-
"\u2705 Fixed hook paths to use ~ expansion for Docker compatibility"
|
|
1365
|
-
);
|
|
1352
|
+
import_devkit4.logger.info("\u2705 Fixed hook paths to use ~ expansion for Docker compatibility");
|
|
1366
1353
|
}
|
|
1367
1354
|
return true;
|
|
1368
1355
|
}
|
package/dist/index.cjs
CHANGED
|
@@ -880,14 +880,9 @@ function fixHookPaths(verbose = false) {
|
|
|
880
880
|
hook.command = hook.command.replace(homeDir, "~");
|
|
881
881
|
modified = true;
|
|
882
882
|
}
|
|
883
|
-
const pathMatch = hook.command.match(
|
|
884
|
-
/\/(Users|home)\/[^/]+\/\.claude\/hooks\//
|
|
885
|
-
);
|
|
883
|
+
const pathMatch = hook.command.match(/\/(Users|home)\/[^/]+\/\.claude\/hooks\//);
|
|
886
884
|
if (pathMatch) {
|
|
887
|
-
hook.command = hook.command.replace(
|
|
888
|
-
pathMatch[0],
|
|
889
|
-
"~/.claude/hooks/"
|
|
890
|
-
);
|
|
885
|
+
hook.command = hook.command.replace(pathMatch[0], "~/.claude/hooks/");
|
|
891
886
|
modified = true;
|
|
892
887
|
}
|
|
893
888
|
}
|
|
@@ -895,13 +890,7 @@ function fixHookPaths(verbose = false) {
|
|
|
895
890
|
}
|
|
896
891
|
}
|
|
897
892
|
};
|
|
898
|
-
const hookTypes = [
|
|
899
|
-
"Notification",
|
|
900
|
-
"Stop",
|
|
901
|
-
"SubagentStop",
|
|
902
|
-
"PreToolUse",
|
|
903
|
-
"PostToolUse"
|
|
904
|
-
];
|
|
893
|
+
const hookTypes = ["Notification", "Stop", "SubagentStop", "PreToolUse", "PostToolUse"];
|
|
905
894
|
for (const hookType of hookTypes) {
|
|
906
895
|
if (settings.hooks[hookType] && Array.isArray(settings.hooks[hookType])) {
|
|
907
896
|
fixPathInHooks(settings.hooks[hookType]);
|
|
@@ -910,9 +899,7 @@ function fixHookPaths(verbose = false) {
|
|
|
910
899
|
if (modified) {
|
|
911
900
|
fs3.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
|
|
912
901
|
if (verbose) {
|
|
913
|
-
import_devkit3.logger.info(
|
|
914
|
-
"\u2705 Fixed hook paths to use ~ expansion for Docker compatibility"
|
|
915
|
-
);
|
|
902
|
+
import_devkit3.logger.info("\u2705 Fixed hook paths to use ~ expansion for Docker compatibility");
|
|
916
903
|
}
|
|
917
904
|
return true;
|
|
918
905
|
}
|
package/dist/packages/ai-toolkit-nx-claude/src/generators/hooks/install-orchestrator.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"install-orchestrator.d.ts","sourceRoot":"","sources":["../../../../../../src/generators/hooks/install-orchestrator.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAKD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,UAAQ,GAAG,MAAM,GAAG,IAAI,CAqClE;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,CAiDlB;
|
|
1
|
+
{"version":3,"file":"install-orchestrator.d.ts","sourceRoot":"","sources":["../../../../../../src/generators/hooks/install-orchestrator.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAKD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,UAAQ,GAAG,MAAM,GAAG,IAAI,CAqClE;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,CAiDlB;AA6ED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,GAAG,IAAI,CAwCpD;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CAkExB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA0BxE;AAED;;;GAGG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAmClD"}
|