# small-scripts

A collection of small, standalone utility scripts for daily use. Scripts are symlinked into `~/sbin` for PATH availability.

## Approach

This project uses **spec-driven development** (OpenSpec) as a testbed for agent-driven development and refinement:

1. Every script starts with a spec in `specs/`
2. Every script supports `--dryrun` to preview actions without side effects
3. Every script has a test in `tests/` that validates dryrun behaviour against the spec

## Scripts

| Script | Purpose | Status |
|--------|---------|--------|
| `git-status-report` | Recursive git repo status with diff stats | Done |
| `md-to-docx` | Markdown to DOCX conversion | Done |
| `claude-profile` | Claude Code profile + engagement-mode launcher | Done |
| `unreflected-logs` | Scan projects for unreflected session logs | Done |
| `validate-skill` | Validate SKILL.md files against known Claude Code restrictions | Done |

### Engagement modes (claude-profile)

`claude-profile` launches Claude Code with both a configuration profile (selecting which `~/.claude-*` directory to use) and an **engagement mode** that bundles a driver model, subagent policy, async tolerance, and workflow stance:

| Mode | Driver | For |
|---|---|---|
| `chat` | Haiku | No project, just conversation |
| `quick` | Sonnet | Single small focused job, fully synchronous |
| `deep` | Sonnet (Opus via named workflows) | Hard design or debugging, plan + spec enforced |
| `hybrid` | Haiku (Opus/Sonnet on demand) | Long sessions, escalates only when needed |
| `orch` | Sonnet | Decompose work and dispatch container agents |

Mode definitions live in `data/claude-profile/modes/<name>.md` — YAML frontmatter (machine-parsed) plus a markdown body that becomes part of the system prompt.

```bash
claude-profile                              # interactive picker
claude-profile oreillyit --mode deep        # explicit profile + mode
claude-profile --preset deep-cluster        # named preset from presets.yaml
claude-profile --dryrun [...]               # show resolved values, do not launch
```

Copy `data/claude-profile/presets.yaml.example` to `$CLAUDE_CONFIG_DIR/presets.yaml` to set up named presets.

## Repository Structure

```
small-scripts/
├── scripts/                  # Executable scripts (symlinked into ~/sbin)
├── specs/                    # OpenSpec files, one per script
├── tests/                    # Test scripts that exercise --dryrun
├── data/                     # Read-only data files used by scripts
│   └── claude-profile/
│       ├── modes/            # Engagement mode definitions
│       └── presets.yaml.example
└── memory/                   # Tiered memory topic files
```

## Quick Start

```bash
# Run all tests
./tests/run-all.sh

# Symlink a script into ~/sbin
ln -sf "$(pwd)/scripts/<name>" ~/sbin/<name>
```

## Milestones

| # | Description | Status |
|---|-------------|--------|
| M1 | Project setup, first script | In progress |