Initial project setup for small-scripts

Spec-driven utility script collection with dryrun support and
automated testing. Includes project docs, test runner, and
directory structure.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md — small-scripts
+
+## Overview
+
+A collection of small, standalone utility scripts designed to be symlinked into `~/sbin`. Development follows an **agent-driven, spec-first workflow** using OpenSpec — this project is the initial testbed for that approach.
+
+## Key Principles
+
+1. **Spec-first development.** Every script starts with an OpenSpec in `specs/`. No implementation without a spec.
+2. **Dryrun by default.** Every script MUST support a `--dryrun` (or `-n`) flag that previews all actions without making changes. Dryrun output should clearly show what *would* happen.
+3. **Test via dryrun.** Each script has a corresponding test script in `tests/` that exercises the main script's `--dryrun` mode to verify behaviour matches the spec.
+4. **Symlink deployment.** Scripts are linked to `~/sbin` for PATH availability — the repo is the source of truth, not the installed copy.
+
+## Repository Structure
+
+```
+small-scripts/
+├── CLAUDE.md          # This file — project conventions
+├── MEMORY.md          # Thin index linking to memory/ topic files
+├── FUTURE.md          # Backlog of ideas
+├── README.md          # Human-readable docs
+├── specs/             # OpenSpec files (one per script)
+│   └── <script-name>.spec.md
+├── scripts/           # The actual scripts
+│   └── <script-name>
+├── tests/             # Test scripts (one per main script)
+│   └── test-<script-name>.sh
+└── memory/            # Tiered memory topic files
+    └── log/           # Session logs
+```
+
+## Workflow
+
+### Adding a new script
+
+1. **Write the spec** — Create `specs/<script-name>.spec.md` using OpenSpec format
+2. **Implement the script** — Create `scripts/<script-name>`, ensuring `--dryrun` support
+3. **Write the test** — Create `tests/test-<script-name>.sh` that validates dryrun output against spec expectations
+4. **Verify** — Run the test, confirm pass
+5. **Symlink** — `ln -sf "$(pwd)/scripts/<script-name>" ~/sbin/<script-name>`
+
+### Script conventions
+
+- Scripts should be idempotent and safe to re-run
+- Exit non-zero on failure
+- Use colour output for status messages where appropriate
+- Include a `--help` flag with usage information
+- Shebang line should specify the interpreter explicitly (e.g., `#!/usr/bin/env bash`, `#!/usr/bin/env python3`)
+- `--dryrun` / `-n` must be supported — it previews actions without side effects
+
+### Test conventions
+
+- Test scripts live in `tests/` and are named `test-<script-name>.sh`
+- Tests invoke the main script with `--dryrun` and assert on output/exit codes
+- Tests should be runnable standalone: `./tests/test-<script-name>.sh`
+- Use colour output (green/red) for pass/fail
+- Exit non-zero if any assertion fails
+- A top-level `./tests/run-all.sh` runs every test and summarises results
+
+### OpenSpec format
+
+Specs define:
+- **Purpose** — What the script does, in one sentence
+- **Usage** — CLI interface, flags, arguments
+- **Behaviour** — Step-by-step description of what the script does
+- **Dryrun behaviour** — What `--dryrun` outputs (explicitly)
+- **Edge cases** — Known boundary conditions and expected handling
+- **Examples** — Concrete input/output examples
+
+## Environment
+
+- Scripts target Linux (Ubuntu/Debian primarily)
+- Bash is the default language unless complexity warrants Python
+- `~/sbin` is in the user's PATH