ga

Post-merge intent-vs-delivery evaluator. Resolves the most recent squash-merged PR, captures its stated intent (title + Summary), diffs it against what actually landed, runs /octo:review for specialist commentary, scans Codex bot comments (P0/P1 degrade the grade), computes a high/medium/low alignment score, and writes a structured grade to state/quality/pr-grades/<merge-sha>.json. Closes the "agent declared done, nobody checked the goal" loop.

Run one bounded supervised autonomous cycle on the Guitar Alchemist repo. Picks the smallest unchecked roadmap slice inside allow_edit, implements it, runs the oracle, emits cycle evidence, and stops. Refuses to run unless dev-process-overseer reports loop-eligible and the preflight passes. Use when asked to "run one supervised loop", "advance the roadmap autonomously", or "do one cycle and stop".

Rebuild the OPTIC-K voicing index (state/voicings/optick.index). Invoke when schema hash bumps, tag enrichment changes, new chord qualities are added, or the leak-test / invariant-coverage tools flag regressions. Mandatory precondition: stop any process that has the index mmap-locked — GaApi and GaMcpServer both hold the file open at runtime, and the write step WILL fail with IOException otherwise.

Generalized Cherny-style autonomous improvement loop. Reads a domain-scoped baseline.json + oracle script, runs the oracle, picks the worst-scoring item, proposes a fix, validates rollback safety, commits if metric improved AND roundtrip passes. Use for chatbot-qa, embeddings, voicing-analysis, or any other domain that has a baseline + oracle. Refuses to run if killswitch present, governance halt active, or scope_boundary violated.

End-to-end autonomous (AFK) harness that develops AND QAs the GA chatbot. Orchestrates the existing Level-3 /auto-optimize dev loop + the semantic /ga-chatbot-qa-panel judge workflow, instruments every step to a dashboard the human can watch, and enforces branch-only / never-merge safety. Use to run unattended chatbot-quality improvement with full human visibility. Refuses to run if the backend is down, a killswitch/halt marker is present, or scope_boundary is violated.

Turns raw Sentrux structural-quality metrics (quality_signal, cycle count, coverage) into a ranked list of actionable refactor recommendations with starter sketches. Pulls live data from sentrux MCP tools, optionally cross-references AI annotations (@ai:business-value, @ai:smell) and the latest /test-plan output, then writes 5-10 prescriptive bullets to state/quality/sentrux-next-steps/<date-Z>.md so the Sentrux dashboard tab can render them. PROPOSES — never auto-refactors; the human picks which recommendation to take.

Lists the seven diatonic triads of a key (root + major/minor). Calls the deterministic `domain.diatonicChords` closure via the `ga_dsl_eval` MCP tool — never recall diatonic sets from training data, since LLMs commonly mis-spell the iv/vii° in less-common keys (Gb major, F# minor).

Backlog grooming. Reads BACKLOG.md (H2 epics → H3 sub-sections), recent open GitHub issues, state/quality/ trend snapshots, state/digests/latest.md, and stale docs/plans/, then proposes a ranked top-3 work items with rationale. Writes the same content to state/backlog-grooming/<date>.md so the proposal survives session compaction. Closes the "agent picks whatever's loudest" failure mode in autonomous mode. PROPOSES — never auto-executes; the human approves.

Diff-driven test-plan proposer for non-trivial PRs. Resolves the PR, categorizes each changed file by language/layer and test surface, weights by risk class (pure-additive / refactor / api-change / one-way-door), and emits a structured proposal of unit + integration + E2E + chatbot test cases keyed to the actual lines that changed. Writes to state/quality/test-plans/<head-sha>.md and posts a sticky PR comment. PROPOSES — never auto-writes test code; the human writes the tests.

Opt-in pre-merge gate that convenes a virtual council of specialist sub-agents for one-way-door PRs (schema changes, public APIs, OPTIC-K dim changes, pricing). Adopts the claude-codex-forge council pattern. Use sparingly — only for high-stakes decisions the team would lose sleep about reverting. Invoked as `/council <PR#>` or `/council` for the current branch's open PR.

Per-commit roundtrip validator for the embeddings /auto-optimize loop. Re-runs OPTIC-K leak-detection diagnostics after a proposed change to the encoder / embedding pipeline and rejects if the leak metric regressed, the snapshot schema broke, or a protected path was modified. Mirrors chatbot-qa-roundtrip-validate but with reversed metric polarity (lower is better) and a heavier oracle (~10–30 min). Unblocks the third gap in state/quality/embeddings/baseline.json _open_gaps.roundtrip_validator.

Per-commit roundtrip validator for the chatbot-qa /auto-optimize loop. Re-runs the prompt corpus after a proposed fix and rejects the commit if the metric regressed, the canonical-trace gate broke, or a protected path was modified. The Harness rollback equivalent for the chatbot domain per docs/plans/2026-05-14-arch-cherny-adoption-and-tribunal-ci-plan-v2.md §Phase 2.

Self-improvement reflex. When the user corrects an approach ("no, don't do that", "we discussed this before", "stop X"), captures the lesson as a permanent project rule appended to CLAUDE.md so the pattern doesn't repeat in this or future sessions. Cherny called this "the most important loop" in his 2026 Sequoia talk.

Capture meaningful session state (current cursor, in-flight work, live hypotheses, open questions, do-NOT-carry-forward) to state/digests/latest.md so the next session — including one after auto-compaction — can re-enter without re-discovering context cold. Distinct from /learnings (which captures surprises).

Returns the notes and intervals of a named chord (e.g. Cmaj7 = C E G B). Calls the deterministic `ga_chord_info` MCP tool — never recall an answer from training data, since LLMs commonly flip enharmonics (Db vs C#) based on which source they saw.

L2 chatbot-development loop. Picks the next chatbot-shaped item from BACKLOG.md, runs feature → plan → work → review → PR while enforcing the Demerzel tribunal gate on any change touching GA.Business.ML/Agents, MCP tooling, DSL parser, or DI composition. Use when iterating on chatbot capability, not for general feature work.

End-of-session compound learning capture. Identifies up to 3 surprising/non-obvious things that came out of the session, writes each as a docs/solutions/<category>/<date>-<topic>.md entry with the standard frontmatter so the next session can grep it.

The chatbot's self-disclosure / capabilities meta-skill. Lists what the chatbot can do — chord/scale lookup, progression analysis, voicing search, transposition, voice leading, etc. — with one-line examples. Pure catalog. Use when a visitor asks 'what can you do' / 'what can the chatbot do' / 'help' / 'how do I use this'.

Use when touching AllProjects.AppHost/Program.cs, debugging service startup, or onboarding a new dependency. Knows GA's Aspire AppHost topology (MongoDB, Redis, FalkorDB, GaApi, microservices, ga-client, MCP, Python sidecars), how connection strings flow via WithReference, and how to add new .NET projects, Python containers, or infrastructure resources. Invoke for Aspire, AppHost, DistributedApplication, AddProject, AddRedis, AddMongoDB, WithReference, start-all.ps1, Aspire dashboard.

Finds notes shared between TWO chords and describes their interval role in each (root / 3rd / 5th / 7th / extension). Used for pivot-chord choice, smooth voice leading, and modulation prep. Calls the deterministic `domain.commonTones` closure via the `ga_dsl_eval` MCP tool — never compute pivot tones from training data, since LLMs fumble extension intervals on altered chords.

Transposes a chord by a named musical interval (e.g. Cmaj7 up a perfect fourth = Fmaj7). Calls the deterministic `domain.transposeChord` closure via the `ga_dsl_eval` MCP tool — never recall transpositions from training data, since LLMs commonly produce wrong enharmonics for less-common keys (Db major vs C# major).

Lists the seven modes of the major scale (Ionian, Dorian, Phrygian, Lydian, Mixolydian, Aeolian, Locrian) with their scale-degree formulas and characteristic sound. Pure catalog — same fixed pedagogy whether the user asks for the whole list or a single mode.

Finds harmonic substitutions for a chord, or classifies the relationship between two chords (tritone sub, secondary dominant, backdoor dominant, set-class equivalent, ICV neighbor). Calls deterministic Grothendieck-ICV math via MCP tools — never recall theory rules from training data.

Computes the fret span and playability of a 6-string guitar chord diagram. Calls the deterministic `ga_fret_span` MCP tool — never recall the answer from training data, since the math depends on knowing exactly which strings are open vs muted vs fretted.

Suggests a structured practice routine for a stated goal — jazz comping, soloing, ear training, fingerstyle technique, etc. Pure catalog skill drawing on guitar-pedagogy templates. Use when a learner asks 'give me a practice plan for X' / 'how do I practice Y'.

Suggests 2-3 diatonic cadence completions for an in-progress chord progression. Reuses the `ga_key_identify` MCP tool for deterministic key detection, then names cadence types (authentic / half / deceptive / plagal) drawn from the detected key's diatonic set.

Reliable techniques for darkening or brightening a chord progression — parallel-mode swaps, modal interchange (Phrygian / Aeolian / Dorian / Lydian / Mixolydian), and borrowed-chord substitutions. Use when a learner asks how to make a progression sound darker / sadder / moodier / brighter / more uplifting.

Walks through the circle of fifths — key signatures, perfect-fifth relationships, the order of sharps and flats, and the practical use for navigation between keys. Pure catalog skill. Use when a learner asks 'explain the circle of fifths' / 'how do key signatures work' / 'why are some keys sharps and others flats'.

Explains what makes a genre sound like itself — the harmonic, melodic, rhythmic, and timbral signatures of blues, jazz, pop, modal, folk, and others. Pure catalog skill. Use when a learner asks 'what makes blues blues' / 'what defines jazz harmony' / 'how do I write a country progression'.

Identifies the most likely musical key of a chord progression and explains why. Calls the deterministic `ga_key_identify` MCP tool — never recall the analysis from training data, since the diatonic-set match is pitch-class arithmetic and the LLM is unreliable at it.

Returns the seven notes of a major or minor key plus its key signature and relative key. Calls the deterministic `ga_scale_get_notes` MCP tool — never recall an answer from training data.

Suggests arpeggios, modes, and target notes for improvisation over a chord progression

Suggests logical next chords to complete or extend a partial chord progression

Returns the eight first-position open guitar chords every curriculum starts with — C, G, D, A, E, Am, Em, Dm — with diagrams and short fingering tips. Use when a learner asks 'what are the easy chords' / 'beginner chords' / 'first chords I should learn'.

Computes the simple interval between two named pitches (e.g. C to G is a perfect fifth). Calls the deterministic `ga_interval_compute` MCP tool — never recall an answer from training data.

How any AI collaborator (Codex, Conductor, Octopus, Compound Engineering, future-Claude) works alongside the QA Architect agent on this repo. Read before designing or shipping a non-trivial change.

How any AI collaborator (Codex, Conductor, Octopus, Compound Engineering, future-Claude) works alongside the QA Architect agent on this repo. Read before designing or shipping a non-trivial change.

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.

Search the OPTIC-K guitar voicing index by chord, mode, or style. Returns top-K matching voicings from a 313k-voicing mmap corpus using partition-weighted musical cosine similarity — not text embeddings. Invoke when the user asks to find, suggest, or list voicings for a chord (Cmaj7, F#m7b5), mode (Lydian, Dorian), or tag (drop2, shell, jazz, rootless).

Talk to Demerzel — the AI governance agent. Query beliefs, run pipelines, execute epistemic commands, and get recommendations via ACP.