Lore Engine / Narrative UX for Workflow Phases

[dean0x]

Summary

Add ANSI-colored transition banners, iteration naming (kill streaks), and phase-specific spinner verbs to DevFlow workflows, providing visual state tracking and progress legibility across multi-phase operations.

Motivation (from Kiln Analysis)

Kiln's lore engine is functional infrastructure, not decoration. It serves state visualization and progress legibility through three data files and a consistent presentation system.

Three Data Files

File	Contents
lore.json	6 greetings + 18 transition states with themed quotes (4-6 per transition)
spinner-verbs.json	8 categories with ~8 verbs each (onboarding, brainstorm, research, architecture, build, review, validation, generic)
agents.json	24 agents x 5-6 personality quotes each

ANSI Color Palette

Purpose	Code	Visual
Brand [kiln]	38;5;173	Warm terracotta
Quote text	38;5;222	Warm gold
Dividers/titles	38;5;179	Muted gold
Kill streak	1;38;5;208	Bold orange
Success	32	Green
Failure	31	Red
Dim/secondary	2	Faint

Transition Banner Format

Single bash call, 2-3 lines max (Claude Code truncates longer output):

printf '\033[38;5;179m━━━ %s\033[0m \033[90m[%s]\033[0m\n\033[38;5;222m"%s"\033[0m \033[2m— %s\033[0m\n' \
  "$TITLE" "$STEP_PROGRESS" "$QUOTE_TEXT" "$QUOTE_SOURCE"

Output:

━━━ Ignition  [1► 2○ 3○ 4○ 5○ 6○ 7○]
"The secret of getting ahead is getting started." — Mark Twain

Kill Streak Names (20, cycling per build iteration)

#	Name	Source
1	first-blood	Dota 2
2	combo	Killer Instinct
3	super-combo	Killer Instinct
4	hyper-combo	Killer Instinct
5	rampage	Dota 2
6	brutal-combo	Killer Instinct
7	dominating	Dota 2
8-20	...	(continues alternating Dota 2 / Killer Instinct)

Kill streak banner:

━━━ ▸ HYPER COMBO ━━━  Iteration 4 · Milestone 2/5
"It does not matter how slowly you go as long as you do not stop." — Confucius

Status Symbols

✓ (complete), ► (active), ✗ (failed), ○ (pending), ⏸ (paused)

Two-Channel Presentation Pattern

• Description (in ● Bash(...) header): narrative setup, evocative
• Output (ANSI-colored banner): visual payoff
• Together they tell a story — no duplication between channels

18 Transition States

Pipeline events map to lore keys: ignition, brainstorm_start, brainstorm_complete, research_start, research_complete, planning_start, plan_approved, architecture_complete, build_start, phase_start, phase_complete, milestone_complete, phases_complete, validation_start, validation_passed, validation_failed, report_start, project_complete, halt.

Spinner Verbs by Phase

Each phase installs step-specific spinner verbs to .claude/settings.local.json — silently, during banner display.

Current State in DevFlow

• Workflows are functional but visually flat
• No phase transition indicators beyond agent spawn messages
• No iteration naming or progress visualization
• No phase-specific spinner verbs
• Users can't quickly tell which phase they're in or how far along they are

Technical Approach

1. Data Files

shared/data/
├── lore.json              # Transition quotes per phase
└── spinner-verbs.json     # Phase-specific spinner verbs

2. DevFlow Phase Mapping

DevFlow Event	Banner Title	Lore Key
/implement start	Explore	explore_start
Explore complete	Context Gathered	explore_complete
Plan start	Planning	plan_start
Plan approved	Plan Locked	plan_approved
Implement start	Build	build_start
Review start	Review	review_start
Review complete	Review Complete	review_complete
/code-review start	Code Review	code_review_start
Reviewer N dispatched	Reviewer: {focus}	reviewer_dispatch
Synthesis start	Synthesis	synthesis_start
Review delivered	Report Ready	report_complete

3. Implementation in Commands

Add printf calls at phase transitions in orchestration commands:

# In implement.md orchestration
printf '\033[38;5;179m━━━ Explore\033[0m \033[90m[1► 2○ 3○ 4○]\033[0m\n'
printf '\033[38;5;222m"%s"\033[0m \033[2m— %s\033[0m\n' "$QUOTE" "$SOURCE"

4. Kill Streaks for Iterative Builds

When /implement runs multiple Coder iterations (Scrutinizer/Shepherd feedback loops):

• Iteration 1: "FIRST BLOOD"
• Iteration 2: "COMBO"
• Iteration 3: "SUPER COMBO"
• etc.

Makes iterative refinement feel like progress, not repetition.

5. Spinner Verb Installation

During each phase transition, silently update .claude/settings.local.json with phase-appropriate spinner verbs.

Acceptance Criteria

• shared/data/lore.json with quotes for each DevFlow phase transition
• Phase transition banners in /implement and /code-review commands
• ANSI colors consistent across all banners (DevFlow brand palette)
• Status symbols showing phase progress (✓►○)
• Kill streak names for iterative build cycles
• Spinner verbs per phase (optional, can defer)
• Banners are 2-3 lines max (Claude Code truncation constraint)
• No impact on non-visual functionality

References

• Kiln repo: lore.json, spinner-verbs.json, kill-streaks.md
• Kiln's two-channel presentation pattern (description + ANSI output)
• DevFlow workflow phases: /implement (Explore → Plan → Build → Review), /code-review (Dispatch → Review → Synthesize)
• Priority: Low-Medium impact, Very Low effort — "Polish"