Essential workflow guidelines for AI agents working on development tasks. Use at the start of every task to ensure proper workflow, skill discovery, port detection, testing methodology, and verification. Consolidates critical prompt updates for consistent agent behavior across all tasks.
Essential workflow guidelines for AI agents working on development tasks. Use at the start of every task to ensure proper workflow, skill discovery, port detection, testing methodology, and verification. Consolidates critical prompt updates for consistent agent behavior across all tasks.
Agent Workflow Guidelines
Overview
Essential workflow guidelines to ensure efficient and reliable task execution. Follow these guidelines at the start of every task.
High Priority Guidelines
1. Mandatory Skill Discovery
MANDATORY WORKFLOW - Do not skip:
Read task file (tasks/next_task.md)
Read progress file (tasks/progress.txt)
Call search_skills("") to list ALL available skills
Load relevant skills before starting implementation
Only then proceed with task work
This is a blocking requirement - the orchestrator will verify skill discovery was performed.
Limiting search breadth: If two skill searches return no relevant match, load the standard set for the task type (e.g. progress-tracking, pre-implementation-check) and proceed. Do not run additional broad queries (e.g. search_skills("backend")) repeatedly.
2. Port Detection Before Browser Connection
Before opening browser for testing:
Check vite.config.ts for server.port configuration
Check package.json for PORT environment variable
Check running processes or terminal output for actual port
Don't assume default ports (3000, 5173, etc.)
Use discovered port in browser commands
If port detection fails, try common ports sequentially with timeout.
3. Phaser Game Testing Methodology
For Phaser game tasks:
PRIMARY METHOD: Use test seam commands (window.__TEST__.commands)
Test seams are the ONLY reliable way to interact with Phaser canvas games
DOM text search (find text) does NOT work with canvas-rendered text
Keyboard simulation may not work - use test seam commands instead
Always check for test seam availability before attempting DOM interactions
If test seam sceneKey doesn't update on transitions, use console logs as fallback verification.
4. Success Criteria Validation
Before marking task complete:
Verify ALL success criteria are met
Don't mark complete if progress shows 0/X criteria
For each criterion, document how it was verified
If browser testing fails, use fallback verification (console logs, code review)
Don't abandon testing on first failure - try alternative methods
Completion Checklist:
All code changes implemented
TypeScript compilation passes
All success criteria verified
Browser testing completed (for web/game tasks)
Progress.txt updated
Git commit with proper format
Medium Priority Guidelines
5. TypeScript Compilation After Edits
After making code edits:
Run npx tsc --noEmitimmediately to check for errors
Fix any compilation errors before proceeding
Don't wait until end of task to check compilation
Use smaller, incremental edits with verification
Common errors to watch for:
Syntax errors (extra/missing braces)
Method name mismatches (check actual method names in code)
Type mismatches (verify interface compatibility)
Import path errors (use relative paths)
6. Server Readiness Before Testing
When starting dev server for testing:
Start server with npm run dev
Poll server health endpoint until ready (don't use fixed sleep)
Check for "Local:" message in terminal output
Implement retry logic with timeout (max 30 seconds)
Only proceed with browser testing when server is confirmed ready
Pattern:
for i in {1..10}; doif curl -s http://localhost:PORT > /dev/null; thenbreak; fisleep 2
done
7. Timer Testing Efficiency
For timer-related features:
NEVER wait for natural countdown (e.g., 60 seconds)
Use test seam setTimer(seconds) to set timer directly
Test boundary conditions (9, 10, 11 seconds for color changes)
Add timer manipulation commands to test seam if not available
Test both positive (timer works) and negative (timer expires) cases
If test seam doesn't have timer commands, add them before testing.
8. Error Handling Testing
For error handling tasks:
Create test scenarios to force error conditions
Add test seam commands to trigger errors (e.g., forceMazeFailure())
Test fallback behavior works correctly
Verify console warnings/logs appear
Don't commit error handling code without testing error paths
If error condition is hard to trigger naturally, create test mode or test seam command.
9. localStorage Key Verification
Before using localStorage:
Read the storage utility file to find the correct key name
Check for constants file with exported storage keys
Verify key format (camelCase, kebab-case, etc.) matches codebase
Don't assume naming conventions - check actual implementation
This codebase uses camelCase: pixelGameSettings (not pixel-game-settings)
10. Scene Transition Testing
For scene transition testing:
Use test seam navigation commands when available
Wait 1-2 seconds after transition before checking test seam
Test seam sceneKey may lag - use console logs as fallback
Don't rely solely on test seam sceneKey for verification
Document scene navigation patterns in progress.txt
11. Browser Automation Timeout
When browser automation commands hang or timeout:
Set explicit timeout (default: 10 seconds)
If command exceeds timeout, try alternative method
Don't abandon testing - use fallback verification
Document timeout issues in progress.txt
Fallback order:
Test seam commands (for Phaser games)
Console log verification
Screenshot comparison
Code review + compilation check
12. Test Seam Command Discovery
When testing Phaser games:
First check source code for available test seam commands
Look for window.__TEST__.commands in scene files
Document discovered commands in progress.txt
Use test seam commands instead of DOM interactions
If command doesn't exist, add it to test seam before testing
Low Priority Guidelines
13. Task Verification Before Starting
Before implementing new features:
Check if functionality already exists in codebase
Search for similar implementations
Verify task dependencies are complete
If feature exists, still verify it works correctly before marking complete
14. Progress Tracking Accuracy
Note: If progress tracking shows 0/X criteria despite completion:
This is a known orchestrator issue
Still verify all success criteria manually
Don't let progress tracking prevent completion if criteria are met
Document verification in progress.txt
15. Incremental Development Pattern
For complex implementations:
Make smaller, incremental edits
Verify after each logical change (compile, test)
Build functionality layer by layer
Don't make large changes without intermediate verification
Pattern: Edit → Compile → Test → Next Edit
Workflow Summary
Start of Task:
Read task file and progress file
Call search_skills("") to discover all skills
Load relevant skills
Detect port before browser connection
Begin implementation
During Implementation:
Run TypeScript compilation after each edit
Use test seam commands for Phaser games
Verify server readiness before testing
Use timer manipulation, not natural countdown
Before Completion:
Verify all success criteria
Don't mark complete if 0/X criteria shown
Use fallback verification if primary method fails
Update progress.txt with learnings
16. Loop Detection and Prevention
Monitor for identical tool calls in short timeframes:
Track tool call patterns (same tool + same arguments)
If identical calls >10 times in 5 minutes, STOP and reassess
Check for progress metrics (files edited, tests run, errors fixed)
If no progress in 5 minutes, intervene (skip step, try alternative, or ask for help)
Intervention triggers:
10+ identical tool calls without progress
No files edited in 5 minutes
No tests run in 5 minutes
Tool failures without fallback strategy
Self-monitoring techniques:
Before each tool call, check: "Have I done this before?"
Track progress: "What have I accomplished since last check?"
Recognize stuck states: "Am I making progress or repeating?"
