# Handoff — Building Out "The Workflow" This is a build-context note for a coding session (e.g. Claude Code) that will turn the course plan into actual lessons. **`syllabus.md` (sibling file) is the source of truth** for structure, module content, the thesis, and the dependency chain. Don't duplicate it here and don't re-derive decisions it already settled — read it first, then use this file for the *how* of building. **Status:** planning is complete (27 modules across 5 units + a capstone finale). No lesson content exists yet. The job is to produce the lessons and hands-on labs. --- ## What's already decided (don't re-litigate these) - **Model- and vendor-agnostic is a core promise.** Never pin a lesson to one LLM vendor, and don't hardcode a specific tool's config filename. Say "your agentic tool's committed instructions file," not a brand. Examples should survive a model swap. - **GitHub is the default, not the requirement.** Module 8 stays provider-neutral (GitHub as the titan; GitLab/Bitbucket/Azure DevOps/Codeberg/SourceHut and self-host options named). Earlier drafts leaned on Gitea specifically — that was deliberately removed. Don't reintroduce it. - **The Module 8 hosting comparison is intentionally NOT built yet.** It's marked a "planned artifact" because pricing/feature claims go stale. When you build it, verify current facts at that moment rather than writing from memory. - **The dependency chain is load-bearing.** Every module assumes only what precedes it. Don't reorder modules without re-checking the chain; if you think something should move, flag it instead of silently moving it. The syllabus's "Notes for the course owner" lists the moves already considered. - **Durable core (Modules 1–14) vs. expansion zone (15+).** The core should read as stable; the expansion zone is where fast-moving material lives and where you should flag things to re-verify. - **The capstone is a finale, not a numbered module.** Leave it that way unless the owner says otherwise. --- ## Recurring devices to keep consistent across every module These threads are what make it one course instead of 27 tutorials. Preserve them: - **The thesis** — the model is the cheap, swappable part; the workflow is the durable skill. Surface it periodically, and land it hard in Module 27 (evals as how you judge a model swap). - **The AI-specific angle** — every module in the syllabus has a reason it matters *specifically* for AI-assisted work (e.g. CI catches code that "looks right"; secrets module exists because AI hardcodes keys). Keep that angle front and center; it's the differentiator from a generic devops course. - **Honesty about limits** — the course repeatedly states where a tool or analogy breaks (Git isn't backup for your database; git only sees what's written to disk). This builds trust with the audience. Don't sand it off. - **The backup-and-recovery thread** spans Module 8 (backup/distribution) and Module 12 (recovery/restore). Keep both halves cross-referenced. - **Humans and agents are both "contributors."** The collaboration framing treats agents as teammates that need branches, review, and permissions. Carry that through. --- ## Audience and voice IT professionals who are fluent in an AI chat window and comfortable with ops concepts — **not beginners.** They respect rigor and detect fluff instantly. Lead with the copy-paste pain they already feel; reframe ops instincts they already have toward AI-assisted work; be direct and concrete. No padding, no motivational filler. When in doubt, show the command and the failure mode. --- ## Per-module lesson template Build every module to the same shape so the course feels coherent and so partial drafts are reviewable. Suggested structure for each `modules/NN-slug/README.md`: 1. **Title & one-line hook** — why this module exists for an IT pro (the pain or payoff). 2. **Prerequisites** — which prior modules it depends on (from the chain). 3. **Learning objectives** — 3–5, action verbs, what they can *do* afterward. 4. **Key concepts** — the actual teaching content, in prose with commands/snippets. 5. **The AI angle** — the module's AI-specific reason for existing (pull from the syllabus entry). 6. **Hands-on lab** — a practical exercise using AI *and* the tool together. This is a tools course; every module should end at a keyboard, not a quiz. Provide starter files where useful. 7. **Where it breaks** — limits, pitfalls, the honest caveat. 8. **Check for understanding** — a short self-check or "you're done when…" criterion. 9. **Verify-before-publish** — for fast-moving topics, a note on what to re-check at build time (versions, pricing, tool behavior). Before mass-producing, write **Modules 1–2 fully as the reference exemplars**, then pause for human review to lock tone, depth, and lab style. Cheaper to align on two than to redo twenty-seven. --- ## Suggested repo layout Markdown-first, which also lets the course repo model the practices it teaches (see "Dogfooding"). ``` the-workflow/ README.md # course overview, derived from syllabus front matter syllabus.md # source of truth (exists) handoff.md # this file # committed AI instructions file — dogfoods Module 5 (tool-agnostic name) modules/ 01-the-copy-paste-problem/ README.md # the lesson lab/ # exercise files, starter repo snapshots, etc. 02-version-control-as-a-safety-net/ ... capstone/ README.md assets/ # diagrams, images ``` Pick **one neutral example language** for labs (a small Python or Node app works) and state it once; the *concepts* stay language-agnostic but the labs need something concrete to run. --- ## Suggested build order 1. Scaffold the repo above; `git init`; commit the agent-config file (dogfooding starts immediately). 2. Write `_TEMPLATE.md` from the per-module structure. 3. Draft **Modules 1–2** as the exemplar pair → **pause for review** (two modules let the review judge consistency, not just a single sample). 4. Build the **durable core (Units 1–3, Modules 1–19)** in chain order. 5. Build the **expansion zone (Units 4–5, Modules 20–27)**, flagging fast-moving topics to verify. 6. Build the **Module 8 hosting comparison** with live verification of current facts. 7. Build the **capstone** last — it integrates everything, so it can't be written before the parts exist. --- ## Dogfooding (a nice-to-have that's on-thesis) The course is about version control, committing AI config, branches, PRs, and review. The course repo can *be* an example of all of it: commit the AI instructions file (Module 5), develop each module on a branch, open PRs, keep an honest history. If you want a recurring callback, the repo itself becomes the worked example students can inspect. --- ## Decisions settled by the owner (2026-06-22) These were the open questions; the owner has now ruled on them. Build to these; don't re-litigate. - **Delivery medium** — **written lessons + interactive labs** (hybrid). Each module is a written README *and* a real hands-on lab the learner runs at the keyboard, not a quiz. - **Hosting/platform** — **plain repo with an optional self-hosted-forge track.** GitHub stays the neutral default (per the syllabus); add a parallel self-host lab track for the air-gapped/on-prem audience. No LMS, no static-site build required. - **Lab environment** — **the learner's own machine, any OS.** Don't assume a provided sandbox or cloud environment. Provide starter files where useful; keep setup OS-agnostic. - **Lab language** — **pick per lab, leaning Python or shell.** (This relaxes the handoff's earlier "one neutral language stated once": prefer Python or shell, but use whatever fits a given lab.) - **Depth/length target per module** — **no fixed budget.** Let each module run as long as it needs; rely on the shared template (not a word count) for coherence. Lead the consistency check off the first two modules, not just one. - **Assessment / certification** — **self-checks only.** Each module ends at its "you're done when…" criterion; no graded work, no certification. - **Unit 4 scope** — **keep as one unit.** Leave Modules 20–23 together under the "extend the AI" theme; revisit only if a seam becomes obvious while building. - **Module 20–21 sequencing** — **keep MCP/skills at the back** so later units can build on them. The dependency chain stands as written. - **Capstone** — **stays a finale, not a numbered module** (27 + finale). - **Future Unit 6 (Adoption, Governance, Scale)** — **deferred.** Finish the 27 + capstone first; Unit 6 stays parked in the syllabus notes. --- ## Don't - Duplicate or fork `syllabus.md` — edit it in place if structure changes, and keep this file's cross-references in sync. - Reorder modules or break the dependency chain without flagging it. - Pin to a specific LLM vendor or a specific tool's config filename. - Write the hosting comparison (or any pricing/version claim) from memory — verify at build time. - Pad. This audience reads fast and trusts concrete over comprehensive.