From 71531eabcd2972d76dc74c5110b3f093056bbc13 Mon Sep 17 00:00:00 2001 From: Bas Date: Thu, 23 Jul 2026 11:53:36 +0200 Subject: [PATCH] docs: add agent integration guide; fix L4 deep-link param in README Add AGENT_GUIDE.md describing how a practice-managing agent drives the deployed tool (guitar.basdado.com) via deep links, with the full drill/param catalog. Correct the README param table: L4 uses ?note, not ?root. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENT_GUIDE.md | 142 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 3 +- 2 files changed, 144 insertions(+), 1 deletion(-) create mode 100644 AGENT_GUIDE.md diff --git a/AGENT_GUIDE.md b/AGENT_GUIDE.md new file mode 100644 index 0000000..66da6fa --- /dev/null +++ b/AGENT_GUIDE.md @@ -0,0 +1,142 @@ +# Guitar Practice Helper — guide for a practice-managing agent + +You (an AI agent) help me run my guitar practice: reminders, a practice diary, +tempo tracking, session planning. This document tells you how to use my companion +web tool so you can hand me ready-to-use links and keep useful records. + +The tool is a static web app deployed at **https://guitar.basdado.com**. It turns +each drill code from my routine (R1, F2, T3, …) into an interactive helper page — +a metronome/click track, a strum or picking pattern, chord/fretboard diagrams, or +a drone. + +## How to use it (the short version) + +- **Give me deep links.** In reminders and session plans, link directly to the + exact drill, tempo, and variant I should do — e.g. + `https://guitar.basdado.com/drill/R1?bpm=72&variant=quarters`. +- **Pin every setting in the URL.** Query params override whatever is stored on the + device, so a fully-specified link always starts me in the right place regardless + of what I did last time. +- **You own the memory, not the tool.** There is no API and no server state you can + read. The app stores per-drill settings and R4 best scores only in the browser's + `localStorage`, per device. Track my progress (current clean tempo per drill, + streaks, notes) in your own diary, and encode it into the links you send me. + +## Link format + +``` +https://guitar.basdado.com/drill/[?param=value¶m=value] +``` + +- `` is a drill code (see catalog). Case-insensitive. +- The index of all drills is at `https://guitar.basdado.com/`. +- An unknown code shows a friendly "unknown drill" page, so nothing breaks. + +## The core practice principle to reinforce + +The routine is built on **additive, edge-of-ability practice**: only raise the tempo +once a drill is played cleanly. The app has a "clean? +2" button for exactly this. + +Your job around that: remember my current **clean tempo** for each click-track drill +in your diary. Each session, send the link at that tempo (`?bpm=`). When I report a +drill felt clean, bump my recorded tempo by ~2 BPM for next time. If I struggled, +hold or drop it. This is the main feedback loop between you and the tool. + +## Drill catalog + +Click-track drills accept `?bpm=` (integer, 30–300) and, where noted, `?variant=`. +"Default BPM" is the app's starting tempo if you don't pin one. + +| Code | Name | Category | Metronome | Default BPM | Other params | +| ---- | ---------------------------------- | ----------- | -------------- | ----------- | ------------------ | +| R1 | 16th-note strum, mute off-beats | Rhythm | yes | 70 | `variant` | +| R2 | Accent patterns | Rhythm | yes | 80 | `variant` | +| R3 | 7/8 loop (can drop to 4/4) | Rhythm | yes | 65 | `variant` | +| R4 | One-minute chord changes | Rhythm | no (60s timer) | — | `pair` | +| R5 | Palm-mute chugging | Rhythm | yes | 90 | `variant` | +| F1 | Travis picking | Fingerstyle | yes | 60 | `variant` | +| F2 | PIMA arpeggio over I–V–vi–IV | Fingerstyle | yes | 65 | `variant` | +| F3 | Thumb-independent bass + melody | Fingerstyle | yes | 55 | `variant` | +| T1 | Name every note on one string | Theory | yes | 60 | — | +| T2 | CAGED shapes | Theory | no | — | `key` | +| T3 | Triads on a 3-string set | Theory | optional | 60 | `root` | +| T4 | Diatonic chords of a key | Theory | no | — | `key` | +| T5 | Intervals from a root | Theory | no | — | `root`, `interval` | +| T6 | Mode over a drone | Theory | no (drone) | — | `root`, `mode` | +| L1 | Alternate picking builder | Lead | yes | 120 | `variant` | +| L2 | Legato runs (triplets) | Lead | yes | 100 | `variant` | +| L3 | String skipping | Lead | yes | 90 | `variant` | +| L4 | Bends and vibrato (reference tone) | Lead | no | — | `note` | +| E1 | Interval recognition | Ear | no | — | — | +| E2 | Chord quality recognition | Ear | no | — | — | +| E3 | Play along by ear (with drone) | Ear | no (drone) | — | — | + +## Parameter values + +| Param | Applies to | Valid values | +| ---------- | -------------------------------------- | ---------------------------------------------------------------------- | +| `bpm` | all metronome drills + T1 | integer 30–300 | +| `variant` | R1, R2, R3, R5, F1, F2, F3, L1, L2, L3 | see per-drill list below | +| `key` | T2, T4 | note letter, e.g. `C` `G` `D` `A` `E` `F` (T4: `G` `D` `C` `A`) | +| `root` | T3, T5, T6 | chromatic root: `C C# D D# E F F# G G# A A# B` | +| `interval` | T5 | `m3` `M3` `P4` `P5` `M6` `m7` `M7` | +| `mode` | T6 | `ionian` `dorian` `phrygian` `lydian` `mixolydian` `aeolian` `locrian` | +| `note` | L4 | chromatic note: `C C# D D# E F F# G G# A A# B` | +| `pair` | R4 | `g-c` `c-d` `g-d` `a-d` `em-c` `am-f` `f-bm` `d-a` | + +### Variant IDs + +- **R1**: `quarters`, `1e-and-a-1-3`, `all-16ths` +- **R2**: `accents-1-3`, `accents-2-4`, `every-3rd` +- **R3**: `2-2-3`, `3-2-2`, `2-3-2`, `drop-4-4` +- **R5**: `chug`, `gallop` +- **F1**: `classic` +- **F2**: `ascending`, `descending` +- **F3**: `preset-1` +- **L1**: `single-string`, `two-string` +- **L2**: `ham-pull` +- **L3**: `skip-1` + +## Example links + +``` +# Rhythm at a pinned tempo + variant +https://guitar.basdado.com/drill/R1?bpm=72&variant=quarters +https://guitar.basdado.com/drill/R3?bpm=66&variant=2-3-2 + +# Chord changes on a specific pair (R4 tracks a best score locally) +https://guitar.basdado.com/drill/R4?pair=f-bm + +# Theory +https://guitar.basdado.com/drill/T4?key=D +https://guitar.basdado.com/drill/T5?root=A&interval=P5 +https://guitar.basdado.com/drill/T6?root=A&mode=dorian + +# Lead reference pitch for bend practice +https://guitar.basdado.com/drill/L4?note=C +``` + +## Using this in my practice management + +- **Session plans / reminders.** Assemble a short interleaved set (mix categories — + don't stack three lead drills) and give me each as a link at its current tempo. + Example daily nudge: "10 min — [R1 @72](…/drill/R1?bpm=72&variant=quarters), + [F2 @66](…/drill/F2?bpm=66&variant=ascending), [T5 A/P5](…/drill/T5?root=A&interval=P5)." +- **Tempo ladder.** Keep a per-drill clean BPM in your diary. Serve at that tempo; + on a clean report, +2 for next time; on a struggle, hold or −2. +- **R4 scores.** The app stores a best score per chord pair on the device. Ask me + the number after a run and log it yourself so you can chart progress across pairs. +- **Interleaving + active recall.** Prefer rotating drills and cold retrieval + (especially T1/T5) over repeating one thing; vary the `variant`/`root`/`key` you + send so I'm tested rather than looping. +- **Diary hooks.** Good things to record per session: which drills, tempos, whether + clean, R4 scores, and anything I say felt hard — then adjust the next plan. + +## Constraints + +- Static site: no login, no API, no push. You cannot read or write app state; drive + everything through links and your own records. +- Settings persist per browser/device via `localStorage`, so state does not follow + me across devices — always pin settings in the URL to be safe. +- Audio needs a tap/click to start (mobile autoplay policy); the metronome keeps the + screen awake while playing. diff --git a/README.md b/README.md index c538b4c..56325ba 100644 --- a/README.md +++ b/README.md @@ -105,9 +105,10 @@ Optional query parameters override the stored/default settings: | `bpm` | click-track drills | `?bpm=66` | | `variant` | drills with variants | `?variant=2-3-2` | | `key` | T2, T4 | `?key=D` | -| `root` | T3, T5, T6, L4 | `?root=A` | +| `root` | T3, T5, T6 | `?root=A` | | `interval` | T5 | `?interval=P5` | | `mode` | T6 | `?mode=dorian` | +| `note` | L4 | `?note=C` | | `pair` | R4 | `?pair=g-c` | Examples: