cassette-flows

What this skill does

# Cassette Flows

Help users build and maintain Cassette processing pipelines. Cassette watches a directory for meeting transcript files, sends them through one or more LLM prompts, and writes structured Markdown output.

GitHub: https://github.com/adawalli/cassette

Run without installing: `bunx @cassette-meetings/cli` or `npx @cassette-meetings/cli`
Install globally (optional): `bun add -g @cassette-meetings/cli` or `npm install -g @cassette-meetings/cli`

Global install gives you a `cassette` command, but `bunx`/`npx` works just as well for everyday use and in LaunchAgent configs. The user doesn't need to install globally unless they want to.

## What you can help with

1. **Create new configs** - run `cassette init` and walk the user through customizing their `config.yaml`
2. **Design prompt chains** - help write and iterate on the LLM prompts used in processing steps
3. **Add or modify steps** - extend an existing flow with new processing stages
4. **Debug failures** - diagnose why transcripts fail, inspect error logs, validate config
5. **Generate Obsidian-formatted output** - craft prompts that produce notes with YAML front matter, wikilinks, and Obsidian conventions
6. **Optimize for specific transcript sources** - tune extraction settings for different transcript formats (MacWhisper, Otter, Teams, Zoom, etc.)
7. **Set up macOS notifications** - install terminal-notifier and configure `on_complete` hooks
8. **Run as a system service** - set up a macOS LaunchAgent so cassette starts automatically at login

## Reference materials

Before generating or editing configs, load the relevant reference:

- **Config schema** (all fields, types, defaults): [references/config-schema.md](references/config-schema.md)
- **Working example** (two-step flow with intake): [references/example-config.yaml](references/example-config.yaml)

Read the schema reference first so you know the exact field names and constraints. The example config shows how a real flow fits together.

## How cassette works

Cassette's processing pipeline:

```
[intake (optional)] -> [watch directory] -> [extract transcript] -> [step 1: LLM] -> [step 2: LLM] -> ... -> [output .md] -> [on_complete hook]
```

Key concepts:

- **Watch** monitors a directory for `.json` and `.vtt` files, waits for them to stabilize, then queues them. Many users just drop transcripts straight into this directory - that's the simplest setup.
- **Intake** (optional) watches a separate source directory (like Downloads) and moves matching files into the watch directory, organized by week. Only needed when transcripts land somewhere the user can't control.
- **Steps** are chained LLM calls. Each step's output becomes the next step's input. You can use a single `prompt:` or multiple `steps:` (not both)
- **On complete** fires a shell command after the final step (macOS notifications, moving files, etc.)

Files are processed serially (one at a time) to avoid overwhelming the LLM endpoint.

## Creating a new config

Start with `cassette init` to generate a starter config, then modify it based on the user's needs. This is faster and less error-prone than writing a config from scratch.

### Step 1: Generate the starter config

```bash
# generates ~/.config/cassette/config.yaml
bunx @cassette-meetings/cli init

# or with a custom path
bunx @cassette-meetings/cli init --config ~/path/to/config.yaml

# overwrite an existing config
bunx @cassette-meetings/cli init --force
```

The starter config includes sensible defaults: a single-prompt flow, `~/Documents/meetings` as the watch directory, and commented-out sections for intake and on_complete hooks.

### Step 2: Gather user needs

Ask the user these questions to know what to change in the generated config:

1. **Where do transcripts come from?** This determines format and transcript extraction settings.
   - **VTT (Teams, Zoom, Meet)** - the most common format. VTT files are parsed natively, so no transcript extraction tuning is needed. However, the `transcript` section must still exist in the config (cassette validates it even for VTT-only workflows - just leave the defaults).
   - **JSON (MacWhisper, Otter, etc.)** - needs `transcript.path`, `transcript.speaker_field`, and `transcript.text_field` configured to match the JSON structure. MacWhisper typically uses a root array with `speaker` + `text` fields.
   - **Other** - ask about the file format and JSON structure

2. **How do transcripts get to cassette?**
   - If the user drops files into a known folder (or a tool exports there), just set that as `watch.root_dir` - no intake needed. This is the simpler default.
   - If transcripts land somewhere messy (like ~/Downloads), enable the `intake` section to auto-move matching files into `watch.root_dir` organized by week.

3. **What LLM endpoint?** Any OpenAI-compatible API works. Sets `llm.base_url` and `llm.model`. The user needs an API key set as `OPENAI_API_KEY` in their environment.

4. **What should the output look like?** This drives the prompt design:
   - Plain markdown summary (the starter config default)
   - Obsidian-formatted with YAML front matter and wikilinks
   - A specific template the user has in mind
   - Multi-step (clean first, then summarize) - replace the single `prompt:` with a `steps:` array

5. **Any special needs?**
   - Name corrections (common with transcription software)
   - Domain-specific terms or acronyms
   - Notifications on completion
   - Copying output to a second location (see `output.copy_to`)

### Step 3: Modify the generated config

Read the generated config, apply the user's answers, and write it back. Use the config schema reference for exact field names and types. For multi-step flows, replace the `prompt:` field with a `steps:` array - the example config shows a complete two-step clean-then-summarize setup.

## Writing good cassette prompts

Cassette prompts receive the extracted transcript as input. The prompt you write is sent to the LLM along with the transcript text. Tips:

### Structure prompts clearly

Give the LLM a role, numbered instructions, and explicit output format. Transcripts can be long, so front-load the important instructions.

### Use `<notes_for_ai>` blocks for metadata

This pattern works well for supplying context that helps the LLM without cluttering the main instructions:

```yaml
prompt: |
  Your main instructions here...

  <notes_for_ai>
  <names>
    <explanation>Correct spellings for names the transcription gets wrong</explanation>
    - Sarah (not Sara)
    - Miguel (not Michael)
  </names>
  <terms>
    - JIRA - project tracking tool
    - OKR - objectives and key results
  </terms>
  </notes_for_ai>
```

### Multi-step flows

The most common pattern is clean-then-summarize:

- **Step 1 (clean)**: Fix transcription errors, merge fragments, preserve speaker labels
- **Step 2 (summarize)**: Structured summary with sections, action items, key points

Each step gets the previous step's output as input, so step 2 works with clean text rather than raw transcript noise.

### Understanding output files

Each step writes its own output file using the step's `suffix` field. For a source file called `standup-2026-03-18.vtt` with a two-step flow:

| Step | Suffix | Output file |
| --- | --- | --- |
| clean | `.cleaned.md` | `standup-2026-03-18.cleaned.md` |
| summarize | `.summary.md` | `standup-2026-03-18.summary.md` |

All output files land in the same directory as the source transcript. The last step's output is what `on_complete` and `copy_to` reference. The intermediate files (like the cleaned transcript) stick around for debugging but the final summary is the one the user typically cares about.

For a single-prompt config (no steps), the output uses `output.markdown_suffix` (default `.md`).

### Obsidian-formatted output

When the user wants Obsidian-compatible notes, include in the prompt:

- YAML front matter with the fields their vault expects (date, tags, people, etc.)
- `[[wikilink]]` format fo