Build out all 27 modules + capstone (#1)

Co-authored-by: claude <claude@jpaul.io>
Co-committed-by: claude <claude@jpaul.io>

the-workflow-syllabus.md

@@ -0,0 +1,293 @@
+# The Workflow
+### The Toolchain Around AI Coding
+
+A living course for IT professionals who are comfortable in an AI chat window and starting to
+build real software with it — but are still copy-pasting between the chat and their files. The
+goal is to replace that loop with durable engineering workflows: version control, collaboration,
+CI/CD, runners, and the tools that extend AI into real systems.
+
+**Thesis:** the model is the cheap, swappable part. The workflow around it is the skill that lasts.
+This course is deliberately model- and vendor-agnostic — whichever LLM you use, the scaffolding
+is the same.
+
+---
+
+## How this syllabus is built
+
+It's a dependency chain, not a topic list. Every module assumes only what the previous ones
+taught, and nothing references a tool before it's been introduced. The 27 modules group into
+five units:
+
+- **Unit 1 (1–7) — Get out of the chat window.** The local foundation: version control, committing
+  the AI's config, and getting the AI editing real files safely.
+- **Unit 2 (8–12) — Make it shareable, reviewable, recoverable.** The team layer: hosting, issues,
+  review, collaboration, and recovery.
+- **Unit 3 (13–19) — Automate the checking and shipping.** The pipeline: tests, CI, security
+  scanning, containers, secrets, delivery, and the compute behind it.
+- **Unit 4 (20–23) — Extend the AI into your systems.** The frontier: MCP, skills, securing them,
+  and working with existing codebases.
+- **Unit 5 (24–27) — AI in the loop.** Agents operating inside the pipeline, from assistive to
+  autonomous, plus the evals that make that trustworthy.
+- **Capstone** ties the whole motion together on one real feature.
+
+**Durable core vs. expansion zone.** Modules 1–14 are the stable foundation — version control,
+review, testing, and CI aren't going anywhere and should rarely change. From Module 15 onward —
+security scanning, the extend-the-AI unit, and all of Unit 5 — is the expansion zone, where a
+fast-moving space will keep handing you new lessons. Keeping the volatile material toward the back
+lets the front stay stable as the course grows.
+
+**The backup-and-recovery thread.** Version control as backup and recovery is woven across
+Module 8 (remotes give you the offsite, distributed copy — the *backup* half) and Module 12
+(commits give you point-in-time restore — the *recovery* half), with an honest accounting of where
+the analogy holds and where it breaks.
+
+---
+
+## Unit 1 — Get out of the chat window
+
+### Module 1 — The Copy-Paste Problem
+Orientation, not content. Diagnose the current state honestly: why pasting between a chat tab and a
+file falls apart the moment a project has more than one file or more than one day of history.
+Establish the course thesis and get everyone set up with a real local project, an editor, and a
+terminal.
+
+### Module 2 — Version Control as a Safety Net
+Git fundamentals framed for this audience as *undo for the AI*: `init`, `commit`, `diff`, `log`,
+`restore`. The reframe that lands: commits are checkpoints you can always return to when the AI
+confidently makes a mess — which is what makes everything riskier in later modules safe to attempt.
+
+A second reframe that matters just as much: the repo is *durable memory the AI can read*. An AI
+session is ephemeral — disconnect and the agent's working context is gone — but the changes on disk
+aren't. A fresh session can answer "where were we?" entirely from ground truth by reading git:
+`git status` shows what's changed but uncommitted (including new untracked files), `git diff` shows
+the actual line-level edits, `git log` shows what's already committed and settled, and
+`git log main..HEAD` plus the ahead/behind report in `git status` show how the branch compares to
+`main` and to the remote — covering the untracked, uncommitted, and not-yet-pushed states in one
+pass. The one limit to teach honestly: git only sees what was *written to disk*; anything the agent
+only reasoned about in context but never wrote is gone with the session. That's also the practical
+argument for committing often — the more granular the history, the cleaner the reconstruction.
+
+### Module 3 — Version Control for Words, Not Just Code
+The lowest-stakes place to practice Git, and a genuinely useful skill on its own. Editing a markdown
+doc with AI and committing it carries almost no risk, so it's the ideal first real application of
+branch / diff / commit / merge before the agent ever touches code. Covers why plain text wins:
+Git diffs are line-based, which is exactly why markdown and AsciiDoc version beautifully while
+`.docx` and `.pptx` version terribly (Git tracks them, but the diff is useless binary noise and
+merges are impossible). A real argument for moving runbooks, ADRs, and specs out of Word and into
+markdown. Doc types covered: READMEs, architecture decision records, runbooks, changelogs, specs/PRDs.
+The "aha": the wikis on most git hosts — GitHub, GitLab, Gitea, and others — are themselves just Git
+repos, so your wiki was version-controlled all along. AI angle: LLMs are native markdown writers, so
+"draft the ADR, branch it, review the diff, merge it" is adoptable tomorrow.
+
+### Module 4 — Getting the AI Out of the Browser
+The literal answer to Module 1: agentic, editor-integrated AI tools that operate on your files
+directly (kept tool- and model-agnostic). This works *because* of Module 2 — you let the AI edit
+real files only because you can now see and revert exactly what it did.
+
+### Module 5 — Commit the AI's Config, Not Just the Code
+The instructions you give the model are as worth versioning as the code it writes — and the thesis
+holds here too: the model is swappable, but *your* setup for it is a durable artifact. Most agentic
+coding tools read a committed, repo-level config or instructions file (kept tool-agnostic here — the
+principle outlives any one vendor's filename): project conventions, build and test commands, coding
+standards, "don't touch these files," and house style. Checking it into the repo means every
+teammate — and every automated agent that later operates on the repo — inherits the same setup
+instead of each person hand-tuning their own and quietly drifting apart. It also makes AI behavior
+*reviewable*: a change to how the AI works on this project arrives as a diff in a PR, like any other
+change. (Its full payoff lands once you have a shared remote in Module 8, but the habit starts now.)
+This is the lightweight foundation that Module 21, Skills, later builds into structured, reusable
+playbooks.
+
+### Module 6 — Branches: Sandboxes for Experiments
+Branching, merging, and resolving conflicts, positioned as isolation for AI experiments: spin up a
+branch, let the agent try something wild, throw it away or keep it with zero risk to working code.
+
+### Module 7 — Worktrees: Running Agents in Parallel
+Multiple working directories from one repo — genuinely powerful once you're running more than one
+AI session at a time and don't want them stepping on each other. The natural payoff of understanding
+branches.
+
+---
+
+## Unit 2 — Make it shareable, reviewable, recoverable
+
+### Module 8 — Remotes and Hosting: GitHub, the Alternatives, and Owning Your Repo
+Push, pull, and remotes — the mechanic that gets your history off your laptop and somewhere durable.
+A remote is just a remote, so this stays deliberately provider-neutral. GitHub is the titan and the
+default nearly everyone will encounter — the largest by far, and the one most AI tooling integrates
+with first — but it is one option among many. Hosted alternatives worth naming include GitLab,
+Bitbucket, Azure DevOps, Codeberg, and SourceHut. For teams that want control, on-prem, or
+air-gapped operation — a real concern for this audience — you can self-host an open-source forge
+instead: Forgejo, Gitea, GitLab CE, Gogs, and OneDev are all viable. (GitLab notably spans both
+camps — hosted SaaS and a self-hostable Community Edition.) **Planned artifact:** a side-by-side
+comparison — hosted vs. self-hosted, pricing, built-in CI/CD, AI-tooling integration, and ease of
+operation — to be built and verified when we develop this module, rather than baking in claims that
+age. **Backup thesis, part one:** a single local repo is *not* a backup — it's one disk away from
+total loss. Pushing to a remote gives you an offsite copy, and because every clone carries the full
+history, a working team accidentally implements something close to the 3-2-1 rule just by working
+normally. The *recovery* power comes from commits; the *backup* power comes from remotes and
+distribution.
+
+### Module 9 — Issues and the Task Layer
+The "sharing dev tasks with others" layer. Issues describe the work; assignment routes it. The twist
+that keeps it on-thesis: your assignees are increasingly a mix of humans and agents — an issue can
+go to a person *or* be handed to an issue-to-PR agent. Sets up the coordination loop completed in
+Module 11.
+
+### Module 10 — Reviewing Code You Didn't Write
+Pull/merge requests as a review gate, and the genuinely new skill of evaluating a diff the AI
+produced — reviewing for plausibility traps, not just correctness. One of the most important and
+least-taught skills in the whole space.
+
+### Module 11 — Collaboration: Humans and Agents on One Repo
+The full coordination loop now that issues (Module 9) and PRs (Module 10) both exist: issue → branch
+→ implementation → PR → review → merge → issue closed. Contributors, forks vs. branches, and who's
+allowed to push. The current-feeling angle: some of those "contributors" aren't human — a PR opened
+by an agent and reviewed by a human, or two agents in parallel who are just two contributors needing
+branches (which is why worktrees earned Module 7).
+
+### Module 12 — When It Goes Wrong: Revert, Reset, and Recovery
+Recovery as its own discipline, placed here because "revert a bad PR" only makes sense once PRs
+exist. `revert` cleanly undoes a change by writing a new commit (safe on shared history); `reset`
+rewrites history (dangerous once others have pulled); the reflog recovers work you thought you'd
+destroyed; tags and releases act as named recovery points. Reverting a bad merge is the headline
+example. **Backup thesis, part two — and its limits:** Git gives excellent point-in-time logical
+recovery for *versioned text*, but it is not backup for your database, your secrets (which shouldn't
+be there anyway — Module 17), your uncommitted changes, or large binaries. Teaching where the
+analogy breaks is what earns this audience's trust.
+
+---
+
+## Unit 3 — Automate the checking and shipping
+
+### Module 13 — Testing in the AI Era
+What a test is, why AI output specifically needs verification, and the happy fact that AI is
+excellent at writing tests once you know how to direct it. Tests are the content that the next
+module automates.
+
+### Module 14 — Continuous Integration
+Automated checks — lint, build, test — running on every push. The pitch writes itself: AI generates
+code that *looks* right, and CI is the tireless reviewer that catches when it isn't.
+
+### Module 15 — Security Scanning for AI-Generated Code
+AI introduces failure modes a build check won't catch: vulnerable dependencies, hardcoded secrets,
+and hallucinated packages that don't exist (a real supply-chain risk — attackers register the
+plausible-but-fake package names LLMs invent). Covers dependency/SCA scanning, secret scanning, and
+static analysis (SAST) as automated gates in the pipeline. Sequenced after CI because it's another
+gate on the same pushes, and after the secrets problem is on the table.
+
+### Module 16 — Containers and Reproducible Environments
+Docker and "works on my machine," solved — reproducibility so your code, your CI, and eventually
+your deployments run identically. Also the foundation for safely sandboxing agents you don't fully
+trust on your host.
+
+### Module 17 — Secrets, Config, and Environments
+Managing secrets and configuration across environments. Earns its own module partly because AI loves
+to hardcode an API key straight into a file — a concrete, recurring, AI-specific failure to defend
+against.
+
+### Module 18 — Continuous Delivery and Deployment
+Getting merged code to something running, automatically. Builds on containers (what you ship) and
+secrets (what it needs to run).
+
+### Module 19 — Runners: The Compute Behind the Automation
+What's actually executing all this CI/CD — hosted vs. self-hosted runners, and why you'd run your
+own. The IT-pro payoff: you've been using someone else's compute; now you own the pipeline end to
+end.
+
+---
+
+## Unit 4 — Extend the AI into your systems
+
+### Module 20 — MCP Servers: Giving the AI Hands
+The Model Context Protocol — connecting the AI to your real tools, data, and systems instead of it
+working blind. Model-agnostic by design (it's a protocol, not a vendor feature), which reinforces
+the whole course thesis.
+
+### Module 21 — Skills: Teaching the AI Your Playbook
+Codifying repeatable workflows so the AI performs them your way, consistently, without re-explaining
+every time. Turns one-off prompting into durable, reusable capability — and, fittingly, the skills
+themselves live in version control. The structured big sibling of the committed config from Module 5.
+
+### Module 22 — Securing Third-Party MCP Servers and Skills
+Module 15 scans the code the AI *writes*; this secures the AI *as an actor* in your environment.
+Unit 4 just gave the model hands — MCP servers and skills — and installing a third-party MCP server
+or skill is installing untrusted code that runs with access to your systems and data. Covers the new
+attack surface: prompt injection (malicious instructions smuggled in through content the AI reads),
+tool and agent abuse, over-broad permissions, and the MCP-and-skills supply chain — vetting, version
+pinning, and least-privilege for anything you connect. The defense belongs here because Unit 4's own
+content is what creates the risk; sequenced immediately after Skills so the danger and its mitigation
+sit together.
+
+### Module 23 — Working with Existing Codebases
+Everything so far has quietly assumed a greenfield project — you starting or growing something. The
+harder, more common reality for IT pros is pointing AI at a large codebase you *didn't* write:
+unfamiliar code, no mental model of it, and changes that have to be safe in a system nobody fully
+understands. This module is about giving the AI enough context to be useful there — orienting it
+across a big repo, having it map and explain unfamiliar areas before touching them, and making
+small, well-scoped, reviewable changes rather than sweeping rewrites. It leverages the full
+extend-the-AI toolkit: MCP (Module 20) for real access to the code and surrounding tools, and skills
+(Module 21) to codify navigation and safe-change playbooks. Placed deliberately late: it needs only
+the Module 4 tooling to attempt, but the basics — version control, review, testing, recovery — are
+exactly what make changing code you don't understand survivable, so it comes after them by design.
+
+---
+
+## Unit 5 — AI in the Loop: Agents Inside Your Pipeline
+
+Units 2–4 built the machinery — issues, PRs, CI, runners — and gave the AI hands. Unit 5 puts the AI
+*inside* that machinery, escalating from the AI assisting you to the AI acting on its own under
+supervision. The honest through-line: an agent can operate unattended only because the review, CI,
+and recovery muscles from earlier units are there to catch it.
+
+### Module 24 — Assistive Agents: AI Review and Issue Triage
+The AI helps, a human still decides. AI reviewers that comment on PRs (Module 10), and agents that
+triage, label, and route incoming issues (Module 9). Low-risk because nothing merges or ships
+without a person — the on-ramp to trusting agents in the loop at all.
+
+### Module 25 — Autonomous Agents: Issue-to-PR and Self-Healing CI
+The AI acts, supervised. Agents that take an assigned issue and open a PR, agents that respond to a
+failing pipeline by proposing a fix, and agents running as triggered or scheduled runner jobs
+(Module 19). Everything they produce still lands as a reviewable PR behind CI and security gates — the
+supervision is structural, not a matter of watching them work.
+
+### Module 26 — Orchestrating Multiple Agents
+More than one agent working at once without stepping on each other — the payoff of worktrees
+(Module 7) at full scale. Coordination, isolation, splitting work cleanly, and keeping parallel
+output reviewable instead of a tangled mess.
+
+### Module 27 — Evals: Trusting an Agent That Acts Without You
+The question Unit 5 forces: how do you know an unattended agent is doing good work? Evals as the
+answer — measuring agent output systematically, setting guardrails, and deciding what an agent is
+allowed to do without a human in the loop. The model-agnostic close to the whole course: evals are
+how you judge any model or agent, so when you swap the model — which you will — your evals are what
+tell you whether the swap was safe.
+
+---
+
+## Capstone — The Full Loop
+One feature taken end to end: prompt → branch → AI implementation → tests → PR → CI → security scan →
+review → merge → containerized deploy, with the committed AI config from Module 5 already in place
+from the first commit. Everything clicks into a single motion, and learners walk away with a workflow
+rather than a pile of tips. Stretch variant: run the same feature the Unit 5 way — an assistive agent
+reviewing, an issue-to-PR agent doing the first pass — so the workflow visibly starts running itself.
+
+---
+
+## Notes for the course owner
+
+- **One sequencing decision to make:** Modules 20–21 (MCP, skills) are somewhat orthogonal to the
+  deploy pipeline and could move much earlier — right after the AI-out-of-the-browser module — if
+  you'd rather front-load "extend the AI's reach" over "ship safely." They sit at the back here so
+  later units can build on them, but your audience's priorities might pull the other way.
+- **Working with Existing Codebases (Module 23)** strictly needs only the Module 4 tooling and could
+  move much earlier; it's placed late on purpose so the basics come first.
+- **The capstone is a 28th unit by design** (27 teaching modules + finale). If you'd rather it count
+  as a numbered module, the easiest merge is folding Issues (Module 9) into Collaboration (Module 11).
+- **Expansion candidates** for future modules, all back-of-course: observability, cost/usage
+  management, prompt-as-code, and dependency/license compliance. (Agent orchestration and evals
+  graduated into Unit 5.)
+- **Recommended future Unit 6 — Adoption, Governance, and Scale.** Sits above Unit 5: agent
+  permissions and least privilege, data governance and local/self-hosted models (the model-layer
+  parallel to self-hosting a git forge), IP and licensing of AI-generated output, audit trails, and
+  cost management. It's the unit that most differentiates a course aimed at IT professionals — parked
+  here until you're ready to build it.