omnilearn-workflow 1.0.3 → 1.0.5

package/commands/omnilearn-init.md

@@ -37,9 +37,20 @@ This global location is always accessible regardless of which project directory
 
 ```
 {learningDirectory}/
-└── .omnilearn/
-    ├── config.json              ← Mirror of the global config (for reference)
-    └── UserPreferences.md       ← Global user preferences (auto-populated)
+├── .omnilearn/                  ← ONLY configuration and global preferences
+│   ├── config.json              ← Mirror of the global config (for reference)
+│   └── UserPreferences.md       ← Global user preferences (auto-populated)
+│
+├── <skill>/                     ← Skills live at the ROOT of learning directory
+│   ├── roadmap.md
+│   ├── SkillPreferences.md
+│   ├── SkillConventions.md
+│   ├── progress-index.md
+│   ├── runs/
+│   └── topics/
+│
+└── <another-skill>/             ← Each skill is its own top-level folder
+    └── ...
 ```
 
 ## Phase 0: CHECK EXISTING CONFIG
@@ -117,7 +128,8 @@ sed -i "s|DATE_PLACEHOLDER|$(date +%Y-%m-%d)|g" "$OMNILEARN_CONFIG"
 ### 2.2 Create Base Directory Structure
 
 ```bash
-# Create .omnilearn in the learning directory
+# Create .omnilearn in the learning directory (config only)
+# Skills will be created as top-level directories at $LEARNING_DIR
 OMNILEARN_DIR="$LEARNING_DIR/.omnilearn"
 mkdir -p "$OMNILEARN_DIR"
 

package/commands/omnilearn-refine.md

@@ -25,7 +25,7 @@ Both scenarios follow the same core flow: research → analyze → produce struc
 ## Directory Structure
 
 ```
-.omnilearn/<skill>/
+<skill>/                                          ← Skill at learning directory root
 ├── roadmap.md
 ├── SkillPreferences.md
 ├── SkillConventions.md                  ← 🔑 Setup conventions read for consistent diagnostic tasks
@@ -121,7 +121,7 @@ fi
 
 LEARNING_DIR=$(grep -o '"learningDirectory"[[:space:]]*:[[:space:]]*"[^"]*"' "$OMNILEARN_CONFIG" | sed 's/"learningDirectory"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
 OMNILEARN_DIR="$LEARNING_DIR/.omnilearn"
-SKILL_DIR="$OMNILEARN_DIR/<skill>"
+SKILL_DIR="$LEARNING_DIR/<skill>"
 TOPIC_DIR="$SKILL_DIR/topics/<topic>"
 TOPIC_ROADMAP="$TOPIC_DIR/topic-roadmap.md"
 CURRENT_RUN="$SKILL_DIR/runs/$(date +%s)-refine-<topic>"
@@ -410,7 +410,7 @@ Write to `$CURRENT_RUN/agent-log.md`:
 
 ```bash
 if git rev-parse --git-dir > /dev/null 2>&1; then
-  git add "$OMNILEARN_DIR/"
+  git add "$LEARNING_DIR/"
   git commit -m "omnilearn: refine topic '{topic}' in {skill}
 
 - {summary of what was done}
@@ -442,7 +442,7 @@ If no git repo: ask if user wants to initialize one (same pattern).
 | Topic not found | Suggest available topics from the skill roadmap |
 | User's question is too vague | Ask clarifying questions before researching |
 | Research yields poor results | Try alternative search queries, broaden scope |
-| Refinement accidentally modifies assignments | Revert: `git checkout .omnilearn/{skill}/topics/{topic}/assignments/` |
+| Refinement accidentally modifies assignments | Revert: `git checkout $SKILL_DIR/topics/$TOPIC/assignments/` |
 | User wants to undo refinement | Archive current, restore from git or previous file in runs/ |
 | User has multiple questions | Answer the most foundational one first, then the dependent ones |
 

package/commands/omnilearn-roadmap-edit.md

@@ -59,14 +59,15 @@ This command performs the same rigorous research-backed process as `/omnilearn-r
 ## Directory Structure Reference
 
 ```
-.omnilearn/
-├── UserPreferences.md
-└── <skill-name>/
+.omnilearn/                                        ← Config only
+└── UserPreferences.md
+
+<skill-name>/                                      ← Skill at learning directory root
     ├── SkillPreferences.md
     ├── SkillConventions.md                  ← Preserved during edits
     ├── roadmap.md                          ← Will be updated
     ├── progress-index.md                   ← Must be preserved & updated
-    ├── runs/
+    ├── runs/                               ← Action logs
     │   └── YYYY-MM-DD-HHMMSS-roadmap-edit/
     │       ├── agent-log.md
     │       ├── research-changes.md         ← Research on requested changes
@@ -110,7 +111,7 @@ fi
 
 LEARNING_DIR=$(grep -o '"learningDirectory"[[:space:]]*:[[:space:]]*"[^"]*"' "$OMNILEARN_CONFIG" | sed 's/"learningDirectory"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
 OMNILEARN_DIR="$LEARNING_DIR/.omnilearn"
-SKILL_DIR="$OMNILEARN_DIR/<skill>"
+SKILL_DIR="$LEARNING_DIR/<skill>"
 ROADMAP="$SKILL_DIR/roadmap.md"
 RUNS_DIR="$SKILL_DIR/runs"
 TOPICS_DIR="$SKILL_DIR/topics"
@@ -142,7 +143,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
@@ -162,21 +163,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
@@ -444,9 +445,9 @@ Write to `$ARCHIVE_DIR/agent-log.md`:
 │  • Preserved: All progress data intact                            │
 │                                                                   │
 │  🔗 Previous version archived at:                                 │
-│     .omnilearn/{skill}/runs/{timestamp}-roadmap-edit/             │
+│     {SKILL_DIR}/runs/{timestamp}-roadmap-edit/                    │
 │                                                                   │
-│  📍 Updated roadmap: .omnilearn/{skill}/roadmap.md                │
+│  📍 Updated roadmap: {SKILL_DIR}/roadmap.md                       │
 │                                                                   │
 │  ┌─ Change Preview ──────────────────────────────────────────┐   │
 │  │ {brief summary of the most significant changes}            │   │
@@ -463,7 +464,7 @@ Write to `$ARCHIVE_DIR/agent-log.md`:
 
 ```bash
 if git rev-parse --git-dir > /dev/null 2>&1; then
-  git add "$OMNILEARN_DIR/"
+  git add "$LEARNING_DIR/"
   git commit -m "omnilearn: update roadmap for {skill}
 
 - {change summary}
@@ -502,8 +503,8 @@ If no git repo: same flow as `/omnilearn-roadmap` — ask if the user wants to i
 | User says "you deleted my progress!" | STOP. Restore from archive. The topics/ directory must be fully intact with git checkout. |
 | Change analysis conflicts with online research | Present both perspectives, ask user which to follow |
 | Progress markers accidentally changed | Restore from archived old roadmap |
-| topic-progress.md accidentally modified | Revert: `git checkout .omnilearn/{skill}/topics/{topic}/topic-progress.md` |
-| topics/ directory accidentally modified | Revert: `git checkout .omnilearn/{skill}/topics/` |
+| topic-progress.md accidentally modified | Revert: `git checkout {SKILL_DIR}/topics/{topic}/topic-progress.md` |
+| topics/ directory accidentally modified | Revert: `git checkout {SKILL_DIR}/topics/` |
 | Topic renamed but topic-progress.md path broken | Move directory back, use a symlink or alias instead |
 | User's requested change is too vague | Ask clarifying questions before proceeding |
 

package/commands/omnilearn-roadmap.md

@@ -1,5 +1,5 @@
 ---
-description: Create a comprehensive, real-world-ready learning roadmap for any skill or subject. Uses multi-agent research to design optimal learning paths with practical, hands-on focus. Stores structured output in .omnilearn/ for continuous learning.
+description: Create a comprehensive, real-world-ready learning roadmap for any skill or subject. Uses multi-agent research to design optimal learning paths with practical, hands-on focus. Stores structured output in the learning directory for continuous learning.
 ---
 
 # /omnilearn-roadmap — Create a Comprehensive Learning Roadmap
@@ -15,13 +15,14 @@ description: Create a comprehensive, real-world-ready learning roadmap for any s
 ## Directory Structure
 
 ```
-.omnilearn/
-├── UserPreferences.md                           ← Global user preferences (auto-read + updated)
-└── <skill-name>/                                 ← Normalized skill folder (e.g., "Rust", "Machine-Learning")
-    ├── SkillPreferences.md                       ← Per-skill learning preferences
-    ├── SkillConventions.md                       ← 🔑 Setup conventions: package manager, project structure, deps, testing (auto-learned)
-    ├── roadmap.md                                ← Master roadmap (the main deliverable)
-    ├── progress-index.md                         ← Progress log — index of all runs
+.omnilearn/                                        ← ONLY config and global preferences
+├── UserPreferences.md                            ← Global user preferences (auto-read + updated)
+
+<skill-name>/                                      ← Skills at LEARNING DIRECTORY ROOT
+├── SkillPreferences.md                           ← Per-skill learning preferences
+├── SkillConventions.md                           ← 🔑 Setup conventions: package manager, project structure, deps, testing (auto-learned)
+├── roadmap.md                                    ← Master roadmap (the main deliverable)
+├── progress-index.md                             ← Progress log — index of all runs
     ├── runs/                                     ← Research & execution logs
     │   └── YYYY-MM-DD-HHMMSS-roadmap-creation/
     │       ├── agent-log.md                      ← What this run did, decisions made
@@ -87,7 +88,10 @@ OMNILEARN_DIR="$LEARNING_DIR/.omnilearn"
 echo "Using learning directory: $LEARNING_DIR"
 ```
 
-All subsequent paths in this command use `$OMNILEARN_DIR` as the base.
+**Path convention:**
+- `$OMNILEARN_DIR` = `$LEARNING_DIR/.omnilearn/` — **ONLY** config + UserPreferences.md
+- `$SKILL_DIR` = `$LEARNING_DIR/<skill>/` — skill folders are at the learning directory ROOT
+- All cross-skill scans use `$LEARNING_DIR/*/` (excluding `.omnilearn`)
 
 ## Current Date Context (CRITICAL — Must Pass to ALL Subagents)
 
@@ -147,18 +151,18 @@ If the input is too vague (e.g., "I want to learn something"), ask for clarifica
 ### 0.2 Check Prerequisites
 
 ```bash
-SKILL_DIR="$OMNILEARN_DIR/<skill-name>"
+SKILL_DIR="$LEARNING_DIR/<skill-name>"
 RUNS_DIR="$SKILL_DIR/runs"
 TOPICS_DIR="$SKILL_DIR/topics"
 
 # Create base omnilearn dir if not exists
-mkdir -p "$OMNILEARN_DIR"
+mkdir -p "$SKILL_DIR"
 ```
 
 ### 0.3 Check for Existing Skill
 
 If `$SKILL_DIR` already has a `roadmap.md`, inform the user:
-> "A roadmap for **{skill}** already exists at `.omnilearn/{skill}/roadmap.md`. To revise it, use `/omnilearn-roadmap-edit`. To start learning, use `/omnilearn-start`."
+> "A roadmap for **{skill}** already exists at `{SKILL_DIR}/roadmap.md`. To revise it, use `/omnilearn-roadmap-edit`. To start learning, use `/omnilearn-start`."
 
 If the user wants to overwrite, note it and proceed (archive old roadmap to runs/ first).
 
@@ -182,9 +186,11 @@ Read `UserPreferences.md` if it exists. Key signals to extract:
 **This is mandatory.** Scan the learning directory for ALL existing skills the user has already learned or is learning:
 
 ```bash
-# List all existing skill directories inside .omnilearn/
-ls -d "$OMNILEARN_DIR"/*/ 2>/dev/null | while read dir; do
+# List all existing skill directories at learning root (NOT .omnilearn/)
+ls -d "$LEARNING_DIR"/*/ 2>/dev/null | while read dir; do
   skill_name=$(basename "$dir")
+  # Skip .omnilearn — it's config only
+  [ "$skill_name" = ".omnilearn" ] && continue
   # Read their progress to understand what the user already knows
   if [ -f "$dir/progress-index.md" ]; then
     echo "Existing skill: $skill_name — checking progress..."
@@ -535,7 +541,7 @@ Write to the agent log file documenting:
 │  ✅ Roadmap Created: {skill}                                      │
 ├──────────────────────────────────────────────────────────────────┤
 │                                                                   │
-│  📍 Location: .omnilearn/{skill}/roadmap.md                       │
+│  📍 Location: {SKILL_DIR}/roadmap.md                                │
 │                                                                   │
 │  📊 Roadmap Overview:                                             │
 │  • Foundation: {N} topics — build the fundamentals                │
@@ -582,7 +588,7 @@ fi
 
 If git repo exists:
 ```bash
-git add "$OMNILEARN_DIR/"
+git add "$LEARNING_DIR/"
 git commit -m "omnilearn: create learning roadmap for {skill}
 
 - Added master roadmap with foundation, core, advanced, and real-world topics
@@ -597,7 +603,7 @@ If no git repo exists, ask:
 If yes:
 ```bash
 git init
-git add "$OMNILEARN_DIR/"
+git add "$LEARNING_DIR/"
 git commit -m "omnilearn: initialize learning environment with {skill} roadmap"
 ```
 
@@ -613,7 +619,7 @@ Mark the task as complete. Update UserPreferences.md if new relevant information
 |-------|-------|-----------------|
 | Content research subagent completed | 1 | Block — must have research |
 | Learning path subagent completed | 1 | Block — must have research |
-| Cross-skill inventory scanned | 0 | Scan .omnilearn/ directories |
+| Cross-skill inventory scanned | 0 | Scan $LEARNING_DIR/*/ (skip .omnilearn) |
 | User level extracted from preferences | 0 | Infer from available signals |
 | Roadmap has 5+ substantive topics | 2 | Re-synthesize with fix |
 | Roadmap skips topics user already knows | 2 | Re-synthesize — remove redundant basics |

package/commands/omnilearn-start.md

@@ -27,12 +27,15 @@ The goal metric: **Can the user apply what they learned to real-world problems t
 ## Directory Structure
 
 ```
-.omnilearn/<skill>/
-├── roadmap.md
-├── SkillPreferences.md
-├── SkillConventions.md                  ← 🔑 Setup conventions: package manager, project structure, deps, testing preferences (auto-learned)
-├── progress-index.md                   ← Overview index: links to topic-progress.md per topic
-├── runs/                                   ← Skill-level run logs (action logs only, NOT progress)
+{learningDirectory}/
+├── .omnilearn/                              ← Config only (config.json, UserPreferences.md)
+│
+└── <skill>/                                  ← Skills at learning root
+    ├── roadmap.md
+    ├── SkillPreferences.md
+    ├── SkillConventions.md                  ← 🔑 Setup conventions: package manager, project structure, deps, testing (auto-learned)
+    ├── progress-index.md                   ← Overview index: links to topic-progress.md per topic
+    ├── runs/                                   ← Skill-level run logs (action logs only, NOT progress)
 │   └── YYYY-MM-DD-HHMMSS-learning-<topic>/
 │       ├── agent-log.md                    ← What happened this run: decisions, actions taken
 │       ├── interaction-1.md                ← User Q&A interaction record
@@ -127,7 +130,7 @@ fi
 
 LEARNING_DIR=$(grep -o '"learningDirectory"[[:space:]]*:[[:space:]]*"[^"]*"' "$OMNILEARN_CONFIG" | sed 's/"learningDirectory"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
 OMNILEARN_DIR="$LEARNING_DIR/.omnilearn"
-SKILL_DIR="$OMNILEARN_DIR/<skill>"
+SKILL_DIR="$LEARNING_DIR/<skill>"
 ROADMAP="$SKILL_DIR/roadmap.md"
 PROGRESS_INDEX="$SKILL_DIR/progress-index.md"
 TOPICS_DIR="$SKILL_DIR/topics"
@@ -158,8 +161,9 @@ Read these files to understand the current state:
 
 **Cross-skill inventory** — Scan the learning directory for other skills the user has learned:
 ```bash
-ls -d "$OMNILEARN_DIR"/*/ 2>/dev/null | while read dir; do
+ls -d "$LEARNING_DIR"/*/ 2>/dev/null | while read dir; do
   skill_name=$(basename "$dir")
+  [ "$skill_name" = ".omnilearn" ] && continue
   if [ "$skill_name" != "$SKILL_NAME" ] && [ -f "$dir/progress-index.md" ]; then
     echo "Related skill: $skill_name — can integrate with $SKILL_NAME"
   fi
@@ -247,8 +251,8 @@ 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:
@@ -314,7 +318,7 @@ 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 create 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 use any external packages that aren't standard library without noting it
@@ -359,7 +363,7 @@ Read the assignment files for the current topic:
 │  {brief description of the assignment}                           │
 │                                                                   │
 │  Files:                                                           │
-│  • Question: .omnilearn/{skill}/topics/{topic}/assignments/      │
+│  • Question: {SKILL_DIR}/topics/{topic}/assignments/             │
 │              01-{name}/question.md                                │
 │  • Scaffold: (same directory)/scaffold/                           │
 │  • Test: (same directory)/test.{ext}                              │
@@ -543,10 +547,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}/
    
@@ -593,7 +598,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).
@@ -699,7 +704,7 @@ Write to `$CURRENT_RUN/agent-log.md`:
 
 ```bash
 if git rev-parse --git-dir > /dev/null 2>&1; then
-  git add "$OMNILEARN_DIR/"
+  git add "$LEARNING_DIR/"
   git commit -m "omnilearn: learning session — {skill}/{topic}
 
 - Completed assignment(s): {list}
@@ -773,7 +778,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.3",
+  "version": "1.0.5",
   "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",