Goal

The author’s requests (translated from Italian):

  • Put the series icon at the top of the README.
  • Give it a real title instead of the repository slug.
  • Say which badges the project could carry, now or later.
  • Start the first draft of the hub article (00) while the author merges the previous session’s pull request.

After the merge, the author asked for more (translated from Italian):

  • Explain what .github/workflows/test.yml does, and whether it’s enough.
  • Record the badges for later, and add each one without being asked once it becomes true.
  • Correct the title’s inspiration: Feynman’s Six Easy Pieces rather than the 1970 film.
  • Make the subtitle more ironic: conceptually little has changed, and the real problems are anything but easy, but they’ve been the same ones since the beginning.
  • Check the articles’ Medium format as soon as possible.
  • Would running sandboxes in CI cost a lot?

What we did

  • The README (8262cb1) now has:
    • the round icon at the top, the title “Five Easy Pieces on Agentic AI” and a one-line subtitle;
    • a status line that matches reality: example 01 runs in the cloud, and nothing is published yet;
    • make run-01 in the Reproduce section;
    • a statement that the illustrations are AI-generated.

    It went into PR #3 before the merge.

  • Badges: only ones that say something checkable today:
    • tests and Pages status (GitHub’s own badges);
    • “verified with sbx v0.50.0”, linking to references/sbx-notes.md;
    • “Python 3.12, stdlib only”;
    • both licences;
    • “written with Claude Code”, linking to this site.

    Every URL was fetched before committing, and both CI badges read “passing”. The colours come from the illustration palette.

  • The hub draft (122f952), about 1,850 words of prose:
    • Thesis: agent = architecture + program, with one question throughout: when does an agent actually need a fence?
    • AIMA: §2.1 to §2.4.7 in paraphrase only (ADR-0012).
    • The pieces: all five, each with whether it needs a sandbox; why 01 and 02 have no LLM; how to reproduce, cloud only (ADR-0010).
    • Front and back matter: a note on sources, series navigation, the hub disclosure line, and the AI-generated illustration. caption (ADR-0013).
    • Medium-safe: # and ## only, no tables, no footnotes.
    • Data: the only numbers are from piece 01’s reference run.
  • The CI, explained and extended (188e046, f968651). Before, it ran 14 unit tests on Python 3.12 and checked the journal format on every push and pull request, nothing more. Now it does three things:
    • Unit tests on Python 3.12 and 3.14. 3.14 is what the cloud sandbox’s shell template ships.
    • make lint: shellcheck on every script, and byte-compiling the Python scripts.
    • A build of the site on every pull request, so a broken page shows up before the merge.

    Still no sandboxes and no secrets in CI.

  • The site header (author’s request): room above the title. On phones the long title had been wrapping at the theme’s 54 px line height; it’s now compact. Checked with headless-Chrome screenshots at 1100 and 390 px.
  • make article-check (08fe535): scripts/article-check.py, run in CI’s lint job.
    • Always errors: headings deeper than ##, tables, footnotes, code blocks over 40 lines, code links on a branch instead of a tag, a missing disclosure line or AI-generated caption (ADR-0013), incomplete front matter.
    • Errors from review on, warnings on drafts: length outside the target, an empty verified_with.
    • Always a warning: a likely direct AIMA quote (ADR-0012).

    A deliberately broken copy of the hub triggered all seven planted problems; the real hub passes.

  • The badge backlog in CLAUDE.md §9.3, each badge with its trigger. /wrap now checks the list (4e85920).
  • The hub’s title and subtitle (f65c931):
    • The title paragraph now credits Feynman’s Six Easy Pieces: the fundamentals look easy, and everything hard sits underneath.
    • The subtitle says the parts have grown since 1995 while the hard problems haven’t moved.
    • CLAUDE.md §3.2 records the nod. The hub is 1,954 words of prose, just under the 2,000 target.

Commands that mattered

New: make lint (from the Makefile). The draft’s “Run it yourself” box quotes the Makefile:

make check-env   # what this machine can run
make run-01      # piece 1 in a cloud sandbox

Decisions

  • Sandboxes in CI: proposed (deterministic pieces only, after merges and on demand), waiting for the author’s decision. It needs an ADR (CLAUDE.md §5.2).
  • No new ADR. The choice of thesis (CLAUDE.md §3.1 says the author picks) is proposed in the draft and waits for the author’s review:
    • Used: “agent = architecture + program”, with one paragraph on “the hardest case”.
    • Saved for later: “the network policy is a simple reflex agent” for piece 01, and “the critic must sit outside” for piece 05.

Dead ends and surprises

  • A sentence that would have been false. An early wording said the report was identical “on my machine” and in the cloud. The host is a Codespace, not the author’s laptop, so it now says “in my Codespace”. The same check applies throughout: the hub must not imply a local-sandbox run that hasn’t happened (ADR-0010).
  • “Every sentence is mine” contradicted the disclosure line. The hub is drafted with Claude, so the source note now says the sentences are paraphrases and doesn’t claim authorship of every word.
  • shellcheck found two real bugs on its first run:
    • site-check.sh didn’t stop when cd failed, so it would have checked the wrong directory.
    • sbx-run.sh used an unquoted variable inside a pattern expansion.

    Its two other findings were false positives, now documented in the code.

  • Docker doesn’t publish cloud-sandbox rates in its docs. The docs say how compute is billed: by the second, on runtime times the CPU/memory shape, with no subscription fee and a one-time promotional credit at signup. The rates themselves appear only in the Agentic Platform Console. So the CI-cost answer gives the measured usage (10–17 s of the smallest shape per run of piece 01), and the author reads the price.
  • Feynman’s book has two publication years: catalogs say 1995, some 1994. The hub says “mid-1990s” rather than pick one.
  • Two pull requests in flight. The author merges PR #3 while this session works. The hub draft therefore stays local until the merge, so #3 contains exactly what was reviewed.

Who did what

  • The author: asked for the README changes and the badge survey, asked for the hub draft, merged PR #3, and corrected the title’s inspiration and the tone of the subtitle.
  • Claude: rewrote the README, picked and verified the badges, drafted the hub, extended the CI and wrote this entry.
  • Still with the author: the thesis, the tone and the edits.

Next

  1. The author reviews the hub draft: thesis, tone, length, what to cut.
  2. Draft piece 01. It publishes with the hub (ADR-0007), and its code and reference run are ready.
  3. Example 02: internal state, and a run where that state survives stopping and restarting the cloud sandbox.