code-reviewer

Original source / Raw SKILL.md

---
name: code-reviewer
description: Automatic code quality and best practices analysis. Use proactively when files are modified, saved, or committed. Analyzes code style, patterns, potential bugs, and security basics. Triggers on file changes, git diff, code edits, quality mentions.
allowed-tools: Read, Grep, Glob
---

# Code Reviewer Skill


Lightweight automatic code quality checks while you code.

## When I Activate

- ✅ Files modified or saved
- ✅ Git diff run
- ✅ Code mentioned in conversation
- ✅ User asks about code quality
- ✅ Before commits

## What I Check

### Quick Wins
- Code style and formatting issues
- Common anti-patterns
- Obvious bugs (null checks, undefined references)
- Basic security patterns (hardcoded secrets)
- Import/export issues
- Unused variables and functions

### What I Don't Do
- Deep architectural review → Use **@code-reviewer** sub-agent
- Comprehensive security audit → Use **security-auditor** skill
- Performance profiling → Use **@architect** sub-agent
- Full refactoring plans → Use **@code-reviewer** sub-agent

## Relationship with @code-reviewer Sub-Agent

**Me (Skill):** Fast, lightweight, real-time feedback
**@code-reviewer (Sub-Agent):** Deep analysis with examples and strategy

### Workflow

1. You write code
2. I auto-analyze (instant feedback)
3. I flag: "⚠️ Potential issue on line 42"
4. You want details → Invoke **@code-reviewer** sub-agent
5. Sub-agent provides comprehensive analysis

## Analysis Examples

### JavaScript/TypeScript

```javascript
// You write this code:
function getUser(id) {
  return db.query(`SELECT * FROM users WHERE id = ${id}`);
}

// I immediately flag:
// 🚨 Line 2: SQL injection vulnerability
// 💡 Use parameterized queries
```

### React

```javascript
// You write:
function UserList({ users }) {
  return users.map(user => <User data={user} />);
}

// I flag:
// ⚠️ Missing key prop in list rendering (line 2)
// 💡 Add key={user.id} to User component
```

### Python

```python
# You write:
def process_data(data):
    return data['user']['profile']['name']

# I flag:
# ⚠️ Potential KeyError - no safety checks (line 2)
# 💡 Use .get() or add try/except
```

## Check Categories

### Code Style
- Inconsistent naming conventions
- Missing semicolons (JavaScript)
- Improper indentation
- Long functions (>50 lines)
- Magic numbers

### Potential Bugs
- Null/undefined access without checks
- Array access without bounds checking
- Type mismatches (TypeScript)
- Unreachable code
- Infinite loops

### Basic Security
- Hardcoded API keys or secrets
- SQL injection patterns
- eval() or exec() usage
- Insecure random number generation
- Missing input validation

### Best Practices
- Missing error handling
- Console.log in production code
- Commented-out code blocks
- TODO comments without context
- Overly complex conditions

## Output Format

```
🤖 code-reviewer skill:
  [Severity] Issue description (file:line)
  💡 Quick fix suggestion
  📖 Reference: [link to learn more]
```

### Severity Levels
- 🚨 **CRITICAL**: Must fix (security, data loss)
- ⚠️ **HIGH**: Should fix (bugs, performance)
- 📋 **MEDIUM**: Consider fixing (maintainability)
- 💡 **LOW**: Nice to have (style, readability)

## When to Invoke Sub-Agent

After I flag issues, invoke **@code-reviewer** sub-agent for:
- Detailed explanation of the issue
- Multiple fix alternatives with pros/cons
- Architectural recommendations
- Refactoring strategies
- Best practice guidelines

**Example:**
```
Me: "⚠️ Potential N+1 query detected"
You: "@code-reviewer explain the N+1 issue and show optimal solution"
Sub-agent: [Provides comprehensive analysis with examples]
```

## Sandboxing Compatibility

**Works without sandboxing:** ✅ Yes (default, recommended for learning)
**Works with sandboxing:** ✅ Yes (no special configuration needed)

- **Filesystem**: Read-only access to project files
- **Network**: None required
- **Configuration**: None required

## Customization

Want different checks or patterns?

1. Copy this skill:
   ```bash
   cp -r ~/.claude/skills/development/code-reviewer ~/.claude/skills/development/my-code-reviewer
   ```

2. Edit `SKILL.md`:
   - Modify `description` to adjust triggers
   - Customize check categories
   - Add language-specific patterns

3. Restart Claude Code:
   ```bash
   claude --restart
   ```

See [../../TEMPLATES.md](../../TEMPLATES.md) for customization guide.

## Examples in Action

### TypeScript Function

```typescript
// Before:
async function fetchUsers(ids) {
  const users = [];
  for (let id of ids) {
    const user = await User.findById(id);  // N+1 query!
    users.push(user);
  }
  return users;
}

// I flag:
// ⚠️ N+1 query pattern detected (line 4)
// 💡 Use User.findByIds(ids) for batch loading

// After fix:
async function fetchUsers(ids) {
  return await User.findByIds(ids);
}
```

### React Component

```jsx
// Before:
function UserCard({ user }) {
  const [data, setData] = useState();

  useEffect(() => {
    fetch(`/api/users/${user.id}`)
      .then(res => res.json())
      .then(setData);
  }, []);  // Missing dependency!

  return <div>{data?.name}</div>;
}

// I flag:
// ⚠️ useEffect dependency array incomplete (line 6)
// 💡 Add user.id to dependencies: [user.id]

// After fix:
useEffect(() => {
  fetch(`/api/users/${user.id}`)
    .then(res => res.json())
    .then(setData);
}, [user.id]);
```

## Integration with /review Command

The `/review` command aggregates my findings with deep sub-agent analysis:

```bash
/review --scope staged --checks all

# Command workflow:
# 1. Collects my automatic findings
# 2. Invokes @code-reviewer sub-agent for deep analysis
# 3. Invokes @security-auditor sub-agent
# 4. Generates comprehensive report with priorities
```

## Performance Impact

- **Activation time**: < 100ms
- **Analysis time**: < 1 second per file
- **Memory usage**: Minimal (read-only)
- **Background operation**: Non-blocking

This skill operates asynchronously and won't slow down your coding workflow.

## Language Support

### Fully Supported
- JavaScript/TypeScript (ES6+, React, Node.js)
- Python (3.8+, Django, FastAPI)
- Java (Spring Boot patterns)
- Go (standard patterns)

### Partial Support
- Ruby, PHP, C#, Rust
- Framework-agnostic patterns apply

Want to add language-specific patterns? See customization guide above.

## Tips for Best Results

1. **Write code first, then review** - Let me catch issues as you go
2. **Don't ignore warnings** - Each flagged issue is worth reviewing
3. **Use sub-agent for learning** - Invoke @code-reviewer to understand "why"
4. **Customize for your stack** - Add project-specific patterns
5. **Combine with /review** - Use command for comprehensive pre-commit checks

## Related Tools

- **security-auditor skill**: Deeper security vulnerability scanning
- **test-generator skill**: Auto-suggest tests for your code
- **@code-reviewer sub-agent**: Comprehensive code review with examples
- **/review command**: Full workflow with multiple agents

## Learn More

- Architecture: [../../../ARCHITECTURE.md](../../../ARCHITECTURE.md)
- Templates: [../../TEMPLATES.md](../../TEMPLATES.md)
- Sub-agents: [../../../agents/README.md](../../../agents/README.md)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### ../../TEMPLATES.md

```markdown
# Skill Templates

> **Copy-paste templates for creating custom skills**

Use these templates to create company-specific or project-specific skills. Each template is ready to customize with your own logic.

---

## Template 1: Basic Skill (Minimal)

**Use for:** Simple detection and suggestion skills

**File:** `skills/custom/my-skill/SKILL.md`

```markdown
---
name: my-skill
description: Brief description with TRIGGER KEYWORDS. Use when [condition], or user mentions [keyword]. Triggers on [event1], [event2].
allowed-tools: Read, Grep
---

# My Skill

[One-sentence description]

## When I Activate

- ✅ [Condition 1]
- ✅ [Condition 2]
- ✅ User mentions [keyword]

## What I Do

- [Action 1]
- [Action 2]
- [Action 3]

## Examples

### Example 1

\```language
// Your code:
[code example]

// I suggest:
[suggestion]
\```

## Relationship with @sub-agent-name

**Me (Skill):** Quick automatic checks
**@sub-agent (Sub-Agent):** Deep manual analysis

### Workflow
1. I detect [issue]
2. User invokes **@sub-agent** for details

## Sandboxing Compatibility

**Works without sandboxing:** ✅ Yes
**Works with sandboxing:** ✅ Yes

- **Filesystem**: [Read/Write/None]
- **Network**: [None/Optional]
- **Configuration**: None required

## Best Practices

1. [Practice 1]
2. [Practice 2]
3. [Practice 3]
```

**File:** `skills/custom/my-skill/README.md`

```markdown
# My Skill

> [One-sentence tagline]

## Quick Example

\```language
// Example showing skill in action
\```

## What It Does

- ✅ [Feature 1]
- ✅ [Feature 2]
- ✅ [Feature 3]

## Triggers

- [Event 1]
- [Event 2]
- [Event 3]

See [SKILL.md](SKILL.md) for full documentation.
```

---

## Template 2: Security Scanner

**Use for:** Custom security checks, company security policies

**File:** `skills/security/company-security-scanner/SKILL.md`

```markdown
---
name: company-security-scanner
description: Company-specific security standards validation. Use when security code modified, auth mentioned, or compliance needed. Triggers on authentication code, API endpoints, data handling.
allowed-tools: Read, Grep, Bash
---

# Company Security Scanner

Enforce company security standards and compliance requirements.

## When I Activate

- ✅ Authentication/authorization code modified
- ✅ API endpoints added or changed
- ✅ Data handling or storage code
- ✅ User mentions security, compliance, or audit
- ✅ Pre-commit (optional)

## What I Check

### Security Standards

**Authentication:**
- Company-approved auth methods only
- JWT token expiration policies
- Password complexity requirements
- MFA enforcement

**Data Protection:**
- PII handling compliance
- Data encryption at rest
- HTTPS/TLS enforcement
- Database credential management

**API Security:**
- Rate limiting implementation
- Input validation standards
- CORS configuration
- API key rotation policies

## Detection Logic

### Pattern Matching

\```javascript
// Detect non-compliant auth:
const violations = [
  /basicAuth/i,                    // BasicAuth not allowed
  /hardcoded.*password/i,          // No hardcoded passwords
  /jwt.*expiresIn.*[^1-9]h/       // JWT must expire < 10h
]
\```

### Company Standards

\```yaml
Required Headers:
  - X-Content-Type-Options: nosniff
  - X-Frame-Options: DENY
  - Strict-Transport-Security: max-age=31536000

Forbidden Packages:
  - old-jwt-lib (use company-auth-lib)
  - insecure-crypto (use company-crypto-lib)
\```

## Examples

### Authentication Violation

\```javascript
// You write:
app.post('/login', (req, res) => {
  const { username, password } = req.body
  if (password === 'admin123') {  // ⚠️ VIOLATION
    res.json({ token: generateToken() })
  }
})

// I alert:
// 🚨 CRITICAL: Security Violation
// Line 3: Hardcoded password
// Company Policy: Passwords must be hashed and stored securely
// Required: Use company-auth-lib.verifyPassword()
// → For compliance review: @security-auditor
\```

### Missing Security Headers

\```javascript
// You write:
app.use(cors())  // ⚠️ INCOMPLETE

// I suggest:
// ⚠️ MEDIUM: Missing required security headers
// Company Standard: Must include X-Frame-Options, CSP
// Add:
app.use(helmet({
  frameguard: { action: 'deny' },
  contentSecurityPolicy: { /* company policy */ }
}))
\```

## Integration with @security-auditor

**Me (Skill):** Real-time company policy enforcement
**@security-auditor (Sub-Agent):** Comprehensive vulnerability analysis

### Workflow
1. I detect company policy violations during coding
2. User runs **@security-auditor** for OWASP Top 10 analysis
3. Combined: Company standards + Industry best practices

## Customization

\```markdown
### Add Company-Specific Rules

Edit SKILL.md and add to "What I Check" section:

**Company Rule #47:**
- All APIs must use company-auth-lib v2.3+
- Rate limit: 100 req/min per user
- Audit logging required for PII access

### Update Detection Patterns

\```javascript
// Add to detection logic:
const companyViolations = [
  /api.*without.*companyAuthMiddleware/i,
  /pii.*without.*auditLog/i
]
\```
\```

## Sandboxing Compatibility

**Works without sandboxing:** ✅ Yes
**Works with sandboxing:** ✅ Yes

**Optional sandboxing config:**
\```json
{
  "network": {
    "allowedDomains": [
      "company-security-api.internal"
    ]
  },
  "filesystem": {
    "readOnly": [
      "/company-security-policies/"
    ]
  }
}
\```

## Best Practices

1. **Keep policies updated** - Sync with security team monthly
2. **Severity levels** - CRITICAL blocks commits, MEDIUM warns
3. **Education over enforcement** - Explain why, not just what
4. **Integration** - Work with CI/CD security gates
5. **Exception handling** - Document approved exceptions

## Related Tools

- **@security-auditor sub-agent**: OWASP vulnerability scanning
- **secret-scanner skill**: Exposed secrets detection
- **dependency-auditor skill**: CVE checking
```

**File:** `skills/security/company-security-scanner/README.md`

```markdown
# Company Security Scanner

> Real-time company security policy enforcement

## Quick Example

\```javascript
// You write non-compliant code:
app.post('/login', basicAuth())  // ❌ BasicAuth not allowed

// Skill alerts:
🚨 Security Policy Violation
Company requires OAuth2 with MFA
Use: company-auth-lib.oauth2WithMFA()
\```

## What It Checks

- ✅ Company-approved authentication methods
- ✅ Required security headers
- ✅ Data protection compliance
- ✅ API security standards
- ✅ Forbidden package usage

## Integration

Works with:
- **@security-auditor**: Industry vulnerability scanning
- **secret-scanner skill**: Exposed secrets
- **CI/CD**: Blocks non-compliant deployments

See [SKILL.md](SKILL.md) for full documentation.
```

---

## Template 3: Framework-Specific Validator

**Use for:** React/Vue/Angular conventions, Next.js best practices

**File:** `skills/development/nextjs-validator/SKILL.md`

```markdown
---
name: nextjs-validator
description: Next.js 15+ best practices and conventions. Use when Next.js files modified, app router used, or server components mentioned. Triggers on page.tsx, layout.tsx, route.ts changes.
allowed-tools: Read, Grep, Glob
---

# Next.js Validator

Enforce Next.js 15+ best practices and App Router conventions.

## When I Activate

- ✅ Files in `app/` directory modified
- ✅ Server/Client components created
- ✅ API routes added
- ✅ User mentions Next.js, App Router, RSC
- ✅ File saved with `.tsx` in `app/` folder

## What I Check

### App Router Conventions

**File Structure:**
- `app/page.tsx` - Pages
- `app/layout.tsx` - Layouts
- `app/loading.tsx` - Loading states
- `app/error.tsx` - Error boundaries
- `app/not-found.tsx` - 404 pages

**Server vs Client Components:**
- Server Components (default)
- Client Components (`'use client'`)
- Proper directive placement

**Data Fetching:**
- `fetch()` with caching strategies
- Server Actions for mutations
- `revalidatePath()` / `revalidateTag()`

### Performance Checks

- Image optimization (`next/image`)
- Font optimization (`next/font`)
- Script loading (`next/script`)
- Dynamic imports for code splitting
- Metadata API usage

## Examples

### Server Component Violation

\```typescript
// You write:
'use client'  // ⚠️ UNNECESSARY

export default function Page() {
  // No client-side features used
  return <div>Static content</div>
}

// I suggest:
// ⚠️ OPTIMIZATION: Unnecessary 'use client'
// This component uses no client-side features
// Remove directive to enable Server Component benefits:
// - Faster initial load
// - Smaller bundle size
// - Better SEO
\```

### Image Optimization

\```typescript
// You write:
<img src="/hero.jpg" />  // ⚠️ NOT OPTIMIZED

// I suggest:
// ⚠️ PERFORMANCE: Use next/image for optimization
// Replace with:
import Image from 'next/image'
<Image
  src="/hero.jpg"
  alt="Hero image"
  width={800}
  height={600}
  priority  // For above-the-fold images
/>
// Benefits: Automatic WebP, lazy loading, responsive
\```

### Data Fetching Pattern

\```typescript
// You write:
'use client'
import { useEffect, useState } from 'react'

export default function Page() {
  const [data, setData] = useState()
  useEffect(() => {
    fetch('/api/data').then(r => setData(r))
  }, [])
}

// I suggest:
// ⚠️ PATTERN: Use Server Component for data fetching
// Replace with:
async function Page() {
  const data = await fetch('/api/data', {
    next: { revalidate: 3600 }  // Cache for 1 hour
  })
  return <div>{data}</div>
}
// Benefits: No loading states, better SEO, simpler code
\```

## Detection Logic

### Pattern Recognition

\```javascript
const patterns = {
  unnecessaryUseClient: /'use client'.*no.*hooks.*no.*events/,
  unoptimizedImage: /<img[^>]+src=/,
  clientDataFetch: /'use client'.*useEffect.*fetch/,
  missingMetadata: /export.*Page.*without.*metadata/
}
\```

## Relationship with @architect

**Me (Skill):** Next.js convention enforcement
**@architect (Sub-Agent):** Full architecture review

### Workflow
1. I detect Next.js-specific issues in real-time
2. User invokes **@architect** for system design review

## Sandboxing Compatibility

**Works without sandboxing:** ✅ Yes
**Works with sandboxing:** ✅ Yes

- **Filesystem**: Read-only
- **Network**: None
- **Configuration**: None required

## Best Practices

1. **Server Components by default** - Only use 'use client' when needed
2. **Optimize images** - Always use next/image
3. **Cache strategically** - Use revalidate for dynamic content
4. **Colocate data fetching** - Fetch in component, not separate hook
5. **Use Metadata API** - Generate SEO tags automatically

## Related Tools

- **@architect sub-agent**: System architecture review
- **code-reviewer skill**: General code quality
- **test-generator skill**: Component testing
```

---

## Template 4: Documentation Generator

**Use for:** Auto-generating specific documentation types

**File:** `skills/documentation/changelog-generator/SKILL.md`

```markdown
---
name: changelog-generator
description: Auto-generate CHANGELOG.md entries from git commits. Use when commits made, version bumped, or release prepared. Triggers on git commit, version in package.json changed.
allowed-tools: Bash, Read, Write
---

# Changelog Generator

Automatically generate CHANGELOG.md from conventional commits.

## When I Activate

- ✅ Git commits detected
- ✅ `package.json` version changed
- ✅ User mentions "changelog", "release notes", or "version"
- ✅ Tag created (e.g., v1.2.0)
- ✅ Multiple commits since last changelog update

## What I Generate

### Changelog Format (Keep a Changelog)

\```markdown
# Changelog

## [1.2.0] - 2025-10-24

### Added
- New authentication system with OAuth2
- User profile management UI

### Changed
- Improved performance of data loading (30% faster)
- Updated dependency versions for security

### Fixed
- Resolved memory leak in WebSocket connection
- Fixed timezone bug in date formatting

### Security
- Patched XSS vulnerability in user input
\```

## Detection Logic

### Parse Conventional Commits

\```bash
# Analyze commits since last tag:
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# Extract commit types:
feat:    → ### Added
fix:     → ### Fixed
perf:    → ### Changed (performance)
security:→ ### Security
docs:    → Skip (documentation changes)
\```

### Version Bumping

\```javascript
// Determine version bump:
const hasFeat = commits.some(c => c.startsWith('feat:'))
const hasFix = commits.some(c => c.startsWith('fix:'))
const hasBreaking = commits.some(c => c.includes('BREAKING CHANGE'))

if (hasBreaking) return 'major'  // 1.0.0 → 2.0.0
if (hasFeat) return 'minor'       // 1.0.0 → 1.1.0
if (hasFix) return 'patch'        // 1.0.0 → 1.0.1
\```

## Examples

### From Commits to Changelog

\```bash
# Recent commits:
feat(auth): add OAuth2 authentication
fix(api): resolve memory leak in WebSocket
perf(db): optimize query performance (30% faster)
docs: update API documentation

# Generated changelog entry:
## [1.2.0] - 2025-10-24

### Added
- **auth**: OAuth2 authentication system

### Fixed
- **api**: Memory leak in WebSocket connection

### Changed
- **db**: Query performance optimized (30% faster)
\```

### Integration with Release

\```bash
# You create tag:
git tag v1.2.0

# I auto-generate:
# 1. CHANGELOG.md entry
# 2. GitHub release notes
# 3. npm version bump
# → For complete release: /release command
\```

## Relationship with @docs-writer

**Me (Skill):** Auto-generate changelog from commits
**@docs-writer (Sub-Agent):** Comprehensive release documentation

### Workflow
1. I generate changelog entries automatically
2. User invokes **@docs-writer** for full release notes with migration guides

## Customization

\```markdown
### Custom Commit Types

Add to detection logic:

\```yaml
Custom Types:
  epic: → ### Major Features
  ux: → ### User Experience
  a11y: → ### Accessibility
\```

### Custom Changelog Format

Edit template:

\```markdown
## [Version] - Date

**New Features**
- Feature 1
- Feature 2

**Bug Fixes**
- Fix 1

**Breaking Changes**
- ⚠️ Change 1 (migration guide link)
\```
\```

## Sandboxing Compatibility

**Works without sandboxing:** ✅ Yes
**Works with sandboxing:** ✅ Yes

- **Filesystem**: Writes to CHANGELOG.md
- **Network**: None (unless fetching GitHub metadata)
- **Git**: Requires git access

## Best Practices

1. **Conventional commits** - Consistent commit messages are crucial
2. **Semantic versioning** - Follow semver strictly
3. **Breaking changes** - Always document migration path
4. **Categorization** - Group changes logically
5. **Links** - Reference issues and PRs

## Related Tools

- **git-commit-helper skill**: Generate commit messages
- **@docs-writer sub-agent**: Full release documentation
- **/release command**: Complete release workflow
```

---

## Template 5: Testing Helper

**Use for:** Test coverage monitoring, test quality checks

**File:** `skills/testing/coverage-monitor/SKILL.md`

```markdown
---
name: coverage-monitor
description: Monitor test coverage and suggest missing tests. Use when code added without tests, coverage drops, or tests mentioned. Triggers on new files without tests, coverage below threshold.
allowed-tools: Bash, Read, Grep, Glob
---

# Coverage Monitor

Track test coverage and suggest missing tests automatically.

## When I Activate

- ✅ New file added without corresponding test file
- ✅ Function added without tests
- ✅ Coverage drops below threshold (e.g., 80%)
- ✅ User mentions "tests", "coverage", or "untested"
- ✅ Pull request created

## What I Check

### Coverage Metrics

**File Coverage:**
- Each source file has corresponding test file
- Naming convention: `utils.ts` → `utils.test.ts`

**Line Coverage:**
- Minimum 80% line coverage
- Critical paths: 100% coverage (auth, payments)

**Branch Coverage:**
- All if/else paths tested
- All switch cases covered
- Error handling tested

**Function Coverage:**
- All exported functions tested
- Edge cases covered

## Examples

### Missing Test File

\```typescript
// You create:
src/utils/formatDate.ts

// I detect:
// ⚠️ COVERAGE: Missing test file
// File: src/utils/formatDate.ts
// Expected: src/utils/formatDate.test.ts
// Functions to test:
//   - formatDate() - 3 suggested tests
//   - parseDate() - 4 suggested tests
// → For full suite: @test-engineer
\```

### Coverage Drop

\```bash
# You commit changes:
git commit -m "feat: add discount calculation"

# I run coverage:
# Coverage: 78% → 72% (-6%)
# ⚠️ COVERAGE DROP
# New uncovered lines:
#   - src/pricing.ts:45-52 (discount logic)
#   - src/pricing.ts:67 (error handling)
# Suggested tests:
#   - Test discount calculation with edge cases
#   - Test error handling for invalid discounts
\```

### Untested Error Path

\```javascript
// You write:
function processPayment(amount) {
  if (amount < 0) {
    throw new Error('Invalid amount')  // ⚠️ UNTESTED
  }
  return chargeCard(amount)
}

// I suggest:
// ⚠️ UNTESTED: Error path not covered
// Line 3: Error thrown but no test
// Add test:
test('throws error for negative amount', () => {
  expect(() => processPayment(-10))
    .toThrow('Invalid amount')
})
\```

## Detection Logic

\```bash
# Check for test file:
if [ -f "src/utils/formatDate.ts" ] && [ ! -f "src/utils/formatDate.test.ts" ]; then
  echo "Missing test file"
fi

# Run coverage:
npm test -- --coverage
if [ $coverage -lt 80 ]; then
  echo "Coverage below threshold"
fi

# Find untested functions:
grep -r "export function" src/ | while read func; do
  # Check if function name appears in tests
done
\```

## Integration with @test-engineer

**Me (Skill):** Real-time coverage monitoring
**@test-engineer (Sub-Agent):** Comprehensive test suite creation

### Workflow
1. I detect missing coverage automatically
2. User invokes **@test-engineer** for complete test implementation
3. I validate coverage after tests added

## Customization

\```markdown
### Set Custom Thresholds

Edit thresholds in SKILL.md:

\```yaml
Coverage Thresholds:
  Minimum: 80%
  Critical Paths: 100%  # auth, payments, security
  New Code: 90%  # Higher bar for new features
\```

### Custom Test Patterns

\```javascript
// Support different test frameworks:
const testPatterns = [
  '.test.ts',     // Jest
  '.spec.ts',     // Angular
  '_test.py',     // Python
  '_spec.rb'      // RSpec
]
\```
\```

## Sandboxing Compatibility

**Works without sandboxing:** ✅ Yes
**Works with sandboxing:** ⚠️ Needs test runner access

**Required sandboxing config:**
\```json
{
  "filesystem": {
    "readWrite": ["coverage/"]
  },
  "commands": {
    "allowed": ["npm test", "jest", "pytest"]
  }
}
\```

## Best Practices

1. **Continuous monitoring** - Check coverage on every commit
2. **Fail fast** - Block PRs below threshold
3. **Prioritize critical paths** - 100% coverage for auth, payments
4. **Test quality over quantity** - Meaningful tests, not just lines
5. **Integration with CI** - Automate coverage reporting

## Related Tools

- **test-generator skill**: Auto-create test scaffolding
- **@test-engineer sub-agent**: Comprehensive test implementation
- **/test-gen command**: Generate complete test suites
```

---

## Installation

### Using Templates

1. **Copy template:**
```bash
cp -r skills/TEMPLATES.md my-project/
```

2. **Customize:**
- Edit SKILL.md frontmatter (name, description, allowed-tools)
- Update detection logic
- Add company-specific examples

3. **Install:**
```bash
# Symlink to Claude Code config
ln -s $(pwd)/skills/custom/my-skill \
      ~/.claude/skills/my-skill
```

4. **Verify:**
```bash
# Check skill is loaded
claude --list-skills | grep my-skill
```

---

## Best Practices for Custom Skills

### 1. Clear Trigger Keywords

**Good:**
```yaml
description: Use when API endpoints modified, routes changed, or REST API mentioned
```

**Bad:**
```yaml
description: Helps with API stuff
```

### 2. Appropriate Tool Selection

**For detection only:**
```yaml
allowed-tools: Read, Grep
```

**For documentation generation:**
```yaml
allowed-tools: Read, Write, Edit
```

**For running checks:**
```yaml
allowed-tools: Read, Bash
```

### 3. Complement, Don't Duplicate

**Skill** = Quick, automatic, real-time
**Sub-Agent** = Deep, manual, comprehensive

**Example:**
- Skill: Detects untested function
- Sub-Agent: Creates full test suite with edge cases

### 4. Sandboxing: Optional First

Design skills to work WITHOUT sandboxing by default. Add sandboxing as optional hardening.

### 5. Progressive Disclosure

README.md = Quick reference
SKILL.md = Complete documentation
External links = Deep-dive resources

---

## Template Checklist

Before publishing custom skill:

- [ ] SKILL.md has valid YAML frontmatter
- [ ] Description includes trigger keywords
- [ ] allowed-tools matches actual tool usage
- [ ] Works WITHOUT sandboxing (default)
- [ ] README.md has quick example
- [ ] Examples show real-world usage
- [ ] Sandboxing section explains optional config
- [ ] Integration with sub-agents/commands documented
- [ ] Best practices section included
- [ ] Tested with actual code changes

---

## Support

**Questions?**
- Browse existing skills in `skills/` for reference
- See [skills/README.md](README.md) for architecture overview
- Check [GETTING-STARTED.md](../GETTING-STARTED.md) for setup help

**Contributing?**
- Fork repo, add skill to `skills/custom/`
- Submit PR with skill + examples
- Follow template structure

---

**Created:** October 24, 2025
**Author:** Alireza Rezvani
**License:** MIT

```

### ../../../ARCHITECTURE.md

```markdown
# Architecture Guide

> **Understanding the 3-tier system: Skills → Sub-Agents → Commands**

Claude Code Tresor uses a carefully designed 3-tier architecture that provides the right tool for every task, from automatic background checks to complex multi-step workflows.

---

## Overview

```
┌─────────────────────────────────────────────────────────────┐
│                     Your Development Flow                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
        ┌──────────────────────────────────────────┐
        │          Tier 1: SKILLS                  │
        │      (Contextual Conversation Helpers)   │
        │  • Invoked by Claude automatically       │
        │  • Context-aware activation              │
        │  • Quick checks                          │
        │  • Proactive suggestions                 │
        └──────────────────────────────────────────┘
                              │
                              ▼ (User decides to investigate)
        ┌──────────────────────────────────────────┐
        │          Tier 2: SUB-AGENTS              │
        │        (Manual Expert Analysis)          │
        │  • Invoked by you (@agent)               │
        │  • Deep analysis                         │
        │  • Separate context                      │
        │  • Expert recommendations                │
        └──────────────────────────────────────────┘
                              │
                              ▼ (User runs workflow)
        ┌──────────────────────────────────────────┐
        │          Tier 3: COMMANDS                │
        │      (Multi-Agent Orchestration)         │
        │  • Complex workflows (/command)          │
        │  • Coordinates multiple agents           │
        │  • Automates repetitive tasks            │
        │  • End-to-end processes                  │
        └──────────────────────────────────────────┘
```

---

## Tier 1: Skills (Contextual Helpers)

### What Are Skills?

Skills are **lightweight, contextual helpers** that Claude invokes automatically during conversations when they're relevant to your discussion or task.

**Key characteristics:**
- ✅ **Claude-invoked** - Claude decides when to activate based on conversation context
- ✅ **Shared context** - See your current conversation and understand the discussion
- ✅ **Limited tools** - Restricted to safe operations (Read, Write, Edit, Grep, Glob, Bash)
- ✅ **Single-purpose** - Each skill has one clear responsibility
- ✅ **Non-blocking** - Provide suggestions without interrupting flow

### How Skills Activate

Skills are invoked by Claude based on **conversation relevance** and their description:

```yaml
---
name: code-reviewer
description: Use when discussing code quality, reviewing files, or analyzing patterns...
---
```

**Invocation examples:**
- You ask "Review this code" → `code-reviewer` is invoked
- You discuss new function testing → `test-generator` is invoked
- You ask about API documentation → `api-documenter` is invoked
- You discuss commit messages → `git-commit-helper` is invoked

### Skills in Action

```javascript
// You write this code:
function getUser(id) {
  return db.query('SELECT * FROM users WHERE id = ' + id)
}

// Immediately, multiple skills activate:

// 1. code-reviewer skill:
// ⚠️ Missing error handling
// 💡 Consider adding try-catch

// 2. security-auditor skill:
// 🚨 SQL Injection vulnerability
// 🔧 Use parameterized queries

// 3. test-generator skill:
// 📋 Missing tests for getUser()
// 💡 Suggest 3 basic tests

// You see all suggestions at once
```

### Available Skills (8 Core)

| Skill | Purpose | Triggers On |
|-------|---------|-------------|
| **code-reviewer** | Code quality checks | File edits, saves |
| **test-generator** | Suggest missing tests | New functions, untested code |
| **git-commit-helper** | Generate commit messages | Git diff, "commit" mentioned |
| **security-auditor** | Vulnerability scanning | Auth code, API endpoints |
| **secret-scanner** | Detect exposed secrets | Pre-commit, API keys in code |
| **dependency-auditor** | Check for CVEs | package.json changes |
| **api-documenter** | Generate OpenAPI specs | API routes added |
| **readme-updater** | Keep README current | Project changes, features added |

**Design principle:** Skills are like **spell-checker in your editor** - always on, always helping, never intrusive.

---

## Tier 2: Sub-Agents (Manual Experts)

### What Are Sub-Agents?

Sub-agents are **manually-invoked specialists** that provide deep, comprehensive analysis when you explicitly request it.

**Key characteristics:**
- ✅ **User-invoked** - You explicitly call them (`@agent`)
- ✅ **Separate context** - Dedicated focus on the task
- ✅ **Full tool access** - Can use Read, Write, Edit, Bash, Grep, Glob, Task, WebFetch
- ✅ **Expert depth** - Comprehensive analysis and recommendations
- ✅ **Task-oriented** - Complete a specific analysis task

### How Sub-Agents Work

You invoke sub-agents when you need **deep analysis** that goes beyond quick skill suggestions:

```bash
# General syntax
@agent-name [task description] [--flags]

# Examples
@code-reviewer Analyze this component for React best practices
@test-engineer Create comprehensive test suite with edge cases
@docs-writer Generate user guide with troubleshooting section
@architect Evaluate this microservices design
@debugger Analyze this stack trace and suggest fixes
```

### Sub-Agents in Action

```javascript
// After skill detected issue:
// skill: "⚠️ Potential security issue in authentication"

// You invoke expert:
You: @code-reviewer --focus security

// Sub-agent provides deep analysis:
@code-reviewer:

📋 SECURITY ANALYSIS: Authentication Module

🚨 CRITICAL ISSUES (2)
1. Line 45: Hardcoded JWT secret
   - Risk: Secret exposure in version control
   - Fix: Move to environment variable
   - Example: process.env.JWT_SECRET

2. Line 67: No rate limiting on login endpoint
   - Risk: Brute force attacks
   - Fix: Implement express-rate-limit
   - Config: 5 attempts per 15 minutes

⚠️ MEDIUM ISSUES (3)
[detailed analysis...]

📖 RECOMMENDATIONS
[architectural improvements...]

✅ GOOD PRACTICES FOUND
[positive feedback...]
```

### Available Sub-Agents (8 Core)

| Agent | Expertise | When to Use |
|-------|-----------|-------------|
| **@code-reviewer** | Code quality, patterns, security | PR reviews, refactoring validation |
| **@test-engineer** | Test suite creation, coverage | Comprehensive testing needs |
| **@docs-writer** | User guides, API docs, tutorials | Documentation site creation |
| **@architect** | System design, architecture | Design reviews, technical decisions |
| **@debugger** | Root cause analysis, debugging | Production issues, complex bugs |
| **@security-auditor** | Vulnerability analysis, compliance | Security audits, penetration testing prep |
| **@performance-tuner** | Performance optimization | Slow queries, memory leaks |
| **@refactor-expert** | Code restructuring, patterns | Technical debt, legacy code |

**Design principle:** Sub-agents are like **consulting an expert** - you schedule time when you need deep help.

---

## Tier 3: Commands (Orchestration)

### What Are Commands?

Commands are **multi-agent workflows** that orchestrate skills and sub-agents to complete complex, end-to-end processes.

**Key characteristics:**
- ✅ **User-triggered** - You explicitly run them (`/command`)
- ✅ **Multi-step workflows** - Coordinate multiple tools
- ✅ **Agent orchestration** - Invoke sub-agents in sequence
- ✅ **Batch operations** - Apply across multiple files
- ✅ **Workflow automation** - Eliminate repetitive tasks

### How Commands Work

Commands provide **structured workflows** for common development tasks:

```bash
# General syntax
/command [args] [--options]

# Examples
/scaffold react-component UserProfile --hooks --tests
/review --scope staged --checks all
/test-gen --file utils.js --framework jest --coverage 90
/docs-gen api --format openapi --include-examples
```

### Commands in Action

```bash
# Example: /review command workflow

You: /review --scope staged --checks all

Command orchestrates:

Step 1: Analyze staged changes
├─ skill: code-reviewer (quick scan)
├─ Read: git diff --staged
└─ Parse: Identify modified files

Step 2: Coordinate expert reviews
├─ @code-reviewer    → Code quality analysis
├─ @security-auditor → Vulnerability scan
├─ @performance-tuner→ Performance check
└─ @architect        → Architecture validation

Step 3: Aggregate results
├─ Combine findings from all agents
├─ Prioritize issues (CRITICAL → LOW)
├─ Remove duplicates
└─ Add line numbers and context

Step 4: Generate report
└─ Markdown report with:
    - Executive summary
    - Issue breakdown by severity
    - Actionable recommendations
    - Code examples with fixes

Total time: 3-5 minutes
Manual equivalent: 30-45 minutes
```

### Available Commands (4 Core)

| Command | Purpose | What It Orchestrates |
|---------|---------|----------------------|
| **/scaffold** | Generate boilerplate | Creates files, adds tests, docs |
| **/review** | Comprehensive code review | @code-reviewer + @security-auditor + @performance-tuner + @architect |
| **/test-gen** | Generate test suites | @test-engineer + test-generator skill |
| **/docs-gen** | Generate documentation | @docs-writer + api-documenter + readme-updater |

**Design principle:** Commands are like **running a script** - automate complex multi-step processes.

---

## Integration Patterns

### Pattern 1: Skill → User → Sub-Agent

**Flow:** Skill detects → User investigates → Sub-agent analyzes

```
┌──────────────┐
│ Skill alerts │  "⚠️ Potential memory leak"
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ User decides │  "Let me investigate"
└──────┬───────┘
       │
       ▼
┌──────────────────┐
│ Sub-agent deep   │  @debugger Analyze memory usage in this module
│ analysis         │  → Comprehensive report with stack traces
└──────────────────┘
```

**Example:**
```javascript
// 1. Skill: "⚠️ test-generator: Missing tests for calculateDiscount()"
// 2. You: "This is critical, needs comprehensive testing"
// 3. You invoke: @test-engineer Create full test suite with edge cases
// 4. Sub-agent: Generates 15 tests covering all scenarios
```

---

### Pattern 2: User → Command → Multi-Agent

**Flow:** User triggers → Command orchestrates → Agents execute

```
┌──────────────┐
│ User runs    │  /review --scope staged
│ command      │
└──────┬───────┘
       │
       ▼
┌────────────────────────────┐
│ Command coordinates:       │
│  1. @code-reviewer         │
│  2. @security-auditor      │
│  3. @performance-tuner     │
│  4. @architect             │
└────────┬───────────────────┘
         │
         ▼
┌────────────────────────────┐
│ Aggregated results with    │
│ prioritized recommendations│
└────────────────────────────┘
```

**Example:**
```bash
# You: /review --scope pr --checks all
# Command runs all agents in parallel, combines results
# Output: Single comprehensive report in 5 minutes
```

---

### Pattern 3: Multiple Skills Collaborate

**Flow:** Multiple skills detect different aspects simultaneously

```
┌────────────────┐       ┌────────────────┐       ┌────────────────┐
│ code-reviewer  │       │ security-      │       │ test-generator │
│ skill          │       │ auditor skill  │       │ skill          │
└────────┬───────┘       └────────┬───────┘       └────────┬───────┘
         │                        │                        │
         ▼                        ▼                        ▼
    "Code smell"          "SQL injection"         "Missing tests"
         │                        │                        │
         └────────────────────────┴────────────────────────┘
                                  │
                                  ▼
                        User sees all suggestions
```

**Example:**
```javascript
// You write function with multiple issues:
function login(username, password) {
  const query = 'SELECT * FROM users WHERE name = ' + username  // Issue 1
  const user = db.query(query)  // Issue 2
  if (user.password === password) return user  // Issue 3
}

// Multiple skills activate simultaneously:
// • code-reviewer: "No error handling, missing types"
// • security-auditor: "SQL injection (line 2), plaintext password (line 4)"
// • test-generator: "Missing tests - suggest 4 tests"

// You see comprehensive feedback immediately
```

---

### Pattern 4: Continuous Development Cycle

**Flow:** Skills monitor → Commands execute → Sub-agents deep-dive

```
┌─────────────────────────────────────────────────────────┐
│                   DEVELOPMENT CYCLE                     │
└─────────────────────────────────────────────────────────┘

1. WRITE CODE
   └─→ Skills monitor continuously
       • code-reviewer checks quality
       • security-auditor scans for vulnerabilities
       • test-generator suggests tests

2. STAGE CHANGES
   └─→ git add .
       • secret-scanner prevents exposed secrets
       • git-commit-helper suggests commit message

3. RUN WORKFLOW
   └─→ /review --scope staged
       • Command orchestrates all agents
       • Comprehensive validation

4. DEEP ANALYSIS (if needed)
   └─→ @architect Review this design pattern
       • Expert analysis for complex issues

5. COMMIT & DEPLOY
   └─→ Skills updated documentation automatically
       • readme-updater keeps README current
       • api-documenter updates OpenAPI specs
```

---

## Decision Tree: Which Tool to Use?

```
                    START: I need help with...
                              │
                              ▼
                    ┌─────────────────────┐
                    │ What type of help?  │
                    └─────────────────────┘
                              │
                 ┌────────────┼────────────┐
                 ▼            ▼            ▼
          AUTOMATIC      MANUAL       WORKFLOW
               │             │            │
               ▼             ▼            ▼
        ┌───────────┐  ┌────────┐  ┌─────────┐
        │  SKILLS   │  │ SUB-   │  │COMMANDS │
        │           │  │ AGENTS │  │         │
        └───────────┘  └────────┘  └─────────┘

Use SKILLS when:                Use SUB-AGENTS when:           Use COMMANDS when:
• You want continuous           • You need expert analysis      • You need multi-step
  monitoring                    • Issue requires deep dive        workflow
• Quick checks needed           • Manual investigation          • Orchestrating multiple
• Real-time suggestions         • Complex problem                 tools
• No explicit invocation        • Dedicated focus               • Batch operations
                                                                • Automation

Examples:                       Examples:                       Examples:
• Code quality while            • @code-reviewer                • /scaffold new component
  typing                          Deep security review          • /review entire PR
• Detect untested code          • @architect                    • /test-gen for file
• Security scans                  System design validation      • /docs-gen API docs
• README updates                • @debugger
                                  Root cause analysis
```

---

## Performance Characteristics

### Skills (Tier 1)

**Activation time:** Instant (< 100ms)
**Tool restrictions:** Read, Write, Edit, Grep, Glob, Bash (safe operations)
**Context size:** Shared (efficient)
**Parallelization:** Automatic (multiple skills run simultaneously)
**Use case:** Continuous background monitoring

**Optimization:**
- Lightweight by design
- Limited tool set prevents expensive operations
- Shared context reduces memory footprint

---

### Sub-Agents (Tier 2)

**Invocation time:** 30 seconds - 5 minutes (depending on task)
**Tool access:** Full (Read, Write, Edit, Bash, Grep, Glob, Task, WebFetch)
**Context size:** Dedicated (comprehensive analysis)
**Parallelization:** Manual (user decides)
**Use case:** Deep, focused analysis

**Optimization:**
- Separate context enables focused work
- Full tool access for comprehensive analysis
- Task tool allows recursive problem-solving

---

### Commands (Tier 3)

**Execution time:** 3-15 minutes (depending on workflow)
**Coordination:** Orchestrates skills + sub-agents
**Parallelization:** Intelligent (runs independent agents in parallel)
**Context management:** Aggregates results from multiple sources
**Use case:** End-to-end workflows

**Optimization:**
- Parallel agent execution where possible
- Result aggregation and deduplication
- Prioritized output (CRITICAL → LOW)

---

## Best Practices

### For Skills

1. **Let them run** - Skills are designed to be non-intrusive
2. **Review suggestions** - Skills detect, you decide
3. **Use as early warning** - Catch issues before they grow
4. **Customize triggers** - Adjust for your workflow
5. **Don't disable unnecessarily** - They're lightweight

### For Sub-Agents

1. **Be specific** - "Analyze security" vs "Check this file"
2. **Use flags** - `@code-reviewer --focus performance`
3. **One task at a time** - Sub-agents work best with clear goals
4. **Read full output** - Expert recommendations are valuable
5. **Iterate** - Re-invoke with refined questions

### For Commands

1. **Use for repetitive tasks** - Automate what you do often
2. **Combine with flags** - `/review --scope staged --checks security`
3. **Let it finish** - Commands orchestrate multiple steps
4. **Review results** - Commands surface prioritized issues
5. **Customize workflows** - Fork and modify for your team

---

## Extending the Architecture

### Custom Skills

Create custom skills for team-specific needs:

```yaml
---
name: company-security-scanner
description: Company security policy enforcement. Use when auth code modified...
allowed-tools: Read, Grep, Bash
---
```

**See:** [skills/TEMPLATES.md](skills/TEMPLATES.md)

---

### Custom Sub-Agents

Add specialized sub-agents for domain expertise:

```json
{
  "name": "mobile-performance-expert",
  "description": "React Native performance optimization specialist",
  "allowed-tools": ["Read", "Bash", "Grep", "Task", "WebFetch"]
}
```

**See:** [agents/README.md](agents/README.md)

---

### Custom Commands

Build workflows specific to your process:

```json
{
  "name": "deploy-check",
  "description": "Pre-deployment validation workflow",
  "agents": ["@security-auditor", "@test-engineer", "@performance-tuner"]
}
```

**See:** [commands/README.md](commands/README.md)

---

## Real-World Workflow Example

### Scenario: Implementing a new feature

```bash
# 1. Start coding (Skills monitor automatically)
vim src/features/user-profile.tsx

  # → code-reviewer: "Consider useCallback for event handlers"
  # → test-generator: "Suggest 3 tests for UserProfile"

# 2. Stage changes
git add src/features/user-profile.tsx

  # → secret-scanner: Checks for exposed secrets
  # → git-commit-helper: Suggests "feat(profile): add user profile component"

# 3. Run comprehensive review
/review --scope staged --checks all

  # → Orchestrates 4 sub-agents in parallel:
  #   • @code-reviewer: React best practices
  #   • @security-auditor: XSS vulnerabilities
  #   • @performance-tuner: Render optimization
  #   • @architect: Component architecture

# 4. Deep-dive on specific issue (if needed)
@code-reviewer --focus performance Analyze re-render behavior

  # → Detailed analysis with profiling recommendations

# 5. Generate tests
/test-gen --file src/features/user-profile.tsx --coverage 90

  # → Creates comprehensive test suite

# 6. Update docs automatically
# (Skills do this in background)
  # → api-documenter: Updates OpenAPI if API changed
  # → readme-updater: Adds feature to README

# 7. Commit
git commit -m "feat(profile): add user profile component"

Total time with tools: 30-40 minutes
Total time without: 3-4 hours
```

---

## Architecture Philosophy

### Design Principles

1. **Right tool for the job** - Skills for detection, sub-agents for analysis, commands for workflows
2. **Progressive disclosure** - Simple → Deep → Complex
3. **Non-blocking** - Never interrupt developer flow
4. **Composable** - Tools work together seamlessly
5. **Customizable** - Extend for team needs

### Why 3 Tiers?

**Problem:** Traditional AI assistants are either:
- Too passive (only respond when asked) OR
- Too aggressive (interrupt constantly)

**Solution:** 3-tier architecture provides:
- **Skills:** Continuous passive monitoring (non-intrusive)
- **Sub-Agents:** Deep analysis on demand (focused)
- **Commands:** Workflow automation (efficient)

**Result:** Help when you need it, silent when you don't.

---

## Next Steps

- **Get Started:** [GETTING-STARTED.md](GETTING-STARTED.md) - 5-minute quick start
- **Skills Guide:** [skills/README.md](skills/README.md) - Deep-dive on skills
- **Templates:** [skills/TEMPLATES.md](skills/TEMPLATES.md) - Create custom tools
- **Migration:** [MIGRATION-GUIDE.md](MIGRATION-GUIDE.md) - Upgrade from older versions
- **Examples:** [examples/workflows/](examples/workflows/) - Real-world patterns

---

**Created:** October 24, 2025
**Author:** Alireza Rezvani
**License:** MIT

```

### ../../../agents/README.md

```markdown
# Claude Code Tresor - Core Agents (Backward Compatibility)

> **⚠️ NOTICE:** This directory is maintained for backward compatibility only.
> **Primary Location:** All agents are now organized in `/subagents/` (v2.7.0+)
> **Migration Path:** The `agent.md` files in this directory are symlinks to `/subagents/core/`

---

## 📦 Directory Structure (v2.7.0)

As of v2.7.0, Claude Code Tresor uses a unified agent structure:

```
subagents/                     # PRIMARY LOCATION (133 total agents)
├── core/                      # 8 core production agents
│   ├── config-safety-reviewer/
│   ├── systems-architect/
│   ├── root-cause-analyzer/
│   ├── security-auditor/
│   ├── test-engineer/
│   ├── performance-tuner/
│   ├── refactor-expert/
│   └── docs-writer/
├── engineering/               # 54 engineering specialists
├── design/                    # 7 design specialists
├── marketing/                 # 11 marketing specialists
├── product/                   # 9 product specialists
├── leadership/                # 14 leadership specialists
├── operations/                # 6 operations specialists
├── research/                  # 7 research specialists
├── ai-automation/             # 9 AI/ML specialists
└── account-customer-success/  # 8 account & CS specialists
```

**See:** [Complete Agent Catalog →](../subagents/README.md) | [Agent Index →](../subagents/AGENT-INDEX.md)

---

## 🤖 Core Agents (8 Total)

These 8 agents are duplicated here for backward compatibility. The authoritative versions are in `/subagents/core/`.

| Agent | Expertise | Location |
|-------|-----------|----------|
| **@config-safety-reviewer** | Configuration safety & production reliability | [subagents/core/config-safety-reviewer](../subagents/core/config-safety-reviewer/) |
| **@systems-architect** | System design & technology evaluation | [subagents/core/systems-architect](../subagents/core/systems-architect/) |
| **@root-cause-analyzer** | Comprehensive RCA & systematic debugging | [subagents/core/root-cause-analyzer](../subagents/core/root-cause-analyzer/) |
| **@security-auditor** | Security assessment & OWASP compliance | [subagents/core/security-auditor](../subagents/core/security-auditor/) |
| **@test-engineer** | Testing strategies & QA | [subagents/core/test-engineer](../subagents/core/test-engineer/) |
| **@performance-tuner** | Performance optimization & profiling | [subagents/core/performance-tuner](../subagents/core/performance-tuner/) |
| **@refactor-expert** | Code refactoring & clean architecture | [subagents/core/refactor-expert](../subagents/core/refactor-expert/) |
| **@docs-writer** | Technical documentation & user guides | [subagents/core/docs-writer](../subagents/core/docs-writer/) |

---

## 🚀 Quick Usage Examples

### Invoke Agents
```bash
# Works from either location (thanks to symlinks)
@systems-architect Design scalable e-commerce architecture for 100k users
@config-safety-reviewer Review database connection pool configuration
@security-auditor Analyze this authentication module for vulnerabilities
```

### Discover Extended Agents
```bash
# Browse 125 additional specialists in /subagents/
@database-optimizer   # Engineering team
@ui-designer          # Design team
@content-strategist   # Marketing team
@product-analyst      # Product team
@cto                  # Leadership team
```

**See:** [Complete List of 133 Agents →](../subagents/AGENT-INDEX.md)

---

## 🔧 Technical Details

### Symlink Structure (v2.7.0)

Each agent directory in `/agents/` contains:
- `README.md` - Original documentation (preserved for reference)
- `agent.md` - **Symlink** to `../../subagents/core/[agent-name]/agent.md`

**Example:**
```bash
agents/systems-architect/
├── README.md       # Original documentation
└── agent.md        # Symlink → ../../subagents/core/systems-architect/agent.md
```

This ensures:
- ✅ Backward compatibility for existing installations
- ✅ Single source of truth in `/subagents/core/`
- ✅ No duplication of agent logic
- ✅ Seamless updates via symlinks

### Installation

The installation script (`scripts/install.sh`) automatically:
1. Installs agents from `/subagents/core/` (primary location)
2. Creates symlinks in `/agents/` for backward compatibility
3. Updates Claude Code's agent registry

```bash
./scripts/install.sh --agents  # Installs all 8 core agents
```

---

## 📚 Documentation

### Quick Links
- **[Agent Catalog →](../subagents/README.md)** - Complete list of all 133 agents
- **[Agent Index →](../subagents/AGENT-INDEX.md)** - Searchable catalog with descriptions
- **[Getting Started →](../documentation/guides/getting-started.md)** - First-time user guide
- **[Technical Reference →](../documentation/reference/agents.md)** - Agent architecture details

### Migration Guide (for v2.4/v2.5 users)

**Agent Naming Changes (v2.5.0)**:
| Old Name (v2.4) | New Name (v2.5+) | Status |
|-----------------|------------------|--------|
| `@code-reviewer` | `@config-safety-reviewer` | ⚠️ Breaking |
| `@debugger` | `@root-cause-analyzer` | ⚠️ Breaking |
| `@architect` | `@systems-architect` | ⚠️ Breaking |

**Location Changes (v2.7.0)**:
- Primary location: `/agents/` → `/subagents/core/` (backward compatible via symlinks)

**No Action Required:** Symlinks ensure existing scripts and workflows continue to work.

---

## ⚠️ Deprecation Timeline

| Version | Status | Action |
|---------|--------|--------|
| **v2.7.0** (Current) | `/agents/` maintained with symlinks | ✅ Fully backward compatible |
| **v2.8.x** (2026 Q1) | `/agents/` marked deprecated | ⚠️ Migration warnings added |
| **v3.0.0** (2026 Q2) | `/agents/` removed | ❌ Breaking change |

**Recommendation:** Update your workflows to reference `/subagents/core/` to prepare for v3.0.0.

---

## 🆘 Support

- **[FAQ →](../documentation/reference/faq.md)** - Common questions
- **[Troubleshooting →](../documentation/guides/troubleshooting.md)** - Fix common issues
- **[GitHub Issues](https://github.com/alirezarezvani/claude-code-tresor/issues)** - Report bugs
- **[GitHub Discussions](https://github.com/alirezarezvani/claude-code-tresor/discussions)** - Ask questions

---

**Version:** 2.7.0
**Last Updated:** November 19, 2025
**License:** MIT
**Author:** Alireza Rezvani

```