omnilearn-workflow 1.0.4 → 1.0.6

package/commands/omnilearn-refine.md

@@ -39,6 +39,7 @@ Both scenarios follow the same core flow: research → analyze → produce struc
 └── topics/
     └── <topic>/
         ├── topic-roadmap.md                 ← Will be updated if refined
+        ├── topic-explanation.md             ← Theory foundation (updated if refined)
         ├── assignments/                     ← May be added to if needed
         └── runs/
 ```

package/commands/omnilearn-roadmap-edit.md

@@ -75,6 +75,7 @@ This command performs the same rigorous research-backed process as `/omnilearn-r
     │       └── new-roadmap-draft.md        ← Draft of updated roadmap
     └── topics/                             ← MUST be preserved — never delete or alter topic-progress.md, assignments/, or runs/
         └── <topic-name>/
+            ├── topic-explanation.md        ← Theory foundation (read before assignments)
             ├── topic-progress.md           ← 🔑 THE source of truth for what the user has done
             ├── assignments/                ← All assignment work the user has completed
             └── runs/                       ← Learning session logs
@@ -143,7 +144,7 @@ TOPICS_DIR="$SKILL_DIR/topics"
 For each topic directory found in `$TOPICS_DIR/`:
 1. Read its `topic-progress.md` — extract:
    - Topic name and overall status (✅ Completed / 🔵 In Progress / 🟢 Not Started)
-   - Which assignments are completed (1/3, 2/3, 3/3)
+   - Which assignments are completed (e.g., 1/3, 2/2, 3/5 — not fixed to any number)
    - Skills demonstrated (from the log)
    - Last session date
 2. List the assignments directory — note which assignment files exist
@@ -163,21 +164,21 @@ Write to this file with the following structure:
 ## Topics Inventory
 | Topic | Status | Assignments Done | Skills Demonstrated | Last Activity |
 |-------|--------|-----------------|---------------------|---------------|
-| topic-1 | ✅ Completed | 3/3 | {list of skills} | {date} |
-| topic-2 | 🔵 In Progress | 1/3 | {partial skills} | {date} |
-| topic-3 | 🟢 Not Started | 0/3 | — | — |
+| topic-1 | ✅ Completed | 3/3 (N=3 total) | {list of skills} | {date} |
+| topic-2 | 🔵 In Progress | 1/2 (N=2 total) | {partial skills} | {date} |
+| topic-3 | 🟢 Not Started | 0/— | — | — |
 
 ## Detailed Topic States
 
 ### topic-1 (✅ Completed)
 - topic-progress.md: {TOPICS_DIR}/topic-1/topic-progress.md
-- Assignments: 01-basics ✅, 02-intermediate ✅, 03-real-world ✅
+- Assignments: 01-basics ✅, 02-intermediate ✅, 03-real-world ✅ (N=3 total)
 - Skills: {extracted skills demonstrated}
 - Sessions: {count} learning sessions in runs/
 
 ### topic-2 (🔵 In Progress)
 - topic-progress.md: {TOPICS_DIR}/topic-2/topic-progress.md
-- Assignments: 01-basics ✅, 02-intermediate 🔵, 03-real-world 🟢
+- Assignments: 01-basics ✅, 02-intermediate 🔵 (N=2 total planned so far — more can be added)
 - Current assignment: {which one they're on}
 - Skills: {extracted skills demonstrated so far}
 - Sessions: {count} learning sessions

package/commands/omnilearn-roadmap.md

@@ -32,6 +32,7 @@ description: Create a comprehensive, real-world-ready learning roadmap for any s
     └── topics/                                   ← Topics in the roadmap (populated during learning)
         └── <topic-name>/                         ← Each topic has its own progress tracking
             ├── topic-roadmap.md                  ← Detailed subtopic roadmap (created on-demand)
+            ├── **topic-explanation.md**          ← ← 🔑 THEORY: TL;DR → concepts → examples → pitfalls (read this first)
             ├── topic-progress.md                 ← Per-topic progress: assignments status, sessions
             ├── assignments/                      ← Hands-on assignments (generated during learning)
             │   ├── 01-<concept>/

package/commands/omnilearn-start.md

@@ -15,8 +15,8 @@ description: Start an interactive learning session. Generates hands-on assignmen
 
 ## Core Learning Philosophy
 
-**The user learns by doing, not by reading.** Every topic produces:
-1. A **topic explanation** — concise, practical overview (just enough context)
+**The user learns by doing — but needs the right theoretical foundation first.** Every topic produces:
+1. **`topic-explanation.md`** — Concise theory: TL;DR → core concepts → annotated examples → common pitfalls → best practices. The minimum viable theory you need before touching code.
 2. **Hands-on assignments** — increasing difficulty: basic → intermediate → real-world
 3. **Test scripts** — automated validation of the user's solution
 4. **Scaffold code** — starter files so they can jump straight into coding
@@ -44,6 +44,7 @@ The goal metric: **Can the user apply what they learned to real-world problems t
 └── topics/
     └── <topic-name>/                       ← e.g., "error-handling", "neural-networks"
         ├── topic-roadmap.md                ← Detailed subtopic roadmap (created on-demand)
+        ├── **topic-explanation.md**        ← ← 🔑 THEORY: concise concept explanation (TL;DR → concepts → examples → pitfalls → best practices)
         ├── topic-progress.md               ← 🔑 PROGRESS LIVES HERE: assignment status, sessions, skills demonstrated
         ├── assignments/
         │   ├── 01-<concept-basics>/
@@ -251,11 +252,53 @@ task(category="deep", run_in_background=false, timeout=600000, prompt="
    ### 2. ...
    
    ## Assignment Structure
-   - 3 assignments: Basic → Intermediate → Real-World
-   - Each builds on the previous
+   - N assignments with progressive difficulty: Basic → Intermediate → Real-World
+   - Each builds on the previous. More than 3 can be created if the user needs extra practice or the topic is deep.
    - Final assignment should be a mini-project or real-world scenario
    
-   STEP 3 — Create Assignment 1 (the first one) at:
+   STEP 3 — Create topic-explanation.md at:
+     {TOPICS_DIR}/{topic}/topic-explanation.md
+   
+   This is the THEORETICAL FOUNDATION the user reads BEFORE attempting assignments.
+   It must be concise but complete — the minimum viable theory to understand the topic.
+   Use this proven format (based on Diátaxis framework + developer learning research):
+   
+   # {topic}
+   
+   ## TL;DR
+   One paragraph. What this is and why it matters in the real world. Assume the user is scanning.
+   
+   ## Core Concepts
+   3-5 key concepts explained concisely. Each concept gets 2-3 sentences max. Use **bold** for terminology being introduced.
+   - **{Concept 1}**: What it is. Why it exists. How it connects to other concepts here.
+   - **{Concept 2}**: ...
+   
+   ## How It Works (with Examples)
+   Annotated code/example blocks showing the concept in action. Use the Diátaxis "Explanation" quadrant — explain WHY each line matters, not just WHAT it does.
+   
+   ```{language}
+   # Annotated example with numbered comments
+   ```
+   
+   > **Note:** If the topic isn't code (e.g., system design, ML theory), use diagrams described in text or real-world analogies.
+   
+   ## Common Pitfalls
+   Table format for scannability:
+   
+   | Pitfall | Why It Happens | How to Avoid |
+   |---------|---------------|--------------|
+   | {mistake} | {root cause} | {solution} |
+   
+   ## Best Practices
+   3-5 bullet points on how this is used in production / real-world scenarios. This bridges theory to the assignments.
+   
+   ## Key Takeaways
+   3-5 bullet points the user should remember after reading. These are memory anchors for the assignments.
+   
+   ## Ready to Practice?
+   Brief bridge sentence to Assignment 1: "Now that you understand {concept}, open assignment 01-{name} to apply it."
+   
+   STEP 4 — Create Assignment 1 (the first one) at:
      {TOPICS_DIR}/{topic}/assignments/01-{concept}/
    
    Create these files:
@@ -290,9 +333,9 @@ task(category="deep", run_in_background=false, timeout=600000, prompt="
      - Common mistakes and how to avoid them
      - Real-world connections
    
-   STEP 4 — Create topic-progress.md at:
-     {TOPICS_DIR}/{topic}/topic-progress.md
-   
+STEP 5 — Create topic-progress.md at:
+   {TOPICS_DIR}/{topic}/topic-progress.md
+
    This is the AUTHORITATIVE progress tracker for this topic. Structure:
    
    # Progress: {topic}
@@ -318,9 +361,10 @@ task(category="deep", run_in_background=false, timeout=600000, prompt="
    - Add topic entry with status 🔵 In Progress and a link to topic-progress.md
 
 5. MUST NOT DO:
-   - Do NOT create all 3 assignments at once — only the first one
+   - Do NOT create all assignments at once — only the first one. Subsequent assignments are generated on-demand as the user progresses.
    - Do NOT make assignments purely theoretical — use real-world scenarios
    - Do NOT skip the scaffold — the user should be able to start coding immediately
+   - Do NOT make topic-explanation.md too verbose — keep it scannable. If a section takes more than 2 minutes to read, it's too long.
    - Do NOT use any external packages that aren't standard library without noting it
    - Do NOT create assignments that are too easy (basic concept application) or too hard (leaps without foundation)
    - Do NOT leave TODOs in scaffold that require making unrelated architectural decisions
@@ -337,6 +381,7 @@ task(category="deep", run_in_background=false, timeout=600000, prompt="
 
 After completion, verify:
 - topic-roadmap.md exists with proper structure
+- **topic-explanation.md exists with all required sections (TL;DR, Core Concepts, Examples, Pitfalls, Best Practices, Takeaways)**
 - Assignment 1 exists with all 4 files (question.md, test, scaffold, solution-guide.md)
 - Test script is syntactically valid (run a quick check)
 
@@ -362,7 +407,10 @@ Read the assignment files for the current topic:
 │                                                                   │
 │  {brief description of the assignment}                           │
 │                                                                   │
+│  📖 Start here: topic-explanation.md — read the theory first     │
+│                                                                   │
 │  Files:                                                           │
+│  • Theory: {SKILL_DIR}/topics/{topic}/topic-explanation.md       │
 │  • Question: {SKILL_DIR}/topics/{topic}/assignments/             │
 │              01-{name}/question.md                                │
 │  • Scaffold: (same directory)/scaffold/                           │
@@ -370,7 +418,8 @@ Read the assignment files for the current topic:
 │  • Solution guide: (same directory)/solution-guide.md             │
 │                                                                   │
 │  To work on this:                                                 │
-│  1. Read the question.md carefully                                │
+│  1. Read topic-explanation.md for the concepts                    │
+│  2. Read the question.md carefully                                │
 │  2. Use the scaffold to write your solution                       │
 │  3. Run the test to verify your solution                          │
 │  4. Ask me questions if you're stuck                              │
@@ -547,10 +596,11 @@ task(category="unspecified-high", run_in_background=false, timeout=300000, promp
    - Read the previous assignment(s) to ensure progression: {ASSIGNMENT_DIR}
    - Read the user's learning preferences and history from {SKILL_PREFS}
    - Research online for real-world applications of this topic at this difficulty level
-   - Create the assignment with INCREASING difficulty:
+   - Create the assignment with INCREASING difficulty following this PATTERN (more levels can be added as needed):
      * Assignment 1: Basic understanding and application
      * Assignment 2: Intermediate — combine concepts, handle edge cases  
      * Assignment 3: Real-world — full scenario, multiple concerns, best practices
+     * (Additional assignments can be created if the user needs more depth or practice)
    - For each assignment, create these files in:
      {TOPICS_DIR}/{topic}/assignments/0{n}-{concept-name}/
    
@@ -597,7 +647,7 @@ task(category="unspecified-high", run_in_background=false, timeout=300000, promp
 
 ### 4.3 When All Assignments Are Complete
 
-When all 3 assignments for a topic are done:
+When all required assignments for a topic are done (the topic-roadmap defines how many; the default progression is 3 but more can be added):
 
 1. **Update `topic-progress.md`** — set overall status to ✅ Completed, finalize all assignment statuses.
 2. **Update `progress-index.md`** — mark topic as ✅ Completed (this is the overview index).
@@ -722,6 +772,8 @@ If no git repo: ask if user wants to initialize one (same as /omnilearn-roadmap)
 | Skill roadmap exists | 0 | Tell user to run /omnilearn-roadmap first |
 | User preferences read | 0 | Read the files |
 | Topic roadmap exists (if needed) | 1.4 | Create it via deep subagent |
+| topic-explanation.md exists with all sections (TL;DR, Concepts, Examples, Pitfalls, Best Practices, Takeaways) | 1.4 | Re-generate — topic-explanation.md is mandatory |
+| topic-explanation.md is scannable (not verbose) | 1.4 | Trim to essential theory only |
 | Assignment 1 exists (question, test, scaffold, solution) | 1.4 | Fix incomplete assignment |
 | Assignment tests are syntactically valid | 1.4 | Quick syntax check, fix if broken |
 | topic-progress.md created when topic roadmap is made | 1.4 | Create it with proper structure |
@@ -777,7 +829,7 @@ Each level should feel meaningfully harder. The jump from 02 to 03 should be the
 - ❌ Do NOT write explanations when user has a doubt — generate a diagnostic task instead
 - ❌ Do NOT give away solutions when the user is stuck — give them tasks that lead to the answer
 - ❌ Do NOT skip scaffold files — the user needs a starting point
-- ❌ Do NOT make all 3 assignments the same difficulty — progression is critical
+- ❌ Do NOT make all assignments the same difficulty — progression is critical. Each should be noticeably harder than the last.
 - ❌ Do NOT let runs/ contain progress state — runs/ is for action logs only, topic-progress.md is the source of truth
 - ❌ Do NOT skip updating topic-progress.md — it's the authoritative progress record per topic
 - ❌ Do NOT lose the user's work or progress — always read topic-progress.md before acting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omnilearn-workflow",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "OmniLearn — AI-powered adaptive learning workflow for OpenCode. Multi-agent orchestration that creates personalized roadmaps, hands-on assignments, and tracks progress across any skill.",
   "keywords": [
     "opencode",