ai-workflow-course/AGENTS.md

AGENTS.md — instructions for AI agents working in this repo

This is the committed AI instructions file for The Workflow course. It exists for two reasons: it actually configures the agents that help author the course, and it is a live worked example of Module 5 — Commit the AI's Config, Not Just the Code. The filename is deliberately vendor-neutral: most agentic coding tools read a repo-level instructions file, and the principle outlives any one vendor's filename. If your tool looks for a different name, point it here.

What this repo is

A course that teaches IT professionals the engineering toolchain around AI coding — version control, collaboration, CI/CD, and the tools that extend AI into real systems. The repo is both the course content and a dogfooded example of the practices it teaches.

• Source of truth for structure: the-workflow-syllabus.md. Don't re-derive decisions it settles; read it first.
• Build-context for authoring: handoff.md. The "how" of building, plus the owner's settled decisions.
• Every module follows _TEMPLATE.md. Don't invent a new shape per module.

Core promises (do not violate)

• Model- and vendor-agnostic. Never pin a lesson to one LLM vendor. Never hardcode a specific tool's config filename — say "your agentic tool's committed instructions file." Examples must survive a model swap.
• GitHub is the default, not the requirement. Keep hosting content provider-neutral; name the alternatives and the self-host track. Do not reintroduce a single specific forge as the answer.
• The dependency chain is load-bearing. A module may assume only what precedes it. Never reference a tool before its introducing module. If you think something should move, flag it — don't silently reorder.
• Honesty about limits. Where a tool or analogy breaks, say so. Don't sand off the caveats.
• Don't pad. This audience reads fast and trusts concrete over comprehensive. Lead with the pain, show the command and the failure mode.

Voice

Direct, concrete, rigorous. Reframe ops instincts the reader already has toward AI-assisted work. No motivational filler. When in doubt, show the command and what goes wrong without it.

Conventions for labs

• Labs run on the learner's own machine, any OS. Don't assume a sandbox, cloud account, or specific shell beyond what's stated.
• Lean on Python or shell, chosen per lab, kept minimal. State the language once per lab.
• Every module ends at a keyboard (a lab), not a quiz, and has a concrete "you're done when…" check.

Working in this repo (dogfooding the course)

This repo is hosted on git.jpaul.io. Follow the same flow the course teaches:

• Never commit directly to main. Branch per module/change, open a PR, squash-merge. The PR is the review gate (Module 10) even for solo work — it exists for traceability.
• Build in dependency-chain order. Modules 1–2 are the locked exemplars; match their tone, depth, and lab style.
• Verify before publishing volatile claims. Anything about pricing, versions, or tool behavior (especially the Module 8 hosting comparison) must be checked at build time, not written from memory. Mark such claims with a "Verify-before-publish" note.

Don't

• Duplicate or fork the-workflow-syllabus.md — edit it in place if structure changes.
• Reorder modules or break the dependency chain without flagging it.
• Pin to a specific LLM vendor or a specific tool's config filename.
• Write pricing/version claims from memory.
• Pad.