small-scripts/CLAUDE.md

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
├── data/              # Read-only data files consumed by scripts
│   └── <script-name>/ # One subdirectory per script that needs data
└── memory/            # Tiered memory topic files
    └── log/           # Session logs

data/ directory

Some scripts need static data that is too large or too structured to embed inline (e.g. claude-profile reads engagement mode definitions from data/claude-profile/modes/*.md). Put such data under data/<script-name>/. Treat it as read-only at runtime — user customisation belongs in the user's config directory, not in data/. Example files (e.g. presets.yaml.example) live alongside the data and are copied by the user into their config dir.

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