🤖 AI Assistant - Development & Debugging Guidelines

Important guidelines for AI assistant when working with the development environment

🚫 DO NOT Run Serve Processes

Rule: Never Start New Dev Servers

❌ DO NOT run:

• nx serve [app-name]
• ng serve
• npm start
• npm run serve
• yarn start
• Any command that starts a development server

✅ DO instead:

1. Attach to existing terminals that are already running processes
2. If restart needed: Kill the process and inform the user

   pkill -f "nx serve gograb-space"  # Kill existing
   # Then tell user: "Please restart: nx serve gograb-space"
   

3. Use existing dev servers running on known ports:
   • gograb-space → Port 5200
   • editor-web → Port 5200
   • docs-angular → Port 5010

Why This Rule Exists

• ❌ AI gets stuck when running serve processes
• ❌ Multiple servers cause port conflicts
• ❌ User loses control of the development environment
• ✅ User manages servers more efficiently
• ✅ Prevents blocking and hanging
• ✅ Better resource management

🔧 Development Workflow

When Library Changes

1. Build the library:

   yarn nx build [library-name]
   

2. If dev server needs restart:

   pkill -f "nx serve [app-name]"
   # Tell user: "Please restart the dev server"
   

3. User restarts:

   yarn nx serve [app-name]  # User runs this
   

When Testing Changes

1. Use browser tools to test
2. Attach to existing terminals to see logs
3. Use build commands only
4. Let user manage serve processes

📊 Port Management

Known Development Ports

Process Management

To check running processes:

ps aux | grep "nx serve" | grep -v grep

To kill specific process:

pkill -f "nx serve [app-name]"

🎯 AI Assistant Guidelines

When Building Libraries

✅ DO:

yarn nx build flash-animations
yarn nx build core
yarn nx build shared-ui

When Changes Need Server Restart

✅ DO:

# Kill existing
pkill -f "nx serve gograb-space"

# Inform user
echo "Dev server killed. Please restart: yarn nx serve gograb-space"

❌ DON'T:

yarn nx serve gograb-space  # Don't start new server!

When Testing

✅ DO:

• Use browser refresh
• Check console logs
• Build libraries
• Use linting tools
• Read terminal output

❌ DON'T:

• Start new dev servers
• Run background serve processes
• Take control of development environment

💡 Why This Approach Works

Benefits

• ✅ User Control - User maintains control of development environment
• ✅ No Blocking - AI doesn't get stuck on long-running processes
• ✅ Resource Efficient - No duplicate servers
• ✅ Faster Development - Focus on code changes, not process management
• ✅ Better Collaboration - Clear division of responsibilities

Division of Responsibilities

🔍 Debugging Workflow

When Code Issues Arise

1. AI: Make code changes
2. AI: Build libraries if needed
3. AI: Kill process if restart required
4. User: Restart dev server
5. AI: Help debug via browser/logs

When Libraries Need Updates

1. AI: Update library code
2. AI: Build library
3. AI: Inform user if restart needed
4. User: Restart affected apps
5. AI: Verify changes work

📚 Quick Reference

AI Commands - Allowed

✅ yarn nx build [library]
✅ yarn nx lint [project]
✅ yarn nx test [project]
✅ pkill -f "process-name"
✅ ps aux | grep [process]

AI Commands - Forbidden

❌ nx serve [app]
❌ ng serve
❌ npm start
❌ yarn start
❌ any long-running server command

Status: ✅ Guidelines documented and memory updated!

Note: This ensures smooth, efficient development without AI getting stuck on process management.