docs: add AI agent context and guidelines
- Create comprehensive AGENTS.md for AI agent orientation - Document project overview, stakeholders, and timeline - Add key decisions and rationale (organization, repo management) - Document working patterns and communication style - Include application categories and programming languages - Add session resume guide and project status tracking - Document known issues and recovery steps 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
290
AGENTS.md
Normal file
290
AGENTS.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# TSYS Cloudron Packaging Project - AI Agent Context
|
||||
|
||||
This file contains important context, guidelines, and decisions made during the development of the TSYS Cloudron Packaging Project. AI agents should reference this file to understand project history, requirements, and working patterns.
|
||||
|
||||
## Project Overview
|
||||
|
||||
### Mission Statement
|
||||
Package 58+ upstream free/libre/open applications for deployment onto Cloudron (TSYS Group's PaaS of choice) as part of the TSYS Group Development Stack.
|
||||
|
||||
### Key Stakeholders
|
||||
- **Project Lead**: Charles N Wyble (@REachableCEO) - The founder
|
||||
- **Timeline**: 48-hour delivery deadline for Cloudron, Lifecycle, and Toolbox components
|
||||
- **Target Completion**: 2025-11-15
|
||||
- **QA/Testing Period**: 2025-11-10 to 2025-11-15
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
TSYSDevStack/
|
||||
└── Platform/
|
||||
└── Cloudron/
|
||||
├── README.md # Comprehensive project documentation
|
||||
├── GitUrlList.txt # Master list of upstream repositories
|
||||
├── clone-repos.sh # Automated repository cloning script
|
||||
├── AGENTS.md # This file - AI agent context
|
||||
├── .gitignore # Git ignore rules
|
||||
├── Package-Artifacts/ # Completed Cloudron packages
|
||||
└── Package-Workspace/ # Working directory organized by function
|
||||
├── API-Gateway/ # 2 apps
|
||||
├── Automation/ # 4 apps
|
||||
├── Business-Apps/ # 9 apps
|
||||
├── Collaboration/ # 2 apps
|
||||
├── Communication/ # 2 apps
|
||||
├── Data-Management/ # 2 apps
|
||||
├── Development/ # 4 apps
|
||||
├── DevOps-Tools/ # 2 apps
|
||||
├── Documentation-Tools/ # 3 apps
|
||||
├── Financial-Payments/ # 1 app
|
||||
├── Financial-Trading/ # 1 app
|
||||
├── Infrastructure/ # 6 apps
|
||||
├── Legal/ # 1 app
|
||||
├── Low-Code/ # 3 apps
|
||||
├── Monitoring/ # 6 apps
|
||||
├── Project-Management/ # 1 app
|
||||
├── Scientific-Computing/ # 2 apps
|
||||
├── Security/ # 5 apps
|
||||
└── System-Administration/ # 3 apps
|
||||
```
|
||||
|
||||
## Key Decisions & Rationale
|
||||
|
||||
### 1. Organization Strategy
|
||||
**Decision**: Organize applications by function rather than programming language.
|
||||
|
||||
**Rationale**:
|
||||
- Founder explicitly requested functional organization over language-based organization
|
||||
- More intuitive for developers working on Cloudron packaging
|
||||
- Aligns with how users will discover and deploy applications
|
||||
- Facilitates better documentation and user experience
|
||||
|
||||
**Implementation**: 20 functional categories created based on application purpose and use cases.
|
||||
|
||||
### 2. Repository Management
|
||||
**Decision**: Clone all upstream repositories into `Package-Workspace` but exclude from git.
|
||||
|
||||
**Rationale**:
|
||||
- Avoid polluting the project repository with large upstream codebases
|
||||
- Enable offline development and packaging work
|
||||
- Maintain clean separation between packaging code and upstream source
|
||||
- Provide reproducible development environment
|
||||
|
||||
**Implementation**:
|
||||
- `.gitignore` excludes `Package-Workspace/**/repo/`
|
||||
- `clone-repos.sh` script enables other developers to replicate workspace
|
||||
- Each app has its own directory with `repo/` subdirectory
|
||||
|
||||
### 3. Documentation Strategy
|
||||
**Decision**: Create comprehensive README.md with application inventory table.
|
||||
|
||||
**Rationale**:
|
||||
- Single source of truth for project status and application catalog
|
||||
- Beautiful, clickable table with links to vendor websites and repositories
|
||||
- Scalable approach for adding new applications
|
||||
- Professional presentation for stakeholders
|
||||
|
||||
**Implementation**:
|
||||
- Markdown table with Application Name (linked to vendor site), Repository (linked to git), Description, and Functional Category
|
||||
- Project statistics and overview sections
|
||||
- Development workflow documentation
|
||||
|
||||
### 4. Automation Approach
|
||||
**Decision**: Create automated cloning script with error handling and categorization.
|
||||
|
||||
**Rationale**:
|
||||
- Enable other developers to quickly set up development environment
|
||||
- Reduce manual setup time and potential errors
|
||||
- Provide consistent workspace structure
|
||||
- Handle edge cases and provide helpful error messages
|
||||
|
||||
**Implementation**:
|
||||
- `clone-repos.sh` with colored output, timeout handling, and automatic categorization
|
||||
- Functional category mapping based on application names
|
||||
- Progress reporting and summary statistics
|
||||
|
||||
## Technical Requirements
|
||||
|
||||
### Cloudron Packaging Standards
|
||||
- Each application requires `Dockerfile` and `CloudronManifest.json`
|
||||
- Follow Cloudron packaging tutorial and best practices
|
||||
- Use appropriate addons (MySQL, PostgreSQL, Redis, etc.)
|
||||
- Ensure proper security and configuration management
|
||||
- Test with `cloudron build` and `cloudron install`
|
||||
|
||||
### Quality Assurance
|
||||
- All work must be QA'd early and often
|
||||
- Use Docker security scanning tools (hadolint, trivy, dockle, dive, syft)
|
||||
- Perform at least 5 validation checks per component
|
||||
- Treat warnings as errors and resolve all issues
|
||||
- No unit/end-to-end test suite means work is not complete
|
||||
|
||||
### Git Standards
|
||||
- Use atomic commits with conventional commit standards
|
||||
- Make verbose and beautiful commit messages
|
||||
- Commit early and often
|
||||
- Use gh/tea commands for pull requests and releases
|
||||
- Commit history should serve as a comprehensive project journal
|
||||
|
||||
### Container Standards
|
||||
- Use Docker containers for all work (no host pollution)
|
||||
- Only use docker and git commands on host
|
||||
- Use curl for health checks
|
||||
- Do not install tooling/packages/runtimes on host
|
||||
|
||||
## Working Patterns
|
||||
|
||||
### Multi-Component Development
|
||||
- Chats start at project root or component root level
|
||||
- Only orient from invoked location down
|
||||
- Do not consider sibling directories
|
||||
- Confine work to directory (and below) where invoked
|
||||
|
||||
### Communication Style
|
||||
- Brief, professional, direct communication
|
||||
- Avoid unnecessary fluff or excessive politeness
|
||||
- Focus on task completion and technical accuracy
|
||||
- Keep responses concise (fewer than 4 lines unless detail requested)
|
||||
|
||||
### Documentation Maintenance
|
||||
- Update both AI-readable (AGENTS.md) and human-readable (JOURNAL.md) journals during each interaction
|
||||
- Maintain running log of work done, remaining tasks, and important notes
|
||||
- Keep documentation in sync with code artifacts
|
||||
|
||||
## Application Categories & Mappings
|
||||
|
||||
### Functional Categories (19 total)
|
||||
1. **API-Gateway** (2 apps): apisix, webhook
|
||||
2. **Automation** (4 apps): runme, rundeck, huginn, windmill
|
||||
3. **Business-Apps** (9 apps): PayrollEngine, openboxes, pimcore, InvenTree, killbill, midday, elabftw, PLMore
|
||||
4. **Collaboration** (2 apps): grist-core, consuldemocracy
|
||||
5. **Communication** (2 apps): craig, fonoster
|
||||
6. **Data-Management** (2 apps): datahub, seatunnel
|
||||
7. **Development** (4 apps): AutoBOM, reviewboard, puter, warp
|
||||
8. **DevOps-Tools** (2 apps): fx, policies
|
||||
9. **Documentation-Tools** (3 apps): docker-drawio, wireviz-web, WireViz
|
||||
10. **Financial-Payments** (1 app): hyperswitch
|
||||
11. **Financial-Trading** (1 app): nautilus_trader
|
||||
12. **Infrastructure** (6 apps): database-gateway, netbox, rathole, easy-gate, chirpstack, sdrangel
|
||||
13. **Legal** (1 app): docassemble
|
||||
14. **Low-Code** (3 apps): openblocks, corteza, no-code-architects-toolkit
|
||||
15. **Monitoring** (6 apps): goalert, healthchecks, fleet, langfuse, sentry, signoz
|
||||
16. **Project-Management** (1 app): Core
|
||||
17. **Scientific-Computing** (2 apps): boinc, jamovi
|
||||
18. **Security** (5 apps): tirreno, gophish, SniperPhish, security-awareness-training, comply
|
||||
19. **System-Administration** (3 apps): mender, mendersoftware, slurm
|
||||
|
||||
### Programming Languages Identified
|
||||
- Go (14 apps)
|
||||
- Node.js/JavaScript (13 apps)
|
||||
- Python (20 apps)
|
||||
- PHP (3 apps)
|
||||
- Java (2 apps)
|
||||
- Rust (1 app)
|
||||
- Ruby (1 app)
|
||||
- TypeScript (1 app)
|
||||
- Mixed/Unknown (3 apps)
|
||||
|
||||
## Important Notes
|
||||
|
||||
### Repository Issues
|
||||
- **oat-sa**: Invalid URL (organization-level only)
|
||||
- **satnogs**: GitLab repository requiring authentication
|
||||
- **mendersoftware**: Fixed with correct URL to mender repository
|
||||
|
||||
### Duplicate Entries
|
||||
- warp and windmill appeared twice in original GitUrlList.txt
|
||||
|
||||
### Recent Additions
|
||||
- **Craig** (craig): Added during session, TypeScript Discord voice recording bot, placed in Communication category
|
||||
|
||||
### Functional Categorization Audit (2025-11-13)
|
||||
**Decision**: Conducted comprehensive audit of application categorization to ensure proper functional grouping.
|
||||
|
||||
**Critical Fixes Implemented**:
|
||||
- **fonoster**: Moved from Development to Communication (telephony platform)
|
||||
- **hyperswitch**: Moved from Business-Apps to Financial-Payments (payments infrastructure)
|
||||
- **nautilus_trader**: Moved from Business-Apps to Financial-Trading (algorithmic trading)
|
||||
- **docassemble**: Moved from Legal/repo to Legal directory (document assembly platform)
|
||||
- **no-code-architects-toolkit**: Moved from Development to Low-Code (low-code platform)
|
||||
- **docker-drawio**: Moved from Development to Documentation-Tools (diagramming tool)
|
||||
- **wireviz-web**: Moved from Voice-Audio to Documentation-Tools (cable diagramming)
|
||||
- **WireViz**: Moved from Voice-Audio to Documentation-Tools (cable documentation)
|
||||
- **corteza**: Moved from DevOps-Tools to Low-Code (low-code platform)
|
||||
- **comply**: Moved from DevOps-Tools to Security (compliance and security)
|
||||
- **policies**: Moved from Development to DevOps-Tools (DevOps policies)
|
||||
|
||||
**New Categories Created**:
|
||||
- **Documentation-Tools**: For diagramming and documentation applications
|
||||
- **Financial-Payments**: For payment processing and financial infrastructure
|
||||
- **Financial-Trading**: For trading and financial algorithm platforms
|
||||
|
||||
**Categories Removed**:
|
||||
- **Voice-Audio**: Removed as empty (WireViz moved to Documentation-Tools)
|
||||
|
||||
**Rationale**:
|
||||
- Improved accuracy in functional categorization
|
||||
- Better user experience for application discovery
|
||||
- More logical grouping for Cloudron packaging workflows
|
||||
- Reduced category ambiguity and overlap
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### For New Applications
|
||||
1. Add to GitUrlList.txt
|
||||
2. Run `./clone-repos.sh` to fetch repository
|
||||
3. Determine appropriate functional category
|
||||
4. Move to correct directory if needed
|
||||
5. Update README.md table
|
||||
6. Begin Cloudron packaging (Dockerfile + CloudronManifest.json)
|
||||
7. Test with Cloudron CLI
|
||||
8. Move completed package to Package-Artifacts/
|
||||
|
||||
### For AI Agents
|
||||
1. Always read AGENTS.md first for context
|
||||
2. **When resuming work: Check RESUME.md for session status and next steps**
|
||||
3. Update AGENTS.md with important decisions and changes
|
||||
4. Maintain professional, concise communication style
|
||||
5. Focus on task completion and technical accuracy
|
||||
6. Use todo system for tracking complex tasks
|
||||
7. Perform thorough QA before marking tasks complete
|
||||
|
||||
## Project Status
|
||||
|
||||
### Completed Tasks
|
||||
- ✅ Repository analysis and language identification
|
||||
- ✅ Functional directory structure creation
|
||||
- ✅ Application organization by function
|
||||
- ✅ Git ignore configuration
|
||||
- ✅ Comprehensive README.md documentation
|
||||
- ✅ Automated cloning script
|
||||
- ✅ AI agent context documentation
|
||||
- ✅ Functional categorization audit and corrections
|
||||
|
||||
### Next Steps
|
||||
- Begin Cloudron packaging for high-priority applications
|
||||
- Establish testing and validation pipeline
|
||||
- Create package templates for common patterns
|
||||
- Develop automated packaging workflows
|
||||
|
||||
## Session Resume Guide
|
||||
|
||||
**📍 Resuming Work? Read RESUME.md first!**
|
||||
|
||||
When returning to this project after a break:
|
||||
1. **Always check RESUME.md** - Contains current session status, uncommitted changes, and immediate next steps
|
||||
2. Review this file (AGENTS.md) for context, decisions, and working patterns
|
||||
3. Review README.md for complete project documentation
|
||||
4. Check git status to see what's uncommitted
|
||||
|
||||
**RESUME.md provides:**
|
||||
- Summary of work done in previous session
|
||||
- List of uncommitted changes
|
||||
- Immediate next steps with commands
|
||||
- Known issues and resolutions
|
||||
- Quick start guides for different scenarios
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-11-13
|
||||
**Session Context**: Functional categorization audit and corrections
|
||||
**AI Agent**: Qwen
|
||||
**Project Phase**: Foundation complete, categorization optimized, ready for packaging phase
|
||||
Reference in New Issue
Block a user