| name | GA Domain Context |
| description | Primes every session with the guitarist's perspective, GA architecture, and how to use the MCP tools during feature development. Load this before working on any Guitar Alchemist feature. |
| triggers | ["guitarist problem","guitar alchemist feature","GA backlog","music theory feature","chord substitution","improvisation feature"] |
GA Domain Context
Guitar Alchemist is a music platform for guitarists, not a generic dev project. Every feature decision should start with a real guitarist's pain, verified with the GA MCP tools, then implemented in the GA domain model.
Who We're Building For
A guitarist who:
- Knows songs but not always why they work harmonically
- Learns by ear first, theory second
- Hits a wall: "why does this sound wrong?" / "what can I play here?"
- Wants answers in guitarist vocabulary: chord names, fret positions, tab — not abstract intervals
North Star question for every feature: What does a guitarist do with this?
GA MCP Tools — Use During Development, Not Just Runtime
The ga-dsl MCP server (registered as mcp__ga-dsl__*) gives you live music theory during brainstorming and planning. Call these tools when designing features to verify your theory is correct before writing code.
Verification workflow for a guitarist problem
- Identify the musical concept — what chord, scale, or key is involved?
- Verify with MCP tools — call
GaAnalyzeProgression, GaChordIntervals, GaCommonTones to ground the feature in real theory
- Design the output — what does the guitarist see? (tab, chord symbol, fretboard, explanation)
- Implement in the right layer — see architecture below
Key tools and when to use them
| Tool | When to call it |
|---|
GaAnalyzeProgression("Am F C G") | Whenever a feature involves key detection or Roman numeral labelling |
GaDiatonicChords("G", "major") | When suggesting chords that "fit" a key |
GaChordIntervals("Cmaj7") | When explaining why a chord sounds the way it does |
GaCommonTones("G7", "Cmaj7") | When implementing voice-leading or pivot-chord features |
GaTransposeChord("Am7", 7) | When implementing transposition or capo features |
GaRelativeKey("A", "minor") | When implementing relative key or parallel key features |
GaSearchTabs("metallica nothing else matters") | When a feature needs real-world tab examples |
GaInvokeClosure("domain.queryChords", '{"key":"G","scale":"major","quality":"minor"}') | For advanced diatonic filtering |
Architecture Quick Reference
Five-layer rule (strict — no exceptions)
Layer 1 — GA.Core / GA.Domain.Core Pure primitives: Note, Interval, PitchClass, Fretboard
Layer 2 — GA.Business.Core Business logic, chord analysis, scale queries
Layer 3 — GA.Business.Core.Harmony Voice leading, chord progression analysis
Layer 4 — GA.Business.ML Embeddings (OPTIC-K), semantic search, agents
Layer 5 — GA.Business.Core.Orchestration High-level workflows, IntelligentBSPGenerator
Rule: new code goes in the lowest layer that has everything it needs. AI code → Layer 4. Workflows → Layer 5. Pure music math → Layer 1 or 2.
Where guitarist features typically land
| Problem type | Layer | Example |
|---|
| "What intervals are in this chord?" | 1–2 | Chord.Intervals, ChordDslService |
| "Which chords fit this key?" | 2–3 | DiatonicChordService |
| "Suggest a substitution" | 3 | HarmonicTransformationService |
| "Find similar-sounding songs" | 4 | OPTIC-K embedding + vector search |
| "Generate a practice routine" | 5 | Orchestration + agent composition |
F# DSL — the closure registry
The GA Language closures (domain.*, tab.*, agent.*) live in GA.Business.DSL. They are:
- Registered at module load via
do register()
- Accessible in-process via
GaClosureRegistry.Global
- Exposed to Claude Code via the
ga-dsl MCP server
When adding a new music-theory closure, add it to DomainClosures.fs and register it in register().
OPTIC-K embeddings (216 dimensions)
Used for semantic similarity between chord voicings/BSP rooms. Never change dimension count without a full re-index. Structure:
- dims 6–29: STRUCTURE (pitch-class invariants) — weight 0.45
- dims 30–53: MORPHOLOGY (fretboard geometry) — weight 0.25
- dims 54–65: CONTEXT (harmonic function) — weight 0.20
- dims 66–77: SYMBOLIC (manual tags) — weight 0.10
The Compound Engineering Loop for GA
Guitarist problem (BACKLOG.md)
↓
Brainstorm: call GA MCP tools to verify the music theory
↓ GaAnalyzeProgression, GaChordIntervals, GaCommonTones…
Plan: docs/plans/ — what does the guitarist see + how does it map to layers?
↓
Implement: lowest layer first, ROP error handling, unit tests
↓
Document: update BACKLOG.md (remove idea), link plan to PR
↓
Compound: solution is now a closure / endpoint / UI feature
that makes the NEXT problem easier to solve
Each solved problem expands the closure registry, which makes future features faster: GaCommonTones built for voice-leading also powers pivot-chord detection and substitution suggestions.
Guitarist Vocabulary → GA Concepts
| What a guitarist says | GA concept | Tool / layer |
|---|
| "What key am I in?" | Key inference from chord set | GaAnalyzeProgression |
| "What scale fits here?" | Diatonic scale from key | GaDiatonicChords |
| "Why does this note sound outside?" | Chromatic pitch class vs. diatonic set | GaChordIntervals + set math |
| "What can I play instead?" | Chord substitution | GaCommonTones + GaRelativeKey |
| "How do I finger this?" | Fretboard geometry | GA.Business.Core.Fretboard layer |
| "Show me a lick" | Tab generation | tab.generateChord, VexTabGenerator |
| "Find me a tab" | Internet tab search | GaSearchTabs (Archive.org + GitHub) |
| "This sounds jazzy/bluesy" | Stylistic tag | OPTIC-K SYMBOLIC dims |
Before Implementing Any Feature
- Call at least one MCP tool to verify the music theory is correct
- Ask: what does a guitarist do with this output? (tab, chord name, fretboard, text)
- Place in the right layer — never put orchestration in Layer 1-2
- ROP all the way — service methods return
Result<T, TError>, never throw
- Write a test that uses a real chord symbol or progression, not mocked values
