page-foundry 2.9.1 → 3.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +82 -25
- package/package.json +1 -1
- package/skills/page-foundry/README.md +3 -3
- package/skills/page-foundry/SKILL.md +227 -59
- package/skills/page-foundry/TESTS.md +57 -2
- package/skills/page-foundry/assets/brief-template.md +15 -1
- package/skills/page-foundry/references/archetypes.md +552 -105
- package/skills/page-foundry/references/conversion-rules.md +2 -2
- package/skills/page-foundry/references/design-direction.md +50 -5
- package/skills/page-foundry/references/handoff.md +208 -34
- package/skills/page-foundry/references/ship-gates.md +115 -27
- package/skills/page-foundry/references/voice.md +6 -1
- package/skills/page-foundry/scripts/run_audit.py +1162 -0
- package/skills/page-foundry/scripts/voice_scan.py +46 -0
- package/skills/page-foundry/tests/build_fixture.sh +214 -0
- package/skills/page-foundry/tests/run_audit_test.sh +92 -0
package/README.md
CHANGED
|
@@ -2,14 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
# page-foundry
|
|
4
4
|
|
|
5
|
-
###
|
|
5
|
+
### One brief in. A page that argues its case out.
|
|
6
6
|
|
|
7
7
|
[](https://www.npmjs.com/package/page-foundry)
|
|
8
|
-
[](https://github.com/taylorbanks/page-foundry/releases)
|
|
8
|
+
[](https://github.com/taylorbanks/page-foundry/releases)
|
|
9
9
|
[](LICENSE)
|
|
10
10
|
[](package.json)
|
|
11
11
|
[](https://github.com/taylorbanks/page-foundry)
|
|
12
|
-
[](skills/page-foundry/references/ship-gates.md)
|
|
13
12
|
|
|
14
13
|
```bash
|
|
15
14
|
npx page-foundry install
|
|
@@ -23,34 +22,80 @@ npx page-foundry install
|
|
|
23
22
|
|
|
24
23
|
---
|
|
25
24
|
|
|
26
|
-
page-foundry is a Claude Code skill.
|
|
25
|
+
page-foundry is a Claude Code skill. It turns one brief into a finished homepage, landing page, or sales page: written in your voice, fast, accessible, honest about its proof, and built so it never reads or looks AI-made. Keep the static HTML, or take the design package to any tool you like.
|
|
27
26
|
|
|
28
|
-
##
|
|
27
|
+
## You already know what an AI-built page looks like
|
|
29
28
|
|
|
30
|
-
You
|
|
29
|
+
You can spot one in about two seconds. So can everyone else, which is the problem. There is a whole shared vocabulary for it now: the gradient, the same three feature cards, the typeface everybody uses.
|
|
31
30
|
|
|
32
|
-
|
|
31
|
+
Here is what is strange about that vocabulary. Go read any of the catalogues of AI page tells. Every item on them is a font, a color, or a layout. Not one is about **what the page says**.
|
|
32
|
+
|
|
33
|
+
So the pages get fixed, and they still do not work. The look improves and the signups do not, and now the failure is invisible, because the thing everyone knows how to name has been handled.
|
|
34
|
+
|
|
35
|
+
## The part nobody names
|
|
36
|
+
|
|
37
|
+
Ask a founder with a page and no signups what is wrong and you get some version of "I don't know what's turning people off." Ask their peers to look, and the answers are never about design. They ask where the pricing went. They say they cannot work out what it actually does, or who it is for, since "everyone" is not an audience. They want to know what makes it different from the dozen others they could pick instead, and where the proof is that any of it works.
|
|
38
|
+
|
|
39
|
+
Those are the same failure the visitor describes from the other side, in the words they use when they leave: *I can't tell what this does.*
|
|
40
|
+
|
|
41
|
+
The reason it is hard to catch in your own page is ordinary and well understood. The page makes sense to you because you already know what the thing is. You cannot un-know it to read your own copy cold. That is a property of expertise rather than a personal failing, and it is why the fix has to come from outside your own head.
|
|
42
|
+
|
|
43
|
+
An agent will not supply it either. Asked for a landing page, it has to decide who the page is for, what it competes with, which objection to answer first, and which proof leads. Nothing told it any of that, so it fills the gap with the average of every page it was trained on. That average is where the sameness comes from, and it is why two runs of the same prompt drift: the average moves when the wording does. One missing input, both symptoms.
|
|
44
|
+
|
|
45
|
+
## What page-foundry does before anything gets designed
|
|
46
|
+
|
|
47
|
+
It writes the spec first. Five questions, five files.
|
|
48
|
+
|
|
49
|
+
| The question | What answers it | What lands on disk |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| Who buys this, and what do they use instead? | `product-marketing`, plus one round of interview for what it cannot infer | `product-marketing.md` |
|
|
52
|
+
| How do buyers describe the problem in their own words? | `customer-research`, reading real threads, reviews, and forums | `voc.md`, every quote carrying a link and a date |
|
|
53
|
+
| Which levers actually move this buyer? | `marketing-psychology` | `persuasion-map.md` |
|
|
54
|
+
| What does the page have to prove, in what order, and why would a qualified buyer still say no? | the message hierarchy and objection map | `message-architecture.md` |
|
|
55
|
+
| What shape converts this, for the traffic it will really get? | `cro` | `page-spec.md` |
|
|
56
|
+
|
|
57
|
+
Then the design direction, the copy, the build. The design phase runs on real craft references and a deterministic detector ([impeccable](https://github.com/pbakaus/impeccable)) that persists a design system for the property and then rejects anything off it, which is what keeps the look from drifting back to the gradient-and-three-cards default. Each stage opens the file the stage before it wrote, so the headline traces back to a claim, the claim traces back to a quote, and the quote traces back to a link you can open.
|
|
58
|
+
|
|
59
|
+
That chain is the product. When it holds, the page argues a case instead of describing a product, and the argument is made of things a real buyer actually said.
|
|
60
|
+
|
|
61
|
+
## "So it is a prompt that says do the positioning first"
|
|
62
|
+
|
|
63
|
+
Fair question, and it is the right one to ask, because that describes most of this category. The difference is what happens to work that does not hold up.
|
|
64
|
+
|
|
65
|
+
Things that stop a page here:
|
|
66
|
+
|
|
67
|
+
- Copy that trips the voice scanner, which reads its rules from a file you edit, so page forty sounds like page one
|
|
68
|
+
- A page whose rendered text has drifted from the approved copy, checked by diff rather than by trust
|
|
69
|
+
- A testimonial, a metric, a command, or a screenshot of something that did not happen
|
|
70
|
+
- A claim left standing with no proof beside it, which becomes a marked gap instead of a nice sentence
|
|
71
|
+
- A design that trips the visual anti-pattern detector, run over the built page against the property's own design system
|
|
72
|
+
- Contrast, keyboard access, or markup that fails WCAG 2.2 AA
|
|
73
|
+
- A hero that needs 400KB to say hello
|
|
74
|
+
|
|
75
|
+
There is a conversion audit too, and it works in a way worth describing: the score of record does not come from the agent that built the page. It comes from a fresh one handed exactly two things, the page as a visitor meets it and the brief. Never the spec, never the reasoning. A page that only makes sense to its author scores badly, which is the entire point, because that is the failure this whole document is about.
|
|
76
|
+
|
|
77
|
+
It is slower. It will refuse to hand you the page a one-shot prompt would have given you five minutes ago. If your proof is thin it says so and builds around what is real, rather than inventing the testimonial that would have looked better.
|
|
33
78
|
|
|
34
79
|
## What you get
|
|
35
80
|
|
|
36
81
|
| | |
|
|
37
82
|
|---|---|
|
|
38
|
-
| **
|
|
39
|
-
| **One voice across everything** | Your writing rules live in a file a scanner enforces, so page
|
|
40
|
-
| **
|
|
41
|
-
| **
|
|
42
|
-
| **Accessible and fast** | Contrast, keyboard access, semantic markup, a weight budget, and a load target are gates
|
|
43
|
-
| **
|
|
83
|
+
| **A page that makes an argument** | Structure and copy follow the objections your buyer actually raises, in the order they raise them, with proof placed beside the claim it supports. |
|
|
84
|
+
| **One voice across everything** | Your writing rules live in a file a scanner enforces, so the fortieth page sounds like the first. |
|
|
85
|
+
| **Nothing invented** | No fabricated testimonial, number, command, or staged screenshot of something that never happened. Thin proof gets named and worked around. |
|
|
86
|
+
| **Does not read or look AI-made** | The scan rejects the vocabulary and the sentence patterns that mark machine-written copy, including the ones a word list cannot catch. A deterministic design detector rejects the visual defaults that give an AI page away, against a design system saved for the property so page forty looks like page one too. |
|
|
87
|
+
| **Accessible and fast** | Contrast, keyboard access, semantic markup, a weight budget, and a load target are gates rather than good intentions. |
|
|
88
|
+
| **Yours** | Static HTML you host anywhere, or a copy-and-design package for the tool of your choice. You are not tied to a platform and you do not need an account with anyone. |
|
|
44
89
|
|
|
45
90
|
## Whatever page you need
|
|
46
91
|
|
|
47
|
-
|
|
92
|
+
Sixteen archetypes, each a conversion contract rather than a fixed template: open source project, SaaS homepage, campaign landing, pricing, comparison, docs, waitlist, event, agency, e-commerce, mobile app, course sales, membership, newsletter, personal site, and a launch changelog. Section order follows how your buyer raises objections instead of a numbered slot, and a page that straddles two archetypes gets a merged contract.
|
|
48
93
|
|
|
49
94
|
Three ways to run it:
|
|
50
95
|
|
|
51
96
|
- **`build`**: one brief in, a finished page out.
|
|
52
|
-
- **`explore`**: contrasting design directions first
|
|
53
|
-
- **`handoff`**: a complete copy-and-design package for Claude Design, Open Design, Codex, Gemini, or
|
|
97
|
+
- **`explore`**: contrasting design directions first, you pick, then it builds the winner.
|
|
98
|
+
- **`handoff`**: a complete copy-and-design package for Claude Design, Open Design, Codex, Gemini, or whatever you build with.
|
|
54
99
|
|
|
55
100
|
## Install
|
|
56
101
|
|
|
@@ -82,18 +127,32 @@ The installer, `bin/page-foundry.js`, is one dependency-free Node file with no n
|
|
|
82
127
|
|
|
83
128
|
## First run
|
|
84
129
|
|
|
85
|
-
Run `/page-foundry` with no arguments
|
|
130
|
+
Run `/page-foundry` with no arguments and it prints what it can do, then stops and asks. Nothing starts until you say so.
|
|
131
|
+
|
|
132
|
+
When you are ready, say "set up my voice". A short wizard writes your voice rules, and those same rules drive the scanner, so your writing guidance and the enforcement cannot drift apart. Until then a neutral default applies.
|
|
86
133
|
|
|
87
|
-
##
|
|
134
|
+
## Read it before you trust it
|
|
88
135
|
|
|
89
|
-
page-foundry is
|
|
136
|
+
page-foundry is new, and few people have installed it. There is no download count here worth quoting, and inventing social proof for a tool whose main promise is refusing to invent proof would be a poor start.
|
|
137
|
+
|
|
138
|
+
What is offered instead is that you can check it yourself in about a minute:
|
|
139
|
+
|
|
140
|
+
- It ships two executables, `scripts/voice_scan.py` (the voice gate) and `scripts/run_audit.py` (the orchestration gate), both standard-library Python with no network access, no subprocess calls, and no dependencies. They are short. Read them.
|
|
141
|
+
- The npm installer is the same story: zero dependencies, Node built-ins, no network, no telemetry.
|
|
142
|
+
- Every skill it leans on is named and linked below, so the capability claim is checkable against projects that do have adoption.
|
|
143
|
+
- A run leaves its work as files on disk. The brief, the buyer quotes with their sources, the message hierarchy, the spec. You can read what it decided and why, after the fact, rather than taking the process on faith.
|
|
144
|
+
|
|
145
|
+
Companion skills install only from the pinned sources in the skill's own table, only when you approve, never from search results. See [SECURITY.md](SECURITY.md) for reporting.
|
|
146
|
+
|
|
147
|
+
One more piece of honesty about fit: the research behind this positioning clears its evidence bar for one buyer, the solo builder shipping their own product. The archetypes cover more ground than that, and if you are an agency or a maintainer, parts of this are still inference.
|
|
90
148
|
|
|
91
149
|
## Built on
|
|
92
150
|
|
|
93
|
-
These projects do the heavy lifting. page-foundry does the sequencing and the checking, and it is a lesser tool without any of them.
|
|
151
|
+
These projects do the heavy lifting. page-foundry does the sequencing and the checking, and it is a lesser tool without any of them. Eight are **core**, meaning the run does not start without them, because they are what makes the output a page-foundry page rather than a design-tool guess: `product-marketing`, `customer-research`, `marketing-psychology`, `cro`, `copywriting`, `frontend-design`, `humanizer`, and `impeccable`. The rest are enhancers that degrade to a condensed fallback when absent.
|
|
94
152
|
|
|
95
|
-
- [marketingskills](https://github.com/coreyhaines31/marketingskills) by [Corey Haines](https://www.corey.co): product-marketing, copywriting, CRO, customer-research, pricing, and psychology.
|
|
96
|
-
- [
|
|
153
|
+
- [marketingskills](https://github.com/coreyhaines31/marketingskills) by [Corey Haines](https://www.corey.co): product-marketing, copywriting, CRO, customer-research, pricing, and psychology. It supplies the marketing half of the pipeline (six of the eight core skills).
|
|
154
|
+
- [impeccable](https://github.com/pbakaus/impeccable) by [Paul Bakaus](https://github.com/pbakaus): the design engine. Craft references, a persistent per-property design system, and the deterministic detector behind the render gate. Core: a page whose look was never run through its detector is not a page-foundry page. Its "a clean scan is a floor, never a verdict" principle governs every mechanical check in the skill.
|
|
155
|
+
- [Anthropic's skills](https://github.com/anthropics/skills): frontend-design, web-artifacts-builder, and skill-creator.
|
|
97
156
|
- [web-design-guidelines](https://github.com/vercel-labs/agent-skills) by Vercel Labs: accessibility, typography, and UX rules.
|
|
98
157
|
- [humanizer](https://github.com/blader/humanizer) by blader: the "Signs of AI writing" pattern set behind the copy pattern pass.
|
|
99
158
|
- [gstack](https://github.com/garrytan/gstack) by Garry Tan: design consultation, the variant shotgun, and visual review.
|
|
@@ -101,9 +160,7 @@ These projects do the heavy lifting. page-foundry does the sequencing and the ch
|
|
|
101
160
|
- The [MECLABS Institute](https://meclabs.com) Conversion Sequence heuristic.
|
|
102
161
|
- The [skills CLI and skills.sh](https://skills.sh) by Vercel.
|
|
103
162
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
Skills run with your agent's permissions. page-foundry ships one program: `scripts/voice_scan.py`, standard-library Python, no network, no subprocess, no dependencies. The npm installer, `bin/page-foundry.js`, is the same story: zero dependencies, Node built-ins, no network. Read both before you install. The skill installs companions only from the pinned sources in its table, only with your approval, never from search results. See [SECURITY.md](SECURITY.md) for reporting. page-foundry is built by a security practitioner who assumes you will not take any of that on faith.
|
|
163
|
+
The eight core skills are required: the run stops at preflight until they are installed (you can override that in chat, but the run is then marked partial and says so). The enhancers are optional; when one is missing the skill falls back to a condensed built-in version of its rules and tells you the run was partial, rather than pretending. Install all of them anyway; the fallbacks are a floor, and the companions are the standard.
|
|
107
164
|
|
|
108
165
|
## License
|
|
109
166
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "page-foundry",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "3.2.0",
|
|
4
4
|
"description": "A gated pipeline for product homepages, landing pages, and sales pages. An orchestrator Claude Code skill. Install it with: npx page-foundry install",
|
|
5
5
|
"bin": {
|
|
6
6
|
"page-foundry": "bin/page-foundry.js"
|
|
@@ -2,12 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
**One brief in, a finished page out.** page-foundry produces homepages, landing pages, and sales pages that convert, hold one voice across every product you ship, stay accessible and fast, and never fabricate proof. It runs the best marketing and design skills available behind one command, then checks the output so an AI page never ships looking like one.
|
|
4
4
|
|
|
5
|
-
**Install:** unzip the `.skill` into `~/.claude/skills/page-foundry/` (Claude Code) or upload the `.skill` file (claude.ai). Run `/page-foundry` with no arguments for orientation: three modes (build, explore, handoff),
|
|
5
|
+
**Install:** unzip the `.skill` into `~/.claude/skills/page-foundry/` (Claude Code) or upload the `.skill` file (claude.ai). Run `/page-foundry` with no arguments for orientation: three modes (build, explore, handoff), the full archetype set, and example invocations.
|
|
6
6
|
|
|
7
7
|
**First run:** set the voice. Say "set up my voice" and the wizard writes `references/voice.md`, which also drives the scanner (`scripts/voice_scan.py`), so your writing guidance and the enforcement stay in sync. Until then a neutral default applies.
|
|
8
8
|
|
|
9
|
-
**What it makes:** open source project
|
|
9
|
+
**What it makes:** sixteen page archetypes, from open source project and SaaS homepage to pricing, comparison, event, and e-commerce pages, each compiled as a conversion contract. Build mode ships static HTML you own; explore mode gives you design directions to pick from; handoff mode packages copy and design for a design tool.
|
|
10
10
|
|
|
11
|
-
**Companions (
|
|
11
|
+
**Companions (two tiers):** seven are core and required: product-marketing, customer-research, marketing-psychology, cro, copywriting (coreyhaines31/marketingskills), frontend-design (Anthropic), and humanizer. Preflight stops until they are installed; only an explicit per-run override proceeds without one, and that output is loudly marked partial. Enhancers (more marketingskills companions, Anthropic's web-artifacts-builder, garrytan/gstack for design variants and visual review) improve results and degrade to built-in condensed rules when missing.
|
|
12
12
|
|
|
13
13
|
Methodology credits: conversion structure informed by published landing-page research and the MECLABS Conversion Sequence heuristic, with Corey Haines' marketing skills doing the marketing work. License: MIT.
|