Prep docs/syllabus/README for github.com/recklessop public mirror (#108)

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

.github/workflows/ci.yml

@@ -21,5 +21,5 @@ jobs:
           set -euo pipefail
           python3 -m pip install --quiet pyyaml || true
           python3 tools/build_wiki.py --repo-root . --out /tmp/awc-wiki-build \
-            --web-base https://github.com/justin/ai-workflow-course --branch main --host github
+            --web-base https://github.com/recklessop/ai-workflow-course --branch main --host github
           bash tools/check.sh

README.md

@@ -18,7 +18,7 @@ built on a branch and merged through review, the same motion the modules teach.
 
 ## Read it as a book
 
-The lessons render into the **[Wiki](https://git.jpaul.io/justin/ai-workflow-course/wiki)** as a
+The lessons render into the **[Wiki](https://github.com/recklessop/ai-workflow-course/wiki)** as a
 navigable textbook (unit-by-unit sidebar, one page per module, prev/next links). The wiki is
 generated from `modules/` and kept in sync automatically; it's build output, so read it there but
 **edit the lessons here in `modules/`**. See [`tools/`](tools/) for the generator and the sync
@@ -92,7 +92,6 @@ ai-workflow-course/
   README.md                 # this file
   AGENTS.md                 # committed AI instructions; dogfoods Module 5 (vendor-neutral name)
   the-workflow-syllabus.md  # the full course plan (source of truth for structure)
-  handoff.md                # build-context notes for the authoring sessions
   _TEMPLATE.md              # the shape every module follows
   modules/
     01-the-copy-paste-problem/
@@ -112,5 +111,6 @@ ai-workflow-course/
 ## Status
 
 All 27 modules and the capstone are written and reviewed. The lessons render to the
-[Wiki](https://git.jpaul.io/justin/ai-workflow-course/wiki) as a textbook, kept in sync from
+[Wiki](https://github.com/recklessop/ai-workflow-course/wiki) as a textbook, kept in sync from
-`modules/` by CI. Blog drafts for jpaul.me live under [`blog/`](blog/).
+`modules/` by CI. Each lab is skip-friendly: copy that module's `lab/start/` snapshot into a
+fresh `tasks-app`, commit, and run that lab without doing the earlier ones.

modules/01-the-copy-paste-problem/README.md

@@ -161,7 +161,7 @@ purpose** so you recognize it later.
 Everything you'll run in this course lives in one repo. Grab it once, up front; no tools required
 beyond a web browser:
 
-1. Open the course's home page, **`https://git.jpaul.io/justin/ai-workflow-course`**, and use its
+1. Open the course's home page, **`https://github.com/recklessop/ai-workflow-course`**, and use its
    **Download ZIP** (archive) link.
 2. Unzip it under your home directory so the course's `modules/` folder lands at
    `~/ai-workflow-course/modules/`. (Rename the unzipped folder to `ai-workflow-course` if your download
@@ -267,5 +267,5 @@ rest of the course safe to attempt.
 
 ## Verify-before-publish
 
-- [ ] Confirm the **Download ZIP** URL (`https://git.jpaul.io/justin/ai-workflow-course`) points at
+- [ ] Confirm the **Download ZIP** URL (`https://github.com/recklessop/ai-workflow-course`) points at
       the published course host before shipping.

the-workflow-syllabus.md

@@ -7,8 +7,9 @@ goal is to replace that loop with durable engineering workflows: version control
 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
+The course is **model-agnostic in principle**: the concepts and workflow don't depend on one LLM,
-is the same.
+and the examples must survive a model swap. To keep steps concrete instead of abstract, the labs
+use **Claude Code** as the worked example (`claude --version  # sub your own agent`).
 
 ---
 
@@ -43,6 +44,36 @@ the analogy holds and where it breaks.
 
 ---
 
+## How git is taught (the reframe)
+
+This is **not** a "memorize git commands" course. The reader should finish knowing git is critical,
+understanding the concepts and the basics, and, above all, knowing they don't have to memorize
+commands because **the AI drives git for them**. The working analogy: learn arithmetic by hand,
+then use a calculator.
+
+- **Modules 1–3 teach the mechanics by hand, on purpose.** The AI is still in a browser chat; the
+  learner types git so the concepts land. Module 3 is where `branch` and `merge` first appear,
+  practiced on a markdown doc where a mistake costs nothing.
+- **Module 4 is the pivot.** It puts the AI in the editor or CLI. From there on the learner
+  **directs the AI** to do the git work (commit, branch, merge, revert, decide what to stage) and
+  **verifies** the result. Later modules don't tell the reader to type the commands themselves and
+  don't re-teach the verbs.
+- **Lesson vs. lab.** The lesson (Key concepts) is theory; commands appear with example output as
+  illustration, never as "run this." All hands-on execution lives in the lab.
+
+---
+
+## Lab format
+
+- **Self-contained, skip-friendly labs.** Each lab carries a `lab/start/` canonical snapshot and a
+  "Starting point (skip-friendly)" preamble, so a learner can copy that snapshot and start any
+  module without doing the prior labs first.
+- Labs run on the learner's **own machine, any OS**: no sandbox, no cloud account. Where a lab needs
+  code, it leans on Python or shell, picked per lab, kept minimal.
+- Every module ends at a keyboard (a lab), not a quiz, with a concrete "you're done when…" check.
+
+---
+
 ## Unit 1. Get out of the chat window
 
 ### Module 1. The Copy-Paste Problem
@@ -68,9 +99,11 @@ only reasoned about in context but never wrote is gone with the session. That's
 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
+The lowest-stakes place to practice Git, and a genuinely useful skill on its own. **This is where
-doc with AI and committing it carries almost no risk, so it's the ideal first real application of
+`branch` and `merge` first land**, practiced on a markdown doc where a mistake costs nothing, so
-branch / diff / commit / merge before the agent ever touches code. Covers why plain text wins:
+the verbs are already familiar before the agent ever touches code. Editing a doc with AI and
+committing it carries almost no risk, which makes it the right first home for the full
+branch / diff / commit / merge loop. 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
@@ -81,25 +114,34 @@ repos, so your wiki was version-controlled all along. AI angle: LLMs are native
 
 ### 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
+directly. Worked example: Claude Code; the criteria for choosing a tool stay vendor-neutral. This
-real files only because you can now see and revert exactly what it did.
+works *because* of Module 2: you let the AI edit real files only because you can now see and revert
+exactly what it did. **This module is the pivot in how git is taught.** From here on, the learner
+directs the agent to run git (commit, branch, merge, revert) and verifies the result, instead of
+typing the commands by hand.
 
 ### 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
+coding tools read a committed, repo-level config or instructions file: project conventions, build
-principle outlives any one vendor's filename): project conventions, build and test commands, coding
+and test commands, coding standards, "don't touch these files," and house style. The principle is
-standards, "don't touch these files," and house style. Checking it into the repo means every
+tool-agnostic; the worked example uses Claude Code's `CLAUDE.md` so the steps are concrete, and the
-teammate (and every automated agent that later operates on the repo) inherits the same setup
+filename convention is called out as a stand-in for whatever your tool reads. The motion itself is
-instead of each person hand-tuning their own and quietly drifting apart. It also makes AI behavior
+now agent-driven: the learner directs the agent to **identify which config files belong in version
-*reviewable*: a change to how the AI works on this project arrives as a diff in a PR, like any other
+control**, stage them, and commit them. Checking the config into the repo means every teammate
-change. (Its full payoff lands once you have a shared remote in Module 8, but the habit starts now.)
+(and every automated agent that later operates on the repo) inherits the same setup instead of each
-This is the lightweight foundation that Module 21, Skills, later builds into structured, reusable
+person hand-tuning their own and quietly drifting apart. It also makes AI behavior *reviewable*: a
-playbooks.
+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
+### Module 6. Branches: Sandboxes for AI Experiments
-Branching, merging, and resolving conflicts, positioned as isolation for AI experiments: spin up a
+**Not** a re-teach of branch verbs (Module 3 already first-taught `branch` and `merge` on docs).
-branch, let the agent try something wild, throw it away or keep it with zero risk to working code.
+Module 6 is about **directing the agent to run a risky experiment on a branch**: spin up a branch,
+have the agent try something bold on real code, then decide as one call to keep it (merge) or throw
+it away (delete the branch) with zero trace on `main`. The learner directs and verifies; the agent
+runs the git. Conflicts are covered as something to *recognize and verify*, including the case where
+the agent resolved one silently and you never saw a marker.
 
 ### Module 7. Worktrees: Running Agents in Parallel
 Multiple working directories from one repo, genuinely powerful once you're running more than one
@@ -267,9 +309,13 @@ 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
+from the first commit. **Every step is agent-driven**: the agent creates the branch, writes the
-rather than a pile of tips. Stretch variant: run the same feature the Unit 5 way (an assistive agent
+code and tests, makes the commits, opens the PR, responds to CI and security findings, and runs the
-reviewing, an issue-to-PR agent doing the first pass) so the workflow visibly starts running itself.
+deploy. The learner *directs* (states intent, sets guardrails, decides what merges) and *verifies*
+(reads the diff, reads the CI output, confirms the deployed behavior). 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.
 
 ---