Architecture

Overview

1. 01

   AI agents

   Nine Claude Code subagents collect and debate; the parent session writes the notes and publishes them. Output accumulates in an LLM wiki (a knowledge base the LLM writes from primary sources and maintains with cross-links); weekly and monthly watches run automatically.

2. 02

   Delivery system

   Astro builds static pages; a single Cloudflare Worker serves them. Workers AI in the same runtime powers the "Ask the notes" chat. Runs within the free tier.

3. 03

   Design system

   DESIGN.md is the source of truth; colour, type, and spacing are implemented as three token layers. Every edit is machine-checked for contrast and consistency, and a review agent checks qualitatively at the end.

In numbered order: agents write the notes, the delivery system publishes them, and the design system decides how they look. The four connections between the three are at the end of the page.

Subagents

9

Published notes

180 JA, 177 EN

Hooks (automatic checks)

6

Contrast checks

7 pairs × 2 themes

Running cost

Free tier

What this setup shows I can take on

Of the four, cloud configuration and putting generative AI into a product also appear in the work list; the automated design-system checks and the agent controls have this site as their first working example.

• Designing systems that use AI

  Choosing models per role, dividing work among agents, a single-writer rule for who edits what, and guardrails. I can build the structure and controls for putting generative AI into an operation, and make it run.

  Evidence: Area 01 , Generative AI projects

• Delivery and operations infrastructure

  Configuration on the cloud (Cloudflare Workers), CI/CD (automatic checks and publishing on every change), and operation with a fixed cost ceiling. I can design infrastructure that keeps publishing, small and reliable.

  Evidence: Area 02 , Cloud projects

• Building a design system with automated checks

  Three layers of source, tokens, and components, plus a mechanical check and a review on every edit. I can make design decisions verifiable.

  Evidence: Area 03 , Design-system notes

• Designing the connection between the two

  Embedding design checks in the development flow and feeding knowledge into both public pages and chat. I can hold the decisions at the boundary between design and systems myself.

  Evidence: Connections , Ask the notes

Area 01

AI agents

The machinery that turns research into notes. A person plans and signs off; subagents do the work.

Decided

• Requests come in through skills (procedures), the work goes to nine subagents, and only the parent session writes files
• Debate runs on Claude Opus, collection and checks on the lighter Sonnet, and the largest model, Fable, only when named per run
• Output accumulates in a three-layer LLM wiki (primary sources, wiki, schema), and every published note ends with its references

Why

Depth of argument and token cost pull against each other. Splitting models by role and tracking sources in a ledger keeps the conclusions of a debate verifiable afterwards.

How it is checked

• Hooks (checks that run before and after a tool call) block writes to the immutable area, access to secrets, and launches with a missing dispatch header
• The Stop hook keeps the session from ending until the wiki health check (seven kinds) reaches zero
• A debate runs once, on evidence fixed in advance, and the record lists the consumption per agent

Details (skills, agents, hooks)

Skills

A skill is the procedure for one type of request. It starts from how the request is phrased and branches on its required input.

Skill	Type of request	Required input	Agents it calls
source-collection	Collect papers, AI news, or industry information	mode (academic, ai-frontier, industry)	source-researcher and others
critical-review	Critical reading of a note	lens (design-theory, pedagogy, industry-career)	academic-critic
industry-perspective	Role arguments from an industry persona	persona (design-firm, strategy-consulting, independent-office)	practice-auditor, industry-lead
designer-role-roundtable	Joint industry and academic debate	question, target note, year range	the four debate agents
wiki-ingest	Ingest material into the wiki	material and target page	none
wiki-lint	Wiki health check	none	none
doc-write	Procedures under docs	destination, verified facts	doc-writer
ui-design-implementation	Build or revise UI	target page	design-reviewer
design-system-check	Verify the design system	none	design-reviewer

Agents

Agents are read-only and return results; the parent session does the writing. The role is switched by the dispatch header on the first line of the prompt.

Agent	Group	Model	Dispatch header
industry-lead	Debate	Opus	persona (design-firm, strategy-consulting, independent-office)
practice-auditor	Debate	Opus	lens (revenue-viability, differentiator-reality, evidence-methodology, liability-provenance, demand-side)
disruption-provocateur	Debate	Opus	axis (historical-disruption, global-arbitrage, platform-power, end-user-indifference)
academic-critic	Debate	Opus	canon (design-theory, design-education, design-industry)
source-researcher	Collection	Sonnet	profile (scholarly, vendor-primary, official, analyst, developer-voice, expert-commentary, labor-market)
paper-screening-agent	Collection	Sonnet	none
docs-researcher	Collection	Sonnet	none
design-reviewer	Review	Sonnet	mode (system-health, ui-analysis)
doc-writer	Documents	Sonnet	none (writes under docs)

Hooks

A hook is a check Claude Code runs before or after a tool call or at the end of a session. Some block the operation; others prompt the next action.

Event	Hook	What it does
PreToolUse	guard-paths	Blocks writes to raw/, reads or writes of secrets, and writes of notes that contain unpublished research without a privacy flag (draft or so_theory)
PreToolUse	dispatch-header-gate	Blocks a launch whose header is missing or carries a value outside the allowed set
PostToolUse	design-system-gate	After an edit to CSS or a page, runs the mechanical check and returns the result
PostToolUse	claude-assets-sync, readme-sync	After an edit that touches .claude or the README, prompts an update of the asset list and the README
Stop	stop-wiki-gate	If wiki/ has changes, runs wiki:lint and blocks the end of the session while violations remain (G1)

Area 02

Delivery system

The infrastructure that delivers the notes and the chat cheaply and without downtime.

Decided

• Astro generates static pages; a single Cloudflare Worker serves them
• The "Ask the notes" chat runs on Workers AI in the same Worker (Llama 3.3 70B)
• Operate within the free tier, with Workers AI as the only external binding

Why

Putting delivery and the API in one runtime keeps the configuration in a single file, so local and CI deploys follow the same steps.

How it is checked

• On every push to main and every pull request, CI runs the wiki health check, type checks, and the build
• Deployment config lives in git and publishing is one command
• External links in published notes are checked weekly, and a gap of more than seven days between watches raises an alert

Details (components, Ask the notes, automated jobs)

Components

Delivery and the API sit in one Worker, and the configuration lives in git as code.

Component	Role	Why this one
Astro 6	Static-site framework that ships no JS by default	Static generation suits a notes-centred site, and the Cloudflare adapter puts it straight onto a Worker
Cloudflare Workers (Static Assets)	Serves the built static assets from a single Worker and runs only /api/chat server-side	Delivery and the API share one runtime, and the free tier (100,000 requests a day) is enough
Workers AI	Runs the generation model for "Ask the notes" (Llama 3.3 70B)	Callable from the same Worker through one binding, within the free tier (10,000 Neurons a day)
wrangler	Gathers the name, compatibility date, routes, and AI binding into one config file and deploys	Deployment config lives in git, so local and CI use the same steps
Custom Domain	Assigns the apex domain directly to the Worker	Cloudflare creates and renews DNS records and certificates
GitHub Actions	Runs the CI checks and publishes after the automated watches	Updates and publishing continue whether or not a PC is on
Tailwind CSS 4	Defines tokens in @theme and composes pages from utilities	Tokens and class names map one to one
TypeScript 6	Type checking through astro check	Used for the type-check gate and in CI
mermaid 11	Renders diagrams in notes on the client	Loaded only on pages with a diagram; on failure the source is shown
p5.js 2 and CodeMirror 6	Sketch and in-place code editor for the home hero (currently hidden)	Only the modules in use are loaded, dynamically

Ask the notes

The chat has two stages, search and generation, with no external search service. Only the published Japanese notes are in scope.

Stage	What it does	Where it runs
Ingest	Embeds the published Japanese notes in the bundle at build time; drafts and confidential blocks are removed	astro build
Search	Scores character-bigram matches with extra weight for Latin words and exact matches, then picks the top four. No dependencies	/api/chat in the Worker
Generate	Injects the four excerpts (about 2,400 characters each) into the system prompt; Llama 3.3 70B answers	Workers AI (free tier, 10,000 Neurons a day)

Automated jobs

The recurring watches and checks run on GitHub Actions and do not depend on anyone’s PC.

Job	When	What	Output
Weekly AI watch	Monday mornings	source-collection (mode: ai-frontier) gathers the past seven days of "AI and design" news from three tiers of sources	Weekly note (Japanese and English) with a source ledger; pushed and published automatically
Monthly scholarly watch	First Monday of the month, before the weekly	source-collection (mode: academic) gathers and screens the past month of peer-reviewed papers and preprints	Monthly note (Japanese and English) and a corpus
Gap detection	Before the weekly watch (the alert fires after publishing)	If more than seven days have passed since the last weekly note, the job fails after publishing	A GitHub failure notification
Link reachability	Before the weekly watch	Checks the external links in published notes; continues on failure	A log (a person decides on replacements)
CI checks	Every push to main and every pull request	Wiki health check, type check, build	Pass or fail

Area 03

Design system

The mechanism that keeps visual decisions in one place and ties implementation to checks.

Decided

• DESIGN.md (a design analysis of Pinterest) is the source of truth; every implemented value maps back to it
• Colour, type, and spacing are implemented as three token layers (raw values, meaning, components)
• Decisions the source does not cover (dark theme, hover, Japanese typeface) keep their rationale in code comments

Why

A one-to-one mapping between the source and the implementation makes visual decisions traceable. Rationale kept in code lets AI agents edit under the same discipline.

How it is checked

• Every edit to CSS or pages triggers a hook that runs the mechanical check (seven contrast pairs in both themes, token parity, hard-coded colours)
• The design-reviewer agent then reviews qualitatively and returns a verdict

Details (source and tokens, themes and type, checks)

Source and tokens

DESIGN.md (a design analysis of Pinterest) is the source of truth, and colour, type, and spacing are implemented as three token layers. Pages reference only the semantic layer, never a primitive directly.

Layer	Role	Examples
primitive	Copies the colour, typeface, and radius values from DESIGN.md as they are. Lives in Tailwind’s @theme	--color-primary #e60023, --color-surface-card, --radius-md 16px
semantic	Names by purpose; the single place where light and dark swap values. Lives in :root and .dark	--background, --foreground, --muted-foreground, --link
component	Bundles semantic tokens into component classes. Lives in @layer components	.btn-primary, .tag, .link, .prose, .t-headline

Themes and type

Decisions the source does not cover (dark, Japanese text, hover) are added as site extensions, with the rationale kept in code comments.

Item	Decided	Basis
Light and dark	Switched by a dark class on html; without a saved choice, follows the OS. The floor is surface-dark #262622 and body links move to a lighter red	DESIGN.md. Brand red reaches only 3.2:1 on the dark floor; text keeps 4.5:1 (WCAG AA)
Typefaces	Inter Variable and Zen Kaku Gothic New are self-hosted; JetBrains Mono for code only. Hierarchy comes from weight, not colour	The stated substitute for Pin Sans (DESIGN.md); hierarchy by weight
Japanese setting	Wraps at phrase boundaries and keeps small kana and long-vowel marks off the line start. Line height is 1.7, wider than for Latin text	Leaving it to the OS changes the voice per device; phrase wrapping uses Chrome’s auto-phrase
Use of colour	Pinterest Red is used only for CTAs, the current-page marker, and the wordmark, never for text	DESIGN.md
Shape and shadow	Two radii, 16px and 32px. No shadow on cards; only the modal has one	DESIGN.md
Spacing and width	8px unit. Max width 1280px, measures of 60ch and 75ch. Dividers are rules, not shadows	DESIGN.md

Checks

The checks run mechanically on every edit, and an agent reviews qualitatively at the end.

Check	Scope	When it runs
Contrast	Four text pairs at 4.5:1 or better and three surface and rule pairs at 3:1 or better, in both light and dark	A PostToolUse hook runs it after an edit to CSS, .astro, or DESIGN.md
Token parity	Whether the five main semantic tokens are defined in :root and overridden in .dark	The same hook
Hard-coded colour	hex, rgb, hsl, and oklch literals in .astro files under src	The same hook (returned as a warning)
Qualitative review	Whether the three layers hold, the source and the implementation agree, both themes read well, and no class is undefined	design-reviewer (mode: system-health) from the design-system-check skill; passes when the mechanical check exits 0 and the review says pass
UI analysis	The target page on five points: typography, layout, colour, responsiveness, consistency	design-reviewer (mode: ui-analysis) from the ui-design-implementation skill, graded on a five-step scale

Where the areas connect

When each area has a different owner, decisions fall through the gaps between them. Here the gaps are narrowed to four places, each turned into a mechanism.

• Design × AI

  Design checks run inside the development flow

  The moment CSS or a page is edited, a hook runs the mechanical check and returns the result to the editing agent. The design system disciplines the implementation without waiting for a human eye.

• AI × Delivery

  Notes flow into both public pages and chat

  Notes written by agents become public pages at build time and, at the same time, the search corpus for the chat. Drafts and confidential blocks are removed from both under the same rule.

• Delivery × Design

  Design assets ship with the delivered site

  Japanese and Latin typefaces are self-hosted and served as static assets of the Worker, and the theme is initialised by an inline script before first paint. The look does not depend on external CDNs or late loading.

• Design × AI

  Design decisions are recorded in the wiki too

  UX reviews and design-system deliberations end as notes, listed in the index and the log, so that the next session's agents do not repeat the same decision.