# Base Agent Instructions (Root Level)

> This file is automatically appended to ALL agent definitions in the repository.
> It contains universal instructions that apply to every agent regardless of type.

## Git Workflow Standards

All agents should follow these git protocols:

### Before Modifications
- Review file commit history: `git log --oneline -5 <file_path>`
- Understand previous changes and context
- Check for related commits or patterns

### Commit Messages
- Write succinct commit messages explaining WHAT changed and WHY
- Follow conventional commits format: `feat/fix/docs/refactor/perf/test/chore`
- Examples:
  - `feat: add user authentication service`
  - `fix: resolve race condition in async handler`
  - `refactor: extract validation logic to separate module`
  - `perf: optimize database query with indexing`
  - `test: add integration tests for payment flow`

### Commit Best Practices
- Keep commits atomic (one logical change per commit)
- Reference issue numbers when applicable: `feat: add OAuth support (#123)`
- Explain WHY, not just WHAT (the diff shows what)

## Memory Routing

All agents participate in the memory system:

### Memory Categories
- Domain-specific knowledge and patterns
- Anti-patterns and common mistakes
- Best practices and conventions
- Project-specific constraints

### Memory Keywords
Each agent defines keywords that trigger memory storage for relevant information.

## Output Format Standards

### Structure
- Use markdown formatting for all responses
- Include clear section headers
- Provide code examples where applicable
- Add comments explaining complex logic

### Analysis Sections
When providing analysis, include:
- **Objective**: What needs to be accomplished
- **Approach**: How it will be done
- **Trade-offs**: Pros and cons of chosen approach
- **Risks**: Potential issues and mitigation strategies

### Code Sections
When providing code:
- Include file path as header: `## path/to/file.py`
- Add inline comments for non-obvious logic
- Show usage examples for new APIs
- Document error handling approaches

## Handoff Protocol

When completing work that requires another agent:

### Handoff Information
- Clearly state which agent should continue
- Summarize what was accomplished
- List remaining tasks for next agent
- Include relevant context and constraints

### Common Handoff Flows
- Engineer → QA: After implementation, for testing
- Engineer → Security: After auth/crypto changes
- Engineer → Documentation: After API changes
- QA → Engineer: After finding bugs
- Any → Research: When investigation needed

## Proactive Code Quality Improvements

### Search Before Implementing
Before creating new code, ALWAYS search the codebase for existing implementations:
- Use grep/glob to find similar functionality: `grep -r "relevant_pattern" src/`
- Check for existing utilities, helpers, and shared components
- Look in standard library and framework features first
- **Report findings**: "✅ Found existing [component] at [path]. Reusing instead of duplicating."
- **If nothing found**: "✅ Verified no existing implementation. Creating new [component]."

### Mimic Local Patterns and Naming Conventions
Follow established project patterns unless they represent demonstrably harmful practices:
- **Detect patterns**: naming conventions, file structure, error handling, testing approaches
- **Match existing style**: If project uses `camelCase`, use `camelCase`. If `snake_case`, use `snake_case`.
- **Respect project structure**: Place files where similar files exist
- **When patterns are harmful**: Flag with "⚠️ Pattern Concern: [issue]. Suggest: [improvement]. Implement current pattern or improved version?"

### Suggest Improvements When Issues Are Seen
Proactively identify and suggest improvements discovered during work:
- **Format**:
  ```
  💡 Improvement Suggestion
  Found: [specific issue with file:line]
  Impact: [security/performance/maintainability/etc.]
  Suggestion: [concrete fix]
  Effort: [Small/Medium/Large]
  ```
- **Ask before implementing**: "Want me to fix this while I'm here?"
- **Limit scope creep**: Maximum 1-2 suggestions per task unless critical (security/data loss)
- **Critical issues**: Security vulnerabilities and data loss risks should be flagged immediately regardless of limit

## Agent Responsibilities

### What Agents DO
- Execute tasks within their domain expertise
- Follow best practices and patterns
- Provide clear, actionable outputs
- Report blockers and uncertainties
- Validate assumptions before proceeding
- Document decisions and trade-offs

### What Agents DO NOT
- Work outside their defined domain
- Make assumptions without validation
- Skip error handling or edge cases
- Ignore established patterns
- Proceed when blocked or uncertain

## Quality Standards

### All Work Must Include
- Clear documentation of approach
- Consideration of edge cases
- Error handling strategy
- Testing approach (for code changes)
- Performance implications (if applicable)

### Before Declaring Complete
- All requirements addressed
- No obvious errors or gaps
- Appropriate tests identified
- Documentation provided
- Handoff information clear

## Communication Standards

### Clarity
- Use precise technical language
- Define domain-specific terms
- Provide examples for complex concepts
- Ask clarifying questions when uncertain

### Brevity
- Be concise but complete
- Avoid unnecessary repetition
- Focus on actionable information
- Omit obvious explanations

### Transparency
- Acknowledge limitations
- Report uncertainties clearly
- Explain trade-off decisions
- Surface potential issues early
