Practitioner Handbook
Audience: Engineering orgs adopting AI-assisted delivery (UI, platform, and full-stack)
Goal: Depth over inventory — how to work day-to-day, not a dump of every file in the repo
Version: 1.0 | Updated: 2026-07-16
Purpose
This handbook is the operating manual for teams that ship with AI. Libraries (skills, agents, MCPs, cookbooks) live elsewhere. Here you learn when to reach for which tool, how to keep humans in control, and how to stop wasting tokens and review cycles.
How to use this handbook
- Read Skills vs prompts vs agents once as the shared vocabulary.
- Run your next feature through Context → Planning → HITL → Coding → PR review → Evals.
- Wire hooks and MCP only after the workflow is clear.
- Use cookbooks and patterns as specialist references, not as the sidebar.
Chapters
| Chapter | You will be able to |
|---|---|
| Skills vs prompts vs agents | Stop treating every XML blob as a “skill” |
| How to give context | Build packages agents can actually use |
| How to set up planning | Enforce plan-before-code without ceremony theater |
| Human in the loop | Place approvals where risk is real |
| PR review with AI | Run severity-calibrated reviews that humans still own |
| Evals as quality gates | Block merges on model regressions |
| Hooks in practice | Fail closed before bad artifacts leave the laptop |
| MCP when and how | Add tools without turning agents into confused deputies |
| Containing token waste | Cut cost and noise without starving quality |
| AIDLC roles & evolving delivery | Staff the new jobs AI-DLC creates |
Repo map (start here on disk)
| Concern | Canonical path |
|---|---|
| Behavioral contract | CLAUDE.md |
| Planner pattern | content/patterns/planner-pattern/README.md |
| Implementation plan prompt | content/08-ai-sdlc/prompts/implementation-plan.prompt.md |
| Skills | content/03-skill-engineering/ |
| Agents | content/04-agent-engineering/ |
| Hooks | content/04-agent-engineering/hooks/ |
| MCPs | content/mcps/ |
| Eval gate workflow | .github/workflows/eval-gate.yml |
| React cookbook (UI depth) | content/cookbook/react/README.md |
| Normative controls | content/standard/ |
Design rule for this handbook
If a page is only a list of links, it does not belong here. Push catalogs to Skills, MCPs, Cookbook, and Patterns. Keep this folder for teachable practice.
Checklist — handbook readiness for an org
- Engineers can name the difference between prompt, skill, agent, hook, and MCP
- Every multi-file change has a plan approval recorded
- PR review uses severity + verification, not “LGTM from the bot”
- Eval gate exists for user-visible model behavior
- Token budgets are measured, not vibed
- Roles for AI-DLC (plan approver, review owner, eval owner) are named
Changelog
- 2026-07-16: Introduced practitioner handbook spine and curated navigation.
Version: AIES v1.0.0✏️ Edit this page on GitHub