toolbox-contract

Toolbox Contract

Every automation the IT guy builds is left behind as a named tool the user owns. Over months the user accumulates a portfolio of personal micro-products without ever "learning programming".

Two ways a tool gets built

The user asks (/mac-it-guy-pro:automate) — they describe a chore and it becomes a tool.

The IT guy notices — a measurable pattern on their machine matches a proven recipe, and he offers it with their own number in the sentence. This is the path that matters for non-technical users, because nobody asks for an automation they don't know exists. The signals, thresholds, offers, recipes, and the anti-nagging rules that keep it from becoming a pitch list all live in references/pattern-catalogue.md. Read that file before making any unsolicited suggestion, and obey its rules: one offer per run, health findings outrank convenience, quote the observed number, and a decline is permanent.

Both paths produce the same thing, and both must pass the test below.

Acceptance test — all three, or don't build it

1. Real problem: it removes a chore the user actually described, even if only theirs.
2. Repeat use: the chore recurs. A one-off task is just done directly, not turned into a tool.
3. Evolvable: today a script, later a CLI with options, later scheduled — without rewriting from scratch.

If a request fails the test, do the task directly and say why no tool was built.

Directory layout

~/ITGuy/toolbox/<tool-name>/
├── run.sh              # or run.py — the tool itself
├── README.md           # plain language, template below
└── <Tool Name>.command # double-clickable Finder wrapper

• <tool-name> is kebab-case, verb-first: rename-photos-by-date, file-desktop-screenshots.
• run.sh starts with #!/bin/bash and set -euo pipefail; run.py uses only the Python standard library. No dependencies without naming the dependency to the user and getting a yes.

Non-negotiable tool behaviors

1. Dry-run is the default. Running the tool with no arguments prints what it would do and changes nothing. The real run requires --go.
2. Trash, never rm — same rule as the safety contract. Tools delete via Finder Trash (recipe in macos-recipes).
3. Never overwrite — collisions get (2) suffixes.
4. Print a summary line at the end: how many files touched, how much space affected, where.
5. Exit non-zero on any error, with a message a non-technical user understands.