Spec: thirdshift.app, a site that shows how the factory works #61

Parent

#29

Problem Statement

thirdshift is released (v0.1.0) and installable with one command, but the only place that explains it is the README. The README is reference documentation. It doesn't show a newcomer, at a glance, what happens between pasting an Issue URL and getting a pull request that's ready for review. Nor does it show what guides the agents while they work. I want to send someone a link that makes them understand thirdshift in about 30 seconds, trust it, and install it. I also want that page to feel like the place thirdshift is named after: the pressroom where my dad, Mark Stephens, ran four-colour presses on third shift.

thirdshift.app already resolves to my server, which runs Caddy, but nothing is served there yet.

Solution

A static site at https://thirdshift.app, with two pages.

The home page is one long page. It looks like a sheet-fed press hall at night: process cyan, magenta and yellow on a near-black "K", halftones, registration marks and light scanlines, newspaper type, and Factorio-style belts on a blueprint grid. It leads with a proof sheet carrying the headline "Your issues go to press overnight." and the install command curl -fsSL https://thirdshift.app/install.sh | sh.

It then explains thirdshift in this order:

1. The Day shift / third shift split, built on Matt Pocock's skills.
2. A four-unit press line that walks through one real Run step by step, with a terminal replaying that Run's real stderr lines.
3. What comes off the press.
4. How the factory will grow.
5. Real pull requests as proof sheets.
6. Requirements and platforms.
7. A personal colophon.

The Prompts and skills page (/prompts/) shows everything that steers the agents: the prompt templates a Run sends, the exact claude command line, and the full text of every Factory skill. It's generated from the source code, so it can't drift from what the binary actually does.

The look was settled by a throwaway prototype on branch prototype/site, commit 5b559d0, which will never be merged. Its commit message records the four verdicts.

Terms in bold are defined in CONTEXT.md.

User Stories

Arriving and installing

1. As a developer new to thirdshift, I want the first screen to tell me what thirdshift does in one headline and one paragraph, so that I know within seconds whether it's for me.
2. As a developer, I want the install command on the first screen, on a laptop and on a phone, so that I don't have to hunt for it.
3. As a developer, I want a one-click copy button on the install command, so that I don't mis-select it.
4. As a cautious developer, I want to reveal the full GitHub Releases install command next to the short one, so that I can see the installer comes from GitHub, not from a personal server.
5. As a developer, I want https://thirdshift.app/install.sh to redirect to the latest release's installer on GitHub, so that the short command always installs the latest release.
6. As a developer, I want the hero to render immediately, with no fade-in, so that the page feels fast.
7. As a developer, I want to see near the top that thirdshift is built on Matt Pocock's skills, with links to aihero.dev/skills and mattpocock/skills, so that I understand where its workflow comes from.

Understanding the workflow

8. As a developer, I want the page to show the Day shift (me grilling, writing a spec, cutting tickets with Matt's skills) next to the third shift (thirdshift implementing, reviewing and opening the pull request), so that I understand what I do and what the factory does.
9. As a developer, I want a press line drawn as a sheet-fed press, with a feeder, four units and a delivery pile, so that one issue going in and one pull request coming out is obvious.
10. As a developer, I want each unit to carry a number, an ink and a name ("1 · C · PREPARE", "2 · M · IMPLEMENT", "3 · Y · REVIEW", "4 · K · FINISH" or similar), so that I can follow it without relying on colour.
11. As a developer, I want unit C to show pre-flight, the Origin match, choosing the Issue branch and creating the worktree, so that I know what's checked before any agent runs.
12. As a developer, I want unit M to show the implement session writing the code with the implement and tdd skills, so that I know how the work gets done.
13. As a developer, I want unit Y to show code-review finding Standards findings and Spec findings in the same session, the agent fixing the ones it agrees with, and pr opening the pull request, so that I know the code is reviewed before a human sees it.
14. As a developer, I want a single "one agent session" bracket over M and Y, so that I'm not misled into thinking review is a separate session.
15. As a developer, I want unit K to show merging the Base branch, watching CI, up to three Repairs, and the final check that the pull request is open, ready and mergeable, so that I know what "ready for review" is backed by.
16. As a developer, I want to see what a Failed run looks like (a misprint: work committed and pushed, pull request back to draft), so that I know a failure doesn't lose work.
17. As a developer, I want scrolling to move the press line one step at a time, with each unit lighting up as a complete frame, so that I can take in each stage before the next one.
18. As a developer, I want 1–4 step buttons, so that I can jump back to a unit I didn't follow without scrolling.
19. As a developer, I want a terminal under the press line that replays the real stderr lines for the current unit, so that I can see this is a real tool with real output.
20. As a developer, I want the replay to come from a real Run (issue A thirdshift-plugin-* temp dir can outlive its Run #24, which produced pull request Treat SIGHUP like SIGINT and SIGTERM #25) and to link to that pull request, so that I can check the output against real work.
21. As a developer, I want a Pause control on the terminal replay, so that moving text never runs when I don't want it to.
22. As a developer on a wide laptop screen, I want the press line to use the full width of the page, with the terminal beneath it, so that the diagram is large enough to read.
23. As a developer who prefers reduced motion, I want a static diagram with every unit shown and each unit's real stderr lines beneath it, so that I get the full explanation without animation.
24. As a developer with JavaScript off, and as a search engine, I want that same static diagram in the page's HTML, so that the explanation doesn't depend on a script.
25. As a scroll-only reader, I want the whole story told by scrolling alone, so that I don't miss anything by not pressing buttons.
26. As a developer, I want scrolling to never be taken over (no snapping, no smoothing), so that the page behaves like any other page.

Trusting the output

27. As a developer, I want a "What comes off the press" section that says what "ready for review" guarantees (mergeable, CI passing, reviewed), so that I know what I'm being handed.
28. As a developer, I want to know that findings the agent chose not to fix are listed as Unaddressed findings in the pull request body, so that I know nothing is hidden from me.
29. As a developer, I want links to real pull requests thirdshift made (Treat SIGHUP like SIGINT and SIGTERM #25, Numbered Issue branches after a merged or closed PR #21, CI watching, CI-fix Repair and the Repair cap #22, Pre-flight checks #16), each shown as a proof sheet with its issue, so that I can judge the quality myself.

Seeing where it's going

30. As a developer, I want a "The factory grows" section showing a top-down floor plan, with today's one press line and ghosted, not-yet-installed lines for self-merge (Merge run: a Run that ends with its PR merged #26), /improve-codebase-architecture (Architect run: thirdshift finds and implements a Strong deepening opportunity unattended #27) and implementing a whole spec (make way for thirdshift to implement a spec #28), so that I understand the direction without mistaking it for what exists today.
31. As a developer, I want that section to end with "Engineer the factory while the factory engineers the software.", so that I understand the idea behind building from primitives.

Checking fit

32. As a developer, I want the requirements (claude, gh, git) and the supported platforms (Rocky Linux 9.8+, Ubuntu 24.04.3+, WSL2 with Ubuntu 24.04+, macOS Tahoe 26.5.2+ on Apple Silicon) listed, so that I know whether my machine is covered.

The story

33. As a visitor, I want a colophon explaining why it's called thirdshift, in the owner's own words, so that the name and the look make sense.
34. As a visitor, I want a footer with links to GitHub, the releases, the licence and credit to Matt Pocock, so that I can go deeper.

Prompts and skills page

35. As a developer, I want a Prompts and skills page, so that I can read exactly what guides the agents before I let them work on my repository.
36. As a developer, I want every prompt template a Run can send (fresh, continuation, conflict Repair, CI-fix Repair and Resume), each with one line on when it is sent, so that I understand every point where the factory speaks to an agent.
37. As a developer, I want the placeholders in each prompt (Issue URL, base, branch, pull request URL, failing checks) highlighted, so that I can tell the fixed text from the parts that change for each Run.
38. As a developer, I want the exact claude command line a session runs, including its permission mode and plugin directory, so that I know what the agent is allowed to do.
39. As a developer, I want the full raw text of every Factory skill, including supporting files such as the tdd skill's notes on tests and mocking, shown exactly as the agent reads it, so that nothing is paraphrased.
40. As a developer, I want the page to say which commit of main it reflects, and that the latest release may differ, so that I know how current it is.
41. As a developer, I want each prompt and skill to name the press unit that uses it, and each unit on the home page to link to its skills, so that I can move between the overview and the detail.
42. As a reader, I want the MIT copyright notice for Matt Pocock's skills, and the credit for Dex Horthy's show-me skill, on the page, so that the skills are reproduced properly.
43. As the maintainer, I want that page generated from the same prompt functions and embedded skills the binary uses, so that it can never drift from what the binary does.
44. As the maintainer, I want cargo test to fail when a prompt, the claude arguments or a skill changes without the page being updated, so that thirdshift's own agents are told to update the page in the same pull request.
45. As the maintainer, I want one command to regenerate the page, so that fixing the failure is trivial.

Sharing and discovery

46. As someone sharing the link, I want an Open Graph and Twitter card with an image of the press line, so that the link previews well in chat.
47. As a visitor, I want a favicon in the shape of a registration mark, so that the tab is recognisable.
48. As the maintainer, I want a robots.txt, so that crawlers are told what's allowed.

Operating the site

49. As the maintainer, I want the site served by Caddy on my server with an automatic TLS certificate, so that I reuse what's already running.
50. As the maintainer, I want www.thirdshift.app to redirect permanently to https://thirdshift.app, so that there is one canonical address.
51. As the maintainer, I want a systemd timer on the server to pull main and publish site/ whenever it changes, so that merged pull requests go live within minutes without GitHub holding credentials for my server.
52. As the maintainer, I want the Caddy site block and the systemd units kept in the repository, so that server config is reviewed like code, while installing them stays a manual step.
53. As the maintainer, I want no analytics, cookies or tracking scripts, so that there's no consent banner (Add privacy-friendly analytics to thirdshift.app #54 tracks adding a privacy-friendly counter later).
54. As the maintainer, I want the crate's homepage field and the GitHub repository's About link set to https://thirdshift.app, so that people can find the site from crates.io and GitHub.
55. As a reader of the README, I want the README's install command to stay the direct GitHub Releases command, so that readers already on GitHub see the most trustworthy form.

Implementation Decisions

Stack

• Plain semantic HTML, one shared CSS file, inline SVG, and one small vanilla JavaScript module. There is no build step, no npm dependencies and no framework. Revisit (with Astro) only if the site grows to around four pages. Reasons are in the stack research note under docs/research/.
• Fonts come from Google Fonts, all OFL: UnifrakturMaguntia (wordmark only), Big Shoulders Display 800 (headlines), JetBrains Mono (body, commands, terminal) and Playfair Display italic (colophon). The wordmark font is subset, or the wordmark is inline SVG, so it doesn't delay the first paint. The prototype loads every font in full, which the real site must not.

Visual tokens (from the prototype, ink set A and the "Subtle" effect preset)

The prototype's token objects are the source of truth. Trimmed:

// ink set "A · Process" (prototype/site @ 5b559d0)
"--k": "#0A0A0A", "--k2": "#141414", "--k3": "#1E1E1E",
"--paper": "#E8E6E1", "--dim": "#9A978F", "--rule": "#2A2A2A",
"--c": "#00AEEF", "--m": "#EC008C", "--m-text": "#FF5CB8", "--y": "#FFF200",
"--nc": "#00FFFF", "--nm": "#FF00FF", "--ny": "#FFFF00",   // glows only
"--grid": "rgba(0,174,239,.07)",
// effects "subtle": halftone 35%, misregistration 1px, scanlines 12%

• Process magenta (--m) is used only for large text and fills. Small magenta text uses --m-text.
• The K unit is a paper-white outline with a label.
• Colour is never the only cue: every unit also has a number and a name.

Home page

• Hero ("Proof, compact", prototype hero D):

  • A paper-white proof sheet on the dark page, with crop marks, registration marks and a colour bar.
  • The blackletter wordmark "The Third Shift" heads the sheet, with a slug such as "Proof · pulled at 03:12 · unit 4 of 4".
  • The headline "Your issues go to press overnight." is set at clamp(44px, 7.2vw, 100px).
  • The framing text sits on the left: the day shift / third shift sentence from CONTEXT.md, plus "Built on Matt Pocock's skills" with both links.
  • The install block is printed on the sheet, on the right. It shows the short command with a copy button and a toggle that reveals curl -LsSf https://github.com/JacobStephens2/thirdshift/releases/latest/download/thirdshift-installer.sh | sh.
  • The hero is never faded in from invisible.

• Section order:

  1. Hero
  2. Day shift / third shift
  3. How a Run works (the press line)
  4. What comes off the press
  5. The factory grows
  6. Proof sheets
  7. Requirements and platforms
  8. Colophon
  9. Footer

• Press line (prototype press D): a side elevation of a sheet-fed press with rollers: feeder → C → M → Y → K → delivery pile.

  • Large unit labels, 24px.
  • A thin "one agent session" bracket spans M and Y.
  • On wide viewports the press spans the full content width, and the terminal sits beneath it inside the sticky area.
  • The section is position: sticky and about 3–4 viewport heights tall.
  • A Failed-run misprint path is shown and labelled as illustrative.

• The units follow the code's stages. The inks are only identity. If a Run ever gains a stage (for example a separate review session), it becomes a fifth unit after K, drawn as a spot-colour or coater unit. The C/M/Y/K assignment is not stretched to fit.

  Unit	Stage	Skills
  C	Pre-flight (Origin match, open issue, git identity), Issue branch selection (fresh or Continuation), worktree. Pre-flight prints nothing on success, so the first visible line is the worktree line.
  M	The implement session.	implement, tdd
  Y	Same session: code-review against the base, agreed findings fixed, the rest listed as Unaddressed findings, then pr opens the pull request, already ready for review.	code-review, pr
  K	Push, "checking the PR", merge origin/<base>, CI watch, up to 3 Repairs (conflict or CI red), "checking the PR is open, ready and mergeable", then "PR … is ready for review". A Resume can happen in any session and doesn't count as a Repair.	resolving-merge-conflicts (in Repair)

• Progressive enhancement:

  • The HTML ships the static diagram: every unit shown, and under it one column per unit with that unit's real stderr lines, plus the Failed-run note.
  • The JS module enhances this into the stepped version only when JavaScript runs and prefers-reduced-motion is not reduce. The markup is not built in JS.

• Step state:

  • An IntersectionObserver on the step markers, plus the 1–4 buttons, all call a single render(n) that sets the whole state (lit unit, button state, terminal content). It never applies changes incrementally, so fast scrolling can't desynchronise the press and the terminal.
  • The prototype found that a root margin of -50% 0px -50% 0px never fires in Chrome. Use about -45% 0px -45% 0px.
  • Include a [hidden] { display: none !important; } reset.

• Scrolling: scroll is never hijacked. No snap, no smooth-scroll library, no scrubbed animation. Transitions between steps are short. Continuous motion, if any, is decoration.

• Terminal replay:

  • It replays the real Run on issue A thirdshift-plugin-* temp dir can outlive its Run #24, which produced pull request Treat SIGHUP like SIGINT and SIGTERM #25. Its session lines are rebuilt from that Run's session log on the owner's server, by passing it through thirdshift's own progress condensing so the lines match exactly. That log is ~/.thirdshift/logs/JacobStephens2-thirdshift-issue-24-20260925T134143Z-implement.jsonl.
  • The lines outside the session (worktree, push, checking the PR, merge, CI, final check, cleanup) use the real thirdshift: … progress formats, with pull request Treat SIGHUP like SIGINT and SIGTERM #25's actual branch, commit and CI results.
  • The real session duration and cost are shown.
  • The replay links to pull request Treat SIGHUP like SIGINT and SIGTERM #25.
  • It has a Pause control (WCAG 2.2.2).

• The factory grows:

  • A static top-down floor plan (derived from prototype press B) of the press hall.
  • Today's line is drawn solid. Merge run: a Run that ends with its PR merged #26, Architect run: thirdshift finds and implements a Strong deepening opportunity unattended #27 and make way for thirdshift to implement a spec #28 are ghosted, labelled "not yet installed", and linked to their issues.
  • It closes with "Engineer the factory while the factory engineers the software."

• Proof sheets: Treat SIGHUP like SIGINT and SIGTERM #25 (SIGHUP), Numbered Issue branches after a merged or closed PR #21 (numbered Issue branches), CI watching, CI-fix Repair and the Repair cap #22 (CI watching and Repair) and Pre-flight checks #16 (pre-flight). Each is drawn as a proof sheet with its title, the issue it closed, and a one-line reason it's worth a look.

• Colophon: set in Playfair Display italic, verbatim:

  My dad, Mark Stephens, was a pressman at Tursack Printing, the print shop Robert Tursack Sr. founded in Philadelphia in 1959. My dad worked third shift at the Morgantown, Pennsylvania plant, keeping the big four-color presses running through the night. Sometimes I got to visit, and I always wondered whether I'd end up in printing myself. The lineage carries on. Bob Tursack went on to found Brilliant Graphics in Exton, where my mom still does graphic design. This is as close as I am to printing right now.

  The printing press made copying words cheap. Agents are doing that for code. thirdshift is named for my dad's shift: the machines can run overnight, and I need something to keep them running.

  - Jacob Stephens

• Vocabulary: the site uses the glossary terms exactly. The press words (unit, feeder, delivery pile, misprint, proof sheet) are visual metaphor, not domain terms, and are not added to CONTEXT.md. Avoid "ticket" for anything on the site, since the glossary reserves it.

Prompts and skills page

• Shares the home page's CSS, header and footer.
• Content, in order:
  1. A short introduction.
  2. The claude command line.
  3. The five prompt templates, each with when it is sent and which unit sends it.
  4. Every Factory skill and supporting file as raw monospace text, laid out like job sheets.
  5. The MIT notice from the skills licence and the pr skill's credits.
  6. A line naming the main commit it reflects, and a link to the latest release's skills/.
• Generated content. The page's content (the command line, the prompts and the skills) is a checked-in fragment that the page includes. A renderer inside the crate, used only by tests, produces it:
  • It calls the real prompt template functions with fixed, readable placeholder values, e.g. <Issue URL>, <base>, <branch>, <pull request URL>, and a placeholder list of failing checks.
  • It walks the same embedded skills directory the binary writes out as the plugin.
  • The placeholder values are then marked up as highlighted placeholders.
• The claude arguments: today they are assembled inline where the session command is built. They move into one shared definition that both the session and the renderer use, so the page shows the flags that are actually passed.
• The commit label comes from the deploy step (the pulled commit), not from the generated fragment. Otherwise every commit would make the golden file stale.
• Links to the home page: each unit's skill labels link to that skill's anchor on this page.

Deploy and hosting

• Caddy site block for thirdshift.app:
  • file_server from the published site/ directory;
  • www.thirdshift.app returns a permanent redirect to the bare domain;
  • /install.sh returns a 302 to https://github.com/JacobStephens2/thirdshift/releases/latest/download/thirdshift-installer.sh.
• Pull-based deploy: a systemd service and timer run a small shell script every few minutes. It fetches main, and if site/ changed, it copies site/ into Caddy's web root atomically (for example, build a new directory and swap a symlink) and records the deployed commit for the Prompts and skills page's label.
• Config in the repository: the Caddy block, the units and the script live in a deploy directory inside site/. They are excluded from what gets served.
• Launch extras: a registration-mark favicon (SVG), an Open Graph and Twitter card image of the press line, robots.txt allowing everything, and page titles and descriptions.
• No analytics.
• Homepage links: the manifest's homepage is set to https://thirdshift.app. The README's install section keeps the GitHub command.

Testing Decisions

• What a good test is here: it asserts on external behaviour, meaning the rendered content of the Prompts and skills page, not how the renderer builds it.
• The golden-file test (one new seam, inside the crate):
  • It renders the Prompts and skills fragment and compares it byte for byte with the checked-in fragment. It fails with a diff and a hint naming the update command.
  • With an update environment variable set, it rewrites the fragment instead.
  • Because the crates.io package includes src/ but not site/, the test skips itself (with a message) when the site directory is absent. Otherwise the packaged crate's tests would fail.
  • Prior art for an in-crate test module is the progress module's unit tests.
• The shared claude arguments are covered by the existing Run tests, which drive the binary against the fake claude. They must keep passing unchanged.
• Packaging: the existing packaging test must keep passing, and site/ must stay out of the crate package.
• No automated front-end tests. The site's front end is checked by the implementing agents' own screenshots during their Runs, and by a ready-for-human acceptance pass. No Playwright or Node in CI.
• Acceptance (human):
  • Load both pages on a laptop and a phone, in Chrome, Safari and Firefox.
  • Check the press line and terminal stay in step when scrolling fast and when using the buttons.
  • Check the Pause control.
  • Check reduced motion (the static diagram) and JavaScript off.
  • Check the install command works when pasted.
  • Check deploy config with curl: the site returns 200 over HTTPS, www redirects, and /install.sh returns a 302 to the release asset.
  • Merge a trivial site/ change and confirm it goes live within the timer's interval.

Out of Scope

• Analytics (Add privacy-friendly analytics to thirdshift.app #54).
• Astro or any build tooling, npm dependencies, or scroll/animation libraries (GSAP, Motion, Lenis). Also WebGL or wasm.
• A WebGL halftone shader. Effects are CSS and SVG only.
• Changing the README's install section. It keeps the GitHub command. The homepage field is the only manifest change.
• Rendering the skills' Markdown as formatted HTML. They're shown raw.
• Showing the latest release's prompts instead of main's.
• Installing the Caddy block and systemd units on the server. That's a manual step.
• Merging prototype/site. It is throwaway.
• Any change to how a Run behaves.

Further Notes

• The prototype: branch prototype/site @ 5b559d0. Serve it with python3 -m http.server -d site 8029 and open /prototype/?h=D&p=D&t=A&mode=motion&fx=subtle (or mode=static) to see the approved look. Its terminal lines use a made-up acme/widgets#7 Run; the real site replaces that with the A thirdshift-plugin-* temp dir can outlive its Run #24 Run.
• Research: the design and stack research notes are in docs/research/. The Tursack Printing history (background for the colophon and visual details) is there too.
• Inferred line order: the order of lines on a Failed run (cleanup before the error line) was inferred from the code, not observed, which is why the misprint is labelled illustrative.
• Humans only (ready-for-human):
  • install the Caddy block and systemd units on the server;
  • set the GitHub About link;
  • run the acceptance pass.