Skip to content

Development ​

Commands ​

bash
npm run build    # tsc 7 (the `typescript7` alias) → compiles src/ to build/
npm run dev      # tsc 7 --watch
npm start        # node build/index.js
npm test         # vitest run (src/test-git-env.ts, the setup file, points git at no global config so a fixture commit never signs)
npm run check    # tsc 7 --noEmit + format:check + lint + scan + vitest + check:ci (the pre-commit gate)
npm run check:static   # the first half of check: tsc 7 --noEmit + format:check + lint + scan (serial, ~2 cores)
npm run check:tests    # the second half: vitest + the pane tests + check:ci (vitest takes WF_THREADS workers when it is set)
npm run check:leased   # check under pool leases sized to each half (scripts/check-leased.sh): 2 threads, then 4-6; what the engine-task gates and a worker run
npm run check:ci # the suite as CI runs it (scripts/check-ci.sh): env -i, an empty HOME, no system git
                 # config, TMPDIR inside it, git user.useConfigOnly (no guessed identity), TZ America/St_Johns (CHECK_CI_TZ),
                 # LANG=C — plus CI's package.json / plugin.json version check
npm run lint     # typescript-eslint (type-checked); fails only on findings absent from eslint-baseline.json
npm run lint:baseline  # re-record eslint-baseline.json (after fixing findings, to ratchet down)
npm run format:check   # biome format check (formatter only; part of check)
                       # TypeScript: the compiler is 7 (devDependency `typescript7`, `npm:typescript@^7`, run as
                       # node_modules/typescript7/bin/tsc); `typescript` stays ^5.9 because typescript-eslint (peer <6.1),
                       # the tests that transpile dashboard sources and tsserver (editor LSP) need the JS compiler API 7 lacks
npm run scan     # ast-grep scan --error: structural rules in rules/ (sgconfig.yml), e.g. .then() without .catch(); 0 findings

The engine's own slice workflow is a tracked file: .claude/workflows/engine-task.yaml (extends: batch-task, the project tier of this checkout). .gitignore un-ignores that one file and keeps the rest of .claude/ ignored, so a slice changes the workflow through its worktree like any other source. Its repro_check and repro_route (a bug line's reproduce step) and its work_check (the CHANGELOG entry, on every engine-task branch whatever its kind) list the branch's changes against the branch's own base (git merge-base master HEAD), not the moving master. work_check also refuses a tree still at reviewed_sha when a review text exists and its verdict (read as review_filed reads it) is not MERGE, a non-canonical verdict line included: the driver took check without sending the list to the worker (exit 3; the stdout carries the review text itself, which work_unready forwards to the worker); The refusal prints the last 8000 bytes of the review (tail -c: the verdict and its list close the text); the bundled templates/batch-task.yaml work_check carries the same guard on batch/<task> against reviewed_sha and review_text, which its review prompt has the driver set; src/work-check-unamended-fixes.test.ts and src/work-check-unamended-fixes-followups.test.ts pin it. After a green gate, review_route decides whether the tree still needs a review visit: it compares the reviewed commit's patch and HEAD's patch over their own parents with the prose paths (CHANGELOG.md, README.md, docs/**/*.md) left out and only the +/- lines read (a rebase's moved hunk headers, index lines and context do not count); the site's own code under docs/ (.vitepress/, .vue, scripts) stays code, as in scripts/review-class.sh. Equal code patches after a MERGE go to project_land (a breaking: true line to breaking_ready); after FIXES to review_verify, one verify-only question to the same reviewer that spends no review visit (max_visits: 2). A rebase_fix after MERGE whose resolution changed code (HEAD's parent is no longer the reviewed commit's) goes to review_verify too, naming the range-diff of the two patches; any other code change enters review as before. src/review-visits-verify-only-fix.test.ts pins it. The worker prompt forbids a bare playwright install (it replaces browsers in the machine-wide ~/Library/Caches/ms-playwright, which every parallel slice's gate launches from) and prescribes PLAYWRIGHT_BROWSERS_PATH=<worktree>-browsers npx playwright install <browser> with the tests run under the same variable; A browser a worker's own script launches runs under a lease through the engine checkout's scripts/wf-run --threads 1 (the prompt's {{context.cwd}}/scripts/wf-run, not a bare name off PATH) and is closed in a finally; work_check refuses (exit 3, the pids listed, nothing killed) while a process reparented to init (ppid 1) has the worktree as its cwd. cleanup removes <worktree>-browsers under its exact-path guard. src/worker-browser-install-isolated.test.ts pins these. A land whose rebase onto a moved master conflicts (project_rebase exit 1) goes through rebase_conflict (an exec state, max_visits: 2) straight to rebase_fix, with no parent and no driver choice; the third conflict of a task follows its on_exhausted to land_failed, which is also where every other land failure goes. rebase_fix's verify does not ask whether master is an ancestor (a lag without a conflict is rebased by the land itself); src/land-rebase-conflict-auto-fix.test.ts pins it.

The engine repo has its own pool gate, .claude/workflows/pool-gate.yaml (tracked beside engine-task.yaml; .gitignore un-ignores it, so every /tmp/wf-* worktree has it): the hook finds a pool-gate.yaml from the directory the command runs in up to the git root (the call's cwd moved by its leading cd <dir> && segments: a worker's call is cd /tmp/wf-X && npx vitest run … while the session's cwd is another project, whose own config would otherwise decide; a target with no config keeps the call cwd's rules; a target with one is judged by it for heavy routing, but the call cwd's project deny rules still refuse, so a worker's cd /tmp/wf-X && git stash meets the session project's deny), and without one a worker's or reviewer's own npx vitest run src/<file>.test.ts, vitest run --maxWorkers=1 or npm run check ran with no lease (load beside an idle pool). The rules lease every vitest form (npx, npm exec, node_modules/.bin, bare), npm test, npm run check, npm run check:ci and scripts/check-ci.sh, sized by what the run uses: an explicit --maxWorkers=N (N = 1, 2, 4, 8) gets N threads, one named test file 1, two files 2, anything else (the suite, a directory, -t) 4-14. Each hands its share to vitest as VITEST_MAX_WORKERS=$WF_THREADS (vitest's own default is one worker per cpu minus one, so without it a 2-thread lease would run 15 workers), and scripts/check-ci.sh carries that one variable through its emptied environment. A command already under wf-run (the workflow's exec states) or run with WF_THREADS set is never leased twice. tsc, lint, scan and build run for about a second and take no lease. src/pool-gate-engine-repo.test.ts pins it, the cd case included (a payload cwd in another git repo with its own pool-gate.yaml without vitest rules).

Architecture ​

FileResponsibility
src/index.tsEntry point — wires components, starts stdio transport
src/workflow-dirs.tsThe one owner of the workflow directories (WORKFLOW_DIR, the cwd's .claude/workflows/, bundled templates/): workflowDirs / workflowLoader, built by the server and by session-cli.js alike
src/engine.tsFSM core — start, transition, abort, context, stack push/pop
src/session-scope.tsWho may end or step a session: scopeVerdict (abort / transition outside the caller's own subtree refused without force + reason), secondRootRefusal (a parentless start beside an active root)
src/loader.tsYAML loading + Zod validation + fs.watch hot-reload
src/storage.tsJSON persistence with atomic writes and lockfile mutex
src/modifier.tsRuntime overlays + create (YAML writer)
src/tools.tsMCP tool registrations + response formatting
src/executor.tsAction state execution — shell commands (exec, a resource: exec under a pool lease) and HTTP requests (fetch)
src/pool.tsMachine-wide thread pool: config, admission pass, lease acquire/release under a file lock
src/wf-run.tsThe wf-run CLI over the pool (--status, --usage)
src/pool-usage.tsWhat each lease held against what its tree ran: the meter, usage.jsonl, wf-run --usage's per-label table
src/queue.tsTask queue files: parse, admission (after: / touches: / owner: / pause), [.] marks under the queue's lock
src/queue-cli.tsThe wf-queue CLI over queue.ts (exec form of queue_next / queue_mark)
src/process.tsProcess-group kill and pid liveness
src/stale.tsStall detection: a state's stale_after (type defaults) and whether a session is STALE
src/template.tsMustache-style {{var}} template rendering for action parameters
src/dashboard.tsExpress REST API + static file serving
src/dashboard-routes.tsThe dashboard's route table (path <-> view), shared by the page and the tests
src/event-fold.tsThe event log's fold and seedEvents (a session file's events), pure; served as /event-fold.js
src/map-layout.tsThe live map's layout (bands, lanes, branches, loops, stops, questions) and keyed scene, pure; served as /map-layout.js
src/replay.tsThe landing page's replay, pure: buildReplay (the sessions of the open-source projects, anyparse and the engine's own, from the event log, a window of whole pipelines under a size limit, nothing of another project; the real spend of their tasks from the ledger by ledgerSpend, an allowlist of the replay's tasks), expandReplay (its rows back to events), the player's clock (SPEEDS, advance, rowsUntil), the map's fit (fitView, cameraTop), the plan pane's Snapshot at a moment (snapshotAt, its Next and Waiting read from ReplayFile.queue) and the parent conversation's lines (conversationAt, with conversationTail its last lines keyed by their index in the whole conversation); the pool of the window (buildPool cuts pool.log to an allowlist of labels, assertReplayClean is the export's self-check, poolStateAt / poolCountsAt the Pool tab's read, poolWaiting the lanes that wait for a lease, poolStrip the strip's paths); scripts/export-replay.mjs writes docs/public/replay/anyparse.json with it
src/replay-queue.tsThe replay's queue, the export's half that reads the queue module: captureReplayQueue runs the engine's own pick (planPick, describeQueue) over the queue file rolled back to the window's start (the lines that ran in it pending again, the lines claimed before it and not ended at it running, so a line after one waits on it) and cuts it to the pending lines of the allowlisted projects as ids, difficulty, priority, kind and one of a fixed set of reasons (never a line's text or notes); snapshotAt (src/replay.ts) plays it back
src/workflow-describe.tsdescribeWorkflows (a workflow as /api/workflows carries it, shared by the endpoint and the site's export) and renderWorkflows (the site's byte-stable file); src/site-workflows.ts (writeSiteWorkflows) writes docs/public/workflows.json from the bundled templates, through scripts/export-workflows.mjs (npm run docs:workflows) and the test run
scripts/record-scene.mjsnpm run docs:record: builds the site, plays the landing's stage (the live map, the Claude Code window with the plan pane over it) frame by frame in headless Chromium through the page's ?record seek hook, and encodes docs/media/scene.gif (with --mp4 also video/out/scene.mp4) with ffmpeg
scripts/scene-capture.mjsThe scene as a headless page for the recorders: builds and serves the site, opens /?record, pins the landing's own 16:9 stage to the 1920x1080 frame at scale 1; shared by record-scene.mjs and video/render.mjs
video/npm run video: the voiced intro. script.md (narration), storyboard.json (card or replay range per phrase), tts.py (Kokoro / Chatterbox, one cached WAV per phrase), render.mjs (plan, frames, audio, SRT, ffmpeg), README.md (setup, voices)
.github/workflows/pages.ymlBuilds the VitePress site and deploys it to GitHub Pages on a push to master
dashboard/The page: index.html (views, ui component helpers), map.js (the live map: events, follow mode, view anchoring), scene-dom.js (the keyed SVG reconciliation, shared with the docs site's replay), graph.js (the workflow graph and its state panel: renderGraph, workflowViewHtml, workflowClick; pure, shared with the docs site's live graphs), stable.js (in-place refresh, scroll memory), tokens.css (the only colour literals: a light and a dark set, data-theme on <html> or the system picks), components.css
src/types.tsZod schemas, TypeScript types, constants

The site ​

The documentation is the site https://axgord.github.io/claude-workflow/ (sources in docs/, built with VitePress: npm run docs:dev, npm run docs:build, npm run docs:preview). docs:dev and docs:build first write the site's generated workflow export (docs:prepare). docs:preview serves docs/.vitepress/dist, which is git-ignored and survives between runs, so it builds first: a preview always shows the current sources.

The hero and the header ​

The landing opens with the GitHub banner as live HTML and SVG (docs/.vitepress/theme/Hero.vue, mounted in the home layout's home-hero-before slot by theme/index.ts), merged with the nav. The page opts in with pageClass: has-hero in docs/index.md; every other page keeps VitePress's own bar. The words are the hero: of docs/index.md (the default text hero stays in the markup, hidden, and still feeds scripts/render-banner.mjs); the chips are the banner's, and the workflow count is the number of templates/*.yaml counted by config.mts at build time (__BUNDLED_WORKFLOWS__), never typed; the diagram is the banner's schematic of a task's life (queue, think, code, review, land, the gates, the fix loop, the thread pool with the waiting agents) drawn from the same words at two widths, so its labels stay legible on a phone (hand-drawn in the template beside schematicSvg of scripts/render-banner.mjs because that one is a string builder in a node script the browser bundle cannot import, and Scene, PoolStrip and WorkflowGraphs draw the replay and the bundled definitions, not a fixed schematic). There is one name: the nav's own title (siteTitle in config.mts, its first word in the banner's gradient) is enlarged while the page is at its top and condenses into the bar's left as the page scrolls, on the desktop layout only (from 960 px, where the hero is two columns); below 960 px the hero stacks and the bar is VitePress's own, opaque and pinned at the top, hiding on a scroll down and showing on a scroll up (fixed at every width with the theme's --vp-nav-bg-color as its background, which VitePress does not paint for a home layout below 960 px; the content padded by --vp-nav-height under it), with its plain title. The hero and the bar share one content width, --hero-content-w (VitePress's home container, the feature grid's 1152 px, inside --vp-layout-max-width): on a wide screen the hero is one centred block, and the logo, the hero's text, the diagram, the bar's right cluster and the feature cards share their edges, not spread to the layout's 1376 px (src/site-hero-content-width.test.ts measures it at 1280, 1440, 1920 and 2560 px). The replay's stage (Scene.vue) and the install block (Install.vue) under the hero take the same width: their max-width is --hero-content-w plus the hero's gutters, with the hero's own gutter (24 px below 768 px, 32 px from there, plus 64 px of max-width from 768 px; the old 16 px phone override is gone), so at 375, 640, 768, 960, 1215, 1280, 1440 and 1920 px their edges and the feature grid's are the hero's, each asserted within 1 px (src/site-scene-install-align.test.ts). VitePress's feature grid takes the same width and gutters: Hero.vue overrides its container under .Layout.has-hero (padding 24 px, 32 px from 768 px, max-width: var(--hero-content-w)) in place of its own 24/48/64 px steps, so its cards' edges are the hero's at every width (src/site-feature-grid-align.test.ts, 375 to 1920 px). The hero and the bar are ONE layout over the whole scroll range, from 960 px a grid of two columns shared by both (CSS variables of .Layout.has-hero: --hero-text-min, the left column's least width, and --hero-dg-max, the diagram's greatest): the left column is the text (in the bar, the title), the right column is the diagram (in the bar, where the search starts, on the diagram's left edge). The diagram is drawn at 70% of the size it first had (594 px of the 848 it filled; three sizes, 60, 70 and 80%, were compared beside the text column at 1440 px: at 60% the labels got small, at 80% the diagram was nearly as tall as the text block and competed with it; at 70% the text block leads and the diagram is 208 px against the text's 260). The scroll has phases: the title first scales down below the bar while the search condenses (the search, which also gives way to the cluster where the row is short, narrows from 300 px to 150 px and slides next to the right cluster: the row is the search between two free spaces that share the width by flex-grow, 0 and 1 at the top, 1 and 0 condensed), then the title rises into the bar; the bar's surface (VitePress's own opaque colour of the current theme) is complete before the title reaches it and its divider comes last. What the hero holds (tagline, buttons, chips, the diagram) does not fade at any width: it scrolls under the opaque bar as plain content, cut by the bar's line and never dissolved (no soft edge; src/site-hero-no-fade.test.ts samples the scroll every 16 px at 375, 414, 768, 960 and 1440 px and asserts opacity 1 for every element with any part in the viewport). The merge of the nav and the hero (the enlarged title, the condensing search, the transparent bar that is fixed over the hero) is for the desktop layout, from 960 px; below it the bar is VitePress's own (opaque and fixed at the top like the desktop one, hiding on a scroll down and showing again on a scroll up, see below; no enlarged title) over a stacked hero, and src/site-mobile-nav-pinned.test.ts pins in a real browser at 390 and 800 px that after a scroll down and a scroll up of more than 10 px (the bar shown again, its transition over) the nav's top is 0 and its bottom is --vp-nav-height, and that the page's content starts below it, plus that the bar's computed background equals --vp-nav-bg-color (alpha 1) after a scroll, light and dark. Every size is a CSS number (--hero-brand-y, --hero-brand-s, --hero-search-w0, --hero-search-w1), nothing is measured; the bar is fixed at every width, over a hero that pads under it from 960 px and under a content padding below it, so nothing jumps. The scroll linkage is CSS scroll-driven animation (animation-timeline: scroll(root block)) where the browser has it and motion is allowed; elsewhere a sentinel's IntersectionObserver toggles hero-condensed on the root and the same states change with a transition, or at once under prefers-reduced-motion. The nav is one entry, Docs, a link to /getting-started (a click goes there; it is active on every docs page) with a list of every page of the sidebar beside it (the landing has no sidebar, so this is where its reader finds the pages; a single text link stood alone beside the icons). VitePress's own dropdown is a button that only opens its menu and it has no link-plus-menu item, so this is a custom nav item, theme/DocsNav.vue (component: "DocsNav" in config.mts, registered in theme/index.ts): the title is a link, the list opens on hover, on keyboard focus and on a click, Enter or tap of the caret beside it (the caret only opens, so it cannot hide a list that hover or focus already opened; Esc, a tap outside, or the pointer or focus leaving closes it), and in the hamburger screen (below 768 px) it is always expanded, with no toggle: a Docs link to /getting-started and every page's link under it, as VitePress's own screen-menu link components (screen-menu is the prop VitePress passes a custom nav component for it; its stock group would be collapsed) (src/site-docs-nav-clickable.test.ts pins the click, the list, the caret and, at 390 px, the open menu with every page visible and no click on Docs, in a browser). The theme switch cross-fades: theme/Layout.vue wraps VitePress's layout (the slots index.ts fills pass through) and provides its toggle-appearance, which flips isDark inside document.startViewTransition (after a nextTick, the recipe VitePress documents, without its circular reveal), so the old page fades into the new one over 300 ms (TRANSITION_MS, the group's animation-duration), the travel time of the switch's own knob (VitePress's VPSwitch moves it in 0.25 s); every demo (the map, the terminal window, the status line, the pool strip) follows html.dark in CSS, so they change in the same transition, with no second change after it. A browser without startViewTransition and a reader under prefers-reduced-motion get the plain flip; input is ignored while the 300 ms runs. src/site-theme-switch-transition.test.ts pins the source and, in Chromium, pauses the transition's animations and captures the page at 0, 100, 200 and 300 ms (set WF_THEME_FRAMES=<dir> to keep the PNGs), the demos' end state against a page loaded dark, the reduced-motion and no-API flips, and runs Firefox and WebKit when playwright's own builds of them are installed. GitHub appears once, as the icon beside the theme switch, and "Get started" once, as the hero's button. src/site-hero.test.ts pins its source; the built landing (the count, the page class, the title) is checked in the one build of src/site-map-replay.test.ts; src/site-hero-layout.test.ts (opt-in, WF_BROWSER_TESTS=1, builds the site and drives it in headless Chromium) scrolls the page in 8 px steps at 1440, 1024, 960, 768, 375 and 320 px, with and without reduced motion, and asserts that every box of the bar lies inside the viewport with a gutter and that no two boxes of the bar (logo, title, search, links, theme switch, GitHub, the extra menu or hamburger) overlap, plus the search's grid line, no horizontal overflow and wrapping chips and buttons across sixteen widths. src/site-hero-320.test.ts pins that the bar's title and the page fit a 320 px phone (the name's and the title's right edges and the page's scroll width at 320 px, scroll top, with and without reduced motion) and runs whenever a browser is installed, with no opt-in. Below 960 px the bar is fixed on every page and auto-hides: Layout.vue owns the one passive, frame-throttled scroll listener, which flips nav-autohide-hidden on <html> on a scroll down (past 10 px, never at the page top, never with the nav screen or the sidebar open) and clears it on any scroll up; the bar and a doc page's local nav (VPLocalNav) then move up by transform: translateY, with no transition under prefers-reduced-motion; a bar with keyboard focus inside it (:focus-within on .VPNav and .VPLocalNav) cancels its hidden transform, so a Tab into a hidden bar shows it and the focused element is never off-screen. From 960 px nothing moves. src/site-mobile-nav-autohide.test.ts pins it in a real browser at 390 and 1280 px, and src/site-mobile-nav-autohide-focus.test.ts pins the focus reveal (the rule's source and, at 390 px on / and /getting-started, a focused nav link and the local nav's button after a scroll down).

The replay ​

The site's landing page replays the live map: a recorded window of real sessions of the open-source projects, anyparse and this engine's own work (docs/public/replay/anyparse.json, written from the event log and the ledger by npm run build && npm run docs:replay -- --project-dir <the anyparse checkout> --workflows <the engine's .claude/workflows>, the sessions of --project anyparse and --also mcp-workflow-engine only (--workflows gives the engine's own engine-task its stations on the map); everything else stays out of the file), with the real cost of each of their tasks: the export reads spend.usd from ledger.jsonl for the tasks of the replay only (an allowlist like the events', a row of any other task is never read into the file; --ledger FILE|none), the plan pane's Landed rows show $x.xx and the day row its sum as the live pane does, and a task with no measured spend stays —; the plan pane's Next and Waiting fill like the live pane's: the export also reads the queue file (--queue FILE|none, default the project's own) through the engine's own pick (planPick and describeQueue, the code wf-queue and queue_next run) over the file rolled back to the window's start (every line that ran at or after the window's start, the window's own and those that ran and landed after it, set back to pending; a line claimed before the window's start and not ended at it is running at the start, so a line after: it waits after: X (running)), and writes ReplayFile.queue (src/replay-queue.ts): per pending line of --project and --also only its id, difficulty, priority, kind and one of a fixed set of reasons (after: X (running), overlaps X, parked, parent-run), never a line's text or notes, and the self-check refuses anything else; snapshotAt replays it, so a line moves Waiting, then Next, then Running as the lines it waits for end (a line added to the queue after the window cannot be rebuilt: the section's note says so).

The stage ​

The window is played through the dashboard's own layout and renderer, no server, on one 16:9 stage (1920x1080 scaled to the page) that the map fills, never scrolling (scaled to the frame, a camera on the running lanes when they are taller). Over it the Claude Code window, translucent and dark or white with the site's theme (terminal-palette.css's --cc-*, shared with the status-line and Pool page demos, and PaneView.vue's --tc-*, one value per theme key of TONE; a toggle and T hide it, as do its close and minimise buttons; its green button and a title-bar double-click zoom it over the stage, Esc leaves), shows the parent conversation's lines and the plan pane, both drawn by the mod's own code: hooks/pane-view.ts turns a Snapshot into the pane's tree, the mod draws it with Claude Code's elements and the site in the DOM (PaneView.vue), from the Snapshot snapshotAt of src/replay.ts builds out of the events. One transport bar under the stage (play / pause, 1x to 60x, scrub) drives both.

The workflow graphs ​

Under the scene the landing draws the workflow graphs live, in the browser and as SVG (sharp at any size): dashboard/graph.js, the module the dashboard's Workflows tab draws with, lays out and draws every bundled workflow from docs/public/workflows.json (a build product, git-ignored and never committed: npm run docs:dev, docs:build and docs:preview write it from templates/ first through npm run docs:prepare, which builds and runs npm run docs:workflows, and so does every test run, so a template edit cannot leave a stale copy), and a click on a state shows what the dashboard shows (its prompt and transitions; a sub-workflow state opens that workflow); the graph has no scroll box of its own: its SVG takes the section's width and the height its viewBox gives at that width, so the page scrolls through it and the mouse wheel is never captured (src/site-graph-no-inner-scroll.test.ts).

The thread pool in the scene ​

The scene also shows the machine's thread pool over the same hours: scripts/export-replay.mjs reads the pool's own log (pool.log, and pool.log.1) for the replay's window, only a window the log covers is chosen, a lease or waiter keeps its label only when it names a slice or session of the replay (an allowlist: the pool is shared by every project on the machine; every other lease is a thread count in one row of leases the log does not name, this project's or another's, since a sample lists no holders and only an overrun:, underuse: or backfill: line names one, and the export checks its own output and refuses to write a foreign label, an absolute path or a pid), a thin strip under the map (PoolStrip.vue) draws threads held against the budget, the Pool tab of the plan pane shows the pool at the clock through the mod's own poolBody, and a lane whose exec waits for a lease (wait_ms of the exec's end event) carries the map's "waiting for the pool" mark. The page Thread pool (docs/pool.md) explains it in plain language with a diagram and the same data live (PoolDemo.vue). The status line below it is the mod's own band (statusBandTree of hooks/pane-view.ts) drawn from the replay at a moment the reader picks.

Recording the scene ​

npm run docs:record re-records that stage into docs/media/scene.gif (960 px, under 4 MB, the animation at the top of the README; -- --mp4 also writes a 1920x1080 clip to the git-ignored video/out/scene.mp4, nothing in the repository reads it); it needs the playwright devDependency with its Chromium (npx playwright install chromium) and ffmpeg.

The brand: logo, banner and social preview ​

npm run docs:banner re-renders the brand: logo 2 (the live map, a dispatcher fanning out into three lanes) as the site's nav logo (docs/public/logo.svg for the dark theme, logo-light.svg for the light one, themeConfig.logo) and its favicon (docs/public/favicon.svg, both colour schemes in one file), and the two images the repository shows about itself, docs/banner.png (1200x400, the top of the README) and docs/social-preview.png (1280x640, the size GitHub asks of a repository's social preview: upload it under Settings > Social preview; the same render is also written to docs/public/og.png, the card image the site's own head names, see below): scripts/brand.mjs holds the brand itself, with no dependency (the name NAME, the two palettes, the logo and faviconSvg: the site config, the dashboard (its <title>, heading and /favicon.svg) and the render script all read it), and scripts/render-banner.mjs holds the banner's SVG templates (a schematic of a task's life: queue, think, code, review, land, the gates between them, the dashed fix arrow, the thread pool with the agents waiting for it), reads the site's name and tagline from the hero of docs/index.md, counts the bundled workflows from templates/ for its line of chips, and puts the drawing over a blurred, dimmed crop of a real frame of the scene (captured as docs:record captures it, never a stored picture; -- --at <replay s> picks the moment, by default the first second at which the plan pane shows three Landed rows with a price, read from the replay itself (defaultAt), so a re-export moves it; the README's size has the weaker background so the schematic reads first), so no number or picture in them is typed or drawn by hand (same prerequisites as docs:record, without ffmpeg).

The site's head carries what a link to it shows in a post (docs/.vitepress/config.mts): Open Graph (og:type, og:site_name, og:image with its width, height and alt) and the Twitter card (summary_large_image, twitter:image) for the whole site, and each page's own og:title, og:description (its frontmatter description; the landing's is its hero) and og:url, with twitter:title and twitter:description, from transformHead. Every url in a tag is absolute (https://axgord.github.io/claude-workflow/...): a crawler does not resolve the base. A preview does not update until the page is deployed and the network re-fetches it; to check after a deploy, paste the address into https://www.opengraph.xyz/ or the LinkedIn Post Inspector (https://www.linkedin.com/post-inspector/), which show the card and drop their cached copy.

The voiced video ​

npm run video renders a voiced 2-3 minute intro (video/out/intro.mp4 and intro.srt) over the same scene: the narration is video/script.md, video/storyboard.json ties each phrase to a card or a stretch of the replay, a local free voice (Kokoro by default, Chatterbox cloning a sample of yours) voices one WAV per phrase cached by text, so an edit or a UI change re-renders one command (video/README.md).

Deploy ​

.github/workflows/pages.yml builds the site and deploys it to GitHub Pages on a push to master (once: Settings > Pages > Source: GitHub Actions).