Expert guidance for developing and extending the SIDFlow C64 SID music streaming platform
Expert AI agent for developing the SIDFlow platform - a CLI-first pipeline that streams C64 SID music with ML-powered recommendations based on your listening feedback and mood preferences.
SIDFlow is a TypeScript monorepo that fetches SID music collections, classifies audio characteristics, trains ML models on user feedback, and provides intelligent playback with mood-based stations. This skill guides you through the architecture, conventions, and workflows for extending and maintaining the platform.
SIDFlow operates as a multi-stage pipeline with four primary packages:
1. **@sidflow/fetch** - Downloads SID collections (currently HVSC, extensible to any local collection)
2. **@sidflow/classify** - Renders WAV cache, extracts heuristic features, generates auto-tags, emits JSONL metadata
3. **@sidflow/train** - Consumes classified data + user feedback, trains ML models, persists LanceDB artifacts
4. **@sidflow/play** - Provides playback, recommendations, and mood-based station creation
All stages read/write structured data to `data/` in JSONL format and respect configuration from `.sidflow.json`.
1. **Always start by reading `AGENTS.md`** at repo root for:
- Repository-wide agent behavior patterns
- ExecPlan usage for multi-step work
- Multi-hour workflow expectations
- Autonomous agent guidelines
2. **Follow `PLANS.md`** for any multi-step work:
- Load and update the central execution plan
- Treat it as single source of truth
- Log progress, surprises, decisions, and outcomes
- Maintain continuity across long sessions
3. **Honor `.cursorrules`** if user is on Cursor (mirrors these guardrails)
1. **Minimal, additive edits only**: Keep public APIs stable unless task requires changes
2. **Preserve conventions**: Follow repository coding patterns and shared utilities
3. **Read before modifying**: Never propose changes to code you haven't read
4. **Validate quickly**: Run fast checks (build, test) after substantive edits
All shared utilities live here - always import rather than reimplementing:
- `sidPath` - Local SID collection path (works with any collection, not just HVSC)
- `audioCachePath` - WAV cache storage
- `tagsPath` - Auto-generated tags location
- `classifiedPath` - (optional) Classification output
- Consumers must tolerate missing folders
- Skip corrupt lines with warnings, not hard failures
Follow this structure for all CLI tools:
1. **Parse args** in `cli.ts`
2. **Call `plan*` function** to validate inputs
3. **Run pure helpers** that accept explicit dependencies (see `runClassifyCli`, `runFetchCli`)
4. **Provide progress reporting** via callbacks with throttling
5. **Keep CLI UX stable** - scripts in `scripts/` are thin wrappers defining the end-to-end contract
```bash
bun run build
bun run test
bun run test:e2e
bun run validate:config
bun run setup:tests
```
- Install deps: `bun install`
- Build: `bun run build`
- Tests/CLIs: `bun run ...`
1. Extend `heuristicFeatureExtractor` in `@sidflow/classify`
2. Update JSONL schema if needed
3. Preserve WAV cache + hash scheme
4. Add tests for feature extraction
5. Validate with `bun run test && bun run build`
1. Edit weight constants in `@sidflow/train`
2. Update feedback merge logic
3. Regenerate model artifacts with new weights
4. Document weight rationale in Decision Log
1. Extend `@sidflow/fetch` with new source
2. Keep classification/training/playback source-agnostic
3. Ensure `.sidflow.json` `sidPath` supports new layout
4. Test end-to-end pipeline with new collection
1. Add to appropriate module in `@sidflow/common`
2. Keep pure and explicitly typed
3. Add unit tests
4. Update this documentation if cross-cutting pattern emerges
You should work autonomously, but ask when:
Otherwise, make reasonable assumptions, document them in the Decision Log, and proceed.
A task is complete when:
1. All requested functionality is implemented
2. Code follows repository conventions
3. Build passes: `bun run build`
4. Tests pass: `bun run test` (+ `test:e2e` if UI changed)
5. Config validation passes: `bun run validate:config`
6. Progress/Decisions/Outcomes logged in `PLANS.md`
7. No regressions introduced in existing functionality
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/sidflow-development-assistant/raw