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