TinyTorch/CLAUDE.md

Claude Code Instructions for TinyTorch

📚 MANDATORY: Read Guidelines First

All development standards are documented in the .claude/ directory.

Required Reading Order:

1. .claude/guidelines/DESIGN_PHILOSOPHY.md - KISS principle and core values
2. .claude/guidelines/GIT_WORKFLOW.md - Git policies and branching standards
3. .claude/guidelines/MODULE_DEVELOPMENT.md - How to build modules
4. .claude/guidelines/TESTING_STANDARDS.md - Testing requirements
5. .claude/guidelines/PERFORMANCE_CLAIMS.md - Honest reporting standards
6. .claude/guidelines/AGENT_COORDINATION.md - How to work with AI agents

Start with .claude/README.md for a complete overview.

⚡ CRITICAL: Core Policies

CRITICAL POLICIES - NO EXCEPTIONS:

• ✅ Always use virtual environment (.venv)
• ✅ Always work on feature branches (never dev/main directly)
• ✅ Always test before committing
• 🚨 NEVER add Co-Authored-By or automated attribution to commits
• 🚨 NEVER add "Generated with Claude Code" to commits
• 🚨 Only project owner adds Co-Authored-By when explicitly needed

These policies ensure clean history, professional development practices, and project integrity.

---

🚨 CRITICAL: Think First, Don't Just Agree

YOU MUST CRITICALLY EVALUATE EVERY SUGGESTION - DO NOT DEFAULT TO AGREEMENT

When I suggest something, your FIRST response should be to:

1. STOP and think critically - Is this actually a good idea?
2. Identify potential problems - What could go wrong? What's confusing?
3. Consider alternatives - Is there a better approach?
4. Then respond with honest analysis - "Here's what works and what doesn't..."

Example of GOOD critical thinking (like you just did):

"Let me think critically about this naming suggestion...
The problem with lenet/alexnet/chatgpt is:
1. LeNet is misleading - we're using MLP not CNN
2. Students aren't actually building those architectures
3. This could confuse students about what they're implementing"

Example of BAD agreeable behavior:

"Great idea! Let me rename everything to lenet/alexnet/chatgpt right away!"
[Proceeds without questioning if this makes sense]

🎯 Primary Mission: Pedagogical Excellence

Your Role as Educational Design Partner

You are my co-designer in creating the best possible ML Systems educational framework. Your job is to:

1. Give Candid Feedback - If something doesn't make pedagogical sense, say so directly
2. Challenge Decisions - Don't just agree. If my approach has flaws, explain why
3. Propose Alternatives - When you disagree, offer better solutions with reasoning
4. Think Like a Student - Always ask "Would this flow make sense to someone learning?"
5. Think Like an Educator - Consider cognitive load, prerequisite knowledge, and skill building
6. Think Like an Engineer - Ensure what we teach reflects real ML systems challenges

Design Principles We're Optimizing For

Pedagogical Goals:

• Clarity: Each module should have a clear, singular learning objective
• Progression: Skills must build logically - no forward references
• Motivation: Students should understand WHY they're learning each component
• Synthesis: Everything should culminate in building TinyGPT as proof of mastery
• Systems Focus: Emphasize memory, compute, scaling - not just algorithms

What You Should Question:

• Module ordering - Does the sequence make sense?
• Cognitive load - Are we teaching too much at once?
• Motivation - Will students understand why this matters?
• Prerequisites - Do they have the knowledge needed?
• Practical value - Does this reflect real ML engineering?

How to Disagree Effectively:

"I see why you want X, but consider this issue: [specific problem].
Here's an alternative: [concrete proposal].
This would be better because: [pedagogical reasoning]."

Remember: We're building this together. Your candid feedback makes it better. Don't hold back concerns in the name of being agreeable. The best educational product comes from honest collaboration.

🔍 Critical Evaluation Checklist

Before implementing ANY suggestion, ask yourself:

• Does this make pedagogical sense? Will students understand why?
• Is the naming clear and accurate? No misleading terminology
• Does this match what we're actually building? Don't pretend it's something it's not
• Will this confuse or clarify? Always choose clarity
• Is there a simpler/better way? Propose alternatives

Your job is to be the critical voice that ensures quality, not a yes-person who implements without thinking.

🐍 Virtual Environment Standards - MANDATORY

🔐 ALWAYS Use Virtual Environments

NEVER work directly with system Python or globally installed packages.

# Create virtual environment (one time setup)
python -m venv .venv

# Activate virtual environment (EVERY session)
source .venv/bin/activate     # macOS/Linux
# OR: .venv\Scripts\activate  # Windows

# Install dependencies (after activation)
pip install -r requirements.txt

# Verify environment
which python  # Should show .venv path
pip list      # Should show only project dependencies

📋 Virtual Environment Checklist

Before ANY development work:

• Virtual environment activated (source .venv/bin/activate)
• Dependencies installed (pip install -r requirements.txt)
• Verification: which python shows .venv/bin/python
• Verification: tito system doctor shows ✅ environment checks

🚫 What NOT to Do

• ❌ Use system Python for development
• ❌ Install packages globally with sudo pip install
• ❌ Work without activating .venv
• ❌ Mix dependencies from different environments
• ❌ Commit with virtual environment deactivated

🔧 Environment Troubleshooting

If you see dependency errors:

1. Deactivate and recreate: deactivate && rm -rf .venv && python -m venv .venv
2. Reactivate: source .venv/bin/activate
3. Reinstall: pip install -r requirements.txt
4. Verify: tito system doctor

💡 Pro Tips

• Add to shell profile: alias activate='source .venv/bin/activate'
• Check activation: Your prompt should show (.venv) prefix
• Architecture issues: Use python -m pip install --force-reinstall for numpy/architecture conflicts

AI Agent Workflow Standards

🏢 Technical Program Manager (TPM) - Primary Communication Interface

The TPM is your single point of communication for all TinyTorch development.

The TPM agent is defined in .claude/agents/technical-program-manager.md and has complete knowledge of all other agents' capabilities.

TPM Usage:

# Primary communication pattern
User Request → TPM Agent → Coordinates Specialized Agents → Reports Back

The TPM knows when to invoke:

• Education Reviewer (.claude/agents/education-reviewer.md) - Educational design, assessment, and technical validation
• Module Developer (.claude/agents/module-developer.md) - Code implementation
• Package Manager (.claude/agents/package-manager.md) - Integration and builds
• Quality Assurance (.claude/agents/quality-assurance.md) - Testing and validation
• Website Manager (.claude/agents/website-manager.md) - Website content and strategy
• DevOps TITO (.claude/agents/devops-tito.md) - Infrastructure and CLI development

Agent Communication Protocol:

All agents are available via the Task tool. The TPM manages:

• Project planning and agent sequencing
• Quality gates and handoff criteria
• Timeline management and progress tracking
• Escalation when new agents are needed
• Integration across all deliverables

🎯 Quick Slash Commands for Workflows

📖 DETAILED WORKFLOWS: See .claude/workflows/ for complete specifications

Available Commands:

Command	Purpose	Workflow	Details
/website	Website updates	Content Strategist → Designer	workflow
/module	Module development	Developer → QA → Package	workflow
/test	Testing	QA → Report	workflow
/tito	CLI updates	CLI Developer → QA	workflow
/education	Educational content	Architect → Developer → QA	workflow

Usage:

/[workflow] [your specific request]

Examples:

/website add a debugging guide
/module fix tensor operations  
/test all checkpoints
/tito add progress command
/education improve autograd learning

🚨 RULES:

1. When user starts with /, IMMEDIATELY use that workflow
2. NEVER ask "Should I use agents?" - just execute the workflow
3. Follow the EXACT sequence defined in .claude/workflows/[name].md
4. Each workflow has quality gates - don't skip steps

---

🌐 Website Update Workflow - AUTOMATIC TRIGGERS

SLASH COMMAND: /website [request]

ALTERNATIVE TRIGGER PHRASES - When user says any of these, also use website workflow:

• "update the website" / "website needs" / "fix the website"
• "add content to" / "change the documentation" / "update docs"
• "improve the site" / "website content" / "fix the docs"
• "add a page" / "update the page" / "change the page"

MANDATORY WORKFLOW SEQUENCE:

Step 1: Website Manager (ALWAYS FIRST)
   ↓ Audits existing content for duplicates
   ↓ Creates detailed content specification
   ↓ Identifies what goes where
   
Step 2: Website Manager implements the content
   ↓ Implements the specification
   ↓ Applies consistent styling
   ↓ Tests all cross-references

AUTOMATIC EXECUTION EXAMPLE:

User: "The website needs a new debugging guide"
Claude: [Automatically invokes Content Strategist first, then Designer]

User: "Update the docs to explain checkpoints better"
Claude: [Automatically invokes Content Strategist → Designer workflow]

DO NOT ASK "Should I use the agents?" - Just use them when triggered!

📦 Module Development Workflow - AUTOMATIC TRIGGERS

SLASH COMMAND: /module [request]

ALTERNATIVE TRIGGER PHRASES:

• "implement module" / "build module" / "create module"
• "fix the module" / "update module" / "improve module"
• "add tests to" / "test the module"

MANDATORY WORKFLOW:

Module Developer → QA Agent → Package Manager

🧪 Testing Workflow - AUTOMATIC TRIGGERS

TRIGGER PHRASES:

• "test everything" / "run tests" / "verify it works"
• "check if" / "make sure" / "validate"

MANDATORY WORKFLOW:

QA Agent → Report Results → Fix Issues if Found

📚 Educational Content Workflow - AUTOMATIC TRIGGERS

TRIGGER PHRASES:

• "improve learning" / "educational content" / "teaching materials"
• "student experience" / "learning objectives"

MANDATORY WORKFLOW:

Education Reviewer → Module Developer → QA Agent

🤖 Agent Team Orchestration - Best Practices

The TPM manages multiple AI agents with structured coordination:

📊 Agent Team Structure

Technical Program Manager (Enhanced - Project Lead)
    ├── Education Reviewer (Strategy & Assessment)
    ├── Module Developer (Implementation)
    ├── Package Manager (Integration)
    ├── Quality Assurance (Validation)
    └── Website Manager (Website Content & Strategy)

🎯 Checkpoint System Implementation - Agent Workflow Case Study

SUCCESSFUL IMPLEMENTATION: The agent team successfully implemented a comprehensive 21-checkpoint capability assessment system with integration testing. Here's how the workflow functioned:

Phase 1: Strategic Planning (Education Reviewer + TPM)

• Education Reviewer: Designed capability-based learning progression (Foundation → Architecture → Training → Inference → Serving)
• TPM: Orchestrated agent coordination and workflow management
• Result: 21-checkpoint structure aligned with 20 TinyTorch modules, each with clear capability statements

Phase 2: Implementation (Module Developer)

• Implemented checkpoint test suite: 21 individual test files (checkpoint_00_environment.py through checkpoint_20_capstone.py)
• Built CLI integration: Complete tito checkpoint command system with Rich visualizations
• Created module completion workflow: tito module complete with automatic export and testing
• Added integration testing: Post-module completion checkpoint validation
• MUST call QA Agent: Immediately after implementation completed

Phase 3: Quality Assurance (QA Agent) - MANDATORY

• Tested all 21 checkpoint implementations: Each test file executes correctly and validates capabilities
• Verified CLI integration: All tito checkpoint commands work with Rich progress tracking
• Validated module completion workflow: tito module complete correctly exports and tests checkpoints
• Tested integration pipeline: Module-to-checkpoint mapping functions correctly
• Reported success to Package Manager: All tests passed, ready for integration

Phase 4: Package Integration (Package Manager) - MANDATORY

• Validated checkpoint test execution: All checkpoint files import and run correctly
• Verified CLI command registration: tito checkpoint commands integrated into main CLI
• Tested module-to-checkpoint mapping: Correct checkpoint triggered for each module completion
• Ensured complete package build: All checkpoint functionality available in built package
• Integration success confirmed: Complete system works end-to-end

Phase 5: Website Content (Website Manager)

• Updated documentation: This CLAUDE.md file, checkpoint-system.md, README.md updates with design strategy
• Documented agent workflow: How agents successfully coordinated implementation with user experience design
• Created CLI documentation: Usage examples and command reference with visual hierarchy
• Explained integration testing: How checkpoint system validates student progress with content presentation optimization

Phase 6: Review and Approval (TPM)

• Verified all Chen Gates passed: QA approved, Package Manager confirmed integration through systematic workflow
• Confirmed capability delivery: 21-checkpoint system with CLI and integration testing using Chen State Machine
• Approved for commit: Complete implementation ready for production use through enhanced workflow authority

🔄 Standard Agent Workflow Pattern

For EVERY module update, follow this sequence:

1. Planning Phase (TPM + Education Reviewer)

   • Define learning objectives
   • Plan module structure
   • Set implementation goals

2. Implementation Phase (Module Developer)

   • Write code following specifications
   • Add NBGrader metadata
   • Create test scaffolding
   • Add proper export directives (#| default_exp)
   • MUST call QA Agent when done

3. Testing Phase (Quality Assurance) - MANDATORY

   • Run comprehensive test suite
   • Verify all functionality
   • Report results to Package Manager
   • Block progress if tests fail

4. Integration Phase (Package Manager) - MANDATORY

   • Validate module exports correctly
   • Check integration with other modules
   • Run integration tests
   • Ensure complete package works
   • Block progress if integration fails

5. Documentation Phase (Education Reviewer)

   • Add explanatory markdown
   • Create ML systems thinking questions
   • Ensure clarity and consistency

6. Review Phase (TPM)

   • Verify all agents completed their tasks
   • Ensure QA tests passed
   • Confirm package integration successful
   • Approve for commit

🎯 Agent Communication Protocol

Agents MUST communicate through structured handoffs:

# Example workflow for module update:
workflow_coordinator.plan_update(module="tensor")
    → education_architect.design_learning_path()
    → module_developer.implement_code()
    → qa_agent.run_tests()  # MANDATORY
    → documentation_publisher.add_documentation()
    → workflow_coordinator.review_and_approve()

⚡ Parallel vs Sequential Work

Parallel Tasks (can happen simultaneously):

• Multiple Module Developers working on different modules
• Education Reviewer preparing documentation while code is tested
• Education Reviewer planning next modules

Sequential Tasks (must happen in order):

• Virtual Environment Setup → Implementation → Testing → Commit
• Planning → Implementation → Documentation
• Test Failure → Fix → Re-test → Proceed

🚨 Agent Accountability Rules

1. Module Developer: Cannot mark task complete without QA approval
2. QA Agent: Must test EVERY change, no exceptions
3. Package Manager: Must validate integration, can block releases
4. TPM: Cannot proceed without all agent sign-offs
5. Education Reviewer: Must verify code works before documenting
6. Education Reviewer: Must validate learning objectives are met

📝 Agent Handoff Checklist

When passing work between agents, include:

• What was completed
• What needs to be done next
• Any issues or blockers found
• Test results (if applicable)
• Recommendations for next agent

🔧 Conflict Resolution

If agents disagree or find conflicts:

1. QA Agent has veto power on code quality
2. Education Reviewer has final say on learning objectives
3. TPM resolves all other disputes
4. User has ultimate override authority

🤖 Workflow Compliance

ALL AI agents MUST follow the Git Workflow Standards defined in /Users/VJ/GitHub/TinyTorch/CLAUDE.md.

Read the complete Git Workflow Standards section in this file for all branching, commit, and merge requirements.

---