### README File Structure Example

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/doc-writer/agent.md

Provides a standard Markdown structure for a project's README file, including sections for features, prerequisites, installation, usage, API reference, contribution, and license. Includes embedded code examples.

```markdown
# Project Name

Brief, compelling description of what the project does.

## 🚀 Features

- Key feature 1
- Key feature 2
- Key feature 3

## 📋 Prerequisites

- Required software/tools
- System requirements
- Dependencies

## 🔧 Installation

```bash
# Step-by-step installation commands
npm install package-name
```

## 💻 Usage

### Basic Example
```javascript
// Simple example showing primary use case
const example = require('package-name');
example.doSomething();
```

### Advanced Usage
```javascript
// More complex examples
```

## 📖 API Reference

### `functionName(param1, param2)`

Description of what the function does.

**Parameters:**
- `param1` (Type): Description
- `param2` (Type): Description

**Returns:** Type - Description

**Example:**
```javascript
const result = functionName('value1', 'value2');
```

## 🤝 Contributing

Guidelines for contributors.

## 📄 License

This project is licensed under the [LICENSE NAME] License.

```

--------------------------------

### Install Claude Sub-Agents CLI

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Provides instructions for installing the Claude Sub-Agents command-line interface using different package managers or from source. This is the primary method to get the tool set up.

```bash
npm install -g @webdevtoday/claude-agents
```

```bash
yarn global add @webdevtoday/claude-agents
```

```bash
git clone https://github.com/webdevtodayjason/sub-agents.git
cd sub-agents
npm install
npm link
```

--------------------------------

### Configuration Documentation: Environment Variables and Files

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/doc-writer/agent.md

Details project configuration, including a table of environment variables with their descriptions, default values, and required status. Also provides an example of a JSON configuration file for database settings.

```markdown
## Configuration

### Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `NODE_ENV` | Application environment | `development` | No |
| `PORT` | Server port | `3000` | No |
| `DATABASE_URL` | PostgreSQL connection string | - | Yes |
| `JWT_SECRET` | Secret key for JWT signing | - | Yes |
| `REDIS_URL` | Redis connection for caching | - | No |

### Configuration Files

#### `config/database.json`
```json
{
  "development": {
    "dialect": "postgres",
    "logging": true,
    "pool": {
      "max": 5,
      "min": 0,
      "acquire": 30000,
      "idle": 10000
    }
  }
}
```

```

--------------------------------

### Claude Sub-Agents CLI Quick Start Commands

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Demonstrates essential commands for interacting with the Claude Sub-Agents CLI. This includes listing available agents, installing agents interactively or in bulk, and using agents via slash commands within Claude Code.

```bash
# See what's available
claude-agents list

# Install your first agent interactively
claude-agents install

# Or install all agents at once
claude-agents install --all

# Use an agent via slash command
# In Claude Code:
> /review
> /test
> /debug TypeError in production
```

--------------------------------

### OpenAPI/Swagger API Specification

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/doc-writer/agent.md

Illustrates the structure of an OpenAPI (Swagger) specification in YAML format for documenting REST APIs. It includes basic information like title and version, and defines an example endpoint for listing users.

```yaml
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: Successful response
```

--------------------------------

### TypeScript Class Documentation (JSDoc)

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/doc-writer/agent.md

Illustrates JSDoc usage for documenting TypeScript classes, including class descriptions, implementation details, constructor parameters, and usage examples. This format is crucial for generating comprehensive API references.

```typescript
/**
 * Represents a user in the system with authentication and profile management
 * 
 * @class User
 * @implements {IAuthenticatable}
 * 
 * @example
 * const user = new User('john@example.com', 'John Doe');
 * await user.authenticate('password123');
 */
class User {
  /**
   * Creates a new User instance
   * @param {string} email - User's email address
   * @param {string} name - User's full name
   * @throws {ValidationError} If email format is invalid
   */
  constructor(email, name) {
    // ...
  }
}
```

--------------------------------

### JavaScript Function Documentation (JSDoc)

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/doc-writer/agent.md

Demonstrates the JSDoc format for documenting JavaScript functions, including parameter types, descriptions, return values, exceptions, and usage examples. This format aids in generating API documentation.

```javascript
/**
 * Calculates the compound interest for a given principal amount
 * 
 * @param {number} principal - The initial amount of money
 * @param {number} rate - The annual interest rate (as a decimal)
 * @param {number} time - The time period in years
 * @param {number} [compound=1] - Number of times interest is compounded per year
 * @returns {number} The final amount after compound interest
 * @throws {Error} If any parameter is negative
 * 
 * @example
 * // Calculate compound interest for $1000 at 5% for 3 years
 * const amount = calculateCompoundInterest(1000, 0.05, 3);
 * console.log(amount); // 1157.63
 * 
 * @example
 * // With quarterly compounding
 * const amount = calculateCompoundInterest(1000, 0.05, 3, 4);
 * console.log(amount); // 1160.75
 */
```

--------------------------------

### Security Scan Report Example

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/security-scanner/agent.md

An example of the structured output format for a security scan report, detailing scan summary, critical, high, medium, and low severity issues with specific examples of fixes.

```text
🔒 SECURITY SCAN REPORT
━━━━━━━━━━━━━━━━━━━━━━

📊 Scan Summary:
- Files Scanned: 47
- Issues Found: 12
- Critical: 2
- High: 3
- Medium: 5
- Low: 2

🔴 CRITICAL ISSUES (2)
━━━━━━━━━━━━━━━━━━━━

1. Exposed API Key
   File: src/config.js:15
   ```javascript
   const API_KEY = "sk-proj-abc123def456";
   ```
   
   Impact: Full API access compromise
   
   Fix:
   ```javascript
   const API_KEY = process.env.API_KEY;
   ```
   Add to .env file and ensure .env is in .gitignore

2. SQL Injection Vulnerability
   File: src/api/users.js:42
   ```javascript
   db.query(`SELECT * FROM users WHERE email = '${email}'`);
   ```
   
   Impact: Database compromise, data theft
   
   Fix:
   ```javascript
   db.query('SELECT * FROM users WHERE email = ?', [email]);
   ```

🟠 HIGH SEVERITY (3)
━━━━━━━━━━━━━━━━━━━

[Additional issues...]

📋 Recommendations:
1. Implement pre-commit hooks for secret scanning
2. Add security linting to CI/CD pipeline
3. Regular dependency updates
4. Security training for developers
```

--------------------------------

### Binary Search Debugging Example

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/debugger/agent.md

A conceptual example of binary search debugging for hard-to-locate issues. This involves systematically commenting out code sections to isolate the problem.

```bash
# For hard-to-locate issues
# Comment out half the code, test, repeat
```

--------------------------------

### Troubleshoot Module Not Found

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/doc-writer/agent.md

Offers solutions for the 'Cannot find module' error in Node.js environments. Steps involve installing dependencies, clearing the node_modules directory, and verifying the module's presence in package.json.

```bash
npm install
rm -rf node_modules && npm install
```

--------------------------------

### Documentation Writer Agent Usage

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Demonstrates how to install and use the Documentation Writer agent for technical writing tasks like API documentation and README generation.

```bash
# Install
claude-agents install doc-writer

# Use
> /document API
> /document architecture
```

--------------------------------

### Agent Installation Scopes

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Explains the two scopes for installing Claude Agents: User Scope for personal agents and Project Scope for project-specific agents, including the use of the `--project` flag.

```markdown
**User Scope** (`~/.claude/agents/`)
- Available in all projects
- Personal agents
- Default installation location

**Project Scope** (`.claude/agents/`)
- Project-specific agents
- Shared with team via version control
- Use `--project` flag
```

--------------------------------

### Architecture Overview and Data Flow

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/doc-writer/agent.md

Documents the architecture of a system, detailing frontend and backend technologies, state management, database choices, authentication methods, and API style. Includes a Mermaid diagram for data flow visualization.

```markdown
# Architecture Overview

## System Components

### Frontend
- **Technology**: React 18 with TypeScript
- **State Management**: Redux Toolkit
- **Styling**: Tailwind CSS
- **Build Tool**: Vite

### Backend
- **Technology**: Node.js with Express
- **Database**: PostgreSQL with Prisma ORM
- **Authentication**: JWT with refresh tokens
- **API Style**: RESTful with OpenAPI documentation

## Data Flow

```mermaid
graph LR
    A[Client] -->|HTTP Request| B[API Gateway]
    B --> C[Auth Service]
    B --> D[Business Logic]
    D --> E[Database]
    E -->|Data| D
    D -->|Response| B
    B -->|JSON| A
```

## Key Design Decisions

1. **Microservices Architecture**: Chose for scalability and independent deployment
2. **PostgreSQL**: Selected for ACID compliance and complex queries
3. **JWT Authentication**: Stateless authentication for horizontal scaling

```

--------------------------------

### JSDoc/TSDoc Inline Documentation

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/doc-writer/agent.md

Demonstrates the use of JSDoc or TSDoc for inline code documentation within JavaScript or TypeScript files. It shows how to document modules with descriptions and metadata.

```javascript
/**
 * @module MyModule
 * @description Core functionality for the application
 */
```

--------------------------------

### Troubleshoot Database Connection

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/doc-writer/agent.md

Provides commands to diagnose and resolve 'Cannot connect to database' errors, typically related to PostgreSQL. It includes checks for service status, connection string format, firewall rules, and database existence.

```bash
pg_isready
postgresql://user:pass@host:port/db
createdb myapp
```

--------------------------------

### Claude Agents CLI Command Reference

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Provides a comprehensive reference for the `claude-agents` command-line interface, detailing installation, agent management, and custom agent creation commands.

```APIDOC
claude-agents CLI Commands:

install
  Description: Install agents interactively.
  Example: `claude-agents install`

install --all
  Description: Install all available agents.
  Example: `claude-agents install --all`

install --project
  Description: Install agents to the current project directory.
  Example: `claude-agents install --project`

list
  Description: Show all available agents.
  Example: `claude-agents list`

list --installed
  Description: Show only the agents that are currently installed.
  Example: `claude-agents list --installed`

enable <agent>
  Description: Enable a disabled agent.
  Parameters:
    - agent: The name of the agent to enable.
  Example: `claude-agents enable code-reviewer`

disable <agent>
  Description: Disable an agent.
  Parameters:
    - agent: The name of the agent to disable.
  Example: `claude-agents disable test-runner`

remove <agent>
  Description: Remove or uninstall an agent.
  Parameters:
    - agent: The name of the agent to remove.
  Example: `claude-agents remove debugger`

info <agent>
  Description: Show detailed information about a specific agent.
  Parameters:
    - agent: The name of the agent to get information for.
  Example: `claude-agents info debugger`

create
  Description: Initiate the interactive process for creating a custom agent.
  Example: `claude-agents create`
```

--------------------------------

### Path Traversal Vulnerability (Python)

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/security-scanner/agent.md

Shows a Python example of a path traversal vulnerability using `os.path.join` with user input and the secure approach by sanitizing the input using `os.path.basename`.

```python
# Vulnerable:
file_path = os.path.join(base_dir, user_input)

# Secure:
file_path = os.path.join(base_dir, os.path.basename(user_input))
```

--------------------------------

### Security Scanner Agent Usage

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Shows how to install and utilize the Security Scanner agent for vulnerability detection, OWASP compliance, and dependency auditing.

```bash
# Install
claude-agents install security-scanner

# Use
> /security-scan
> /security-scan src/api/
```

--------------------------------

### ShadCN UI Builder Agent Usage

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Illustrates the installation and usage of the ShadCN UI Builder agent for modern, accessible, and responsive UI development with ShadCN components.

```bash
# Install
claude-agents install shadcn-ui-builder

# Use
> /ui create a login page
> /shadcn implement dashboard with sidebar
```

--------------------------------

### Advanced Configuration - State Management

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Illustrates the structure of the `.claude-agents.json` file used for managing agent states, including installed agents, their versions, scopes, and enabled/disabled status.

```json
{
  "installedAgents": {
    "code-reviewer": {
      "version": "1.0.0",
      "scope": "user",
      "installedAt": "2024-01-20T10:00:00Z"
    }
  },
  "enabledAgents": ["code-reviewer"],
  "disabledAgents": []
}
```

--------------------------------

### Common Fixes: Mock/Stub Updates

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/test-runner/agent.md

Shows an example of updating mocks in JavaScript (using Jest) to align with new module interfaces or expected behavior.

```javascript
// Update mocks to match new interfaces
jest.mock('./module', () => ({
  method: jest.fn().mockResolvedValue(newResponse)
}));
```

--------------------------------

### Missing Error Handling Example

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/code-reviewer/agent.md

Highlights a warning-level issue where a critical operation (payment processing) lacks proper error handling. The suggestion is to implement a try-catch block to manage potential exceptions gracefully.

```javascript
// The payment processing lacks proper error handling. Wrap in try-catch.
```

--------------------------------

### SQL Injection Vulnerability Example

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/code-reviewer/agent.md

Demonstrates a common security vulnerability (SQL injection) and its remediation using parameterized queries in JavaScript. This highlights the agent's focus on security best practices.

```javascript
db.query(`SELECT * FROM users WHERE id = ${userId}`);
```

```javascript
db.query('SELECT * FROM users WHERE id = ?', [userId]);
```

--------------------------------

### Common Fixes: Assertion Updates

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/test-runner/agent.md

Provides an example of how to update assertions in JavaScript when the expected behavior of the code has legitimately changed.

```javascript
// If behavior changed legitimately:
// OLD: expect(result).toBe(oldValue);
// NEW: expect(result).toBe(newValue); // Updated due to [reason]
```

--------------------------------

### Troubleshooting - Agent Status Checks

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Provides commands to troubleshoot agent issues by checking installation status, verifying agent information, and re-enabling disabled agents.

```bash
# Check installation
claude-agents list

# Verify agent status
claude-agents info <agent-name>

# Re-enable if disabled
claude-agents enable <agent-name>
```

--------------------------------

### Test Runner Agent Usage

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Instructions for installing and utilizing the Test Runner sub-agent. This agent automates test execution, detects frameworks, and can fix failing tests.

```bash
# Install
claude-agents install test-runner

# Use
> /test
> /test src/**/*.test.js
```

--------------------------------

### Debugger Agent Usage

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Guidance on installing and employing the Debugger sub-agent. This agent assists with root cause analysis, stack trace interpretation, and performance profiling.

```bash
# Install
claude-agents install debugger

# Use
> /debug Cannot read property 'map' of undefined
```

--------------------------------

### Exposed API Key Example

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/code-reviewer/agent.md

Illustrates a critical security issue where an API key is hardcoded directly into the source code. The recommended fix involves removing the hardcoded key and utilizing environment variables for sensitive information.

```javascript
// Remove this line and use environment variables:
const API_KEY = 'sk-1234567890abcdef';
```

--------------------------------

### JavaScript Debug Output Code Change Example

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/debugger/agent.md

Illustrates a code modification to handle potential null values in JavaScript, preventing runtime errors. This is part of the debugger's solution implementation phase.

```javascript
// Before:
const results = data.map(item => item.value);

// After:
const results = (data || []).map(item => item.value);
```

--------------------------------

### Execution Workflow: Initial Test Run

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/test-runner/agent.md

Illustrates the initial step of the agent's workflow, focusing on detecting and executing all tests based on the identified framework, with fallback mechanisms.

```bash
# Detect and run all tests
[appropriate test command based on framework]

# If no test command found, check common locations:
# - package.json scripts
# - Makefile targets
# - README instructions
```

--------------------------------

### Output Format: Initial Test Run

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/test-runner/agent.md

Specifies the expected output format after the initial test execution, including framework detection and summary statistics.

```text
🧪 Test Framework Detected: [Framework Name]
📊 Running tests...

Test Results:
✅ Passed: X
❌ Failed: Y
⚠️  Skipped: Z

Total: X+Y+Z tests
```

--------------------------------

### Best Practices: DOs and DON'Ts

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/test-runner/agent.md

Lists recommended practices (DOs) and actions to avoid (DON'Ts) for effective test execution and maintenance.

```general
DO:
- Run tests before making any changes (baseline)
- Fix one test at a time when possible
- Preserve existing test coverage
- Add tests for edge cases discovered during debugging
- Use test isolation to debug specific failures
- Check for flaky tests (intermittent failures)

DON'T:
- Delete failing tests without understanding why
- Change test assertions just to make them pass
- Modify test data unless necessary
- Skip tests without documenting why
- Ignore test warnings
```

--------------------------------

### Code Reviewer Agent Usage

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Details on how to install and use the Code Reviewer sub-agent. This agent specializes in code quality, security, and maintainability analysis.

```bash
# Install
claude-agents install code-reviewer

# Use
> /review
```

--------------------------------

### Adding New Agents - File Structure

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Outlines the recommended directory structure for adding new agents, including agent definition, metadata, and optional hooks files.

```markdown
agents/
└── your-agent/
    ├── agent.md       # Agent definition
    ├── metadata.json  # Agent metadata
    └── hooks.json     # Optional hooks
```

--------------------------------

### Troubleshooting - Debug Mode

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Explains how to run the Claude CLI with debug output enabled to help diagnose issues.

```bash
# Run Claude with debug output
claude --debug
```

--------------------------------

### Test Framework Detection Logic

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/test-runner/agent.md

Details the logic used by the agent to detect the project's testing framework by checking for common configuration files and patterns across various languages.

```general
JavaScript/TypeScript:
- package.json scripts containing "test"
- Jest: jest.config.*, *.test.js, *.spec.js
- Mocha: mocha.opts, test/ directory
- Vitest: vitest.config.*, *.test.ts
- Playwright: playwright.config.*
- Cypress: cypress.json, cypress.config.*

Python:
- Pytest: pytest.ini, conftest.py, test_*.py
- Unittest: test*.py files
- Tox: tox.ini

Go:
- *_test.go files
- go test command

Java:
- Maven: pom.xml → mvn test
- Gradle: build.gradle → gradle test
- JUnit test files

Ruby:
- RSpec: spec/ directory, *_spec.rb
- Minitest: test/ directory

Other:
- Rust: cargo test
- .NET: dotnet test
- PHP: PHPUnit configuration
```

--------------------------------

### Refactor Assistant Agent Usage

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Information on installing and activating the Refactor Assistant sub-agent. This agent focuses on code transformation, applying design patterns, and modernizing legacy code.

```bash
# Install
claude-agents install refactor

# Use
> /refactor [target]
```

--------------------------------

### Execution Workflow: Verification

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/test-runner/agent.md

Details the final step of the workflow, which involves verifying fixes by running specific tests and then the entire suite to catch regressions.

```general
After fixes:
1. Run the specific fixed tests first
2. Run the full test suite to ensure no regressions
3. Check test coverage if tools are available
```

--------------------------------

### Command Injection Vulnerability (Python)

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/security-scanner/agent.md

Presents a Python code snippet illustrating command injection via `os.system` and its secure counterpart using `subprocess.run` with a list of arguments, ensuring proper execution and error checking.

```python
# Vulnerable:
os.system(f"convert {user_file} output.pdf")

# Secure:
subprocess.run(["convert", user_file, "output.pdf"], check=True)
```

--------------------------------

### Dependency Scanning Commands

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/security-scanner/agent.md

Provides commands for auditing and fixing vulnerabilities in project dependencies across different package managers like npm, pip, Go, and Maven.

```bash
### NPM/Node.js
npm audit
npm audit fix

### Python
pip-audit
safety check

### Go
go mod audit
govulncheck ./...

### Java
mvn dependency-check:check
```

--------------------------------

### Git Bisect for Bug Introduction

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/debugger/agent.md

Demonstrates the usage of `git bisect` to efficiently find the commit that introduced a bug. This command-line tool performs a binary search through commit history.

```bash
# Find when bug was introduced
git bisect start
git bisect bad  # Current version is bad
git bisect good <commit>  # Known good commit
# Test each commit git suggests
```

--------------------------------

### Execution Workflow: Failure Analysis

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/test-runner/agent.md

Outlines the process for analyzing individual test failures, including identifying assertions, locating code, and determining root causes.

```general
For each failing test:
1. Identify the specific assertion that failed
2. Locate the code being tested
3. Determine if it's a code issue or test issue
4. Check recent changes that might have caused the failure
```

--------------------------------

### Error Handling: Unfixable Tests

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/test-runner/agent.md

Describes the protocol for handling tests that cannot be immediately fixed, emphasizing documentation and clear communication of the issue.

```general
If tests cannot be fixed:
1. Document why the test is failing
2. Provide clear explanation of what needs to be done
3. Suggest whether to skip temporarily or requires deeper changes
4. Never leave tests in a broken state
```

--------------------------------

### Execution Workflow: Fix Implementation

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/test-runner/agent.md

Describes the principles for implementing fixes to failing tests, emphasizing preserving test intent, addressing root causes, and updating assertions only when behavior changes.

```general
When fixing tests:
- Preserve test intent: Never change what the test is trying to verify
- Fix the root cause: Address the actual issue, not symptoms
- Update assertions: Only if the expected behavior genuinely changed
- Add missing tests: For uncovered edge cases discovered during fixes
```

--------------------------------

### Output Format: After Fixes

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/test-runner/agent.md

Presents the expected output format after successful test fixes, summarizing the changes made and the final test results.

```text
🔧 Fixed Tests:
✅ [Test 1] - [Brief description of fix]
✅ [Test 2] - [Brief description of fix]

📊 Final Test Results:
✅ All tests passing (X tests)
⏱️  Execution time: Xs
```

--------------------------------

### Refactoring Analysis Report

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/refactor/agent.md

A sample report detailing code quality metrics before and after refactoring, listing applied refactoring techniques, modified files, and testing status.

```report
🔧 REFACTORING ANALYSIS
━━━━━━━━━━━━━━━━━━━━━

📊 Code Quality Metrics:
- Cyclomatic Complexity: Before 15 → After 8
- Lines of Code: Before 200 → After 150
- Number of Methods: Before 5 → After 12
- Duplication: Removed 3 instances

🎯 Refactorings Applied:
1. ✅ Extract Method: validateInput() from processData()
2. ✅ Replace Magic Number: MAX_RETRIES = 3
3. ✅ Remove Duplication: Created shared utility function
4. ✅ Simplify Conditional: Used early return pattern

📁 Files Modified:
- src/processor.js (major restructuring)
- src/utils.js (new utility functions)
- src/constants.js (new constants file)

⚠️  Breaking Changes: None
🧪 Tests: All passing (15/15)
```

--------------------------------

### Advanced Configuration - Hook Integration

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Demonstrates how to configure hooks in `claude-agents.json` to trigger agent actions or commands automatically based on specific events or tool use patterns.

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Consider running /review' >&2"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Output Format: Failure Analysis

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/test-runner/agent.md

Defines the output format for detailed failure analysis, providing context like test name, file location, failure reason, and root cause.

```text
❌ Failed Test: [Test Name]
📁 File: [File Path:Line Number]
🔍 Failure Reason: [Specific Error]

Root Cause Analysis:
[Detailed explanation]

Proposed Fix:
[Description of what needs to be changed]
```

--------------------------------

### Custom Agent Creation - Manual Definition

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Details the structure and content required for manually creating a custom agent by defining its metadata and behavior in a markdown file.

```markdown
---
name: my-agent
description: What this agent does and when to use it
tools: Read, Edit, Grep, Bash
---

You are an expert in [DOMAIN]. Your role is to [PURPOSE].

When invoked, you will:
1. [STEP 1]
2. [STEP 2]
3. [STEP 3]

Always ensure [KEY PRINCIPLE].
```

--------------------------------

### Adding New Agents - Slash Command Definition

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/README.md

Shows where to define new slash commands for custom agents within the project structure.

```markdown
commands/
└── your-command.md
```

--------------------------------

### Secret Detection Patterns (Bash)

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/security-scanner/agent.md

Provides regular expression patterns used for detecting exposed secrets and credentials in code. These patterns cover API keys, passwords, tokens, private keys, AWS credentials, and database URLs.

```bash
# Patterns to search for:
- API keys: /api[_-]?key/i
- Passwords: /password\s*[:=]/i
- Tokens: /token\s*[:=]/i
- Private keys: /BEGIN\s+(RSA|DSA|EC|OPENSSH)\s+PRIVATE/
- AWS credentials: /AKIA[0-9A-Z]{16}/
- Database URLs with credentials
```

--------------------------------

### JavaScript/TypeScript Common Error Fixes

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/debugger/agent.md

Provides common error patterns and their solutions for JavaScript and TypeScript. Includes handling undefined properties, promise rejections, module resolution, and type mismatches.

```javascript
// Common issues and solutions:

// TypeError: Cannot read property 'x' of undefined
// Fix: Add null/undefined checks
if (obj && obj.x) { ... }
// Or use optional chaining
obj?.x?.method?.()

// Promise rejection errors
// Fix: Add proper error handling
try {
  await someAsyncOperation();
} catch (error) {
  console.error('Operation failed:', error);
  // Handle appropriately
}

// Module not found
// Fix: Check import paths and package.json
```

```typescript
// TypeScript example
// Error: Type 'string' is not assignable to type 'number'
// Fix: Proper type conversion or type correction
const num: number = parseInt(str, 10);
// Or fix the type annotation
const value: string = str;
```

--------------------------------

### Common Fixes: Async/Timing Issues

Source: https://github.com/webdevtodayjason/sub-agents/blob/main/agents/test-runner/agent.md

Illustrates a common fix for test failures related to asynchronous operations or timing issues, using a wait function.

```javascript
// Add proper waits or async handling
await waitFor(() => expect(element).toBeVisible());
```