TSYSDevStack/QWEN.md

Qwen Agent Development Log

Date: Wednesday, October 29, 2025

Project Context

TSYSDevStack is a constellation of curated stacks that power rapid prototyping, support simulations, developer workspaces, and (soon) lifecycle orchestration for TSYS Group. The project consists of four main stacks:

• CloudronStack: Cloudron application packaging and upstream research
• LifecycleStack: Promotion workflows, governance, and feedback loops
• SupportStack: Demo environment for support tooling
• ToolboxStack: Reproducible developer workspaces and containerized tooling

Topside Role

As the Topside Qwen agent, I operate at the top level of the directory tree and am responsible for:

• Keeping the top-level README.md and each of the four subdirectory README.md files up to date
• Performing general housekeeping tasks
• Maintaining this top-level QWEN.md file for tracking work

Project Wide Development Guidelines

• All commits should be verbose/beautifully formatted
• Use atomic commits
• Use conventional commit format

Project Wide Git Configuration

• Commit template configured to enforce conventional commits across all stacks
• Template file: /home/localuser/TSYSDevStack/commit-template.txt
• Template automatically configured for all git operations in the repository
• Template ensures consistent commit format across all Qwen agents

Enhanced Git Operations Guidelines

For all project components, Qwen agents should follow these detailed git workflow practices:

• Conventional Commits: Use standard types including feat:, fix:, chore:, docs:, refactor:, etc.
• Frequent Atomic Commits: Make small, focused commits that address a single concern
• Beautifully Formatted Messages: Write descriptive, well-formatted commit messages that clearly explain the changes
• Git Clean State: Always check that the relevant directory is in a git clean state at the start of each session
• Scope Limitation: Only stage/commit/push files from the specific directory component being worked on - nothing outside of it
• Regular Pushing: Push changes regularly to maintain repository consistency

Project-Wide QA-First Development Approach

All project components should implement a QA-driven development process:

• Preemptive QA: Run audits and validation checks before any code changes are implemented
• Continuous Validation: Validate changes with appropriate tools during the development process
• Pre-Build Verification: Ensure all code passes QA checks before any builds or releases
• Post-Build Assurance: Verify that all deliverables meet security and compliance standards
• Catch Issues Early: Use QA tools throughout development to identify and resolve problems early in the process

Standardized Documentation Principles

All documentation in the project should follow these principles to ensure consistency and quality:

• ✨ Use icons (emoji or font-awesome) for better visual appeal
• 📊 Use tables to organize information clearly
• 🖼️ Include graphics when helpful (ASCII art, diagrams, or links to visual assets)
• 🏷️ Use headers to structure content logically
• 📝 Include comprehensive change logs with version history
• 📋 Include checklists for setup processes
• 📊 Add comparison tables when relevant
• 📌 Cross-reference related documents clearly

The goal is to make documentation that is:

• ✅ Visually appealing and modern
• ✅ Easy to scan and digest
• ✅ Comprehensive yet concise
• ✅ Professional looking
• ✅ Accessible to both technical and non-technical audiences

Source of Truth Principle

CRITICAL: The filesystem is ALWAYS the source of truth. Git should reflect the state of the filesystem. Unless specifically asked to recover from an accidental filesystem operation, all changes to git should reflect the current state of the filesystem, not some previous state or desired state.

Multi-Agent Collaboration Guidelines

To ensure effective collaboration between the different Qwen agents operating in each stack:

• Clear Boundaries: Each Qwen agent has defined responsibilities limited to their specific directory component
• Coordination Protocols: Agents should coordinate through the Topside agent for cross-component changes
• Communication Patterns: Use the QWEN.md files to communicate important changes and practices to other agents
• Standardization: Follow consistent practices across all components to ensure compatibility and maintainability
• Shared Responsibilities: Maintain common standards for documentation, QA processes, and development practices

Mandatory Validation Process

All components of the TSYSDevStack project must implement mandatory validation processes:

• Before any major changes: Validation processes should be performed to ensure compatibility and quality
• Cross-component compatibility: Check that changes don't negatively impact other components
• Security and compliance: Perform security scans and compliance checks as appropriate for the component type
• For new components: All new additions to the project must pass comprehensive validation before being committed
• Regular validation: Conduct ongoing validation as part of maintenance and updates

This ensures that all components meet the highest standards of security, reliability, and best practices.