AI Agent toolbox for software architecture
Audience: Humans (GitHub landing page)
A structured knowledge base that turns AI coding agents into architecture-aware partners — built for senior software professionals: architects, tech leads, principal engineers, solution architects, technical consultants, and anyone working at the intersection of code and architecture decisions.
Give your AI coding assistant the skills to do real architecture work — analysis, synthesis, auditing, contextualization, documentation, reporting, planning, and more.
It ships as a git submodule your agent reads at session start. No plugins, no API calls — just markdown that teaches the agent how to think about architecture.
- Analysis — Architecture analysis (SQLite-first), security analysis, nonfunctional analysis, architecture synthesis, fitness functions
- Code Intelligence — Full call-graph extraction into SQLite; SQL-speed queries at near-zero token cost
- Architecture — TOGAF ADM (Preliminary + Phases A-H), C4 modeling with Structurizr DSL
- Workflows — Session lifecycle (
/start,/update,/upgrade), git conventions, task management - Outputs — 9 structured formats: architecture docs, PDF reports, presentations, C4 workspaces, Excalidraw, and more
Copy and paste this prompt to your AI assistant:
Add the AI architect toolbox by adding a git submodule from
https://github.com/quantum-crowbar/quantum-toolbox.gitinto.quantum-toolbox. Once downloaded, readAGENTS.mdand the toolkit files it references, then run/start.
This will:
- Add the toolbox as a submodule
- Load the skill catalog and bootstrap workflows
- Run
/start— which detects first-time setup vs. established project - First-time: guide you through 8-step project setup (AGENTS.md, CONTEXT.md, enabled skills)
- Established project: print a live snapshot of enabled skills, code-graph status, and available commands
At the start of every session, run:
/start
The agent reads your project's AGENTS.md and CONTEXT.md, validates enabled skills and the analysis manifest, and prints a status snapshot — code-graph currency, any dependency warnings, and available commands. Use /skills to see the full skill list, or /help for the complete command reference.
All commands are invoked by typing them directly to your agent:
| Command | What it does | Modifies files? |
|---|---|---|
/start |
Orient the agent: presents project state, enabled skills, and available commands. Detects first-time setup vs. established project. | No |
/help |
Full command reference with descriptions and examples. | No |
/skills |
Lists all registered skills with enabled/disabled status for your project. | No |
/update |
Refresh the KB. Re-runs enabled analysis skills on source repos that have changed since the last run, regenerates affected views and documentation, then writes updated SHAs and view lists back to the manifest and context files. Also checks toolkit version — flags if /upgrade should follow. |
Yes |
/upgrade |
Apply a new toolkit version. Pulls the latest toolkit, diffs old→new (new skills, views, reports, config requirements), checks source staleness, then generates new views/reports and re-runs analysis where needed. By the end, project is fully current with the new toolkit version. | Yes (on confirm) |
/updatevs/upgrade—/updatekeeps your KB current with code changes (source repos moved ahead)./upgradekeeps your KB current with toolkit changes (new skills, views, hooks shipped in a new version). Run both after updating the submodule.
There are two commands for keeping your knowledge base in sync — one for source changes, one for toolkit changes.
When your source repos have changed (code commits since the last analysis run):
/update
Re-runs enabled analysis skills on the repos that moved, regenerates the affected architecture-docs views, and writes updated SHAs + view lists back to the manifest and context files. Both source and documentation are refreshed together.
When the toolkit has a new version (you've pulled a new .quantum-toolbox):
/upgrade
Pulls the latest toolkit, diffs v_old → v_new for new skills, views, reports, and config requirements, then generates new views/reports and re-runs analysis where the new views need fresh source data. By the end, your project is fully current with the new toolkit version — new views generated, missing config inserted, source re-analysed where needed.
Run
/updateroutinely as code evolves. Run/upgradeafter pulling a new toolkit version — and/updatefirst if your sources are also stale.
| Model | Best For | When to Use |
|---|---|---|
| Claude Haiku | Fast, simple tasks | Quick edits, simple questions, code formatting |
| Claude Sonnet | Balanced performance | Most coding tasks, analysis, debugging |
| Claude Opus | Complex reasoning | Architecture design, large refactors, multi-file changes |
The toolkit is built around a single core idea: the mental model is the engine.
graph TD
MM["<b>Mental Model</b><br/><i>architecture-thinking.md</i><br/><br/>Domains · Stakeholders · Principles<br/>Gap Analysis · Risk · Prioritization"]
MM --> A["Analysis Skills"]
MM --> M["Modeling Skills"]
MM --> W["Workflow Skills"]
A --> O["Outputs<br/><i>9 formats</i>"]
M --> O
W --> O
core/architecture-thinking.md defines how the agent thinks about architecture — which domains to consider, which stakeholders matter, how to analyze gaps, assess risk, and prioritize work. Every analysis skill, every TOGAF phase, every output adapter inherits its lens from this file.
This means you can change how the toolkit thinks:
- Override sections — Add a domain, swap prioritization criteria, adjust stakeholder types. Drop an
architecture-thinking.local.mdin your project root and the agent layers your changes on top of the defaults. - Swap the entire model (coming soon) — Select a named profile (
lean-startup,platform-eng,regulated-enterprise) for a fundamentally different architectural worldview.
The skills are the tools. The mental model is what makes them coherent.
The toolkit provides 30+ specialized skills organized into 5 categories:
| Category | Count | Skills |
|---|---|---|
| Analysis | 5 | arch-analysis (default), security-analysis, nonfunctional-analysis, architecture-synthesis, fitness-functions |
| Code Intelligence | 2 | code-graph (SQLite call-graph extraction), coding-profile |
| Architecture | 11 | structurizr, TOGAF ADM (Preliminary + Phases A-H) |
| Workflow | 4 | bootstrap (session lifecycle), git-workflow, todo-workflow, update-logs |
| Output | 9 | core-architecture, architecture-docs, coding-context, product-spec, structurizr, archimate, presentation, pdf-report, excalidraw-import |
"Analyze the architecture" → arch-analysis
"Analyze this codebase" → arch-analysis (default entry point)
"Extract the code graph" → code-graph
"Analyze security with OWASP" → security-analysis
"Apply TOGAF Business Architecture" → togaf/business-architecture
"Create C4 model" → structurizr
"Analyse this excalidraw file" → excalidraw-import
"Export to PDF" → pdf-report
"Generate presentation" → presentation
Full skill documentation: docs/skills/README.md
.
├── AGENTS.md # Agent entry point (lean router)
├── core/ # Core concepts and workflows
│ ├── instructions.md # Coding rules, safety
│ ├── workflows.md # Development processes
│ ├── architecture-thinking.md # TOGAF foundations
│ └── glossary.md # Standard terminology
├── skills/ # Modular skill packages
│ ├── _index.md # Canonical skill catalog
│ ├── core/ # Always-active skills
│ └── optional/ # Opt-in skills
├── templates/ # Commit, PR templates
├── docs/ # Human-readable guides
└── specs/ # Specifications & roadmaps
See the toolkit in action on a real codebase: quantum-blockchain — a Python/Flask blockchain microservice with the toolkit wired up, custom mental model overrides (Consensus Architecture, Network Topology), and copy-paste prompts to try.
| Resource | Description |
|---|---|
| Skills Documentation | Full skill listing with detailed guides |
| Skills Index | Skill catalog and activation guide |
| TOGAF Index | ADM phases and when to use each |
| Analysis Outputs | Available export formats |
| Architecture Guide | How to analyze unfamiliar codebases |
| Roadmap | Planned work and progress |
MIT