WhylLima Subagents

Agentes de IA especializados para o projeto WhylLima. Cada agente é focado em uma tarefa específica para otimizar uso de tokens e dar suporte preciso ao código.

Hub: github.com/whyllima/whyl-subagents

---

Plugins disponíveis

| Plugin | Categoria | Descrição | |--------|-----------|-----------| | whyll-agents | Laravel | Builders e fixers: full-stack, model, API, endpoint, test, job, resource, seeder, event, JWT, ACL (config-driven + privilege escalation prevention), audit, AI agents, MCP servers, quality-checker e fixers. Laravel 13, PHP 8.3+, PHP attributes, domain folders, versioned API, Service-Repository. | | whyll-agents-front | Front-end | Builders para Nuxt 4: project, page, component, store, composable, API service, i18n, layout, plugin, middleware, testing, quality-checker. Stack: Vue 3, Pinia, Axios, PrimeVue 4 (design tokens), Tailwind, TypeScript, i18n. | | whyll-agents-biz | Business & Product | product-manager, ux-researcher, business-analyst, content-marketer, project-manager, scrum-master, customer-success, sales-engineer, technical-writer, legal-advisor, wordpress-master. Discovery pipeline: ideia → problema → requisitos → posicionamento. |

---

Quick Start

No Claude Code

# Adicionar marketplace
/plugin marketplace add /Users/whyl/.claude/plugins/marketplaces/whyl-subagents

# Instalar plugins
/plugin install whyll-agents@whyl-subagents
/plugin install whyll-agents-front@whyl-subagents
/plugin install whyll-agents-biz@whyl-subagents

# Usar agente Laravel
@whyll-agents:full-stack-specialist Create a complete feature for "Categories"

# Usar agente Front-end (Nuxt)
@whyll-agents-front:nuxt-project-builder Create a Nuxt project with Pinia, Axios, PrimeVue, and i18n
@whyll-agents-front:component-builder Create UserProfileCard in dashboard domain
@whyll-agents-front:store-builder Create store for managing notifications

# Usar agente Business & Product
@whyll-agents-biz:product-manager Define product idea and value hypothesis

---

Agentes disponíveis (whyll-agents – Laravel)

Builders (criar componentes)

| Agente | Propósito | Linhas | ~Tokens | |--------|-----------|--------|---------| | full-stack-specialist | Feature completa do zero | 197 | ~500 | | model-builder | Só estrutura de dados | 63 | ~160 | | api-layer-builder | API para model existente | 182 | ~450 | | endpoint-builder | Só rotas | 95 | ~240 | | test-builder | Testes PHPUnit | 152 | ~380 | | job-builder | Jobs em fila | 55 | ~140 | | resource-builder | Transformação JSON | 57 | ~140 | | seeder-builder | Dados de teste/dev | 68 | ~170 | | event-builder | Eventos e broadcasting | 79 | ~200 | | jwt-auth-builder | Autenticação JWT completa | 587 | ~1.5k | | acl-builder | Sistema ACL Modular (3 níveis) | 723 | ~1.8k | | audit-builder | Auditoria de Models | 421 | ~1k | | ai-agent-builder | AI Agents (laravel/ai) | ~150 | ~375 | | mcp-server-builder | MCP Servers (laravel/mcp) | ~140 | ~350 |

Qualidade e Fixers (auditar e corrigir)

| Agente | Propósito | Linhas | ~Tokens | |--------|-----------|--------|---------| | quality-checker | Audita código e gera prompts | 131 | ~330 | | controller-fixer | Remove lógica do Controller | 88 | ~220 | | service-fixer | Garante Repository e Resources | 75 | ~190 | | repository-fixer | Converte DB:: para Model | 61 | ~150 | | model-fixer | Traits, UUID e relacionamentos | 57 | ~140 | | formrequest-fixer | Validação create/update | 50 | ~125 | | resource-fixer | Campos explícitos, datas ISO | 54 | ~135 |

Resumo de Tokens (Laravel)

| Categoria | Agentes | Total Linhas | ~Tokens | |-----------|---------|--------------|---------| | Builders | 14 | ~2.970 | ~7.4k | | Fixers | 7 | ~520 | ~1.3k | | Quality | 1 | ~130 | ~330 | | Total | 22 | ~3.620 | ~9k |

> Nota: Estimativa baseada em ~2.5 tokens/linha de markdown/código.

---

Agentes disponíveis (whyll-agents-front – Front-end Nuxt 4)

Builders

| Agente | Propósito | |--------|-----------| | nuxt-project-builder | Projeto Nuxt 4 do zero com PrimeVue 4 design tokens | | page-builder | Páginas com file-based routing, layout props, route groups | | component-builder | Componentes Vue SFC com PrimeVue 4 (Select, DatePicker, Tabs) | | store-builder | Pinia stores com SSR safety e undefined defaults | | composable-builder | Composables + shared/utils/ + createUseFetch | | api-service-builder | Camada API: Axios → Proxy → Nitro + createUseFetch | | i18n-manager | Locales e traduções | | layout-builder | Layouts, Drawer, Menu, dark mode via .p-dark | | plugin-builder | Plugins Nuxt com usePreset/updatePreset | | middleware-builder | Route middleware, auth guards, route groups | | testing-builder | Vitest + Vue Test Utils + Pinia testing |

Qualidade

| Agente | Propósito | |--------|-----------| | quality-checker | Audita código Nuxt 4 + PrimeVue 4 compliance |

Convenções (Front-end)

| Convenção | Padrão | |-----------|--------| | SFC Order | <script setup> → <template> → <style scoped> | | PrimeVue 4 | Auto-importado via @primevue/nuxt-module. Utilities: FilterMatchMode de @primevue/core/api | | PrimeVue 4 Names | <Select>, <DatePicker>, <ToggleSwitch>, <Drawer>, <Popover>, <Tabs> | | PrimeVue 4 Theme | Design Tokens via presets (Aura, Lara). Sem CSS imports. Dark mode .p-dark | | PrimeVue 4 Fluid | fluid prop ou <Fluid> wrapper (não .p-fluid class) | | Nuxt 4 Dir | app/ como srcDir, shared/ para cross-context, #server alias | | Data Fetching | shallowRef por padrão, undefined defaults, singleton por key | | Error Handling | .then().catch() para async. try/catch só para ops síncronas críticas | | SSR Safety | import.meta.client, <ClientOnly>, typeof window !== 'undefined' | | i18n | useI18n() + t() para todo texto. Estratégia no_prefix | | State | Pinia stores para estado complexo; composables para lógica UI | | Styling | Tailwind + :deep() para PrimeVue overrides. CSS layers para coexistência | | Path Alias | @/ → app/, #shared → shared/, #server → server/ |

---

Agentes disponíveis (whyll-agents-biz – Business & Product)

| Agente | Papel no pipeline / Uso | |--------|---------------------------| | product-manager | Gera e valida a ideia (o quê e por quê) | | ux-researcher | Confirma se o problema é real (dor do usuário) | | business-analyst | Traduz a ideia em requisitos e viabilidade | | content-marketer | Posicionamento e narrativa | | project-manager | Planejamento e entrega | | scrum-master | Processo ágil | | customer-success-manager | Retenção e sucesso do cliente | | sales-engineer | Demos e adoção técnica | | technical-writer | Documentação | | legal-advisor | Conformidade e riscos | | wordpress-master | Conteúdo e WordPress |

Discovery pipeline: product-manager → ux-researcher → business-analyst → content-marketer. Detalhes em categories/03-business-product/README.md e DISCOVERY-PIPELINE.md.

---

Arquitetura (Laravel)

Controller (sem lógica) → Service (toda lógica) → Repository (acesso via Model) → Model
                                                                              ↓
Resposta sempre via Resource ←────────────────────────────────────────────────

Regras:

• Controller: só delega para Service; sem try-catch, sem Log, sem queries.
• Service: toda lógica de negócio; sempre retorna Resource.
• Repository: usa sempre Model (nunca facade DB).
• Resource: todas as respostas da API passam por Resource.

---

Detalhes dos agentes

full-stack-specialist

Quando usar: Criar uma feature nova do zero (banco + API).

Cria (nessa ordem): 1. Migration (UUID como PK, soft deletes, índices) 2. Model (HasFactory, HasUuids, SoftDeletes, AutoIncrementId, Auditable) 3. Repository (extends App\Repositories\Repository, queries via Model) 4. Service (extends App\Services\Service, retorna Resources) 5. Form Request (validação store/update com UUID ignore) 6. Controller (só delega para Service, sem lógica) 7. Resource e Collection 8. API Routes (Route::controller())

Exemplo:

@whyll-agents:full-stack-specialist Create a complete feature for "Categories" with name, slug, description, and status.

---

model-builder

Quando usar: Só estrutura de banco, sem camada de API.

Cria: Migration, Model (traits e relacionamentos).

Não cria: Repository, Service, Controller, Routes, Tests.

Exemplo:

@whyll-agents:model-builder Create migration and model for "Tags" with name, slug, color, and entity_uuid (belongsTo Entity).

---

api-layer-builder

Quando usar: Model já existe e precisa expor via API.

Pré-requisitos: Migration e Model existentes.

Cria: Repository, Service, Form Request, Controller, Resource, Collection, Routes.

Não cria: Migration, Model, Tests.

Exemplo:

@whyll-agents:api-layer-builder Create API layer for the existing Tag model with CRUD and getByEntity custom action.

---

endpoint-builder

Quando usar: Controller existe e só falta definir rotas.

Pré-requisitos: Controller e métodos existentes.

Cria: Rotas em routes/api.php.

Exemplo:

@whyll-agents:endpoint-builder Add routes for TagController with methods: index, show, store, update, destroy, getByEntity.

---

test-builder

Quando usar: Endpoints existem e precisa de testes.

Pré-requisitos: Controller, rotas e factory existentes.

Cria: Feature Tests (PHPUnit) – CRUD, validação, auth (401).

Importante: Usa DatabaseTransactions (não limpa o banco).

Exemplo:

@whyll-agents:test-builder Create feature tests for TagController covering all CRUD operations and getByEntity.

---

job-builder

Quando usar: Processamento em background com filas.

Cria: Jobs (ShouldQueue), config Horizon, logging no canal jobs.

Exemplo:

@whyll-agents:job-builder Create a job to sync entities with external API, with retry logic and Horizon monitoring.

---

resource-builder

Quando usar: Transformar models em respostas JSON padronizadas.

Pré-requisitos: Model existente.

Cria: JsonResource, ResourceCollection (com whenLoaded, whenCounted, datas ISO).

Exemplo:

@whyll-agents:resource-builder Create EntityResource and EntityCollection with category, tags relationships, and comments_count.

---

seeder-builder

Quando usar: Dados de teste ou desenvolvimento.

Pré-requisitos: Model e relacionamentos existentes.

Cria: Factory (definition + states), Seeder.

Exemplo:

@whyll-agents:seeder-builder Create EntityFactory with states (published, draft, featured) and EntitySeeder with 50 sample records.

---

event-builder

Quando usar: Eventos de domínio, listeners ou broadcasting em tempo real.

Cria: Events (normais e broadcastable), Listeners (sync e queued), autorização de canais (routes/channels.php).

Exemplo:

@whyll-agents:event-builder Create EntityCreated, EntityUpdated events with broadcasting to private channel and notification listener.

---

jwt-auth-builder

Quando usar: Configurar autenticação JWT com single-session, refresh token, password reset.

Cria: AuthController, AuthService, AuthRepository, JwtMiddleware, FormRequests, Resources.

Detecta ACL: Verifica se existe ACL Modular ou Simple para incluir roles/permissions no me().

Exemplo:

@whyll-agents:jwt-auth-builder Setup JWT authentication with password reset and profile update

---

acl-builder

Quando usar: Configurar sistema de permissões modular com três níveis: User → Role → Module → Permission.

Arquitetura:

User ──has── Role ──has── Module ──has── Permission
              │             │
              └─────────────┘
         role_modules_permissions

Cria:

• Migrations (modules, model_has_permissions, role_modules_permissions)
• Models (Module, ModelHasPermission, RoleModulesPermission, Role, Permission)
• Traits (HasNameLookup, HasModulePermission)
• Middleware (ModelAndPermissionMiddleware)
• Exception (NotLoggedInException)
• Seeders (PermissionSeeder, ModuleSeeder, RoleSeeder)

Formato de permissão: {action}-{module} (ex: show-rule, index-user)

Uso em Controller:

$this->middleware('model_permission:show-entity')->only(['show']);
$this->middleware('model_permission:index-entity')->only(['index']);

Exemplo:

@whyll-agents:acl-builder Setup modular ACL system with modules: user, role, entity, campaign

---

audit-builder

Quando usar: Configurar sistema de auditoria ou verificar se models estão configurados para audit.

Cria:

• Config audit.php customizado
• Migration audits com UUID
• Resolvers (IpAddress, UserAgent, Url)
• Resources (AuditResource, AuditCollection)

Também verifica:

• Models sem interface ContractAuditable
• Models sem trait Auditable
• Models com password sem $auditExclude

Exemplos:

# Setup completo
@whyll-agents:audit-builder Setup auditing system

# Verificar models
@whyll-agents:audit-builder Check audit configuration in all models

---

quality-checker

Quando usar: Auditar uma feature ou arquivos para ver se seguem o padrão.

Faz: Escaneia controllers, services, repositories, models, form requests e resources; identifica violações; gera prompts prontos para copiar e usar com os fixers.

Exemplo:

@whyll-agents:quality-checker Audit Entity feature

Saída típica: Lista de componentes com problemas + prompts no formato:

@whyll-agents:controller-fixer Fix EntityController
File: app/Http/Controllers/EntityController.php
Issues: try-catch blocks, Log:: calls, direct queries

---

Fixers (controller-fixer, service-fixer, repository-fixer, model-fixer, formrequest-fixer, resource-fixer)

Quando usar: Depois do quality-checker ou quando souber qual arquivo está fora do padrão.

Uso: Cole o prompt gerado pelo quality-checker (ou monte um semelhante com arquivo e issues).

Exemplos:

@whyll-agents:controller-fixer Fix EntityController - remove logic, delegate to Service. File: app/Http/Controllers/EntityController.php

@whyll-agents:repository-fixer Fix EntityRepository - convert DB facade to Model queries. File: app/Repositories/EntityRepository.php

---

Guia de decisão

Laravel (whyll-agents)

Precisa criar algo?
│
├── Feature nova do zero         → full-stack-specialist
├── Só banco de dados            → model-builder
├── Model existe, precisa de API → api-layer-builder
├── Controller existe, só rotas  → endpoint-builder
├── API existe, precisa testes   → test-builder
├── Processamento em background  → job-builder
├── Transformação JSON           → resource-builder
├── Dados de teste/dev           → seeder-builder
├── Eventos/real-time            → event-builder
├── Autenticação JWT             → jwt-auth-builder
├── Sistema de permissões        → acl-builder
├── Auditoria de models          → audit-builder
├── AI Agents (laravel/ai)       → ai-agent-builder
└── MCP Servers (laravel/mcp)    → mcp-server-builder

Precisa auditar/corrigir?
│
├── Auditar feature              → quality-checker (gera prompts)
└── Corrigir componente          → controller-fixer | service-fixer
                                   repository-fixer | model-fixer
                                   formrequest-fixer | resource-fixer

Front-end (whyll-agents-front)

Projeto novo do zero             → nuxt-project-builder
Nova página/rota                 → page-builder
Novo componente visual           → component-builder
Gerenciamento de estado          → store-builder
Lógica reutilizável/UI           → composable-builder
Integração com API externa       → api-service-builder
Traduções/idiomas                → i18n-manager
Layout/sidebar/menu/dark mode    → layout-builder
Plugin Vue/Nuxt                  → plugin-builder
Auth guards/redirects            → middleware-builder
Testes unitários/componente      → testing-builder
Auditar código Nuxt/PrimeVue     → quality-checker

---

Stack do projeto

Back-end (Laravel)

• PHP: 8.3+
• Laravel: v13
• Auth: JWT (tymon/jwt-auth) ou Sanctum v4
• Queue: Horizon v5
• Real-time: Reverb v1
• Performance: Octane v2
• Code Style: Pint v1
• Testing: PHPUnit ^12 / Pest ^4
• Auditing: owen-it/laravel-auditing
• AI: laravel/ai (AI SDK), laravel/mcp (MCP servers)

Front-end (Nuxt)

• Nuxt: 4.4+ (SSR habilitado, app/ srcDir, shared/ directory)
• Vue: 3.5+ (Vue Router v5)
• State: Pinia 2.3+
• HTTP: Axios 1.13+ / createUseFetch (Nuxt 4 native)
• UI: PrimeVue 4.5+ (Design Tokens, @primeuix/themes)
• CSS: Tailwind CSS 4+ (CSS layers com PrimeVue)
• i18n: @nuxtjs/i18n 10+
• Language: TypeScript 5.5+ (noUncheckedIndexedAccess: true)
• Testing: Vitest + @nuxt/test-utils + Vue Test Utils

---

Convenções

| Convenção | Padrão | |-----------|--------| | Primary Key | UUID, coluna uuid | | Column Order | id (unsignedBigInteger) primeiro, uuid (PK) segundo | | Auto Increment | DB::statement('ALTER TABLE x MODIFY id ... AUTO_INCREMENT UNIQUE') | | Foreign Keys | {entity}_uuid | | Model Config | PHP Attributes: #[Table(key: 'uuid', ...)], #[Fillable([...])] | | Traits do Model | HasFactory, HasUuids, SoftDeletes | | Folder Structure | Domain-based: Controllers/{Domain}/, Models/{Domain}/, etc. | | Services | Estendem App\Services\Service | | Repositories | Estendem App\Repositories\Repository, nunca usam DB:: | | Controller | DI constructor, sem lógica; só delega para Service | | Respostas | Sempre via Resource, Collection com #[Collects] | | Rotas | Versionadas em routes/api/v1.php, permission middleware per-route | | Documentação | PHPDoc em inglês, sem comentários inline | | Formatação | vendor/bin/pint --dirty |

---

Estrutura de arquivos

whyl-subagents/
├── README.md
├── .claude/
│   └── settings.local.json
├── .claude-plugin/
│   └── marketplace.json
└── categories/
    ├── README.md
    ├── 01-laravel/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── full-stack-specialist.md
    │   ├── model-builder.md
    │   ├── api-layer-builder.md
    │   ├── endpoint-builder.md
    │   ├── test-builder.md
    │   ├── job-builder.md
    │   ├── resource-builder.md
    │   ├── seeder-builder.md
    │   ├── event-builder.md
    │   ├── jwt-auth-builder.md
    │   ├── acl-builder.md
    │   ├── audit-builder.md
    │   ├── ai-agent-builder.md
    │   ├── mcp-server-builder.md
    │   ├── quality-checker.md
    │   ├── controller-fixer.md
    │   ├── service-fixer.md
    │   ├── repository-fixer.md
    │   ├── model-fixer.md
    │   ├── formrequest-fixer.md
    │   └── resource-fixer.md
    ├── 02-front-end/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── nuxt-project-builder.md
    │   ├── page-builder.md
    │   ├── component-builder.md
    │   ├── store-builder.md
    │   ├── composable-builder.md
    │   ├── api-service-builder.md
    │   ├── i18n-manager.md
    │   ├── layout-builder.md
    │   ├── plugin-builder.md
    │   ├── middleware-builder.md
    │   ├── testing-builder.md
    │   └── quality-checker.md
    └── 03-business-product/
        ├── .claude-plugin/
        │   └── plugin.json
        ├── README.md
        ├── DISCOVERY-PIPELINE.md
        ├── product-manager.md
        ├── ux-researcher.md
        ├── business-analyst.md
        ├── content-marketer.md
        ├── project-manager.md
        ├── scrum-master.md
        ├── customer-success-manager.md
        ├── sales-engineer.md
        ├── technical-writer.md
        ├── legal-advisor.md
        └── wordpress-master.md

---

Comandos úteis

# Laravel
php artisan make:migration create_entities_table --no-interaction
php artisan make:model Entity -fs --no-interaction
php artisan make:controller EntityController --api --no-interaction
php artisan make:request EntityRequest --no-interaction
php artisan make:job ProcessEntityJob --no-interaction
php artisan make:test EntityControllerTest --no-interaction
php artisan make:resource EntityResource --no-interaction
php artisan make:resource EntityCollection --collection --no-interaction
php artisan make:factory EntityFactory --model=Entity --no-interaction
php artisan make:seeder EntitySeeder --no-interaction
php artisan make:event EntityCreated --no-interaction
php artisan make:listener SendEntityNotification --event=EntityCreated --no-interaction

# Code Style
vendor/bin/pint --dirty

# Testing
php artisan test --filter=EntityControllerTest
php artisan test --parallel

# Queue
php artisan horizon
php artisan horizon:status

# Reverb (WebSockets)
php artisan reverb:start
php artisan reverb:start --debug

# Seeding
php artisan db:seed
php artisan db:seed --class=EntitySeeder

---

License

MIT

---

Hub: github.com/whyllima/whyl-subagents