Claude Code Subagents Registry

This repository uses specialized Claude Code subagents to handle specific workflows. Each agent has minimal tool permissions following least-privilege principles.

Agent Overview

Key Improvements

Reduced Overlap

• Merged: analysis-reporter + component-inspector → code-analyzer
  • Handles both automated analysis (madge, jscpd, ts-prune) and manual component exploration
  • Single agent for all code structure questions

Tightened Permissions

• Bash-only agents (no file reading needed, work with command output):
  • build-validator, test-runner, supabase-seeder, deploy-guardian
• Limited Edit (only for auto-fixes):
  • lint-enforcer (Bash + Edit)
• Read-only agents (exploration without modification):
  • i18n-manager, repo-onboarding
• Analysis agent (needs to read reports and code):
  • code-analyzer (Bash + Read + Grep + Glob)

Usage Guidelines

When Claude Code Should Auto-Delegate

Claude Code should automatically invoke these agents when:

1. build-validator - After modifying TypeScript files, components, or build config
2. lint-enforcer - After creating/modifying source files
3. test-runner - Before user says "deploy" or "ready for production"
4. deploy-guardian - When user requests deployment
5. code-analyzer - When user asks about code quality, architecture, or component structure
6. i18n-manager - After adding new UI components with user-facing text
7. repo-onboarding - When user asks "how does this work" or needs architectural overview

Workflow Examples

Pre-Deployment Checklist

1. lint-enforcer (auto-fix issues)
2. build-validator (verify types and build)
3. test-runner (run E2E tests)
4. deploy-guardian (execute deployment)

New Feature Development

1. code-analyzer (understand existing architecture)
2. [user makes changes]
3. lint-enforcer (check code quality)
4. build-validator (verify compilation)
5. i18n-manager (check translations)
6. test-runner (verify user flows)

Onboarding New Developer

1. repo-onboarding (architectural overview)
2. code-analyzer (explore specific components)
3. [developer makes changes]
4. lint-enforcer (ensure code quality)

Code Quality Review

1. code-analyzer (run automated analysis)
2. [review findings]
3. lint-enforcer (fix style issues)
4. build-validator (verify changes)

Agent Details

build-validator

Purpose: Validates Vite build and TypeScript compilation Tools: Bash only What it does: Runs tsc --noEmit and npm run build, parses output for type errors What it doesn't: Read files directly (works with compiler output)

lint-enforcer

Purpose: Enforces ESLint code quality standards Tools: Bash, Edit What it does: Runs npm run lint, applies auto-fixes with Edit tool What it doesn't: Fix semantic issues (only safe auto-fixes)

test-runner

Purpose: Executes Playwright E2E tests Tools: Bash only What it does: Runs npm run test:ui, parses test results from output What it doesn't: Read test files (works with test runner output)

supabase-seeder

Purpose: Manages database seeding operations Tools: Bash only What it does: Runs npm run seed:* scripts, reports success/failure What it doesn't: Read seed scripts or data files

deploy-guardian

Purpose: Deploys to GitHub Pages Tools: Bash only What it does: Runs npm run deploy, verifies with git status and ls What it doesn't: Read config files (uses command output)

code-analyzer

Purpose: Analyzes code quality and architecture Tools: Bash, Read, Grep, Glob What it does:

• Automated mode: Runs npm run analysis:all, reads reports/analysis.json
• Component mode: Explores React components, traces dependencies, maps architecture What it doesn't: Modify code (analysis only) Replaces: Previous analysis-reporter and component-inspector agents

i18n-manager

Purpose: Validates translation coverage Tools: Read, Grep, Glob What it does: Reads translation files, greps for usage, identifies missing/unused keys What it doesn't: Modify translations or run commands (pure exploration)

repo-onboarding

Purpose: Teaches repository architecture to newcomers Tools: Read, Grep, Glob What it does: Explores structure, reads key files, explains patterns and conventions What it doesn't: Modify anything (read-only guide)

Agent Files

All agent definitions are located in .claude/agents/:

• build-validator.md - Build and type checking
• lint-enforcer.md - ESLint integration
• test-runner.md - E2E testing
• supabase-seeder.md - Database seeding
• deploy-guardian.md - GitHub Pages deployment
• code-analyzer.md - Code quality and component analysis
• i18n-manager.md - Translation validation
• repo-onboarding.md - Architecture guide

Repository Context

• Type: React + TypeScript portfolio website
• Build: Vite
• Styling: Tailwind CSS
• Backend: Supabase (PostgreSQL, auth, storage)
• Testing: Playwright (E2E)
• Linting: ESLint
• Deployment: GitHub Pages via gh-pages
• CI/CD: GitHub Actions (.github/workflows/)
• Analysis: Custom tools (madge, jscpd, ts-prune, depcheck)

Tool Permission Matrix

Design Principles

1. Least Privilege: Agents only get tools they absolutely need
2. Single Responsibility: Each agent has one clear purpose
3. No Overlap: Agent responsibilities don't overlap or duplicate
4. Report First: Agents report issues rather than auto-fixing complex problems
5. Bash-Only Default: If agent only needs command output, it only gets Bash
6. Progressive Disclosure: Start with least permissions, add only when necessary

Extending Agents

To add new agents:

1. Create .claude/agents/your-agent.md with YAML frontmatter
2. Define minimal tool permissions (start with least, add only if needed)
3. Write clear responsibilities and examples
4. Update this registry table
5. Test agent invocation
6. Document in tool permission matrix

Notes

• Agents DO NOT modify application source code outside their specific mandates
• Agents operate only within their designated directories
• All agents provide file:line references for issues found
• Agents prioritize reporting over auto-fixing complex issues
• Permission tightening: Agents can only use tools explicitly listed in their frontmatter