immortaly007/guitar-practice-tool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add agent integration guide; fix L4 deep-link param in README

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
Bas Dado
2026-07-23 11:53:36 +02:00
parent 0ba48dfbf3
commit 71531eabcd
2 changed files with 144 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENT_GUIDE.md
+142
View File
@@ -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/<CODE>[?param=value&param=value]
```
- `<CODE>` 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.