# CLAUDE.md

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

## 🔴 CRITICAL: You Are an LLM with Outdated Knowledge

**Your training data is outdated. NEVER assume you know current APIs.**

- Libraries, frameworks, and APIs change constantly
- Your memory of APIs is unreliable
- Current documentation is the ONLY source of truth

**ALWAYS use research agents PROACTIVELY - without user asking.**

## 🔴 CRITICAL: Proactive Agent & Skill Usage

**You MUST use agents and skills AUTOMATICALLY for ALL tasks - do NOT wait for user to tell you.**

### Research Agents (Use BEFORE Implementation)

| Agent | Auto-Invoke When | User Interaction |
|-------|------------------|------------------|
| `docs-researcher` | ANY external library/API usage | NONE - just do it |
| `docs-researcher-advanced` | Implementation fails OR docs-researcher insufficient | NONE - just do it |
| `Explore` | Need codebase patterns or multi-file analysis | NONE - just do it |

**Research-First Flow (Mandatory):**
```
Task involves external API? → AUTO-INVOKE docs-researcher
                              ↓
                              Implement based on docs
                              ↓
                              Failed? → AUTO-INVOKE docs-researcher-advanced
                              ↓
                              Still failed? → ASK USER for guidance
```

### Skills (Use DURING Implementation)

| Trigger | Auto-Invoke Skill |
|---------|-------------------|
| Writing Angular templates | `angular-template` |
| Writing HTML with interactivity | `html-template` |
| Applying Tailwind classes | `tailwind` |
| Writing any Angular code | `logging` |
| Creating CSS animations | `css-keyframes-animations` |
| Creating new library | `library-scaffolder` |
| Regenerating API clients | `swagger-sync-manager` |
| Git operations | `git-workflow` |

**Skill chaining for Angular work:**
```
angular-template → html-template → logging → tailwind
```

### Implementation Agents (Use for Complex Tasks)

| Agent | Auto-Invoke When |
|-------|------------------|
| `angular-developer` | Creating components, services, stores (2-5 files) |
| `test-writer` | Writing tests, adding coverage |
| `refactor-engineer` | Refactoring 5+ files, migrations |

### Anti-Patterns (FORBIDDEN)

```
❌ Implementing without researching first
❌ Asking "should I research this?" - just do it
❌ Asking "should I use a skill?" - just do it
❌ Trial and error: implement → fail → try again → fail
❌ Writing Angular code without loading skills first
```

### Correct Pattern

```
✅ "Researching [library] API..." → [auto-invokes docs-researcher]
✅ "Loading angular-template skill..." → [auto-invokes skill]
✅ "Implementing based on current docs..."
✅ If fails: "Escalating research..." → [auto-invokes docs-researcher-advanced]
```

## Communication Guidelines

- Keep answers concise and focused
- Use bullet points and structured formatting
- Skip verbose explanations unless requested
- Focus on what the user needs, not everything you know

## Context Management

**Context bloat kills reliability. Minimize aggressively.**

### Tool Result Minimization

| Tool | Keep | Discard |
|------|------|---------|
| Bash (success) | `✓ Command succeeded` | Full output |
| Bash (failure) | Exit code + error (max 10 lines) | Verbose output |
| Edit | `✓ Modified file.ts` | Full diffs |
| Read | Extracted relevant section | Full file content |
| Agent results | 1-2 sentence summary | Raw JSON/full output |

### Agent Result Handling

```
❌ WRONG: "Docs researcher returned: [huge JSON...]"
✅ RIGHT: "docs-researcher found: Use signalStore() with withState()"
```

### Session Cleanup

Use `/clear` between unrelated tasks to prevent context degradation.

### Long-Running Task Pattern

For complex tasks approaching context limits:
1. Dump progress to a `.md` file (e.g., `progress.md`)
2. Use `/clear` to reset context
3. Resume by reading the progress file
4. Continue from where you left off

### Context Monitoring

- Use `/context` to check current token usage
- Fresh session baseline: ~20k tokens
- Consider `/compact` when approaching 150k tokens
- Prefer `/clear` over `/compact` when starting new topics

## Extended Thinking

Use progressive thinking depth for complex analysis:

| Trigger | Thinking Budget | Use Case |
|---------|----------------|----------|
| `"think"` | ~4k tokens | Basic analysis, simple decisions |
| `"think hard"` | ~10k tokens | Moderate complexity, multi-factor decisions |
| `"think harder"` | ~16k tokens | Deep analysis, architectural decisions |
| `"ultrathink"` | ~32k tokens | Maximum depth, critical planning |

**Examples:**
- "Think about how to structure this component"
- "Think hard about the best approach for state management"
- "Ultrathink about the architecture for this feature"

## Code Investigation (MANDATORY)

**Never speculate about code you haven't read.**

If user references a specific file:
1. **READ the file first** using the Read tool
2. **THEN provide analysis** based on actual contents
3. If file doesn't exist, **say so explicitly**

**Anti-Hallucination Rules:**
- Never describe code you haven't opened
- Never assume file contents based on names
- Never guess API signatures without documentation
- Always verify imports and dependencies exist

## Implementation Decisions

| 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                        |
| **Monorepo Library Overview**     | `docs-researcher`  | Uses `docs/library-reference.md`          |
| **Code Pattern Search**           | `Explore`          | Set thoroughness level                    |
| **Implementation Analysis**       | `Explore`          | Multiple file analysis                    |
| **Single Specific File**          | Read tool directly | No agent needed                           |

**Note:** The `docs-researcher` agent uses `docs/library-reference.md` as a primary index for discovering monorepo libraries. This file contains descriptions and locations for all libraries, enabling quick library discovery without reading individual READMEs.

### 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

### When to Use Agents vs Direct Tools

```
Single known file? → Read tool directly
Code pattern search? → Explore agent
Documentation lookup? → docs-researcher agent
Creating 2-5 Angular files? → angular-developer agent
Refactoring 5+ files? → refactor-engineer agent
Simple 1-file edit? → Direct implementation
```

### Proactive Agent Triggers

**Auto-invoke `angular-developer` when user says:**
- "Create component/service/store/pipe/directive/guard"
- Task touches 2-5 Angular files

**Auto-invoke `test-writer` when user says:**
- "Write tests", "Add coverage"

**Auto-invoke `refactor-engineer` when user says:**
- "Refactor all", "Migrate X files", "Update pattern across"

**Auto-invoke `context-manager` when user says:**
- "Remember to", "TODO:", "Don't forget"

## Agent Communication

### Briefing Agents

Keep briefings focused:
```
Implement: [type] at [path]
Purpose: [1 sentence]
Requirements: [list]
```

### Agent Results

Extract only what's needed, discard the rest:
```
✓ Created 3 files
✓ Tests: 12/12 passing
✓ Skills applied: angular-template, logging
```

<!-- nx configuration start-->
<!-- Leave the start & end comments to automatically receive updates. -->

# General Guidelines for working with Nx

- Run tasks through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of underlying tooling
- Use `nx_workspace` tool to understand workspace architecture
- Use `nx_project_details` for specific project structure
- Use `nx_docs` for nx configuration questions

<!-- nx configuration end-->