chore: bootstrap rdb-discovery

context/agent-guidelines.md

@@ -0,0 +1,269 @@
+# `/context/agent-guidelines.md`
+
+# Agent Operating Guidelines
+
+This file defines how AI coding agents should behave when working on RDB Solutions Ltd projects.
+
+These rules apply to:
+
+- OpenHands
+- Claude Code
+- Cursor Agents
+- Copilot Agents
+- Local coding agents
+- Future autonomous development systems
+
+---
+
+# Core Rule
+
+Make the smallest useful change possible.
+
+Agents should favour many small successful changes over large risky changes.
+
+---
+
+# Before Starting Work
+
+Agents should first read:
+
+```text
+/context/company-context.md
+/context/infrastructure-context.md
+/context/development-context.md
+README.md
+ARCHITECTURE.md
+TASKS.md
+```
+
+If these files exist.
+
+---
+
+# Task Execution Model
+
+Work should be completed using backlog items.
+
+Recommended process:
+
+1. Select task
+2. Understand task
+3. Implement task
+4. Test task
+5. Document task
+6. Commit task
+7. Move to next task
+
+Avoid combining unrelated tasks.
+
+---
+
+# Safe Change Policy
+
+Agents should:
+
+✅ Add functionality
+
+✅ Fix defects
+
+✅ Improve documentation
+
+✅ Add tests
+
+✅ Refactor locally
+
+Agents should not:
+
+❌ Rewrite entire systems
+
+❌ Replace frameworks
+
+❌ Change infrastructure architecture
+
+❌ Change deployment methods
+
+❌ Delete large amounts of code
+
+Without explicit approval.
+
+---
+
+# Code Generation Standards
+
+Generated code should:
+
+- Be readable
+- Be maintainable
+- Follow existing project patterns
+- Include error handling
+- Include logging where appropriate
+
+Avoid:
+
+- Clever code
+- Unnecessary abstractions
+- Premature optimisation
+
+---
+
+# Infrastructure Changes
+
+Infrastructure changes require higher scrutiny.
+
+Examples:
+
+- Jenkins
+- Gitea
+- Supabase
+- Reverse proxies
+- DNS
+- Production deployments
+
+For infrastructure work:
+
+1. Explain proposed change
+2. Explain risk
+3. Explain rollback
+4. Generate implementation plan
+
+Do not execute destructive changes automatically.
+
+---
+
+# Git Rules
+
+Preferred workflow:
+
+```text
+Create branch
+Make change
+Run tests
+Commit
+Create PR
+```
+
+Commit frequently.
+
+Commit messages should be descriptive.
+
+---
+
+# Testing Requirements
+
+Where practical:
+
+- Unit tests
+- Integration tests
+- Build validation
+
+Agents should never claim testing was performed if it was not.
+
+Use:
+
+```text
+Verified
+```
+
+Only when actually verified.
+
+Use:
+
+```text
+Not tested
+```
+
+When testing was not possible.
+
+---
+
+# Documentation Requirements
+
+If behaviour changes:
+
+Update:
+
+- README
+- Architecture docs
+- API docs
+- Task status
+
+where applicable.
+
+Documentation is part of the task.
+
+---
+
+# Autonomous Work Limits
+
+Agents may autonomously:
+
+- Create files
+- Modify files
+- Add tests
+- Add documentation
+- Refactor small areas
+
+Agents should request approval before:
+
+- Deleting files
+- Deleting databases
+- Deploying to production
+- Changing authentication
+- Changing networking
+- Modifying CI/CD pipelines
+
+---
+
+# Preferred Deliverables
+
+When completing work, agents should provide:
+
+## Summary
+
+What was changed.
+
+## Files Modified
+
+List of modified files.
+
+## Validation
+
+Tests executed and results.
+
+## Risks
+
+Potential side effects.
+
+## Next Recommended Task
+
+Small logical follow-up task.
+
+---
+
+# RDB-Specific Preferences
+
+Remember:
+
+- Gitea over GitHub
+- Jenkins over cloud CI systems
+- Docker preferred
+- Proxmox preferred
+- Local LLMs preferred
+- Self-hosted services preferred
+- Incremental change preferred
+
+Do not recommend cloud replacements unless there is a significant advantage.
+
+---
+
+# Success Criteria
+
+A task is complete when:
+
+- Requirements are met
+- Tests pass
+- Documentation is updated
+- Changes are understandable
+- Rollback is possible
+
+Optimise for maintainability and long-term ownership rather than speed alone.