ai-workflow-course/handoff.md

# 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
  <agent-config>       # 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.