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, written out 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 exhaustive.