Built with Kiro

How we used spec-driven development, agent hooks, steering docs, and MCP to build LearningSong entirely with AI assistance

✨ 100% Kiro-Powered Development

🎵 What is LearningSong?

LearningSong transforms educational content into memorable songs using AI. It merges two powerful domains: music and learning.

We've all struggled to memorize dry educational content. Songs stick in our heads effortlessly—why not harness that for learning? LearningSong was born from the idea that AI could bridge the gap between boring study material and memorable musical experiences.

🎯 The Core Flow

  • Page A (Text Input): Paste educational content (up to 10,000 words). Optional Google Search grounding enriches short queries.
  • Page B (Lyrics Editing): AI-generated lyrics appear for review and editing. Choose from 8 music styles.
  • Page C (Song Playback): Suno API generates two song variations with karaoke-style synchronized lyrics.

📋 Spec-Driven Development

We built LearningSong entirely through spec-driven development with Kiro, creating 10 comprehensive specs from project setup to E2E testing. Each spec followed a rigorous 3-document structure:

📄 requirements.md
EARS-compliant acceptance criteria with formal WHEN/THEN/SHALL syntax for unambiguous requirements
🏗️ design.md
Architecture diagrams, component interfaces, data models, and correctness properties
✅ tasks.md
Numbered implementation checklist with hierarchical tasks referencing specific requirements

The 10 Specs (in order)

1
project-setup
Foundation—React/FastAPI architecture, Firebase integration, dev environment
2
page-a-text-input
Home page—text input, Google Search grounding toggle, rate limit display
3
page-b-lyrics-editing
Lyrics editor—AI-generated lyrics, 8 music style selection, song generation
4
page-c-song-playback
Playback page—audio player, basic lyrics display, song metadata
5
dual-song-selection
Dual variations—SongSwitcher component, variation storage, user preference persistence
6
timestamped-lyrics-sync
Karaoke sync—word-level highlighting, binary search for O(log n) lookup, auto-scroll
7
song-playback-improvements
Offset adjustment, song history, LRC export
8
page-b-debugging
Debugging pipeline issues and UI refinements
9
e2e-chrome-devtools-testing
End-to-end testing with Chrome DevTools MCP
10
implementation-analysis
Cross-cutting concerns and architecture review

🪝 Agent Hooks

We created 4 agent hooks to automate testing and linting workflows. Click any card to view the hook configuration.

🔍 ESLint Report Generator
Runs ESLint, saves raw output to ./temp/, generates formatted checklist in ./report/lint-checking/ with issues grouped by file and prioritized (Urgent → Low Risk)
Linting User Triggered
⚡ Oxlint Report Generator
Fast linting for daily development. Runs oxlint and saves formatted report with timestamp, grouped by file path with errors prioritized at top
Linting User Triggered
🧪 Frontend Test Report
Runs Jest tests, generates timestamped reports in ./report/frontend-test/ with errors organized as todo lists from urgent to low risk
Testing User Triggered
🐍 Backend Test Report
Runs pytest with coverage, generates comprehensive test reports with coverage metrics
Testing User Triggered

🧭 Steering Documents

Three concise steering files in .kiro/steering/ kept Kiro aligned with our architecture and conventions. Click any card to view the full content.

📦 product.md
Core flow, features, MVP constraints (anonymous auth, 3 songs/day, 48-hour retention, max 10,000 words)
Product
📁 structure.md
Project layout, frontend/backend directory structure, naming conventions, @/ alias
Architecture
⚙️ tech.md
Technology stack, quick commands, dev workflow (backend :8000, frontend :5173)
Tech Stack

🔌 MCP Integration

We integrated 3 MCP servers that extended Kiro's capabilities beyond the IDE.

🌐 Fetch MCP
Purpose: External API documentation access
Usage: Fetched Suno API documentation to understand response formats and endpoints. Retrieved library docs (TanStack Query, Zustand) for correct usage patterns. Enabled Kiro to work with up-to-date API specs without manual copy-paste.
📚 Context7 MCP
Purpose: Library-specific knowledge
Usage: Provided accurate, version-specific documentation for React 19, FastAPI, and shadcn/ui. Helped resolve breaking changes between library versions. Reduced hallucination on API usage—Kiro generated correct code on first try.
🔧 Chrome DevTools MCP
Purpose: E2E testing and debugging
Usage: Visual debugging with screenshots, network monitoring, console capture, page navigation automation. Essential for testing the complete user flow across all 3 pages.

🛠️ Tech Stack

Frontend

React 19
TypeScript
Vite
TailwindCSS 4
shadcn/ui
Zustand
TanStack Query
Socket.IO
Jest + RTL
Oxlint
ESLint
pnpm

Backend

FastAPI
Python 3.11+
Poetry
LangChain
LangGraph
Pydantic v2
pytest
Hypothesis

External Services

Suno API
Firebase Auth
Firestore
Google Search API
Redis

🏆 Key Accomplishments

📋 10 Complete Specs
Covering every major feature from project setup to E2E testing
🧪 Property-Based Testing
Hypothesis (Python) and fast-check (TypeScript) ensuring correctness across edge cases
🎤 Karaoke-Style Lyrics
Word-level highlighting with smooth auto-scroll and binary search O(log n) lookup
🎵 Dual Song Selection
Compare and choose between two AI-generated song variations