| name | ga-compose |
| description | Compose a chord progression with smooth voice leading — chains ga_generate_progression → ga_voice_leading_pair → ga_search_voicings. Use when the user asks for a progression in a key / style with playable voicings (e.g. "compose ii-V-I in Bb with smooth voicings"). |
GA Compose Skill
End-to-end composition pipeline: template → chord symbols → smooth-voiced arrangement. Wraps three MCP tools into one workflow so the user gets a playable progression in one turn instead of managing the chain manually.
When to use
Trigger this skill when the user asks for a composed progression with voicings — phrases like:
- "compose a ii-V-I in Bb"
- "give me 12-bar blues in E with smooth voice leading"
- "rhythm changes in F, playable on guitar"
- "andalusian in A minor"
- "canon progression in D"
Do not invoke for:
- Single-chord voicing lookups → use
mcp__ga__ga_search_voicings directly.
- Reharmonization of an existing progression → that's a separate workflow (
/ga-reharm if built later).
- Fuzzy mood/style queries with no structural template → use
mcp__ga__ga_search_voicings with allowSampling: true.
Arguments
Parse the user's request into:
| Argument | Required | Example | Notes |
|---|
root | yes | C, Bb, F# | Canonical roots per mcp__ga__ga_voicing_vocabulary |
template | yes | ii-V-I, 12-bar-blues | See template list below |
length | no | 8 | Override natural template length (truncates or loops) |
instrument | no | guitar, bass, ukulele | Default: guitar |
Templates (from ga_generate_progression):
| Template | Domain | Length |
|---|
ii-V-I | jazz | 3 |
circle-of-fifths | jazz | 4 |
rhythm-changes-a | jazz | 8 |
I-V-vi-IV | pop axis | 4 |
I-vi-IV-V | doo-wop | 4 |
canon | Pachelbel | 8 |
12-bar-blues | blues | 12 |
minor-vamp | minor | 3 |
andalusian | flamenco | 4 |
If the user's phrase maps to a style not listed (e.g. "bossa nova"), pick the closest template (ii-V-I for most jazz styles, canon for folk, 12-bar-blues for blues) and mention the substitution in your reply.
Workflow
Step 1 — Generate the progression
mcp__ga__ga_generate_progression(root, template, length?)
Returns an array of {roman, symbol, degree, quality, pitchClasses}. If the template name is unknown, the tool returns an error with availableTemplates — show those to the user and ask them to pick.
Step 2 — Find smooth-voiced transitions
For each consecutive chord pair (chords[i], chords[i+1]), call:
mcp__ga__ga_voice_leading_pair(
fromChord: chords[i].symbol,
toChord: chords[i+1].symbol,
limit: 3,
instrument: <user-specified or "guitar">,
candidatesPerChord: 15
)
Fire these pair calls in parallel — they're independent. For an N-chord progression you'll have N-1 pair calls.
Step 3 — Stitch the voicing chain
Build a single voicing sequence:
- Start with the
from voicing of pair[0] (best candidate by voice-leading distance).
- For each subsequent pair i, the
to voicing of pair[i] becomes the from of the next chord. But pair[i+1].from is an independent retrieval, not constrained to match pair[i].to.
This means the naive chain — [pair[0].from, pair[0].to, pair[1].to, pair[2].to, ...] — has a gap: pair[0].to and pair[1].from are not guaranteed to be the same voicing. In practice they often are (same chord → same top candidates) but not always.
Resolution: for a strictly continuous chain, walk the pair results and pick the best pair[i].to that equals (same MIDI notes as) pair[i+1].from. If no match exists, accept the gap and flag it in the output.
For most use cases (pedagogical / quick composition), the simpler "concatenate top pairs" produces a readable arrangement even with small gaps. Start with that and only escalate to strict-chain matching if the user asks for it.
Step 4 — Format the reply
Present the composed arrangement as:
**<template> in <root>** — <length> chords on <instrument>
| # | Roman | Chord | Diagram | MIDI notes | Voice-leading → next |
|---|---|---|---|---|---|
| 1 | ii7 | Dm7 | x-5-3-5-3-x | [62, 57, 53, 45] | 7 semitones |
| 2 | V7 | G7 | x-x-x-5-8-7 | [55, 53, 47] | 5 semitones |
| 3 | Imaj7 | Cmaj7 | 8-8-9-9-x-8 | [72, 67, 64, 59, 48] | — (final) |
Total voice motion: 12 semitones across 2 transitions.
Include:
- The template + key + length in a header
- A table with chord, diagram, MIDI notes, transition cost
- Total voice motion as a summary metric
Step 5 — Offer follow-ups
Short menu the user can redirect to:
- "Want me to try a different template?"
- "Reharmonize with tritone substitutions?" (requires
ga_chord_substitutions)
- "Realize on bass/ukulele instead?"
- "Generate an alternate voicing-leading path through the same chords?"
Examples
Example 1 — jazz ii-V-I
User: /ga-compose ii-V-I in Bb
- Call
ga_generate_progression(root: "Bb", template: "ii-V-I") → Cm7 / F7 / Bbmaj7
- Fire
ga_voice_leading_pair(Cm7, F7) + ga_voice_leading_pair(F7, Bbmaj7) in parallel
- Format as a 3-chord arrangement with transition costs
Example 2 — rhythm changes
User: /ga-compose rhythm changes in F
- Template:
rhythm-changes-a (first 8 bars of rhythm-changes)
- 8 chords, 7 parallel pair calls
- Format as 8-row table
Example 3 — mismatch fallback
User: /ga-compose bossa nova in D
bossa nova not a template. Pick ii-V-I and mention: "Using ii-V-I — bossa-nova-specific templates aren't in the library yet. Flag this if you want a bossa template added."
Failure modes
Tool returns "error": "unknown template" — show the availableTemplates list and ask the user to pick.
Tool returns "error": "unknown root" — likely a typo. Suggest the closest canonical root (e.g. "Did you mean Bb?").
ga_voice_leading_pair returns fewer pairs than expected — candidate retrieval was thin. Re-run with candidatesPerChord: 30 for that single transition. Flag which transition needed the boost in your reply.
The strategy / MCP server is cold — first call can take ~500 ms. Subsequent calls are ~10 ms. Don't retry on first-call latency.
Why this exists
We shipped three primitives — ga_generate_progression, ga_voice_leading_pair, ga_search_voicings — but composing them by hand is tedious: 1 generate call + N-1 voice-leading calls + stitching + formatting = 10+ tool calls for a simple ii-V-I. This skill reduces it to a single invocation. It's the difference between "bricks" and "a house."
