From 4bd586bbd07563917a875abc1f17de5e7a03552b Mon Sep 17 00:00:00 2001 From: Justin Paul Date: Mon, 22 Jun 2026 10:07:56 -0400 Subject: [PATCH] Delete HANDOFF.md --- HANDOFF.md | 193 ----------------------------------------------------- 1 file changed, 193 deletions(-) delete mode 100644 HANDOFF.md diff --git a/HANDOFF.md b/HANDOFF.md deleted file mode 100644 index aa96164..0000000 --- a/HANDOFF.md +++ /dev/null @@ -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. \ No newline at end of file