Summary of Approach

Why this exists

This was never "build a DJ app." It was a deliberate experiment in building software the disciplined way, while chasing a few personal threads at once:

• Learn vibe coding, but with rigor. Prove fast AI-assisted building can still leave behind a clean, documented, resumable codebase — not a pile of one-off prompts. Every feature ships with its why written down.
• Practice real planning. Roadmaps with slices, key decisions recorded with their reasoning, pull conditions for parked ideas, gap audits that ask "did we build it right?" before adding more.
• Rediscover lost passions. DJ culture, Carnatic percussion, synthesis, birding, nature photography — underground threads made load-bearing instead of hobby footnotes.
• Build one coherent world, not scattered demos. A single brand system with a taxonomy, a design constitution, and a house voice, so everything feels like the same person made it.

AVIARY — one enclosure, many birds

AVIARY is the parent brand. Every tool is a species; every name maps a bird behavior to a tool function — one taxonomy, no names-from-nowhere.

• The design constitution — "The Field Guide": nine principles derived from a life (Goddard and the garden, the hawk on the lotus pond, the runway that became habitat), not from a trends article. Computers and the forest · Serendipity by design · Restore, don't extract · Steward beyond your term · Every theme is a world · Identity does work · Pressure-tested elegance · Joy is load-bearing · Underground by choice.
• The brand spec — seven themes (each a world, not a color swap); seven working marks where the logo literally is the play button / scratch platter / reset control; two type voices; a dry, "field guide not brochure" voice.
• North star — "The system thinks, you decide." Every smart feature suggests; none ever takes the wheel.

Principles first, then everything cascades

It started before any code, with a set of universal design principles — written as a design constitution derived from a life rather than a trends article. Those principles came first, then cascaded down into everything: the brand system, the themes, the marks, the naming taxonomy, the house voice, and the working practice itself. Every tool in the repo is an instantiation of that one document — which is exactly why six separate instruments still feel like the same person built them.

The working practice that travels to every tool:

• Archive before overwrite — 120+ numbered snapshots; nothing archived is ever edited.
• Three standing documents — architecture (what exists), roadmap (what's planned + why decisions went the way they did), changelog (what changed, every version).
• Docs move with the code — a feature isn't done until the architecture doc says it exists.
• Decisions get a why — the next session, human or AI, inherits the reasoning, not just the result.
• Self-tests — each instrument ships a ?selftest=1 suite (CHIRP grew to 41 checks) proving the engine's mechanics before every commit.

What actually shipped

CHIRP — the flagship two-deck DJ instrument

A single self-contained index.html. No build step, no dependencies beyond Google Fonts. Phase 1.0 → 2.0: single-track modulator → full two-deck DJ kit — per-deck effect chains, equal-power crossfader, real playhead, transport + cue, waveform module with BPM detection and loop windows, beat-matching, true-reverse scratch platters (AudioWorklet), WAV recording, shareable presets.

Phase 3 — the "smart" arc, shipped as three planned slices (each closed the same day it was planned — the planning was the work): hosting + LURE demo set → the shared musical Clock → PERCH (beat-grid / downbeat analysis, "dim, don't guess") → key detection + DUET matchmaking → MONAL (the library as a living compatibility map) → session save → PERCH phase 2 + bar-SYNC → MUTATE (roll-the-dice suggestions) → the ease pass → FLYWAY + recipe export.

The instruments — "CHIRP learns to sing"

Sibling single-file tools, each an engine wearing a playable face, with a loop-perfect bounce back into CHIRP's Beats — closing the studio → booth → export flywheel.

• TRILL — the arpeggiator (engine: SYRINX; a wrong note is unrepresentable). v5 opened a full sound-design cabinet.
• FLAMEBACK — the Carnatic mridangam (engine: MEMBRANE, modal synthesis), two playable heads and a tala grid.
• BITTERN — the rave-bass playground (engine: GULAR), five legendary calls as starting points with every knob exposed.
• CLUTCH — the step sequencer / drum machine (engine: GIZZARD — an 808 and a 909 rebuilt as circuits, no samples anywhere). Every step is an egg; golden eggs lean. Swing, two chained nests, pocket-SYRINX melody perches on scale rails, Flameback's fill lattices, 16/32/64-step windows, and a seam-folded bounce into CHIRP's Beats. Gated until the "place the notes" itch arrived — then shipped in five releases, one day.

MOLT — the photo instrument and audiovisual world

MOLT began as CHIRP's registry-of-effects idea aimed at pixels — a photo deep-frier / darkroom. But it grew into an audiovisual world engine. Point it at any track and MOLT's 21 ambient worlds paint themselves to the music: the fireflies learn its beat, the kelp sways to its bass, the herd moves one animal per band. "Not a visualizer — a landscape that listens."

NIGHTJAR — the secret

A hidden space-quest game, opened by long-pressing the hero mark and linked from nowhere by design. Its beat is a high-school rap — a lost passion literally re-shipped.

Nine days, day by day

The receipts

Parked, not forgotten

Each unparks on a pull condition, never speculatively: MIDI notes into the instruments (a controller's keys playing TRILL / BITTERN / CLUTCH live — v73's CC plumbing was the first rung) · MIDI file import/export (load an arrangement in, bounce a pattern out) · the piano roll + playlist question — whether the Aviary grows into a DAW, or stays a flock of instruments that feed a booth · PREEN's library intake · the PWA rung and iPad pass · BOWER (the first non-audio species — a nature-photo portfolio). Phone is ruled out permanently — underground by choice doesn't chase form factors.

The whole thing is one person's answer to a simple question: can you build fast with AI and still build like a steward? The docs, the archive, the self-tests, and the fact that a cold session can pick any of this up tomorrow — that's the answer, written down.