Execution Playbook
Build the MasteryMade Embeddable Agent
Paint-by-numbers guide to building a generic embeddable AI agent that reads any HTML page and guides users through its content. Uses Claude Code as the builder. You are the quality checker.
⏱ 2-4 hours
🔧 Claude Code + Terminal
📦 Output: mastery-agent.js (< 50KB)
What You're Building
A single JavaScript file that embeds on any HTML page via a script tag. On load, it reads the page content and a JSON config, then renders a floating chat panel that guides users through the content — executing playbooks step by step, answering questions about proposals, or searching meeting dashboards.
One engine. Three deployment contexts. Differentiated by config, not code.
├── Visible content
├── <script id="mastery-agent-config">
├── <script id="mastery-agent-data">
└── <script src="mastery-agent.js">
│
├── On Load: Read config → Parse HTML → Load enrichment → Load progress → Render chat
├── On Message: Build prompt → Call API → Render response → Save progress
└── On Close: Save conversation + progress to localStorage
How to Use This Page
With Claude Code: Share this page's URL with Claude Code. It will read the visible steps AND the hidden JSON enrichment (which contains the full PRD technical specs, file structure, schemas, and acceptance criteria). Tell Claude Code to read the page, then follow the steps.
As a help assistant: Open a second Claude window, paste this page's URL, and use it to ask questions about the build while Claude Code executes. The two don't share context, but they both have access to the same spec.
Set up the project folder, initialize npm, install esbuild, and create the folder structure. This is the only step you do manually before handing off to Claude Code.
$ mkdir mastery-agent && cd mastery-agent
💬 Say to Claude Code
Initialize a Node.js project for a browser-embeddable JavaScript bundle. We need esbuild as a dev dependency. The build script should bundle src/agent.js into dist/mastery-agent.js as an IIFE (self-executing function). Add a dev script that watches for changes and serves the test/ directory. No other dependencies — this is a zero-dependency browser bundle. Create the folder structure: src/, dist/, test/, styles/.
- Run the terminal command to create and enter the project directory
- Give Claude Code the initialization prompt
- Verify package.json has esbuild in devDependencies
- Verify build and dev scripts exist
- Verify src/, dist/, test/, styles/ folders exist
✅ Verify
Run
cat package.json — esbuild in devDependencies, build/dev scripts present. Run
ls — src, dist, test, styles folders visible.
This is the most important step. Claude Code needs the full technical specification before it writes a single line. Share this page's URL or paste the enrichment JSON content.
💬 Say to Claude Code
I'm building an embeddable AI agent. Here is the full spec page: [THIS PAGE'S URL]. Read the entire page including the hidden JSON blocks (id="mastery-agent-config" and id="mastery-agent-data"). The mastery-agent-data JSON contains the complete PRD — file structure, HTML schema, config schema, heuristics spec, UI spec, and acceptance criteria. Read it all before doing anything, then tell me what you understand the build order should be.
- Share this page's URL with Claude Code (or paste the enrichment JSON)
- Wait for Claude Code to confirm it understood the spec
- Verify Claude Code's proposed build order makes sense (parser → config → heuristics → API → progress → chat UI → main entry)
⚠️ If Claude Code seems confused
Copy specific sections from the enrichment JSON and paste directly. Say: "Re-read this section carefully" then paste the relevant spec section.
The parser extracts structured content from the host page. It looks for data-mastery attributes first, falls back to generic h1-h4 / p / pre / a extraction if none found.
💬 Say to Claude Code
Build src/parser.js. Follow the parser specification from the spec. It needs to: 1) Extract data-mastery attributed elements (title, steps with substeps, content sections, decisions, action items, links, code blocks), 2) Fall back to generic HTML parsing when no data-mastery attributes found (extract h1-h4 as topics, p as content, pre>code as code, a as links), 3) Return a structured object with: title, steps[], content[], decisions[], actionItems[], links[], codeBlocks[]. Export the parsePage function.
- Give Claude Code the parser prompt
- Open src/parser.js and verify it has parsePage() function
- Verify it queries for all data-mastery attributes from the schema
- Verify fallbackParse() function exists and works on generic HTML
- Verify it exports parsePage
Three files that work together: config reads the JSON from the page, heuristics contains the "chef's brain" system prompt template, prompt-builder assembles everything into the final system prompt sent with each API call.
💬 Say to Claude Code
Build three files: 1) src/config.js — reads JSON from script tags with id="mastery-agent-config" and id="mastery-agent-data". Validates required fields (minimum: mode). Merges with defaults per the config schema in the spec. Export loadConfig and loadEnrichment. 2) src/heuristics.js — the static system prompt template. Contains ALL the core behaviors, anti-slop rules, mode-specific instructions, and progress commands from the spec. Template placeholders for dynamic content. Export getHeuristics. 3) src/prompt-builder.js — takes (config, pageContent, enrichment, progress) and fills the heuristics template with real data. Steps formatted with substeps and completion status. Export buildPrompt.
- Give Claude Code the combined prompt for all three files
- CHECK CAREFULLY: Open src/heuristics.js — verify ALL anti-slop rules are present
- Verify execution mode has: orient, instruct, verify, advance, adapt behaviors
- Verify prompt-builder takes 4 inputs and returns a complete string
- Verify config.js handles missing/malformed JSON gracefully (defaults, no crash)
⚠️ If the heuristics feel generic
Say to Claude Code: "The heuristics need more teeth. Add: 1) Every response must reference THIS specific page content — if it could apply to any page, it's too generic. Redo. 2) Code must be complete and copy-pasteable. 3) When a step has a link, tell user exactly what to do after opening it. 4) Never say 'it depends' without resolving the dependency."
💬 Say to Claude Code
Build: 1) src/api.js — fetch wrapper for Anthropic Messages API. Takes messages array, system prompt, config. Uses config.api.model, config.api.maxTokens. Supports config.api.proxyUrl (if set, calls proxy instead of api.anthropic.com). Try/catch with friendly error messages, never expose stack traces. Export sendMessage. 2) src/progress.js — localStorage keyed by page URL (btoa(url).slice(0,32) as key). Stores: currentStep, completedSteps[], completedSubsteps{}, conversationHistory (cap at 20 messages), startedAt, lastUpdated timestamps. Export loadProgress, saveProgress.
- Give Claude Code the prompt
- Verify api.js supports proxyUrl and has error handling
- Verify progress.js caps conversation at 20 messages
- Verify localStorage key derives from page URL
💬 Say to Claude Code
Build src/chat.js with embedded CSS (no separate file). Requirements: 1) Shadow DOM for complete style isolation from host page. 2) Collapsed state: 48x48px circular button with avatar emoji, subtle pulse animation, positioned per config. 3) Expanded: panel at config width × maxHeight, rounded corners, dark background, slide-up animation. 4) Layout: header (name + progress bar) → message area (scrollable) → input (text + send button). 5) Messages: user right-aligned tinted primaryColor, agent left-aligned dark. 6) Code blocks in responses: monospace, dark bg, copy button. 7) Links in responses: clickable, open new tab. 8) Responsive: full-width bottom sheet under 768px. 9) CRITICAL: Vanilla JavaScript ONLY — no React, no frameworks. Use document.createElement and DOM manipulation. All CSS injected as string into shadow root.
- Give Claude Code the chat UI prompt
- Verify Shadow DOM usage (attachShadow in the code)
- Verify CSS is embedded as string, injected into shadow root
- Verify no React or framework imports
- Verify collapsed/expanded toggle, message rendering, code copy, link handling
⚠️ If Claude Code creates React
Say: "This must be vanilla JavaScript. No React, no Vue. It's a self-contained script for any HTML page. Use document.createElement."
💬 Say to Claude Code
Build src/agent.js as the main entry point. Self-executing IIFE on load. Flow: 1) loadConfig(), 2) parsePage(), 3) loadEnrichment(), 4) loadProgress(window.location.href), 5) buildPrompt(config, pageContent, enrichment, progress), 6) renderChat(config, progress, systemPrompt). When user sends a message: append to conversation history → call sendMessage API → render response → update progress → saveProgress. Import all modules we built. Then run npm run build and fix any import/export issues until we get a clean dist/mastery-agent.js bundle.
- Give Claude Code the main entry point prompt
- Run: npm run build
- If build fails — paste the error to Claude Code: "Build failed with [error]. Fix it."
- Verify dist/mastery-agent.js exists
- Verify file is under 100KB (ideally under 50KB)
💬 Say to Claude Code
Build three test pages that embed dist/mastery-agent.js: 1) test/test-playbook.html — "Build Your Own 24/7 AI Assistant" playbook using full data-mastery schema. 8 steps with substeps. Config: execution mode. Include enrichment JSON with code snippets for steps 0-3. Must look like a real styled content page. 2) test/test-proposal.html — Mock JV proposal for "Brad Himel - Newsletter Growth Partnership." data-mastery="content" sections for terms, revenue share, timeline. Config: qa mode, consultative tone. 3) test/test-dashboard.html — Mock MasteryOS meeting dashboard. 3-4 meeting summaries, action items with owners, decisions. Config: search mode.
- Give Claude Code the test pages prompt
- Start dev server: npm run dev
- Open test-playbook.html — agent button visible, click to open, type "begin"
- Test step guidance: agent gives specific instructions, asks for confirmation
- Test "status" command — shows progress
- Reload page → open chat → "status" — progress persisted
- Test off-topic: ask "What's the weather?" — should redirect
- Test mobile: devtools → device toolbar → verify bottom sheet layout
- Open test-proposal.html — QA mode works, answers about proposal content
- Open test-dashboard.html — search mode works, finds action items by owner
✅ Write down every bug
List every issue you find. After testing all three pages, paste the full bug list to Claude Code: "Here are the issues I found: [list]. Fix all of them."
💬 Say to Claude Code (cleanup)
Review all source files. Remove: console.log statements, commented-out code, hardcoded values that should be in config, unresolved TODOs. Then run npm run build for the production bundle.
💬 Say to Claude Code (API proxy)
Build a Cloudflare Worker that proxies Anthropic API requests. It accepts POST requests with the same body as the Anthropic Messages API, adds the API key server-side (from Cloudflare secret), forwards to api.anthropic.com, returns response with CORS headers. Give me the worker code and deploy instructions.
- Run cleanup prompt
- Run: npm run build — verify clean output, no warnings
- Verify dist/mastery-agent.js is under 100KB
- Build the Cloudflare Worker proxy
- Deploy worker, set ANTHROPIC_API_KEY as secret
- Update test page config: set api.proxyUrl to worker URL
- Host test pages (GitHub Pages, Vercel, or Cloudflare Pages)
- Test the hosted version — agent works through proxy, no API key exposed
- Create README.md: what it is, how to embed, config schema, HTML schema
Share the hosted test-playbook.html with community members. The entire thesis rests on one question: do users with the agent get further than users with just the static page?
- Share URL with 3-5 people from your community
- Ask them to: open page, click agent, say "begin", follow for at least Steps 0-2
- Collect: where they got confused, where agent helped, where agent failed, where they quit
- Compare: how far do people typically get with just the static playbook?
- If 2x+ completion improvement → thesis holds → invest in value ladder tiers
- If similar completion → heuristics need work, or format needs work — iterate
Done Checklist — Verify All Before Sharing
- Agent loads on test-playbook.html via script tag
- Clicking button opens chat panel with animation
- "begin" starts step-by-step guidance
- Agent gives specific instructions (not generic)
- Agent asks for confirmation before advancing
- "status" shows current progress
- Progress survives page reload
- Off-topic questions get redirected
- Code blocks have copy buttons
- Links open in new tabs
- Mobile layout works (bottom sheet)
- No API key exposed in client code
- No errors in browser console
- QA mode works on test-proposal.html
- Search mode works on test-dashboard.html
- README exists and is accurate