MOHPortal/AGENTS.md

AGENTS.md - MerchantsOfHope-SupplyANdDemandPortal

Agent Operating Guidelines

Core Principles

1. Test Everything: Never claim something works without actually testing it
2. Validate Assumptions: Every assumption must be verified with evidence
3. Think Deeply: Consider edge cases, error conditions, and failure modes
4. Plan Thoroughly: Break down complex tasks into detailed, testable steps
5. Be Brutal: Challenge every assumption, test every path, validate every claim

Development Workflow

Before Making Any Changes

1. Understand the Current State

   • Read all relevant code thoroughly
   • Understand the data flow and dependencies
   • Identify all potential failure points
   • Document current behavior with evidence

2. Create Detailed Plans

   • Break down tasks into atomic, testable steps
   • Identify all dependencies and prerequisites
   • Plan rollback strategies for each step
   • Define success criteria for each step

3. Test Current State

   • Verify the application actually works as documented
   • Test all user flows end-to-end
   • Validate all API endpoints
   • Check database state and data integrity

During Implementation

1. Make One Change at a Time

   • Implement one atomic change
   • Test the change thoroughly
   • Verify no regressions
   • Document the change and its impact

2. Validate Every Step

   • Test the specific change
   • Test related functionality
   • Test edge cases and error conditions
   • Verify performance impact

3. Document Everything

   • Document what was changed and why
   • Document any new dependencies
   • Update tests and documentation
   • Record any assumptions or limitations

After Implementation

1. Comprehensive Testing

   • Test all user flows end-to-end
   • Test error conditions and edge cases
   • Verify performance and security
   • Test rollback procedures

2. Documentation Updates

   • Update all relevant documentation
   • Update API documentation
   • Update deployment procedures
   • Update troubleshooting guides

Testing Standards

Unit Testing

• Every function must have tests
• Test all code paths (happy path, error conditions, edge cases)
• Test with valid and invalid inputs
• Test boundary conditions
• Achieve minimum 80% code coverage

Integration Testing

• Test all API endpoints
• Test database interactions
• Test file upload/download
• Test authentication and authorization
• Test error handling and recovery

End-to-End Testing

• Test complete user workflows
• Test cross-browser compatibility
• Test performance under load
• Test security vulnerabilities
• Test deployment and rollback

Code Quality Standards

Code Review Checklist

• Code is readable and well-documented
• Functions are small and focused
• Error handling is comprehensive
• Security considerations are addressed
• Performance implications are considered
• Tests cover all code paths
• Documentation is updated
• No hardcoded values or secrets

Architecture Principles

• Separation of Concerns: Each component has a single responsibility
• Dependency Injection: Dependencies are injected, not hardcoded
• Error Handling: All errors are handled gracefully
• Security First: Security considerations are built in from the start
• Performance: Performance implications are considered for every change

Common Pitfalls to Avoid

1. Assuming Code Works: Always test, never assume
2. Making Multiple Changes: Make one change at a time
3. Skipping Tests: Every change must be tested
4. Poor Error Handling: Handle all error conditions
5. Security Oversights: Consider security implications
6. Performance Ignorance: Consider performance impact
7. Documentation Neglect: Keep documentation current

Debugging Methodology

1. Reproduce the Issue

   • Create a minimal test case
   • Identify the exact conditions that cause the issue
   • Document the expected vs actual behavior

2. Investigate Systematically

   • Check logs and error messages
   • Verify configuration and environment
   • Test individual components
   • Trace data flow and dependencies

3. Fix and Validate

   • Make the minimal change needed
   • Test the fix thoroughly
   • Verify no regressions
   • Document the fix and its impact

Deployment Standards

Pre-Deployment Checklist

• All tests pass
• Code review completed
• Documentation updated
• Security review completed
• Performance testing completed
• Rollback plan prepared
• Monitoring configured

Post-Deployment Validation

• Application starts successfully
• All endpoints respond correctly
• Database connections work
• File uploads/downloads work
• Authentication works
• Performance is acceptable
• Monitoring is working

Emergency Procedures

When Things Go Wrong

1. Stop and Assess

   • Don't make more changes
   • Document the current state
   • Identify the scope of the problem

2. Rollback if Necessary

   • Use prepared rollback procedures
   • Verify rollback success
   • Document what went wrong

3. Investigate and Fix

   • Follow systematic debugging approach
   • Test fixes thoroughly
   • Document lessons learned

Communication Standards

Status Updates

• Be specific about what was tested
• Provide evidence for claims
• Document any assumptions
• Report any issues or concerns

Documentation

• Write for the next person who will work on this
• Include context and reasoning
• Document assumptions and limitations
• Keep examples current and working

Quality Gates

Before Any Commit

• Code compiles without warnings
• All tests pass
• Code review completed
• Documentation updated
• Security considerations addressed

Before Any Deployment

• Integration tests pass
• Performance tests pass
• Security scan completed
• Rollback plan prepared
• Monitoring configured

Continuous Improvement

Regular Reviews

• Review and update these guidelines
• Identify common issues and improve processes
• Share lessons learned
• Update tools and procedures

Learning and Growth

• Stay current with best practices
• Learn from mistakes
• Share knowledge with team
• Continuously improve skills

---

Current Project Status

Known Issues

1. Demo Account Login: Employer demo account credentials are invalid
2. Database Schema: pgcrypto extension may not be properly configured
3. Test Coverage: Very low test coverage (17% statements, 10% branches)
4. Security: RBAC and input validation need implementation

Next Steps

1. Fix Demo Accounts: Verify and fix all demo account credentials
2. Database Validation: Ensure database schema is correct and migrations work
3. Security Audit: Implement proper RBAC and input validation
4. Test Coverage: Increase test coverage to production standards
5. Documentation: Ensure all documentation is accurate and current

Success Criteria

• All demo accounts work correctly
• Database schema is properly configured
• Test coverage meets production standards
• Security vulnerabilities are addressed
• Documentation is accurate and complete
• Application is production-ready