# AGENT.md

## Available MCP Tools

You have access to **five powerful MCP tool sets** for comprehensive research and analysis:

### 1. CodeGraphContext (CGC) - Local Code Analysis

**Purpose**: Analyze, understand, and navigate local codebases through graph-based relationships.

**When to Use**:
- Working with existing code in the local repository
- Understanding how code works together
- Finding where functions/classes are defined or used
- Analyzing the impact of code changes
- Identifying dead code or complex code
- Tracing execution flows across files
- Refactoring or maintaining code

**Key Tools**:
- `codegraph_find_code` - Find functions, classes, or code by keywords
- `codegraph_analyze_code_relationships` - Analyze callers, callees, inheritance, dependencies
- `codegraph_watch_directory` - Monitor active projects for real-time updates
- `codegraph_add_code_to_graph` - Index code into the graph
- `codegraph_find_dead_code` - Find potentially unused functions
- `codegraph_calculate_cyclomatic_complexity` - Measure function complexity
- `codegraph_get_repository_stats` - Understand codebase size and structure
- `codegraph_list_indexed_repositories` - Check what code is available

**Common Queries**:
- "Where is the `process_payment` function?"
- "What functions call `get_user_by_id`?"
- "If I change `calculate_tax`, what code will be affected?"
- "Show me the call chain from `main` to `process_data`"
- "Find dead or unused code in this project"
- "What's the most complex function in this codebase?"

**Best Practices**:
- Check `codegraph_list_indexed_repositories` first to see what code is available
- Use `codegraph_watch_directory` for projects you're actively working on
- Start with `codegraph_find_code` for simple searches
- Use `codegraph_analyze_code_relationships` for deep analysis and impact assessment
- Check `codegraph_list_watched_paths` to see what's being monitored
- Background indexing jobs return a `job_id` - use `codegraph_check_job_status` to track progress

---

### 2. Context7 - Up-to-Date Library Documentation

**Purpose**: Get current, version-specific documentation and code examples for thousands of libraries and frameworks.

**When to Use**:
- Needing up-to-date documentation for libraries or frameworks
- Looking for code examples and best practices
- Implementing new features using external libraries
- Learning APIs you haven't used before
- Wanting to avoid hallucinated APIs or outdated code
- Working with specific versions of libraries

**Key Tools**:
- `context7_resolve-library-id` - Find the correct library ID (max 3 calls/question)
- `context7_query-docs` - Get documentation for a library (max 3 calls/question)

**Usage Pattern**:
1. Call `context7_resolve-library-id` with library name and your task
2. Review results, select best match based on description, trust score, benchmark score
3. Call `context7_query-docs` with the library ID and your specific question

**If user provides library ID in `/org/project` format**, you can skip step 1.

**Common Queries**:
- "How do I set up authentication with Supabase?"
- "Show me examples of using Next.js middleware"
- "How to implement JWT auth with Express.js"
- "What's the best way to handle errors in React hooks?"

**Best Practices**:
- **ALWAYS use `context7_resolve-library-id` first** unless user provides exact library ID
- **Be specific** in your query: "How to set up authentication with JWT" not "auth"
- **Max 3 calls**: Do not call these tools more than 3 times per question
- **Check scores**: Prioritize libraries with higher trust and benchmark scores
- **No secrets**: Never include API keys, passwords, credentials, or personal data in queries
- **Explain choice**: Briefly explain which library was selected when multiple matches exist

---

### 3. Brave - Quick Web Search

**Purpose**: Quick web searches for current information.

**When to Use**:
- Needing fast, general web searches
- Looking for recent news or updates
- Finding current technology information
- Quick research without deep crawling

**Key Tools**:
- `brave_brave_web_search` - General web search
- `brave_brave_local_search` - Local business/places search

---

### 4. Tavily - Advanced Search & Extraction

**Purpose**: Comprehensive web search with advanced capabilities including content extraction and crawling.

**When to Use**:
- Needing in-depth research on technical topics
- Extracting content from multiple URLs
- Crawling entire websites for documentation
- Finding detailed implementation examples

**Key Tools**:
- `tavily_tavily_search` - Advanced search with detailed results
- `tavily_tavily_extract` - Extract structured content from URLs
- `tavily_tavily_crawl` - Crawl websites systematically
- `tavily_tavily_map` - Map website structure

---

### 5. BrightData - Web Scraping & Data Extraction

**Purpose**: Comprehensive web scraping, structured data extraction, and browser automation.

**When to Use**:
- Web scraping with anti-bot bypass
- Structured data extraction (clean markdown, tables, embedded content)
- Browser automation for complex, interactive websites
- Testing web applications

**Key Tools**:
- `brightData_search_engine` - Web search using Google Search API
- `brightData_scrape_as_markdown` - Extract and convert to markdown
- `brightData_search_engine_batch` - Multi-query searches
- Playwright browser automation (11 tools)

---

## Project Context

**Project Name**: allmywork
**Purpose**: Portfolio web application
**Stack**: SvelteKit, Bun, Biome, Tailwind CSS, Feature Sliced Design (FSD)
**Deployment**: Self-hosted on VPS in Docker container

---

## Bun Usage Guidelines

**Always use `bun` commands, never `npm`**:

- **Package management**: `bun install`, `bun add`, `bun remove`
- **Script execution**: `bun run <script-name>`
- **Running binaries**: Use `bunx <package>` instead of `npx <package>`
- **Test runner**: `bun test` or `bun run test` (Vitest via Bun)

**Examples**:
```bash
# Install dependencies
bun install

# Add dependency
bun add -D tailwindcss

# Run script
bun run dev

# Run binary (instead of npx)
bunx @biomejs/biome init

# Run tests (Vitest via Bun)
bun run test
```

---

## Agent Roles & Responsibilities

### UI/UX Agent

**Responsibilities**:
- Design and implement UI components using Svelte 5 features (runes, snippets)
- Apply Tailwind CSS classes following the mixed approach pattern:
  - Use utilities directly for one-off styles
  - Create component classes for repeated patterns
- Ensure responsive design and accessibility (WCAG compliance)
- Implement micro-interactions and animations
- Work within Feature Sliced Design structure

**Naming Conventions**:
- Components: PascalCase (e.g., `UserProfile.svelte`)
- Utilities: camelCase (e.g., `formatDate.ts`)

**Comment Style**:
```svelte
/**
 * Component description
 */
<script lang="ts">
  // Short remark for inline logic
</script>
```

**When to Use**:
- "Design/create component", "Add styling", "UI implementation", "Add animations"

---

### Feature Developer Agent

**Responsibilities**:
- Create and manage FSD slices (pages, features, entities, widgets, shared)
- Implement business logic and data flows
- Integrate UI components with backend functionality
- Follow FSD methodology for slice composition
- Ensure proper separation of concerns across layers

**FSD Structure**:
```
src/
├── pages/        # Full pages
├── features/      # User interactions
├── entities/      # Business entities
├── widgets/       # Composed components
├── shared/        # Shared code
└── app/          # SvelteKit app layer (routes)
```

**When to Use**:
- "Create feature", "Implement business logic", "Add page", "Create slice"

---

### Test Engineer Agent

**Responsibilities**:
- Write unit tests using Vitest
- Write E2E tests using Playwright
- Test critical user flows
- Ensure test coverage meets quality standards
- Follow test-driven approach for new features

**Testing Infrastructure**:
- Unit tests: Vitest (Vite-native)
- E2E tests: Playwright
- Target coverage: 80%+ for new code
- Write tests alongside implementation (TDD for new features)

**When to Use**:
- "Write tests", "Test coverage", "Add E2E test", "Test flow"

---

### Documentation Agent

**Responsibilities**:
- Write inline code comments following "Less is more" principle
- Create API documentation
- Write README files and guides
- Document FSD structure and slice usage
- Explain core logic and caveats succinctly

**Comment Patterns**:
```typescript
/**
 * Function description explaining core logic
 */
export function processPayment(data: PaymentData): Promise<Payment> {
  // Validate input data
  const validated = validateData(data);

  // Process payment with fallback
  return processWithFallback(validated);
}
```

**When to Use**:
- "Write documentation", "Add comments", "Document API", "Create README"

---

### Architecture Reviewer Agent

**Responsibilities**:
- Review code for FSD compliance
- Identify architectural violations and anti-patterns
- Ensure proper layer separation
- Check for circular dependencies
- Verify component and slice integration patterns

**Review Checklist**:
- [ ] FSD layer boundaries respected
- [ ] No circular dependencies
- [ ] Proper slice composition
- [ ] Shared code appropriately extracted
- [ ] Feature isolation maintained

**When to Use**:
- "Review architecture", "Check FSD compliance", "Analyze code structure"

---

## Key Workflows

### 1. Creating a New Feature

**Prerequisites**: None required

**Steps**:

1. **Create feature branch**:
   ```bash
   git checkout -b feature/featureName
   ```

2. **Plan FSD slice**:
   - Determine which layers needed (page, feature, entity, widget, shared)
   - Identify dependencies between layers
   - Plan data flow

3. **Implement entities** (bottom-up):
   ```bash
   # Example: src/entities/user/ui/UserAvatar.svelte
   # Example: src/entities/user/model/types.ts
   ```

4. **Implement features**:
   ```bash
   # Example: src/features/auth/ui/LoginForm.svelte
   # Example: src/features/auth/model/useAuth.ts
   ```

5. **Compose widgets** (if needed):
   ```bash
   # Example: src/widgets/header/ui/Header.svelte
   ```

6. **Create page**:
   ```bash
   # Example: src/pages/home/ui/HomePage.svelte
   # Example: src/pages/home/index.ts
   ```

7. **Integrate in app routes**:
   ```bash
   # src/app/routes/+page.svelte
   import { HomePage } from '$lib/pages/home';
   ```

8. **Write tests**:
   - Unit tests for business logic
   - E2E tests for critical flows

9. **Commit with conventional format**:
   ```bash
   git commit -m "feat(featureName): short yet capacitive description"
   ```

**Output**: Complete feature implementation with FSD-compliant structure

**Success Criteria**:
- Feature works as specified
- All tests pass
- FSD layer boundaries respected
- Code follows naming conventions
- Comments explain core logic

---

### 2. Creating a New Component

**Prerequisites**: None required

**Steps**:

1. **Identify layer**:
   - Entity: Reusable business entity component
   - Feature: User interaction component
   - Widget: Composed UI component
   - Page: Full page component

2. **Create component file**:
   ```bash
   # src/features/myFeature/ui/MyComponent.svelte
   ```

3. **Write Svelte 5 component**:
   ```svelte
   <script lang="ts">
     /**
      * Component description
      */
     let { data }: { data: DataType } = $props();

     // Reactive state with runes
     let state = $state({});
   </script>

   <div class="tailwind-classes">
     <!-- Component content -->
   </div>
   ```

4. **Add Tailwind styles**:
   - One-off styles: Use utilities directly
   - Repeated patterns: Extract to shared classes

5. **Export from index** (if applicable):
   ```typescript
   // src/features/myFeature/index.ts
   export { MyComponent } from './ui/MyComponent.svelte';
   ```

6. **Write tests**:
   ```typescript
   // src/features/myFeature/ui/MyComponent.test.ts
   ```

7. **Commit**:
   ```bash
   git commit -m "feat(myFeature): add MyComponent for ..."
   ```

**Output**: Working component with tests

**Success Criteria**:
- Component renders correctly
- Follows naming conventions
- Has appropriate tests
- Styles follow Tailwind pattern

---

### 3. Running Tests

**Prerequisites**: Project initialized with Vitest and Playwright

**Steps**:

1. **Run unit tests**:
   ```bash
   bun run test
   # or
   bun run test:watch
   ```

2. **Run E2E tests**:
   ```bash
   bun run test:e2e
   ```

3. **Run all tests**:
   ```bash
   bun run test:all
   ```

4. **Check coverage**:
   ```bash
   bun run test:coverage
   ```

**Output**: Test results with pass/fail status

**Success Criteria**:
- All tests pass
- Coverage meets 80%+ for new code
- No flaky tests

---

### 4. Building for Production

**Prerequisites**: Development complete, tests passing

**Steps**:

1. **Run linting and formatting**:
   ```bash
   bun run lint
   bun run format:check
   ```

2. **Build application**:
   ```bash
   bun run build
   ```

3. **Test build locally**:
   ```bash
   bun run preview
   ```

4. **Build Docker image**:
   ```bash
   docker build -t allmywork:latest .
   ```

5. **Test Docker container**:
   ```bash
   docker run -p 3000:3000 allmywork:latest
   ```

**Output**: Production-ready build and Docker image

**Success Criteria**:
- Build completes without errors
- Linting passes
- Docker image runs successfully
- Application accessible at expected port

---

### 5. Deploying to VPS

**Prerequisites**: Docker image built, VPS accessible

**Steps**:

1. **Transfer image to VPS**:
   ```bash
   docker save allmywork:latest | gzip | ssh user@vps "docker load"
   ```

2. **Or build directly on VPS**:
   ```bash
   ssh user@vps "cd /path/to/project && bun run build && docker build -t allmywork:latest ."
   ```

3. **Stop old container** (if exists):
   ```bash
   ssh user@vps "docker stop allmywork && docker rm allmywork"
   ```

4. **Run new container**:
   ```bash
   ssh user@vps "docker run -d --name allmywork -p 3000:3000 --restart unless-stopped allmywork:latest"
   ```

5. **Verify deployment**:
   ```bash
   curl https://your-domain.com
   ```

**Output**: Running application on VPS

**Success Criteria**:
- Container running
- Application accessible
- No errors in logs
- HTTPS configured (if applicable)

---

## Code Conventions

### Naming

- **Components**: PascalCase (e.g., `UserProfile.svelte`)
- **Files/Functions**: camelCase (e.g., `formatDate.ts`, `getUserData`)
- **Types**: PascalCase (e.g., `UserData`, `PaymentResult`)

### Comments

**Multiline comments** (for documentation and types):
```typescript
/**
 * Function description explaining core logic and caveats
 */
```

**One-line comments** (for short remarks):
```typescript
// Validate input before processing
```

**Rule**: "Less is more" - short yet capacitive, explaining core logic and caveats

### Commit Messages

**Format**: `prefix(featureName/fileName): short yet capacitive one-line description`

**Prefixes**:
- `feat` - New feature
- `fix` - Bug fix
- `chore` - Maintenance tasks
- `refactor` - Code refactoring
- `docs` - Documentation changes
- `style` - Code style changes
- `test` - Test changes
- `perf` - Performance improvements
- `ci` - CI/CD changes
- `build` - Build system changes
- `revert` - Revert previous commit

**Examples**:
- `feat(auth): add OAuth2 token refresh`
- `fix(payment): resolve memory leak in service`
- `docs(readme): update setup instructions`

---

## Tool Selection Decision Tree

```
Need help with code or libraries?
│
├─ LOCAL codebase analysis?
│  └─ YES → CodeGraphContext
│     ├─ Find something → codegraph_find_code
│     ├─ Understand relationships → codegraph_analyze_code_relationships
│     ├─ Check impact → find_callers, find_all_callers
│     └─ Code quality → find_dead_code, find_most_complex_functions
│
└─ EXTERNAL library/framework?
   └─ YES → Context7
      ├─ Have exact ID? → context7_query-docs
      └─ Need to find ID? → resolve-library-id → query-docs

Need web research?
│
├─ Quick search?
│  └─ YES → Brave
│     └─ brave_brave_web_search
│
├─ Advanced research/extraction?
│  └─ YES → Tavily
│     ├─ tavily_tavily_search
│     ├─ tavily_tavily_extract
│     └─ tavily_tavily_crawl
│
└─ Scraping/testing?
   └─ YES → BrightData
      ├─ brightData_search_engine
      ├─ brightData_scrape_as_markdown
      └─ Playwright tools
```

---

## Deployment Strategy

**Self-Hosted Docker Deployment**:
- Build: `bun run build`
- Docker image: `docker build -t allmywork:latest .`
- Run: `docker run -d -p 3000:3000 --restart unless-stopped allmywork:latest`
- Update: `docker stop && docker rm && docker run ...`

---

## Git Workflow

**Branching Strategy**:
- Feature branches: `feature/featureName`
- Bugfix branches: `fix/issueName`
- Main branches: `main`, `develop`

**Commit Process**:
1. Write code
2. Run tests: `bun run test:all`
3. Run lint: `bun run lint`
4. Stage files: `git add`
5. Commit: `git commit -m "prefix(feature): description"`
6. Push: `git push`
7. Create PR

**Use `skip orchestrator` when committing** to avoid extra agent overhead.