omnilearn-workflow 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# OmniLearn Workflow
+
+**AI-powered adaptive learning workflows for [OpenCode](https://opencode.ai).** Uses multi-agent orchestration to create personalized learning roadmaps, generate hands-on assignments, and track progress across any skill.
+
+**GitHub:** https://github.com/BlackPool25/OmniLearn
+
+## Quick Start
+
+```bash
+# Install the workflow commands
+npx omnilearn-workflow
+
+# Open OpenCode
+opencode
+
+# Set up your learning directory
+/omnilearn-init
+
+# Create your first roadmap
+/omnilearn-roadmap I want to learn Rust
+```
+
+## Available Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/omnilearn-init` | Set up your learning directory and config |
+| `/omnilearn-roadmap` | Create a personalized, research-backed learning roadmap |
+| `/omnilearn-roadmap-edit` | Edit an existing roadmap without losing progress |
+| `/omnilearn-start` | Interactive learning: hands-on assignments, Q&A, progress tracking |
+| `/omnilearn-refine` | Deep-dive questions and subtopic refinements |
+
+## How It Works
+
+OmniLearn uses **multi-agent orchestration** (Sisyphus → subagents) to:
+
+1. **Research** — Parallel subagents use web search + Context7 to find everything needed for real-world proficiency
+2. **Adapt** — Scans your existing skills, reads your preferences, and skips what you already know
+3. **Integrate** — Combines skills you already have with new ones (e.g., Python + FastAPI = full-stack ML API)
+4. **Generate** — Creates hands-on assignments at 3 difficulty levels: Basic → Intermediate → Real-World
+5. **Track** — Every assignment completion and session is logged in `topic-progress.md`
+
+## Architecture
+
+```
+.omnilearn/                          ← In your configured learning directory
+├── UserPreferences.md               ← Global preferences (auto-learned)
+└── <skill>/
+    ├── roadmap.md                   ← Master roadmap
+    ├── SkillPreferences.md          ← Per-skill preferences
+    ├── progress-index.md            ← Overview index
+    ├── runs/                        ← Action logs only
+    └── topics/<topic>/
+        ├── topic-roadmap.md         ← Detailed subtopic plan
+        ├── topic-progress.md        ← 🔑 Progress lives here
+        ├── assignments/             ← Hands-on tasks with tests
+        └── runs/                    ← Session action logs
+```
+
+## Requirements
+
+- [OpenCode](https://opencode.ai) with [Oh-My-OpenAgent](https://github.com/code-yeongyu/oh-my-openagent) installed
+- Node.js >= 18
+
+## Configuration
+
+OmniLearn stores its config at `~/.config/opencode/omnilearn.json`:
+
+```json
+{
+  "learningDirectory": "/absolute/path/to/learning",
+  "setupDate": "2026-07-04",
+  "version": "1"
+}
+```
+
+Run `/omnilearn-init` in OpenCode to configure.
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+
+/**
+ * OmniLearn Workflow Installer
+ * 
+ * Installs OmniLearn commands into OpenCode's command directory
+ * so they're available as global /omnilearn-* commands.
+ * 
+ * GitHub: https://github.com/BlackPool25/OmniLearn
+ * 
+ * Usage:
+ *   npx omnilearn-workflow              # Interactive install
+ *   npx omnilearn-workflow --help       # Show help
+ *   npx omnilearn-workflow --yes        # Auto-install with defaults
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const PKG_DIR = path.resolve(__dirname, '..');
+const COMMANDS_DIR = path.join(PKG_DIR, 'commands');
+const OPENCODE_COMMAND_DIR = path.join(
+  process.env.HOME || process.env.USERPROFILE,
+  '.config',
+  'opencode',
+  'command'
+);
+
+const COMMANDS = [
+  'omnilearn-init.md',
+  'omnilearn-roadmap.md',
+  'omnilearn-roadmap-edit.md',
+  'omnilearn-start.md',
+  'omnilearn-refine.md',
+];
+
+function printBanner() {
+  console.log(`
+  ╔══════════════════════════════════════════════════╗
+  ║             OmniLearn Workflow Installer         ║
+  ║  AI-powered adaptive learning for OpenCode       ║
+  ╚══════════════════════════════════════════════════╝
+  `);
+}
+
+function printHelp() {
+  console.log(`
+  Usage:
+    npx omnilearn-workflow           Interactive install
+    npx omnilearn-workflow --yes     Auto-install with defaults
+    npx omnilearn-workflow --help    Show this help
+
+  What this installer does:
+    1. Copies 5 command files to ~/.config/opencode/command/
+    2. Makes them available as /omnilearn-* commands in OpenCode
+
+  After install, open OpenCode and run:
+    /omnilearn-init    — Set up your learning directory
+    /omnilearn-roadmap — Create your first roadmap
+  `);
+}
+
+function ask(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function install(autoYes = false) {
+  printBanner();
+
+  // Check if OpenCode command directory exists
+  if (!fs.existsSync(OPENCODE_COMMAND_DIR)) {
+    console.log(`  [✗] OpenCode command directory not found at:`);
+    console.log(`      ${OPENCODE_COMMAND_DIR}`);
+    console.log(``);
+    console.log(`  Make sure OpenCode is installed first:`);
+    console.log(`  https://opencode.ai`);
+    console.log(``);
+    process.exit(1);
+  }
+
+  console.log(`  OpenCode command directory: ${OPENCODE_COMMAND_DIR}`);
+  console.log(``);
+
+  // List existing omnilearn commands
+  const existing = fs.readdirSync(OPENCODE_COMMAND_DIR)
+    .filter(f => f.startsWith('omnilearn-') && f.endsWith('.md'));
+
+  if (existing.length > 0 && !autoYes) {
+    console.log(`  Found ${existing.length} existing OmniLearn command(s):`);
+    existing.forEach(f => console.log(`    • ${f}`));
+    console.log(``);
+    const answer = await ask('  Overwrite existing commands? [y/N] ');
+    if (answer.toLowerCase() !== 'y') {
+      console.log('  Skipping installation of command files.');
+      console.log('  Existing commands preserved.');
+      console.log('');
+      return await postInstall(autoYes);
+    }
+  }
+
+  // Copy command files
+  let copied = 0;
+  for (const cmd of COMMANDS) {
+    const src = path.join(COMMANDS_DIR, cmd);
+    const dest = path.join(OPENCODE_COMMAND_DIR, cmd);
+
+    if (!fs.existsSync(src)) {
+      console.log(`  [✗] Source not found: ${cmd}`);
+      continue;
+    }
+
+    try {
+      fs.copyFileSync(src, dest);
+      fs.chmodSync(dest, 0o644);
+      console.log(`  [✓] Installed: ${cmd}`);
+      copied++;
+    } catch (err) {
+      console.log(`  [✗] Failed to install ${cmd}: ${err.message}`);
+    }
+  }
+
+  console.log(``);
+  console.log(`  Installed ${copied}/${COMMANDS.length} command(s).`);
+  console.log(``);
+
+  return await postInstall(autoYes);
+}
+
+async function postInstall(autoYes) {
+  console.log(`  ┌──────────────────────────────────────────────────────────┐`);
+  console.log(`  │  ✅ OmniLearn commands installed!                        │`);
+  console.log(`  │                                                          │`);
+  console.log(`  │  Next steps:                                             │`);
+  console.log(`  │                                                          │`);
+  console.log(`  │  1. Open OpenCode in your learning project               │`);
+  console.log(`  │  2. Run:  /omnilearn-init                                │`);
+  console.log(`  │     (This sets up your learning directory)               │`);
+  console.log(`  │                                                          │`);
+  console.log(`  │  3. Run:  /omnilearn-roadmap I want to learn <skill>     │`);
+  console.log(`  │     (Creates your first learning roadmap)                │`);
+  console.log(`  │                                                          │`);
+  console.log(`  │  Available commands:                                     │`);
+  console.log(`  │  /omnilearn-init        — Configure learning directory   │`);
+  console.log(`  │  /omnilearn-roadmap     — Create a learning roadmap      │`);
+  console.log(`  │  /omnilearn-roadmap-edit— Edit an existing roadmap       │`);
+  console.log(`  │  /omnilearn-start       — Start learning a topic         │`);
+  console.log(`  │  /omnilearn-refine      — Refine a subtopic or ask Qs    │`);
+  console.log(`  └──────────────────────────────────────────────────────────┘`);
+  console.log(``);
+}
+
+// ─── CLI ───
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  printHelp();
+  process.exit(0);
+}
+
+const autoYes = args.includes('--yes') || args.includes('-y');
+
+install(autoYes).catch((err) => {
+  console.error('Installation failed:', err.message);
+  process.exit(1);
+});

package/commands/omnilearn-init.md

@@ -0,0 +1,203 @@
+---
+description: Initialize OmniLearn — set your learning directory, create the base structure, and configure global preferences. Run this before using any other omnilearn-* command.
+---
+
+# /omnilearn-init — Initialize OmniLearn Learning Environment
+
+## Usage
+```
+/omnilearn-init
+/omnilearn-init /absolute/path/to/learning/materials
+/omnilearn-init ./my-learning
+```
+
+## What This Does
+
+1. Checks if OmniLearn is already configured (reads `~/.config/opencode/omnilearn.json`)
+2. If not configured: asks the user where to store learning materials, saves config
+3. Creates the base `.omnilearn/` directory structure at the configured path
+4. Creates initial `UserPreferences.md` (empty — populated organically)
+5. Confirms setup is complete
+
+## Config File
+
+OmniLearn stores its configuration in `~/.config/opencode/omnilearn.json`:
+
+```json
+{
+  "learningDirectory": "/absolute/path/to/learning",
+  "setupDate": "2026-07-04",
+  "version": "1"
+}
+```
+
+This global location is always accessible regardless of which project directory you're in. All commands read this file at startup.
+
+## Directory Structure Created
+
+```
+{learningDirectory}/
+└── .omnilearn/
+    ├── config.json              ← Mirror of the global config (for reference)
+    └── UserPreferences.md       ← Global user preferences (auto-populated)
+```
+
+## Phase 0: CHECK EXISTING CONFIG
+
+### 0.1 Check if Already Configured
+
+```bash
+OMNILEARN_CONFIG="$HOME/.config/opencode/omnilearn.json"
+
+if [ -f "$OMNILEARN_CONFIG" ]; then
+  echo "OmniLearn is already configured."
+  LEARNING_DIR=$(jq -r '.learningDirectory' "$OMNILEARN_CONFIG")
+  echo "Learning directory: $LEARNING_DIR"
+  echo ""
+  echo "To change it, run: /omnilearn-init <new-path>"
+  echo "Or continue using the existing setup with any omnilearn-* command."
+  exit 0
+fi
+```
+
+If the user provided a path as an argument, use it directly (skip Phase 1).
+
+### 0.2 Read Argument (if provided)
+
+```bash
+if [ -n "$ARG1" ]; then
+  LEARNING_DIR=$(realpath "$ARG1" 2>/dev/null || echo "$ARG1")
+  # Proceed to Phase 2
+fi
+```
+
+## Phase 1: ASK USER FOR LEARNING DIRECTORY
+
+If no argument was provided and no config exists:
+
+> "Welcome to OmniLearn! 🎉
+>
+> I need a directory where all your learning materials will be stored.
+> This is where skill roadmaps, assignments, progress tracking, and run logs live.
+>
+> Where would you like to set up your learning directory?"
+>
+> Options:
+> 1. **Current directory** ({cwd}) — simplest, everything stays in this project
+> 2. **Home directory** (~/OmniLearn) — accessible from any project
+> 3. **Custom path** — you specify
+
+Use the `question` tool to present these options. For "Custom path", collect the user's typed path.
+
+```bash
+# Make the path absolute
+LEARNING_DIR=$(realpath "$LEARNING_DIR" 2>/dev/null || echo "$LEARNING_DIR")
+```
+
+## Phase 2: CREATE CONFIG & DIRECTORY STRUCTURE
+
+### 2.1 Save Global Config
+
+```bash
+mkdir -p "$HOME/.config/opencode"
+
+cat > "$OMNILEARN_CONFIG" << 'CONFIG'
+{
+  "learningDirectory": "LEARNING_DIR_PLACEHOLDER",
+  "setupDate": "DATE_PLACEHOLDER",
+  "version": "1"
+}
+CONFIG
+
+# Replace placeholders
+sed -i "s|LEARNING_DIR_PLACEHOLDER|$LEARNING_DIR|g" "$OMNILEARN_CONFIG"
+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
+OMNILEARN_DIR="$LEARNING_DIR/.omnilearn"
+mkdir -p "$OMNILEARN_DIR"
+
+# Create a local config mirror (for reference when browsing)
+cat > "$OMNILEARN_DIR/config.json" << 'CONFIG'
+{
+  "learningDirectory": "LEARNING_DIR_PLACEHOLDER",
+  "setupDate": "DATE_PLACEHOLDER",
+  "version": "1"
+}
+CONFIG
+sed -i "s|LEARNING_DIR_PLACEHOLDER|$LEARNING_DIR|g" "$OMNILEARN_DIR/config.json"
+sed -i "s|DATE_PLACEHOLDER|$(date +%Y-%m-%d)|g" "$OMNILEARN_DIR/config.json"
+```
+
+### 2.3 Create Initial UserPreferences.md
+
+```bash
+cat > "$OMNILEARN_DIR/UserPreferences.md" << 'EOF'
+# Global User Preferences
+
+_This file is auto-managed by OmniLearn. Preferences are learned organically from interactions — never from forms or questionnaires._
+
+## Learning Style
+<!-- Preferences about how the user learns best, inferred from behavior -->
+
+## Technical Background
+<!-- The user's demonstrated experience level, preferred tools, and known technologies -->
+
+## Goals
+<!-- Career, personal, or academic goals related to learning -->
+
+## Preference Log
+
+### {setupDate}: OmniLearn initialized
+- Learning directory set to: {learningDirectory}
+- OmniLearn v1 initialized
+- User preferences file created — will grow organically with use
+EOF
+```
+
+## Phase 3: CONFIRM SETUP
+
+```markdown
+┌──────────────────────────────────────────────────────────────────┐
+│  ✅ OmniLearn Initialized                                         │
+├──────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  Learning directory: {learningDirectory}                           │
+│  Config: {OMNILEARN_CONFIG}                                        │
+│                                                                   │
+│  All omnilearn-* commands are now ready to use:                   │
+│                                                                   │
+│  /omnilearn-roadmap <skill>      — Create a learning roadmap       │
+│  /omnilearn-roadmap-edit <skill> — Edit an existing roadmap        │
+│  /omnilearn-start <skill>        — Start learning                  │
+│  /omnilearn-refine <skill>       — Refine a subtopic               │
+│                                                                   │
+│  Get started:                                                      │
+│  /omnilearn-roadmap I want to learn Rust                          │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Quality Gates
+
+| Check | Phase | Action if Failed |
+|-------|-------|-----------------|
+| Config file written | 2 | Check permissions on ~/.config/opencode/ |
+| Learning directory exists | 2 | Create if not exists |
+| .omnilearn/ created inside learning directory | 2 | mkdir -p |
+| UserPreferences.md created | 2 | Write default template |
+| Config readable by shell | 2 | Test: `jq` or `grep` the file |
+| User confirmed the path is correct | 1 | Re-ask if wrong |
+
+## Error Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Config already exists | Show current config, exit |
+| User provides invalid path | Ask again with validation |
+| ~/.config/opencode/ not writable | Suggest `sudo` or manual setup |
+| jq not available | Use `grep` + `sed` to parse JSON instead |
+| User wants to change directory later | Re-run /omnilearn-init <new-path> |