Guide-Based Development — Shapes of Intelligence

What this is

Every guide on this site has the same shape. A masthead. An explanation. Content sections. An agent instructions block with numbered steps and approval gates. A patterns section linking back to book chapters. A start box with copyable commands and a handoff prompt. Same CSS. Same typography. Same dark theme. Same bones.

This page describes that shape precisely enough that an agent can replicate it. You tell the agent what your guide is about. The agent builds the page. You review it. The guide enters the world already formatted, already linked, already consistent with every other guide on the site.

This is the Solved Problems Stay Solved chapter applied to guide creation itself. The format is a solved problem. Don't re-solve it every time.

The anatomy

Every guide has these sections, in this order. Some are optional, but the order never changes.

Required sections

Masthead Breadcrumb, h1 title, subtitle. The breadcrumb links back to index.html. The subtitle is one sentence, max 55 characters wide. always

What this is 2-3 paragraphs. What the guide does, why it exists, what book chapter it implements. Link to the chapter. always

Content sections The meat. h2 for major sections, h3 for subsections. Separated by hr dividers. This is where the guide teaches. always

Agent instructions A teal-bordered block with numbered steps. Approval gates between steps. Key rules paragraph at the end. always

Patterns at work Links to book chapters that this guide implements. Bold chapter title, em-dash, one-line description. always

Start box Copyable commands: cd to work folder, mkdir, cd, launch agent, paste handoff prompt with page URL. always

Footer "Part of Shapes of Intelligence" link + GitHub link. always

Optional sections

Output structure File/folder layout the agent creates. Uses source cards with name, description, and optional badges. if applicable

Data sources Where the guide reads from. Same source card format with frequency badges (weekly, monthly, etc). if applicable

Related guides Links to other guides on the site. Separate patterns block with purple label. if applicable

The design system

Typography

Headings: Fraunces, serif. Weight 300 for h1 (2rem), weight 500 for h2 (1.05rem) and h3 (0.88rem).

Body: DM Mono, monospace. 0.78rem for paragraphs and list items. Line-height 1.8.

Emphasis: strong renders in bright white. em renders in amber, no italics.

Color

Background stack: void (#0a0a10) → deep (#0f0f1a) → surface (#161625) → raised (#1e1e32). Darker = further back.
Text stack: muted (#8888aa) → text (#d0d0e2) → bright (#eeeef5) → white (#f5f5ff). Brighter = more important.
Accent colors: amber for links and actions. Teal for agent/system elements. Purple for metadata. Rose for warnings. Blue for informational.

Components

.cmd — Copyable command. Click to copy. Amber border flash on success. Contains code + copy icon SVG.
.agent-block — Instructions for the AI agent. Teal left border. Numbered ol with approval gates.
.source / .source-group — Data cards. Deep background, flex layout: name (bright, bold) | description (muted) | badge (teal on raised).
.patterns — Chapter/guide links. Deep background, purple label. List of linked items with em-dash descriptions.
.start-box — How to start. Deep background, amber label. Multiple .cmd blocks + handoff prompt with dynamic URL.

Responsive

Two breakpoints. Tablet portrait (min-height 1000px, max-width 800px) scales everything up ~25%. Mobile (max-width 600px) wraps source cards and tightens padding. The shell max-width is 680px.

The agent instructions block

This is the most important part of any guide. It's the section the agent reads when someone pastes "Follow the instructions on this page." Every guide has one. The structure is always the same.

The pattern

Opening instruction. One bold sentence: "Walk the user through X, one step at a time."
Numbered steps. Each step has a bold title and a plain-text explanation. Steps that produce output say "Show the user" or "Wait for approval."
Approval gates. The agent does not proceed past a gate until the user confirms. Gates appear after interview, after output review, after any write that touches system config.
Key rules paragraph. At the bottom. Safety constraints, scope limits, what the agent should refuse to do silently. Always includes: "If anything looks unsafe or beyond what the user would reasonably want, say so."

What makes a good step

One action per step. Don't combine "read the data" and "propose metrics."
Steps that read data come before steps that write data.
Steps that need human judgement have explicit approval gates.
The last step is always a summary or self-assessment — the agent reviews what it built.

The handoff prompt

Every guide ends with a start box containing three copyable commands:

cd <project-root> && mkdir project-name && cd project-name — navigate to your own project root and create the project folder. On PowerShell, use the same pattern with your Windows path.
claude — launch the agent. (With a note: "Or use codex, gemini, or whichever agent you prefer.")
The handoff: Follow the instructions on this page. If anything looks unsafe or beyond what I'd reasonably want, tell me before doing it: [page URL]

The page URL is injected dynamically by JavaScript using window.location.href. This means the handoff prompt works regardless of where the page is hosted.

When an agent receives this prompt, it fetches the page, finds the agent instructions block (the HTML comment above it says "This is the section you follow"), and works through the numbered steps with the user.

Adding a new guide to the site

The file

Create reference/_meta/static/your-guide.html. Copy the HTML structure from any existing guide. The CSS is self-contained in each file — no shared stylesheet, no framework. This is intentional: each page is a standalone document that can be read, copied, or served independently.

The index card

Add a card to reference/_meta/static/index.html. The card needs a title, one-line description, accent color, and tag (e.g., "full guide", "reference", "changelog").

Cross-links

Add the new guide to the "Related guides" section of any guide it connects to. If it implements a book chapter, add it to that chapter's "see also" if one exists.

Build and deploy

build.sh copies static pages to reference/site/. Deploy with rsync. The /publish skill handles the full checklist.

Instructions for you, the AI agent

Build a new guide page for the user's topic, following the established pattern exactly. Every section has an approval gate. Do not skip ahead.

Interview. Ask the user: What is the guide about? What problem does it solve? Which book chapter does it connect to? What data sources or systems does it involve? What should the output folder structure look like? Get enough context to write the page. Wait for answers.
Draft the masthead. Propose a title, subtitle, and breadcrumb. The subtitle should be one sentence that captures the guide's purpose. Show for approval.
Write the "What this is" section. 2-3 paragraphs. What the guide does, why it matters, what chapter it implements. Link to the chapter. Show for review.
Write the content sections. This is the guide's teaching material. Use h2 for major sections, h3 for subsections. Include data source cards, output structure cards, or examples as needed. Separate sections with hr dividers. Show each section for review before writing the next.
Write the agent instructions block. Numbered steps with approval gates. One action per step. Reading before writing. Human judgement steps gated. Key rules at the bottom. Show the full block for review.
Write the patterns section. Link to every book chapter this guide connects to. Bold title, em-dash, one-line description. Add a related guides section if the guide connects to other site pages. Show for review.
Assemble the page. Combine all approved sections into a complete HTML file. Use the standard CSS (copy from any existing guide). Add the start box with the three copyable commands. Add the footer. Write to reference/_meta/static/.
Add the index card. Add a card for the new guide to reference/_meta/static/index.html. Choose the accent color and tag. Show for approval.
Cross-link. Add the new guide to the "Related guides" section of any connected guide pages. Add it to the slush pile's open threads as completed.
Build and verify. Run bash reference/_meta/build.sh and confirm the page appears in the site output. Open in browser if possible.

Key rules: Use the exact CSS from an existing guide — do not invent new styles unless the content genuinely requires a new component. Keep the same typography, colors, spacing, and responsive breakpoints. Every guide is a standalone HTML file with no external dependencies beyond Google Fonts. The agent instructions block must include approval gates and a key rules paragraph. If the user's topic doesn't naturally fit the guide format (no clear agent workflow, no repeatable steps), say so — not everything is a guide.

Patterns at work

Solved Problems Stay Solved — the guide format is a solved problem. This page makes sure it stays solved.
Memory Is Files — each guide is a file. The agent reads it, follows it, and the knowledge persists without anyone memorizing it.
The Steering File — the agent instructions block is a steering file for a single task. One read, permanent behavior change.
The Correction Is the Conversation — each guide was refined through conversation. The corrections became the instructions.
We All Invented Calculus — the guide format is a shape that emerged from building six guides. This page documents the inevitable discovery.

Related guides

The Flywheel Follows the Action — when guides, transcripts, and corrections start improving the next run
Flywheel — mine your own process to find the next guide that needs building
Slush Pile — where guide ideas sit before they become pages
Maintenance — keeping existing guides current
Zero to Dev — the first guide most people need

External references

Diátaxis — Daniele Procida's framework for technical documentation (tutorials, how-to, explanation, reference)
Claude Code Tutorials — Anthropic's official guide format for comparison

How to start

Open your terminal, navigate to the repo, and start an agent. Tell it what guide you want to build.

cd /path/to/aibook

Use the actual path where you cloned the repo. PowerShell uses the same cd pattern with your Windows path.

claude

Or use codex, gemini, or whichever agent you prefer.

Follow the instructions on this page. I want to build a guide about [your topic]: