Running-example consistency: paths, tasks.json, command collisions (#7,#10,#11) (#57)

Co-authored-by: claude <claude@jpaul.io>
Co-committed-by: claude <claude@jpaul.io>
This commit was merged in pull request #57.
This commit is contained in:
2026-06-22 15:35:51 -04:00
committed by Claude (agent)
parent 848ad14e3c
commit 06b9f8f308
14 changed files with 192 additions and 136 deletions
@@ -330,15 +330,21 @@ That's the entire client/server loop, end to end, with zero code you wrote. Now
> *"Add a task: review the Module 20 lab."*
It should call `add_task("review the Module 20 lab")`. Then **verify the effect outside the AI**,
which is the whole point — the change is real:
which is the whole point — the change is real. Verify it the way you'd verify any runtime effect:
by reading the *state*, not the repo:
```bash
python cli.py list # the new task is there, because the server wrote the same tasks.json
git diff # the change shows up in your repo, exactly like any other edit (Module 2)
cat tasks.json # the raw state the server changed, end to end
```
The AI just changed real state in a real system through a tool call. No copy-paste, no script you
ran by hand, no pasting `tasks.json` into a chat. That's "hands."
The AI just changed real state in a real system through a tool call. Notice what you did *not*
reach for: `git diff`. `tasks.json` is deliberately gitignored (Module 2's `.gitignore` treats it
as generated runtime state, not source), so `git diff` stays empty here — and that's correct, not a
bug. The proof the task list changed is the live state (`python cli.py list` / `cat tasks.json`),
not version control; runtime data the app owns is exactly the kind of thing you keep *out* of
history. No copy-paste, no script you ran by hand, no pasting `tasks.json` into a chat. That's
"hands."
7. (Optional, to feel the discovery point.) Edit the docstring on `add_task` to be vague — change it
to just `"""Adds something."""` — reload, and try the same request. Notice the AI gets *less*
@@ -392,8 +398,9 @@ The honest caveats — and one of them is large enough that it gets its own modu
- You built `tasks_mcp_server.py`, wired it into your tool, and saw the `tasks` server report as
connected with `list_tasks` and `add_task` available.
- You asked the AI a question and it answered by **calling a tool** against the live system, and you
asked it to add a task and then **verified the change outside the AI** with `python cli.py list`
and `git diff`.
asked it to add a task and then **verified the change outside the AI** by reading the runtime state
(`python cli.py list` / `cat tasks.json`) — not `git diff`, because `tasks.json` is deliberately
gitignored (Module 2).
- You can explain the client/server model in one breath — *servers expose tools/resources/prompts;
the client (your agentic tool) discovers and calls them on the AI's behalf* — and why "it's a
protocol, not a vendor feature" means your server survives a model swap.