[Phase 2] Scripted tutorial step engine driving avatar prompts and awaiting user interaction

[don-petry]

Story

As a first-time TalkTerm user,
I want be walked through an ordered sequence of steps where the avatar prompts me and then waits for me to actually do the thing,
so that I learn the interaction model by doing each action myself, at my own pace, rather than watching a passive demo.

Acceptance Criteria

1. A step engine advances through an ordered list of steps, tracking the current step and exposing next/back/skip transitions.
2. For each step the engine plays an avatar prompt (TTS) and then blocks progression until the step's expected user interaction (voice, ActionCard selection, or text) is satisfied.
3. Scripted steps that require no generated content do not invoke the live agent loop.
4. If the microphone is unavailable or permission is denied, a step that expects voice falls back to the text input path so the user is never stuck.
5. Engine step transitions and the step definitions are decoupled, so step content can be supplied by a later story without changing the engine.

Tasks / Subtasks

• Implement a step state machine (ordered steps, current-step tracking, next/back/skip) decoupled from concrete step content. (AC: Install BMad Method v6.2.0 with Claude Code integration #1, Add architecture, UX design, and enhanced planning artifacts #5)
• Per step, drive an avatar TTS prompt and await the declared expected interaction before advancing. (AC: Add brainstorming session: TalkTerm concept review and revision #2)
• Ensure scripted-only steps short-circuit the full agent loop (no generation call). (AC: chore: add Dependabot with auto-merge via GitHub App #3)
• Add a voice->text fallback when the microphone is unavailable or denied. (AC: Bump actions/create-github-app-token from 1 to 3 #4)
• Define a step interface/schema (prompt, expected interaction, completion predicate) the content story implements. (AC: Add architecture, UX design, and enhanced planning artifacts #5)

Dev Notes

• The discussion is internally inconsistent about whether tutorial steps run through the real agent pipeline (Technical Opportunity) or bypass the full agent loop (Suggested Next Step). Design the engine so each step DECLARES whether it needs generation; do not hardcode 'always bypass' or 'always pipeline'. The pipeline-boundary decision is an open question and must not be baked into an AC.
• Reuse existing input handling for voice and text (UX-DR9) and ActionCard selection (UX-DR2); the engine observes those existing input events to decide a step is complete rather than reimplementing input capture.
• Blocking-until-satisfied should be event-driven, not a busy wait; a step completes when its completion predicate fires on a real user interaction event.
• Fallback path matters for the primary non-technical audience: mic permission prompts frequently fail on first run, so voice steps must degrade to text rather than dead-end.
• Testing: drive the engine with a fake set of steps and simulated interaction events to assert ordering, blocking, skip, and the voice->text fallback without real audio.

Project Structure Notes

New step-engine module consumed by the tutorial session type from story 1; observes existing input/ActionCard events rather than adding new input capture.

References

• Ideas Discussion 💡 Guided Interactive Onboarding: Avatar-Led Learn-by-Doing First Session #245 — Technical Opportunity vs Suggested Next Step (pipeline-vs-bypass tension)
• TalkTerm UX-DR9 — text input (guided text path and no-mic fallback)
• TalkTerm UX-DR2 — ActionCards (selection as a step-completion signal)

Likely target surface

• tutorial step engine / state machine
• avatar TTS prompt driver
• input-event observation for step completion

Story prepared by the BMAD Scrum Master (Bob) for epic #333. Status: ready-for-dev.