Agents Documentation
Portfolio Project: omer-akben AI-powered portfolio Framework: Claude Code with specialized agents Version: Phase 1 - Foundation Last Updated: 2025-11-08
Table of Contents
- Overview
- Agent Catalog
- Agent Selection Guide
- Collaboration Patterns
- Handoff Procedures
- Quality Standards
Overview
The omer-akben project uses a specialized agent architecture where each agent is an expert in a specific domain. This approach ensures:
- Deep Expertise: Each agent masters its domain
- Consistent Patterns: Agents follow established project conventions
- Quality Focus: Every agent enforces quality gates
- Clear Ownership: Domain boundaries prevent overlap
Architecture Principles
- Specialization over Generalization: Each agent has a narrow, deep focus
- Skills Integration: Agents leverage shared skills for common patterns
- Project Awareness: All agents understand the portfolio context
- Quality Gates: Every agent ensures code meets production standards
- Collaboration: Agents can hand off to each other when needed
Agent + Skills Model
Agent (Strategic Layer)
├── Understands project context
├── Makes architectural decisions
├── Follows established patterns
└── Uses Skills (Tactical Layer)
├── Provides implementation patterns
├── Shares common solutions
├── Documents best practices
└── Reduces duplication
```typescript
---
## Agent Catalog
### 1. Next.js Architect
**File:** `.claude/agents/nextjs-architect.md`
**Model:** Sonnet
**Tools:** Read, Write, Edit, Bash, Grep, Glob
#### Purpose
Expert in Next.js 15, React 19, App Router, server components, and TypeScript. The go-to agent for all Next.js architecture decisions, component patterns, routing, data fetching, and SSR/hydration issues.
#### Core Expertise
- **Next.js 15**: App Router, parallel routes, intercepting routes, server actions
- **React 19**: Actions, useActionState, useOptimistic, use() hook
- **TypeScript**: Strict typing, generics, Zod validation
- **Patterns**: Server vs client components, hydration-safe patterns, data fetching
#### When to Use
✅ Use nextjs-architect for:
- Creating new pages or routes
- Implementing server/client components
- Fixing hydration mismatches
- Data fetching patterns
- Route organization
- Metadata and SEO
- Next.js build optimization
❌ Don't use for:
- UI styling (use ui-ux-developer)
- Deployment issues (use deployment-engineer)
- Testing (use test-engineer)
#### Key Skills Used
- `hydration-safety-skill` - SSR/CSR patterns
- `data-architecture-skill` - Data organization with facts.ts
- `brightness-system-skill` - Ensure 8-mode support
- `testing-and-quality-gates-skill` - Component testing
#### Example Invocation
```typescript
User: "Add a new blog page with SSR data fetching"
→ Use nextjs-architect
```typescript
---
### 2. UI/UX Developer
**File:** `.claude/agents/ui-ux-developer.md`
**Model:** Sonnet
**Tools:** Read, Write, Edit, Bash, Grep
#### Purpose
Expert in Tailwind CSS 4, shadcn/ui, responsive design, accessibility, and 8-brightness-mode theming. The specialist for all UI components, styling, layouts, and user experience improvements.
#### Core Expertise
- **Tailwind CSS 4**: Modern utilities, custom properties, responsive design
- **shadcn/ui**: 40+ components, Radix UI primitives, customization
- **Design System**: 8 brightness modes, CSS custom properties
- **Accessibility**: WCAG 2.1 AA, semantic HTML, ARIA, keyboard navigation
#### When to Use
✅ Use ui-ux-developer for:
- Creating UI components
- Styling and layout fixes
- Responsive design implementation
- Accessibility improvements
- shadcn/ui component integration
- Brightness mode testing
- Icon usage (Lucide)
❌ Don't use for:
- Next.js routing (use nextjs-architect)
- API logic (use ai-sdk-specialist)
- Deployment (use deployment-engineer)
#### Key Skills Used
- `brightness-system-skill` - CRITICAL: All UI must support 8 modes
- `hydration-safety-skill` - Client-side interactive components
- `testing-and-quality-gates-skill` - UI component testing
- `bundle-optimization-skill` - Icon imports
#### Example Invocation
```typescript
User: "Make the sidebar responsive and add dark mode support"
→ Use ui-ux-developer
```typescript
---
### 3. Deployment Engineer
**File:** `.claude/agents/deployment-engineer.md`
**Model:** Sonnet
**Tools:** Read, Write, Edit, Bash, Grep
#### Purpose
Expert in Vercel deployment, CI/CD pipelines, GitHub Actions, and production infrastructure. Ensures zero-downtime deployments and robust production systems.
#### Core Expertise
- **Vercel Platform**: Deployments, preview environments, edge functions
- **GitHub Actions**: 6 quality gates workflow, auto-merge
- **Production Monitoring**: Sentry, PostHog, performance tracking
- **Security**: Environment variables, headers, secrets management
#### When to Use
✅ Use deployment-engineer for:
- Deployment issues
- CI/CD pipeline configuration
- Environment variable management
- Quality gate failures
- Production monitoring setup
- Vercel configuration
- Branch strategy questions
❌ Don't use for:
- Code implementation (use appropriate specialist)
- UI fixes (use ui-ux-developer)
- Test writing (use test-engineer)
#### Key Skills Used
- `git-workflow-and-deployment-skill` - CRITICAL: Branch strategy
- `environment-configuration-skill` - Secrets management
- `testing-and-quality-gates-skill` - CI/CD gates
#### Example Invocation
```typescript
User: "Deploy failed on the build step"
→ Use deployment-engineer
```typescript
---
### 4. Test Engineer
**File:** `.claude/agents/test-engineer.md`
**Model:** Sonnet
**Tools:** Read, Write, Edit, Bash, Grep
#### Purpose
Expert in Vitest unit testing and Playwright E2E testing. Ensures the portfolio maintains high-quality with 776+ unit tests and 66 E2E tests passing consistently.
#### Core Expertise
- **Vitest**: Component testing, mocking, async patterns, coverage
- **Playwright**: Browser automation, cross-browser testing, visual regression
- **Testing Strategy**: TDD, behavior-driven testing, integration testing
- **Hydration Testing**: SSR-safe test patterns for Next.js
#### When to Use
✅ Use test-engineer for:
- Writing new tests
- Debugging test failures
- Improving test coverage
- Test infrastructure setup
- TDD workflows
- E2E test scenarios
- Quality gate failures
❌ Don't use for:
- Production code (use appropriate specialist)
- Deployment (use deployment-engineer)
- UI design (use ui-ux-developer)
#### Key Skills Used
- `testing-and-quality-gates-skill` - CRITICAL: Complete testing patterns
- `brightness-system-skill` - Test all 8 brightness modes
- `hydration-safety-skill` - Test SSR/CSR properly
#### Example Invocation
```typescript
User: "Unit tests are failing after I added a new feature"
→ Use test-engineer
```typescript
---
### 5. AI SDK Specialist
**File:** `.claude/agents/ai-sdk-specialist.md`
**Model:** Sonnet
**Tools:** Read, Write, Edit, Bash, Grep
#### Purpose
Expert in Vercel AI SDK v5, Mastra framework, LLM integrations, and AI agent tool development. The authority on AI chat implementation, tool creation, streaming responses, and LLM configuration.
#### Core Expertise
- **Vercel AI SDK v5**: streamText(), generateText(), tool calling
- **Mastra Framework**: Agent creation, tool definition, memory systems
- **LLM Integrations**: XAI Grok (primary), OpenAI (fallback), embeddings
- **Tool Development**: Schema definition, API routes, validation
#### When to Use
✅ Use ai-sdk-specialist for:
- Creating AI tools
- Fixing AI agent bugs
- LLM integration issues
- Streaming response problems
- Tool schema design
- Memory system implementation
- Model configuration
❌ Don't use for:
- UI components (use ui-ux-developer)
- Deployment (use deployment-engineer)
- Next.js patterns (use nextjs-architect)
#### Key Skills Used
- `aI-agent-implementation-skill` - CRITICAL: Mastra patterns
- `environment-configuration-skill` - API key management
- `redis-integration-skill` - Caching and rate-limiting
- `testing-and-quality-gates-skill` - Testing AI tools
#### Example Invocation
```typescript
User: "Create a new tool for the AI agent that fetches project details"
→ Use ai-sdk-specialist
```typescript
---
### 6. Mastra Optimization Researcher
**File:** `.claude/agents/mastra-optimization-researcher.md`
**Model:** Sonnet
**Description:** Elite Mastra.ai implementation specialist
#### Purpose
Researches official Mastra.ai documentation and optimizes Mastra-based agent architectures. Proactively analyzes current setup and suggests improvements based on official patterns.
#### Core Expertise
- **Documentation Research**: Systematic analysis of mastra.ai/docs
- **Implementation Analysis**: Identify anti-patterns and suboptimal code
- **Optimization**: Architecture refactoring, performance improvements
- **Context-Aware**: Understands existing agent/tool architecture
#### When to Use
✅ Use mastra-optimization-researcher for:
- Optimizing Mastra implementation
- Researching Mastra best practices
- Reviewing agent architecture
- Tool integration improvements
- Memory system optimization
- Migration to newer Mastra patterns
❌ Don't use for:
- Non-Mastra AI code (use ai-sdk-specialist)
- General optimization (use appropriate specialist)
- Deployment (use deployment-engineer)
#### Key Research Areas
- Agent architecture and coordination
- Memory systems (episodic, semantic, working)
- Tool definition patterns
- Performance optimization
- Integration with Vercel AI SDK
#### Example Invocation
```typescript
User: "Review our Mastra agent setup and suggest improvements"
→ Use mastra-optimization-researcher
```typescript
---
### 7. xAI Integration Optimizer
**File:** `.claude/agents/xai-integration-optimizer.md`
**Model:** Sonnet
**Description:** Elite xAI (Grok) integration specialist
#### Purpose
Optimizes xAI (Grok) integration in the codebase. Focuses on Mastra framework implementation, performance improvements, API usage patterns, and migration strategies.
#### Core Expertise
- **xAI API**: Official documentation at docs.x.ai/docs
- **Model Variants**: Reasoning vs non-reasoning performance
- **Mastra Integration**: LLM orchestration with Grok models
- **Migration**: Strategies from OpenAI to xAI
#### When to Use
✅ Use xai-integration-optimizer for:
- Optimizing xAI/Grok usage
- Model variant selection (reasoning vs non-reasoning)
- Performance improvements for AI calls
- Migration from OpenAI to xAI
- Cost optimization
- xAI API best practices
❌ Don't use for:
- Non-xAI providers (use ai-sdk-specialist)
- General AI architecture (use mastra-optimization-researcher)
- Deployment (use deployment-engineer)
#### Key Skills Used
- `environment-configuration-skill` - API key management
- `redis-integration-skill` - Caching for LLM responses
- `aI-agent-implementation-skill` - Model configuration
#### Example Invocation
```typescript
User: "Should we migrate more OpenAI calls to xAI?"
→ Use xai-integration-optimizer
```typescript
---
## Agent Selection Guide
### Decision Tree
Use this flowchart to select the right agent:
```typescript
Is it about...
┌─ Next.js routing, components, SSR?
│ → nextjs-architect
│
├─ UI styling, responsiveness, accessibility?
│ → ui-ux-developer
│
├─ Deployment, CI/CD, environment variables?
│ → deployment-engineer
│
├─ Writing/fixing tests, test coverage?
│ → test-engineer
│
├─ AI tools, LLM calls, Mastra agents?
│ ├─ Mastra optimization?
│ │ → mastra-optimization-researcher
│ ├─ xAI/Grok specific?
│ │ → xai-integration-optimizer
│ └─ General AI/tools?
│ → ai-sdk-specialist
│
└─ Not sure?
→ Start with nextjs-architect (full-stack default)
```typescript
### Common Scenarios
#### Scenario: New Feature Development
```typescript
1. Architecture planning → nextjs-architect
2. UI implementation → ui-ux-developer
3. Testing → test-engineer
4. Deployment → deployment-engineer
```typescript
#### Scenario: Bug Fix
```typescript
1. Identify domain:
- Routing/SSR issue? → nextjs-architect
- Styling issue? → ui-ux-developer
- Test failure? → test-engineer
- Deploy failure? → deployment-engineer
- AI tool issue? → ai-sdk-specialist
```typescript
#### Scenario: Optimization
```typescript
1. What to optimize?
- Mastra architecture? → mastra-optimization-researcher
- xAI integration? → xai-integration-optimizer
- Next.js performance? → nextjs-architect
- UI performance? → ui-ux-developer
- CI/CD pipeline? → deployment-engineer
```typescript
### Selection Matrix
| Task Type | Primary Agent | Support Agents |
| --------------- | ------------------------------ | ------------------------------- |
| New page/route | nextjs-architect | ui-ux-developer, test-engineer |
| UI component | ui-ux-developer | nextjs-architect, test-engineer |
| AI tool | ai-sdk-specialist | test-engineer |
| Fix deployment | deployment-engineer | - |
| Write tests | test-engineer | - |
| Optimize Mastra | mastra-optimization-researcher | ai-sdk-specialist |
| Optimize xAI | xai-integration-optimizer | ai-sdk-specialist |
| Full feature | nextjs-architect | ALL (coordinate) |
---
## Collaboration Patterns
### Pattern 1: Sequential Handoff
One agent completes their work, then explicitly hands off to the next agent.
**Example: New Blog Feature**
```typescript
1. nextjs-architect
- Creates app/blog/page.tsx with SSR
- Implements data fetching
- Sets up routing
- Status: ✅ Architecture complete
- Handoff: "UI needs styling and responsiveness"
2. ui-ux-developer
- Styles blog layout with Tailwind
- Ensures responsive design
- Tests 8 brightness modes
- Status: ✅ UI complete
- Handoff: "Ready for testing"
3. test-engineer
- Writes unit tests for components
- Adds E2E tests for blog flow
- Verifies hydration safety
- Status: ✅ Tests passing
- Handoff: "Ready for deployment"
4. deployment-engineer
- Verifies quality gates
- Deploys to production
- Monitors post-deployment
- Status: ✅ Deployed
```typescript
### Pattern 2: Parallel Collaboration
Multiple agents work on different aspects simultaneously.
**Example: AI Chat Feature**
```typescript
Parallel Work:
┌─ ai-sdk-specialist
│ - Implements AI tool schemas
│ - Creates API routes
│ - Configures LLM models
│
├─ ui-ux-developer
│ - Designs chat interface
│ - Creates message components
│ - Implements streaming UI
│
└─ test-engineer
- Plans test strategy
- Sets up test fixtures
- Prepares E2E scenarios
Convergence:
→ nextjs-architect integrates all pieces
→ deployment-engineer deploys
```typescript
### Pattern 3: Iterative Refinement
Agent completes initial work, then refines based on feedback.
**Example: Performance Optimization**
```typescript
Round 1:
xai-integration-optimizer
- Analyzes current xAI usage
- Suggests model variant changes
- Provides migration plan
Review: Performance improved 40%
Round 2:
mastra-optimization-researcher
- Reviews Mastra architecture
- Suggests tool optimizations
- Refines memory usage
Review: Performance improved 70%
Round 3:
ai-sdk-specialist
- Implements caching
- Adds rate-limiting
- Optimizes streaming
Final: ✅ Performance meets targets
```typescript
### Pattern 4: Consultation
One agent consults another for specific expertise.
**Example: Component with AI Feature**
```typescript
Primary: ui-ux-developer (building component)
Consultation 1: nextjs-architect
Q: "Should this be server or client component?"
A: "Client component - needs user interaction"
Consultation 2: ai-sdk-specialist
Q: "How to integrate AI tool result?"
A: "Use message.parts array in AI SDK v5"
Consultation 3: test-engineer
Q: "How to test hydration with AI streaming?"
A: "Wait for data-testid='hydrated' before assertions"
Result: Component complete with all expertise integrated
```typescript
---
## Handoff Procedures
### Clear Handoff Template
When an agent completes their work:
```markdown
## Handoff Summary
**Agent:** [agent-name]
**Task:** [what was accomplished]
**Status:** ✅ Complete / 🟡 Partial / ❌ Blocked
### What Was Done
- [Specific action 1]
- [Specific action 2]
- [Specific action 3]
### Files Changed
- [path/to/file1.ts] - [description]
- [path/to/file2.tsx] - [description]
### Testing Status
- [ ] Unit tests: [passing/failing/not written]
- [ ] E2E tests: [passing/failing/not written]
- [ ] Manual testing: [done/pending]
### Next Steps
1. [What needs to happen next]
2. [Which agent should handle it]
3. [Any blockers or dependencies]
### Recommended Next Agent
**Agent:** [next-agent-name]
**Reason:** [why this agent]
**Context:** [what they need to know]
```typescript
### Handoff Examples
#### Example 1: Architecture to UI
```markdown
## Handoff Summary
**Agent:** nextjs-architect
**Task:** Create contact form page with server action
**Status:** ✅ Complete
### What Was Done
- Created app/contact/page.tsx with server component
- Implemented submitContact server action
- Added form validation with Zod
- Set up error handling
### Files Changed
- app/contact/page.tsx - Contact form page
- app/contact/actions.ts - Server actions
- lib/schemas/contact.ts - Zod schema
### Testing Status
- [x] Unit tests: 3/3 passing (validation logic)
- [ ] E2E tests: Not written yet
- [x] Manual testing: Form submits successfully
### Next Steps
1. Style the contact form with Tailwind
2. Make it responsive (mobile, tablet, desktop)
3. Ensure 8 brightness modes work
4. Add proper focus states and animations
### Recommended Next Agent
**Agent:** ui-ux-developer
**Reason:** Form needs styling and responsive design
**Context:** The form structure is complete with proper semantic HTML. Focus on styling, animations, and accessibility.
```typescript
#### Example 2: UI to Testing
```markdown
## Handoff Summary
**Agent:** ui-ux-developer
**Task:** Style and make contact form responsive
**Status:** ✅ Complete
### What Was Done
- Styled form with Tailwind CSS 4
- Implemented responsive breakpoints (mobile → desktop)
- Tested all 8 brightness modes
- Added focus states and animations
- Ensured WCAG AA accessibility
### Files Changed
- app/contact/page.tsx - Added Tailwind classes
- app/contact/components/ContactForm.tsx - New component
### Testing Status
- [x] Unit tests: Still passing (no logic changes)
- [ ] E2E tests: Need comprehensive test coverage
- [x] Manual testing: Tested on all screen sizes
### Next Steps
1. Write E2E tests for contact form submission
2. Test validation error states
3. Test success/failure flows
4. Test keyboard navigation
5. Verify hydration after form submission
### Recommended Next Agent
**Agent:** test-engineer
**Reason:** Need comprehensive test coverage
**Context:** Form is complete and styled. Focus on user flow testing, including validation, submission, and error handling.
```typescript
#### Example 3: Testing to Deployment
```markdown
## Handoff Summary
**Agent:** test-engineer
**Task:** Write comprehensive tests for contact form
**Status:** ✅ Complete
### What Was Done
- Added 12 unit tests for form validation
- Created 3 E2E tests for user flows
- Tested all error states
- Verified hydration safety
- All tests passing ✅
### Files Changed
- app/contact/components/ContactForm.test.tsx - 12 unit tests
- e2e/contact-form.spec.ts - 3 E2E tests
### Testing Status
- [x] Unit tests: 788/788 passing (+12)
- [x] E2E tests: 69/69 passing (+3)
- [x] Manual testing: All scenarios verified
### Next Steps
1. Verify all quality gates pass
2. Deploy to pre-deployment branch
3. Monitor for issues
4. Merge to main after verification
### Recommended Next Agent
**Agent:** deployment-engineer
**Reason:** Ready for production deployment
**Context:** All tests passing, quality gates should pass. Contact form feature is complete and ready for users.
```typescript
---
## Quality Standards
### Every Agent Must Ensure
#### 1. Code Quality
- ✅ Zero ESLint errors
- ✅ Zero TypeScript errors
- ✅ Follows project patterns
- ✅ Uses `@/` path alias
- ✅ No TODO comments
- ✅ No console.log in production
#### 2. Testing
- ✅ Unit tests for logic
- ✅ E2E tests for flows
- ✅ All tests passing
- ✅ No skipped tests without reason
- ✅ Coverage maintained or improved
#### 3. Documentation
- ✅ Code is self-documenting
- ✅ Complex logic has comments
- ✅ API routes documented
- ✅ PropTypes/schemas defined
#### 4. Performance
- ✅ Bundle size within limits
- ✅ Images optimized
- ✅ No unnecessary re-renders
- ✅ Proper code splitting
#### 5. Accessibility
- ✅ Semantic HTML
- ✅ ARIA labels where needed
- ✅ Keyboard navigation
- ✅ Focus management
#### 6. Project-Specific
- ✅ 8 brightness modes supported (UI)
- ✅ Hydration-safe patterns (SSR)
- ✅ No hardcoded colors
- ✅ Lucide icons (no emojis)
### Quality Gates (Pre-Deployment)
All 6 gates must pass before merging to main:
1. **ESLint**: `npm run lint` - 0 errors
2. **TypeScript**: `npx tsc --noEmit` - 0 errors
3. **Unit Tests**: `npm test` - 776+ passing
4. **Build**: `npm run build` - Success
5. **Bundle Size**: `npm run size` - Within limits
6. **E2E Tests**: `npm run test:e2e` - 66+ passing
### Agent Accountability
Each agent is accountable for their domain's quality:
| Agent | Quality Responsibility |
| ------------------------------ | -------------------------------------- |
| nextjs-architect | Architecture, routing, SSR correctness |
| ui-ux-developer | Visual quality, responsiveness, a11y |
| deployment-engineer | Deploy success, zero downtime |
| test-engineer | Test coverage, test quality |
| ai-sdk-specialist | AI tool reliability, LLM costs |
| mastra-optimization-researcher | Architecture optimization |
| xai-integration-optimizer | xAI performance and costs |
---
## Best Practices
### For Users
1. **Be Specific**: "Fix the sidebar styling on mobile" is better than "Fix the sidebar"
2. **Mention Context**: "The contact form we just built" helps agent understand
3. **State Constraints**: "Without changing existing tests" prevents rework
4. **Trust the Agent**: Let them follow their domain expertise
5. **Allow Handoffs**: Don't force one agent to do everything
### For Agent Selection
1. **Start Narrow**: Choose the most specific agent first
2. **Allow Escalation**: Agent can hand off if needed
3. **Consider Sequence**: Some tasks naturally flow (architecture → UI → testing)
4. **Parallel When Possible**: Independent work can happen simultaneously
5. **Iterate**: It's okay to revisit agents for refinement
### For Handoffs
1. **Be Explicit**: Clear handoff summary, not implicit
2. **Include Context**: Next agent needs to understand what was done
3. **List Files**: What was changed and why
4. **Test Status**: What's tested, what's not
5. **Next Steps**: Clear action items for next agent
---
## Troubleshooting
### "Agent did work outside their domain"
**Solution**: Use handoff procedure to transfer to correct agent
### "Multiple agents needed but unclear order"
**Solution**: Use decision tree, or start with nextjs-architect for coordination
### "Agent asked for clarification"
**Solution**: Provide more context about what you're trying to achieve
### "Quality gates failing"
**Solution**: Use test-engineer or deployment-engineer to diagnose
### "Not sure which agent to use"
**Solution**:
1. Check decision tree
2. Use scenario matrix
3. Default to nextjs-architect for full-stack tasks
---
## Agent Communication Protocol
### How Agents Communicate
Agents don't directly talk to each other, but they:
1. **Leave Clear Handoffs**: Documented summaries for next agent
2. **Reference Context**: Point to relevant files and patterns
3. **Follow Conventions**: All agents know project patterns
4. **Use Skills**: Shared knowledge through skill files
5. **Maintain Quality**: Each agent enforces standards
### Communication Flow
```typescript
User Request
↓
Agent Selection (based on domain)
↓
Agent Works (using skills + context)
↓
Agent Completes (or hands off)
↓
[If handoff needed]
↓
Clear Handoff Summary
↓
Next Agent Continues
```typescript
---
## Advanced Patterns
### Meta-Agent Coordination
For complex features requiring multiple domains, nextjs-architect can act as coordinator:
```typescript
User: "Build a complete blog system with AI-powered summaries"
Coordinator: nextjs-architect
├─ Phase 1: nextjs-architect (architecture)
├─ Phase 2: ai-sdk-specialist (AI tools)
├─ Phase 3: ui-ux-developer (UI components)
├─ Phase 4: test-engineer (comprehensive tests)
└─ Phase 5: deployment-engineer (deploy)
```typescript
### Consultation Pattern
Any agent can pause to consult another agent's skill:
```typescript
Agent: ui-ux-developer (working on component)
Pause: "Need to check hydration pattern"
Consult: Read hydration-safety-skill
Resume: Continue with proper pattern
```typescript
### Iterative Refinement
Some tasks benefit from multiple passes:
```typescript
Pass 1: Initial implementation
Pass 2: Optimization (research agent)
Pass 3: Final polish
```typescript
---
## Quick Reference
### Agent Quick Selector
| If you need... | Use this agent |
| --------------- | ------------------------------ |
| New page | nextjs-architect |
| Fix styling | ui-ux-developer |
| Fix deployment | deployment-engineer |
| Write tests | test-engineer |
| Add AI tool | ai-sdk-specialist |
| Optimize Mastra | mastra-optimization-researcher |
| Optimize xAI | xai-integration-optimizer |
| Not sure | nextjs-architect |
### Common Commands
```bash
# Run all quality gates
npm run lint && npx tsc --noEmit && npm test && npm run build && npm run test:e2e
# Watch tests during development
npm test -- --watch
# Run specific agent tests
npm test -- nextjs-architect
# Deploy to staging
git push origin pre-deployment
# View logs
vercel logs
```typescript
---
## Conclusion
The specialized agent architecture ensures:
- ✅ **Deep Expertise**: Each agent masters their domain
- ✅ **Quality Focus**: Every agent enforces standards
- ✅ **Clear Ownership**: No confusion about responsibility
- ✅ **Efficient Collaboration**: Clean handoffs between agents
- ✅ **Maintainability**: Consistent patterns across codebase
Remember: The goal isn't just to complete tasks—it's to maintain a production-grade portfolio that showcases technical excellence. Every agent plays a part in achieving that goal.
---
**Need Help?**
- Check [CLAUDE.md](./CLAUDE.md) for the strategic router
- Review [skills directory](./skills/) for implementation patterns
- See [commands directory](./commands/) for common workflows
**Last Updated:** 2025-11-08 (Phase 1 - Foundation Complete)