Practice AI Engineering. Prove What Works.

24 small, runnable companions for the courses and articles at profrod.ai.
Learn with real files, visible failures, and tests you can run on your own computer.

This repository is also a top-down curriculum map and scaffold. Every site-backed runnable course has one small, credential-free vertical slice that accepts an input, emits an observable result, and proves it with a test. Those slices establish the run/verify/reset contract for later labs; they are not completed course material, nor a substitute for the lessons.

Run your first exercise · Choose a practice · Fix a problem · Contribute

---

The learning loop: read the teaching material → predict what should happen → change the bytes → run the check → explain the evidence.

The Python beginner path makes no network calls after you clone the repository. Every baseline uses invented data, and no exercise requires an API key, paid call, or live AI service. The optional Node.js exercise downloads its locked packages before it runs.

Companion boundary: this repository contains practice material, not the courses or articles themselves. It never copies or republishes the teaching material from profrod.ai.

The book's course: build an always-on agent, one unit at a time

Reading Build Your Always-On AI Agent From Scratch on profrod.ai/book? Its practice lives here, in courses/sovereign-agent-book: 38 ninety-minute notebook units, two per chapter, each with a one-click Colab badge, a separate worked solution, and educator guides for a class. They build, piece by piece, the finished agent in profrodai/sovereign-agent.

Start here: your first exercise in five minutes

For the agent-routing lab, replay constructed scores and inspect Jev's typed interface. It needs only Python 3.10+: no model download, GPU or API key. Its counterexample tests the routing policy and accounting, rather than measuring a model.

What you need

• A computer with a terminal.
• Git.
• Python 3.10 or newer. Check with python3 --version.

On Windows, these instructions are easiest in Windows Subsystem for Linux. If your computer uses python instead of python3, substitute python in the commands below.

You do not need Node.js for the first exercise. Node.js is only required for the Cursor order-api exercise.

1. Download the exercises

Copy and paste these commands into your terminal one line at a time:

git clone --depth 1 https://github.com/profrodai/profrodai-resources.git
cd profrodai-resources

You should now be inside a folder named profrodai-resources.

Prefer buttons to Git commands? Download the repository as a ZIP file, unzip it, and open your terminal in the new folder.

2. Run a ready-made example

python3 tools/run_article_practice.py \
  articles/build-a-working-agent-with-sovereign-agent/practice.json

You should see this result:

{
  "failure": {
    "missing": [
      "check"
    ],
    "ready": false
  },
  "positive": {
    "missing": [],
    "ready": true
  }
}

That output proves two things:

• the complete example is allowed to continue; and
• the incomplete example stops and names the missing check.

If you see that output, congratulations: you have run your first verified practice exercise.

What just happened? You did not ask an AI to tell you it succeeded. You ran a deterministic check that proved one example complete and denied another example because evidence was missing. That difference is the central habit these companions teach.

3. Make a small change

Open these two files in any text editor:

• the instructions
• the example data

Follow the README exercise. Run the same command again after every change. A failure is useful: it means the checker found a difference between the result you produced and the result the fixture says is correct.

What should I practise next?

There are two kinds of companion:

• Course practices are small projects built around a runnable lab. Choose one when you want to edit code, add a test, and produce evidence.
• Article practices are short JSON exercises. Choose one when you want to explore a single idea in roughly 10–20 minutes.

You do not need to complete them in order.

Course practices

Every course practice has a PRACTICE.md file with an objective, guided task, project, evidence checklist, rubric, accessibility option, safety boundary, and verification command.

Choose the description that sounds most useful. Each link opens the matching practice guide; its final word tells you which runtime you need.

• Change and test a small order API — Agentic Coding with Cursor (Node.js)
• Check whether a business brief has enough evidence — Claude Code for Business (Python)
• Route uncertain work to human review — LangGraph Agent Orchestration (Python)
• Choose an eligible model without hiding cost or latency — Nebius Token Factory in Production (Python)
• Turn retrieval inputs into a bounded deployment plan — NVIDIA NIM in Production (Python)
• Store evidence without accepting duplicates — Tools, Memory, and Multi-Agent Systems (Python)
• Measure a before-and-after time saving honestly — Transformation Tracker with Claude Code (Python)
• Separate deterministic code from uncertain agent work — Two Architectures (Python)
• Prevent a voice agent from speaking after a call ends — Voice Agents, Not Chatbots (Python)
• Reject an answer that lacks required evidence — Why Agents Fail (Python)
• Measure operator minutes saved without hiding regressions — ZEO ITAM Autumn 2026 (Python)

The Why Agents Fail exercise is a good first course practice. Run it from the repository root:

make -C courses/why-agents-fail run
make -C courses/why-agents-fail verify

The first command prints a result. The second runs the tests. Success ends with OK.

Article practices

Each article folder contains:

• README.md — what to practise and how to know you succeeded;
• practice.json — one successful case and one failure case; and
• an exact command that checks both cases.

Choose one idea to explore. Every link opens a short, offline JSON exercise; you only need Python to run it.

• Prove an agent result has evidence and an owner — Build a Working Agent with sovereign-agent
• Deny unsafe file targets and overwrites — Build Your First ZeoCore Tool
• Compare requested permissions with granted permissions — Claude Code Permissions Are Your Org Chart
• Deduplicate customer data without silently losing records — Clean a Messy Customer List
• Check whether every task handoff has an owner and evidence — Govern a Multi-Agent Project
• Choose a content block for a communication goal — The Content Kit
• Compare verification cost with expected failure loss — Unverified Output Has a Negative Margin
• Calculate a synthetic token-usage cost — What Claude Code Actually Costs
• Decide whether a proposed change needs review — What Claude Code Actually Changes
• Route decisions to operator, Master, stream, or Sparring — What Is a Zero-Employee Organization?
• Check whether a task is safe to run unsupervised — When Can You Actually Walk Away?
• Compare the transaction cost of a firm and a market — Why AI Agents Don't Dissolve the Firm
• Rebuild state from an ordered event record — Your Chat History Is Not a System of Record

A simple way to work through any exercise

Use the same loop every time:

1. Read the exercise README or PRACTICE.md from top to bottom.
2. Run the unchanged example once. This proves your setup works.
3. Predict what a small change will do before editing the file.
4. Change one thing. Small edits make failures easier to understand.
5. Run the verification command again.
6. Explain the result in your own words.
7. Save evidence: the command, its output, and the change you made.

Do not aim only for a green check. The useful part is being able to explain why the successful case passed and why the failure case was denied.

Folder map

profrodai-resources/
├── courses/       runnable course labs and guided practice files
├── articles/      short article exercises with synthetic JSON data
├── catalog/       the machine-readable list of tracked companions
├── docs/          contributor and CI documentation
├── tests/         tests for the repository-wide checks
└── tools/         local exercise runners and validators

The teaching material stays on profrod.ai. This repository deliberately does not contain copied lesson prose or article bodies.

Common problems

git: command not found

Install Git, close and reopen your terminal, then try the clone command again.

python3: command not found

Try:

python --version

If that prints Python 3.10 or newer, replace python3 with python in the exercise command. Otherwise install Python 3 before continuing.

destination path 'profrodai-resources' already exists

You already have a folder with that name. Do not overwrite it. Either enter the existing clone with cd profrodai-resources, or choose a different name for a fresh copy:

git clone https://github.com/profrodai/profrodai-resources.git profrodai-resources-fresh
cd profrodai-resources-fresh

make: command not found

The article exercises do not require make; run their python3 tools/run_article_practice.py ... command directly. For course practices, install Make or use WSL on Windows.

No such file or directory

You are probably in the wrong folder. Run:

pwd
ls

The ls output should include articles, courses, catalog, tools, and Makefile. If it does not, return to the cloned repository with:

cd profrodai-resources

mismatch: expected=... observed=...

The runner is working: your edited fixture no longer describes the result the code produced. Compare expected with observed, decide which one should change, and rerun the command.

cannot read practice spec or invalid ... JSON

JSON punctuation is strict. Check for a missing quote, comma, brace, or square bracket. A common mistake is leaving a comma after the final item. Your text editor may highlight the exact line containing the error.

set PROFROD_SITE_REPO ...

You ran the maintainer-only full repository gate. Beginners do not need that gate. Use the verification command in the exercise README, or run the repository's public checks with:

make verify-pr

I changed too much and want to start again

First run git diff so you can see and learn from the changes. The simplest safe reset is to make a new clone in a different folder; your original work will remain available for comparison.

Safety and cost

The baseline exercises are designed to be:

• offline;
• credential-free;
• deterministic;
• based on synthetic data;
• safe to rerun; and
• free of paid-provider calls.

Never paste real customer data, credentials, API keys, or private company records into an exercise. If you later connect an exercise to a live service, that is a separate project with its own cost, privacy, and permission review.

Questions and feedback

If an instruction is unclear or an example behaves differently on your computer, open an issue. Include the exercise path, the command you ran, and the error text. Remove all credentials, private data, and identifying customer information before posting.

For contributors and maintainers

The learner path above is intentionally simple. The repository-wide provenance, maintenance, and contribution machinery is available below without interrupting that path.

Open maintainer verification and catalog details

Public pull-request gate

make verify-pr

This runs all 11 course gates, all 13 article exercise specifications, the repository tests, manifest checks, maintenance checks, and local-link checks. It does not need access to the teaching-site repository.

The whole-repository gate requires Git, Make, Python, Node.js, and npm because it also tests the Cursor order-api. A learner running one Python exercise does not need that full toolchain.

Source-backed maintainer gate

git clone https://github.com/rodriveracom/profrod-site.git ../profrod-site
PROFROD_SITE_REPO=../profrod-site make verify

This additionally proves the catalog against the pinned profrod-site Git object. It deliberately fails when PROFROD_SITE_REPO is missing. Pinned-source verification runs only from trusted main or manual CI contexts; pull requests never receive the private-source credential. See the CI trust-boundary documentation.

Catalog and status language

• catalog/curriculum.json lists the 11 courses and 13 long-form articles.
• catalog/profrod-site-source-index.json pins their exact source paths and titles.
• catalog/curriculum-manifest.json connects each source item to its local practice guide and verification command.
• catalog/curriculum-maintenance.json records review ownership and due dates.

contract_status: complete means the companion package and its mechanical checks exist. It does not mean the source course or article is reproduced or finished here. maturity describes teaching maturity, while review_status records independent human pedagogical and accessibility review. The current manifest truthfully claims 9 scaffold courses, two developed flagship courses (ZEO ITAM · Autumn 2026 and Agentic Coding with Cursor), 13 mapped articles, and zero operator-reviewed resources. developed records a complete multi-practical teaching contract with direct Site lesson links and independent acceptance; it is not a claim of operator pedagogical or accessibility review.

Contributing practice material

1. Keep source identity and provenance truthful.
2. Add a course-local guided practice and runnable lab, or an article-local exercise with synthetic positive and failure cases.
3. Keep the baseline deterministic, offline, credential-free, and safe to rerun.
4. Include an objective, evidence, rubric, accessibility route, safety/cost boundary, and exact verification command.
5. Run make verify-pr, then the source-backed make verify before requesting review.

Detailed contract rules live in the practice-companion authoring guide. The Transformation Tracker course also has a separate public companion at profrodai/transformation-tracker-course; the small local lab here does not replace it.

Taxonomy and consolidation status

• starter: runnable teaching code already supports a lesson path.
• scaffolded: one functional vertical slice is present; additional labs are intentionally not authored yet.
• mapped: source and documentation are catalogued, but no runnable companion is claimed.

Course directories are courses/<site-course-slug>/; article mappings are articles/<site-article-slug>/. A course may link an external, already-public companion rather than duplicate or migrate it. Article code needs a separate source/licensing and demonstration decision before it is added.

Consolidating approved public companions

The resources repository is the planned maintained home for approved public ProfRod teaching material. The source-to-target registry is catalog/consolidation-sources.json; the readable policy, status table, and gates are in docs/consolidation.md. A mapping records only reviewed provenance and intended destination. It never copies source bodies, rewrites an upstream history, or silently changes a licence.

Two course curricula have been adopted as mapped documentation only:

• Agent Engineering Foundations
• LLM Engineering Essentials

They have no runnable labs until an offline, credential-free vertical slice and course gate land.

Contributing a next lab

1. Add or amend a catalog entry and keep its source pointer truthful.
2. Create a course-local README and a self-contained lab with make run, make test, and make verify.
3. Keep the first run deterministic, offline, and credential-free. Put any live-provider setup behind a later, clearly labelled opt-in decision.
4. Run make verify from the repository root. The catalog validator fails closed if an entry, README, runtime contract, or course gate is missing.

Bootstrap record

The published initial commit contains README.md and LICENSE only. It predates the clarified repository-birth contract in RULING-216 Amendment A2. This PR introduces .gitignore as its first content diff, before any course resource reaches main; the public history is not rewritten to claim otherwise. Future resource repositories start with their required safety .gitignore.

Current runnable course

Course	Directory	What's there
Build Your Always-On AI Agent From Scratch	courses/sovereign-agent-book/	The book's course, imported from sovereign-agent: 38 notebook units with solutions and educator guides, and the chapter code. Its gate (make imported-courses) needs uv and Python 3.14.
Agentic Coding with Cursor	courses/agentic-coding-with-cursor/order-api/	order-api, the small Node/Express/TypeScript order-lookup service the course runs against starting in lesson 4.

The complete map names all remaining source courses. Each gets its own directory under courses/<course-slug>/; nothing is shared across courses unless a later README says otherwise.

Using a course's code

Clone the whole repo, or just the one course you need:

git clone https://github.com/profrodai/profrodai-resources.git
cd profrodai-resources/courses/agentic-coding-with-cursor/order-api
npm install
npm test

From the repository root, run the project gate with make verify. It performs the locked install, format check, tracked agent-exhaust boundary lint, test suite, TypeScript check, and high-severity dependency audit.

Each course directory is self-contained: its own package.json, its own dependencies, runnable on its own without anything else in this repo.

Current companion boundary

The Transformation Tracker public companion remains live while its canonical import is only mapped. The existing labs/01-baseline-delta is explicitly its successor scaffold, not its replacement. The consolidation policy forbids archiving a legacy repository before a reviewed replacement and clear learner redirect exist.

License

The repository is licensed under the MIT License.