SlyyCooper cursorrules-architect .cursorrules file for Python (stars: 15)

The main goal is to provide comprehensive project analysis and maintain the `.cursorrules` file, which defines project standards and AI behavior guidelines for your codebase.
- **Anthropic DEVELOPMENT**: You are required to use the brand new latest model: **'claude-3-5-sonnet-20241022'**!!
* !!!NEVER use 'claude-3-sonnet-20240229' or 'claude-3-haiku-20240307' or 'claude-3-opus-20240229'!!!
* **OpenAI DEVELOPMENT**: You are required to use the brand new latest model: **'o1-preview'**!!
* !!!NEVER use 'gpt-4o' or 'gpt-4' or 'gpt-4-turbo' or 'gpt-4-turbo-preview', 'gpt-3.5'!!!

<!-- BEGIN_STRUCTURE -->
# Project Directory Structure
------------------------------
```
📁 cursorrules-architect
├── 📁 agents
│   ├── 📄 dependency_analyzer_agent.py
│   └── 📄 project_architect_agent.py
├── 📁 architects
│   ├── 📄 monitoring-cursorrules.py
│   ├── 📄 project_doc_generator.py
│   └── 📄 project_extractor.py
├── 📁 docs
│   └── 📄 directory_structure.md
├── 📁 utils
│   └── 📄 project_doc_generator.py
├── 📄 .env
└── 📄 README.md
```
<!-- END_STRUCTURE -->
<tree_structure>
.
├── .cursorrules
├── .env
├── .gitignore
├── CONTRIBUTING.md
├── README.md
├── agents
│   ├── dependency_analyzer_agent.py
│   ├── project_architect_agent.py
├── main.py
├── requirements.txt
├── seperate_architects
│   ├── project_doc_generator.py
├── utils
│   ├── __init__.py
│   ├── __pycache__
│   │   ├── project_doc_generator.cpython-311.pyc
│   ├── monitoring-cursorrules.py
│   ├── project_doc_generator.py
</tree_structure>

The system uses a sophisticated 5-phase analysis approach that alternates between Claude-3.5-Sonnet and o1-preview models for different types of analysis. Here's how it works:

1. **Phase 1: Initial Discovery** (Claude-3.5-Sonnet)
   - Uses three parallel agents:
     1. Structure Agent: Analyzes directory/file organization
     2. Dependency Agent: Investigates packages and libraries
     3. Tech Stack Agent: Identifies frameworks and technologies
   - You see multiple "Phase 1" logs because each agent runs independently

2. **Phase 2: Methodical Planning** (o1-preview)
   - Takes the findings from all Phase 1 agents
   - Creates a detailed analysis plan including:
     - File-by-file examination approach
     - Critical areas needing investigation
     - Documentation requirements
     - Inter-dependency mapping method

3. **Phase 3: Deep Analysis** (Claude-3.5-Sonnet)
   - Uses four specialized agents:
     1. Code Analysis Agent: Examines logic patterns
     2. Dependency Mapping Agent: Maps file relationships
     3. Architecture Agent: Studies design patterns
     4. Documentation Agent: Creates documentation

4. **Phase 4: Synthesis** (o1-preview)
   - Reviews and synthesizes all findings from Phase 3
   - Updates analysis directions
   - Identifies areas needing deeper investigation

5. **Phase 5: Consolidation** (Claude-3.5-Sonnet)
   - Final consolidation of all findings
   - Creates comprehensive documentation
   - Prepares report for final analysis

The reason you see multiple Phase 1/2 logs is because:
- Phase 1 runs multiple agents in parallel (hence multiple Claude API calls)
- Each agent works independently but simultaneously
- The system waits for all agents to complete before moving to the next phase

The flow looks like this:
```mermaid
graph TD
    A[Start] --> B[Phase 1: Initial Discovery]
    B -->|Structure Agent| C[Claude Analysis]
    B -->|Dependency Agent| D[Claude Analysis]
    B -->|Tech Stack Agent| E[Claude Analysis]
    
    C & D & E --> F[Phase 2: Planning]
    F -->|o1-preview| G[Create Analysis Plan]
    
    G --> H[Phase 3: Deep Analysis]
    H -->|Multiple Agents| I[Detailed Analysis]
    
    I --> J[Phase 4: Synthesis]
    J -->|o1-preview| K[Synthesize Findings]
    
    K --> L[Phase 5: Consolidation]
    L -->|Claude| M[Final Report]
```

This multi-phase approach ensures:
1. Thorough analysis from different perspectives
2. Cross-validation of findings
3. Progressive refinement of understanding
4. Comprehensive documentation
5. Leveraging the strengths of both Claude and o1-preview models

### Number of API calls per phase

1. **Phase 1** appears multiple times (3 times) because it runs three agents in parallel:
   ```python
   # From main.py
   self.phase1_agents = [
       ClaudeAgent("Structure Agent", "analyzing directory and file organization", [...]),
       ClaudeAgent("Dependency Agent", "investigating packages and libraries", [...]),
       ClaudeAgent("Tech Stack Agent", "identifying frameworks and technologies", [...])
   ]
   ```
   - Each agent makes its own API call to Claude
   - They run simultaneously (using `asyncio.gather`)
   - That's why you see three separate "Phase 1" logs with HTTP requests

2. **Phase 2** appears multiple times because:
   - It processes the results from each Phase 1 agent
   - Makes API calls to o1-preview to plan next steps based on each agent's findings
   - The logs show the HTTP requests to OpenAI's API

3. **Phases 3, 4, and 5** only appear once because:
   - Phase 3: While it uses multiple agents, they're batched into a single phase execution
   - Phase 4: Single synthesis step using o1-preview
   - Phase 5: Single consolidation step using Claude

Here's the count of API calls per phase in one complete run:
```
Phase 1: 3 calls (one per agent) to Claude
Phase 2: Multiple calls to o1-preview for planning
Phase 3: 1 batch call to Claude (though using multiple agents internally)
Phase 4: 1 call to o1-preview
Phase 5: 1 call to Claude
```

The key is in this part of `main.py`:
```python
# Phase 1: Multiple parallel agents
agent_tasks = [agent.analyze(context) for agent in self.phase1_agents]
results = await asyncio.gather(*agent_tasks)  # This runs them all at once

# Later phases: Single execution
phase3_results = await self.run_phase3(phase2_results, tree)  # One batch
phase4_results = await self.run_phase4(phase3_results)        # One call
consolidated_report = await self.run_phase5(all_results)      # One call
```

So while you see multiple logs, it's still just one run through the phases - Phase 1 just happens to make multiple parallel API calls for efficiency.

Here's how the files are connected:

1. **Main Entry Point**:
   - `main.py` is the primary entry point that orchestrates the entire analysis process
   - It uses a 5-phase analysis system combining Claude-3.5-Sonnet and o1-preview models

2. **Agent System**:
   - `agents/project_architect_agent.py` and `agents/dependency_analyzer_agent.py` are specialized workers
   - They're called by `main.py` during different phases of analysis
   - The agents work independently but are orchestrated by the main analyzer

3. **Documentation System**:
   - `utils/project_doc_generator.py` is the core library for tree generation
   - `architects/project_doc_generator.py` is a higher-level interface that uses the core library
   - `utils/monitoring-cursorrules.py` monitors file changes and updates documentation

Here's the flow of how they work together:

```mermaid
graph TD
    A[main.py] -->|Orchestrates| B[Project Analysis]
    B -->|Phase 1| C[Initial Discovery]
    B -->|Phase 2| D[Methodical Planning]
    B -->|Phase 3| E[Deep Analysis]
    B -->|Phase 4| F[Synthesis]
    B -->|Phase 5| G[Consolidation]
    
    C -->|Uses| H[project_architect_agent.py]
    C -->|Uses| I[dependency_analyzer_agent.py]
    
    H -->|Generates Trees| J[utils/project_doc_generator.py]
    I -->|Analyzes Dependencies| K[Package Files]
    
    L[seperate_architects/project_doc_generator.py] -->|Uses| J
    M[utils/monitoring-cursorrules.py] -->|Monitors| N[.cursorrules]
```

The files that can run independently are:
1. `utils/monitoring-cursorrules.py` - Can run standalone to monitor project changes
2. `architects/project_doc_generator.py` - Can run independently to generate documentation
3. `main.py` - The main entry point that can run the full analysis

The files that are dependent on others:
1. `agents/project_architect_agent.py` - Depends on `utils/project_doc_generator.py`
2. `agents/dependency_analyzer_agent.py` - Used by the main analyzer
3. `architects/project_doc_generator.py` - Depends on `utils/project_doc_generator.py`

So while some files can operate independently, they're designed to work together in a cohesive system where `main.py` orchestrates the full analysis workflow.

Let me break down each of these files and their purposes:

# 1. monitoring-cursorrules.py
This file is responsible for monitoring and maintaining the `.cursorrules` file in your project. Its main functions are:

- Watches for file system changes in your project directory
- Automatically updates the project structure tree in `.cursorrules` when files are added/removed/modified
- Provides an interactive CLI interface with 4 modes:
  1. Generate directory tree only
  2. Generate tree and monitor for changes
  3. Generate tree and update .cursorrules
  4. Generate tree, update .cursorrules, and monitor for changes

# 2. project_doc_generator.py
This file is an enhanced version of the documentation generator that:

- Generates directory structure documentation
- Maintains file comments and metadata
- Has the same monitoring capabilities as monitoring-cursorrules.py
- Additionally tracks and preserves comments about files in the tree structure
- Can output the documentation to markdown files

# 3. project_extractor.py
This is a sophisticated project analysis tool that:

- Uses a multi-phase analysis approach with both Claude and OpenAI models
- Has 5 distinct phases:
  1. Initial Discovery (using Claude agents)
  2. Methodical Planning (using OpenAI)
  3. Deep Analysis (using Claude agents)
  4. Synthesis (using OpenAI)
  5. Consolidation (using Claude)

The key difference between these files and the agents is:

## Architects vs Agents
- **Architects** (these files) are standalone tools that provide specific functionality:
  - monitoring-cursorrules.py → Project structure monitoring
  - project_doc_generator.py → Documentation generation
  - project_extractor.py → Project analysis and understanding

- **Agents** (in the agents/ directory) are more like specialized workers:
  - dependency_analyzer_agent.py → Analyzes project dependencies
  - project_architect_agent.py → Makes architectural decisions

Here's a diagram to help visualize the relationship:

```mermaid
graph TD
    A[Architects] --> B[monitoring-cursorrules.py]
    A --> C[project_doc_generator.py]
    A --> D[project_extractor.py]
    
    E[Agents] --> F[dependency_analyzer_agent.py]
    E --> G[project_architect_agent.py]
    
    D -->|uses| F
    D -->|uses| G
```

The architects are the tools you interact with directly, while the agents are components that are used by these tools (particularly by project_extractor.py) to perform specific analysis tasks.

Let me break down these agents and their relationships clearly.

First, I'll examine both files to understand their roles:

Search files...


Let me explain the project structure and how the agents and architects work together:

This is a sophisticated project analysis system that uses AI to analyze codebases. Here's how it works:

### 1. Agents vs Architects

**Agents** are specialized workers that perform specific analysis tasks:
- `dependency_analyzer_agent.py`: Analyzes project dependencies, versions, and compatibility
- `project_architect_agent.py`: Makes high-level architectural decisions and categorizes project components

**Architects** are higher-level tools that orchestrate the agents and provide specific functionality:
- `monitoring-cursorrules.py`: Monitors and maintains the `.cursorrules` file
- `project_doc_generator.py`: Generates project documentation
- `project_extractor.py`: Runs the complete project analysis workflow

### 2. The Analysis Flow

The system uses a sophisticated 5-phase analysis process:

1. **Initial Discovery** (Using Claude-3.5-Sonnet)
   - Structure Agent: Analyzes directory organization
   - Dependency Agent: Examines package dependencies
   - Tech Stack Agent: Identifies technologies used

2. **Methodical Planning** (Using o1-preview)
   - Processes agent findings
   - Creates detailed analysis plans

3. **Deep Analysis** (Using Claude-3.5-Sonnet)
   - Code Analysis Agent: Examines logic patterns
   - Dependency Mapping Agent: Maps file relationships
   - Architecture Agent: Studies design patterns
   - Documentation Agent: Creates documentation

4. **Synthesis** (Using o1-preview)
   - Reviews and synthesizes findings
   - Updates analysis directions

5. **Consolidation** (Using Claude-3.5-Sonnet)
   - Combines all findings
   - Prepares final documentation

### 3. Key Features

- Uses modern AI models (Claude-3.5-Sonnet-20241022 and o1-preview)
- Real-time progress tracking with rich console output
- Comprehensive dependency analysis
- Automatic documentation generation
- Project structure monitoring
- Security-first approach (no storage of sensitive data)

The main goal is to provide comprehensive project analysis and maintain the `.cursorrules` file, which defines project standards and AI behavior guidelines for your codebase.