feat: start an Agents week

.github/workflows/cd.yml

@@ -57,8 +57,13 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
       - name: Make slides
-        run: npx @marp-team/marp-cli@latest --input-dir slides --output _output
+        run: bun run build-slides
 
       - uses: actions/upload-artifact@v7
         with:

.gitignore

@@ -203,3 +203,9 @@ content/week09_compiled/ramses/
 _output/Volumes
 *.doit.db
 _output/
+
+# Node / bun
+node_modules/
+
+# Symlink to AGENTS.md
+.claude/

.pre-commit-config.yaml

@@ -40,6 +40,7 @@ repos:
     hooks:
       - id: codespell
         args: ["-L", "hist,whet,classe,nd", "-w"]
+        exclude: ^bun\.lock$
 
   - repo: local
     hooks:

AGENTS.md

@@ -4,22 +4,24 @@ MyST MD course site for _Software Engineering for Scientific Computing_.
 
 ## Build & run
 
-| Target                       | Command                                                              |
-| ---------------------------- | -------------------------------------------------------------------- |
-| Book (with pixi)             | `pixi run book`                                                      |
-| Pyodide / JupyterLite        | `nox -s pyodide`                                                     |
-| Slides                       | `npx @marp-team/marp-cli@latest --input-dir slides --output _output` |
-| Live dev server (JupyterLab) | `pixi run lab`                                                       |
+| Target                 | Command                                                              |
+| ---------------------- | -------------------------------------------------------------------- |
+| Book (with pixi)       | `pixi run book`                                                      |
+| Pyodide / JupyterLite  | `nox -s pyodide`                                                     |
+| Slides                 | `npx @marp-team/marp-cli@latest --input-dir slides --output _output` |
+| Live dev server (MyST) | `pixi run serve`                                                     |
+| JupyterLab             | `pixi run lab`                                                       |
 
 - `pixi run book` depends on the `install-kernel` task, which installs the
   project's Python kernel into the pixi environment (`--sys-prefix`), then
   builds the site using `myst build --execute --html`. It sets
   `PYDEVD_DISABLE_FILE_VALIDATION=1`.
 - `mystmd` is configured to **execute all notebooks** on every build
-  (`--execute` flag).
+  (`--execute` flag), so broken code in a notebook breaks CI.
 - Only files listed in the `toc` section of `myst.yml` are included in the
-  build. The `notes/` directory is explicitly excluded and contains instructor
-  notes—do not reference it as book content.
+  build. Adding a new chapter file means adding it to `myst.yml`. The `notes/`
+  directory is explicitly excluded and contains instructor notes—do not
+  reference it as book content.
 
 ## Environment
 
@@ -33,15 +35,23 @@ MyST MD course site for _Software Engineering for Scientific Computing_.
 
 - `content/` — Book chapters (mix of `.md` and `.ipynb`).
 - `slides/` — Marp slide decks. These are rendered by CI and deployed to
-  `public/slides`.
+  `public/slides`. Files are named `week-NN-N.md` (e.g. `week-14-1.md`) and use
+  the Marp `gaia` theme; copy the front matter from an existing deck. Slides
+  parallel a content chapter: the chapter links to its deck near the top with
+  `` {button}`Slides <https://se-for-sci.github.io/slides/week-NN-N>` ``, and
+  the deck opens with a `# SE4Sci` / `## <Title>` lead slide, with `---`
+  separating slides.
 - `notes/` — Instructor notes; not built into the book.
 - `myst.yml` drives the project configuration and table of contents.
 
 ## Lint / format / pre-commit
 
 - Always use `prek -a --quiet` instead of `pre-commit run -a`.
 - Hooks include: ruff-format, blacken-docs, nbstripout, prettier, codespell,
-  blocklint, plus a **custom `disallow-caps` hook**.
+  blocklint, plus a **custom `disallow-caps` hook** that rejects
+  miscapitalizations of names like pybind11, NumPy, CMake, ccache, GitHub, and
+  pytest — always use the canonical spelling (the hook also applies to this
+  file).
 - Prettier config (`.prettierrc.toml`): prose wraps at 80 chars by default,
   **but never for `slides/*.md`**.
 

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

content/week14_agents/setup.md

@@ -0,0 +1,217 @@
+# Setting up Agentic AI
+
+{button}`Slides <https://se-for-sci.github.io/slides/week-14-1>`
+
+Agentic AI is the most significant change to software engineering ever. It is
+also still a fast-changing field; we'll try to balance general advice and
+specific examples that might change.
+
+## LLM details
+
+The core of agentic programming is an LLM, large language model. These are
+simply completion engines trained on lots of data with a limited enough number
+of parameters so that they learn concepts from the dataset.
+
+Models don't take letters in, they take tokens. That's why you can't ask a model
+to count the "r"'s in "strawberry" - it doesn't actually see the word that way.
+Tokenization is model specific; Claude Opus 4.7 has a finer tokenization than
+Opus 4.6. (Different tokenizations are usually associated with a newly trained
+model, rather than just updated weights, but model numbering has social
+implications.)
+
+## Selecting a harness
+
+The first thing you'll interact with is the harness. These tend to come in three
+flavors:
+
+- **TUI**, short for Terminal User Interface. These run in your terminal. Works
+  anywhere, including on clusters.
+- **GUI**, short for Graphical User Interface. These are stand-alone application
+  with custom graphics. These can often do a little more than TUI's, like render
+  webpage previews.
+- **Editor plugins**: These run in your editor, usually looking like a chat
+  window alongside the normal editor.
+
+Most harnesses come in all three flavors, you just pick the one you like
+interacting with best. Some harnesses are more feature rich in one flavor. For
+example, Copilot usually adds features to the editor plugin first. Claude Code
+and OpenCode favor the TUI.
+
+There's a second component to harnesses, and it's really important: the **system
+prompt**. The reason most model providers have a harness is to provide a system
+prompt that is customized to that model. Model specific customizations are
+likely not really needed, especially for larger models, so feel free to explore
+if you can. But note that's likely the biggest difference between the same model
+using different harnesses.
+
+Some providers (like Anthropic) require you use their harness to use
+subscription coding, so you don't get a choice. (Providers can cache the prompt
+tokens, reducing the cost and latency of the 10k-30k tokens of system prompt).
+
+Harnesses provide **tools**, which are things the model can call to perform
+operations. Models are mostly smart enough to figure out how to use tools, and
+most harnesses provide a small set of useful tools, so this isn't usually an
+issue except maybe for small local models.
+
+This is what makes Agentic AI special, and more useful than a simple chat; the
+model can call tools, read output, and loop, fixing mistakes, just like a human
+would. Many other things in this course - tests, formatters, linters, type
+checking, and CI all feed into the agentic loop, letting the agent correct
+mistakes and produce high quality output.
+
+Most harnesses have these features:
+
+- `/` commands - these control the harness. Common examples:
+  - `/init`: Set up or update the `AGENTS.md` file (equivalent)
+  - `/restore` (or `/sessions`): open up a previous session
+  - `/review`: Review a PR and/or other diff (depends on the harness)
+- `@` to load files into context (just mentioning them works too, but it's up to
+  the model to load all or parts)
+
+## Selecting a model
+
+There are different levels of models, with different costs / subscription usages
+associated with them. Small open source models can even run locally. Some models
+are faster than others, too. In general, if you are just learning about agentic
+AI, you should use a fairly powerful model, so you don't hit model limitations.
+Once you've used it for a bit, then you can start matching model strength to the
+problem description. You often have an "effort level" toggle as well. Using a
+strong model with a high effort level on a simple task can actually overengineer
+sometimes.
+
+Here's a current breakdown of some current models:
+
+- Frontier models: Claude Opus, GPT 5.5
+- Workhorse models: Claude Sonnet, GPT 5.4, Kimi K2.6, Composer 2.5
+- Simple models: Claude Haiku, GPT 5.4 mini
+- Local models: Gemma 4, Qwen 3.6
+
+(GLM 5.1 sits right in between Simple and Workhorse, and is a personal
+favorite).
+
+Here are some suggested task breakdowns. You can always use a stronger model,
+this is just a recommended minimum:
+
+- Local models
+  - Asking questions about a codebase
+  - Very, very simple edits
+  - Throw-away scripts (like plotting code)
+  - Writing config for AI
+  - Summaries
+- Simple models
+  - Repetitive edits
+  - Categorization/triage of open issues
+  - Simple merge conflicts
+  - Simple tests
+  - Fixing lints
+  - Quick chores
+  - Setting up, compiling, running code
+  - Working on webpages / theming
+- Workhorse models
+  - Complex merge conflicts
+  - Complex tests
+  - PR/diff review
+  - Assistance with docs
+  - Bug fixes
+  - Fixing CI
+  - Conversion (languages, CI providers, documentation generators, etc)
+  - Adding static types
+  - Recovering old PRs or changes
+  - Applying a design document / standard
+- Frontier models
+  - Large refactors
+  - Profiling and optimizations
+  - Difficult bug fixes
+  - Prototyping new features
+  - New features
+  - Any of the smaller model items if they fail to do it first
+
+## Setting up the harness
+
+Once you've picked a harness and model provider, then you'll need to download
+and install it, and get signed in or your API key set somewhere.
+
+Your harness has a central location for config and a user-level
+`AGENTS.md`-equivalent file. You can add a little bit of text here that will
+always be loaded right after the system prompt. Here's a template:
+
+```md
+You are on macOS. The github user is `<username>`. `python3` can be used if
+python without dependencies is needed. Use `uv run` if in a python package.
+
+Use `prek -a --quiet` instead of `pre-commit run -a` for linting.
+
+If you make a commit, follow conventional commits and add a trailer:
+`Assisted-by: <harness>:<model>`, where `<harness>` is the current agent harness
+(like ClaudeCode), and `<model>` is the AI model (Like claude-opus-4.8).
+
+Prefix PR descriptions and comments on PRs with the line ":robot: _AI text
+below_ :robot:" to indicate you are an agent speaking on a user's behalf.
+```
+
+(You would insert your GitHub username above). This does several things:
+
+- Some basic system setup, so the agents don't have to keep asking the same
+  questions
+- Guide for running prek, since I use that everywhere
+- Enforce conventional commits and Linux kernel style trailer. If using claude,
+  `You don't need to add a coauthored-by claude when you have this.` can be
+  added.
+- Not needed for a large model, but if using local models, add
+  `Use relative paths when possible.`, this reduces the errors in making paths.
+- Makes sure AI text is clearly marked (Claude also seems to comment on PRs
+  sometimes without asking, so this helps there too).
+
+Some example locations for this file:
+
+- Claude Code: `~/.claude/CLAUDE.md`
+- OpenCode: `~/.config/opencode/AGENTS.md`
+- Pi: `~/.pi/agent/APPEND_SYSTEM.md`
+
+There are also useful settings in these folders, too, like auto approve for
+certain tools.
+
+## Setting up the project
+
+When you start up a harness, you are starting fresh, there's no knowledge about
+the high level project features or low level details, everything must be
+investigated by the agent. To speed this up, reduce token usage, and give the
+agent a better "big-picture" view, you should create a project-level `AGENTS.md`
+file. You can type `/init` into your harness, and that should generate one. Some
+tools have custom file names; if yours does, move it to `AGENTS.md` after it is
+generated. The only tool that does not support the `AGENTS.md` standard is
+Claude Code; if you are using that then you'll also need to run
+`ln -s AGENTS.md CLAUDE.md` and add `CLAUDE.md` to your gitignore (also
+`.claude` while you are at it). Feel free to review and edit if it got anything
+wrong (like best way to run the tests, etc).
+
+If it's a new project, you can write one shortly after getting started. You can
+update it with AI as well, so feel free to include specifics that might change.
+You can even instruct the AI to update `AGENTS.md` when things change in the
+`AGENTS.md`!
+
+## Things to try first
+
+You can do nearly anything, but some ideas to get started.
+
+Try investigating the codebase. Some example prompts:
+
+- `How do I run the tests?`
+- `Write an ARCHITECTURE.md describing how this project works.`
+- `Who wrote the majority of the CI?`
+
+Your agent can look up git history, webpages, and much more, as it needs,
+without being explicitly told.
+
+Try reviewing code:
+
+- `/review` (some harnesses require a PR number or description of what to
+  review)
+- `Review this repository and look for things that can be modernized or simplified`
+
+And try this on issues or PRs if you have any:
+
+- `Categorize the open issues and tell me which ones are easiest to close`
+- `Fix #123`
+- `Is #234 still broken?`
+- `Fix the CI` (on a failing PR)

myst.yml

@@ -92,6 +92,9 @@ project:
       children:
         - file: content/week13_misc/webassembly.md
         - file: content/week13_misc/shell.md
+    - title: "WIP: Agentic AI"
+      children:
+        - file: content/week14_agents/setup.md
 site:
   title: SE4Sci
   nav:

package.json

@@ -0,0 +1,12 @@
+{
+  "name": "se-for-sci",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build-slides": "marp --input-dir slides --output _output",
+    "clean": "rm -rf _output"
+  },
+  "dependencies": {
+    "@marp-team/marp-cli": "^4.0"
+  }
+}