# CLAUDE.md

This file contains meta-instructions for how Claude should work with the ISA-Frontend codebase.

## 🔴 CRITICAL: Mandatory Agent Usage

**You MUST use these subagents for ALL research and knowledge management tasks:**
- **`docs-researcher`**: For ALL documentation (packages, libraries, READMEs)
- **`docs-researcher-advanced`**: Auto-escalate when docs-researcher fails
- **`Explore`**: For ALL code pattern searches and multi-file analysis

**Violations of this rule degrade performance and context quality. NO EXCEPTIONS.**

## Communication Guidelines

**Keep answers concise and focused:**
- Provide direct, actionable responses without unnecessary elaboration
- Skip verbose explanations unless specifically requested
- Focus on what the user needs to know, not everything you know
- Use bullet points and structured formatting for clarity
- Only provide detailed explanations when complexity requires it

## Researching and Investigating the Codebase

**🔴 MANDATORY: You MUST use subagents for research. Direct file reading/searching.**

### Required Agent Usage

| Task Type | Required Agent | Escalation Path |
|-----------|---------------|-----------------|
| **Package/Library Documentation** | `docs-researcher` | → `docs-researcher-advanced` if not found |
| **Internal Library READMEs** | `docs-researcher` | Keep context clean |
| **Code Pattern Search** | `Explore` | Set thoroughness level |
| **Implementation Analysis** | `Explore` | Multiple file analysis |
| **Single Specific File** | Read tool directly | No agent needed |

### Documentation Research System (Two-Tier)

1. **ALWAYS start with `docs-researcher`** (Haiku, 30-120s) for any documentation need
2. **Auto-escalate to `docs-researcher-advanced`** (Sonnet, 2-7min) when:
   - Documentation not found
   - Conflicting sources
   - Need code inference
   - Complex architectural questions

### Enforcement Examples

```
❌ WRONG: Read libs/ui/buttons/README.md
✅ RIGHT: Task → docs-researcher → "Find documentation for @isa/ui/buttons"

❌ WRONG: Grep for "signalStore" patterns
✅ RIGHT: Task → Explore → "Find all signalStore implementations"

❌ WRONG: WebSearch for Zod documentation
✅ RIGHT: Task → docs-researcher → "Find Zod validation documentation"
```

**Remember: Using subagents is NOT optional - it's mandatory for maintaining context efficiency and search quality.**