From e12394fc07fd3994b2d6a95df8f83d4578b8e130 Mon Sep 17 00:00:00 2001
From: Yoann Moinet <yoann.moinet@datadoghq.com>
Date: Thu, 3 Jul 2025 15:22:40 +0200
Subject: [PATCH 1/6] Sort commands by priority for yarn format

---
 CLAUDE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index aa50a24b..019f755c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -14,9 +14,9 @@ yarn dev                   # Link packages with web-ui and watch for changes
 yarn build:all             # Build all plugins (for each bundler)
 
 # Code quality (run before committing)
+yarn format                # ESLint checking with fixes
 yarn lint                  # ESLint checking
 yarn typecheck:all         # TypeScript checking across workspaces
-yarn format                # ESLint checking with fixes
 
 # Testing
 yarn test:e2e              # Run E2E tests across bundlers

From 710c45781df26e5ac6fa8d591e6a48821f1ad54d Mon Sep 17 00:00:00 2001
From: Yoann Moinet <yoann.moinet@datadoghq.com>
Date: Thu, 3 Jul 2025 15:25:20 +0200
Subject: [PATCH 2/6] Update claude commands

---
 .claude/commands/create-cli-command.md | 155 ++++++++++++++++++++
 .claude/commands/create-command.md     | 170 ----------------------
 .claude/commands/fix.md                | 125 ----------------
 .claude/commands/reflection.md         | 159 --------------------
 .claude/commands/verify-docs.md        | 191 ++++++++-----------------
 5 files changed, 218 insertions(+), 582 deletions(-)
 create mode 100644 .claude/commands/create-cli-command.md
 delete mode 100644 .claude/commands/create-command.md
 delete mode 100644 .claude/commands/fix.md
 delete mode 100644 .claude/commands/reflection.md

diff --git a/.claude/commands/create-cli-command.md b/.claude/commands/create-cli-command.md
new file mode 100644
index 00000000..cb749ac7
--- /dev/null
+++ b/.claude/commands/create-cli-command.md
@@ -0,0 +1,155 @@
+You are an expert in creating CLI commands for the Datadog Build Plugins project.
+Your task is to create a new CLI command in `packages/tools/src/commands/` following the project's established patterns and conventions.
+
+If you're unsure about the purpose of the command, ask for clarifications.
+
+## Overview
+
+The project uses [Clipanion framework](https://mael.dev/clipanion/docs/) for CLI commands.
+Each command should be self-contained in its own directory under `packages/tools/src/commands/` with proper TypeScript implementation.
+
+## Step-by-Step Implementation
+
+### 1. Create Command Directory Structure
+
+First, create the directory structure for your new command:
+
+```bash
+mkdir -p packages/tools/src/commands/<command-name>
+```
+
+The command name should be kebab-case (e.g., `verify-links`, `create-plugin`, `check-deps`).
+
+### 2. Create the Command Implementation
+
+Create `packages/tools/src/commands/<command-name>/index.ts` with this template:
+
+```typescript
+import { Command, Option } from 'clipanion';
+import path from 'path';
+import fs from 'fs';
+
+import { ROOT } from '@dd/core/constants';
+
+class YourCommandName extends Command {
+    static paths = [['<command-name>']];
+
+    static usage = Command.Usage({
+        category: 'The category of the command',
+        description: 'Brief description of what this command does in one sentence',
+        details: `
+            Detailed description of the command's purpose and behavior.
+        `,
+        examples: [
+            ['Basic usage', 'yarn cli <command-name>'],
+            ['With options', 'yarn cli <command-name> --fix'],
+        ],
+    });
+
+    // Define command options using Clipanion helpers
+    fix = Option.Boolean('--fix', false, {
+        description: 'Automatically fix issues when possible',
+    });
+
+    async execute() {
+        // Implementation of the command's logic.
+        // For the dependencies, import the non native ones in the function that needs it:
+        const { green } = await import('@dd/tools/helpers');
+        console.log(`Executing ${green('<command-name>')} command...`);
+    }
+}
+
+export default [YourCommandName];
+```
+
+### 3. Common Patterns to Follow
+
+#### Dependencies
+
+Only import native modules at the top of the file.
+
+For non-native dependencies, import them inside the method that needs it.
+This helps reduce the initial load time and avoids unnecessary imports when the command is not executed.
+
+```typescript
+const { green } = await import('@dd/tools/helpers');
+console.log(`Executing ${green('<command-name>')} command...`);
+```
+
+#### Error Handling
+
+Prefer gathering errors and reporting them at the end of the command execution to avoid breaking the flow.
+
+If the command is grouping multiple workflows or operations, collect errors in a consistent format and throw one at the end listing everything.
+
+```typescript
+const errors: string[] = [];
+
+// Collect errors in a non blocking/breaking way, with consistent formatting
+errors.push(`[${red('Error|Category')}] ${file}:${line} - ${dim(message)}`);
+
+// Report all errors at the end of the execution
+if (errors.length > 0) {
+    throw new Error(`Found ${errors.length} error${errors.length > 1 ? 's' : ''}`);
+}
+```
+
+#### Progress Indicators
+```typescript
+console.log(`  Processing ${green(files.length.toString())} files...`);
+
+// For long operations
+for (const [index, file] of files.entries()) {
+    console.log(`    [${index + 1}/${files.length}] ${dim(file)}...`);
+    // Process file
+}
+```
+
+### 4. Testing Your Command
+
+Test your command locally:
+
+```bash
+# Run your command
+yarn cli <command-name>
+yarn cli <command-name> --help
+yarn cli <command-name> --fix
+```
+
+### 5. Code Quality Checks
+
+Before finalizing:
+
+```bash
+# Format your code
+yarn format packages/tools/src/commands/<command-name>
+
+# Check types
+yarn typecheck:all
+```
+
+### 6. Documentation
+
+Update the main documentation:
+
+1. Add command to README.md if it's user-facing
+2. Update CONTRIBUTING.md if it's a development tool
+3. Add inline comments for complex logic
+
+## Example Commands for Reference
+
+Look at these existing commands for patterns:
+- `integrity/index.ts` - Complex multi-phase command
+- `create-plugin/index.ts` - Interactive command with prompts
+- `bump/index.ts` - Command with external tool integration
+
+## Best Practices
+
+1. **Keep it focused**: Each command should do one thing well
+2. **Use existing utilities**: Leverage `@dd/core` helpers
+3. **Consistent output**: Use colors consistently (green for success, red for errors, yellow for warnings) available in `@dd/tools/helpers`
+4. **Graceful errors**: Always catch and report errors clearly
+5. **Progress feedback**: Show users what's happening during long operations
+6. **Exit codes**: Return 0 for success, 1 for errors
+
+Remember: CLI commands are the primary interface for developers. Make them intuitive, fast, and reliable.
diff --git a/.claude/commands/create-command.md b/.claude/commands/create-command.md
deleted file mode 100644
index 3d422cc0..00000000
--- a/.claude/commands/create-command.md
+++ /dev/null
@@ -1,170 +0,0 @@
-You are an expert in designing efficient command-line interfaces and AI assistant workflows. Your task is to create a new Claude Code command that follows established patterns and maximizes usability and effectiveness.
-
-The command is defined by "#$ARGUMENTS".
-
-Follow this structured approach:
-
-## 1. Requirements Analysis Phase
-
-First, understand what the new command needs to accomplish:
-
-**Define Purpose:**
-- Clearly articulate the primary goal of the command
-- Identify the specific problem or workflow it will solve
-- Determine the target user and use case scenarios
-- Establish success criteria for the command
-
-**Analyze Context:**
-- Review existing commands in `.claude/commands/` for patterns and consistency
-- Identify any overlapping functionality with existing commands
-- Understand how this command fits into the broader workflow
-- Consider integration points with other tools and commands
-
-**Gather Requirements:**
-- List all functional requirements (what the command must do)
-- Identify non-functional requirements (performance, usability, etc.)
-- Determine input parameters or arguments needed
-- Specify expected outputs and deliverables
-
-## 2. Design Phase
-
-Create a structured approach that follows established patterns:
-
-**Command Structure Design:**
-- Use the proven 4-6 phase structure (Analysis → Investigation → Implementation → Validation)
-- Include clear sub-sections with bold headers for each phase
-- Design logical flow between phases
-- Plan for collaborative interaction points with the user
-
-**Content Framework:**
-- Start with a clear expert persona statement
-- Include a "Follow this structured approach:" introduction
-- Design numbered phases with descriptive names
-- Add Key Principles section for core guidelines
-- Include Quality Checks or Validation section
-- End with summary statement reinforcing the goal
-
-**Tool Integration:**
-- Identify which Claude Code tools will be needed (Read, Write, Edit, Bash, Glob, Grep, Task, etc.)
-- Plan tool usage patterns for maximum efficiency
-- Consider error handling and edge cases
-- Design for both simple and complex scenarios
-
-## 3. Implementation Phase
-
-Write the command following established patterns:
-
-**File Structure:**
-- Create the file as `./.claude/commands/{command-name}.md`
-- Use kebab-case for command names (e.g., `create-command.md`, `debug-performance.md`)
-- Follow consistent markdown formatting and structure
-
-**Content Implementation:**
-- Write clear, actionable instructions
-- Use consistent terminology and phrasing
-- Include specific examples where helpful
-- Provide detailed sub-tasks for each phase
-- Add context-specific guidance relevant to this codebase
-
-**Format Consistency:**
-- Use `## N. Phase Name` for main phases
-- Use `**Bold Headers:**` for sub-sections
-- Include bullet points for actionable items
-- Add code blocks or examples where appropriate
-- Maintain consistent tone and style with existing commands
-
-## 4. Validation Phase
-
-Ensure the command meets quality standards:
-
-**Review Against Patterns:**
-- Compare structure with existing commands like `fix.md` and `reflection.md`
-- Verify consistent formatting and organization
-- Check for appropriate level of detail and specificity
-- Ensure logical flow and clear progression
-
-**Usability Testing:**
-- Walk through the command mentally to identify gaps
-- Verify all necessary information is included
-- Check that instructions are clear and unambiguous
-- Ensure the command can handle both simple and complex scenarios
-
-**Quality Checks:**
-- Verify markdown syntax is correct
-- Check for typos and grammatical errors
-- Ensure all tool references are accurate
-- Confirm the command serves its intended purpose effectively
-
-## Command Template
-
-Use this template as a starting point:
-
-```markdown
-You are an expert in [DOMAIN], specializing in [SPECIFIC_EXPERTISE]. Your task is to [PRIMARY_GOAL] for [TARGET_CONTEXT].
-
-Follow this structured approach:
-
-## 1. [Analysis/Discovery] Phase
-
-[Clear description of first phase purpose]
-
-**[Sub-section 1]:**
-- [Actionable items]
-- [Specific guidance]
-
-**[Sub-section 2]:**
-- [More actionable items]
-- [Tool usage patterns]
-
-## 2. [Planning/Investigation] Phase
-
-[Description of second phase]
-
-**[Sub-section]:**
-- [Detailed steps]
-
-## 3. [Implementation/Execution] Phase
-
-[Description of main work phase]
-
-**[Sub-section]:**
-- [Implementation guidance]
-
-## 4. [Validation/Review] Phase
-
-[Description of validation phase]
-
-**[Sub-section]:**
-- [Quality checks]
-
-## Key Principles
-
-- **[Principle 1]**: [Description]
-- **[Principle 2]**: [Description]
-- **[Principle 3]**: [Description]
-
-## Quality Checks
-
-[Final validation steps]
-
-[Closing statement reinforcing the goal]
-```
-
-## Key Principles
-
-- **Follow Established Patterns**: Use the same structure and formatting as existing commands
-- **Be Specific and Actionable**: Every instruction should be clear and executable
-- **Design for Efficiency**: Optimize for Claude Code's capabilities and tools
-- **Enable Collaboration**: Include natural interaction points with users
-- **Maintain Consistency**: Ensure the command fits seamlessly with existing workflows
-
-## Quality Checks
-
-Before finalizing the new command:
-- Verify it follows the established 4-6 phase structure
-- Check formatting consistency with `fix.md` and `reflection.md`
-- Ensure all necessary tools and workflows are covered
-- Confirm the command is appropriately scoped and focused
-- Test that instructions are clear and unambiguous
-
-Remember: A well-designed command should feel natural to execute, provide clear guidance at each step, and integrate smoothly with existing Claude Code workflows and tools.
diff --git a/.claude/commands/fix.md b/.claude/commands/fix.md
deleted file mode 100644
index 016c4026..00000000
--- a/.claude/commands/fix.md
+++ /dev/null
@@ -1,125 +0,0 @@
-You are an expert software engineer specializing in debugging and fixing complex issues in codebases. Your task is to systematically investigate and fix bugs reported in GitHub issues or identified in the codebase.
-If you're given an argument #$ARGUMENTS, it should be the number identifying the GitHub issue located at https://github.com/DataDog/build-plugins/issues/$ARGUMENTS.
-
-Follow this structured approach:
-
-## 1. Issue Analysis Phase
-
-First, thoroughly understand the problem:
-
-**Gather Information:**
-- Read the GitHub issue or bug report completely
-- Extract the problem description, expected behavior, and actual behavior
-- Note the environment details (OS, Node version, bundler version, etc.)
-- Identify any code examples, error messages, or reproduction steps provided
-
-**Analyze the Problem Domain:**
-- Understand which part of the codebase the issue likely affects
-- Identify the specific plugin or module that could be responsible
-- Consider edge cases and potential root causes
-
-## 2. Investigation Phase
-
-Use a systematic approach to locate the bug:
-
-**Search Strategy:**
-- Use the `Task` tool for broad searches when looking for keywords, functionality, or concepts
-- Use `Glob` tool for finding files by specific patterns or names
-- Use `Grep` tool for searching specific code patterns within files
-- Examine related files and dependencies
-
-**Code Analysis:**
-- Read the relevant source files to understand the current implementation
-- Trace the code flow to identify where the bug might occur
-- Look for patterns like:
-  - String manipulation that could fail with edge cases
-  - Path handling that might not work across different scenarios and/or platforms
-  - Logic that assumes certain conditions but doesn't handle exceptions
-
-## 3. Test Creation Phase
-
-Before fixing, create a test that reproduces the issue:
-
-**Write Failing Tests:**
-- Create a test case that demonstrates the bug
-- Use realistic data that matches the reported issue
-- Ensure the test fails with the current implementation
-- Write the test to be generic and cover multiple scenarios, not just the specific bug
-
-**Test Guidelines:**
-- Follow the existing test patterns in the codebase
-- Use descriptive test names that explain the expected behavior
-- Include multiple test cases to cover edge cases
-- Make tests maintainable and easy to understand
-
-## 4. Fix Implementation Phase
-
-Implement the fix with careful consideration:
-
-**Root Cause Analysis:**
-- Identify the exact line(s) of code causing the issue
-- Understand why the current implementation fails
-- Consider the original intent of the code
-
-**Solution Design:**
-- Choose the most robust solution that handles edge cases while remaining as simple as possible
-- Avoid over-engineering; focus on the specific problem at hand
-- Prefer using well-tested utilities (like Node.js `path` module) over custom string manipulation
-- Consider cross-platform compatibility
-- Think about performance implications
-
-**Code Implementation:**
-- Add comments on changed/added lines explaining the fix and why it's necessary in the context of the codebase
-- Document edge cases the fix handles
-- Provide examples in comments when helpful
-- Ensure the fix follows the existing code style and patterns
-
-## 5. Validation Phase
-
-Verify the fix works correctly:
-
-**Test Execution:**
-- Run the specific test you created to ensure it now passes
-- Run the entire test suite for the affected module to ensure no regressions
-- Run broader tests across all bundlers with `yarn test:unit`
-- Verify TypeScript compilation succeeds with `yarn typecheck:all`
-
-**Quality Checks:**
-- Verify integrity of the codebase with `yarn cli integrity`
-- Ensure code follows project conventions
-- Check that all tests pass
-- Verify that the documentation remains accurate and up-to-date
-- Alert the human if there are any breaking changes, and document them clearly
-
-## 6. Documentation and Comments
-
-**In-Code Documentation:**
-- Add comments explaining the fix, especially complex logic
-- Document edge cases and why specific approaches were chosen
-- Reference the GitHub issue number if applicable
-
-**Test Documentation:**
-- Write clear test descriptions that explain what behavior is being tested
-- Avoid tying tests directly to specific bug numbers
-- Make tests generic enough to catch similar issues in the future
-
-## Example Workflow
-
-Here's how this approach worked for a real fix:
-
-1. **Issue**: [Sourcemap paths included incorrect filesystem paths](https://github.com/DataDog/build-plugins/issues/179)
-2. **Investigation**: Found the bug in `decomposePath`function using string replacement in `./packages/plugins/error-tracking/src/sourcemaps/files.ts`
-3. **Root Cause**: `String.replace()` was replacing first occurrence anywhere in string, not necessarily at the start
-4. **Test**: Created failing test with multiple directory structure scenarios
-5. **Fix**: Replaced `string.replace()` with `path.relative()` for proper path calculation
-6. **Validation**: All tests passed, including existing ones
-
-## Key Principles
-
-- **Be Systematic**: Follow the phases methodically
-- **Test First**: Always reproduce the bug in a test before fixing
-- **Think Generically**: Fix the class of problems, not just the specific instance
-- **Document Thoroughly**: Explain why the fix works and what edge cases it handles
-- **Validate Completely**: Ensure no regressions and all quality checks pass
-
-Remember: A good fix not only solves the immediate problem but also prevents similar issues in the future and makes the codebase more robust.
diff --git a/.claude/commands/reflection.md b/.claude/commands/reflection.md
deleted file mode 100644
index 3af73c7a..00000000
--- a/.claude/commands/reflection.md
+++ /dev/null
@@ -1,159 +0,0 @@
-You are an expert in prompt engineering, specializing in optimizing AI code assistant instructions. Your task is to analyze and improve both the instructions for Claude Code found in ./CLAUDE.md and the project commands found in ./.claude/commands/ based on recent chat history and performance observations.
-
-Follow this structured approach:
-
-## 1. Analysis Phase
-
-Begin by thoroughly reviewing the current state and identifying improvement opportunities:
-
-**Review Current Instructions:**
-- Read the current Claude instructions in ./CLAUDE.md completely
-- Understand the existing guidance, rules, and behavioral expectations
-- Note the structure and organization of the current instructions
-
-**Review Project Commands:**
-- Examine all command files in ./.claude/commands/ directory
-- Understand the purpose and structure of each command
-- Identify how commands were used during the chat history
-- Note any gaps between command definitions and actual usage patterns
-
-**Analyze Chat History:**
-- Review the conversation history in your context window
-- Look for patterns in user requests and Claude's responses
-- Identify any confusion, misunderstandings, or suboptimal responses
-- Track which commands were invoked and how effectively they were executed
-- Note any corrections or refinements the human provided during command execution
-
-**Identify Improvement Areas:**
-
-*For CLAUDE.md:*
-- Inconsistencies in Claude's responses to similar requests
-- Misunderstandings of user intent or project context
-- Areas where Claude could provide more detailed or accurate information
-- Missing guidance for common tasks or scenarios
-- Opportunities to enhance Claude's ability to handle specific types of queries
-- Places where instructions could be clearer or more specific
-
-*For Project Commands:*
-- Commands that were used differently than their definitions suggested
-- Missing commands for workflows that appeared frequently in chat history
-- Command definitions that were unclear or led to suboptimal execution
-- Opportunities to create new commands based on successful ad-hoc workflows
-- Command improvements based on human corrections or refinements during execution
-
-## 2. Interaction Phase
-
-Present your findings collaboratively with the human:
-
-**Present Findings:**
-For each improvement opportunity identified:
-- Clearly categorize whether it's a CLAUDE.md improvement or command improvement
-- Explain the current issue or gap you've identified
-- Provide specific examples from the chat history if applicable
-- Propose a specific change or addition to the instructions/commands
-- Describe how this change would improve Claude's performance or workflow efficiency
-
-**Critical Evaluation:**
-Before finalizing any suggestions, apply critical thinking:
-- Question whether the proposed improvement addresses a real need or creates unnecessary complexity
-- Consider if existing commands or instructions already cover the functionality
-- Evaluate if the change would duplicate existing workflows or create confusion
-- Ask: "Would this actually be used in practice, or is it theoretical over-engineering?"
-- Challenge assumptions about what needs to be systematized vs. handled ad-hoc
-- **Verify against source of truth**: Check if documented information duplicates what's already in configuration files, package.json, or other authoritative sources
-- **Prefer references over duplication**: Link to configuration files instead of copying their content to avoid maintenance burden and inconsistencies
-
-**Collaborative Review:**
-- Present both CLAUDE.md and command improvements together for holistic evaluation
-- Wait for feedback from the human on each suggestion before proceeding
-- If the human questions or challenges a suggestion, treat it as valuable feedback for refinement
-- Be prepared to abandon suggestions that don't provide clear value
-- If not approved, refine your suggestion or move on to the next idea
-- Engage in discussion to ensure the proposed changes align with project needs and actual usage patterns
-- Document the reasoning behind both accepted and rejected suggestions for future reference
-- **Meta-improvement**: If the reflection process itself reveals gaps or improvements (e.g., missing evaluation criteria, unclear steps), immediately update this reflection.md command to incorporate those learnings
-- Ask: "What did this reflection process teach us about how to do better reflections in the future?"
-
-## 3. Implementation Phase
-
-For each approved change, implement it systematically:
-
-**Document CLAUDE.md Changes:**
-- Clearly state which section of ./CLAUDE.md you're modifying
-- Present the new or modified text for that section
-- Explain how this change addresses the issue identified in the analysis phase
-- Ensure the new instructions are clear, actionable, and consistent with existing guidance
-
-**Document Command Changes:**
-- For new commands: Use the create-command methodology to build them properly
-- For existing command updates: Clearly state which command file is being modified
-- Present the new or modified command text
-- Explain how the changes reflect actual usage patterns observed in chat history
-- Ensure commands follow established patterns and formatting
-
-**Maintain Consistency:**
-- Ensure new instructions don't conflict with existing ones in CLAUDE.md
-- Ensure command updates follow the established command structure and style
-- Keep the same tone and style throughout both instruction sets and commands
-- Verify that changes enhance rather than complicate the overall workflow
-
-## 4. Output Format
-
-Present your final deliverable in this structured format:
-
-**Analysis Summary:**
-```
-<analysis>
-[List the issues identified and potential improvements with specific examples]
-</analysis>
-```
-
-**Approved Improvements:**
-```
-<improvements>
-[For each approved improvement, categorized as either CLAUDE.md or Commands:
-
-CLAUDE.md Improvements:
-1. Section being modified (e.g., "## Code Standards" or "# Architecture")
-2. New or modified instruction text
-3. Explanation of how this addresses the identified issue
-
-Command Improvements:
-1. Command file being modified or created (e.g., "fix.md" or "new-debug.md")
-2. New or modified command content
-3. Explanation of how this reflects actual usage patterns and improves workflow]
-</improvements>
-```
-
-**Final Deliverables:**
-```
-<final_instructions>
-[Present the complete, updated ./CLAUDE.md content, incorporating all approved changes]
-</final_instructions>
-
-<updated_commands>
-[Present any new or modified command files with their complete content]
-</updated_commands>
-```
-
-## Key Principles
-
-- **Be Evidence-Based**: Ground suggestions in actual observations from the chat history and command usage patterns
-- **Maintain Core Functionality**: Enhance existing capabilities without breaking fundamental behaviors
-- **Focus on Clarity**: Make both instructions and commands more precise and actionable
-- **Consider Context**: Ensure improvements are relevant to the specific codebase and team workflow
-- **Preserve Intent**: Maintain the original purpose and goals of both the AI assistant and command system
-- **Reflect Real Usage**: Commands should match how they were actually used, not just theoretical definitions
-- **Enable Iteration**: Both instructions and commands should support continuous improvement based on feedback
-
-## Quality Checks
-
-Before finalizing:
-- Verify all changes are internally consistent between CLAUDE.md and commands
-- Ensure instructions remain comprehensive but not overly complex
-- Check that new guidance and commands are actionable and measurable
-- Confirm the updated instructions maintain the project's coding standards and practices
-- Validate that command improvements reflect successful patterns from chat history
-- Ensure new or modified commands follow established formatting and structure patterns
-
-Remember: Your goal is to enhance Claude's performance and consistency while maintaining the core functionality and purpose of the AI assistant. Commands should evolve based on real usage patterns, and instructions should support the most effective workflows observed in practice.
diff --git a/.claude/commands/verify-docs.md b/.claude/commands/verify-docs.md
index 4279a832..f3263d24 100644
--- a/.claude/commands/verify-docs.md
+++ b/.claude/commands/verify-docs.md
@@ -1,128 +1,63 @@
-You are an expert in technical documentation management and quality assurance. Your task is to verify the consistency of all documentation in the project, ensuring it remains current, accurate, and properly cross-referenced.
-
-Follow this structured approach:
-
-## 1. Discovery Phase
-
-First, identify and catalog all documentation in the project:
-
-**Find Documentation Files:**
-- Use Glob to find all markdown files: `**/*.md`
-- Identify README files in all package directories
-- Locate any other documentation formats (txt, rst, etc.)
-- Catalog configuration files that contain documentation (package.json descriptions, etc.)
-- Locate inline comments in code files that could serve as documentation
-- Be sure to "read" the whole file, not just the first few lines
-
-**Categorize Documentation:**
-- Project-level documentation (README.md, CONTRIBUTING.md, CLAUDE.md)
-- Package-specific documentation (individual README files)
-- Command documentation (.claude/commands/*.md)
-- Migration and changelog documentation (MIGRATIONS.md, CHANGELOG.md if present)
-- Code comments and inline documentation
-
-## 2. Cross-Reference Validation Phase
-
-Verify all internal references and links are accurate:
-
-**Check Internal Links:**
-- Scan for relative path references between documentation files
-- Verify file paths mentioned in documentation actually exist
-- Check that directory structures referenced are current
-- Validate any anchors or section links within documents
-
-**Verify Command References:**
-- Check that all yarn/npm commands mentioned in docs are valid
-- Test references to CLI commands (e.g., `yarn cli integrity`)
-- Verify script names in package.json match documentation
-- Confirm workspace commands are accurately documented
-
-**Validate File Structure References:**
-- Check that directory paths mentioned in docs exist
-- Verify example file paths are accurate
-- Ensure workspace structure descriptions match reality
-- Confirm package names and locations are current
-
-## 3. Content Verification Phase
-
-Validate that documented procedures and examples work correctly:
-
-**Test Documented Commands:**
-- Run key commands mentioned in documentation to verify they work
-- Check that example commands produce expected results
-- Verify installation and setup procedures are current
-- Test development workflow commands (build, test, lint, etc.)
-
-**Verify Code Examples:**
-- Check that code snippets in documentation are syntactically correct
-- Ensure examples reflect current API and usage patterns
-- Verify configuration examples match current schema
-- Test that import statements and package references are accurate
-
-**Validate Procedures:**
-- Walk through setup instructions to ensure they're complete
-- Check that troubleshooting sections address current issues
-- Verify that development workflows are accurately described
-- Ensure contribution guidelines match current practices
-
-## 4. Currency Check Phase
-
-Ensure information reflects the current state of the project:
-
-**Version and Dependency Checks:**
-- Compare documented versions with current package.json versions
-- Check that Node.js version requirements are current
-- Verify bundler version references are up-to-date
-- Ensure dependency examples reflect current packages
-
-**Feature Currency:**
-- Verify that documented features still exist and work as described
-- Check for new features that should be documented
-- Identify deprecated features that should be removed from docs
-- Ensure plugin configurations reflect current options
-
-**Workflow Accuracy:**
-- Confirm that development setup procedures are current
-- Verify testing procedures match current test infrastructure
-- Check that build and deployment procedures are accurate
-- Ensure contribution workflow matches current practices
-
-## 5. Reporting Phase
-
-Provide clear, actionable feedback on documentation status:
-
-**Generate Findings Report:**
-- List all inconsistencies found with specific file locations
-- Prioritize issues by severity (broken links, incorrect procedures, minor outdated info)
-- Provide specific recommendations for each issue
-- Suggest improvements for documentation organization or clarity
-
-**Recommend Actions:**
-- Identify which files need immediate updates
-- Suggest additions for missing documentation
-- Recommend consolidation where documentation is redundant
-- Propose automation opportunities for keeping docs current
-
-**Integration with Existing Tools:**
-- Run `yarn cli integrity` to check automated documentation verification
-- Compare findings with existing validation tools
-- Recommend integration points with CI/CD for ongoing validation
-
-## Key Principles
-
-- **Be Thorough**: Check both obvious and subtle inconsistencies
-- **Test Practically**: Actually run commands and procedures to verify they work
-- **Think Like a New User**: Consider whether documentation would help someone unfamiliar with the project
-- **Prioritize Impact**: Focus on issues that would cause real problems for users
-- **Suggest Solutions**: Don't just identify problems, propose specific fixes
-
-## Quality Checks
-
-Before finalizing the verification:
-- Ensure all major documentation files have been reviewed
-- Verify that critical user workflows have been tested
-- Check that findings are specific and actionable
-- Confirm recommendations are practical and implementable
-- Validate that the verification itself was comprehensive
-
-Remember: Good documentation is a living part of the codebase that should evolve with the project. Your verification should not only catch current issues but also suggest ways to keep documentation accurate going forward.
+You are an expert in technical documentation management and quality assurance. Your task is to efficiently verify the consistency of documentation in the project.
+
+## Execution Strategy
+
+### Phase 1: Parallel Discovery & Initial Checks
+
+Run these operations concurrently using multiple agents:
+
+**Agent 1 - Documentation Discovery:**
+
+- Find all *.md files using `find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/.yarn/*" -not -path "*/dist/*" -not -path "*/.claude/*" -not -path "*/.github/*"`
+- Group by type: project-level, package-specific, commands
+
+**Agent 2 - Overall Verification:**
+
+- Run `yarn cli integrity` for an overall check (more details in `CONTRIBUTING.md#integrity`)
+- Parse output for broken links and other errors
+- Note which files have issues
+
+**Agent 3 - Critical File Check:**
+
+- Verify at the root the existence and accuracy of: README.md, CONTRIBUTING.md, LICENSE.md
+- In `./packages/published`, check for essential `package.json` fields: `name`, `version`, `description`, `keywords`, `homepage`, `repository`
+
+### Phase 2: Comprehensive Validation
+
+Using the list of markdown files found earlier.
+
+**Command Verification:**
+- Check configuration examples against types and implementations
+- Validate CLI commands documentation against actual implementation
+
+**Content Analysis:**
+- Check for outdated feature documentation
+- Validate workflow descriptions
+- Verify code snippets examples against types and implementations
+
+### Phase 3: Intelligent Reporting
+
+**Error Prioritization:**
+1. **Critical**: Broken links, missing files, invalid commands
+3. **Minor**: Formatting issues, style inconsistencies
+
+**Fix Suggestions:**
+- For broken links found by the integrity command, update the targets
+- For missing READMEs: Provide a template following the project's style and suggest the content to add to it
+
+## Integration Points
+
+1. **Leverage existing tools:**
+   - Use `yarn cli integrity` for an overall check (more details in `CONTRIBUTING.md#integrity`), it includes:
+     - `yarn install` for lock files update
+     - `yarn oss` for Open Source compliance
+     - `yarn typecheck:all` for type validation
+     - `yarn format` for linting, formatting and automatic fixes
+   - Use git for change detection
+   - Use `yarn build:all` to ensure all packages are not broken
+
+2. **Avoid duplication:**
+   - Don't re-implement things that exist already in the repository
+   - Focus on documentation-specific issues
+
+Remember: Speed comes from doing less work, not doing work faster. Focus on high-value validations and leverage existing tools wherever possible.

From cb338bd29bedd062081aee8a03ecead7d6b76ba1 Mon Sep 17 00:00:00 2001
From: Yoann Moinet <yoann.moinet@datadoghq.com>
Date: Thu, 3 Jul 2025 15:28:47 +0200
Subject: [PATCH 3/6] Small accuracy updates on integrity command

---
 README.md                                       |  7 ++++++-
 packages/tools/src/commands/integrity/index.ts  |  2 +-
 packages/tools/src/commands/integrity/readme.ts | 15 ++++++++++-----
 3 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 0b265b12..0cdfd30a 100644
--- a/README.md
+++ b/README.md
@@ -88,9 +88,14 @@ Follow the specific documentation for each bundler:
 {
     auth?: {
         apiKey?: string;
+        appKey?: string;
     };
     customPlugins?: (arg: GetPluginsArg) => UnpluginPlugin[];
-    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none';
+    disableGit?: boolean;
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none',
+    metadata?: {
+        name?: string;
+    };;
     errorTracking?: {
         disabled?: boolean;
         sourcemaps?: {
diff --git a/packages/tools/src/commands/integrity/index.ts b/packages/tools/src/commands/integrity/index.ts
index aedba064..1761bf2c 100644
--- a/packages/tools/src/commands/integrity/index.ts
+++ b/packages/tools/src/commands/integrity/index.ts
@@ -2,7 +2,6 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2019-Present Datadog, Inc.
 
-import { getWorkspaces } from '@dd/tools/helpers';
 import { Command, Option } from 'clipanion';
 
 class Integrity extends Command {
@@ -27,6 +26,7 @@ class Integrity extends Command {
         const { updateDependencies } = await import('./dependencies');
         const { updateFiles } = await import('./files');
         const { updateReadmes, injectTocsInAllReadmes } = await import('./readme');
+        const { getWorkspaces } = await import('@dd/tools/helpers');
 
         const workspaces = await getWorkspaces();
 
diff --git a/packages/tools/src/commands/integrity/readme.ts b/packages/tools/src/commands/integrity/readme.ts
index 06b62116..95c8b6e9 100644
--- a/packages/tools/src/commands/integrity/readme.ts
+++ b/packages/tools/src/commands/integrity/readme.ts
@@ -218,7 +218,7 @@ const getBundlerTemplate = (bundler: Workspace, bundlerMeta: BundlerMetadata) =>
     return outdent`- [${getBundlerPicture(name)} ${title} \`${bundler.name}\`](/${bundler.location}#readme)`;
 };
 
-const handleBundler = (bundler: Workspace, index: number) => {
+const handleBundler = (bundler: Workspace) => {
     const readmePath = `${bundler.location}/README.md`;
     const errors = [];
 
@@ -272,7 +272,7 @@ export const injectTocsInAllReadmes = () => {
 
         const readmeToc = getReadmeToc(readmeContent);
 
-        console.log(`  Inject ${green('TOC')} in ${green(readmePath)}.`);
+        console.log(`  Inject ${green('TOC')} in ${green(path.relative(ROOT, readmePath))}.`);
         fs.writeFileSync(readmePath, replaceInBetween(readmeContent, MD_TOC_KEY, readmeToc));
     }
 };
@@ -358,9 +358,14 @@ export const updateReadmes = async (plugins: Workspace[], bundlers: Workspace[])
             {
                 auth?: {
                     apiKey?: string;
+                    appKey?: string;
                 };
                 customPlugins?: (arg: GetPluginsArg) => UnpluginPlugin[];
-                logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none'
+                disableGit?: boolean;
+                logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none',
+                metadata?: {
+                    name?: string;
+                };
         `,
     ];
     const errors: string[] = [];
@@ -383,8 +388,8 @@ export const updateReadmes = async (plugins: Workspace[], bundlers: Workspace[])
         errors.push(...pluginErrors);
     }
 
-    for (const [i, bundler] of bundlers.entries()) {
-        const { list, errors: bundlerErrors } = handleBundler(bundler, i);
+    for (const bundler of bundlers) {
+        const { list, errors: bundlerErrors } = handleBundler(bundler);
         bundlersContents.push(list);
         errors.push(...bundlerErrors);
     }

From b342d33e9adaa4ac86610c6714f33b94c4cd0715 Mon Sep 17 00:00:00 2001
From: Yoann Moinet <yoann.moinet@datadoghq.com>
Date: Thu, 3 Jul 2025 15:29:09 +0200
Subject: [PATCH 4/6] Add link verification to integrity command

---
 CONTRIBUTING.md                               |  1 +
 .../tools/src/commands/integrity/index.ts     |  4 +-
 .../tools/src/commands/integrity/readme.ts    | 97 +++++++++++++++++++
 3 files changed, 101 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f160c23c..d8eceb20 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -212,6 +212,7 @@ It will:
     - generate and update the Table of Contents delimited by `<!-- #toc -->`.
     - update the [root README](/#readme) with the list of plugins and their configuration.
     - update the [Custom Hooks' README](/packages/plugins/custom-hooks/#existing-hooks) with the list of hooks from the other plugins.
+    - verify that all internal links are valid.
 - update the necessary `.ts` and `package.json` files.
     - with the aggregated types from the plugins.
     - with the aggregated helpers from the plugins.
diff --git a/packages/tools/src/commands/integrity/index.ts b/packages/tools/src/commands/integrity/index.ts
index 1761bf2c..69e0083e 100644
--- a/packages/tools/src/commands/integrity/index.ts
+++ b/packages/tools/src/commands/integrity/index.ts
@@ -25,7 +25,7 @@ class Integrity extends Command {
         const { runAutoFixes } = await import('@dd/tools/helpers');
         const { updateDependencies } = await import('./dependencies');
         const { updateFiles } = await import('./files');
-        const { updateReadmes, injectTocsInAllReadmes } = await import('./readme');
+        const { updateReadmes, injectTocsInAllReadmes, verifyLinks } = await import('./readme');
         const { getWorkspaces } = await import('@dd/tools/helpers');
 
         const workspaces = await getWorkspaces();
@@ -47,6 +47,8 @@ class Integrity extends Command {
         errors.push(...(await updateReadmes(plugins, bundlers)));
         // Inject TOC into all of the readmes.
         injectTocsInAllReadmes();
+        // Verify markdown links.
+        errors.push(...(await verifyLinks()));
         // Update the files that need to be updated.
         errors.push(...(await updateFiles(plugins)));
         // Run auto-fixes to ensure the code is correct.
diff --git a/packages/tools/src/commands/integrity/readme.ts b/packages/tools/src/commands/integrity/readme.ts
index 95c8b6e9..4ef770f8 100644
--- a/packages/tools/src/commands/integrity/readme.ts
+++ b/packages/tools/src/commands/integrity/readme.ts
@@ -57,6 +57,8 @@ const README_EXCEPTIONS = [
 const error = red('Error|README');
 // Matches image tags individually with surrounding whitespaces.
 const IMG_RX = /[\s]*<img.+?(?=\/>)\/>[\s]*/g;
+// Matches markdown links individually and catch targets.
+const MARKDOWN_LINK_RX = /\[[^\]]+\]\(([^)]+)\)/g;
 
 const verifyReadmeExists = (pluginPath: string) => {
     const readmePath = path.resolve(ROOT, pluginPath, 'README.md');
@@ -436,3 +438,98 @@ export const updateReadmes = async (plugins: Workspace[], bundlers: Workspace[])
 
     return errors;
 };
+
+const isInternalLinkValid = (target: string, currentFilepath: string, rootDir: string): boolean => {
+    // We don't validate external links
+    if (/^https?:\/\//.test(target)) {
+        return true;
+    }
+
+    // Split path and anchor
+    const [targetPath, anchor] = target.includes('#') ? target.split('#') : [target, null];
+
+    // If the target starts with "/", we resolve it against the root directory.
+    // If it starts with "#", we assume it's an anchor in the current file.
+    // Otherwise, we resolve it against the directory of the current file.
+    let resolvedPath = targetPath.startsWith('/')
+        ? // Using path.join to avoid using targetPath as the root.
+          path.join(rootDir, targetPath)
+        : // If the target is an anchor, we remain in the same file.
+          target.startsWith('#')
+          ? currentFilepath
+          : path.resolve(path.dirname(currentFilepath), targetPath);
+
+    // If we target an anchor and the target is a directory, we assume there's a README.md file.
+    if (anchor && fs.statSync(resolvedPath).isDirectory()) {
+        resolvedPath = path.join(resolvedPath, 'README.md');
+    }
+
+    // Check if the file exists
+    if (!fs.existsSync(resolvedPath)) {
+        return false;
+    }
+
+    // If there's an anchor, verify it exists in the target file
+    if (anchor) {
+        // Get the linked file's content.
+        const linkedFileContent = fs.readFileSync(resolvedPath, 'utf-8');
+        // List all its slugs.
+        const slugs =
+            linkedFileContent
+                // Remove code blocks to avoid non-header # usage.
+                .replace(/```[\s\S]*?```/gm, '')
+                // Match headings (starting with #).
+                .match(/^#+ .+$/gm)
+                // Convert everything to clean slugs.
+                ?.map((heading) =>
+                    slugify(heading.replace(/^#+ */, '').trim().replace(IMG_RX, '-').toLowerCase()),
+                ) || [];
+
+        // Include 'readme' and 'top' as a valid anchor for the top of the file.
+        slugs.push('readme', 'top');
+
+        return slugs.includes(anchor.toLowerCase());
+    }
+
+    return true;
+};
+
+export const verifyLinks = async (): Promise<string[]> => {
+    const errors: string[] = [];
+
+    // Get all markdown files
+    const files = glob.sync('**/*.md', {
+        ignore: ['**/node_modules/**', '.yarn/**'],
+        absolute: true,
+        cwd: ROOT,
+    });
+
+    console.log(
+        `  Verifying ${green('markdown links')} in ${green(files.length.toString())} file${files.length <= 1 ? '' : 's'}.`,
+    );
+
+    for (const file of files) {
+        const content = fs.readFileSync(file, 'utf-8');
+        const lines = content.split('\n');
+
+        for (let lineNum = 0; lineNum < lines.length; lineNum++) {
+            const line = lines[lineNum];
+            // Reset regex
+            MARKDOWN_LINK_RX.lastIndex = 0;
+            let match = MARKDOWN_LINK_RX.exec(line);
+            while (match !== null) {
+                const target = match[1].trim();
+                // Skip external links (http/https)
+                if (!isInternalLinkValid(target, file, ROOT)) {
+                    // Report broken links
+                    errors.push(
+                        `[${error}] ${path.relative(ROOT, file)}:${lineNum + 1} - Broken link: ${dim(target)}`,
+                    );
+                }
+                match = MARKDOWN_LINK_RX.exec(line);
+            }
+        }
+    }
+
+    return errors;
+};

From 2cb40ad892b5862b8b5af1af189f50dd817b122c Mon Sep 17 00:00:00 2001
From: Yoann Moinet <yoann.moinet@datadoghq.com>
Date: Thu, 3 Jul 2025 15:29:33 +0200
Subject: [PATCH 5/6] Update broken links

---
 packages/plugins/git/README.md | 2 +-
 packages/tests/README.md       | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/plugins/git/README.md b/packages/plugins/git/README.md
index bd3531f1..5cab5639 100644
--- a/packages/plugins/git/README.md
+++ b/packages/plugins/git/README.md
@@ -8,7 +8,7 @@ Adds repository data to the global context from the `buildStart` hook.
     git?: {
         hash: string;
         remote: string;
-        trackedFilesMatcher: [TrackedFilesMatcher](/packages/plugins/git/trackedFilesMatcher.ts) {
+        trackedFilesMatcher: [TrackedFilesMatcher](/packages/plugins/git/src/trackedFilesMatcher.ts) {
             matchSourcemap: (path: string, onSourceFound: (): void): string[];
             matchSources: (sources: string[]): string[];
             rawTrackedFilesList: (): string[];
diff --git a/packages/tests/README.md b/packages/tests/README.md
index b0126da3..0235a6a6 100644
--- a/packages/tests/README.md
+++ b/packages/tests/README.md
@@ -110,7 +110,7 @@ yarn test:unit packages/... --build=1 --bundlers=webpack4,esbuild
 
 #### More complex projects
 
-We also have [a more complex project](/packages/tests/src/_jest/fixtures/project), with third parties dependencies for instance, that you can use with the `getComplexBuildOverrides()` function.<br/>
+We also have [a more complex project](/packages/tests/src/_jest/fixtures/hard_project), with third parties dependencies for instance, that you can use with the `getComplexBuildOverrides()` function.<br/>
 To be used as follow:
 
 ```typescript

From e22a593ca446de67ca43f8af40ae3208f343a785 Mon Sep 17 00:00:00 2001
From: Yoann Moinet <yoann.moinet@datadoghq.com>
Date: Thu, 3 Jul 2025 15:30:03 +0200
Subject: [PATCH 6/6] Allow some bash commands

---
 .claude/settings.local.json | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 .claude/settings.local.json

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
new file mode 100644
index 00000000..087734d5
--- /dev/null
+++ b/.claude/settings.local.json
@@ -0,0 +1,6 @@
+{
+    "permissions": {
+        "allow": ["Bash(yarn cli:*)", "Bash(find:*)", "Bash(ls:*)"],
+        "deny": []
+    }
+}