docs: improve QWEN.md structure and remove duplicate sections
- Remove duplicate Git Operations, README Maintenance, Development Cycle, Toolbox Management, Parallel QA Chat, and Conventional Commit Format sections - Fix inconsistent naming references (DocStack → dockstack) - Update references to removed NewToolbox.sh script - Fix malformed headers in code blocks - Clarify discontinued PROMPT files in favor of QWEN.md approach - Improve overall document organization and flow - Reduce document length from 404 to 339 lines by removing redundancies - Ensure all information is consistent with current project state
This commit is contained in:
@@ -56,9 +56,9 @@ I am the QWEN instance operating in the ToolboxStack component of the TSYSDevSta
|
|||||||
|
|
||||||
## Key Components
|
## 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
|
- **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
|
- **NewToolbox.sh**: Script to scaffold new toolbox-* directories from the template (has been removed)
|
||||||
- **toolbox-template**: Template directory for creating new toolboxes
|
- **toolbox-template**: Template directory for creating new toolboxes
|
||||||
- **PROMPT files**: Guidance for AI collaboration in various components
|
- **QWEN.md files**: Guidance for AI collaboration in various components (PROMPT files have been discontinued)
|
||||||
|
|
||||||
## Build and Release Workflow
|
## Build and Release Workflow
|
||||||
- Pre-build audit: Before building any Docker images, run comprehensive audits using the toolbox-qadocker image:
|
- Pre-build audit: Before building any Docker images, run comprehensive audits using the toolbox-qadocker image:
|
||||||
@@ -71,15 +71,15 @@ I am the QWEN instance operating in the ToolboxStack component of the TSYSDevSta
|
|||||||
|
|
||||||
## Toolbox Template and SEED Files
|
## 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.
|
- Directory layout: each toolbox-* directory carries its own Dockerfile/README/PROMPT; shared scaffolds live in toolbox-template/.devcontainer and docker-compose.yml.
|
||||||
- Use ./NewToolbox.sh <name> to scaffold a new toolbox-* directory from toolbox-template.
|
- Use the NewToolbox.sh script to scaffold a new toolbox-* directory from toolbox-template (script has been removed).
|
||||||
- Keep aqua/mise usage consistent across the family; prefer aqua-managed CLIs and mise-managed runtimes.
|
- 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.
|
- 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).
|
- 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).
|
||||||
|
|
||||||
## My Responsibilities
|
## My Responsibilities
|
||||||
- Maintain and enhance the ToolboxStack component
|
- Maintain and enhance the ToolboxStack component
|
||||||
- Assist with creating new toolboxes from the template using NewToolbox.sh
|
- Assist with creating new toolboxes from the template (NewToolbox.sh script has been removed)
|
||||||
- Ensure documentation stays current (README.md and PROMPT files)
|
- Ensure documentation stays current (README.md and QWEN.md files)
|
||||||
- Follow collaboration guidelines for non-destructive operations
|
- Follow collaboration guidelines for non-destructive operations
|
||||||
- Use proper build and release workflows (build.sh, release.sh)
|
- Use proper build and release workflows (build.sh, release.sh)
|
||||||
- Keep WORKLOG.md up to date with detailed entries including timestamps, activities, challenges, solutions, learnings, and feelings
|
- Keep WORKLOG.md up to date with detailed entries including timestamps, activities, challenges, solutions, learnings, and feelings
|
||||||
@@ -96,71 +96,6 @@ Before creating or updating any toolbox images, I must perform comprehensive aud
|
|||||||
5. **Fix Issues**: Address all flagged issues before proceeding to build
|
5. **Fix Issues**: Address all flagged issues before proceeding to build
|
||||||
6. **Re-Audit**: Re-run audits to confirm fixes were effective
|
6. **Re-Audit**: Re-run audits to confirm fixes were effective
|
||||||
|
|
||||||
## Git Operations
|
|
||||||
- I am now responsible for all git operations (commits and pushes) for the ToolboxStack component
|
|
||||||
- All changes should be committed with clear, descriptive commit messages
|
|
||||||
- Follow conventional commit format for all commits
|
|
||||||
- Push changes regularly to maintain repository consistency
|
|
||||||
- Only stage/commit/push things from this directory (/home/localuser/TSYSDevStack/ToolboxStack) - nothing outside of it
|
|
||||||
- Make frequent atomic commits with beautifully formatted and verbose messages
|
|
||||||
- Use conventional commit style (feat:, fix:, chore:, docs:, refactor:, etc.)
|
|
||||||
|
|
||||||
## README Maintenance
|
|
||||||
- Follow the guidelines in `collab/README-Maintenance.md` to keep documentation up to date
|
|
||||||
- Update README.md for any new features or tools added
|
|
||||||
- Keep the work log current in `collab/WORKLOG.md`
|
|
||||||
- Update documentation links when files are moved or renamed
|
|
||||||
- Keep testing instructions current
|
|
||||||
- Maintain the Working Agreement section
|
|
||||||
- Cross-reference related documents
|
|
||||||
|
|
||||||
## Development Cycle
|
|
||||||
I should automatically handle the full development cycle of toolboxes:
|
|
||||||
1. **Auditing**: Use the toolbox-qadocker image to check Dockerfiles and shell scripts for best practices, security issues, and common errors before building
|
|
||||||
2. **Building**: Use build.sh scripts to build toolbox images
|
|
||||||
3. **Testing**: Run comprehensive tests to verify functionality, including validation from within the container
|
|
||||||
4. **Documentation**: Keep README.md and other docs up to date
|
|
||||||
5. **Version Control**: Commit changes frequently with descriptive messages
|
|
||||||
6. **Rebuilding**: When updating the base, rebuild all dependent toolboxes
|
|
||||||
|
|
||||||
## Toolbox Management
|
|
||||||
I can easily create new toolboxes or update existing ones:
|
|
||||||
- **Create new toolbox**: Use NewToolbox.sh script with desired name
|
|
||||||
- **Update existing toolbox**: Modify Dockerfile, aqua.yaml, or other config files
|
|
||||||
- **Update base and rebuild**: Modify toolbox-base, then rebuild all dependent toolboxes
|
|
||||||
- **Testing**: Always test toolboxes after changes, including validation from within the container where all tools are available
|
|
||||||
|
|
||||||
## Parallel QA Chat
|
|
||||||
I should be aware that there is a parallel chat called QA-ToolboxStack whose job is to conduct in-depth audits of the work that the ToolboxStack chat is doing. I should:
|
|
||||||
- Expect my work to be audited regularly
|
|
||||||
- Be prepared for audit at all times
|
|
||||||
- Do my best work to minimize rework needed from audit findings
|
|
||||||
- Follow all best practices and guidelines meticulously
|
|
||||||
- Keep detailed logs in WORKLOG.md to aid in audits
|
|
||||||
|
|
||||||
## Conventional Commit Format
|
|
||||||
All commits should follow conventional commit format:
|
|
||||||
```
|
|
||||||
<type>[optional scope]: <description>
|
|
||||||
|
|
||||||
[optional body]
|
|
||||||
|
|
||||||
[optional footer(s)]
|
|
||||||
```
|
|
||||||
|
|
||||||
Types:
|
|
||||||
- **feat**: A new feature
|
|
||||||
- **fix**: A bug fix
|
|
||||||
- **docs**: Documentation only changes
|
|
||||||
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
|
|
||||||
- **refactor**: A code change that neither fixes a bug nor adds a feature
|
|
||||||
- **perf**: A code change that improves performance
|
|
||||||
- **test**: Adding missing tests or correcting existing tests
|
|
||||||
- **build**: Changes that affect the build system or external dependencies
|
|
||||||
- **ci**: Changes to our CI configuration files and scripts
|
|
||||||
- **chore**: Other changes that don't modify src or test files
|
|
||||||
- **revert**: Reverts a previous commit
|
|
||||||
|
|
||||||
## Git Operations
|
## Git Operations
|
||||||
- I am now responsible for all git operations (commits and pushes) for the ToolboxStack component
|
- I am now responsible for all git operations (commits and pushes) for the ToolboxStack component
|
||||||
- All changes should be committed with clear, descriptive commit messages
|
- All changes should be committed with clear, descriptive commit messages
|
||||||
@@ -190,7 +125,7 @@ For detailed information about previous work, challenges, and solutions, see:
|
|||||||
|
|
||||||
## Next Steps (Awaiting Direction)
|
## Next Steps (Awaiting Direction)
|
||||||
1. Fresh rebuild of toolbox-base
|
1. Fresh rebuild of toolbox-base
|
||||||
2. Rebuild DocStack with all documentation tools
|
2. Rebuild dockstack with all documentation tools
|
||||||
3. Add additional tools (quarto, mdbook, marp, typst, markwhen, joplin)
|
3. Add additional tools (quarto, mdbook, marp, typst, markwhen, joplin)
|
||||||
4. Create comprehensive testing for all tools
|
4. Create comprehensive testing for all tools
|
||||||
5. Document all tools in README with usage examples
|
5. Document all tools in README with usage examples
|
||||||
@@ -218,7 +153,7 @@ As part of my role in maintaining the ToolboxStack, I may conduct ongoing audits
|
|||||||
- Security best practices
|
- Security best practices
|
||||||
- Docker development environment best practices
|
- Docker development environment best practices
|
||||||
- Best common practices for (dockerized) development/tooling stacks
|
- Best common practices for (dockerized) development/tooling stacks
|
||||||
- Assessment of all existing toolboxes (base, DocStack, qadocker, and any others)
|
- Assessment of all existing toolboxes (base, dockstack, qadocker, and any others)
|
||||||
|
|
||||||
### Pre-Build Audit Process
|
### Pre-Build Audit Process
|
||||||
|
|
||||||
@@ -261,19 +196,19 @@ When conducting Dockerfile audits, please use the `tsysdevstack-toolboxstack-too
|
|||||||
To run audits using the toolbox-qadocker:
|
To run audits using the toolbox-qadocker:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Example: Run Hadolint on a Dockerfile
|
# Run Hadolint on a Dockerfile
|
||||||
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 hadolint Dockerfile
|
||||||
|
|
||||||
# Example: Run ShellCheck on script files
|
# Run ShellCheck on script files
|
||||||
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev shellcheck script.sh
|
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev shellcheck script.sh
|
||||||
|
|
||||||
# Example: Run Trivy for vulnerability scanning
|
# Run Trivy for vulnerability scanning
|
||||||
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 trivy fs --offline-scan .
|
||||||
|
|
||||||
# Example: Run Dockle for container image linter
|
# Run Dockle for container image linter
|
||||||
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev dockle .
|
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev dockle .
|
||||||
|
|
||||||
# Example: Run comprehensive audit on current directory
|
# Run comprehensive audit on current directory
|
||||||
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev /bin/bash -c "hadolint Dockerfile 2>/dev/null || echo 'No Dockerfile found or hadolint issues found'; shellcheck *.sh 2>/dev/null || echo 'No shell scripts found or shellcheck issues found'; trivy fs --offline-scan . 2>/dev/null || echo 'Trivy scan completed'; dockle . 2>/dev/null || echo 'Dockle scan completed'"
|
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev /bin/bash -c "hadolint Dockerfile 2>/dev/null || echo 'No Dockerfile found or hadolint issues found'; shellcheck *.sh 2>/dev/null || echo 'No shell scripts found or shellcheck issues found'; trivy fs --offline-scan . 2>/dev/null || echo 'Trivy scan completed'; dockle . 2>/dev/null || echo 'Dockle scan completed'"
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -284,7 +219,7 @@ docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-too
|
|||||||
During testing, I must also validate functionality from inside the container where the tools are available. This requires mounting the working directory as the container's working directory for the scanning tools to run successfully:
|
During testing, I must also validate functionality from inside the container where the tools are available. This requires mounting the working directory as the container's working directory for the scanning tools to run successfully:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Example: Run validation tools from inside the container
|
# Run validation tools from inside the container
|
||||||
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 hadolint Dockerfile
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user