jp-learner
A 24-week Japanese listening and speaking program for Chinese-speaking learners, built as a Claude Code plugin. Powered by specialized agents that plan your curriculum, coach your pronunciation, and track your progress across every session.
Purpose
jp-learner guides you from beginner (N5) through lower-intermediate (N4/N3) Japanese over 24 structured weeks, with a focus on:
- Listening comprehension — staged transcript drills with comprehension questions
- Shadowing — sentence-level pronunciation and rhythm training
- Speaking production — prompted free-speech tasks with native-level correction
- Vocabulary and grammar — spaced repetition informed by your actual mistake patterns
The program is designed for Chinese-speaking learners: all explanations, prompts, and feedback are in Chinese (Traditional) by default.
Installation
- Clone or copy this plugin directory into your Claude Code plugins folder.
- Run
/jp-init in Claude Code to create your learner profile and generate your 24-week plan.
- Run
/jp-today each day to get your personalized task list.
Command Reference
| Command | Description | Agent | Skill |
|---|
/jp-init [goal] [level] [daily_minutes] | Initialize profile and generate 24-week study plan | Planner | build-study-plan |
/jp-today [available_minutes?] | Get today's personalized task list | Planner | generate-daily-tasks |
/jp-vocab [count?] [topic?] | Vocabulary training session | Planner | select-vocab-items |
/jp-grammar [pattern?] | Grammar pattern training session | Planner | select-grammar-items |
/jp-listen [topic?] [duration?] | Structured listening comprehension drill | Planner | generate-listening-drill |
/jp-shadow [topic?] | Shadowing drill for pronunciation and rhythm | SpeakingCoach | generate-shadowing-drill |
/jp-speak [topic?] [duration?] | Free speaking task with hints and sample answer | SpeakingCoach | generate-speaking-prompt |
/jp-review <answer_text> [target_pattern?] | Get correction and coaching on a Japanese answer | SpeakingCoach | review-answer |
/jp-complete <task_id> <rating> [note] | Mark task complete and update progress | ProgressTracker | update-progress |
/jp-weekly | Weekly performance review and next-week plan | ProgressTracker | build-weekly-review |
Architecture
Commands (user entry points)
|
v
Agents (specialists)
+-----------+ +--------------+ +----------------+
| Planner | | SpeakingCoach| | ProgressTracker|
| (opus) | | (sonnet) | | (sonnet) |
+-----------+ +--------------+ +----------------+
| | |
v v v
Skills (reusable logic modules)
build-study-plan review-answer update-progress
generate-daily-tasks generate-speaking build-weekly-review
select-vocab-items generate-shadowing
select-grammar-items
generate-listening-drill
| |
v v
Data (content library) Storage (learner state)
data/vocab.json storage/users.json
data/grammar.json storage/progress.json
data/listening.json storage/daily_state.json
data/speaking.json storage/reviews.json
24-Week Program Structure
| Phase | Weeks | Focus | Skills Emphasized |
|---|
| Foundation | 1–8 | Vocabulary + Listening | select-vocab-items, generate-listening-drill |
| Structure | 9–16 | Grammar + Shadowing | select-grammar-items, generate-shadowing-drill |
| Production | 17–24 | Speaking + Review | generate-speaking-prompt, build-weekly-review |
Memory Layers (per spec §11.1)
jp-learner maintains four memory layers across sessions:
| Layer | File | What It Stores |
|---|
| Long-term learning memory | storage/users.json | Profile, goals, 24-week plan |
| Session state | storage/daily_state.json | Today's tasks, completions, ratings, weak points |
| Progress memory | storage/progress.json | Mastery state, streaks, recurring mistakes, score trends |
| Review history | storage/reviews.json | All answer corrections with mistake classifications |
MVP Scope
The current version covers:
- Profile initialization and 24-week plan generation
- Daily task list generation with time budgeting
- Vocabulary drills (5 N5 seed items)
- Grammar pattern sessions (4 N5 seed patterns)
- Listening comprehension drills (3 seed passages: N5–N4)
- Shadowing from listening/speaking source material
- Speaking tasks with scaffolded hints (3 seed prompts)
- Answer correction with mistake categorization
- Streak tracking and mastery promotion
- Weekly review summaries
josix
josix
