The AI Orchestrator - Cursor IDE Rules

Project Context

Project: The AI Orchestrator - AI-Augmented Full-Stack Engineering Bootcamp
Target Audience: Justice-impacted developers with CS fundamentals
Philosophy: Fundamentals first, AI as enhancement (not replacement)
Constraint: Zero-cost mandate - all tools must have free tiers
Languages: Python (primary), JavaScript (web deployment)

Core Principles

1. Fundamentals Over Shortcuts

Never suggest AI-generated code without explaining the underlying CS concept
Always discuss time/space complexity (Big O notation) for algorithms
Prefer teaching moments over quick fixes
When refactoring, explain WHY the improvement matters

2. Zero-Cost Infrastructure

Only recommend tools with free tiers
Default to: Gemini (free), Claude Sonnet (free web), GPT-4o-mini
Vector DB: ChromaDB (local) or Pinecone (free tier)
Deployment: Vercel/Netlify/GitHub Pages (free)
Never suggest paid-only solutions

3. Justice-Focused Accessibility

Assume limited hardware (explain if task requires 16GB+ RAM)
Provide offline alternatives when possible
Consider unreliable internet (batch operations, local-first design)
Use inclusive language and avoid assumptions about background

Code Style Standards

Python

PEP 8 compliance (use Black formatter, line length: 88)
Type hints required for all function signatures
Docstrings required (Google style format)
Naming conventions:
- Functions:
```
snake_case
```
- Classes:
```
PascalCase
```
- Constants:
```
SCREAMING_SNAKE_CASE
```
- Private methods:
```
_leading_underscore
```

JavaScript/TypeScript

Modern ES6+ syntax
Functional style preferred over classes (unless React components)
Destructuring for clarity
Arrow functions for short callbacks
Const/let (never var)

File Naming

Python files:
```
snake_case.py
```
(except classes:
```
ClassName.py
```
)
JavaScript:
```
kebab-case.js
```
or
```
PascalCase.jsx
```
(components)
Markdown:
```
UPPERCASE.md
```
(top-level) or
```
kebab-case.md
```
(nested)

Documentation Standards

What to Include

Purpose: One-sentence description of file/function
Algorithm: If non-trivial, explain the approach
Complexity: Time and space Big O
Examples: Show expected input → output
Edge cases: What breaks this? How is it handled?

What to AVOID

❌ Generic emojis (🚀 ✅ ❌ etc.) - use SVG icons or text
❌ Placeholder comments (
```
# TODO: implement later
```
)
❌ Redundant documentation (if code is self-documenting)
❌ Copy-paste boilerplate from other projects
❌ "As discussed earlier" (every doc should be standalone)

Premium Elements

✅ SVG icons from brand palette
✅ Mermaid diagrams for architecture
✅ Tables for comparisons/specifications
✅ Code examples with expected output
✅ Analogies from cooking/gaming/90s movies (sparingly)

Code Example Template

def function_name(param: type) -> return_type:
    """
    Brief one-line description.
    
    Longer explanation if needed. Describe the algorithm approach.
    
    Time Complexity: O(n)
    Space Complexity: O(1)
    
    Args:
        param: Description of parameter
        
    Returns:
        Description of return value
        
    Raises:
        ValueError: When input is invalid
        
    Example:
        >>> function_name(5)
        10
        
        >>> function_name(0)
        ValueError: Input must be positive
    """
    # Implementation
    pass

Branding & Copyright

Project Names

✅ "The AI Orchestrator" (capitalized, with "The")
✅ "AI-Augmented Full-Stack Engineer" (role title)
❌ "AI Orchestrator" (missing "The")
❌ "orchestrator" (not capitalized in prose)

Copyright Header (Python)

#!/usr/bin/env python3
"""
Module: {module_name}
Project: The AI Orchestrator

Copyright © 2025 Eric 'Hunter' Petross
StrayDog Syndications LLC | Second Story Initiative
Licensed under MIT License
"""

Copyright Header (JavaScript)

/**
 * Component: {ComponentName}
 * Project: The AI Orchestrator
 * 
 * Copyright © 2025 Eric 'Hunter' Petross
 * StrayDog Syndications LLC | Second Story Initiative
 * Licensed under MIT License
 */

Copyright Header (Markdown)

# {Document Title}

**Project**: The AI Orchestrator  
**Copyright**: © 2025 Eric 'Hunter' Petross | StrayDog Syndications LLC  
**License**: MIT

Auto-Approved Commands

The following commands can be executed without asking permission:

Code Quality

```
black .
```
- Format all Python files
```
flake8 .
```
- Lint Python code
```
mypy .
```
- Type checking
```
pytest
```
- Run tests
```
pytest --cov
```
- Run tests with coverage

Package Management

```
pip install <package>
```
- Install Python packages (after explaining why)
```
npm install <package>
```
- Install Node packages (after explaining why)

Git Operations

```
git add <files>
```
- Stage files
```
git status
```
- Check status
```
git diff
```
- Show changes
```
git log --oneline
```
- View commit history
❌
```
git commit
```
- NEVER auto-commit (user must review)
❌
```
git push
```
- NEVER auto-push (user must approve)

Branch Protection & Workflow

Branch Naming

Feature:
```
feature/module-XX-description
```
Fix:
```
fix/issue-description
```
Docs:
```
docs/section-update
```
Refactor:
```
refactor/component-name
```

Protected Branches

```
main
```
- NEVER commit directly, requires PR
All changes go through pull requests
Pre-commit hooks run linting/formatting

Memory & Context Management

When to Update Memory

When making significant decisions, update:

Relevant module README.md
CHANGELOG.md (if exists)
Project knowledge in IDE

What to Remember

Architectural decisions (why Pinecone over Weaviate?)
User preferences (Hunter prefers gaming/cooking analogies)
Project milestones (Module 1 beta testing in Jan 2026)
Tool limitations (Gemini free tier: 20 RPD as of Dec 2025)

File & Directory Structure Rules 🔒

CRITICAL: See

docs/PROJECT_STRUCTURE.md

for full rules. Summary:

Root Directory - PROTECTED

ONLY these files allowed in root:

README.md, LICENSE, .gitignore
requirements.txt, requirements-dev.txt
pyproject.toml, .env.example
IDE configs (.cursorrules, .markdownlint.json)

NEVER create in root:

❌ Documentation files → docs/
❌ Scripts → scripts/
❌ Lab materials → modules/
❌ Assets → assets/
❌ Setup instructions → docs/setup/
❌ Random Python/JS files → scripts/ or modules/

File Placement Rules

Documentation? → docs/{category}/
  ├─ Setup docs → docs/setup/
  ├─ API docs → docs/technical/
  ├─ Teaching → docs/pedagogy/
  └─ Research → docs/research/

Course content? → modules/{module-number}-{name}/
  ├─ Lectures → lectures/
  ├─ Labs → labs/
  ├─ Projects → projects/
  └─ Resources → resources/

Script? → scripts/{category}/
Media? → assets/{category}/
Template? → templates/{type}/
Test? → tests/{matching-structure}/

Naming Conventions (ENFORCED)

Python:

snake_case.py

(or

ClassName.py

for class files) JavaScript:

kebab-case.js

(or

ComponentName.jsx

for React) Markdown:

UPPERCASE.md

(root docs) or

kebab-case.md

(nested) Notebooks:

01-descriptive-name.ipynb

(numbered, kebab-case)

Forbidden:

❌ Spaces in filenames
❌ Generic names (file.py, test.js, utils.py)
❌ Version suffixes (module_v2.py, final-FINAL.js)
❌ Special characters (#, @, parentheses)

Pre-Creation Checklist

Before creating any file, ask:

Does it belong in root? (99% of time: NO)
What's the correct category? (docs, scripts, modules, assets)
Does the name follow conventions?
Is there a README in the target directory?
Will this exceed directory size limits?

When in doubt: Ask user or place in

docs/notes/

temporarily

Memory Format

Remember: [Decision/Fact]
Context: [Why this matters]
Impact: [What changes because of this]

Token Optimization

Cost Hierarchy (Cheapest → Most Expensive)

Gemini 2.0 Flash: $0.001/1k tokens (default for simple tasks)
Claude 3.5 Haiku: $0.0025/1k tokens (code completion)
GPT-4o-mini: $0.005/1k tokens (balanced option)
Claude 3.5 Sonnet: $0.015/1k tokens (complex reasoning)
GPT-4o: $0.005/1k input (when GPT-specific features needed)

Optimization Strategies

Use semantic chunking (only send relevant file portions)
Leverage prompt caching (mark static context)
Batch similar requests
Reference previous responses by ID, not full text
Avoid repeating project context in every message

Model Selection Guide

Autocomplete: Gemini Flash (fastest, free tier)
Code review: Claude Sonnet (best bug detection)
Explanation: Gemini Flash (fast, educational)
Refactoring: Claude Sonnet (architectural understanding)
Test generation: GPT-4o-mini (edge case coverage)
Documentation: Gemini Flash (cost-effective prose)

Special Instructions

For Module Development

When creating curriculum modules:

Start with learning objectives (what will students know/do?)
Design hands-on labs (20-30 min focused exercises)
Create mini-projects (3-5 hours, proof of mastery)
Write assessment rubrics (test understanding, not copying)
Include "before/after" code examples

For Code Review

When reviewing code:

Check for bugs and edge cases
Analyze time/space complexity (Big O)
Verify adherence to project style
Suggest optimizations with explanations
Identify security vulnerabilities
Confirm error handling

For Refactoring

When refactoring:

Explain current complexity (Big O)
Propose optimized approach
Show "before" and "after" code
Explain tradeoffs (memory vs speed)
Verify tests still pass
Update documentation

For Explanations

When explaining code:

Assume audience knows OOP and Big O
Use analogies from cooking/gaming/90s movies (sparingly)
Focus on "why" not just "what"
Include visual aids (Mermaid diagrams)
Provide concrete examples
Check understanding with questions

Error Patterns to Avoid

Common Mistakes

❌ Suggesting O(n²) solution when O(n) exists
❌ Using paid APIs without free-tier alternatives
❌ Generic variable names (
```
data
```
,
```
result
```
,
```
temp
```
)
❌ Missing type hints on function signatures
❌ No docstrings on public functions
❌ Hardcoded values instead of constants
❌ No error handling on external API calls

Quality Gates

Before suggesting code, verify:

Follows project naming conventions
Includes type hints (Python) or JSDoc (JavaScript)
Has docstring with complexity analysis
Handles edge cases (None, empty, max values)
Uses most efficient algorithm (Big O)
Works on free-tier infrastructure
Includes example usage with output

Pedagogy Guidelines

The "Chinese Room Architect" Frame

Student = architect who designs the system
AI = operator in the room following rules
Student's job: design rules, verify outputs, catch edge cases
AI's job: execute tasks quickly, suggest optimizations

Teaching Approach

Concept: Explain the "why" (2-3 min)
Example: Show concrete code (5 min)
Practice: Hands-on exercise (20-30 min)
Reflection: What did you learn? (5 min)

Complexity Ladder

Start simple (O(1), O(n))
Build to intermediate (O(n log n))
Graduate to advanced (O(n²), optimization)
Never skip fundamentals for AI shortcuts

Response Style

Tone

Professional but approachable
Empowering, not condescending
Assumes competence (they have CS fundamentals)
Patient with questions
Honest about tradeoffs

Structure

Lead with direct answer
Follow with explanation
Provide examples
Suggest next steps
Ask clarifying questions only when needed

Length

Concise by default
Detailed when complexity warrants
Use headings for long responses
Break into sections with clear hierarchy

Final Reminders

This is an educational project - prioritize learning over speed
Justice-impacted students face unique challenges - be sensitive
Free-tier constraints breed creativity - embrace them
Code is communication - write for humans, not just machines
Every decision should have a documented rationale

Version: 1.0.0
Last Updated: December 23, 2025
Maintainer: Eric 'Hunter' Petross
Project: The AI Orchestrator

The AI Orchestrator - Cursor IDE Rules

Project Context

Project: The AI Orchestrator - AI-Augmented Full-Stack Engineering Bootcamp
Target Audience: Justice-impacted developers with CS fundamentals
Philosophy: Fundamentals first, AI as enhancement (not replacement)
Constraint: Zero-cost mandate - all tools must have free tiers
Languages: Python (primary), JavaScript (web deployment)

Core Principles

1. Fundamentals Over Shortcuts

Never suggest AI-generated code without explaining the underlying CS concept
Always discuss time/space complexity (Big O notation) for algorithms
Prefer teaching moments over quick fixes
When refactoring, explain WHY the improvement matters

2. Zero-Cost Infrastructure

Only recommend tools with free tiers
Default to: Gemini (free), Claude Sonnet (free web), GPT-4o-mini
Vector DB: ChromaDB (local) or Pinecone (free tier)
Deployment: Vercel/Netlify/GitHub Pages (free)
Never suggest paid-only solutions

3. Justice-Focused Accessibility

Assume limited hardware (explain if task requires 16GB+ RAM)
Provide offline alternatives when possible
Consider unreliable internet (batch operations, local-first design)
Use inclusive language and avoid assumptions about background

Code Style Standards

Python

PEP 8 compliance (use Black formatter, line length: 88)
Type hints required for all function signatures
Docstrings required (Google style format)
Naming conventions:
- Functions:
```
snake_case
```
- Classes:
```
PascalCase
```
- Constants:
```
SCREAMING_SNAKE_CASE
```
- Private methods:
```
_leading_underscore
```

JavaScript/TypeScript

Modern ES6+ syntax
Functional style preferred over classes (unless React components)
Destructuring for clarity
Arrow functions for short callbacks
Const/let (never var)

File Naming

Python files:
```
snake_case.py
```
(except classes:
```
ClassName.py
```
)
JavaScript:
```
kebab-case.js
```
or
```
PascalCase.jsx
```
(components)
Markdown:
```
UPPERCASE.md
```
(top-level) or
```
kebab-case.md
```
(nested)

Documentation Standards

What to Include

Purpose: One-sentence description of file/function
Algorithm: If non-trivial, explain the approach
Complexity: Time and space Big O
Examples: Show expected input → output
Edge cases: What breaks this? How is it handled?

What to AVOID

❌ Generic emojis (🚀 ✅ ❌ etc.) - use SVG icons or text
❌ Placeholder comments (
```
# TODO: implement later
```
)
❌ Redundant documentation (if code is self-documenting)
❌ Copy-paste boilerplate from other projects
❌ "As discussed earlier" (every doc should be standalone)

Premium Elements

✅ SVG icons from brand palette
✅ Mermaid diagrams for architecture
✅ Tables for comparisons/specifications
✅ Code examples with expected output
✅ Analogies from cooking/gaming/90s movies (sparingly)

Code Example Template

def function_name(param: type) -> return_type:
    """
    Brief one-line description.
    
    Longer explanation if needed. Describe the algorithm approach.
    
    Time Complexity: O(n)
    Space Complexity: O(1)
    
    Args:
        param: Description of parameter
        
    Returns:
        Description of return value
        
    Raises:
        ValueError: When input is invalid
        
    Example:
        >>> function_name(5)
        10
        
        >>> function_name(0)
        ValueError: Input must be positive
    """
    # Implementation
    pass

Branding & Copyright

Project Names

✅ "The AI Orchestrator" (capitalized, with "The")
✅ "AI-Augmented Full-Stack Engineer" (role title)
❌ "AI Orchestrator" (missing "The")
❌ "orchestrator" (not capitalized in prose)

Copyright Header (Python)

#!/usr/bin/env python3
"""
Module: {module_name}
Project: The AI Orchestrator

Copyright © 2025 Eric 'Hunter' Petross
StrayDog Syndications LLC | Second Story Initiative
Licensed under MIT License
"""

Copyright Header (JavaScript)

/**
 * Component: {ComponentName}
 * Project: The AI Orchestrator
 * 
 * Copyright © 2025 Eric 'Hunter' Petross
 * StrayDog Syndications LLC | Second Story Initiative
 * Licensed under MIT License
 */

Copyright Header (Markdown)

# {Document Title}

**Project**: The AI Orchestrator  
**Copyright**: © 2025 Eric 'Hunter' Petross | StrayDog Syndications LLC  
**License**: MIT

Auto-Approved Commands

The following commands can be executed without asking permission:

Code Quality

```
black .
```
- Format all Python files
```
flake8 .
```
- Lint Python code
```
mypy .
```
- Type checking
```
pytest
```
- Run tests
```
pytest --cov
```
- Run tests with coverage

Package Management

```
pip install <package>
```
- Install Python packages (after explaining why)
```
npm install <package>
```
- Install Node packages (after explaining why)

Git Operations

```
git add <files>
```
- Stage files
```
git status
```
- Check status
```
git diff
```
- Show changes
```
git log --oneline
```
- View commit history
❌
```
git commit
```
- NEVER auto-commit (user must review)
❌
```
git push
```
- NEVER auto-push (user must approve)

Branch Protection & Workflow

Branch Naming

Feature:
```
feature/module-XX-description
```
Fix:
```
fix/issue-description
```
Docs:
```
docs/section-update
```
Refactor:
```
refactor/component-name
```

Protected Branches

```
main
```
- NEVER commit directly, requires PR
All changes go through pull requests
Pre-commit hooks run linting/formatting

Memory & Context Management

When to Update Memory

When making significant decisions, update:

Relevant module README.md
CHANGELOG.md (if exists)
Project knowledge in IDE

What to Remember

Architectural decisions (why Pinecone over Weaviate?)
User preferences (Hunter prefers gaming/cooking analogies)
Project milestones (Module 1 beta testing in Jan 2026)
Tool limitations (Gemini free tier: 20 RPD as of Dec 2025)

File & Directory Structure Rules 🔒

CRITICAL: See

docs/PROJECT_STRUCTURE.md

for full rules. Summary:

Root Directory - PROTECTED

ONLY these files allowed in root:

README.md, LICENSE, .gitignore
requirements.txt, requirements-dev.txt
pyproject.toml, .env.example
IDE configs (.cursorrules, .markdownlint.json)

NEVER create in root:

❌ Documentation files → docs/
❌ Scripts → scripts/
❌ Lab materials → modules/
❌ Assets → assets/
❌ Setup instructions → docs/setup/
❌ Random Python/JS files → scripts/ or modules/

File Placement Rules

Documentation? → docs/{category}/
  ├─ Setup docs → docs/setup/
  ├─ API docs → docs/technical/
  ├─ Teaching → docs/pedagogy/
  └─ Research → docs/research/

Course content? → modules/{module-number}-{name}/
  ├─ Lectures → lectures/
  ├─ Labs → labs/
  ├─ Projects → projects/
  └─ Resources → resources/

Script? → scripts/{category}/
Media? → assets/{category}/
Template? → templates/{type}/
Test? → tests/{matching-structure}/

Naming Conventions (ENFORCED)

Python:

snake_case.py

(or

ClassName.py

for class files) JavaScript:

kebab-case.js

(or

ComponentName.jsx

for React) Markdown:

UPPERCASE.md

(root docs) or

kebab-case.md

(nested) Notebooks:

01-descriptive-name.ipynb

(numbered, kebab-case)

Forbidden:

❌ Spaces in filenames
❌ Generic names (file.py, test.js, utils.py)
❌ Version suffixes (module_v2.py, final-FINAL.js)
❌ Special characters (#, @, parentheses)

Pre-Creation Checklist

Before creating any file, ask:

Does it belong in root? (99% of time: NO)
What's the correct category? (docs, scripts, modules, assets)
Does the name follow conventions?
Is there a README in the target directory?
Will this exceed directory size limits?

When in doubt: Ask user or place in

docs/notes/

temporarily

Memory Format

Remember: [Decision/Fact]
Context: [Why this matters]
Impact: [What changes because of this]

Token Optimization

Cost Hierarchy (Cheapest → Most Expensive)

Gemini 2.0 Flash: $0.001/1k tokens (default for simple tasks)
Claude 3.5 Haiku: $0.0025/1k tokens (code completion)
GPT-4o-mini: $0.005/1k tokens (balanced option)
Claude 3.5 Sonnet: $0.015/1k tokens (complex reasoning)
GPT-4o: $0.005/1k input (when GPT-specific features needed)

Optimization Strategies

Use semantic chunking (only send relevant file portions)
Leverage prompt caching (mark static context)
Batch similar requests
Reference previous responses by ID, not full text
Avoid repeating project context in every message

Model Selection Guide

Autocomplete: Gemini Flash (fastest, free tier)
Code review: Claude Sonnet (best bug detection)
Explanation: Gemini Flash (fast, educational)
Refactoring: Claude Sonnet (architectural understanding)
Test generation: GPT-4o-mini (edge case coverage)
Documentation: Gemini Flash (cost-effective prose)

Special Instructions

For Module Development

When creating curriculum modules:

Start with learning objectives (what will students know/do?)
Design hands-on labs (20-30 min focused exercises)
Create mini-projects (3-5 hours, proof of mastery)
Write assessment rubrics (test understanding, not copying)
Include "before/after" code examples

For Code Review

When reviewing code:

Check for bugs and edge cases
Analyze time/space complexity (Big O)
Verify adherence to project style
Suggest optimizations with explanations
Identify security vulnerabilities
Confirm error handling

For Refactoring

When refactoring:

Explain current complexity (Big O)
Propose optimized approach
Show "before" and "after" code
Explain tradeoffs (memory vs speed)
Verify tests still pass
Update documentation

For Explanations

When explaining code:

Assume audience knows OOP and Big O
Use analogies from cooking/gaming/90s movies (sparingly)
Focus on "why" not just "what"
Include visual aids (Mermaid diagrams)
Provide concrete examples
Check understanding with questions

Error Patterns to Avoid

Common Mistakes

❌ Suggesting O(n²) solution when O(n) exists
❌ Using paid APIs without free-tier alternatives
❌ Generic variable names (
```
data
```
,
```
result
```
,
```
temp
```
)
❌ Missing type hints on function signatures
❌ No docstrings on public functions
❌ Hardcoded values instead of constants
❌ No error handling on external API calls

Quality Gates

Before suggesting code, verify:

Follows project naming conventions
Includes type hints (Python) or JSDoc (JavaScript)
Has docstring with complexity analysis
Handles edge cases (None, empty, max values)
Uses most efficient algorithm (Big O)
Works on free-tier infrastructure
Includes example usage with output

Pedagogy Guidelines

The "Chinese Room Architect" Frame

Student = architect who designs the system
AI = operator in the room following rules
Student's job: design rules, verify outputs, catch edge cases
AI's job: execute tasks quickly, suggest optimizations

Teaching Approach

Concept: Explain the "why" (2-3 min)
Example: Show concrete code (5 min)
Practice: Hands-on exercise (20-30 min)
Reflection: What did you learn? (5 min)

Complexity Ladder

Start simple (O(1), O(n))
Build to intermediate (O(n log n))
Graduate to advanced (O(n²), optimization)
Never skip fundamentals for AI shortcuts

Response Style

Tone

Professional but approachable
Empowering, not condescending
Assumes competence (they have CS fundamentals)
Patient with questions
Honest about tradeoffs

Structure

Lead with direct answer
Follow with explanation
Provide examples
Suggest next steps
Ask clarifying questions only when needed

Length

Concise by default
Detailed when complexity warrants
Use headings for long responses
Break into sections with clear hierarchy

Final Reminders

This is an educational project - prioritize learning over speed
Justice-impacted students face unique challenges - be sensitive
Free-tier constraints breed creativity - embrace them
Code is communication - write for humans, not just machines
Every decision should have a documented rationale

Version: 1.0.0
Last Updated: December 23, 2025
Maintainer: Eric 'Hunter' Petross
Project: The AI Orchestrator

The AI Orchestrator - Cursor IDE Rules

Related Skills

.cursorrules

This is an Elixir library that recompiles Elixir code in its AST form.

This is AI chat app called DeeperSeeker.