How to
How to generate a sequence diagram from a request
You describe who talks to whom; the agent writes actors and messages as YAML; chiltepin check confirms every message joins two real actors; the renderer draws the lifelines. Nobody chooses a coordinate at any step.
1. Give the agent the request
Install the skill once — npx skills add jdiejim/chiltepin -g — then say what the reader needs, in plain words. Do not name a block type; picking it is the skill's job.
How the login flow works across the SPA, the auth service, and Google. Write docs/login-flow.md and run chiltepin check.
The three parties are the actors. “How it works” asks for order, which is the sequence lens; the agent adds a context view first so the reader knows who the parties are.
2. What the agent picks, and why
The skill reads the request as the reader's question and answers it with two to five blocks, each a different lens. For this request it picks:
sequence— the flow — actors with subtitles, messages in the terse form, activations with + and -, responses as -->; the happy path and the refresh in one diagramc4— who the parties are before they start talking — the SPA, the auth service, the session store and Google, one labelled edge eachflow— the callback’s decision tree — state matches, token verifies, email verified — where a sequence diagram would need three alt boxes
Before writing each one it runs chiltepin block <type>, which prints the fields, enums and terse forms from the schema. It writes YAML; it never places a shape.
The block it wrote
The sequence block the agent wrote for this exact request, unedited: three actors, fifteen messages in the terse form, activations, a footer with the redirect URI and token lifetime.
```sequence
id: login-happy-path
title: Sign in with Google — happy path
actors:
- { id: SPA, name: SPA, sub: app.example.com }
- { id: Auth, name: Auth service, sub: auth.example.com }
- { id: Google, name: Google, external: true }
messages:
- SPA -> +Auth: "GET /auth/google/start?return_to=/dashboard"
- Auth -> Auth: "create login record: state, PKCE verifier, return_to (TTL 5 min)"
- Auth --> -SPA: "302 to Google authorize URL; Set-Cookie login_state (HttpOnly, 5 min)"
- SPA -> +Google: "GET /o/oauth2/v2/auth?client_id&redirect_uri&scope=openid email profile&state&code_challenge"
- Google --> -SPA: "302 to https://auth.example.com/auth/google/callback?code&state"
- SPA -> +Auth: "GET /auth/google/callback?code&state (Cookie: login_state)"
- Auth -> Auth: "match state to login record; load PKCE verifier"
- Auth -> +Google: "POST /token (code, code_verifier, client_id, client_secret)"
- Google --> -Auth: "200 { id_token, access_token, expires_in }"
- Auth -> Google: "GET /oauth2/v3/certs (cached JWKS)"
- Auth -> Auth: "verify id_token signature, iss, aud, exp, nonce, email_verified"
- Auth -> Auth: "upsert user by Google sub; create session family in Redis"
- Auth --> -SPA: "302 to /dashboard; Set-Cookie refresh_token (HttpOnly, Secure, SameSite=Lax, 30 d)"
- SPA -> +Auth: "POST /auth/refresh (Cookie: refresh_token)"
- Auth --> -SPA: "200 { access_token (JWT, 15 min), user }; rotated refresh_token cookie"
foot:
- { label: Redirect URI, value: "https://auth.example.com/auth/google/callback" }
- { label: Scopes, value: "openid email profile" }
- { label: Access token lifetime, value: "15 minutes" }
```3. Check it
The agent runs npx -y chiltepin check docs/<file>.md --json. Every diagnostic has a stable code, the file and line, and a hint. One it might see on a first draft:
E_SCHEMA docs/login-flow.md:22 sequence: unknown field 'text'
hint: Did you mean `end`? Valid fields: from, to, label, kind, summary, code, note, activate, deactivate, frame, else, end.It fixes what the hint says and re-runs the check. A change is not done until the check passes — and in CI the same command fails the build, so a document cannot drift silently.
4. Render it
npx chiltepin html docs/login-flow.md -p renders and opens the page. chiltepin slides docs/login-flow.md -p makes a deck where the sequence builds one message per step. chiltepin build publishes it with the other docs; the output is static SVG in HTML with no runtime JavaScript.
See it done
The agent-written document for this request is in the gallery: Login flow, shown exactly as generated from “How the login flow works across the SPA, the auth service, and Google.”. Related: the sequence diagram generator, the flows reference, and the blocks sequence, flow, swimlane.
Frequently asked questions
- How does a request become a sequence diagram?
- The skill reads “how X works across A, B and C” as a question about order between parties, which is what a sequence diagram answers. The agent declares the actors, writes the messages in the terse form (SPA -> +Auth: "GET /start"), marks activations with + and -, responses with -->, and errors with -x->. The renderer places lifelines, arrows and activation bars.
- Do I have to know the syntax?
- No. The agent runs chiltepin block sequence and reads the contract from the schema before writing. You write English; you review a diff. If you want to edit by hand, the terse form reads almost like the prose that produced it.
- What does chiltepin check catch in a sequence diagram?
- A message from or to an actor that was not declared, an activation closed on the wrong side, unknown fields, and a diagram past its density budget — the last one is the hint to split a forty-message flow into the happy path and the failure path.
- Can it render as slides?
- Yes. chiltepin slides gives a sequence diagram an automatic build: one message per keypress, earlier messages stay, the newest takes the accent. The page and the PDF show the whole diagram.