ai-workflow-course/the-workflow-syllabus.md

# 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 uses 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.