Pedalboard Pluginary VST3/AU Plugin Scanner

Development guidelines for working on the pedalboard-pluginary project - a robust audio plugin management system for the Spotify Pedalboard Python library.

Project Overview

Pedalboard-pluginary is a production-ready scanner for audio plugins (VST3, AU) that provides:

**Current Status**: Successfully scanning 289 plugins with atomic commits and two-phase consistency guarantees.

Core Architecture

Key Components

Development Workflow

Pre-Work Preparation (MANDATORY)

1. **ALWAYS read `WORK.md` first** to understand current progress

2. **Read `README.md`** for project context

3. **STEP BACK and THINK STEP BY STEP** about the task

4. **Consider alternatives** before choosing an approach

5. **Check existing solutions** in the codebase

Project Documentation to Maintain

| File | Purpose |

|------|---------|

| `README.md` | Project purpose and functionality |

| `CHANGELOG.md` | Past change release notes (accumulative) |

| `PLAN.md` | Detailed future goals with specifics |

| `TODO.md` | Flat simplified `- [ ]` checklist from PLAN.md |

| `WORK.md` | Current work progress updates |

Core Development Principles

Incremental Development

Code Quality Standards

**Readability First:**

**Robustness:**

**Modularity:**

File Path Tracking (MANDATORY)

**Every source file must maintain a `this_file` record** showing the path relative to project root:

**Python files:**

```python

#!/usr/bin/env -S uv run -s

this_file: src/scanner_isolated.py

```

**Markdown files:**

```yaml

---

this_file: docs/architecture.md

---

```

Python Development Guidelines

Standards

Modern Python Practices

CLI Script Template

```python

#!/usr/bin/env -S uv run -s

/// script

dependencies = ["fire", "rich", "loguru"]

///

this_file: scripts/example_cli.py

"""

Brief description of what this script does.

"""

import fire

from rich.console import Console

from loguru import logger

def main(verbose: bool = False):

"""Main entry point with verbose logging."""

if verbose:

logger.enable("__name__")

# Implementation here

if __name__ == "__main__":

fire.Fire(main)

```

Post-Edit Python Commands

After editing Python files, run:

```bash

fd -e py -x uvx autoflake -i {}; \

fd -e py -x uvx pyupgrade --py312-plus {}; \

fd -e py -x uvx ruff check --output-format=github --fix --unsafe-fixes {}; \

fd -e py -x uvx ruff format --respect-gitignore --target-version py312 {}; \

python -m pytest;

```

Available Tools

Codebase Analysis

```bash

Verify file locations

tree

Generate condensed codebase snapshot

DIR="."; \

uvx codetoprompt --compress --output "$DIR/llms.txt" \

--respect-gitignore --cxml \

--exclude "*.svg,.specstory,*.md,*.txt,ref,testdata,*.lock,*.svg" "$DIR"

Scan dependency source code

Check .venv folder for package implementations

```

New Python Project Setup

```bash

curl -LsSf https://astral.sh/uv/install.sh | sh

uv venv --python 3.12

uv init

uv add fire rich loguru

uv sync

```

Post-Work Activities

Critical Reflection

After completing work:

1. Say **"Wait, but..."** and do additional critical reasoning

2. **Go back, think, reflect** on what you've done

3. **Revise and improve** the implementation

4. **Don't invent functionality** freely - stick to requirements

5. Focus on **"minimal viable next version"**

Documentation Updates

1. Update **`WORK.md`** with progress and next steps

2. Document changes in **`CHANGELOG.md`**

3. Update **`TODO.md`** and **`PLAN.md`** accordingly

Virtual Team Methodology

Lead two expert personas through collaborative problem-solving:

**"Ideot"** - Creative, unorthodox ideas and approaches

**"Critin"** - Critical analysis, moderation, balanced thinking

**Process:**

1. Present problem to both personas

2. Let them collaborate step-by-step

3. Share thoughts and adapt approaches

4. If errors found, step back and refocus on accuracy

5. Be creative, diligent, critical, relentless, and funny

Special Commands

`/plan [requirement]` - Transform Requirements into Plans

When given a requirement, you must:

**1. DECONSTRUCT:**

**2. DIAGNOSE:**

**3. RESEARCH:**

**4. DEVELOP:**

**5. DELIVER to `PLAN.md`:**

Write comprehensive plan with:

**Simultaneously create/update `TODO.md`** with flat `- [ ]` checklist.

**Optimization Techniques:**

`/report` - Update Documentation

1. Read `./TODO.md` and `./PLAN.md`

2. Analyze recent changes

3. Document changes in `./CHANGELOG.md`

4. Remove completed items from `./TODO.md` and `./PLAN.md`

5. Ensure `./PLAN.md` contains detailed plans with specifics

6. Ensure `./TODO.md` is flat simplified representation

`/work` - Continuous Work Mode

1. Read `./TODO.md` and `./PLAN.md` and reflect

2. Write immediate iteration items into `./WORK.md`

3. Work on these items

4. Think, contemplate, research, reflect, refine, revise

5. Be careful, curious, vigilant, energetic

6. Verify changes and think aloud

7. Consult, research, reflect

8. Periodically remove completed items from `./WORK.md`

9. Tick off completed items from `./TODO.md` and `./PLAN.md`

10. Update `./WORK.md` with improvement tasks

11. Execute `/report`

12. Continue to next item

**Continuous Work Mode Rules:**

Key Reminders

Command Summary

| Command | Purpose |

|---------|---------|

| `/plan [requirement]` | Transform requirements into detailed `PLAN.md` and `TODO.md` |

| `/report` | Update documentation and clean up completed tasks |

| `/work` | Enter continuous work mode to implement plans |

Use these commands autonomously when appropriate to maintain project momentum and documentation quality.