EduOrchestrate Documentation

EduOrchestrate is a universal /eduorchestrate agent skill and daily learning orchestrator for job-role learners. A single NPX command installs agent adapters, captures the learner profile, generates a 30-day-minimum plan, prepares daily email delivery, and creates a GitHub Actions runner for autonomous daily plans.

It is a vendor-neutral learning coach: it works inside Claude Code, Codex, Gemini, OpenClaw, Antigravity, Hermas, generic coding agents, and any MCP-capable runtime. The system is not a motivational chatbot — it is a training orchestrator that protects learner focus and converts learning into job-role evidence.

Everything runs locally. Plans, research digests, progress logs, and cards are written to data/ in your repo; SMTP credentials live in .env.local or GitHub Actions secrets, never in committed config.

Quickstart

From an agent terminal in a cloned repo, run the one-command setup:

$ npx eduorchestrate

Onboarding asks for: name, email, target role, what you are currently studying, the first skill you want to focus on, current stage, weekly hours, plan length in days, daily email time, timezone, and SMTP settings. It then writes everything in one pass:

• eduorchestrate.config.json — learner profile, schedule, and email config
• Agent adapters for all seven supported runtimes
• data/30-day-plan.json — the first adaptive plan
• data/eduorchestrate-harness.json and .md — the execution harness
• data/learning-sources.json and .md — role-specific course catalogs
• The first research digest and the default terminal card
• .github/workflows/eduorchestrate-daily.yml — the scheduled delivery runner
• .env.local with your SMTP values, and a .gitignore entry for data/

Non-interactive setup is supported for automation:

$ npx eduorchestrate --yes --name "Ada" --email "ada@example.com" \
    --role "Agentic AI and LLM Engineer" --skill "RAG evaluation" --days 45

Then preview your first daily email:

$ npx eduorchestrate send-today --dry-run

Core concepts

The operating loop

EduOrchestrate runs the learner through one loop: define the role outcome, identify the smallest useful skill gap, choose current sources when freshness matters, build a small artifact, log evidence, then review and adjust the next day. Each plan day is capped at one core topic, one build artifact, and one review loop.

The 30-day minimum

Plan length is learner-chosen but never below 30 days. If you request fewer, 30 days are generated anyway. If you request more, the plan is extended with next-skill ramp and trend-refresh days. Good plans are organized around capability and proof — not course lists.

The execution harness

npx eduorchestrate harness writes a compact contract that keeps agent runs token-conscious. Agents load data/eduorchestrate-harness.json before broader docs, load only the active plan day unless asked for a full review, call CLI programs for stateful work instead of recreating outputs, and never paste SMTP secrets or SVG card source into chat.

Specialist agents

The skill treats the system as a typed multi-agent workflow, even when a single model executes it:

Research rules

Every research update must include a source title, URL, access or publication date, why it matters to the target role, and one concrete practice task. The roadmap only changes when an update improves employability, project quality, interview readiness, or safety — never because a technology is trendy.

Daily workflow

A typical day with EduOrchestrate, end to end:

$ npx eduorchestrate harness
$ npx eduorchestrate status
$ npx eduorchestrate research --day 8
$ npx eduorchestrate send-today --dry-run
$ npx eduorchestrate log-progress --day 8 --completed "Built RAG eval harness" \
    --evidence "github.com/me/rag-evals" --minutes 90 --confidence 4
$ npx eduorchestrate progress-card

1. Load the harness. First command of every agent run after initialization — it tells the agent what to load, when to research, and what not to paste into chat.
2. Resolve the day. status reports the active plan day, next action, and momentum.
3. Research when it matters. research writes a dated digest of official docs, YouTube search links, and GitHub sample-code search links to data/research-digests/.
4. Build the artifact. Each day defines one practical task, one proof target, review questions, and a next-day bridge.
5. Log evidence. log-progress captures the day, what was completed, evidence links, minutes, confidence, and blockers. Confidence and blockers decide whether to advance, repeat, or narrow.
6. Render proof. progress-card and terminal-card run the prebuilt renderer — agents never hand-author the card UI.

Each week, weekly-summary --week N rolls progress into data/weekly-summary-N.json. After the plan window, recommend-next suggests the next skill based on the current role and first-skill focus.

Role blueprints

Four blueprints ship built in. For any other role, the planner infers the closest blueprint and keeps the plan artifact-driven.

Course recommendations prefer official company catalogs, docs, academies, and free MNC/vendor sources, plus newsletters and update feeds. Marketplaces are avoided unless the learner explicitly asks. Daily emails keep it short: two course sources and two update feeds by default.

CLI reference

All commands run through npx eduorchestrate <command>. Running with no command (or /eduorchestrate) starts onboarding.

Agent integrations

Setup writes adapter files so common agents can expose or honor /eduorchestrate. Every adapter follows the same resume rule: on resume, load the harness or status, resolve today's plan day, and run send-today after SMTP setup — or send-today --dry-run and ask, when secrets or approval are missing.

The canonical universal skill lives at skills/eduorchestrate/SKILL.md, with exact agent contracts in references/agent-contracts.md and learning-loop policy in references/learning-system.md.

Email & scheduling

EduOrchestrate does not need a browser window or an agent session to stay open. Setup writes .github/workflows/eduorchestrate-daily.yml, which runs node bin/eduorchestrate.js send-today in GitHub Actions at your configured daily time using repository secrets.

How the scheduled day is computed

schedule.startDate is stored in eduorchestrate.config.json at setup. Scheduled runs advance the day from that date and skip sending after the plan window completes (with reason plan-complete) instead of repeating the same day forever.

SMTP configuration

Locally these live in .env.local. For Actions, setup-secrets prints the exact commands to run after gh auth login:

$ npx eduorchestrate setup-secrets
$ gh secret set SMTP_HOST --body "smtp.example.com"
$ gh secret set SMTP_PORT --body "465"
$ gh secret set SMTP_USER --body "you@example.com"
$ gh secret set SMTP_PASS
$ gh secret set SMTP_FROM --body "you@example.com"

Data & state

All local state is written to data/ by default and ignored by git.

Architecture

The CLI is dependency-free Node under src/: planner.js (plans and daily emails), harness.js (execution harness), courses.js (source packs), research.js (digests), progress.js (logs, status, summaries), card-components.js + progression-card.js (compact SVG component renderer), adapters.js (adapter generator), workflow.js (Actions workflow generator), and email.js (SMTP mailer). Regression tests live in tests/node/ and run with npm test.

Troubleshooting

Start with the built-in diagnostic:

$ npx eduorchestrate doctor

doctor reports ready or needs-setup after checking: package.json, the canonical skill, AGENTS.md, GEMINI.md, the Claude Code skill, the MCP manifest, eduorchestrate.config.json, and .env.local.

License & contributing

EduOrchestrate is MIT-licensed, open source, and free forever. The package ships with zero runtime dependencies and requires Node 18 or newer.

$ git clone https://github.com/haroontrailblazer/EduOrchestrate
$ cd EduOrchestrate
$ npm test

Bug reports and contributions are welcome on GitHub Issues. The npm package is published as eduorchestrate.