justin/ai-workflow-course
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Delete HANDOFF.md

Browse Source
This commit is contained in:
Justin Paul
2026-06-22 10:07:56 -04:00
parent ced344db9b
commit 4bd586bbd0
1 changed files with 0 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files
HANDOFF.md
-193
View File
@@ -1,193 +0,0 @@
# 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 20 modules group into
four acts:
- **Act 1 (1–6) — Get out of the chat window.** The local foundation: version control and getting
the AI editing real files safely.
- **Act 2 (7–11) — Make it shareable, reviewable, recoverable.** The team layer: hosting,
issues, review, collaboration, and recovery.
- **Act 3 (12–18) — Automate the checking and shipping.** The pipeline: tests, CI, security
scanning, containers, secrets, delivery, and the compute behind it.
- **Act 4 (19–20) — Extend the AI into your systems.** The frontier: MCP and skills.
- **Capstone** ties the whole motion together on one real feature.
**Durable core vs. expansion zone.** Modules 1–13 are the stable foundation — Git, review,
testing, and CI aren't going anywhere and should rarely change. Modules 14 and 19–20, plus
anything added later, are the expansion zone where a fast-moving space will keep handing you new
lessons (agent orchestration, evals, observability, cost/usage management, prompt-as-code). 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 7 (remotes give you the offsite, distributed copy — the *backup* half) and Module 11
(commits give you point-in-time restore — the *recovery* half), with an honest accounting of where
the analogy holds and where it breaks.
---
## Act 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.
### 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": Gitea and GitHub wikis are themselves just Git repos — 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 — 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 6 — 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.
---
## Act 2 — Make it shareable, reviewable, recoverable
### Module 7 — Remotes and Hosting: Gitea, GitHub, and Owning Your Repo
Push, pull, remotes, and the hosting layer, with a deliberate self-hosting angle (Gitea) since this
audience cares about control and on-prem. **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 8 — 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 10.
### Module 9 — 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 10 — Collaboration: Humans and Agents on One Repo
The full coordination loop now that issues (8) and PRs (9) 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 6).
### Module 11 — 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 16), your uncommitted changes, or large binaries. Teaching where the
analogy breaks is what earns this audience's trust.
---
## Act 3 — Automate the checking and shipping
### Module 12 — 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 13 — 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 14 — 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 15 — 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 16 — 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 17 — 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 18 — 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.
---
## Act 4 — Extend the AI into your systems
### Module 19 — 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 20 — 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.
---
## Capstone — The Full Loop
One feature taken end to end: prompt → branch → AI implementation → tests → PR → CI → security scan →
review → merge → containerized deploy. Everything clicks into a single motion, and learners walk away
with a workflow rather than a pile of tips.
---
## Notes for the course owner
- **One sequencing decision to make:** Modules 19–20 (MCP, skills) are somewhat orthogonal to the
deploy pipeline and could move much earlier — right after Module 4 — if you'd rather front-load
"extend the AI's reach" over "ship safely." They sit at the back here so the capstone can integrate
them, but your audience's priorities might pull the other way.
- **The capstone is a 21st unit by design** (20 teaching modules + finale). If you'd rather it count
as Module 20, the easiest merge is folding Module 8 (Issues) into Module 10 (Collaboration).
- **Expansion candidates** for future modules, all back-of-course: agent orchestration, evals,
observability, cost/usage management, prompt-as-code, and dependency/license compliance.