feat(course): build out all 27 modules, capstone, scaffold, and conventions

Scaffold the course repo and author the full curriculum in dependency-chain order, following the settled build decisions in handoff.md. - Scaffold: course README, vendor-neutral AGENTS.md (dogfoods Module 5), _TEMPLATE.md (the fixed 9-section module shape), root .gitignore, ship config. - Modules 1-2: reference exemplars (locked for tone/depth/lab style). - Modules 3-27: full lessons + runnable labs, each following the template, respecting the chain, vendor/model-agnostic, with "feel the pain" labs. - Module 8 hosting comparison web-researched and date-stamped (as of 2026-06-22), not written from memory; expansion-zone modules carry Verify-before-publish. - Capstone: the full loop end to end on the running tasks-app example. Lab code syntax-checked (Python/shell/YAML); every module has the 7 core template sections. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TfzV5QvtPDz8LJS3Pu5VLT
2026-06-22 12:18:30 -04:00
parent 4bd586bbd0
commit fbec36cb67
117 changed files with 15131 additions and 1 deletions
@@ -0,0 +1,67 @@
+# Skill: Add a new tasks-app command, end to end
+
+> A reusable playbook. Don't paste this whole file into a chat and hope. Point your agentic tool at
+> it by name — "follow `add-command.md` to add a `clear` command" — or drop it wherever your tool
+> auto-discovers procedures (a skills/commands folder). The steps are the same either way.
+
+## When to use this
+
+Invoke this whenever the task is **"add a new subcommand to the `tasks-app` CLI."** It exists so a
+new command lands the *same* way every time: real code, a real test, a changelog line, and a clean
+commit — never just the code with the rest forgotten.
+
+If the task is *not* "add a CLI command" (a bug fix, a refactor, a docs change), this skill does not
+apply. Don't force it.
+
+## Inputs you need before starting
+
+Ask for these if they weren't given:
+
+- `COMMAND_NAME` — the subcommand word, e.g. `clear`.
+- `WHAT_IT_DOES` — one sentence of intended behavior, e.g. "remove all tasks."
+
+## Project facts (so you don't have to rediscover them)
+
+- Core logic lives in `tasks.py` (the `TaskList` class). The CLI front end is `cli.py`. State
+  persists to `tasks.json` — **never edit `tasks.json` by hand; it's generated.**
+- Tests live in `test_tasks.py` and run with `python -m unittest`. Standard library only — no
+  third-party packages, no new dependencies.
+- The human-facing change log is `CHANGELOG.md`, newest entry on top.
+
+## Procedure — do these in order, do not skip
+
+1. **Core logic in `tasks.py`.** If the command needs new behavior on the task list, add a small
+   method to `TaskList` (e.g. `clear()`). Keep it minimal; match the existing style. If the command
+   only reads existing state, skip to step 2.
+
+2. **Wire the CLI in `cli.py`.** Add a branch to `main()` for `COMMAND_NAME`, call into `tasks.py`,
+   `save()` if it mutated state, and print a short confirmation. Add the command to the `usage:`
+   string so it's discoverable.
+
+3. **Add a real test in `test_tasks.py`.** Test the *behavior you intended*, not just "it doesn't
+   crash." Assert the end state (e.g. after `clear()`, `len(tasks) == 0` and `pending()` is empty).
+   A test that passes against a broken implementation is worse than no test.
+
+4. **Run the tests.** `python -m unittest` from the project root. Do not claim success until it's
+   green. If it fails, fix the code — not the test — and run again.
+
+5. **Smoke-test the CLI.** Actually run it: `python cli.py COMMAND_NAME`, then `python cli.py list`
+   to confirm the visible result. Paste what you ran and what it printed.
+
+6. **Add a `CHANGELOG.md` entry.** One line under the top heading, present tense:
+   `- Add \`COMMAND_NAME\` command: WHAT_IT_DOES.` Newest on top.
+
+7. **Commit as one logical change.** Stage code + test + changelog together and commit with a
+   message that names the command: `git add tasks.py cli.py test_tasks.py CHANGELOG.md && git commit
+   -m "Add COMMAND_NAME command"`. Do **not** stage `tasks.json`.
+
+## Done when
+
+- `python -m unittest` is green and includes a new test that actually exercises `COMMAND_NAME`.
+- `python cli.py COMMAND_NAME` does `WHAT_IT_DOES` and you've shown the output.
+- `CHANGELOG.md` has a new top line for the command.
+- One commit contains the code, the test, and the changelog line — and nothing else (no
+  `tasks.json`, no unrelated reformatting).
+
+If any of those is missing, the skill isn't finished. Report which step failed and stop — don't
+paper over it.
@@ -0,0 +1,9 @@
+# Changelog
+
+Newest entries on top. One line per user-visible change.
+
+## Unreleased
+
+- Add `count` command: print how many tasks are still pending.
+- Add `done <index>` command: mark a task complete.
+- Initial CLI: `add` and `list`.
@@ -0,0 +1,59 @@
+"""Tiny command-line front end for the demo task app.
+
+Run it:
+    python cli.py add "write the lesson"
+    python cli.py list
+    python cli.py count
+
+State is kept in tasks.json next to this file. The same minimal app from Module 1 onward — the
+target your "add a command" skill extends.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+from tasks import Task, TaskList
+
+STATE = Path(__file__).parent / "tasks.json"
+
+
+def load() -> TaskList:
+    if not STATE.exists():
+        return TaskList()
+    raw = json.loads(STATE.read_text())
+    return TaskList(tasks=[Task(**t) for t in raw])
+
+
+def save(tlist: TaskList) -> None:
+    STATE.write_text(json.dumps([t.__dict__ for t in tlist.tasks], indent=2))
+
+
+def main(argv: list[str]) -> int:
+    tlist = load()
+    if not argv:
+        print("usage: python cli.py [add <title> | list | done <index> | count]")
+        return 1
+
+    command = argv[0]
+    if command == "add":
+        title = " ".join(argv[1:])
+        tlist.add(title)
+        save(tlist)
+        print(f"added: {title}")
+    elif command == "list":
+        print(tlist.render())
+    elif command == "done":
+        tlist.complete(int(argv[1]))
+        save(tlist)
+        print("updated")
+    elif command == "count":
+        print(f"{tlist.pending_count()} task(s) pending")
+    else:
+        print(f"unknown command: {command}")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
@@ -0,0 +1,41 @@
+"""Core task logic for the demo app.
+
+The same running example from Module 1 onward, carried forward with the `pending_count()` helper
+that backs the `count` command. This is the codebase your "add a command" skill operates on.
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Task:
+    title: str
+    done: bool = False
+
+
+@dataclass
+class TaskList:
+    tasks: list[Task] = field(default_factory=list)
+
+    def add(self, title: str) -> Task:
+        task = Task(title=title)
+        self.tasks.append(task)
+        return task
+
+    def complete(self, index: int) -> None:
+        self.tasks[index].done = True
+
+    def pending(self) -> list[Task]:
+        return [t for t in self.tasks if not t.done]
+
+    def pending_count(self) -> int:
+        return len([t for t in self.tasks if not t.done])
+
+    def render(self) -> str:
+        if not self.tasks:
+            return "(no tasks yet)"
+        lines = []
+        for i, task in enumerate(self.tasks):
+            box = "[x]" if task.done else "[ ]"
+            lines.append(f"{i}. {box} {task.title}")
+        return "\n".join(lines)
@@ -0,0 +1,44 @@
+"""Test suite for the tasks-app. Run from this folder with:
+
+    python -m unittest
+
+Your "add a command" skill should ADD a test here for every new command. The point is to assert
+intended behavior, not just that nothing crashed.
+"""
+
+import unittest
+
+from tasks import TaskList
+
+
+class TestTaskBasics(unittest.TestCase):
+    def test_add_appends_a_task(self):
+        tl = TaskList()
+        tl.add("write the skill")
+        self.assertEqual(len(tl.tasks), 1)
+        self.assertEqual(tl.tasks[0].title, "write the skill")
+        self.assertFalse(tl.tasks[0].done)
+
+    def test_complete_marks_done(self):
+        tl = TaskList()
+        tl.add("a")
+        tl.complete(0)
+        self.assertTrue(tl.tasks[0].done)
+
+    def test_pending_excludes_completed(self):
+        tl = TaskList()
+        tl.add("a")
+        tl.add("b")
+        tl.complete(0)
+        self.assertEqual([t.title for t in tl.pending()], ["b"])
+
+    def test_pending_count_ignores_done(self):
+        tl = TaskList()
+        tl.add("a")
+        tl.add("b")
+        tl.complete(0)
+        self.assertEqual(tl.pending_count(), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()