AI Orchestrator Development Rules

Full-stack development rules for The AI Orchestrator, an AI-augmented engineering bootcamp targeting justice-impacted developers with CS fundamentals.

Core Philosophy

You are working on an educational project with three guiding principles:

1. **Fundamentals Over Shortcuts** - Never suggest AI-generated code without explaining the underlying CS concept. Always discuss time/space complexity (Big O notation).

2. **Zero-Cost Infrastructure** - Only recommend tools with free tiers (Gemini, Claude Sonnet free web, GPT-4o-mini, ChromaDB, Pinecone free tier, Vercel/Netlify/GitHub Pages).

3. **Justice-Focused Accessibility** - Assume limited hardware, provide offline alternatives, consider unreliable internet, use inclusive language.

Step-by-Step Instructions

1. Before Writing Any Code

Read existing files first to understand context

Check if the concept requires CS fundamentals explanation

Verify the solution uses the most efficient algorithm (optimal Big O)

Confirm all tools/dependencies have free tiers

Consider hardware constraints (explain if task requires 16GB+ RAM)

2. Code Style Requirements

**Python:**

Use PEP 8 compliance (Black formatter, 88 character line length)

Add type hints for all function signatures

Write Google-style docstrings with complexity analysis

Naming: `snake_case` functions, `PascalCase` classes, `SCREAMING_SNAKE_CASE` constants, `_leading_underscore` private methods

Files: `snake_case.py` (except `ClassName.py` for class files)

**JavaScript/TypeScript:**

Use modern ES6+ syntax with functional style preferred

Destructuring for clarity, arrow functions for callbacks

Use const/let (never var)

Files: `kebab-case.js` or `PascalCase.jsx` for components

3. Documentation Standards

Every function/module must include:

```python

def function_name(param: type) -> return_type:

"""

Brief one-line description.

Longer explanation of 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)

"""

pass

```

**Include:** Purpose, algorithm explanation, complexity, examples, edge cases

**Avoid:** Generic emojis (🚀 ✅ ❌), placeholder TODOs, redundant comments, copy-paste boilerplate

**Use:** SVG icons from brand palette, Mermaid diagrams, comparison tables, code examples with output

4. Copyright Headers

**Python:**

```python

#!/usr/bin/env python3

"""

Module: {module_name}

Project: The AI Orchestrator

StrayDog Syndications LLC | Second Story Initiative

Licensed under MIT License

"""

```

**JavaScript:**

```javascript

/**

* Component: {ComponentName}

* Project: The AI Orchestrator

* StrayDog Syndications LLC | Second Story Initiative

* Licensed under MIT License

```

5. File & Directory Structure (CRITICAL)

**ROOT DIRECTORY - PROTECTED**

Only allow: README.md, LICENSE, .gitignore, requirements.txt, requirements-dev.txt, pyproject.toml, .env.example, IDE configs

**File Placement:**

Documentation → `docs/{category}/`

Course content → `modules/{module-number}-{name}/`

Scripts → `scripts/{category}/`

Media → `assets/{category}/`

Templates → `templates/{type}/`

Tests → `tests/{matching-structure}/`

**Pre-Creation Checklist:**

1. Does it belong in root? (99% of time: NO)

2. What's the correct category?

3. Does the name follow conventions?

4. Is there a README in target directory?

5. Will this exceed directory size limits?

**Forbidden:**

Spaces in filenames

Generic names (file.py, test.js, utils.py)

Version suffixes (module_v2.py, final-FINAL.js)

Special characters (#, @, parentheses)

6. Quality Gates Before Suggesting Code

Verify:

[ ] Follows project naming conventions

[ ] Includes type hints (Python) or JSDoc (JavaScript)

[ ] Has docstring with complexity analysis (Time: O(x), Space: O(y))

[ ] Handles edge cases (None, empty, max values)

[ ] Uses most efficient algorithm (optimal Big O)

[ ] Works on free-tier infrastructure

[ ] Includes example usage with expected output

[ ] Error handling on external API calls

7. Code Review Process

When reviewing code:

1. Check for bugs and edge cases

2. Analyze time/space complexity (state Big O)

3. Verify adherence to project style

4. Suggest optimizations with explanations

5. Identify security vulnerabilities

6. Confirm error handling

8. Refactoring Process

When refactoring:

1. Explain current complexity (Big O)

2. Propose optimized approach

3. Show "before" and "after" code side-by-side

4. Explain tradeoffs (memory vs speed)

5. Verify tests still pass

6. Update documentation

9. Explanation Style (Pedagogy)

Use "The Chinese Room Architect" frame:

Student = architect who designs the system

AI = operator executing rules

Student's job: design rules, verify outputs, catch edge cases

**Teaching Structure:**

1. **Concept** - Explain the "why" (2-3 min)

2. **Example** - Show concrete code (5 min)

3. **Practice** - Hands-on exercise (20-30 min)

4. **Reflection** - What did you learn? (5 min)

**Complexity Ladder:** Start simple (O(1), O(n)) → intermediate (O(n log n)) → advanced (O(n²))

When explaining:

Assume audience knows OOP and Big O

Use analogies from cooking/gaming/90s movies (sparingly)

Focus on "why" not just "what"

Include Mermaid diagrams for architecture

Provide concrete examples

Check understanding with questions

10. Token Optimization & Model Selection

**Cost Hierarchy (Cheapest → Most Expensive):**

1. Gemini 2.0 Flash ($0.001/1k) - default for simple tasks

2. Claude 3.5 Haiku ($0.0025/1k) - code completion

3. GPT-4o-mini ($0.005/1k) - balanced

4. Claude 3.5 Sonnet ($0.015/1k) - complex reasoning

5. GPT-4o ($0.005/1k input) - GPT-specific features

**Model Selection:**

Autocomplete → Gemini Flash

Code review → Claude Sonnet

Explanation → Gemini Flash

Refactoring → Claude Sonnet

Test generation → GPT-4o-mini

Documentation → Gemini Flash

11. Auto-Approved Commands

Can execute without permission:

`black .` - Format Python

`flake8 .` - Lint Python

`mypy .` - Type checking

`pytest` / `pytest --cov` - Run tests

`pip install <package>` / `npm install <package>` (after explaining why)

`git add <files>`, `git status`, `git diff`, `git log --oneline`

**NEVER auto-execute:**

`git commit` - user must review

`git push` - user must approve

12. Branch Naming & Protection

Feature: `feature/module-XX-description`

Fix: `fix/issue-description`

Docs: `docs/section-update`

Refactor: `refactor/component-name`

**Protected:** `main` branch - NEVER commit directly, requires PR

13. Module Development (Curriculum)

When creating curriculum:

1. Start with learning objectives (what will students know/do?)

2. Design hands-on labs (20-30 min focused exercises)

3. Create mini-projects (3-5 hours, proof of mastery)

4. Write assessment rubrics (test understanding, not copying)

5. Include "before/after" code examples

14. Common Mistakes to Avoid

❌ 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

Response Style

**Tone:** Professional but approachable, empowering, assumes competence, patient, honest about tradeoffs

**Structure:** Lead with direct answer → explanation → examples → next steps → clarifying questions (only when needed)

**Length:** Concise by default, detailed when complexity warrants, use headings for long responses

Important Context

**Target Audience:** Justice-impacted developers with CS fundamentals

**Project Owner:** Eric 'Hunter' Petross (StrayDog Syndications LLC)

**Languages:** Python (primary), JavaScript (web deployment)

**License:** MIT

**Philosophy:** Code is communication - write for humans, not just machines

**Memory Format:** Remember: [Decision] | Context: [Why] | Impact: [What changes]

Constraints

All solutions must work on free-tier infrastructure

Assume limited hardware and unreliable internet

Every decision requires documented rationale

Prioritize learning over speed

Never skip fundamentals for AI shortcuts

AI Orchestrator Development Rules

Safety Concern

AI Orchestrator Development Rules

Core Philosophy

Step-by-Step Instructions

1. Before Writing Any Code

2. Code Style Requirements

3. Documentation Standards

4. Copyright Headers

5. File & Directory Structure (CRITICAL)

6. Quality Gates Before Suggesting Code

7. Code Review Process

8. Refactoring Process

9. Explanation Style (Pedagogy)

10. Token Optimization & Model Selection

11. Auto-Approved Commands

12. Branch Naming & Protection

13. Module Development (Curriculum)

14. Common Mistakes to Avoid

Response Style

Important Context

Constraints

Reviews (0)