Add HANDOFF.md

2026-06-21 23:03:08 -04:00
parent 9e9bb515ee
commit ced344db9b
1 changed files with 193 additions and 0 deletions
@@ -0,0 +1,193 @@
 # 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.