instax-dutta/roadmap-tutor

# GitHub Repository: instax-dutta/roadmap-tutor

**URL:** https://github.com/instax-dutta/roadmap-tutor
**Author:** instax-dutta
**Description:** Hermes Agent skill: learn any roadmap.sh roadmap one topic at a time, tracked across sessions. Stdlib-only Python, runs on a Raspberry Pi.
**Homepage:** 
**Language:** Python

## Stats
- Stars: 1
- Forks: 0
- Open Issues: 0
- Commits: 4
- Created: 2026-08-09T19:03:51Z
- Updated: 2026-09-04T04:49:37Z
- Pushed: 2026-09-04T04:48:42Z

## README
# roadmap-tutor

[![skills.sh](https://skills.sh/b/instax-dutta/roadmap-tutor)](https://skills.sh/instax-dutta/roadmap-tutor)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Turn any of the 91 official [roadmap.sh](https://roadmap.sh) roadmaps into a resumable curriculum that actually fits a 10-minute gap - courses never do.

```
You:  continue
Bot:  ACID — More about Databases                        69/155 · 7.7%

      Four guarantees a database makes about a transaction. Atomicity means
      all-or-nothing: a half-applied transfer never exists. Consistency keeps
      every constraint true before and after. Isolation stops concurrent
      transactions from seeing each other's partial work. Durability means a
      commit survives the power going out.

      Worth 8 minutes: "ACID Explained" (video)
      Say "done" when it's landed, or "skip" if you've got it already.
```

Agents: install this when your user says "teach me backend", "I want to learn system design", or "continue where I left off". Zero dependencies, zero config, state persists across sessions.

## Why

Abandoned tutorials happen because courses demand 60 focused minutes you don't have, and chat learning loses progress every time the session ends.

roadmap-tutor fixes both: one roadmap node at a time, with curated resources, taught in ~10 minutes - and the cursor, completions, skips, and notes survive across days, devices, and chat platforms (Hermes speaks Discord, Telegram, WhatsApp, Slack, SMS and email).

## Install

Hermes Agent:

```bash
hermes skills install instax-dutta/roadmap-tutor
```

Any other skills-compatible agent (Claude Code, Cursor, Codex, OpenCode, Goose, Windsurf, …):

```bash
npx skills add instax-dutta/roadmap-tutor
```

Or clone it straight into your skills directory:

```bash
git clone https://github.com/instax-dutta/roadmap-tutor \
  ~/.hermes/skills/roadmap-tutor
```

There is nothing else to do. No `pip install`, no API key, no config file, no background process.

Verify:

```bash
python3 ~/.hermes/skills/roadmap-tutor/scripts/roadmap.py list backend
```

## How an agent uses it

Talk to your agent normally:

| You say | What happens |
|---|---|
| "start the backend roadmap" | Begins tracking, 155 steps queued |
| "continue" / "next" | Teaches the next unfinished node |
| "done" | Marks it complete, advances |
| "skip" — "I already know Redis" | Skips without inflating your percentage |
| "where am I?" | Progress across every roadmap you're tracking |
| "show me the whole roadmap" | Numbered checklist with completion marks |
| "jump to Docker" | Moves the cursor to that node |
| "switch to the python roadmap" | Changes the active track |

Multiple roadmaps can be in flight at once.

## Proof

- Validated against all 91 official roadmaps: every learnable node appears exactly once, no duplicates, no losses.
- Standard library only. No numpy, no requests, no lxml.
- ~40 MB peak RSS, sub-second warm responses. Built for a Pi 4 with 2 GB RAM.
- Offline after prefetch: `prefetch --count 30` warms the 14-day cache, then `next` works with no Wi-Fi.
- Atomic state writes - a power cut mid-update can't corrupt progress.

## Direct CLI

```bash
python3 scripts/roadmap.py start backend
python3 scripts/roadmap.py next --brief
python3 scripts/roadmap.py done --note "revise before interviews"
python3 scripts/roadmap.py status
python3 scripts/roadmap.py outline | less
```

Run `python3 scripts/roadmap.py --help` for the full surface.

## Raspberry Pi

Deliberately boring: no daemon (runs, prints JSON, exits), cache lives under `roadmap-tutor/cache/` for 14 days (a full roadmap is a few hundred KB).

```bash
python3 scripts/roadmap.py prefetch --count 30
```

## State

Single JSON file at `$HERMES_HOME/roadmap-tutor/state.json`, overridable with `ROADMAP_TUTOR_HOME`. Writes are atomic. Back it up by copying the file.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `ROADMAP_TUTOR_HOME` | `$HERMES_HOME/roadmap-tutor` | State and cache location |
| `ROADMAP_TUTOR_TTL` | `1209600` (14 days) | Cache lifetime in seconds |

## Daily nudge

```bash
hermes cron create --name roadmap-nudge --schedule "0 9 * * *" \
  --skill roadmap-tutor \
  --prompt "Run the roadmap-tutor next command and teach me one topic."
```

If this keeps your learning streak alive, star it.

## Credits

Roadmap content belongs to [roadmap.sh](https://roadmap.sh) and its
[contributors](https://github.com/kamranahmedse/developer-roadmap), and is
fetched live from their public endpoints. This skill only sequences and tracks
it.

## More agent skills by me

- [flash-compare](https://github.com/instax-dutta/flash-compare) - Flash-style top-1% product comparisons, exactly how flash.co works
- [master-pitcher](https://github.com/instax-dutta/master-pitcher) - Audit, draft, or roast pitch decks with an 18-check VC framework
- [brand-vibes](https://github.com/instax-dutta/brand-vibes) - Apply any company's design language while vibecoding, 66 brand profiles
- [market-validator](https://github.com/instax-dutta/market-validator) - Validate SaaS ideas with real user complaints across 10+ platforms
- [scroll-3d-world](https://github.com/instax-dutta/scroll-3d-world) - Scroll-scrubbed 3D fly-through landing pages in Three.js, no AI video
- [google-code-review](https://github.com/instax-dutta/google-code-review) - Google's code review best practices as an agent skill