omnilearn-workflow 1.0.8 → 1.0.10

package/commands/omnilearn-start.md

@@ -265,10 +265,11 @@ task(category="deep", run_in_background=false, timeout=600000, prompt="
    
    ### 2. ...
    
-   ## Assignment Structure
-   - 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
+   ## Assignment Structure (Adaptive — Determined During Learning)
+   - **Assignments are NOT pre-defined.** They are generated on-demand based on the user's performance, ZPD, and pace.
+   - The general trajectory is: Baseline → Stretch → Real-World, but the number of assignments and their specific difficulty is determined adaptively.
+   - If the user breezes through, they get fewer, harder assignments. If they struggle, they get more scaffolding and intermediate bridging exercises.
+   - The final assignment will be a real-world scenario that integrates this topic with other skills the user knows.
    
    STEP 3 — Create topic-explanation.md at:
      {TOPICS_DIR}/{topic}/topic-explanation.md
@@ -334,18 +335,69 @@ task(category="deep", run_in_background=false, timeout=600000, prompt="
      - Use the simplest possible test setup
    
    c) scaffold/ directory with starter files:
-     - Minimal code structure to get started
-     - Comments marking where to write code // TODO: or # TODO:
-     - Import/require statements already in place
-     - Can be empty scaffold if topic is conceptual
-   
-   d) solution-guide.md:
-     - Complete reference solution (code)
-     - Explanation of the solution approach
-     - Why certain choices were made
-     - Alternative approaches
-     - Common mistakes and how to avoid them
-     - Real-world connections
+   
+      GOLDEN RULE: The user must be able to go from `cd scaffold/` to `running the test` in ONE command.
+      If the assignment isn't testing setup/environment skills, automate ALL of that.
+   
+      - Include a setup script (`setup.sh` for Unix, `setup.ps1` for Windows) that:
+        * Creates virtual environment (Python: `python -m venv .venv`), or installs deps (Node: `npm install`)
+        * Installs required packages
+        * Prints "Environment ready! Run this command to start: ..."
+      - OR include a one-liner in the scaffold README: `python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt`
+      - Include `requirements.txt` / `package.json` with ALL needed deps pre-listed
+      - Minimal code structure — only the files the user needs to touch
+      - Comments marking where to write code // TODO: or # TODO:
+      - Import/require statements already in place
+      - Cross-skill integration: if the user knows {related_skill}, structure the scaffold to use familiar patterns from it
+      - If the topic is NOT a programming topic (e.g., system design), provide templates or worksheets instead
+   
+      ANNOYING THINGS TO NEVER DO:
+      - Do NOT make the user manually create a venv or install packages unless the assignment is specifically about that
+      - Do NOT leave unlisted imports — if a package is needed, it must be in requirements.txt / package.json
+      - Do NOT require the user to set up databases, API keys, or external services without providing clear instructions or a docker-compose.yml
+      - Do NOT leave configuration files empty or incomplete — provide working defaults
+      - Do NOT make the user hunt for the right Python/Node version — specify it in the scaffold or use `.nvmrc`/`.python-version`
+   
+   d) solution-guide.md — CRITICAL: Must be researched, accurate, and complete.
+   
+      BEFORE writing the solution:
+      1. Use google_search / context7_query-docs to research the CORRECT approach for this specific problem.
+      2. Verify your solution compiles/runs correctly — test it mentally or note any assumptions.
+      3. Cross-reference with topic-explanation.md to ensure consistency.
+      4. If the topic involves a library/framework, check official docs via context7 to confirm API accuracy.
+      
+      The solution-guide.md must have this structure:
+      
+      ## Solution Overview
+      - What approach was taken and why (1 paragraph)
+      - Key decisions made and the tradeoffs considered
+      
+      ## Complete Solution
+      ```{language}
+      # The full, working solution code
+      # Each section commented with WHY, not just WHAT
+      ```
+      
+      ## Step-by-Step Explanation
+      - Break the solution into logical steps
+      - For each step: what it does, why it's done this way, what would happen if you did it differently
+      - Reference the topic-explanation.md concepts being applied
+      
+      ## Edge Cases Handled
+      - List edge cases the solution handles
+      - What would break if not handled
+      
+      ## Alternative Approaches
+      - At least one alternative solution approach
+      - Why the main approach was chosen over alternatives
+      
+      ## Common Mistakes
+      - 3-5 specific mistakes learners make on this type of problem
+      - How to identify and fix each one
+      
+      ## Real-World Notes
+      - How this solution would differ in a production codebase
+      - Performance, security, or maintainability considerations
    
 STEP 5 — Create topic-progress.md at:
    {TOPICS_DIR}/{topic}/topic-progress.md
@@ -382,6 +434,8 @@ STEP 5 — Create topic-progress.md at:
    - 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
+   - **Do NOT write solutions without researching first** — use google_search or context7 to verify API syntax, library behavior, and best practices before writing solution-guide.md
+   - **Do NOT guess** — if you're unsure how a library function works, look it up via context7. Guesses lead to inaccurate solutions.
 
 6. CONTEXT:
    - Skill: {skill}
@@ -390,6 +444,7 @@ STEP 5 — Create topic-progress.md at:
    - User experience level: {from preferences}
    - User learning style: {from preferences}
    - Skill conventions (package manager, project structure, deps, testing setup): {from SkillConventions.md — read before generating scaffold}
+   - Cross-skill context (other skills user knows, so scaffold can use familiar patterns): {from cross-skill inventory}
 ")
 ```
 
@@ -399,9 +454,28 @@ After completion, verify:
 - Assignment 1 exists with all 4 files (question.md, test, scaffold, solution-guide.md)
 - Test script is syntactically valid (run a quick check)
 
-If anything is missing, fix via session continuation: `task(task_id="<session_id>", prompt="Fix: {missing element}")`
+If anything is missing, fix via session continuation: `task(task_id="<session_id>", prompt="Fix: {missing element}")"
+
+## Phase 1.5: READINESS GATE — Teach Before Test
+
+**The user MUST read the theory before touching assignments.** This is non-negotiable.
+
+1. Present the topic-explanation.md to the user:
+> "Before we jump into coding, let's cover the concepts you need.
+>
+> 📖 **{SKILL_DIR}/topics/{topic}/topic-explanation.md**
+>
+> This covers: TL;DR → Core Concepts → Examples → Pitfalls → Best Practices
+> It should take about 5-10 minutes to read.
+>
+> Let me know when you've finished reading, or ask me questions about anything that's unclear."
+
+2. **Wait for the user to confirm they've read it.** Do NOT skip this step.
+   - If they ask questions → answer them (using diagnostic task pattern from Phase 3 if needed)
+   - If they say "I already know this" → ask 2 quick concept-checking questions to verify. If they pass, skip. If they fail, tell them to read it.
+   - If they say "ready" → proceed.
 
-**Then proceed to Phase 2.**
+3. **Only after confirmation** → proceed to Phase 2.
 
 ## Phase 2: ASSIGNMENT PRESENTATION
 
@@ -650,30 +724,73 @@ task(category="unspecified-high", run_in_background=false, timeout=300000, promp
      - Self-contained and runnable
    
    c) scaffold/ — Starter code:
-     - Minimal boilerplate
-     - TODO markers for user implementation
-     - All necessary imports/includes set up
    
-   d) solution-guide.md:
-     - Complete solution
-     - Explanation of approach
-     - Alternative solutions' discussion
-     - Real-world production considerations
-     - Common mistakes
-
-5. MUST NOT DO:
+      GOLDEN RULE: The user must go from `cd scaffold/` to running tests in ONE command.
+      
+      - Include setup script (`setup.sh` + `setup.ps1`) that auto-creates env + installs deps
+      - OR one-liner setup instructions in a README
+      - `requirements.txt` / `package.json` with ALL deps pre-listed
+      - Minimal boilerplate — only what the user needs to touch
+      - TODO markers for user implementation
+      - All necessary imports/includes set up
+      - If the user knows {related_skill} from SkillConventions.md, use familiar patterns
+      - Auto-setup: `python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt`
+      - NEVER make the user manually install packages (unless assignment tests that skill)
+   
+   d) solution-guide.md — CRITICAL: Must be researched and accurate.
+   
+      BEFORE writing:
+      1. Use google_search / context7_query-docs to research the correct approach.
+      2. Verify the solution works — test mentally or note assumptions.
+      3. Cross-reference with previous solution-guide.md files to maintain consistency.
+      
+      Structure:
+      
+      ## Solution Overview
+      - Approach taken, key decisions, tradeoffs
+      
+      ## Complete Solution
+      ```{language}
+      # Full working code with WHY comments, not just WHAT
+      ```
+      
+      ## Step-by-Step Explanation
+      - Logical steps with reasoning for each
+      - What changes at this difficulty level vs previous assignments
+      
+      ## Edge Cases Handled
+      - What was considered and why
+      
+      ## Alternative Approaches
+      - Other valid solutions and when to use them
+      
+      ## Common Mistakes
+      - Specific errors learners make at this difficulty level
+      
+      ## Production Notes
+      - How this scales, performs, or differs in real codebases
+
+5. MUST DO (research before generation):
+   - **Research FIRST** — Use context7 or google_search to verify your solution approach before writing
+   - **Cross-reference** with topic-explanation.md and prior solution-guide.md files
+   - **Verify accuracy** — If you're unsure about API syntax or behavior, look it up. Do not guess.
+   
+6. MUST NOT DO:
    - Do NOT make the next assignment a repetition of the previous one
    - Do NOT skip difficulty progression
+   - Do NOT write solutions without researching first
    - Do NOT use external non-standard dependencies without noting it in scaffold setup
+   - Do NOT guess API signatures — use context7 to verify
 
 6. CONTEXT:
    - Skill: {skill}
    - Topic: {topic}
-   - Assignment number: {n}/3
-   - Difficulty: {basic/intermediate/real-world}
+   - Assignment number: {n}
+   - Difficulty: {current difficulty level}
    - Previous assignment concepts: {summary}
    - User performance on previous assignment: {observations}
    - Skill conventions (package manager, project structure, deps, testing setup): {from SkillConventions.md — MUST follow these when generating scaffold}
+   - Cross-skill context (other skills the user knows): {from cross-skill inventory — integrate these patterns into the scaffold if relevant}
 ")
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omnilearn-workflow",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "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",