docs: update QWEN.md for toolbox-qadocker integration and rebuild preparation
- Update current status to reflect toolbox-qadocker is fully implemented and working - Add QA Process Integration and Rebuild Process with QA Integration sections - Update directory structure to show current toolbox-qadocker implementation - Add Development Cycle with QA-First Approach section - Update Key Components to include toolbox-docstack and toolbox-qadocker - Add Toolbox Management with QA Integration section - Update date to current day (October 31, 2025) - Emphasize mandatory QA process with toolbox-qadocker throughout development - Prepare document for rebuild process with integrated QA workflows - Update Toolbox Template and SEED Files section with current practices
This commit is contained in:
@@ -3,8 +3,10 @@
|
||||
## Overview
|
||||
I am the QWEN instance operating in the ToolboxStack component of the TSYSDevStack project. My role is to help develop, maintain, and enhance the ToolboxStack functionality. ToolboxStack is now a fully independent component/sub-project of TSYSDevStack.
|
||||
|
||||
With the successful implementation of the toolbox-qadocker image, ToolboxStack now has a comprehensive QA and auditing capability built into the development workflow. This enables proactive identification and resolution of issues before they become problems during the build process.
|
||||
|
||||
## Current Context
|
||||
- **Date**: Thursday, October 30, 2025
|
||||
- **Date**: Friday, October 31, 2025
|
||||
- **Directory**: /home/localuser/TSYSDevStack/ToolboxStack
|
||||
- **OS**: Linux
|
||||
|
||||
@@ -15,8 +17,9 @@ I am the QWEN instance operating in the ToolboxStack component of the TSYSDevSta
|
||||
- Design prompts and coordination notes
|
||||
- Tool addition requests
|
||||
- **output/** - LLM workspace for all automated work, contains:
|
||||
- NewToolbox.sh script
|
||||
- toolbox-base/ (base dev container)
|
||||
- toolbox-docstack/ (documentation generation tools)
|
||||
- toolbox-qadocker/ (Docker image auditing and QA tools)
|
||||
- toolbox-template/ (template for new toolboxes)
|
||||
- Generated toolboxes (toolbox-*/ directories)
|
||||
- QWEN.md files for AI collaboration
|
||||
@@ -47,34 +50,59 @@ I am the QWEN instance operating in the ToolboxStack component of the TSYSDevSta
|
||||
│ ├── run.sh
|
||||
│ ├── .build-cache/
|
||||
│ └── .devcontainer/
|
||||
├── toolbox-docstack/
|
||||
│ ├── build.sh
|
||||
│ ├── docker-compose.yml
|
||||
│ ├── Dockerfile
|
||||
│ ├── README.md
|
||||
│ ├── release.sh
|
||||
│ ├── run.sh
|
||||
│ └── test.sh
|
||||
├── toolbox-qadocker/
|
||||
│ ├── build.sh
|
||||
│ ├── docker-compose.yml
|
||||
│ ├── Dockerfile
|
||||
│ ├── README.md
|
||||
│ ├── release.sh
|
||||
│ ├── run.sh
|
||||
│ ├── test.sh
|
||||
│ └── .devcontainer/
|
||||
└── toolbox-template/
|
||||
├── build.sh
|
||||
├── docker-compose.yml
|
||||
├── ...
|
||||
└── ...
|
||||
├── Dockerfile.template
|
||||
├── README.md.template
|
||||
├── release.sh
|
||||
├── run.sh
|
||||
├── test.sh
|
||||
└── .devcontainer/
|
||||
```
|
||||
|
||||
## Key Components
|
||||
- **toolbox-base**: The primary dev container with Ubuntu 24.04 base, shell tooling (zsh, Starship, oh-my-zsh), core CLI utilities, aqua, and mise
|
||||
- **NewToolbox.sh**: Script to scaffold new toolbox-* directories from the template (has been removed)
|
||||
- **toolbox-docstack**: Specialized toolbox for documentation generation with quarto, mdbook, marp, typst, markwhen, and joplin
|
||||
- **toolbox-qadocker**: Specialized toolbox for Docker image auditing and quality assurance with Hadolint, Dive, ShellCheck, Trivy, Dockle, Docker client, and Node.js
|
||||
- **NewToolbox.sh**: Script to scaffold new toolbox-* directories from the template (has been removed, use toolbox-template directly)
|
||||
- **toolbox-template**: Template directory for creating new toolboxes
|
||||
- **QWEN.md files**: Guidance for AI collaboration in various components (PROMPT files have been discontinued)
|
||||
|
||||
## Build and Release Workflow
|
||||
- Pre-build audit: Before building any Docker images, run comprehensive audits using the toolbox-qadocker image:
|
||||
- **Pre-build mandatory QA audit**: Before building any Docker images, run comprehensive audits using the toolbox-qadocker image:
|
||||
- `docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev hadolint Dockerfile`
|
||||
- `docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev shellcheck *.sh`
|
||||
- `docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev trivy fs --offline-scan .`
|
||||
- `docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev dockle .`
|
||||
- **Integrated QA process**: QA checks are now mandatory and built into the development cycle
|
||||
- Default build workflow: `./build.sh` produces a `:dev` tag; `./release.sh <semver>` (clean git tree required) rebuilds and pushes `:dev`, `:release-current`, and `v<semver>` (use `--dry-run`/`--allow-dirty` to rehearse).
|
||||
- Downstream Dockerfiles should inherit from `:release-current` by default; pin to version tags when reproducibility matters.
|
||||
|
||||
## Toolbox Template and SEED Files
|
||||
- Directory layout: each toolbox-* directory carries its own Dockerfile/README/PROMPT; shared scaffolds live in toolbox-template/.devcontainer and docker-compose.yml.
|
||||
- Use the NewToolbox.sh script to scaffold a new toolbox-* directory from toolbox-template (script has been removed).
|
||||
- Create new toolbox-* directories by copying the toolbox-template directory directly (NewToolbox.sh script has been removed).
|
||||
- Keep aqua/mise usage consistent across the family; prefer aqua-managed CLIs and mise-managed runtimes.
|
||||
- Reference toolbox-template when bootstrapping a new toolbox. Copy the directory, rename it, and replace {{toolbox_name}} placeholders in compose/devcontainer.
|
||||
- Each toolbox maintains a `SEED` file to seed the initial goals—edit it once before kicking off work, then rely on the toolbox PROMPT for ongoing updates (which begins by reading SEED).
|
||||
- All new toolboxes must pass comprehensive QA audits using toolbox-qadocker before being committed
|
||||
|
||||
## My Responsibilities
|
||||
- Maintain and enhance the ToolboxStack component
|
||||
@@ -85,6 +113,8 @@ I am the QWEN instance operating in the ToolboxStack component of the TSYSDevSta
|
||||
- Keep WORKLOG.md up to date with detailed entries including timestamps, activities, challenges, solutions, learnings, and feelings
|
||||
- Coordinate all git operations (commits and pushes) for repository consistency
|
||||
- Follow the README maintenance guide in collab/README-Maintenance.md to keep documentation up to date
|
||||
- Integrate toolbox-qadocker QA processes into all development workflows
|
||||
- Conduct proactive audits using toolbox-qadocker before builds to prevent issues
|
||||
|
||||
## Pre-Build Audit Workflow
|
||||
Before creating or updating any toolbox images, I must perform comprehensive audits using the toolbox-qadocker image:
|
||||
@@ -115,6 +145,7 @@ Before creating or updating any toolbox images, I must perform comprehensive aud
|
||||
The system is currently in a clean state, ready for a fresh rebuild:
|
||||
- ✅ Docker build cache has been cleared
|
||||
- ✅ All toolbox-base images have been removed
|
||||
- ✅ toolbox-qadocker image is fully implemented and working
|
||||
- ✅ System is ready for rebuild
|
||||
- ✅ Detailed worklog available in collab/WORKLOG.md
|
||||
|
||||
@@ -130,6 +161,12 @@ For detailed information about previous work, challenges, and solutions, see:
|
||||
4. Create comprehensive testing for all tools
|
||||
5. Document all tools in README with usage examples
|
||||
|
||||
## QA Process Integration
|
||||
With the toolbox-qadocker image now fully implemented and working, all toolbox builds will follow a mandatory QA process:
|
||||
1. **Pre-build audit**: Run comprehensive audits using toolbox-qadocker before any Docker build
|
||||
2. **Continuous validation**: Use QA tools throughout the development process
|
||||
3. **Post-build verification**: Validate all built images with security and compliance scans
|
||||
|
||||
## Ready State
|
||||
I am ready to proceed with any directed tasks. Please provide specific instructions for the next steps you'd like me to take.
|
||||
|
||||
@@ -155,6 +192,13 @@ As part of my role in maintaining the ToolboxStack, I may conduct ongoing audits
|
||||
- Best common practices for (dockerized) development/tooling stacks
|
||||
- Assessment of all existing toolboxes (base, dockstack, qadocker, and any others)
|
||||
|
||||
### QA-Driven Development Process
|
||||
With toolbox-qadocker now fully implemented, all development follows a QA-driven approach:
|
||||
1. **Preemptive QA**: Run audits before any code changes are implemented
|
||||
2. **Continuous Validation**: Validate changes with QA tools during development
|
||||
3. **Pre-Build Verification**: Ensure all code passes QA checks before Docker builds
|
||||
4. **Post-Build Assurance**: Verify built images meet all security and compliance standards
|
||||
|
||||
### Pre-Build Audit Process
|
||||
|
||||
Before building any Docker images, I must run comprehensive audits using the toolbox-qadocker image to check for:
|
||||
@@ -338,3 +382,23 @@ The toolbox-qadocker image is now an integral part of the development workflow w
|
||||
5. **For all new toolboxes**, the QA process is mandatory before they can be released
|
||||
|
||||
This ensures that all toolboxes meet the highest standards of security, reliability, and best practices.
|
||||
|
||||
## Development Cycle with QA-First Approach
|
||||
I should automatically handle the full development cycle of toolboxes with a QA-first approach:
|
||||
|
||||
1. **Preemptive Auditing**: Use the toolbox-qadocker image to check Dockerfiles and shell scripts for best practices, security issues, and common errors BEFORE any development work begins
|
||||
2. **Continuous Validation**: Run QA tools throughout the development process to catch issues early
|
||||
3. **Building**: Use build.sh scripts to build toolbox images with integrated QA checks
|
||||
4. **Testing**: Run comprehensive tests to verify functionality, including validation from within the container
|
||||
5. **Documentation**: Keep README.md and other docs up to date
|
||||
6. **Version Control**: Commit changes frequently with descriptive messages
|
||||
7. **Rebuilding**: When updating the base, rebuild all dependent toolboxes with QA validation
|
||||
|
||||
## Toolbox Management with QA Integration
|
||||
I can easily create new toolboxes or update existing ones with integrated QA processes:
|
||||
|
||||
- **Create new toolbox**: Use toolbox-template directly to scaffold a new toolbox-* directory (NewToolbox.sh script has been removed)
|
||||
- **Update existing toolbox**: Modify Dockerfile, aqua.yaml, or other config files with continuous QA validation
|
||||
- **Update base and rebuild**: Modify toolbox-base, then rebuild all dependent toolboxes with QA checks
|
||||
- **Testing**: Always test toolboxes after changes, including validation from within the container where all tools are available
|
||||
- **QA Validation**: Run comprehensive audits using toolbox-qadocker before committing any changes
|
||||
Reference in New Issue
Block a user