# 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