Foreman / Registro delle modifiche
Registro delle modifiche.
Ogni versione e il progetto o feedback che l’ha motivata. La versione attuale è 3.0.1, del 27 ottobre 2026.
- Sito e documentazione, 30 ottobre 2026
- 3.0.1, 27 ottobre 2026
- 3.0.0, 27 ottobre 2026
- 2.2.0, 25 agosto 2026
- 2.1.0, 25 agosto 2026
- 2.0.0, 25 agosto 2026
- 1.9.0, 25 agosto 2026
- 1.8.0, 25 agosto 2026
- 1.7.0, 25 agosto 2026
- 1.6.0, 25 agosto 2026
- 1.5.0, 25 agosto 2026
- 1.4.0, 25 agosto 2026
- 1.3.0, 11 agosto 2026
- 1.2.0, 10 agosto 2026
- 1.1.0, 10 agosto 2026
- 1.0.0, 6 agosto 2026
Note di versione in inglese
Website and documentation, 30 October 2026
The installable skill remains at 3.0.1. This update changes the public website and its documentation, not the session flow or skill files.
- Refined film captions with a padded overlay, custom language and speed menus, and a Films link in desktop and mobile navigation.
- Published five short Foreman product films at
/film/, with individual watch pages, 33 caption languages, transcripts, custom thumbnails, localized share cards and a video sitemap. The films use English narration and nonmusical sound design. - Rebuilt the site with a monochrome theme, clear glass navigation, a hard-hat identity and transparent favicons.
- Added visual examples for Board, Punch list and Launch, alongside Palette’s colour swatches.
- Added the reference-guided Dana portfolio and an initial-draft comparison. The example’s documentation records its inputs and review; it is not a controlled benchmark.
- Added a custom 404, refreshed page-specific share cards, and checked mobile layouts, keyboard controls, links and metadata.
- Replaced stale README screenshots, including the terminal card that still showed 3.0.0. README preview assets are now generated from the current site and skill, with freshness checks in CI.
3.0.1, 27 October 2026
Adds measurement tools and corrects folder-first intake. A full clean scenario benchmark has not been completed for this patch.
Added:
- The bench, in
bench/: real Claude Code sessions, played out against a simulated owner from a fact sheet, with and without Foreman installed, then measured in a browser. It counts what a visitor meets: numbers on the page the owner never gave, the default AI palette, dead links, overflow on a phone, contrast failures, missing metadata, a missing 404, dashes, and stock SaaS words.review.pyshows each pair blind for a person to judge. Its README says what it cannot tell you, and documentation takes numbers only from its clean runs. - The field count,
bench/field.py, which reads real Claude Code and Codex transcripts and prints how sessions where Foreman actually spoke went, as counts only. - The pulse,
bench/pulse.py, which appends GitHub's stars, traffic, referrers and downloads to a log, because GitHub forgets traffic after 14 days. - A session report form, and one line at the close of every session pointing to it, including the sessions that went badly, which are the ones most worth hearing about. Foreman still sends nothing anywhere on its own.
Changed:
- The failure report form named the old phases. It names the eight steps and the tools now.
Fixed, from the bench's first runs:
- Orient reads the folder. In both of the first two runs Foreman asked the owner for numbers that were sitting in
project-notes.md, then asked her to paste the notes. Step 1 now lists the project folder and reads the files about the subject before anything else, in every mode, and never asks a question a file already answers. - The bench gave Foreman its own files. Headless sessions could not ask to read the plugin folder, so the skill ran without its references and assets. The runner now grants that read, as a user clicking allow would.
- The simulated owner stops claiming files. It kept saying screenshots were in the folder when they were not. It now knows nothing else is there and says so.
- The simulated owner runs in safe mode. On a test run with the author's own config, his rules walked the owner model out of its role mid-session, and the run stalled with nothing built. The owner now never loads a CLAUDE.md or rules file. The agent cannot do the same, because safe mode also blocks the plugin, so clean agent runs still need their own login.
3.0.0, 27 October 2026
Major, because the session flow changed: it now runs at three depths, and four of its parts can run without the session at all.
The evidence this time was feedback rather than a broken build. People who ran Foreman said it asked too many questions, and they were right about the cost and wrong about the cure. The cure most tools reach for is to ask less and assume more, and an agent that assumes is an agent that lands on the average, which is the page this playbook exists to stop. So the questions did not get fewer for free. In the new short mode, every question that is skipped becomes research the agent has to do instead.
Added:
- Three modes: Survey, Blueprint, and Stress test. A mode changes how many questions are asked and who does the legwork. It never changes which decisions get made, and every gate holds in all three at the same resolution. Blueprint is the full interview as it was. Stress test pushes every answer once, runs a pre-mortem before the brief freezes, makes the reference board part of step 3, and runs the full punch list plus a stranger test at step 6.
- Survey researches instead of asking. It reads the repo, the current site, the CV and the product's docs, looks at four or five real sites in the category to see what they all do, and sends the step 2 decisions as one sheet with a source on every line. An assumption with no source is a question and still gets asked. The palette pick, the copy, and the sign-off on the brief stay with the owner in every mode, because those are the decisions the playbook exists to put in their hands.
- The mode is never a question. The card carries a
MODEline, the owner switches by saying the word at any point, and a session started with a mode word opens in it. Asking someone how many questions they want is one more question. - Questions in the cheapest form available. Where the harness has a structured question tool, a question with a likely answer goes through it with the recommendation first and room for their own. Most of "too many questions" turned out to be too much typing.
- The toolbelt. Four tools, each one file in
toolbelt/, that run on their own or mid-session without losing the step: board (real sites chosen for this brief, as a list or a visual board, ending in named principles), punch list (an audit of any site, ranked, each item with its fix, and no invented score), palette (three variants from a named material, contrast checked, inbrand.html), and launch (domain, DNS, SSL, metadata, the 404, the sitemap and indexing, for a site built anywhere). In Claude Code they are also slash commands,/foreman:board,/foreman:punch-list,/foreman:paletteand/foreman:launch, through four thin wrapper skills that read the same files. - The visual board has a condition. It is built only when the session can capture real screenshots. A board of text cards is a list in a costume, and the list is the default because it works everywhere, a phone included.
references/standards.md, a fourteenth reference: colour theory, proportion and the golden ratio, type scale and measure, spacing, gestalt grouping, hierarchy, motion timing, and optical correction. Written as standards, not rules: each is a default with a reason, departed from on purpose with the reason written inBRAND.md. It is honest about the golden ratio, whose mathematics is real and whose aesthetic claims mostly are not.assets/reference-board.html, the throwaway visual board, with keep and skip marks that work without a line of script.- The same opening in Survey, added to the worked example.
Changed:
- Rule 4's compressed run is now Survey, with the legwork moved to the agent.
- The stamp carries the mode outside Blueprint, and each tool stamps its own name.
- The brief template records the scale ratio, the spacing base, and the standards departed from.
- The plugin's homepage is the site rather than the repository, and the README, the plugin README and the manifests were rewritten around install, usage, the modes, and the tools.
- The README badges said version 1.3.0 and nine references while the playbook was at 2.2.0 with thirteen. That is the stale-number failure this playbook warns about, on its own front page. The version now has one source,
plugin.json, and CI fails when any copy disagrees with it. - The site is generated from
site/byscripts/build_site.py, which takes every version and count from the manifest and the folders, and CI rebuilds it to checkdocs/matches.
2.2.0, 25 August 2026
The most important change in the 2.x line, and a correction rather than an addition. The playbook had grown a veto it was never supposed to have.
The run that showed it: asked for a placeholder logo row so the owner could judge a layout, it answered "I am Foreman. I do not build templates and I do not put placeholder logos on pages, not even to check if it looks good. If you want a placeholder logo row, you can add it yourself or hand the brief to another coding agent." Every part of that is wrong. It opened by asserting its own authority, refused a layout question on a content principle, lectured, and closed by suggesting the owner go elsewhere. An hour earlier it had told the same owner that editing their own copy would mean abandoning the brief.
Added:
- Rule 8: the owner decides, you advise, once. It outranks the other seven wherever they collide. Say what a choice costs in one sentence, offer the alternative in one more, then it is settled and you build it at full effort and never raise it again, because a thing built grudgingly is worse than the thing they asked for and they can always tell. Explicitly theirs, whatever the playbook thinks: copying a site or one element out of it, a logo row, a stats band, testimonials, a pricing table, a carousel, going dark, keeping the gradient, any change to their own copy at any point, and anything they want on the page for ten minutes so they can look at it. None of it is a refusal.
- "It goes against the brief" is never a reason to tell them no. The brief records what they decided and they are allowed to decide something else. An agent that informs its owner they have violated their own brand guidelines has forgotten whose guidelines they are.
- Never open with what you are. "I am Foreman, and I do not" is an appeal to an authority the playbook does not have. State the thing, not your standing.
- What the playbook does hold, named as three things and none of them their taste: the sequence, because the decisions are worth more than a head start; the quality floor, because they asked for a site that works; and its own output, which does not invent a statistic, a customer, a quote, or a paragraph nobody wrote. That last one is the confusion at the centre of this release. Not inventing on your own initiative is a rule about the agent. It was never a veto over the owner.
Changed:
- Every prohibition in the references now says which direction it points.
vibe-coded-tells.mdis a list of the agent's own reflexes, and asking for one of them by name is the owner choosing it, which was always the stated test.design-direction.mdrefuses your reflexes, not their requests, and now covers the case where someone asks for a deliberate copy: say what it costs, offer the principle-extraction version, build whichever they pick, and build it well. The brief's own line now ends "this is about what you add unprompted; anything I ask for, build." - The gates are about sequence, not taste. "We are not choosing colours before the copy exists" is a gate. "You cannot have that colour" is overreach.
- Rule 7's element test is a question you ask, not a permission you grant.
- The layout-probe paragraph no longer grants conditional permission. When they want to look at something, build it and let them look. Grey boxes are a fine suggestion and a terrible condition, and what a shipped version would claim is worth saying at the point it is about to ship, not at the point they asked to see it.
- "What you are" now states the mechanism plainly: everything worth anything in a Foreman session comes from a decision the owner made that they would otherwise have skipped, which makes them the authority on all of it and makes the agent the one who gets those decisions made rather than the one who makes them.
2.1.0, 25 August 2026
A third run, and the front half of the playbook held. The interview refused "try the tool" as an action, ran the competitor swap on the job, and refused "repetitive tasks" until it got seventeen minutes against two minutes twenty. The shape, the material, what carries the page, the composition sentence, and the five-part signature spec were all asked and answered. The files were written and the build happened in session.
Then six iterations went in circles. Everything in this release is from the back half.
Added:
- Copy gets assigned to a slot. Locking the copy was never the end of the step: copy with no home is copy the coding agent puts wherever there is room, and there is always room in the hero. Five good sentences and one hero slot produced a four-paragraph hero, and the owner correctly called it stacked. The brief now carries an opening, a support line, an action, everything else below the fold, and an explicit cut list. A hero is three things; a fourth is a paragraph pretending to be a hero.
- The freeze binds the builder, not the owner. The run told the owner that changing their own copy meant abandoning the brief, and offered a choice between keeping it locked and re-opening it. That is backwards. The brief is frozen against an agent substituting its taste, never against the person whose site it is. Changes from the owner are amendments in three moves: name what it invalidates, re-decide only that at the same resolution, update the file and stamp it. No ultimatum, and nobody is told they broke something.
- A mid-build reference gets the step 3 procedure. "Take some taste from Railway and Raycast" arrived with seven buildable principles attached and was answered by adjusting CSS and reporting that the influence had been pulled in. It now gets extracted, read back, written into
BRAND.mdas an amendment, and then built. Where a principle contradicts what was locked, the contradiction is the thing to raise rather than a reason to defend the earlier decision. - Rule 6 applies hardest during iteration. Steps 1 to 4 are slow by construction and then the build starts and every message becomes a fast reply to the last thing said. The owner had to write "think longer, and deeper" to stop it. If they have to say that, you had already stopped.
- "Does this hit the mark?" is banned. It is "do you like it" wearing a collar, it invites a taste answer, and a taste answer is not actionable. Say what changed as a list, then ask about exactly one thing.
- A placeholder you look at is not a placeholder that ships. The run refused to build a logo row for evaluating a layout, correctly on the principle and wrongly on the case, then shipped a placeholder background image an hour later. Fabricated evidence is about what a visitor sees. A layout probe made of grey boxes labelled
logois how you decide a grid, and it comes out in the same session it went in. - The metadata line is on the first-build checklist. The head block was in the brief, was skipped in the build, and was only caught when the owner asked where it was. It is invisible in a screenshot, which is exactly why it needs a line of its own.
Changed:
- Refusals are one sentence. The logo-row refusal was the right call delivered as a lecture, opening with a statement of identity, restating the principle twice in one session, and closing by telling the owner to go and use a different agent. Rule 3 now covers it: refuse in one sentence, offer the nearest real thing you can build, and move. They came for the judgement, not for a rebuke.
- Content is an input covers images too. Offering to generate a moody backdrop to fill a media slot is the stock hero arriving by a longer route, and it is now named in
vibe-coded-tells.mdas its own tell.
2.0.0, 25 August 2026
Major, because the session gained a decision it never asked for and the brief gained two sections that decide most of what a page feels like.
The evidence was a second full run in Antigravity, where the interview worked, the opening line got fixed, the material question got a real answer, and the page still came back as a centred dark column with an enormous headline, two equal boxes holding one sentence each, and a dead button. Every gate held. So the remaining failure is not in the flow, it is in what the brief does not say.
Added:
references/composition-and-choreography.md, a thirteenth reference, covering the two decisions a brief silently hands to the coding agent: where everything goes, and what happens in the first two seconds. Both are things a reader actually experiences, and every constraint in the quality floor can pass while a page fails at both. It carries the spacing backbone (one gutter pair used by every element touching the page edge, through whatever mechanism each needs), the declared layer stack, three composition archetypes, the entrance choreography table, the interaction inventory, specifying behaviour as an algorithm with named constants rather than as an adjective, marking tuned values so a tidy-up does not round them, and declaring the compromises worth keeping so nobody fixes them into something worse.- What carries the page, as a named decision: media, type, structure, or an artifact from their own subject. When it is media at full bleed, the brief now says so completely, including no scrim, tint, gradient, blur, or blend mode over it, because dropping a dark gradient over an image is the reflex that turns a photograph into a background.
- The shape of the site, asked at step 3 and never assumed: one non-scrolling viewport, one scrolling page, or several pages. The middle one is the default failure and it gets chosen by not choosing, which is how five sentences of copy become a hero plus two boxes. The test is a count: under four content units is one viewport, four to eight is one page, more than eight with categories is several.
- A
NON-NEGOTIABLESblock in the brief, for the things that are the point of the build and that a tidy-up would quietly remove.
Changed:
- Size follows the length of the line. Fixing the opening line usually makes it longer and more specific, and then it gets set at display size out of habit, producing a wall of text where a headline should be, which reads as less considered than the vague version it replaced. Up to six words can be enormous; six to twelve comes down hard; past twelve it is prose that happens to be first, and the display move goes onto a number in it, onto one word, or onto the artifact instead. Letter-spacing tightens at display sizes and is left alone at reading sizes. Two weights.
- One of the three palette variants is light, whatever the material was. A dark material honestly reads dark, and dark is also where the model was going anyway, so the material has moved nothing and neither party can tell. Every dark material has non-dark things in it: a server rack is aluminium rails, label tape, and a printed rack diagram, and only the room is dark. If they still choose dark after seeing the same material in daylight, it is a decision. Until then it is the default wearing a story.
- Verification watches the first three seconds, loads the page with animation blocked to confirm it is complete without it, and holds the composition sentence next to the screenshot.
- Two additions to
vibe-coded-tells.md: a page that arrives all at once and then sits there, and everything centred and symmetrical. CONTRIBUTING.mdnow admits that thirteen references is past the point where an agent reliably loads them all, which is why the irreducible move from each is repeated insideSKILL.md.
The governing warning, written into the new reference: the pages that teach this are mostly dark with video grounds, and that is an accident of where they came from. Copy the resolution of their specifications, never their values. A page built on someone else's easing curve, gutter, and accent is a clone with a new name on it.
1.9.0, 25 August 2026
From a full 1.7.0 run in Antigravity. The steps ran, the gates were stamped,
and the page was still the generic one, which located the failure precisely:
every gate was declared met without being met, and nothing in the playbook checked.
Changed:
- The first-message card is pure ASCII now. Block and box-drawing characters look better and fall back to a substitute font in any client whose monospace face lacks the glyph, and a substitute has a different advance width. That is what a wandering right border and a smeared face are. The card uses nothing above code point 126 and cannot fall back.
- A stamp is a claim that the gate is met. Before writing one, say what is missing. If every field cannot be filled from something they actually said, the gate is not met, and a false stamp is a thing the next six steps get built on. The observed case stamped
job: present tool to solo devs, which is a category, not a job. - Step 2 carries the interview inline rather than delegating all of it to
content-interview.md, because a partial file load produced four questions and a shipped draft. Six questions in order, with the competitor swap as the test for the one job: if a rival could put the same sentence on their page unchanged, it is a category. Evidence gets asked for twice, because the first answer is a summary and the second is the fact. - Copy they paste is a first draft, not an input. The strongest pull in the step is to receive finished-looking copy, say thank you, and move on, which is how a careful interview still produces a generic page. Everything pasted now gets read against the opening-line test first.
- The buried headline, in
content-interview.mdand the worked example. People lead with an abstraction and then say the true thing one row lower as though it were support. "Build faster without giving up control" is true of every developer tool ever shipped; "gets repetitive work done in a few minutes instead of fifteen or twenty" has a number in it and was already in the next sentence. The most common fix is a swap that invents nothing. - The material question is now in
SKILL.mditself, in the words to use, and it fires before any hex value exists. Delegating it topalette.mdmeant the reference library got read and the palette workflow did not, and the step collapsed into "here are three directions I made". - When they name a colour, that is the start of the question. "Swap the green for blue" is reasonable and blue is a family with a thousand members, so left alone you hand them the framework's. Blue of what: a blueprint, a gas flame, a Delft tile, ink on a bank note, the shadow on snow. Mid-review corrections are where the palette most often collapses back to the default, because the change feels small.
- If you built it, you verify it. The observed run built the site and then handed the owner four things to check in their own browser. You have the files, and they cannot tell a real 404 status from a 200. Their job is to react to the result.
- The first-build checklist gained a seventh item: the section count against the copy. Five sentences that became a hero and two boxes means the boxes exist because the page looked short. Copy decides sections.
1.8.0, 25 August 2026
The handoff was written when the brain was assumed to live in a chat. It is not, most of the time, and telling an agent that can write files to go open a different agent is friction invented by an old assumption.
Changed:
- Step 5 is now a fork, and it asks. First, can this session build: you know your own tools, and if you can write files and run commands you can build the site. Second, and regardless of the answer, ask them which they want. Someone paying for another agent may want it there, someone who wants to watch wants it here, someone on a phone has no choice. Never assume either direction.
- Building it yourself has its own rules, because it is the weakest position in the playbook: you become the coding agent and its reviewer at once and nobody is checking you. Build from the two files rather than from your memory of the conversation, since the conversation holds every rejected option and the files hold the decisions. Spawn a sub-agent or a fresh session where possible and give it only those two files, because a clean context building from a brief beats a long one building from a recollection. That was always the real reason for the handoff and it survives the handoff going away. Run the six-item checklist against your own output before showing anything, and re-read
BRAND.mdbefore every visual change. - Rule 1 got the loophole closed. Knowing you will build it yourself is not permission to start early. It is the strongest reason not to, because code written before the decisions exist is code you will defend afterwards, against the person whose site it is.
- The brief goes on disk as two files.
BRAND.mdholds the locked tokens, the material sentence, the type scale, the motion rule, and the signature element spec, and is re-read before every visual change, which is what stops the tokens drifting.BRIEF.mdholds everything else and points atBRAND.mdrather than repeating it, since two copies of a hex value disagree within a week. The split exists because the two are read differently: the brief once at the start,BRAND.mdevery time a colour is about to be chosen, which is exactly when an agent reaches for its defaults. A brief that lives in the chat is gone when the context is. - "You do not write the site" became "the order is the product, who types is a detail", across the skill, the site, the README, and both manifests.
1.7.0, 25 August 2026
Added:
- What to do when another design skill is loaded in the same session. A taste, UI, or component skill alongside this one is useful for execution quality and component detail, and none of it gets the palette, the type, or the direction. When another skill's defaults and the locked tokens disagree, the locked tokens win without discussion. Two opinionated design systems in one session converge on whichever is more prescriptive, and the more prescriptive one is never the one derived from the owner. The playbook also never tells anyone to install anything: markdown with no scripts, no network calls, and no dependencies is worth more than any skill it could pull in.
- Machine-readable design systems in
reference-library.md, the newest category of reference and the most dangerous because it is the most useful. A human reference gets half-remembered, which is a filter. ADESIGN.mdwritten for an agent gets pasted, and the build carries another company's hexes, radius, and easing curve under the owner's name. The section uses a published Tesla analysis as the worked case: what does not transfer, the seven principles that do, and the two tests. If you cannot state what you took as a sentence about behaviour, you took the tokens. And check the principle against what they have, since "the photography carries everything" is an empty page for someone with three screenshots. - Effects and components as a reference category, for when the signature element is a treatment rather than a layout.
- The treatment of their own image, in
design-direction.md: the cheapest signature element that cannot be generic. Render a photograph they already have through ASCII, dither, halftone, contour lines, a duotone, or a plotted trace. The input is theirs, so the output cannot be a stock aesthetic, and every one of these is buildable in an afternoon. The failure mode is applying it to a stock photograph, which is the average with an extra step.
Changed:
- A design system pasted in whole is now named in
vibe-coded-tells.mdas what it is: the framework defaults again, with a more respectable source.
1.6.0, 25 August 2026
From a full eight-step run on Gemini in Antigravity. The gates held and the output was still generic, which puts the failure in the design step and the brief rather than in the flow.
Added:
references/palette.md, a twelfth reference and the answer to the clearest convergence in the whole playbook: left alone, an agent produces a near-black ground, grey neutrals, and a blue or violet accent, for every subject in every field, immediately after being told not to. A rejection list narrows the space without pointing anywhere, so this is a workflow instead. Ground before hue, with eight grounds and what each costs. A named material before any hex, because "the orange on the emergency stop" does not arrive at#6366F1. Derive from an image they already own. Neutrals tinted from the accent rather than grey. An accent budget of about four named places. Variants that differ on ground mode, accent family, personality, and contrast strategy, so three shades of one idea cannot pass as three options. Contrast checked before the owner sees anything,--on-accentas its own token, and the list of specific hexes and hue ranges that need a stated reason.- Rule 7: product grade, including the throwaway. The standard is the work you would hand the client who pays the most, and it does not drop because this one is a test. Every control works or its control is removed. Every element justifies itself in one sentence, which is what rules out the pill around a heading and the eyebrow label on every section. A bare section gets shorter, never fuller. Nothing real finishes in a minute.
- The first-build checklist at step 5. Six things asked for by name before anyone discusses how the page looks: the hover and focus states pointed at, every control clicked, 375px, the 404 reached from a bad URL, the signature element at spec, and the locked hex values present in the built CSS. Design notes on a build with no states in it are notes on a draft.
EVERY CONTROL WORKSandEVERY ELEMENT JUSTIFIES ITSELFas brief blocks, plus--on-accentand the material sentence in the locked tokens.
Changed:
worked-example.mdwas demonstrating the failure it warns about. It locked#0B0D10with a#5B8DEFaccent, which is precisely the convergent palette, in the one file the agent reads before its first session. Rebuilt around the material question and an aluminium and emergency-stop-orange palette with every contrast pair checked. It also now records a first build that came back in two minutes with no hover states, a dead button, and a bare 404, since that is what a fast build actually contains.brand-harness.htmlwas anchoring too. Its three shipped variants were dark navy with blue, white with green, and dark with gold, which is the space the model already defaults to. Replaced with three that differ on axes rather than on shade: mid-tone signage green with signal orange, institutional paper with oxblood, warm dark with amber. No blue, no violet, all contrast-checked, and the file now says in the header that replacing all of these values is the job and that a winning palette identical to one of them means the step did not happen.- The brief is read back against
palette.mdbefore it freezes. A dark ground with grey neutrals and a blue accent that nobody can trace to a real thing is worth reopening step 3 for, because it is cheaper there than anywhere later.
1.5.0, 25 August 2026
Added:
- The first message is a card. An ASCII wordmark, the foreman portrait, and a boxed panel carrying the playbook name and version, the step, the method in six words, and the rule that no site code appears until the brief is signed off. It is the session's whole introduction, so nothing follows it except the question on its last line, and the wordmark never appears again. Every line inside the box is the same width, and the skill says to paste it rather than retype it, because one stray space breaks the whole thing. There is a documented fallback for narrow surfaces and for harnesses that mangle it: a broken box is a bug, not a brand.
- Rule 6: think for longer than the reply takes to read. Re-read their last message for the throwaway clause, which is usually the constraint. Name what just changed and what it invalidates. Ask the question that moves the build furthest rather than the next one on the list. The first answer that occurs to you is the average answer, a thin answer gets a follow-up rather than a new question, and anything you have written on another build means you are pattern matching instead of listening. Long thinking and a short message are the same discipline.
- Strings that claim a fact, in
metadata-and-404.md: a version in the footer, a last-updated date, a copyright year, a count in the copy. One source per number, a generated copyright year, alastmodthat is not six months behind the deploy, and the list of every place a version appears written into the release routine. Now aFOOTERblock in the brief and a check at step 6. - A release routine in
AGENTS.mdnaming all six places the version lives, because this repository shipped 1.4.0 with the site still reading 1.3.0.
Changed:
assets/404.htmlnow has the nav and the footer on it. The old template told the coding agent to reuse the site layout and then demonstrated the opposite: a centred box on an empty background, which is the host default wearing the site's palette. It now ships the chrome, the interactive states, and the reduced-motion block, and the brief's one-line 404 requirement was replaced with the full spec so what the coding agent reads matches what the reference says.- The brief asks the coding agent to point at the hover and focus states of the primary action, the nav, and a card when it hands the work back. A rule nobody has to demonstrate is a rule that quietly does not ship.
- Stale counts corrected across the site and the docs: seven phases, nine references, and "the same nine places" were all wrong after 1.4.0.
1.4.0, 25 August 2026
The release that answers the three reports in the tracker, plus the two failure modes the playbook was causing itself: steering toward pages with no life in them, and assuming every site is somebody's portfolio.
Added:
- Four rules at the top of
SKILL.mdthat outrank the rest of the file. No site code before the brief is frozen, one step per message, reasoning stays in the chat, gates hold under pressure. They sit above the step list because an agent that reads the whole file and then builds anyway has not disobeyed anything specific enough to disobey. - The step stamp. Every message opens with
FOREMAN · 3/8 · LOOK, and a cleared gate is stamped once with what is now fixed. The user can follow the build from the stamps alone. The stamp is also the agent's own anchor: it cannot skip to the build without writing down that it did. - A scripted answer to "just build it." Compress to four exchanges, never to zero. "Pick for me" is answered with named options, never with one finished result.
- "Refuse the unfinished page" in
design-direction.md, with a five-point check: type that does real work, vertical rhythm, one thing that breaks the column, detail at the small scale, and a response on every interactive element. Simple was never the failure. Unresolved is, and in a screenshot the two are identical. - Motion rules. State changes always, the signature once, decoration never.
prefers-reduced-motionis the same page at its resting frame, and the resting frame gets designed first because it is every screenshot anyone takes. - A five-part signature element spec in the brief: what, where, what it does, at 375px, and under reduced motion. An unspecified signature element is the first thing a coding agent downgrades to a static image.
- Hover, focus, transition, and selection states in
brand-harness.html, plus--durand--easetokens per variant, so the owner picks a look with its behaviour attached rather than a still frame. - Verification now checks the register word, the hover and focus states, the reduced-motion frame, and whether the coding agent substituted the signature element or padded the page with filler copy.
references/vibe-coded-tells.md, a tenth reference. The patterns that mark a page as generated, in layout, colour, type, copy, motion, affordances, and in the source. It includes the tells that are absences rather than elements: no empty state, no error state, no loading state, buttons that do nothing, content that never varies in length. A rejection list at step 3 and a checklist at step 6, with a search for the locked hex values in the built CSS, because framework palette names in the class strings are proof the tokens never shipped.references/reference-library.md, an eleventh reference, and the reference step that uses it. Offered once with the skip attached, because most people have no references and will not go looking unless handed somewhere to look. Around fifty places sorted by what each is good for: galleries, product and interface, motion, type, colour, and the non-web sources that produce the least derivative results, since nothing there can be copied directly and only the principle survives the trip. The agent sends the three or four rows that match what is being built, never the whole file, because a list of forty links is a way of not choosing.- Icon sets. Ten of them by voice rather than by popularity, the note that most personal sites need three brand glyphs and not a set at all, and the rules that go in the brief: one family, one stroke, tokens not defaults, never an icon carrying meaning alone.
- Rule 5: no em dashes, anywhere. Not in the agent's messages, not in the brief, not in the site copy, not in alt text, a meta description, a commit message, or a filename. En dashes included, ranges get the word "to". It is the loudest punctuation tell of generated text, and one of them in the line at the top of the page undoes a great deal of the rest of the playbook. It now sits in the brief as a constraint, in the verification checklist as a search, and in
vibe-coded-tells.mdas what it is. - A one-line introduction on the first message. The session opens by naming itself and saying who runs the decisions, then asks the two orient questions. One line, never a tour of the eight steps. The name appears exactly twice in a session, here and at the close.
Changed:
- Phases are steps, numbered 1 to 8. The file said seven phases and had eight, numbered from zero, which made "step 3 of 8" impossible to stamp correctly. Renumbered across the skill, the references, the README, and the site.
no animationis no longer offered as a default non-goal. It shipped pages that felt like a PDF. The default non-goal isno scroll-triggered animation, and the brief now states that state transitions are not on that list.- The brief tells the coding agent to use the copy verbatim and to add no explanatory sentences of its own. Filler copy in an empty-looking section is how a page ends up explaining itself to its reader.
content-interview.mdextends the no-justification rule to the agent's own messages: no preambles, no recaps, no defending an unchallenged constraint, no apologising for asking. It reads as doubt and it reopens settled gates.worked-example.mdshows the stamps, the specified signature element, and the "just build it" push being turned down in three sentences.- The playbook no longer assumes every site is a portfolio. The content interview opens by establishing what kind of page this is, with a table of six common kinds and what the top of each owes its reader. The table is explicitly examples rather than a menu, since most real sites are two rows at once and plenty are no row at all. When it is not listed the question does not change: what did this reader come for, and what do they need in the first five seconds of having it. "The hero line" is now "the first thing the reader reads", which on a restaurant page is the hours and the address, not a sentence about craft. Project entries became content units, the bio became the about section, and
brand-harness.htmlno longer puts[REAL HERO LINE]in theh1of a page that may not have one. - Fabricated evidence is now called out by name and refused rather than restyled: invented metrics, logo rows of non-customers, testimonials from people who do not exist, charts with no data. It is attached to the owner's real name, which makes it their problem and not a styling question.
Credit: issue #3 (a reference step), issue #4 (the site looks too simple), and issue #5 (the AI over explains) in the tracker.
1.3.0, 11 August 2026
Added:
references/design-direction.mdnow refuses the single accented word. Colouring one word of a headline in the brand colour is one of the strongest tells that a machine set the type, along with the one-word gradient, swoosh, and highlighter block. The section gives the structural alternatives that are actual decisions.- Gates for phases 4, 5, 6, and 7. The playbook claimed seven gated phases and only had four.
- A hard number for the hero media cap, 1.5 MB, in
performance-and-access.mdand in the brief template, which previously read[X] MB. This is the constraint whose absence produces the failure inworked-example.md.
Changed:
- The failure-modes list names the agent's own version of the first failure: presenting a finished visual system instead of variants the owner chose from.
assets/brand-harness.htmlnow fills all three variants. It previously shipped one filled variant and two empty stubs, so the side-by-side comparison the file exists for could not happen without extra work.- The Close section can now truthfully say the repository is linked in the skill, because it is.
1.2.0, 10 August 2026
Added:
references/worked-example.md: a full run from Phase 0 to a frozen brief, plus the failure that followed.references/bilingual-rtl.md: second languages as a layout problem, RTL mirroring, type, URL structure.references/stack-choice.md: what to recommend, what to refuse, how to end the stack debate.- An opening script for Phase 0, so the first message is consistent.
- A single attribution line at the end of a successful ship.
Changed:
- Skill slug is now
foreman(wasforeman-by-turki-alshuaibi). Attribution moved todisplayName, the author field, and the README, where it belongs. - Description broadened to cover redesigns, hosting, DNS, Open Graph, indexing, Lighthouse, and RTL, which are the moments people actually ask for help.
- Packaged as a Claude Code plugin marketplace.
1.1.0, 10 August 2026
Added:
references/content-interview.md: Phase 1 question sequence, hero line test, project entry shape, bio standards.references/metadata-and-404.md: head block, OG image rules, JSON-LD, crawl files, and a real 404 spec.references/performance-and-access.md: image, video, font, and JavaScript constraints, accessibility floor, and the budget to write into the brief.assets/head-metadata.html,assets/404.html,assets/robots.txt,assets/sitemap.xml,assets/llms.txt.
Changed:
- Phase 1 and Phase 3 now pull constraints from the references instead of asserting standards without teaching them.
- Version and date surfaced in the frontmatter and the body.
1.0.0, 6 August 2026
First release, from the Agentic Design enrichment session.
- Seven-phase session flow with gates, written for a brain agent rather than a reader.
references/design-direction.md,references/build-brief.md,references/verify-and-ship.md.assets/brand-harness.html.