A gamified learning application that helps agile teams write better user stories through interactive practice and instant feedback.
- Story Crafting: Three-field form for writing user stories (As a..., I want..., So that...)
- Real-time Scoring: Instant feedback on story quality with detailed breakdown
- Smart Feedback: Lightweight NLP analysis with actionable suggestions
- Progress Tracking: XP-based leveling system (Novice → Apprentice → Writer → Storyteller → Product Sage)
- Badge Display: All badges shown near XP — earned badges are highlighted, locked badges are greyed out with a tooltip describing how to earn them
- Achievements: Unlock badges for milestones and quality writing
- Story History: Track all your stories with CSV export functionality
- Persistent Storage: Progress and stories saved locally
The app evaluates user stories based on:
- Completeness (10 pts): All three fields filled
- Length (10 pts): Ideal range 18-40 words
- Clarity (10 pts): Simple, direct language without filler
- Value Statement (20 pts): Specific, outcome-focused "So that..." clause
- Creativity (5 pts): Unique word usage
Maximum Score: 55 points per story
- Levels: Progress through 5 levels based on total XP
- Achievements: Unlock badges like "Crystal Clear Value", "Concise Master", "Epic Writer"
- Instant Feedback: Get suggestions for improvement after each submission
Try the app live at: https://leejsinclair.github.io/kipling-v2/
- Node.js 16+
- npm or yarn
- Clone the repository:
git clone https://github.com/leejsinclair/kipling-v2.git
cd kipling-v2- Install dependencies:
npm install- Start the development server:
npm run dev- Open your browser to http://localhost:5173
npm run buildThe production-ready files will be in the dist directory.
This project is configured to automatically deploy to GitHub Pages when changes are pushed to the main branch. The GitHub Actions workflow handles building and deployment.
To enable GitHub Pages for your fork:
- Go to your repository Settings
- Navigate to Pages (under Code and automation)
- Under "Build and deployment", select "Source: GitHub Actions"
- The site will be available at
https://<your-username>.github.io/kipling-v2/
npm run preview- React 19.2 - UI framework with hooks
- Tailwind CSS 4.1 - Utility-first CSS framework
- Vite 7.3 - Fast build tool and dev server
- LocalStorage - Client-side data persistence
- Write a Story: Fill in the three fields with your user story
- Get Scored: Submit to receive instant analysis and score
- Earn XP: Each submission adds to your total experience points
- Level Up: Progress through levels as you practice
- Unlock Achievements: Earn badges for quality writing and milestones
- Export Stories: Download your story history as CSV
By using this app, you'll learn to:
- Write complete user stories with clear personas, goals, and outcomes
- Articulate value statements that focus on outcomes rather than features
- Use concise, direct language without filler words
- Understand what makes a high-quality agile user story
This project is open source and available under the MIT License.
Contributions are welcome! Please feel free to submit a Pull Request.
This repository accepts issue reports only for code bugs and functional product requests.
Maintenance mode: this is a personal project with limited maintainer capacity, so issue and PR responses may be delayed or unavailable.
This application was built following the comprehensive story plan in storyplan.md, which defines:
- Game mechanics and scoring algorithms
- NLP heuristics for story evaluation
- Progression system and achievements
- Non-functional requirements (fast scoring, offline-friendly, accessible)
Built with ❤️ using React & Tailwind CSS • Helping teams write better user stories