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-agnostic in principle; Claude Code as the concrete example. The concepts and workflow never depend on one LLM or tool. Name the common agentic tools once, then use Claude Code as the worked example in commands and labs — e.g. claude --version # sub your own agent. Keep the concepts vendor-neutral; use a concrete tool so steps aren't abstract. 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.

What the course teaches about git (the reframe)

This is not a "memorize git commands" course. The reader should finish knowing git is critical, understanding the concepts and the basics, and — above all — that they don't have to memorize commands because the AI drives git for them. The analogy: learn arithmetic by hand, then use a calculator.

• Modules 1–3 teach the mechanics by hand, on purpose. The AI is still in the browser; the learner types git to build intuition. Keep that.
• Module 4 is the pivot. It puts the AI in the editor/CLI. From there on the learner directs the AI to do the git work (commit, branch, merge, revert, decide what to commit) and verifies the result — they don't type the commands by hand, and modules must not tell them to.
• Don't re-teach basics. Once a concept is introduced, later modules build on it through the AI; they don't re-explain how to create a branch, etc.

Lesson vs. lab (keep them separate)

• The lesson / Key-concepts section is theory. To show a command, show it with example output as illustration — never instruct the reader to run it there.
• All hands-on execution lives in the lab. The lesson must not duplicate commands the lab runs.

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.

No slop. Don't write like an AI. Avoid "prose" (say "writing", "words", or "docs"), "unlock", "leverage" as filler, "delve", "dive in", "seamless", "in today's fast-paced", "it's worth noting". Don't lean on em-dashes — at density they read as a machine tell; vary the punctuation.

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.