Workslop (Workshop Player for ADHD Learners)

Overview

Workslop is a native macOS application that runs structured learning workshops from a declarative XML file format. Users prompt any LLM to generate a .workslop file using the shipped format spec, drop it in ~/workslop, and the app guides them through sections with visual timers, checklists, and inline content. The app doesn't generate content — it just plays it with an ADHD-friendly experience wrapper.

Core insight: Learning apps for ADHD typically fail in two ways — sterile and anxiety-inducing, or heavily gamified with streaks and badges that create shame cycles when missed. Workslop rejects both. External time visualization (ring/bar timers, not numeric countdowns) works pre-consciously. Section structure stays visible. You can jump anywhere without losing the thread.

Target users: Neurodivergent learners who want structured guidance through any topic, using content they generate themselves via LLMs they already trust.

What It Does

• Workshop format — XML with sections, time budgets, tasks (required/optional), content references to external markdown/images, and optional conditional skip rules
• Visual countdown timers — Ring and bar timers per section, plus an independent Pomodoro overlay. Time is seen, not calculated.
• Guided flow + map view — Step-by-step section navigation alongside a whole-workshop overview showing progress
• Checklist tracking — Per-section tasks with completion state, resume from where you left off
• Inline content rendering — Markdown and images referenced by path, rendered in the guided view
• Folder-based library — ~/workslop is the canonical folder. Drop files in, they appear. No import flow, no database.
• Self-reflection capture — Difficulty ratings and notes per section after completion

How It Fits Together

SwiftUI throughout, targeting macOS 14+ with iOS portability via a shared WorkslopCore Swift Package. XMLCoder for declarative XML parsing, Textual for markdown rendering, DispatchSource for folder watching. No external dependencies beyond those three libraries.

Single-window design — one workshop at a time. Opening a new file replaces the current one. This is deliberate: ADHD-friendly focus, not multitasking.

Key Design Decisions

• XML format, not JSON/YAML — Richer structure for optional branching, and LLMs handle XML generation well (they can infer structure from element names)
• External content references, not embedded — Keeps .workslop files small, content is editable independently, images stay as filesystem resources
• No streaks, badges, or extrinsic gamification — This isn't cosmetic. ADHD users experience shame spirals around missed streaks. Progress is its own reward.
• The format spec is the product — Once documented, any LLM generates workshops. The app is a player, not a walled garden.
• Rust CLI deferred — XMLCoder already solves parsing elegantly. Adding FFI for a non-problem would be premature complexity.
• Moog-inspired visual direction — Warm saturated colors, bold typography, rounded shapes. Not hardware skeuomorphism — the aesthetic calm of Moog's visual language applied to a learning interface.

Open Questions

• Phase 1 hasn't started building yet. Research and architecture are complete, but no source code exists. The macOS pitfalls surfaced in research (sandbox bookmarks, broken ScenePhase, FileDocument vs ReferenceFileDocument) will be the first test of whether the architecture holds.
• Format adoption is the real risk. The app is only useful if people generate workshops. Whether the format spec is clear enough for reliable LLM generation across different models is untested.
• Single-platform for now. iOS is architecturally planned (shared Swift Package) but not started.

Ecosystem Role

Workslop shares the neurodivergent-first design philosophy with Haven (garden sessions for a 7-year-old), OpenClaw (executive function prosthetics), and Evolver (ADHD-adapted synthesizer learning). It's the most general-purpose of the group — any structured learning topic, not a specific domain.