ISA-Frontend/CLAUDE.md

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

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