From 789cfc03a3e6540e7b824d1cb1d6f594d5f66d34 Mon Sep 17 00:00:00 2001
From: Hans Heinemann <hansheinemann@icloud.com>
Date: Sun, 15 Mar 2026 17:34:46 -0400
Subject: [PATCH] =?UTF-8?q?chore:=20reorganize=20=E2=80=94=20tools/=20subf?=
 =?UTF-8?q?older,=20README=20as=20central=20index=20with=20linked=20projec?=
 =?UTF-8?q?ts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                                     | 38 +++++++++++++------
 {gh-monitor => tools/gh-monitor}/buildspec.md |  0
 {gh-monitor => tools/gh-monitor}/design.md    |  0
 3 files changed, 26 insertions(+), 12 deletions(-)
 rename {gh-monitor => tools/gh-monitor}/buildspec.md (100%)
 rename {gh-monitor => tools/gh-monitor}/design.md (100%)

diff --git a/README.md b/README.md
index 599bb98..016a293 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,40 @@
 # hans-tools
 
-Personal tooling for Hans — GitHub PR monitoring, automation hooks, and utilities.
+Central reference for all tools built for Hans — small utilities live here,
+larger standalone projects are linked below.
 
-## Tools
+---
+
+## Small Tools (`tools/`)
 
 | Tool | Description | Status |
 |---|---|---|
-| `gh-monitor` | Polls GitHub for PR activity and notifies Hans via OpenClaw | Spec review |
+| [gh-monitor](tools/gh-monitor/) | Polls GitHub for PR activity, notifies Hans via OpenClaw | Spec review |
+
+---
+
+## Larger Projects
+
+| Project | Repo | Description | Status |
+|---|---|---|---|
+| the-agency | [coding-with-hans-heinemann/the-agency](https://github.com/coding-with-hans-heinemann/the-agency) | Tiered multi-agent orchestration pipeline (T1–T5) | Phase 2 complete |
+
+---
 
 ## Structure
 
 ```
 hans-tools/
-├── gh-monitor/           # GitHub PR polling monitor
-│   ├── design.md         # Design doc
-│   ├── buildspec.md      # Build spec
-│   └── ...               # Implementation (pending review)
-└── README.md
+├── tools/                  # Self-contained small tools
+│   └── <tool-name>/
+│       ├── design.md
+│       ├── buildspec.md
+│       └── ...
+└── README.md               # This index
 ```
 
-## Principles
+## Conventions
 
-- Every tool has a design doc and build spec reviewed before implementation
-- No secrets in the repo — all credentials via environment variables
-- Tools run as cron jobs or daemons managed by OpenClaw
+- Every tool has a `design.md` and `buildspec.md` reviewed before implementation
+- No secrets in the repo — credentials via environment variables only
+- All work on feature branches (`hans/...`), never directly to `main`
diff --git a/gh-monitor/buildspec.md b/tools/gh-monitor/buildspec.md
similarity index 100%
rename from gh-monitor/buildspec.md
rename to tools/gh-monitor/buildspec.md
diff --git a/gh-monitor/design.md b/tools/gh-monitor/design.md
similarity index 100%
rename from gh-monitor/design.md
rename to tools/gh-monitor/design.md