flyer-crawler.projectium.com/docs/subagents/OVERVIEW.md

# Claude Code Subagent System Overview

This document provides a comprehensive guide to the subagent system used in the Flyer Crawler project. Subagents are specialized AI assistants that focus on specific domains, allowing for more targeted and effective development workflows.

## What Are Subagents?

Subagents are task-specific Claude instances that can be launched using the `Task` tool in Claude Code. Each subagent has specialized knowledge and instructions tailored to a particular domain, such as coding, testing, database work, or DevOps.

**Why Use Subagents?**

- **Focused Expertise**: Each subagent has domain-specific knowledge and instructions
- **Better Context Management**: Subagents can work on isolated tasks without polluting the main conversation
- **Parallel Work**: Multiple subagents can work on independent tasks simultaneously
- **Consistency**: Subagents follow project-specific patterns and conventions automatically

## Available Subagents

The following subagents are available for use in this project:

### Core Development

| Subagent  | Purpose                                                         | When to Use                                                      |
| --------- | --------------------------------------------------------------- | ---------------------------------------------------------------- |
| **plan**  | Design implementation plans, identify files, analyze trade-offs | Starting new features, major refactoring, architecture decisions |
| **coder** | Write and modify production Node.js/TypeScript code             | Implementing features, fixing bugs, writing new modules          |

### Testing and Quality

| Subagent          | Purpose                                                           | When to Use                                          |
| ----------------- | ----------------------------------------------------------------- | ---------------------------------------------------- |
| **tester**        | Adversarial testing: edge cases, race conditions, vulnerabilities | Finding bugs, security testing, stress testing       |
| **testwriter**    | Create comprehensive tests for features and fixes                 | Writing unit tests, integration tests, test coverage |
| **code-reviewer** | Review code quality, security, best practices                     | Code review, PR reviews, architecture review         |

### Database and Infrastructure

| Subagent            | Purpose                                                   | When to Use                                                    |
| ------------------- | --------------------------------------------------------- | -------------------------------------------------------------- |
| **db-dev**          | Schemas, queries, migrations, optimization, N+1 problems  | Database development, query optimization, schema changes       |
| **db-admin**        | PostgreSQL/Redis admin, security, backups, infrastructure | Database administration, performance tuning, backup strategies |
| **devops**          | Containers, services, CI/CD pipelines, deployments        | Deployment issues, container configuration, CI/CD pipelines    |
| **infra-architect** | Resource optimization: RAM, CPU, disk, storage            | Capacity planning, performance optimization, cost reduction    |

### Specialized Technical

| Subagent                    | Purpose                                                    | When to Use                                               |
| --------------------------- | ---------------------------------------------------------- | --------------------------------------------------------- |
| **bg-worker**               | Background jobs: PM2 workers, BullMQ queues, async tasks   | Queue management, worker debugging, job scheduling        |
| **ai-usage**                | LLM APIs (Gemini, Claude), prompt engineering, AI features | AI integration, prompt optimization, Gemini API issues    |
| **security-engineer**       | Security audits, vulnerability scanning, OWASP, pentesting | Security reviews, vulnerability assessments, compliance   |
| **log-debug**               | Production errors, observability, Bugsink/Sentry analysis  | Debugging production issues, log analysis, error tracking |
| **integrations-specialist** | Third-party services, webhooks, external APIs              | External API integration, webhook implementation          |

### Frontend and Design

| Subagent                | Purpose                                                      | When to Use                                                   |
| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------------- |
| **frontend-specialist** | UI components, Neo-Brutalism, Core Web Vitals, accessibility | Frontend development, performance optimization, accessibility |
| **uiux-designer**       | UI/UX decisions, component design, Neo-Brutalism compliance  | Design decisions, user experience improvements                |

### Documentation and Planning

| Subagent             | Purpose                                                     | When to Use                                                |
| -------------------- | ----------------------------------------------------------- | ---------------------------------------------------------- |
| **documenter**       | User docs, API specs, feature documentation                 | Writing documentation, API specs, user guides              |
| **describer-for-ai** | Technical docs for AI: ADRs, system overviews, context docs | Writing ADRs, technical specifications, context documents  |
| **planner**          | Break down features, roadmaps, scope management             | Project planning, feature breakdown, roadmap development   |
| **product-owner**    | Feature requirements, user stories, validation, backlog     | Requirements gathering, user story writing, prioritization |

### Support

| Subagent                         | Purpose                                  | When to Use                                          |
| -------------------------------- | ---------------------------------------- | ---------------------------------------------------- |
| **tools-integration-specialist** | Bugsink, Gitea, OAuth, operational tools | Tool configuration, OAuth setup, operational tooling |

## How to Launch a Subagent

Subagents are launched using the `Task` tool in Claude Code. Simply ask Claude to use a specific subagent for a task:

```
"Use the coder subagent to implement the new store search feature"
```

Or:

```
"Launch the db-dev subagent to optimize the flyer items query"
```

Claude will automatically invoke the appropriate subagent with the relevant context.

## Subagent Selection Guide

### Which Subagent Should I Use?

**For Writing Code:**

- New features or modules: `coder`
- Complex architectural changes: `plan` first, then `coder`
- Database-related code: `db-dev`
- Frontend components: `frontend-specialist`
- Background job code: `bg-worker`

**For Testing:**

- Writing new tests: `testwriter`
- Finding edge cases and bugs: `tester`
- Reviewing test coverage: `code-reviewer`

**For Infrastructure:**

- Container issues: `devops`
- CI/CD pipelines: `devops`
- Database administration: `db-admin`
- Performance optimization: `infra-architect`

**For Debugging:**

- Production errors: `log-debug`
- Database issues: `db-admin` or `db-dev`
- AI/Gemini issues: `ai-usage`

**For Documentation:**

- API documentation: `documenter`
- Architecture decisions: `describer-for-ai`
- Planning and requirements: `planner` or `product-owner`

## Best Practices

### 1. Start with Planning

For complex features, always start with the `plan` subagent to:

- Identify affected files
- Understand architectural implications
- Break down the work into manageable tasks

### 2. Use Specialized Subagents for Specialized Work

Avoid using `coder` for database migrations. Use `db-dev` instead - it understands:

- The project's migration patterns
- Schema synchronization requirements
- PostgreSQL-specific optimizations

### 3. Let Subagents Follow Project Conventions

All subagents are pre-configured with knowledge of project conventions:

- ADR patterns (see [docs/adr/index.md](../adr/index.md))
- Repository pattern standards (ADR-034)
- Service layer architecture (ADR-035)
- Testing standards (ADR-010)

### 4. Combine Subagents for Complex Tasks

Some tasks benefit from multiple subagents:

1. **New API endpoint**: `plan` -> `coder` -> `testwriter` -> `code-reviewer`
2. **Database optimization**: `db-dev` -> `tester` -> `infra-architect`
3. **Security fix**: `security-engineer` -> `coder` -> `testwriter`

### 5. Always Run Tests in the Dev Container

Regardless of which subagent you use, remember:

> **ALL tests MUST be run in the dev container (Linux environment)**

The subagents know this, but as a developer, ensure you verify test results in the correct environment:

```bash
podman exec -it flyer-crawler-dev npm run test:unit
```

## Subagent Communication

Subagents can pass information back to the main conversation and to each other through:

1. **Direct Output**: Results and recommendations returned to the conversation
2. **File Changes**: Code, documentation, and configuration changes
3. **Todo Lists**: Task tracking and progress updates

## Related Documentation

- [CODER-GUIDE.md](./CODER-GUIDE.md) - Working with the coder subagent
- [TESTER-GUIDE.md](./TESTER-GUIDE.md) - Testing strategies and patterns
- [DATABASE-GUIDE.md](./DATABASE-GUIDE.md) - Database development workflows
- [DEVOPS-GUIDE.md](./DEVOPS-GUIDE.md) - DevOps and deployment workflows
- [../adr/index.md](../adr/index.md) - Architecture Decision Records
- [../TESTING.md](../TESTING.md) - Testing guide

## Troubleshooting

### Subagent Not Available

If a subagent fails to launch, it may be due to:

- Incorrect subagent name (check the list above)
- Network or API issues
- Context length limitations

### Subagent Gives Incorrect Advice

All subagents follow the CLAUDE.md instructions. If advice seems wrong:

1. Verify the project context is correct
2. Check if the advice conflicts with an ADR
3. Provide additional context to the subagent

### Subagent Takes Too Long

For complex tasks, subagents may take time. Consider:

- Breaking the task into smaller pieces
- Using the `plan` subagent first to scope the work
- Running simpler queries first to verify understanding