From f743bb671bc87a9d90705673cccb9d1f7ffa26fa Mon Sep 17 00:00:00 2001 From: claude Date: Mon, 22 Jun 2026 17:45:33 -0400 Subject: [PATCH] Voice + consistency: vary stock formulas, vendor-balance orient.py, unify loop (#48,#49,#51) (#68) Co-authored-by: claude Co-committed-by: claude --- .../07-worktrees-running-agents-in-parallel/README.md | 5 ++--- modules/08-remotes-and-hosting/README.md | 4 ++-- modules/09-issues-and-the-task-layer/README.md | 11 +++++------ modules/15-security-scanning/README.md | 2 +- .../README.md | 3 +-- .../README.md | 4 ++-- modules/20-mcp-servers-giving-the-ai-hands/README.md | 6 +++--- .../21-skills-teaching-the-ai-your-playbook/README.md | 3 +-- modules/23-working-with-existing-codebases/README.md | 8 ++++---- .../23-working-with-existing-codebases/lab/orient.py | 6 ++++++ modules/25-autonomous-agents/README.md | 9 ++++----- modules/26-orchestrating-multiple-agents/README.md | 7 ++++--- 12 files changed, 35 insertions(+), 33 deletions(-) diff --git a/modules/07-worktrees-running-agents-in-parallel/README.md b/modules/07-worktrees-running-agents-in-parallel/README.md index 7dc4376..4c9c2b1 100644 --- a/modules/07-worktrees-running-agents-in-parallel/README.md +++ b/modules/07-worktrees-running-agents-in-parallel/README.md @@ -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, diff --git a/modules/08-remotes-and-hosting/README.md b/modules/08-remotes-and-hosting/README.md index ecf873f..4a506c5 100644 --- a/modules/08-remotes-and-hosting/README.md +++ b/modules/08-remotes-and-hosting/README.md @@ -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. diff --git a/modules/09-issues-and-the-task-layer/README.md b/modules/09-issues-and-the-task-layer/README.md index af40822..13c3a5f 100644 --- a/modules/09-issues-and-the-task-layer/README.md +++ b/modules/09-issues-and-the-task-layer/README.md @@ -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 diff --git a/modules/15-security-scanning/README.md b/modules/15-security-scanning/README.md index 5b1aa85..2f6d7e8 100644 --- a/modules/15-security-scanning/README.md +++ b/modules/15-security-scanning/README.md @@ -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: diff --git a/modules/16-containers-and-reproducible-environments/README.md b/modules/16-containers-and-reproducible-environments/README.md index 1c1a2b8..075e3bc 100644 --- a/modules/16-containers-and-reproducible-environments/README.md +++ b/modules/16-containers-and-reproducible-environments/README.md @@ -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" diff --git a/modules/19-runners-the-compute-behind-automation/README.md b/modules/19-runners-the-compute-behind-automation/README.md index 31e70c1..9ba3f67 100644 --- a/modules/19-runners-the-compute-behind-automation/README.md +++ b/modules/19-runners-the-compute-behind-automation/README.md @@ -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. diff --git a/modules/20-mcp-servers-giving-the-ai-hands/README.md b/modules/20-mcp-servers-giving-the-ai-hands/README.md index 73066cb..a0a127a 100644 --- a/modules/20-mcp-servers-giving-the-ai-hands/README.md +++ b/modules/20-mcp-servers-giving-the-ai-hands/README.md @@ -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 diff --git a/modules/21-skills-teaching-the-ai-your-playbook/README.md b/modules/21-skills-teaching-the-ai-your-playbook/README.md index 428cda3..408bef0 100644 --- a/modules/21-skills-teaching-the-ai-your-playbook/README.md +++ b/modules/21-skills-teaching-the-ai-your-playbook/README.md @@ -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 diff --git a/modules/23-working-with-existing-codebases/README.md b/modules/23-working-with-existing-codebases/README.md index 6b148c1..6acec5a 100644 --- a/modules/23-working-with-existing-codebases/README.md +++ b/modules/23-working-with-existing-codebases/README.md @@ -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 — diff --git a/modules/23-working-with-existing-codebases/lab/orient.py b/modules/23-working-with-existing-codebases/lab/orient.py index 372cf5e..489f074 100644 --- a/modules/23-working-with-existing-codebases/lab/orient.py +++ b/modules/23-working-with-existing-codebases/lab/orient.py @@ -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. diff --git a/modules/25-autonomous-agents/README.md b/modules/25-autonomous-agents/README.md index e9d038a..1e1c2f4 100644 --- a/modules/25-autonomous-agents/README.md +++ b/modules/25-autonomous-agents/README.md @@ -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 diff --git a/modules/26-orchestrating-multiple-agents/README.md b/modules/26-orchestrating-multiple-agents/README.md index 33b7d07..9adc18f 100644 --- a/modules/26-orchestrating-multiple-agents/README.md +++ b/modules/26-orchestrating-multiple-agents/README.md @@ -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