TSYSDevStack/ToolboxStack

🧰 ToolboxStack

Reproducible Developer Workspaces for TSYSDevStack

ToolboxStack provides reproducible developer workspaces for TSYSDevStack contributors. The current toolbox-base image captures the daily-driver container environment used across the project.

---

📋 Table of Contents

🔧 Component	📝 Description	📁 Path
🖥️ Dev Container Image	Ubuntu 24.04 base with shell tooling, mise, aqua-managed CLIs, and Docker socket access.	output/toolbox-base/Dockerfile
🛠️ Build Helpers	Wrapper scripts for building (build.sh) and running (run.sh) the Compose service.	output/toolbox-base/
🔌 Devcontainer Config	VS Code Remote Container definition referencing the Compose service.	output/toolbox-base/.devcontainer/devcontainer.json
📋 Prompt & Docs	Onboarding prompt plus a feature-rich README for future collaborators.	output/toolbox-base/PROMPT, output/toolbox-base/README.md
📝 Work Log	Comprehensive record of work conducted on the ToolboxStack component.	collab/WORKLOG.md
🤝 Collaboration Notes	Shared design prompts and coordination notes for toolbox evolution.	collab/
🔍 Audit Tools	Docker image auditing and quality assurance tools.	output/toolbox-qadocker/

---

🚀 Quick Start

Base Toolbox

cd output/toolbox-base
./build.sh        # build the image with UID/GID matching your host
./run.sh up       # launch the toolbox-base service in the background
docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh

Use ./run.sh down to stop the container when you are finished.

Audit Toolbox

cd output/toolbox-qadocker
./build.sh        # build the audit image
./run.sh          # run audit operations

---

🛠️ Available Toolboxes

🖥️ toolbox-base

• Purpose: Daily-driver development environment
• Features: Shell tooling (zsh, Starship), CLIs (aqua), runtimes (mise), Docker client
• Base: Ubuntu 24.04

🔍 toolbox-qadocker

• Purpose: Docker image auditing and quality assurance
• Features: Hadolint, ShellCheck, Trivy, Dive, Docker client, Buildctl, Dockerlint
• Base: Ubuntu 24.04 (independent of toolbox-base)

---

📊 Contribution Guidelines

✅ Best Practice	📝 Details
📝 Documentation	Document every tooling change in both the PROMPT and README.md.
📦 Tool Management	Prefer installing CLIs via aqua and language runtimes via mise to keep the environment reproducible.
🧹 Git Hygiene	Keep cache directories (.build-cache/, mise mounts) out of Git—they are already covered by the repo's .gitignore.
📝 Work Log	Update the work log in collab/WORKLOG.md with detailed entries for all significant work.
📚 Maintain Docs	Follow the README maintenance guide in collab/README-Maintenance.md to keep documentation up to date.
🔍 Audit Process	Use toolbox-qadocker to audit Dockerfiles and ensure best practices.

---

🧭 Working Agreement

• 🔄 Stacks stay in sync. When you add or modify automation, update both the relevant stack README and any linked prompts/docs.
• 📁 Collab vs Output. Use collab/ for planning and prompts, keep runnable artifacts under output/.
• 📈 Document forward. New workflows should land alongside tests and a short entry in the appropriate README table.
• 🤖 AI Agent Coordination. Use Qwen agents for documentation updates, code changes, and maintaining consistency across stacks.
• 📝 Work Log Maintenance. Keep collab/WORKLOG.md up to date with detailed entries including timestamps, activities, challenges, solutions, learnings, and feelings.

---

🤖 AI Agent

This stack is maintained by ToolboxBot, an AI agent focused on ToolboxStack workspace management.

---

📄 License

See LICENSE for full terms. Contributions are welcome—open a discussion in the relevant stack's collab/ area to kick things off.

---

📅 Recent Changes

Date	Change	Author
2025-10-31	Added toolbox-qadocker for Docker image auditing	ToolboxBot
2025-10-30	Enhanced documentation standards for beautiful READMEs	ToolboxBot
2025-10-29	Initial ToolboxStack setup and configuration	ToolboxBot