Voice + consistency: vary stock formulas, vendor-balance orient.py, unify loop (#48,#49,#51) (#68)

Co-authored-by: claude <claude@jpaul.io> Co-committed-by: claude <claude@jpaul.io>
2026-06-22 17:45:33 -04:00
parent f7011d4211
commit f743bb671b
12 changed files with 35 additions and 33 deletions
@@ -185,9 +185,8 @@ Learn the primitive here on two; the orchestration comes later.

 ## The AI angle

-A generic devops course would mention worktrees as a niche convenience for the human who hates
-stashing. For AI-assisted work they're closer to essential, for a reason specific to how agents
-behave:
+Worktrees look like a niche convenience — a way to dodge `git stash` when you switch branches. For
+AI-assisted work they're closer to essential, for a reason specific to how agents behave:

 - **An agent assumes its working directory is stable.** It reads files, reasons about them, and
  writes them back over a session that can run for many minutes. If a *second* agent (or you,
@@ -42,8 +42,8 @@ By the end of this module you can:

 ### A remote is just another copy

-Strip the branding away and a **remote** is one thing: a named reference to *another copy of this
-same repository*, usually somewhere you can reach over the network. That's it. `origin` is not a
+A **remote** is a named reference to *another copy of this same repository*, usually somewhere you
+can reach over the network. That's it. `origin` is not a
 GitHub concept, a GitLab concept, or a Gitea concept — it's a Git concept, and the copy it points at
 is a full, equal Git repo that happens to live on a server.

@@ -40,9 +40,9 @@ By the end of this module you can:

 ### What an issue actually is (for this audience)

-Strip the project-management vocabulary away and an issue is one thing: **a written, addressable unit
-of work that lives next to the code instead of in someone's head, a Slack thread, or a chat tab.**
-It has a title, a body, and metadata (labels, an assignee, a status). It gets a stable number. You
+An issue is **a written, addressable unit of work that lives next to the code instead of in
+someone's head, a Slack thread, or a chat tab.** The project-management vocabulary around it varies;
+that core doesn't. It has a title, a body, and metadata (labels, an assignee, a status). It gets a stable number. You
 can link to it, search it, and close it.

 You already know this shape — it's a ticket. Jira, Linear, ServiceNow, a help-desk queue: same idea.
@@ -198,9 +198,8 @@ You don't need any of that yet. You need issues good enough to feed it. That's t

 ## The AI angle

-A generic project-management lesson would teach the same issue tracker. What's specific to
-AI-assisted work is that **the issue has quietly become an agent's task specification**, and that
-raises the stakes on writing it well in three concrete ways:
+The issue tracker itself isn't new. What's changed is that **the issue has quietly become an agent's
+task specification**, and that raises the stakes on writing it well in three concrete ways:

 - **Acceptance criteria are the agent's definition of done.** A human reads fuzzy criteria and fills
  the gaps with judgment. An agent reads them literally and stops when they're satisfied — so vague
@@ -181,7 +181,7 @@ CI, so there's one source of truth for "what counts as a finding."

 ## The AI angle

-A generic DevSecOps course teaches these three gates too. What makes them *load-bearing* here is that
+These three gates exist in any DevSecOps practice. What makes them *load-bearing* here is that
 AI-assisted coding doesn't just fail to prevent these problems — it actively manufactures all three,
 and does it in the exact form that slips past a human skim and a green build:

@@ -137,8 +137,7 @@ run identically — laptop, pipeline, production.

 ## The AI angle

-A generic devops course teaches Docker the same way. What makes containers matter *more* in
-AI-assisted work:
+Docker itself you may already know. What makes containers matter *more* in AI-assisted work:

 - **AI writes code for an environment it can't see.** The model assumes packages are installed, a
  certain runtime version, paths that exist on *its* imagined machine. "Works on my machine"
@@ -44,8 +44,8 @@ By the end of this module you can:

 ### A runner is just a computer that does what the YAML says

-Strip away the branding and a runner is one thing: **a process, on some machine, that checks out
-your code and executes the steps in your pipeline.** When your Module 14 workflow says "set up
+A runner is **a process, on some machine, that checks out your code and executes the steps in your
+pipeline** — nothing more exotic than that. When your Module 14 workflow says "set up
 Python, install pytest, run the tests," *something physical* has to do that — pull the repo onto a
 disk, run `pip install`, run `pytest`, report pass or fail back to the forge. That something is the
 runner.
@@ -201,9 +201,9 @@ that same AI hands beyond the repo. The next three modules build directly on it:

 ## The AI angle

-A generic integration course would teach you to wire systems together for *programs* to use —
-fixed clients calling fixed endpoints. MCP is shaped for a different consumer: **an AI that decides
-at runtime what it needs.** That changes what matters about the integration.
+Most integration work wires systems together for *programs* to use — fixed clients calling fixed
+endpoints. MCP is shaped for a different consumer: **an AI that decides at runtime what it needs.**
+That changes what matters about the integration.

 - **Discovery, not hardcoding.** A traditional client is written against specific API calls by a
  human. An MCP client hands the AI a *menu* — tool names, descriptions, argument schemas — and the
@@ -143,8 +143,7 @@ are more steps to get wrong, and more value in getting them right every time.

 ## The AI angle

-A generic automation course would call this "write a runbook." The AI-specific twist is what makes it
-land:
+On paper this is just "write a runbook." The AI-specific twist is what makes it land:

 - **The AI will execute the playbook, not just read it.** A runbook for a human is a reminder; a skill
  for an agent is something it *performs*. The precision pays off immediately — vague step, vague
@@ -144,10 +144,10 @@ in unfamiliar code," they encode *exactly* what careful means, as steps the AI f

 ## The AI angle

-A generic "onboarding to a legacy codebase" guide would tell a human to read the README and ask a
-senior dev. What's specific here is that **the AI is both the thing reading the codebase and the
-thing most likely to confidently misread it** — and the bigger the repo, the wider that gap between
-"sounds authoritative" and "is correct."
+Onboard a human to a legacy codebase and the advice is familiar: read the README, ask a senior dev.
+What's specific here is that **the AI is both the thing reading the codebase and the thing most
+likely to confidently misread it** — and the bigger the repo, the wider that gap between "sounds
+authoritative" and "is correct."

 So the AI-specific discipline is verification, not exploration. The model is genuinely excellent at
 the grunt work of orientation — reading a hundred files, summarizing structure, tracing a call path —
@@ -49,8 +49,14 @@ SIGNALS: dict[str, str] = {
    "README.md": "Has a README — read it first",
    "CONTRIBUTING.md": "Has contributor guidance — read before changing",
    "ARCHITECTURE.md": "Has an architecture doc — rare and valuable",
+    # Committed AI-instruction files. Name the real ones across vendors — singling out one
+    # would both miss files and cut against the vendor-neutral point (Module 5).
    "AGENTS.md": "Has a committed AI instructions file (Module 5)",
    "CLAUDE.md": "Has a committed AI instructions file (Module 5)",
+    "GEMINI.md": "Has a committed AI instructions file (Module 5)",
+    ".cursorrules": "Has a committed AI instructions file (Module 5)",
+    ".cursor/rules": "Has a committed AI instructions file (Module 5)",
+    ".github/copilot-instructions.md": "Has a committed AI instructions file (Module 5)",
 }

 # Common test-runner hints keyed off a present signal file.
@@ -17,8 +17,8 @@ purpose — each piece is a wall the autonomous agent has to land behind.
 - **Module 9** — issues as an agent's task specification, including the `ready` label and the idea of
  an agent as an *assignee*. An issue is the agent's input here.
 - **Module 6** — branches. The agent's work goes on a branch, never straight onto `main`.
- **Modules 10 and 11** — the PR review gate and the full issue → branch → PR → review → merge → close
-  loop. The PR *is* the unit of supervision in this module.
+- **Modules 10 and 11** — the PR review gate and the full issue → branch → implementation → PR →
+  review → merge → close loop. The PR *is* the unit of supervision in this module.
 - **Modules 13 and 14** — tests and CI. The automated gate that runs on the agent's PR.
 - **Module 15** — security scanning as another gate on the same pushes. Autonomy makes this
  non-optional, not optional.
@@ -177,9 +177,8 @@ ask you to trust the model more. It asks you to trust your gates more, and to ha

 ## The AI angle

-A generic automation lesson would teach you to script a runner job. What's specific to AI here is
-that **the actor inside the job is non-deterministic and persuasive**, and that changes what
-"automation" has to mean:
+Scripting a runner job is ordinary automation. What's specific to AI here is that **the actor inside
+the job is non-deterministic and persuasive**, and that changes what "automation" has to mean:

 - **The output is a proposal, not a result.** A normal scheduled job (back up the database, rotate
  logs) you trust to *complete*. An agent job you trust only to *propose* — because its output is a
@@ -16,9 +16,10 @@
 - **Module 25 — Autonomous agents** — you can hand an agent an issue and get a reviewable PR back,
  supervised. This module runs *several* of those at once. If you can't trust one unattended agent,
  you have no business running five.
- **Module 11 — Collaboration: humans and agents on one repo** — the issue → branch → PR → review →
-  merge → close loop. Orchestration is that loop run N times in parallel and fanned back into one
-  `main`. Parallel agents are just contributors who happen to share a clock.
+- **Module 11 — Collaboration: humans and agents on one repo** — the issue → branch →
+  implementation → PR → review → merge → close loop. Orchestration is that loop run N times in
+  parallel and fanned back into one `main`. Parallel agents are just contributors who happen to
+  share a clock.
 - **Module 10 — Reviewing code you didn't write** — the skill that becomes the bottleneck. N agents
  produce N diffs; one human reviews them one at a time.
 - **Module 9 — Issues** — the unit of work you split across agents. A clean fan-out is a set of clean