# Project Context & Agent Ecosystem

> **Last Updated**: {{timestamp}}
> **Generated By**: AGENTS.md Context Compiler v1.0
> **Auto-Watch**: {{enabled|disabled}}

## Table of Contents
1. [Project Overview](#project-overview)
2. [Technology Stack](#technology-stack)
3. [Project Structure](#project-structure)
4. [Agent Ecosystem](#agent-ecosystem)
5. [Development Conventions](#development-conventions)
6. [Key Dependencies](#key-dependencies)
7. [Architectural Patterns](#architectural-patterns)
8. [Testing Strategy](#testing-strategy)
9. [Deployment & Build](#deployment--build)
10. [Common Workflows](#common-workflows)
11. [Maintenance Notes](#maintenance-notes)

## Project Overview
**Name**: {{project_name}}
**Version**: {{version}}
**Type**: {{application|library|tool|service}}
**Primary Language**: {{language}}

### Description
{{2-3 paragraphs from README or package description}}

### Purpose & Goals
- Primary goal: {{main purpose}}
- Target users: {{who uses this}}
- Key value proposition: {{what problem it solves}}

### Project Status
- Development stage: {{prototype|alpha|beta|production|maintenance}}
- Activity level: {{active|maintenance|archived}}
- Last major update: {{date if discoverable}}

## Technology Stack
### Core Technologies
**Runtime Environment**: {{Node.js, Python, etc.}}
**Primary Framework/Library**: {{React, Next.js, FastAPI, etc.}}
**Language & Typing**: {{TypeScript, Python with type hints, etc.}}
**Build & Development Tools**: {{Vite, Webpack, npm, etc.}}

### Supporting Technologies
**State Management**: {{Redux, Zustand, none, etc.}}
**Styling**: {{Tailwind, CSS Modules, etc.}}
**Testing**: {{Jest, Vitest, Pytest, etc.}}
**Linting & Formatting**: {{ESLint, Prettier, etc.}}

## Project Structure

### File Naming Conventions
- Components: {{PascalCase.tsx, kebab-case.tsx, etc.}}
- Utilities: {{camelCase.ts, snake_case.py, etc.}}
- Tests: {{*.test.ts, *_test.py, etc.}}

## Agent Ecosystem
### Overview
Total agents: {{count}}
Total skills: {{count}}
Primary workflow: {{how agents/skills interact}}

For each agent:
#### Agent: {{agent_name}}
**Role**: {{one-line description}}
**Type**: {{specialist|generalist|reviewer|analyzer}}
**Location**: `{{path/to/agent/file}}`
**Status**: {{active|experimental|deprecated}}

**Primary Capabilities**
- Capability 1: {{description}}
- Capability 2: {{description}}

**Tools & Permissions**
- Tool 1: {{purpose}}
- Tool 2: {{purpose}}

**When to Use This Agent**
- Use case 1: {{description}}
- Use case 2: {{description}}

**Integration Points**
- Reads from: {{directories or files}}
- Writes to: {{directories or files}}
- Dependencies: {{other agents or tools}}

**Communication Style**
Tone: {{formal|casual|technical}}
Verbosity: {{concise|balanced|detailed}}
Audience: {{developers|reviewers|end-users}}

### Skill Registry
For each skill:
#### Skill: {{skill_name}}
**Purpose**: {{one-line description}}
**Location**: `{{path/to/skill/SKILL.md}}`
**Type**: {{task-specific instruction|workflow|pattern}}

**What It Does**
- Capability 1: {{description}}
- Capability 2: {{description}}

**When to Use**
- Use case 1: {{description}}
- Use case 2: {{description}}

**Integration Points**
- References: {{AGENTS.md sections, other agents, etc.}}
- Used by: {{which agents or workflows}}

## Development Conventions
### Code Style
**General Principles**
- Principle 1: {{e.g., "Prefer functional components"}}
- Principle 2: {{e.g., "Use explicit types, avoid 'any'"}}

**Naming Conventions**
- Variables: {{camelCase, snake_case, etc.}}
- Functions: {{conventions}}
- Classes: {{PascalCase, etc.}}
- Constants: {{UPPER_SNAKE_CASE, etc.}}

**Import Conventions**: {{how imports organized}}
**Comment Style**: {{JSDoc, inline comments, etc.}}

### Git Conventions
**Branch Naming**: {{feature/*, bugfix/*, etc.}}
**Commit Message Format**: {{conventional commits, etc.}}
**PR Requirements**: {{tests, reviews, etc.}}

## Key Dependencies
### Critical Dependencies
#### {{dependency_name}} (v{{version}})
**Purpose**: {{Why this exists}}
**Usage**: {{Where and how used}}
**Alternatives Considered**: {{If known}}

### Dependency Health
- Outdated dependencies: {{count or list}}
- Security vulnerabilities: {{count or severity}}
- Deprecated packages: {{list if any}}

## Architectural Patterns
### Overall Architecture
{{Describe high-level architecture: MVC, microservices, monolith, layered, etc.}}

### Common Patterns
**Pattern: {{pattern_name}}**
- Where used: {{directories or modules}}
- Purpose: {{what problem it solves}}
- Example: {{brief code example or file reference}}

### Data Flow

### Error Handling
- Errors are caught at: {{where}}
- Error propagation: {{how errors bubble up}}
- User-facing errors: {{how presented}}
- Logging: {{what gets logged and where}}

## Testing Strategy
### Test Organization
Tests are located in: {{test directories}}
Test file naming: {{pattern}}
Test runner: {{Jest, Vitest, Pytest, etc.}}

### Coverage Expectations
- Unit test coverage target: {{percentage}}
- Integration test coverage: {{approach}}
- End-to-end tests: {{whether they exist}}

### Testing Conventions
**Unit Tests**: {{What gets unit tested and how}}
**Integration Tests**: {{Integration test approach}}
**Test Structure**: {{AAA, Given-When-Then, etc.}}
**Mocking Strategy**: {{How mocks used}}

## Deployment & Build
### Build Process
**Development Build**: `{{command}}`
**Production Build**: `{{command}}`
**Build Output**: {{where builds go}}

### Deployment
- Platform: {{Vercel, AWS, Docker, etc.}}
- Environment variables: {{how managed}}
- Deployment trigger: {{git push, manual, CI/CD}}
- Rollback strategy: {{how to revert}}

### CI/CD
- Pipeline tool: {{GitHub Actions, GitLab CI, etc.}}
- Stages: {{lint → test → build → deploy}}
- Automated checks: {{what must pass}}

## Common Workflows
### Workflow: Adding a New Feature
**Steps**:
1. {{Create branch}}
2. {{Planning/design}}
3. {{Implementation}}
4. {{Testing}}
5. {{Review and deployment}}

**Agent Assistance**: {{Which agents help}}

### Workflow: Fixing a Bug
**Steps**: {{Bug reproduction → Root cause → Fix → Test → Deploy}}
**Agent Assistance**: {{How agents help}}

## Maintenance Notes
### Known Issues
- Issue 1: {{description and impact}}
- Issue 2: {{description and impact}}

### Future Enhancements
- Enhancement 1: {{description}}
- Enhancement 2: {{description}}

### Update Triggers
AGENTS.md should be updated when:
- [ ] New agents are added or removed
- [ ] New skills are added or removed
- [ ] Project structure changes significantly
- [ ] New major dependencies are added
- [ ] Architectural patterns change
- [ ] Development conventions are updated
- [ ] Testing strategy evolves
- [ ] Deployment process changes

## Context Update Decision Logic

### Trigger: New or Modified Agent/Skill Files
**Locations to Watch**:
- `.cursor/agents/**/*`, `.cursor/skills/**/*`
- `.cline/agents/**/*`, `.agents/**/*`, `agents/**/*`

**Action**: Always update Agent Ecosystem section.

### Trigger: Configuration File Changes
**Files to Watch**: `package.json`, `requirements.txt`, `.eslintrc.*`, `tsconfig.json`, `*config.*`, `.github/workflows/*`, `Dockerfile`

**Action**: Update relevant sections (Dependencies, Build, Conventions, CI/CD).

### Trigger: Major Structural Changes
**Patterns to Watch**: New root directories, directory renames, package reorganization

**Action**: Update Project Structure and Architectural Patterns.

### False Positives (Don't Trigger Updates)
- Regular code changes in source files
- Minor dependency version bumps
- Temporary or experimental files
- Generated files or build artifacts

## Generation Workflow

1. **Initial Scan**: Scan project with specified depth (shallow/medium/deep)
2. **Extract Context**: Extract information from agents, configs, docs
3. **Generate Document**: Build complete AGENTS.md following structure
4. **Create Cursor Rule**: If `auto_watch` is true, generate `.cursor/rules/agents-maintainer.md`
5. **Verification**: Check paths, references, TOC, timestamp
6. **Summary Report**: Provide statistics and next steps

## Quality Standards

- **Completeness**: All sections present
- **Accuracy**: Information matches actual project state
- **Clarity**: Technical but accessible
- **Currency**: Timestamp accurate, up-to-date
- **Maintainability**: Structure supports easy updates
- **Actionability**: Readers know what to do