Skip to content

AGENTS.md -- kurzz Scenario

Read ../AGENTS.md first. It covers the repository model, the host, tutorial development practice, and the content rules shared by all scenarios. This file covers kurzz-specific tracks, execution order, and invariants.

What This Scenario Is

kurzz is a playable scenario in which a human musician joins a live AI jazz ensemble using Walker as the GUI surface and jazz-server as the backend engine. The AI musicians are driven by plant_jazz (MusicianEnsemble, JazzRole, Form, BeatClock). The human reads the band through the POP Piano Roll panel in Walker and eventually emits notes into the shared form.

The scenario is organized around a tutorial arc. The first experience a new player has should be a slow, legible call-and-respond session that teaches how to listen to the ensemble and when to play. That tutorial is the narrative anchor for the whole scenario. Build toward it, not around it.

Three Parallel Tracks

All work in this scenario belongs to one of three tracks. Know which track you are on before writing any code or content.

Track A: Jazz Balance Panel (TypeScript, Walker-led)

This track builds the full playable session GUI.

Plan: PLAN-kurzz-playable-surface.md (7 phases) + PLAN-JAZZ-MONITOR.md (5 phases)

Critical path: 1. jazz-server emits jazz agent telemetry (jg-playable-surface Phase I) -- Rust 2. Session control REST API (jg-playable-surface Phase II) -- Rust 3. JazzBalanceCore + renderers (JAZZ-MONITOR Phases I-III) -- Walker TypeScript NOTE: Phases I-III are unblocked today. Start here if doing Walker work. 4. JazzBalanceRunnerAdapter wiring (jg-playable-surface Phase IV) -- Walker 5. Walker session dock layout (Phase V) -- Walker 6. Human note input (Phase VI) -- Rust + Walker

Walker work (Steps 3-6) lives in the Walker repository at /home/srussell/src/walker. Rust work (Steps 1-2) lives in the Plantangenet repository at /home/srussell/src/plantangenet/jazz/.

Do not add Walker TypeScript files to the scenarios/kurzz/ directory. Walker panel code belongs in /home/srussell/src/walker/src/panels/.

Track B: Runner-Driven HUD (Rust-led, Walker-light)

This track proves the Rust -> SSE -> Walker -> HTML path and delivers a lightweight session readout without writing a TypeScript adapter.

Plans: PLAN-WALKER-RUNNER-HUD.md (Walker) + PLAN-kurzz-runner-hud.md (this scenario)

Order: 1. PLAN-WALKER-RUNNER-HUD.md Phase I: event schemas in Walker -- unblocked 2. PLAN-WALKER-RUNNER-HUD.md Phase II: RunnerHUDRenderer.ts -- Walker 3. PLAN-WALKER-RUNNER-HUD.md Phase III: panel slot + dock -- Walker 4. PLAN-kurzz-runner-hud.md Phase I: build_hud_config() in jazz-server -- Rust, unblocked 5. PLAN-kurzz-runner-hud.md Phase II: bar-boundary HUD updates -- Rust (needs steps 1-3) 6. PLAN-WALKER-RUNNER-HUD.md Phase IV + PLAN-kurzz-runner-hud.md Phase III: E2E test

Phase IV of PLAN-WALKER-RUNNER-HUD.md (the integration test) is the historically unproven step. The prior attempt stalled here. It is named explicitly as its own phase. Do not declare Track B done until the integration test passes.

Rust work in this track lives in /home/srussell/src/plantangenet/jazz/src/bin/jazz_server.rs. Walker work lives in /home/srussell/src/walker/.

Tracks A and B share no code dependencies and can proceed in parallel.

Track C: Tutorial POP Content (data-led, no code required yet)

This track authors the scenario content: pop specs, venue specs, ren beats, ren triggers, and eventually quests. It is NOT blocked on Tracks A or B.

Content lives entirely inside scenarios/kurzz/: pop/ -- simulation.pop specs (musical guidance layer) venues/ -- simulation.jazz specs (ensemble venue configuration) ren/ -- simulation.ren scenes (VN-style cutscene beat sequences) ren_triggers/ -- simulation.ren_trigger bindings (quest -> scene) creatures/ -- simulation.npc definitions (human player, named jazzmates) area/ -- simulation.area definitions (venues as spatial contexts) quests/ -- simulation.quest definitions (musical progress objectives)

Already created (2026-05-16): pop/follow_the_leader.yaml -- tutorial pop: "Follow the Leader" venues/tutorial_follow_the_leader.yaml -- companion jazz venue spec

Tutorial pop design summary: 72 BPM, 4/4, C major, II-V-I chord loop (Dm7-G7-Cmaj7-Cmaj7). 8-bar form: call section (AI leads, bars 1-4) + respond section (bars 5-8). tutorial_cue guidance field: watch (call) / your_turn (respond). This guidance field is the hook for all tutorial ren triggers and quest conditions. Do not replace it with a timer or a hardcoded UI state -- the pop spec drives flow.

Next content work (all unblocked, no code dependencies): - ren/tutorial_watch.yml + ren/tutorial_your_turn.yml VN beats that fire on tutorial_cue transitions. - ren_triggers/tutorial_watch.yml + ren_triggers/tutorial_your_turn.yml Bind the ren scenes to tutorial_cue guidance field events. - creatures/human_player.yml The human musician creature definition. - area/the_shed.yml A small informal jazz venue area for the tutorial context. - quests/tutorial_first_respond.yml First tutorial quest: "complete one full respond section." - pop/slow_blues.yaml Second pop spec at slightly higher difficulty (once tutorial arc is stable).

Planning documents for Track C content live here: docs/plans/PLAN-kurzz-foundation.md (Layer 1: Playable session) docs/plans/PLAN-kurzz-overview.md (Navigation and dependency map)

When PLAN-kurzz-cutscenes.md and PLAN-kurzz-quests.md are written, they will also live in docs/plans/ inside this scenario directory. Not in Walker, not in the root Plantangenet plans directory.

Execution Order

When starting a new work session on this scenario, determine which track you are on and follow its order strictly. Do not skip phases. Do not implement Phase IV work while Phase I is incomplete.

If you are doing Track C content work, you do not need the code tracks to be complete. Author YAML files. Write ren beats. Track C can always proceed.

If you are doing Track A or B code work:

  • Check the current phase status in the relevant plan document.
  • Work the lowest-numbered incomplete phase first.
  • Mark the phase done-when checklist items as you complete them.
  • Do not add speculative features that are not in the current phase's deliverables.

File Ownership Rules

All paths below are relative to /home/srussell/src/plantangenet-core/.

scenarios/kurzz/pop/ -- POP specs. Authored here. Never auto-generated. scenarios/kurzz/venues/ -- Jazz venue specs. Authored here. scenarios/kurzz/ren/ -- Ren scene beat sequences. Authored here. scenarios/kurzz/ren_triggers/ -- Ren trigger bindings. Authored here. scenarios/kurzz/creatures/ -- NPC/player creature definitions. Authored here. scenarios/kurzz/area/ -- Area definitions. Authored here. scenarios/kurzz/quests/ -- Quest definitions. Authored here. scenarios/kurzz/docs/plans/ -- Plans for THIS scenario only. scenarios/kurzz/docs/tutorial/-- Technical creative tutorial narrative docs.

NO src/ directory. NO Cargo.toml. This scenario has no Rust code of its own. See Repository Model section above.

External code repositories: Walker panel code --> /home/srussell/src/walker/src/panels/ Walker HUDyML code --> /home/srussell/src/walker/src/hudyml/ Walker plans --> /home/srussell/src/walker/docs/plans/ jazz-server code --> /home/srussell/src/plantangenet/jazz/src/bin/jazz_server.rs plant_jazz crate --> /home/srussell/src/plantangenet/jazz/src/

Do not create Walker TypeScript files inside scenarios/kurzz/. Do not create a Cargo.toml or src/ directory inside scenarios/kurzz/.

Key Invariants

  • The tutorial pop spec (pop/follow_the_leader.yaml) is the narrative anchor. All tutorial ren triggers, quests, and Walker UI cues derive from it. Do not change the tutorial_cue field names (watch, your_turn) without updating all ren triggers and quest conditions that reference them.

  • The tutorial jazz venue (venues/tutorial_follow_the_leader.yaml) must keep form_length: 8 to match the pop spec's 8-bar structure. If you change one, change both.

  • PLAN-kurzz-foundation.md is the top-level progress tracker for the scenario. When a phase completes, mark its done-when checkboxes there.

  • PLAN-kurzz-overview.md is the navigation document. When new plans are created or new content files are added, update the inventory section there.

  • All plan documents inside docs/plans/ use plain ASCII only (no Unicode, no smart quotes, no em dashes). This is a hard constraint so that plan files are diff-friendly and terminal-readable without encoding issues.

Reference Files

docs/plans/PLAN-kurzz-overview.md Full dependency map and recommended start order. docs/plans/PLAN-kurzz-foundation.md Top-level phase tracker. docs/plans/PLAN-kurzz-playable-surface.md Track A detail (7 phases). docs/plans/PLAN-kurzz-runner-hud.md Track B detail (3 phases, Rust side). docs/tutorial/01_lets_pop.md Narrative walkthrough of the tutorial pop design.

Walker plans (external): /home/srussell/src/walker/docs/plans/PLAN-JAZZ-MONITOR.md /home/srussell/src/walker/docs/plans/PLAN-WALKER-RUNNER-HUD.md

Structural reference for YAML content: /home/srussell/src/plantangenet-core/scenarios/solace/ (Reference for area, creature, quest, ren, ren_trigger file shapes.)

solace is also a pure-content scenario with no Rust src/ or Cargo.toml. Its Rust host code lives in scenarios/host/, not inside solace/. Use solace's YAML files as content reference.