Roadmap

Roadmap

A phase-by-phase plan for growing the profilers from two standalone CLIs into a complete text-leveling toolkit for the EFL classroom — and, ultimately, the shared analysis engine behind the RubricMaker grading platform.

The through-line is one teacher question: "is this text right for this class, and if not, what has to change?" Each phase moves closer to answering it in one command, and closer to feature parity with what RubricMaker already does inside a full app (see RubricMaker Alignment).

Status legend — ✅ shipped · 🔨 in progress · 📋 planned · 💭 idea

This is a direction of travel, not a dated commitment. Phases are ordered by dependency: each builds on the one before.

---

Phase 0 — Foundations ✅ (shipped)

Everything that exists today.

• ✅ Vocabulary profiler — CEFR (A1–C2), AWL, and NAWL banding, deterministic word-list matching, dependency-free Python 3.
• ✅ Grammar profiler — ~70 constructions across every major family, mapped to CEFR via the CEFR-J Grammar Profile, rule-based over a spaCy parse (no AI).
• ✅ File formats — .txt, .md, .docx, .pdf, and stdin.
• ✅ Two output modes — colour pretty for the terminal, json for scripts, auto-selected by whether output is a TTY.
• ✅ Claude Code plugins & skills — ask for a level in a Cowork session.
• ✅ Rebuilt, provenance-documented word lists and a citable grammar profile.

Outcome: you can profile any single text two ways, by hand or in chat.

---

Phase 1 — One text, one verdict ✅ (shipped)

Make the two profilers answer as one, and answer against a target.

• ✅ Unified difficulty report — text_report.py runs both profilers and prints one combined summary (vocabulary band + grammatical range + a blended estimatedLevel), instead of two separate invocations.
• ✅ --target-level B1 — pass the class's level and the report flags what exceeds it: words above B1, constructions above B1, and a one-line verdict ("on level" / "reaches B2 — pre-teach 6 words, 2 structures").
• ✅ Coverage figure — "a B1 learner will already know ~92% of the running words," the single number teachers ask for most.
• ✅ Readability line — Flesch–Kincaid / Flesch Reading Ease, reported alongside — never instead of — the CEFR bands.
• ✅ Pre-teaching exports — --export md|csv|flashcards write the above-target words and structures as a handout, spreadsheet, or RubricMaker-importable flashcard deck; --cloze turns the examples into fill-the-gap sentences that paste straight into a RubricMaker fill-the-gap question.
• ✅ Free dictionary enrichment — decks ship with plain definitions, phonetics and part-of-speech from the Free Dictionary API (no key), backed by a persistent JSON lookup cache; --pre-enrich primes the cache for a whole class's word list in one polite, rate-limited pass. Offline or on a miss, the deck falls back to in-context sentences.
• ✅ OLP-EN-CEFRJ wordlist merge — build_wordlists.py gap-fills the CEFR lists from the open CEFR-J + Octanove profiles and emits levels.json, so CEFR levels need no dictionary API.

RubricMaker parallel: its document analysis already reports vocabulary and grammar on one uploaded essay — Phase 1 gives the CLI the same combined view, and its deck import now reads the CLI's enriched output directly.

---

Phase 2 — A class set, not one text 📋

Scale from one text to the folder of candidate readings a teacher actually has.

• 📋 Batch mode — --file accepts a directory or glob; profile a whole folder in one run.
• 📋 CSV / summary report — one row per text (filename, typical & reached vocabulary band, grammar range, % above target), ready for a spreadsheet.
• 📋 Rank & filter — sort a set of texts by level, or list only those that fit a target band — turning "which of these 20 articles suits B1?" into one command.
• 📋 Vocabulary-list export by band — dump the distinct words in each CEFR band to CSV, for pre-teaching lists and glossaries.

Why now: Use Cases 5 and 10 are shell loops today; this makes them first-class.

RubricMaker parallel: directly mirrors RubricMaker's Vocabulary Profile dashboard, which aggregates a class's texts into a CEFR distribution and exports vocabulary lists by CEFR band to CSV — Phase 2 produces the same artifact from the command line.

---

Phase 3 — From analysis to adaptation 📋

Stop only describing difficulty and start helping change it — the heart of the original VocabKitchen ("adjust a text to a target level").

• 📋 Above-target highlighting — list (and, in pretty mode, colour) every word and construction above the target level, so a rewriter sees the offenders at a glance (Use Case 6).
• 📋 Simpler-synonym suggestions — for each above-level word, suggest a lower-band alternative (purchase → buy), from a curated substitution list.
• 💭 Grammar gap report — given a target level, list the target-level constructions the text does not use yet, for graded-reader authors who need to introduce structures, not just remove them.
• 💭 Watch mode — re-profile on save for a tight edit → re-check loop.

Why now: once Phase 1 knows the target and Phase 2 handles many texts, adaptation aids are the natural next step and the highest-value one for materials writers.

RubricMaker parallel: RubricMaker's grammar linker checks target grammar per-criterion; the CLI's gap report is the authoring-side twin — what's missing versus what's present.

---

Phase 4 — Standards & framework alignment 📋

Speak the frameworks teachers are held accountable to, not just raw CEFR.

• 📋 Curriculum checklist — profile a text (or unit) against a supplied list of required grammar/vocabulary and get a pass/fail coverage report (Use Case 7).
• 📋 Cambridge English exam mapping — report the matching Cambridge Qualification (A2 Key, B1 Preliminary, B2 First, C1 Advanced, C2 Proficiency) next to each CEFR band, as an opt-in.
• 💭 CEFR Can-Do framing — express a text's demands as Can-Do descriptors, the language rubrics and self-assessment already use.
• 💭 Pluggable vocabulary profiles — first-class support for swapping in Oxford 3000/5000 or the Octanove C1/C2 profile via the existing one-word-per-line format, for teams standardised on a licensed list.

RubricMaker parallel: RubricMaker offers the exact same Cambridge English exam mapping and links criteria to standards (CCSS/NGSS, Dutch kerndoelen, CEFR Can-Do). Phase 4 makes the CLI produce output in those same frameworks, so a text profiled on the command line and a criterion graded in the app describe proficiency identically.

---

Phase 5 — The analysis engine behind RubricMaker 📋

Close the loop: make these profilers the authoritative text-analysis backend RubricMaker calls, so both tools share one CEFR taxonomy and one implementation.

• 📋 Stable library / JSON contract — a documented, versioned output schema and an importable entry point (not just a CLI), so RubricMaker's document analysis (vocabulary & grammar checking on uploaded essays) can call the profilers directly instead of maintaining a parallel implementation.
• 📋 Per-criterion grammar pass/fail — emit results in the shape RubricMaker's grammar linker consumes for its per-criterion, apply-as-comment breakdown.
• 💭 Feed the Vocabulary Profile dashboard — batch-profile a class's essays and hand back the per-student CEFR vocabulary distribution the dashboard renders.
• 💭 Single source of truth for grammar — the CEFR-J Grammar Profile bundled here becomes the shared taxonomy both tools cite, so a construction is levelled the same way whether it's detected in a reading (CLI) or an essay (app).
• 📋 Free lookup swap in RubricMaker — replace cambridgeApi.lookupWord (the paid Cambridge Dictionary API) with the free stack the CLI now uses: CEFR levels from the bundled CEFR-J / levels.json, definitions + phonetics from the Free Dictionary API, sharing the same cache format so teacher lookups and deck exports use one warmed cache.
• 📋 Offline dictionary fallback — bundle Open English WordNet (CC BY 4.0) so definitions ship even with no network, writing results into the same lookup cache — the final layer that makes enrichment fully offline-capable.
• 📋 Import RubricMaker vocabulary lists into --pre-enrich — read a class's vocabulary-list export (CSV/JSON) directly, so the cache is primed from the app's own data without reformatting.

Why last: it depends on the combined report (Phase 1), the framework alignment (Phase 4), and a proven detection surface — but it's the destination that makes the whole roadmap coherent: one leveling engine, two front ends (a CLI for materials prep, a web app for grading).

---

How the phases build on each other

Phase 0  two profilers, one text            ✅ shipped
   │
Phase 1  one combined verdict + target      → answers "right for my class?"
   │
Phase 2  many texts, CSV, by-band export     → answers "which of these?"
   │
Phase 3  highlight + simplify + gaps         → answers "what do I change?"
   │
Phase 4  Cambridge / curriculum / Can-Do     → answers "in my framework"
   │
Phase 5  shared engine for RubricMaker       → one taxonomy, two front ends

Already-shipped groundwork that makes this realistic: a data-driven design (word lists and the grammar profile are swappable files, not hard-coded), a stable JSON output the tests freeze, and a no-AI, rule-based core that is deterministic and auditable — the same principles RubricMaker's own analysis is built on.

---

See also

• Use Cases — the scenarios each phase improves.
• RubricMaker Alignment — the feature-by-feature map these phases converge on.