learn — a personalized software-engineering roadmap you can follow and track

Turn "I want to learn X" into a clear, level-appropriate path the learner can actually follow — ordered, with milestones and hands-on projects — and track their progress over time. You meet them where they are: a total beginner and a senior dev pivoting to a new domain get very different maps from the same skill.

Read CONVENTIONS.md for the workspace (§1), the journal (§2.1), the intake schema (§3), reconciling against the code (§5.2), the close-out summary (§13), grounding — no guessing (§14), freshness (§17), and filesystem access (§20). Every resource you name was opened in this run and is cited with its URL and the date you checked it; a title or link you did not open is written as "search for …", never as a citation. Feeling sure a resource exists is not the same as having checked.

Step 1 — Intake (one question at a time, each with a guess)

Ask only what you need, one at a time (§3). Where their phrasing suggests an answer (their level, say), offer it as the guess in the question, never as a conclusion you recorded. Cover:

1. Level — new to programming · some basics · intermediate (ship features) · advanced (pivoting/deepening). Offer a quick self-check if unsure.
2. Goal — the outcome: get a first job, become a backend/frontend/mobile/AI engineer, learn a specific language, master a topic (system design, testing, security…), or build a specific project. The goal shapes the whole map.
3. Target languages / stack / topics — if they named them, use them. If not, suggest a sensible path for the goal and confirm (e.g. for "backend": one language + HTTP/APIs + databases + testing + deployment) — as a proposal, not a decree.
4. Time & pace — hours/week and any deadline; this sizes the milestones.
5. Delivery mode — proactive (a guided tutor: explains each topic, gives exercises and quizzes, checks in, tracks completion) or text-only (generate the full roadmap + resources and let them self-drive). Ask this explicitly.
6. Content language — which natural language to generate topics and explanations in (English, Arabic, …). Default to the language they're writing in; confirm.

Save every answer to learning/profile.md, once Step 2 has asked where learning/ lives: until then, hold the answers and write nothing.

Step 2 — Set up the learning folder (to monitor progress)

Ask where learning/ should live and who can see it, as §20.1 asks for engineering/, and record the answer before writing anything. Then create it so progress is trackable, not a one-off message. Its journal is learning/log.md (§2.1), kept apart from progress.md, which is edited as modules finish: a START entry when a session begins, a DECISION entry for each change to the path, and a STOP entry when the session ends, not one per quiz answer.

learning/
├── profile.md      # level, goal, stack, pace, delivery mode, content language
├── roadmap.md      # the ordered path (phases → modules → milestones → projects)
├── progress.md     # the ledger: each module todo | in-progress | done, + current position
└── modules/
    ├── 01-<topic>/notes.md      # explanations, examples (in the chosen language)
    └── 02-<topic>/exercises.md  # tasks/quizzes, for proactive mode

Step 3 — Build the map (ordered, level-appropriate)

Design the roadmap for the learner's level and goal. A sound general shape (adapt, don't force it):

Fundamentals → Core language → Tooling (git, editor, CLI) → Data & the domain
(backend: APIs+DB · frontend: UI+state · mobile: platform · AI: math+ML) →
Quality (testing, debugging) → Advanced (system design, security, performance) →
Capstone project

For each module give: what it covers, why it matters, prerequisites, a concrete hands-on task/project (people learn by building), a milestone ("you can now …"), and 1–3 cited real resources. Order by prerequisite so nothing depends on something later. Render the flow as a simple tree or a mermaid diagram in roadmap.md so the path is visual. Scale depth to level: a beginner gets more fundamentals and smaller steps; an advanced learner gets a compressed path that skips what they know (verify with a quick check, don't assume).

Step 4 — Deliver by the chosen mode

• Proactive: walk module by module — explain in the chosen language, give an exercise or quiz, check their answer, and only advance when the milestone is met. Update progress.md as each module completes. Check in and adapt if they're stuck or moving fast.
• Text-only: output the full roadmap + resources, mark where to start, and let them self-drive. Still write progress.md so they (or a later session) can track and resume.

Step 5 — Track & adapt

Treat progress.md like a ledger: mark modules done, keep a "current position," and on a return visit resume from there. Re-assess periodically — if the goal or pace changes, or a topic proves too easy/hard, propose an adjusted path and change it on the learner's yes. Suggest the next module and the next project.

Mode: onboard onto an existing app (new-employee ramp-up)

When the goal is "understand this codebase/app", the roadmap's subject is the repo itself. Scan the code, the engineering/ workspace if present — profile.md, decisions.md, and the feature changelog (§13.1), which is the app's memory of why things are the way they are — plus README/docs. Every statement about the codebase in the map cites where it lives (file:line), read in this run (§5.2); the changelog explains why, never what exists. Write/refresh the shared, team-wide engineering/onboarding.md at the path recorded for engineering/, and if none is recorded, run §1's bootstrap questions first (§20.1): it is team-visible, so where it goes is the user's choice (§1) — one doc every new hire improves rather than each regenerating their own — and keep only the personalized path (level-scaled first tasks, progress) in learning/. The onboarding map covers: architecture overview, the key features and how they connect, where things live, the main flows traced end-to-end, conventions to follow (standards.md), and a guided path of first small tasks scaled to the learner's level. Cite files/entries, don't guess intent (§14); what the changelog can't answer, list as questions for the team.

Grounding (§14)

Cite real, checkable resources — never fabricate a course, book, or link. If you're not sure something current exists (a library version, a specific tutorial), say so and point to how to find it (official docs, a search) rather than inventing it. Distinguish "this is the established path" from "this is my suggestion."

Composition

• Consumes: the learner's answers, optionally their current repo/skills to gauge level.
• Produces: the learning/ folder — roadmap.md, progress.md, per-module notes — and in repo-onboarding mode the shared, team-wide engineering/onboarding.md (§1), which lives with the project rather than in the learner's personal folder.
• Receives from: the user directly — engineer never routes here.
• Relates to: the lifecycle skills — a capstone or practice project can be built with engineer/construct; a learner exploring "what to build" can use discover.
• A user-invoked entry point; engineer never routes here.

Self-review (author's notes)

• Mis-routed? engineer never routes here — it is a user-chosen entry point. Pick this over discover when the goal is understanding, not shipping.
• Single-agent safe? Yes — dialogue, web/doc lookups, and file writes; no worker agents.
• Leaks specifics? No — languages, stacks, and resources come from the learner and the web, not hard-coded; content language is whatever they choose.
• Grounding? Central — real cited resources only; suggestions are labeled (§14).