Handbook
What the handbook is, who reads it, the order to read it in, and how it relates to the skills.
This handbook records how Kevin Liu runs his work at General Translation (GT), a localization platform for developers. It is written for the agents and people who work with him: Claude Code and Codex sessions, teammates, and anyone who copies this repository into another project to work the same way. The skills hold the procedures for each area of the work. The handbook holds what spans them: the standing principles, the bar for done, the rules for running many sessions and agents at once, pull requests and review, the product facts, the vocabulary and the dated rulings.
The handbook is a section of the docs site, served at /docs/handbook on each of the site's three addresses (www.prototemplate.com, the canonical one, and the aliases prototemplate.vercel.app and prototemplate.kevinliu.studio). The files live in docs/handbook/ of the public repository, and each page of the section includes its file, so the site always shows the file as it stands. The section opens with the agent guide and the operating principles. Its Process folder holds seven of the twelve documents below, its Reference folder holds the product map, the glossary, the numbers and the traps and fixes, and its Canon folder holds eight files from the repository's root and docs/: BRAND.md, DESIGN.md, the libraries with the build log, the graphics pipeline, the artifact pictures, ARCHITECTURE.md, the ship loop and the tools. Each page also answers as Markdown at its address plus .md. The rest of the docs site explains how the hub works.
Guide and principles
Agent guide
The entry point for an agent: the read order, the principles in brief, the skill for each task, the house rules and using the hub elsewhere.
Operating principles
The eighteen standing rules behind Kevin’s corrections, each with how to apply it, the skill that holds it and its dated directive.
Process
Quality bar
The measurable bar for each kind of artifact, from pages and motion to copy, pull requests and films, and for done, each row with its owner.
Multi-session playbook
How many agent sessions share one machine: lanes, forked sessions, shared checkouts, collisions, Claude and Codex on one main, and resumption.
Decisions log
Kevin’s dated rulings on process, product, design and the repositories, what each replaced, his words and the gate that holds it.
Agents on one machine
Agent sessions on one workstation: stopping processes by id, zsh traps, exit-status gates, memory and disk, long commands and shared checkouts.
Agent workflows
Subagent workflows: lane prompts that survive relayed messages, resuming by run id, workflow shapes, refuters, kinds of check and paid model runs.
Pull requests and CI
Pull requests on gt-cloud: CI signals that mislead, review bots, size and shape, parity for redesigned flows, ratcheted lints and git on shared trees.
Reviewing with Kevin
How Kevin’s review words map to measures, one exemplar before a set, how a result reaches him, the five ship states and the ask ledger.
Reference
GT product and architecture map
What General Translation sells and to whom, how the products fit together, the copy that must be exact, and where each part lives.
Glossary
The terms in Kevin’s messages, the skills and the code, each defined in a sentence or two with where it lives.
Numbers
Every load-bearing number in one place, grouped by area, each with its reason, its token or constant, the lint that holds it and the page that explains it.
Traps and fixes
One line per trap met in GT work, grouped by area: the symptom a reader sees, the fix in a few words and the section that explains the cause.
Canon
The canon is the eight files at the repository's root and in docs/ that hold the brand, the design system and the working procedures.
Brand
The identity canon: the name, the idea, the character and voice, the mark, color, type, language as material, and where the identity ships.
Design system
The design canon: the four-color system, the line law, rails and seams, the doubled line, iso, the 1-bit language, moving type and motion.
Libraries
The index of the componentized instruments, then the build log: every library running live with its plates and API snippets.
Graphics pipeline
How the blog illustrations are made with the toolchain in graphics/: captures, labelled crops, the sizing rules, clips, export and hand-off.
Artifact pictures
The standard for the dithered photographs: the rules, the Blue Marble tone grid and screen, the cutter, adding a picture and its lint.
Architecture
The code map: the direction registry, the toolchain as the single source and fork rescoping, the componentized instruments, the mirror.
Ship loop
The verify-and-ship procedure every round runs: the line audit, the page check, the ratchets, types, captures and the gated build.
Tools
Every pnpm command in the repository and the scripts the skills bundle, each with what it does. Written by pnpm build:tools.
The documents
| Document | What it holds | Read it |
|---|---|---|
| Operating principles | The eighteen standing rules behind Kevin's corrections, each with how to apply it, the skill that holds its procedure and the dated directive it comes from | Before the first task of any GT work |
| Quality bar | The measurable bar for each kind of artifact and for done, each row with the skill that owns it | Before showing Kevin work or shipping it |
| Multi-session playbook | Lanes, forked sessions, one instruction sent to several sessions, shared checkouts, collisions, Claude and Codex on one main, relay notes and shared resources | When another session works on the same machine or repository |
| Decisions log | Kevin's dated rulings, what each replaced, his words and the lint, gate or skill that holds it | Before changing a standard, and when two sources disagree |
| Agents on one machine | Stopping processes by their ids, zsh traps, exit-status gates, memory and disk, long commands and shared checkouts, each with the incident that set it | Before running agents, builds or servers on a machine other sessions use |
| Agent workflows | Lane prompts that survive relayed messages, resuming a run, workflow shapes, refuters, kinds of check and paid model runs | Before launching subagents or a long autonomous run |
| Pull requests and CI | CI signals that mislead, the review bots, pull request size and crops, parity for a redesigned flow, lints and ratchets, and git on shared trees | Before opening, updating or reporting a pull request |
| Reviewing with Kevin | How his review words map to measures, one exemplar before a set, how a result reaches him, the ship states and the ask ledger | Before showing Kevin work and when reading his feedback |
| GT product and architecture map | What GT sells and to whom, how the products fit together, the copy that must be exact, the CLI and agent entry points, and the repositories | Before writing about, designing for or changing a GT product |
| Glossary | The terms in Kevin's messages, the skills and the code, each with where it lives | When a word in a request or a skill is unfamiliar |
| Numbers | Every load-bearing number by area, each with its reason, its token or constant, the lint that holds it and the page that explains it | Before changing a size, a duration or a limit, and when a review names one |
| Traps and fixes | One line per trap met in GT work: the symptom, the fix in a few words and the section that explains the cause | When something breaks, and before a round of work in an area |
How the handbook relates to the skills
- A skill holds the procedure. The handbook states the rule and names the skill. When the two disagree, the skill is right, and the change that finds the difference corrects the handbook.
AGENTS.mdat the repository root is the entry point for an agent. It summarizes the principles, routes each kind of task to its skill, and points here for depth.- The skills name handbook files by their paths (
docs/handbook/quality-bar.md). A project that installs the skills copies this folder andAGENTS.mdbeside them, as README.md's "Import this into another project" section describes.
Changing the handbook
- A new ruling from Kevin goes into the decisions log as a dated row that names what it replaced, and the skill, lint or gate that holds it changes in the same commit.
- A document keeps the writing rules of
gt-voice: plain declarative sentences, no em dashes, no metaphors, and no contrast pairs. - The repository is public. No document carries keys, account ids, email addresses, personal details, customer names that generaltranslation.com does not show, unannounced plans or business figures (operating principle 18).
- On the site, a new document needs its page in the folder group of
content/docs/(guide)/handbook/it belongs to ((process),(reference)or(canon)), which includes the file with<include cwd>docs/handbook/<file>.md</include>, its row in that folder'smeta.json, its entry insrc/app/handbook/registry.tsin the same order, its card on the section's index page and its headings inHANDBOOK_HEADINGS(src/lib/search-index.ts). A page that sets live figures between sections includes the file one heading at a time, and the build fails when such a page leaves a heading of the file out. Theprototemplateskill (section 6) lists every step, andpnpm lint:registriesreports what a change missed.
Sources
- The first six documents were written on 2026-10-05 from Kevin's messages to Claude Code and Codex between 2026-07-20 and 2026-10-05, about 5,800 in all, and from the curated skills. The four Process documents on agents on one machine, agent workflows, pull requests and review were added on 2026-10-21 from the skills and the incident records behind them, and the numbers and the traps and fixes were added the same day as indexes of the docs pages and skills that hold each value and each failure. Each document's Sources section lists its own evidence.
- Kevin, 2026-10-05: "this prototemplate is supposed to be my hub for general translation work, but also i should be able to use it anywhere and build on top of it so it also acts as a wiki / repository of how i do work at GT".