diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..37227fa --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,36 @@ +{ + "name": "pagekit", + "owner": { + "name": "Hiten Shah" + }, + "metadata": { + "description": "PageKit: skills for making web pages that are contextually relevant to your audience and what your product does.", + "version": "0.3.0" + }, + "plugins": [ + { + "name": "pagekit", + "source": { + "source": "github", + "repo": "hnshah/pagekit" + }, + "description": "Skills, subagents, and scripts for the PageKit method: signal doc, message spine, first-page decision, page argument shape, proof map, first-page draft, claim check.", + "version": "0.3.0", + "author": { + "name": "Hiten Shah" + }, + "homepage": "https://github.com/hnshah/pagekit", + "repository": "https://github.com/hnshah/pagekit", + "license": "MIT", + "keywords": [ + "pagekit", + "content-strategy", + "copywriting", + "landing-pages", + "claim-check", + "anti-slop" + ], + "category": "productivity" + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..e7b2176 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "pagekit", + "description": "Skills for making web pages that are contextually relevant to your audience and what your product does. Ships the 7-step method (signal doc, message spine, first-page decision, page argument shape, proof map, first-page draft, claim check) plus tooling skills and subagents.", + "version": "0.3.0", + "author": { + "name": "Hiten Shah" + }, + "homepage": "https://github.com/hnshah/pagekit", + "repository": "https://github.com/hnshah/pagekit", + "license": "MIT", + "keywords": [ + "pagekit", + "content-strategy", + "copywriting", + "landing-pages", + "claim-check", + "anti-slop" + ] +} diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 3572325..f6e19ef 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -16,7 +16,7 @@ Delete the comments before submitting. - [ ] `bash scripts/doctor.sh` → PASS - [ ] `bash scripts/slop-check.sh` → exit 0 clean - [ ] (if the PR touches run structure) `bash scripts/run-check.sh runs/` → FULLY LOGGED (or tier you target) -- [ ] (if the PR touches prompts/frameworks) reviewed against `AGENTS.md` and `CLAUDE.md` for consistency +- [ ] (if the PR touches skills or their bundled references) reviewed against `AGENTS.md` and `CLAUDE.md` for consistency ## Notes for the reviewer diff --git a/AGENTS.md b/AGENTS.md index b951753..23a17d0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,94 +1,55 @@ # AGENTS.md -Neutral agent contract for PageKit. Readable by Codex (primary `AGENTS.md` consumer), Claude Code (which also reads `CLAUDE.md`), Claude Cowork, and any agent reading the repo cold. +Neutral agent contract for PageKit. Readable by Codex, Claude Code, and any agent reading the repo cold. ## What PageKit is -A system for producing better pages by strengthening the source materials that shape the copy. Markdown-first. Method-over-prompts. +A Claude Code plugin plus a chat-paste path for producing web pages that are contextually relevant to your audience and what your product does. The method runs upstream of copy: signal → spine → first-page decision → argument shape → proof map → first-page draft → claim check. -## Where to start - -Read these files in this order: +## If you are Claude Code -1. **`pagekit.yaml`** — canonical method manifest. The source of truth for every step, artifact, framework, template, guided-run and prompt. If you need to know what step N does and where its output goes, this file tells you. -2. **`CLAUDE.md`** — fuller operational contract, including the quality rules, the anti-slop rules, and the "Running PageKit end-to-end as an agent" section. -3. **`README.md`** — human-facing overview. +The plugin is self-contained in this repo. Skills live under [`skills/`](skills/), subagents under [`agents/`](agents/), and the plugin manifests under [`.claude-plugin/`](.claude-plugin/). Invoke the orchestrator with `Run PageKit on ` and it dispatches the 7-step chain. -## Method in one glance +Key entry points: +- `skills/pagekit/SKILL.md`: orchestrator +- `skills/pagekit-/SKILL.md`: per-step skills (signal-doc through claim-check) +- `agents/pagekit-claim-checker.md`: adversarial claim-check subagent +- `agents/pagekit-evaluator-pass.md`: adversarial evaluator-pass subagent -``` -signal-doc → message-spine → first-page-decision → page-argument-shape → proof-map → first-page-draft [ → claim-check ] -``` +## If you are Codex or another chat-based agent -Canonical prompts: `prompts/01-signal-doc.md` through `prompts/07-claim-check.md`. +Use the prompt-paste path. Open [`prompt-paste/`](prompt-paste/) and walk the 7 prompts in order. Each step consumes the previous step's output. -## Running a fully-logged run +## Running a fully-logged run from the shell ```sh -scripts/new-run.sh # scaffold the folder -# … work through the steps, filling prompts/NN-*.md and outputs/NN-*.md -scripts/run-check.sh runs/ # validate the run meets the fully-logged tier -``` +# scaffold the folder +bash scripts/new-run.sh -Or via make: +# …work through prompts/NN-*.md and outputs/NN-*.md -```sh -make new-run NAME= -make run-check RUN= -``` - -## Anti-slop - -Drafts must respect `frameworks/anti-slop.md`. The regression check is `scripts/slop-check.sh`. Run it on the draft before the claim-check step; run it again after. - -## Claim-check - -```sh -scripts/claim-check.sh runs//first-page-draft.md runs//proof-map.md --severity hard -``` +# validate against the logging tiers +bash scripts/run-check.sh runs/ -Outputs a ready-to-paste prompt. Paste into the model, then save the result as `runs//claim-check.md` and the corrected draft as `runs//first-page-draft-corrected.md`. +# claim-check the draft at the severity you intend +bash scripts/claim-check.sh runs//first-page-draft.md runs//proof-map.md --severity hard -## Pre-flight +# heuristic anti-slop regression against the draft +bash scripts/slop-check.sh runs//first-page-draft.md -```sh -scripts/doctor.sh -# or -make doctor +# pre-flight check for the repo +bash scripts/doctor.sh ``` -## If you are Claude Code - -See `.claude/skills/pagekit/SKILL.md` for the orchestrator skill. Per-step skills live under `.claude/skills/pagekit-/`. The custom subagent for claim-check is `.claude/agents/pagekit-claim-checker.md`. The SessionStart hook in `.claude/settings.json` runs `scripts/doctor.sh` on session start. - -Agentic path: `agentic/claude-code-agentic-path.md`. - -## If you are Codex - -This file is your contract. Read `pagekit.yaml` for the method. Scripts in `scripts/` are the tooling you will drive. Custom prompts / skills for Codex live alongside your own installation (see Codex docs); the canonical prompts in `prompts/` are what they should wrap. - -Agentic path: `agentic/codex-agentic-path.md`. - -## If you are Claude Cowork - -The skill bundle at `.claude/skills/` is the plugin body. See `agentic/claude-cowork-agentic-path.md` for local installation and eventual published-plugin notes. - ## Hard rules -Non-negotiable across tools and agents: - -- **Do not hard-code homepage-first.** Step 03 is where the first page is chosen. The object decides. +- **Do not hard-code homepage-first.** Step 03 picks the first page from the object. Name rejected candidates. - **Do not invent proof.** Mark unverified product-specific claims with `*[verification flag: ...]*` inline. -- **Do not ship a draft with AI-slop patterns.** See `frameworks/anti-slop.md`. Run `scripts/slop-check.sh` and resolve every hit. -- **Do not skip run logging.** Fully-logged runs are defined in `frameworks/run-logging.md`. If you are producing a run that claims to be fully-logged, it must meet that tier. `scripts/run-check.sh` tells you if it does. -- **Edit the canonical prompts in `prompts/`, never duplicate.** Guides reference them. +- **Do not ship a draft with AI-slop patterns.** See `skills/pagekit/references/anti-slop.md`. Run `scripts/slop-check.sh` and resolve every hit. +- **Do not skip run logging.** Fully-logged runs are defined in `skills/pagekit/references/run-logging.md`. `scripts/run-check.sh` tells you if your run meets the tier. ## Getting unstuck - Output of a step feels generic → fix upstream source material, not the step output. - First-page decision reluctant → add a mechanism / proof / comparison brief in `sources/` and rerun. -- Claim-check flagging the same pattern every run → update `frameworks/anti-slop.md` and the argument-shape drafting constraints so the pattern does not return. - -## What this file is not - -A full user manual. The full method lives in `frameworks/` and `guided-runs/`. The tool-specific paths live in `guides/`, `quickstart/` and `agentic/`. This file is the doormat that tells you where to look. +- Claim-check flagging the same pattern every run → update `skills/pagekit/references/anti-slop.md` and the argument-shape drafting constraints so the pattern does not return. diff --git a/CHANGELOG.md b/CHANGELOG.md index 225df27..0d497db 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,40 @@ Format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [Unreleased] +## [0.3.0] — 2026-04-17 + +Skills-first restructure. PageKit now ships as a Claude Code plugin: one install, twelve skills, two subagents, a chat-paste path for non-Claude-Code chat windows. Breaking for the repo layout; non-breaking for the method itself. + +### Added +- `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` — plugin manifests. Install via `/plugin marketplace add hnshah/pagekit` + `/plugin install pagekit@pagekit`. +- `skills/` top-level directory with 12 skills (orchestrator, 7 method steps, 4 tooling skills). Each skill has its own bundled `references/` folder with framework, template, and prompt. +- `skills/pagekit/references/` owns the shared references (`anti-slop.md`, `run-logging.md`, `method.md`). Sibling skills link by relative path. +- `agents/` — subagents live at repo root instead of under `.claude/agents/`. +- `examples/` — worked runs moved here from `runs/` (both `vegan-dog-food-verdel` and `personal-crm-founders`). `runs/` stays as user scratch. +- `prompt-paste/` — seven prompts stripped of YAML frontmatter for pasting into ChatGPT / Perplexity / Grok / Gemini / other chat windows. + +### Changed +- `README.md` rewritten skills-first: install, skills list, worked example. One page, no tree of entry choices. +- `AGENTS.md` and `CLAUDE.md` slimmed to neutral agent contracts (~45 lines each). Point at skills and the plugin install. +- `CONTRIBUTING.md` rewritten against the new layout. +- `scripts/new-run.sh` resolves canonical prompts from `skills/pagekit-/references/prompt.md`. +- `scripts/claim-check.sh` reads from `skills/pagekit-claim-check/references/prompt.md`. +- `scripts/slop-check.sh` scans `runs/` and `examples/` by default. +- `scripts/doctor.sh` validates the plugin layout: plugin manifest, top-level `skills/` and `agents/`, bundled references. +- `scripts/run-check.sh` — fix an unbound-variable warning at PUBLISHABLE tier (cosmetic; tier output was always correct). + +### Removed +- `START-HERE.md`, `quickstart/`, `guides/`, `guided-runs/`, `agentic/` — replaced by the rewritten README and the `prompt-paste/` path. +- `frameworks/`, `templates/`, `prompts/` — absorbed into each skill's `references/` folder. +- `pagekit.yaml` — distilled into `skills/pagekit/references/method.md`. +- `.claude/skills/` and `.claude/agents/` — migrated to the top-level `skills/` and `agents/`. +- `templates/output-judgment-template.md` — orphan, not referenced by any step. + +### Method integrity +The anti-slop framework, run-logging tiers, claim-check severities, and all seven method steps are unchanged from v0.2. Only the filesystem layout and the install surface changed. `scripts/slop-check.sh` and `scripts/run-check.sh` on both example runs still pass at their prior tiers. + +## [0.2.0] — 2026-04-15 + ### Added - `.github/workflows/check.yml` runs `doctor.sh` and `slop-check.sh` on every push and PR. - `.github/PULL_REQUEST_TEMPLATE.md` + issue templates (`method-feedback`, `bug`, `method-proposal`). @@ -46,5 +80,7 @@ Baseline public release. The agentic foundation is in place. ### Notes - PRs #1–#8 all merged prior to this release. See the GitHub PR history for the run-to-repo-improvement loop that produced the method surface. -[Unreleased]: https://github.com/hnshah/pagekit/compare/v0.1.0...HEAD +[Unreleased]: https://github.com/hnshah/pagekit/compare/v0.3.0...HEAD +[0.3.0]: https://github.com/hnshah/pagekit/compare/v0.2.0...v0.3.0 +[0.2.0]: https://github.com/hnshah/pagekit/compare/v0.1.0...v0.2.0 [0.1.0]: https://github.com/hnshah/pagekit/releases/tag/v0.1.0 diff --git a/CLAUDE.md b/CLAUDE.md index 6580c1d..66ba675 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,99 +1,67 @@ # CLAUDE.md -This file is the agent-facing repo contract for PageKit. - -## What this repo is for -PageKit is a system for getting to better pages by improving the source materials that shape the copy. - -The repo should help produce: -- signal docs -- message spines -- first-page decisions -- page argument shapes -- proof maps -- page drafts -- logged runs and evaluations - -## Canonical method -The stable process is: -1. signal doc -2. message spine -3. first-page decision -4. page argument shape -5. proof map -6. first page draft - -Optional durability pass: 7. claim check. - -The canonical manifest is `pagekit.yaml`. Canonical prompts are `prompts/01-signal-doc.md` through `prompts/07-claim-check.md`. **Edit the canonical prompts, never duplicate.** Guides, skills and scripts all read from those files. - -## Running PageKit end-to-end as an agent - -If you are an agent being asked to run PageKit on object X, do this exact sequence: - -1. **Read `pagekit.yaml`.** It lists every step, artifact, framework, template, guided-run, and canonical prompt path. This is the source of truth. -2. **Scaffold a run folder** with `scripts/new-run.sh ` (or `make new-run NAME=`). This creates `runs//` with all required files for the fully-logged tier. -3. **Fill `runs//goal.md` and `sources/`** with the object's ground truth. For fictional training objects, commit to concrete facts up front — no `[Product name]` placeholders in source briefs. -4. **Work through steps 01 through 06 in order.** For each step: - - Save the prompt used as `runs//prompts/NN-.md` (copy from `prompts/NN-*.md` and substitute inputs). - - Save the raw model output as `runs//outputs/NN--output.md`. - - Distill the output into the canonical artifact: `signal-doc.md`, `message-spine.md`, `first-page-decision.md`, `page-argument-shape.md`, `proof-map.md`, `first-page-draft.md`. - - Record what changed in `working-log.md`. - - Do not advance if the step's quality bar is not met. Go back upstream and fix source material. -5. **Run `scripts/slop-check.sh runs//first-page-draft.md`.** Resolve every flagged pattern before continuing. -6. **Run step 07 (claim check) at the severity you intend:** `scripts/claim-check.sh runs//first-page-draft.md runs//proof-map.md --severity hard`. Paste the expanded prompt, save `claim-check.md` and `first-page-draft-corrected.md`. -7. **Write `evaluation.md` and `evaluator-pass.md`** per `frameworks/run-logging.md`. The evaluator pass is adversarial; do not skip it at the fully-logged tier. -8. **Validate with `scripts/run-check.sh runs/`** (or `make run-check RUN=`). Fix anything it flags. - -If you are inside Claude Code, the `.claude/skills/pagekit/` skill orchestrates steps 2 through 8 for you. Invoke with `/pagekit` or describe the job ("run PageKit on X") and the skill will auto-load. - -## What must stay stable -- source material comes before copy -- weak drafts should trigger upstream repair first -- proof must not be invented -- uncertainty should stay visible when it is real -- runs should be logged when they matter +Agent-facing repo contract for PageKit. PageKit ships as a Claude Code plugin plus a chat-paste path. -## What must stay variable -- what page comes first -- what shape the page takes -- how trust lands -- how proof lands -- how the argument is ordered +## What this repo is -Do not hard-code homepage-first assumptions unless the object clearly earns that decision. -Do not hard-code a fixed homepage section pattern. +- `skills/`: 12 skills (orchestrator, 7 method steps, 4 tooling skills) +- `agents/`: 2 subagents (claim-checker, evaluator-pass) +- `.claude-plugin/`: plugin and marketplace manifests +- `scripts/`: new-run, run-check, claim-check, slop-check, doctor +- `examples/`: worked runs (vegan-dog-food-verdel, personal-crm-founders) +- `prompt-paste/`: 7 prompts for non-Claude-Code chat windows +- `runs/`: user scratch space + +## Running PageKit end-to-end + +Invoke the `pagekit` skill. The orchestrator walks steps 01–07, scaffolds `runs//` via `pagekit-new-run`, fills artifacts via each step skill, runs `pagekit-slop-check` on the draft, dispatches `pagekit-claim-checker` for the audit, writes `evaluation.md`, dispatches `pagekit-evaluator-pass`, and closes with `pagekit-run-check`. + +If you are running by hand: `bash scripts/new-run.sh ` → work through `prompts/NN-*.md` → `bash scripts/run-check.sh runs/`. All canonical prompts live at `skills/pagekit-/references/prompt.md`. + +## Hard rules + +- **Do not hard-code homepage-first.** Step 03 picks the first page from the object. Name rejected candidates. +- **Do not invent proof.** Mark unverified product-specific claims with `*[verification flag: ...]*` inline. +- **Do not ship a draft with AI-slop patterns.** See `skills/pagekit/references/anti-slop.md`. The full pattern list is there with examples. Run `pagekit-slop-check` (or `scripts/slop-check.sh`) and resolve every hit. +- **Do not skip run logging.** Fully-logged runs are defined in `skills/pagekit/references/run-logging.md`. A draft is not the deliverable; a logged run is. +- **Edit canonical references in place.** Framework, template, and prompt files live under each skill's `references/` folder and under `skills/pagekit/references/` for shared material. Do not duplicate. ## Quality rules -- avoid AI slop. Specifically: no "Not X. Not Y." pairs, no three parallel short sentences in a row, no sentence-start anaphora, no editorial voice narrating brand restraint, no em-dash stacking, no "actually / testament / landscape / showcasing / truly" as intensifiers, no copula-avoidance (`serves as`, `boasts`), no signposting (`let's dive in`), no significance inflation (`pivotal moment`). See `frameworks/anti-slop.md` for the full list and examples. + +- avoid AI slop. See `skills/pagekit/references/anti-slop.md` for the pattern list. - avoid generic category-default wording - avoid overclaiming - avoid polishing weak inputs into prettier weak outputs - when copy is weak, ask which source artifact is too weak or missing -- when copy carries AI-slop patterns, name the pattern from `frameworks/anti-slop.md` and rewrite +- when copy carries AI-slop patterns, name the pattern and rewrite + +## What must stay variable + +- what page comes first +- what shape the page takes +- how trust lands +- how proof lands +- how the argument is ordered + +The object decides. Category habit does not. ## Repo behavior guidelines + - improve user-facing clarity when possible -- keep quickstarts short and guides self-contained - keep examples honest and tied to real runs -- use logged runs as evidence, not decoration -- mechanize structural work via `scripts/` (new-run, run-check, claim-check, slop-check, doctor); do not hand-roll run folders -- treat `pagekit.yaml` as the canonical method manifest; if it disagrees with a doc, update the doc -- the SessionStart hook in `.claude/settings.json` runs `scripts/doctor.sh` to verify repo health on every session start -- skills under `.claude/skills/pagekit*` orchestrate the method end-to-end; the `pagekit-claim-checker` subagent under `.claude/agents/` runs the read-only claim-check pass - -## Good agent behavior in this repo -Good work in PageKit: -- strengthens templates when runs expose weak spots -- strengthens guided runs when users would otherwise get stuck +- mechanize structural work via `scripts/`; do not hand-roll run folders +- the SessionStart hook in `.claude/settings.json` runs `scripts/doctor.sh` on every session start +- skills under `skills/pagekit*` orchestrate the method end-to-end; the subagents under `agents/` run the read-only adversarial passes + +## Good vs bad agent behavior + +Good: +- strengthens skill references when runs expose weak spots - makes the process more object-driven, not more rigid - keeps the repo honest about what it can and cannot yet do -## Bad agent behavior in this repo -Bad work in PageKit: +Bad: - assuming every object wants the same homepage - filling proof gaps with smooth language -- treating the process as a prompt library only -- writing docs that sound polished but do not improve usability - shipping drafts with AI-slop patterns -- running the slop-check script (`scripts/slop-check.sh`) only after committing, or skipping it +- skipping `pagekit-slop-check` or running it only after committing diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c2f38b..01e0eec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,12 @@ # Contributing to PageKit -Thanks for looking at this. PageKit is a methodology repo plus the scaffolding that lets an agent drive the method end-to-end. Contributions fall into four shapes, each with a slightly different bar. +Thanks for looking at this. PageKit ships as a Claude Code plugin: twelve skills, two subagents, a chat-paste path, and the scripts that hold runs to a consistent shape. Contributions fall into four shapes, each with a slightly different bar. ## The method in one sentence -**Signal doc → message spine → first-page decision → page argument shape → proof map → first page draft → (optional) claim check.** +Signal doc -> message spine -> first-page decision -> page argument shape -> proof map -> first-page draft -> (optional) claim check. -Canonical source of truth: `pagekit.yaml` and `prompts/`. Edit canonical prompts in one place; guides reference them. +Canonical source of truth: `skills/pagekit/references/method.md` plus each step's bundled `skills/pagekit-/references/`. Edit the canonical files in place; do not duplicate. ## Four kinds of contribution @@ -15,8 +15,8 @@ Canonical source of truth: `pagekit.yaml` and `prompts/`. Edit canonical prompts The bar is high and the shape is prescribed: 1. Open an issue using the `method-proposal` template. Name the run or evaluator-pass that surfaced the gap. Proposals without run evidence land lower. -2. If we agree on the change, the PR should update the canonical surface plus every downstream surface that references it (framework, template, prompt, skill, guided-run, CLAUDE.md, AGENTS.md if relevant). Run `bash scripts/doctor.sh` to verify. -3. When the change is driven by a specific run's evaluator-pass, cite that run in the PR body. The method-change loop is: `run → evaluator-pass → punch list → method change`. +2. If we agree on the change, the PR should update the canonical surface plus every downstream surface that references it (framework, template, prompt, SKILL.md, CLAUDE.md, AGENTS.md if relevant). Run `bash scripts/doctor.sh` to verify. +3. When the change is driven by a specific run's evaluator-pass, cite that run in the PR body. The method-change loop is: run -> evaluator-pass -> punch list -> method change. ### 2. A logged run @@ -30,16 +30,18 @@ The most useful contribution for strengthening the method is a real run. ### 3. Tooling (scripts, CI, hooks, skills, subagents) -- Scripts live in `scripts/`. POSIX-leaning bash, exit 0 on success / non-zero on failure (so they work in hooks and CI). -- Skills live in `.claude/skills/pagekit-*/SKILL.md`. Each has YAML frontmatter (`name`, `description`, optional `tools`). The description is what determines auto-invocation — front-load the trigger phrase. -- Subagents live in `.claude/agents/`. Scope the `tools:` field tightly. +- Scripts live in `scripts/`. POSIX-leaning bash, exit 0 on success and non-zero on failure so they work in hooks and CI. +- Skills live in `skills/pagekit-*/SKILL.md`. Each has YAML frontmatter (`name`, `description`, optional `tools`). The description is what determines auto-invocation: front-load the trigger phrase. +- Bundled references live in `skills//references/`. Shared references (anti-slop, run-logging, method) live in `skills/pagekit/references/` and are linked from sibling skills via `../pagekit/references/`. +- Subagents live in `agents/`. Scope the `tools:` field tightly. +- Plugin and marketplace manifests live in `.claude-plugin/`. - Always update `scripts/doctor.sh` if you add a file the repo should guarantee exists. -### 4. Docs (README, guides, quickstarts, CLAUDE.md, AGENTS.md) +### 4. Docs (README, CLAUDE.md, AGENTS.md) -- Canonical prompts live in `prompts/`. Guides reference them; do not duplicate the prompt text into a guide. -- Anything in `README.md`, `START-HERE.md`, `CLAUDE.md`, or `AGENTS.md` that describes the method must agree with `pagekit.yaml` and with `frameworks/`. If you change one, grep for the others. -- Anti-slop rules apply to the docs too. See `frameworks/anti-slop.md`. `scripts/slop-check.sh` catches the mechanical tells. +- Canonical prompts live at `skills/pagekit-/references/prompt.md`. The chat-paste copies in `prompt-paste/` mirror those bodies with YAML stripped. +- Anything in `README.md`, `CLAUDE.md`, or `AGENTS.md` that describes the method must agree with `skills/pagekit/references/method.md` and the per-step frameworks. If you change one, grep for the others. +- Anti-slop rules apply to the docs too. See `skills/pagekit/references/anti-slop.md`. `scripts/slop-check.sh` catches the mechanical tells. ## Required checks before a PR @@ -59,16 +61,16 @@ If you want local enforcement before commit, `.pre-commit-config.yaml` is set up Use the PR template. Keep summaries short, verification concrete. Reviews look for: - does the PR follow the source-of-truth rule (edit canonical, let downstream pick it up)? - does CI pass? -- if it touches prompts/frameworks/skills, do they still agree with each other? +- if it touches prompts, frameworks, or skills, do they still agree with each other? - if it claims to fix something a run surfaced, is the run named? ## What bad contribution looks like -- A draft rewrite with no slop-check / claim-check audit trail -- A new guide that duplicates a prompt instead of referencing `prompts/` +- A draft rewrite with no slop-check or claim-check audit trail +- A new doc that duplicates a prompt instead of referencing the canonical at `skills/pagekit-/references/prompt.md` - A method change without a run behind it - A run that skips the evaluator pass and calls itself fully-logged -- A PR that adds 35 mentions of the same rule across 5 guides instead of editing one canonical file +- A PR that adds 35 mentions of the same rule across five docs instead of editing one canonical file ## Questions diff --git a/README.md b/README.md index 5cc515b..dd149c2 100644 --- a/README.md +++ b/README.md @@ -1,149 +1,87 @@ # PageKit -**Better page copy usually starts with better source materials.** +**Skills for making web pages that are contextually relevant to your audience and what your product does.** -PageKit is a method for producing web pages that do not sound AI-written. It works by strengthening the inputs (signal, spine, first-page decision, page-argument shape, proof map) before asking any model to draft the page. An anti-slop layer and an optional claim-check step keep the draft honest. +PageKit ships as a Claude Code plugin. One install, fourteen skills (twelve method skills + two subagents), and the full 7-step chain runs end-to-end: signal doc → message spine → first-page decision → page argument shape → proof map → first-page draft → claim check. An anti-slop regression script catches mechanical slop patterns; the claim-check subagent catches the rest. -The repo ships the method, the canonical prompts, a Claude Code skills bundle, a Codex `AGENTS.md` contract, a Claude Cowork plugin body, and scripts that mechanize the structural work. Everything an agent needs to run PageKit end-to-end is here. +If you do not use Claude Code, there is a chat-paste path in [`prompt-paste/`](prompt-paste/). -**See what a run looks like**: [`runs/vegan-dog-food-verdel/`](runs/vegan-dog-food-verdel/) is the canonical worked example. Fully-logged, non-homepage first page, claim-checked at hard severity, with evaluator pass. +## Install -## What PageKit helps you go from +Inside Claude Code: -- vague market understanding -- weak source material -- generic page direction -- AI-slop drafts - -## … to - -- a sharper signal doc -- a clearer message spine -- a deliberate first-page decision -- a page argument shape that fits the object -- a proof map with honest constraints -- a page draft grounded in better inputs that does not read as machine-written - -## Who this is for - -PageKit is for: -- founders -- marketers -- product marketers -- operators -- AI-native teams who want faster website work without generic output - -## Choose your starting path - -### I am new here -Start here: -- `START-HERE.md` - -### I just want prompts (lightest entry, one step) -Start here: -- `quickstart/README.md` -- `quickstart/start-with-prompts.md` - -### I want a full tool-specific path in one file (chat tools) -Start here: -- `guides/README.md` - -### I want to drive this agentically (Claude Code, Codex, Cowork) -Start here: -- `agentic/README.md` - -### I want the full method -Start here: -- `guided-runs/01-build-signal-doc/README.md` - -## The artifact chain - -The canonical PageKit workflow is: - -**signal doc -> message spine -> first-page decision -> page argument shape -> proof map -> first page draft** - -An optional durability pass follows: - -**claim check** - -That order matters. -The whole point is to get the upstream structure right before asking AI to write final pages. +```text +/plugin marketplace add hnshah/pagekit +/plugin install pagekit@pagekit +``` -## What makes this different +That is the whole installation. All fourteen skills register automatically. -- starts upstream, with signal -- improves the source materials before chasing better copy -- preserves audience differences -- lets the object decide the page shape -- does not default to homepage -- maps proof to specific argument moves -- keeps AI inside a real workflow -- keeps intermediate artifacts visible and reusable -- treats AI-slop patterns as hard no-go rules (`frameworks/anti-slop.md`) with a regression script (`scripts/slop-check.sh`) +## Use it -## Repo structure +Ask Claude Code to run PageKit on any object: ```text -AGENTS.md neutral agent contract (Codex, Claude Code, Cowork) -CLAUDE.md Claude Code agent contract; full operational manual -START-HERE.md first-time entry doc -README.md this file -pagekit.yaml canonical method manifest (single source of truth) -Makefile discoverable wrappers around scripts/ -quickstart/ low-friction prompt-first entry (one step) -guides/ fully self-contained tool-specific chat paths -agentic/ third tier: Claude Code, Codex, Cowork agentic paths -guided-runs/ step-by-step workflows -frameworks/ the durable method docs -templates/ copyable artifact templates -prompts/ canonical prompts (one per step; do not duplicate) -runs/ logged validation runs -scripts/ tooling (new-run, run-check, claim-check, slop-check, doctor) -.claude/ Claude Code skills + subagents + SessionStart hook (also the Cowork plugin body) +Run PageKit on . ``` -## Current scope +The orchestrator skill (`pagekit`) walks you through the seven steps, scaffolds a fully-logged `runs//` folder, and invokes each step skill in turn. -PageKit v0.1 is intentionally narrow. -It focuses on one core workflow: +To run one step on its own, invoke the step skill directly: -**signal -> spine -> first-page decision -> argument shape -> proof map -> first page draft** - -With an optional claim-check pass on top. +```text +Use pagekit-signal-doc on . +``` -That keeps the system honest and usable. +## The skills -## Logged runs +| Skill | What it does | +| --- | --- | +| `pagekit` | Orchestrator. Runs all 7 steps end-to-end into a fully-logged run. | +| `pagekit-signal-doc` | Step 01. Turn source briefs into a signal doc. | +| `pagekit-message-spine` | Step 02. Reduce the signal doc to a message spine. | +| `pagekit-first-page-decision` | Step 03. Decide which page comes first — without defaulting to homepage. | +| `pagekit-page-argument-shape` | Step 04. Shape the argument for the chosen page. | +| `pagekit-proof-map` | Step 05. Map proof to sections. Name what cannot be said. | +| `pagekit-first-page-draft` | Step 06. Draft the page inside the argument shape and proof map. | +| `pagekit-claim-check` | Step 07. Adversarial audit at light / normal / hard severity. | +| `pagekit-new-run` | Scaffold a fully-logged run folder. | +| `pagekit-run-check` | Validate a run against the logging tiers. | +| `pagekit-slop-check` | Heuristic anti-slop regression against drafts. | +| `pagekit-evaluator-pass` | Invoke the evaluator-pass subagent on a completed run. | -The repo includes validation runs so the process can be judged against real objects, not theory alone. +Two subagents (`pagekit-claim-checker`, `pagekit-evaluator-pass`) do the adversarial reads. The orchestrator dispatches to them automatically. -See `frameworks/run-logging.md` for the definition of "fully logged" vs "summary logged." +## A worked example -**Fully logged** -- `runs/vegan-dog-food-verdel/` — fully-logged run on a fictional plant-based dog food brand. Chose a non-homepage first page (a trust/safety landing page). First run produced on the agentic foundation; its evaluator-pass surfaced the punch list that became the anti-slop and step-03 tightening PRs. +[`examples/vegan-dog-food-verdel/`](examples/vegan-dog-food-verdel/) is the canonical run. Fully logged, non-homepage first page, claim-checked at `severity: hard`, evaluator pass included. Read `first-page-draft.md` against `proof-map.md` against `claim-check.md` to see how the chain constrains the draft. -Future runs should reach the fully-logged tier by default. `scripts/new-run.sh` scaffolds the layout; `scripts/run-check.sh` validates it. The `.claude/skills/pagekit/` orchestrator skill drives the entire chain end-to-end on Claude Code. +[`examples/personal-crm-founders/`](examples/personal-crm-founders/) is a second worked example on a different object shape. -## What comes later +## Without Claude Code -Later versions can add: -- more non-homepage real-object runs -- exhibit packaging -- agent/skill-powered paths -- deeper page-family generation +If you use ChatGPT, Perplexity, Grok, Gemini, or another chat window, open [`prompt-paste/`](prompt-paste/) and paste the 7 prompts in order. Your output quality depends on how honest your source briefs are; that constraint does not change. -The system should also keep getting better through fully logged runs that expose weak prompts, weak templates and weak process steps. +## What makes this different -But the core system needs to hold first. +- Starts upstream, with signal, not with copy. +- Does not default to homepage. Step 03 forces you to name rejected candidates. +- Maps proof to sections. A section that cannot be proven is flagged or removed. +- Treats AI-slop patterns as hard no-go rules. `pagekit-slop-check` runs the regression; `pagekit-claim-check` catches the rest. +- Logs the whole run. The draft is not the deliverable; the logged run is. -## Core principle +## Repo structure -**Better page copy usually starts with better source materials.** +- `.claude-plugin/`: plugin and marketplace manifests +- `skills/`: 12 SKILL.md files, each with a bundled `references/` folder +- `agents/`: 2 subagents (claim-checker, evaluator-pass) +- `examples/`: worked runs (vegan-dog-food-verdel, personal-crm-founders) +- `prompt-paste/`: chat-app path with 7 prompts ready to paste +- `runs/`: your own runs land here (empty by default) +- `scripts/`: tooling (new-run, run-check, claim-check, slop-check, doctor) ## License MIT -*** - -Built by [`Hiten`](https://x.com/hnshah) +Built by [`Hiten`](https://x.com/hnshah). diff --git a/START-HERE.md b/START-HERE.md deleted file mode 100644 index dc8b3c3..0000000 --- a/START-HERE.md +++ /dev/null @@ -1,81 +0,0 @@ -# Start Here - -If this is your first time using PageKit, begin here. - -## What PageKit is -PageKit is a practical system for getting to better pages by strengthening the source materials that shape the copy. - -It helps you move from: -- vague product understanding -- weak source material -- generic page direction - -to: -- a sharper signal doc -- a clearer message spine -- a deliberate first-page decision -- a page argument shape that fits the object -- a proof map with honest constraints -- a proof-aware page draft - -## What PageKit is not -PageKit is not: -- a one-prompt page generator -- a guarantee of final copy from thin inputs -- a fixed homepage template - -PageKit does not assume the first page is a homepage. -That is a decision the method forces you to make on purpose. - -The system is strongest when it helps you improve what the page is based on. - -## Choose your path - -### If you want the fastest start (one step, copy-paste) -Go to: -- `quickstart/README.md` - -### If you want a full tool-specific chat guide -Go to: -- `guides/README.md` - -### If you want to drive PageKit agentically (Claude Code, Codex, Cowork) -Go to: -- `agentic/README.md` - -### If you want the full method -Go to: -- `guided-runs/01-build-signal-doc/README.md` - -### If you want proof that the system is real -Go to: -- `runs/` — logged validation runs - -## The core method -The stable part of PageKit is the process: -1. build a signal doc -2. reduce it to a message spine -3. decide what page should exist first -4. design the page's argument shape -5. map proof and proof limits -6. draft the page from the full chain -7. optional: run a claim check for durability - -## The main rule -If the copy gets generic, do not just keep editing the copy. -Go upstream and improve the source materials. - -## What good use looks like -Good use of PageKit: -- keeps uncertainty visible -- improves the source material before polishing copy -- lets the object determine the page shape -- treats proof carefully - -## What weak use looks like -Weak use of PageKit: -- jumping to draft too early -- forcing every object into the same homepage pattern -- inventing proof -- mistaking a cleaner prompt for a stronger process -- shipping a draft full of AI-slop patterns ("Not X. Not Y." pairs, rule-of-three cadence, editorial voice, em-dash stacking, etc. — see `frameworks/anti-slop.md`) diff --git a/agentic/README.md b/agentic/README.md deleted file mode 100644 index 9394b14..0000000 --- a/agentic/README.md +++ /dev/null @@ -1,44 +0,0 @@ -# Agentic - -Third tier of entry points. Use this when the tool you are using is itself an agent that has file access, shell tools, and the ability to run the method end-to-end without you orchestrating each step. - -## How this differs from quickstart and guides - -| Tier | What it is | Who it is for | -|---|---|---| -| `quickstart/` | One prompt, one step, copy-paste-ready. Fastest way to get started. | Anyone wanting to try the method by running step 01. | -| `guides/` | The full seven-step chain inside a single chat tool (ChatGPT, Claude, Perplexity, Grok, OpenAI). You paste prompts and keep the thread. | People running the method by hand inside a chat model. | -| `agentic/` | The full chain driven by an agent that has file access, scripts, and tool use. You describe the job; the agent does the steps. | People using Claude Code, Codex, or Claude Cowork to run the method on the repo itself. | - -## When to use the agentic tier - -- You have a real object and want a fully-logged run created for you on disk. -- You want the agent to call `scripts/new-run.sh`, fill sources, run each step, save prompts and outputs, run the slop-check and claim-check scripts, and hand you a clean `runs//` at the end. -- You want the method to keep running correctly across future runs without you re-teaching the tool each time. - -If you are iterating conversationally inside a chat and do not want the tool touching files, use a `guides/` path instead. - -## Paths - -- **`claude-code-agentic-path.md`** — Claude Code (the Anthropic CLI). Uses the skills bundle at `.claude/skills/`, the subagent at `.claude/agents/`, and the SessionStart hook at `.claude/settings.json`. Most mechanized path; most recommended if you have Claude Code installed. -- **`codex-agentic-path.md`** — OpenAI Codex (the CLI). Reads `AGENTS.md` at the repo root. Drives the method through the scripts in `scripts/` and the canonical prompts in `prompts/`. -- **`claude-cowork-agentic-path.md`** — Claude Cowork (the Anthropic desktop product, GA early 2026). The skills bundle in `.claude/skills/` is the plugin body. Installable locally today; publishable to claude.com/plugins as a packaged plugin later. - -## Shared foundation - -All three paths read the same source of truth: -- `pagekit.yaml` — method manifest -- `prompts/` — canonical prompts -- `frameworks/` — durable method docs -- `scripts/` — tooling - -So the methodology stays identical across tools. What differs is how the tool drives the chain. - -## Hard rules for agentic use - -- The agent must produce a fully-logged run per `frameworks/run-logging.md`. Validate with `scripts/run-check.sh runs/` before declaring the run done. -- The agent must respect `frameworks/anti-slop.md`. Validate with `scripts/slop-check.sh` before the claim-check step and again after. -- Unverified product-specific claims must carry `*[verification flag: ...]*` inline. -- The first-page decision must be made on purpose at step 03. Homepage is not a default. - -These rules are named in `AGENTS.md` and `CLAUDE.md` so the agent picks them up at session start. diff --git a/agentic/claude-code-agentic-path.md b/agentic/claude-code-agentic-path.md deleted file mode 100644 index 54a103d..0000000 --- a/agentic/claude-code-agentic-path.md +++ /dev/null @@ -1,90 +0,0 @@ -# Claude Code Agentic Path - -The most mechanized way to run PageKit. The agent produces a fully-logged run on disk without you orchestrating each step. - -## What you need - -- [Claude Code](https://docs.claude.com/claude-code) installed. -- The PageKit repo cloned locally. - -## First run - -1. `cd` into the repo. -2. Start a Claude Code session. The `SessionStart` hook in `.claude/settings.json` will run `scripts/doctor.sh` and report repo health. -3. Give the agent an object to run on. Examples: - - "Run PageKit on a new plant-based dog food brand called Kind Bowl." - - "Use PageKit to produce a first-page draft for this B2B invoicing product: [paste product description]." -4. The agent will invoke the `/pagekit` skill (or you can invoke explicitly: `/pagekit`). The skill drives the full chain. - -## What the skill does - -`.claude/skills/pagekit/SKILL.md` orchestrates: - -1. Calls `scripts/new-run.sh ` to scaffold `runs//`. -2. Asks you for (or infers from your prompt) the source material — product brief, audience hypothesis, etc. Saves source briefs to `runs//sources/`. -3. Runs each step 01 through 07 by loading the corresponding per-step skill (`.claude/skills/pagekit-signal-doc/`, etc.). Each per-step skill loads its canonical prompt from `prompts/NN-*.md`, prompts the model, saves the raw output to `runs//outputs/`, distills the artifact into the run root. -4. Runs `scripts/slop-check.sh` against the first-page draft before running the claim-check step. Flags resolved before continuing. -5. Runs the claim-check step at the severity you specified. The `pagekit-claim-check` skill delegates to the `pagekit-claim-checker` subagent (`.claude/agents/pagekit-claim-checker.md`) which is read-only and hard-severity by default. -6. Writes `evaluation.md` and `evaluator-pass.md`. -7. Calls `scripts/run-check.sh runs/` to verify the fully-logged tier is met. Reports the result. - -## What you do during a run - -- Provide source material when asked. -- Approve or refine the first-page decision at step 03. The agent will list candidates and its choice; you can override. -- Review the claim-check output. If a flag is wrong, tell the agent and it will revise. -- Sign off on the run at the end. - -## When to intervene - -- If the first-page decision drifts to homepage by default, challenge it. -- If the draft reads machine-cadenced even after slop-check, paste the slop line back and ask for a rewrite. -- If the proof map feels thin, ask the agent to add a source brief (mechanism, proof, comparison) before drafting. - -## Per-step skill invocation - -You can invoke a single step without the full orchestrator: - -- `/pagekit-signal-doc` — builds just the signal doc -- `/pagekit-message-spine` -- `/pagekit-first-page-decision` -- `/pagekit-page-argument-shape` -- `/pagekit-proof-map` -- `/pagekit-first-page-draft` -- `/pagekit-claim-check` — runs against an existing draft, takes `--severity hard|normal|light` - -Tooling skills: - -- `/pagekit-new-run ` — scaffolds a run folder -- `/pagekit-run-check ` — validates a run's logging tier -- `/pagekit-slop-check [paths...]` — runs the regression check - -## Typical failure modes - -- **Agent scaffolds but does not fill source briefs.** Remind the agent that source briefs must be concrete before step 01. -- **Agent produces abstract signal doc.** Usually because the product brief is abstract. Sharpen the brief first, not the signal doc. -- **Agent lands on homepage without considering alternatives.** The `pagekit-first-page-decision` skill requires listing candidates considered and rejected. If that list is missing, ask explicitly. -- **Draft passes slop-check but still reads machine-cadenced.** The script is a heuristic. Claim-check at hard severity catches what the script does not. - -## Files this path uses - -``` -.claude/ -├── settings.json # SessionStart hook -├── skills/ -│ ├── pagekit/SKILL.md # orchestrator -│ ├── pagekit-signal-doc/SKILL.md -│ ├── pagekit-message-spine/SKILL.md -│ ├── pagekit-first-page-decision/SKILL.md -│ ├── pagekit-page-argument-shape/SKILL.md -│ ├── pagekit-proof-map/SKILL.md -│ ├── pagekit-first-page-draft/SKILL.md -│ ├── pagekit-claim-check/SKILL.md -│ ├── pagekit-new-run/SKILL.md -│ ├── pagekit-run-check/SKILL.md -│ └── pagekit-slop-check/SKILL.md -└── agents/ - └── pagekit-claim-checker.md # read-only subagent -``` - -All of these are committed to the repo. Cloning gives you the agentic bundle for free. diff --git a/agentic/claude-cowork-agentic-path.md b/agentic/claude-cowork-agentic-path.md deleted file mode 100644 index 3c1adaf..0000000 --- a/agentic/claude-cowork-agentic-path.md +++ /dev/null @@ -1,72 +0,0 @@ -# Claude Cowork Agentic Path - -Run PageKit inside Claude Cowork — the Anthropic desktop product (GA early 2026) that brings Claude Code's agentic capabilities to non-coders. Cowork plugins bundle skills, slash commands, connectors (MCP) and subagents. - -This repo's `.claude/skills/` directory is the PageKit plugin body. You can install it locally today; publishing it as a packaged plugin to claude.com/plugins is a small follow-up step on top. - -## What you need - -- Claude Cowork installed (Pro, Max, Team, or Enterprise tier). -- The PageKit repo cloned locally (until the published plugin lands). - -## Local install (today) - -1. Clone the PageKit repo. -2. Copy the `.claude/skills/pagekit*` folders and the `.claude/agents/pagekit-claim-checker.md` file into the Cowork skills location for your installation: - - macOS / Windows: typically `~/.claude/skills/` (user-level, available across all projects). Cowork picks them up automatically. -3. Open Cowork. The PageKit skills become invocable: `/pagekit`, `/pagekit-signal-doc`, `/pagekit-claim-check`, etc. - -The canonical prompts in `prompts/` are loaded by the skills using paths inside the PageKit repo. Cowork must be allowed to read the repo as a working folder for the skills to function. - -## Published-plugin install (follow-up) - -The PR that landed this agentic foundation includes the skill bodies but not yet a Cowork plugin manifest. Once a plugin manifest is added (file shape per the [`anthropics/knowledge-work-plugins`](https://github.com/anthropics/knowledge-work-plugins) reference repo), Cowork users will be able to install PageKit from claude.com/plugins without cloning the repo. - -That step is intentionally deferred so the skills can be exercised and tightened first. See the open items in the PR description. - -## What the plugin gives you in Cowork - -- The `/pagekit` orchestrator skill, which drives a full run end-to-end. -- Per-step skills for finer-grained invocation: `/pagekit-signal-doc`, `/pagekit-message-spine`, `/pagekit-first-page-decision`, `/pagekit-page-argument-shape`, `/pagekit-proof-map`, `/pagekit-first-page-draft`, `/pagekit-claim-check`. -- Tooling skills: `/pagekit-new-run `, `/pagekit-run-check `, `/pagekit-slop-check`. -- The `pagekit-claim-checker` subagent for read-only claim-check work. - -## How Cowork is different - -Compared to Claude Code (CLI): - -- Cowork runs in a desktop UI, not a terminal. The agent has access to your local files and folders and can read source material from Drive, GitHub, etc. via connectors. -- Skills work the same way (markdown + frontmatter, auto-invoked by description). Slash commands work the same. -- Cowork's connectors layer (MCP-based) lets the agent pull in source material from external systems. For example: a Drive folder of customer interview notes can become source briefs without manual copying. - -## Connectors (optional) - -If your team uses connectors: - -- **GitHub MCP** — let Cowork read run folders from a tracked GitHub repo, or push completed runs back as PRs. -- **Drive MCP** — pull source material (customer interviews, sales-call transcripts, product briefs) directly into `runs//sources/`. -- **Slack MCP** — surface run completions or claim-check flags to a team channel. - -PageKit itself does not require any connector. They are useful if you want the method to live alongside the rest of your team's tooling. - -## Typical use - -A Cowork user types: "Run PageKit on Kind Bowl, our plant-based dog food brand. Source material is in this Drive folder." - -The plugin: - -1. Invokes `/pagekit-new-run kind-bowl` to scaffold the run. -2. Pulls the source material from Drive (via the user's connector) into `runs/kind-bowl/sources/`. -3. Drives the seven-step chain via the per-step skills. -4. Surfaces the first-page decision for user approval. -5. Runs slop-check and claim-check. -6. Hands the user the completed run with an evaluation. - -## What this path does not yet prove - -The PR that introduced the Cowork agentic path includes the skills bundle. It does not yet include: - -- A published Cowork plugin manifest. -- A worked example of a real Cowork run on a real object. - -Both are deliberate. The PR proves the skills first; the plugin packaging and the worked example come once the skills are exercised. diff --git a/agentic/codex-agentic-path.md b/agentic/codex-agentic-path.md deleted file mode 100644 index 92c2bd2..0000000 --- a/agentic/codex-agentic-path.md +++ /dev/null @@ -1,58 +0,0 @@ -# Codex Agentic Path - -Run PageKit inside OpenAI's Codex CLI. Codex reads `AGENTS.md` at the repo root — that file plus the scripts in `scripts/` are all the agent needs to drive the method end-to-end. - -## What you need - -- OpenAI Codex CLI installed. See the [Codex docs](https://developers.openai.com/codex/cli). -- The PageKit repo cloned locally. - -## First run - -1. `cd` into the repo. -2. Start Codex. It reads `AGENTS.md` and (per Codex's walk behavior) any `AGENTS.md` files up and down the tree. -3. Give Codex the job: "Run PageKit on ." The agent should: - - read `pagekit.yaml` - - run `scripts/new-run.sh ` - - work through the seven canonical prompts in `prompts/` - - run `scripts/slop-check.sh` and `scripts/claim-check.sh` at the right moments - - run `scripts/run-check.sh runs/` to validate - -## How Codex differs from Claude Code here - -| Surface | Claude Code | Codex | -|---|---|---| -| Agent contract | `CLAUDE.md` + `AGENTS.md` | `AGENTS.md` | -| Skill bundle | `.claude/skills/` loaded automatically | Not used by Codex today; use Codex skills instead (see below) | -| Subagents | `.claude/agents/` loaded automatically | `developers.openai.com/codex/subagents` — define separately | -| Session hook | `.claude/settings.json` SessionStart | Not wired here; run `scripts/doctor.sh` manually at session start | - -The method is identical across tools. Only the agentic plumbing differs. - -## Optional: port the Claude Code skills to Codex skills - -Codex supports skills (markdown + metadata, same conceptual shape as Claude Code). To use the PageKit skills inside Codex, copy or symlink the per-step skill bodies from `.claude/skills/pagekit-*/SKILL.md` into the Codex skills location for your installation. The skill names map 1:1 (`/pagekit-signal-doc`, etc.). - -The canonical prompt files in `prompts/` are tool-neutral, so whichever skill system you use in Codex should load them by path rather than copy their content. - -## Optional: MCP - -Codex has first-class MCP support. PageKit does not ship an MCP server today because the scripts in `scripts/` cover everything the method needs. If your team later integrates PageKit with external systems (GitHub issues for runs, Drive for source material, etc.), a small MCP server is a natural next step; see `developers.openai.com/codex/mcp`. - -## What Codex should produce - -Same outputs as any other agentic path: - -- `runs//` scaffolded at the fully-logged tier -- per-step prompts in `runs//prompts/` -- raw outputs in `runs//outputs/` -- distilled artifacts in the run root -- `claim-check.md`, `first-page-draft-corrected.md` -- `evaluation.md` and `evaluator-pass.md` -- `scripts/run-check.sh runs/` exits 0 - -## Typical failure modes - -- **Codex does not consistently re-read `AGENTS.md` across a long session.** If drift shows up, point the agent back at `AGENTS.md` and `pagekit.yaml` explicitly. -- **Agent writes outputs directly to artifact files without saving the raw output.** Remind it: per the fully-logged tier, raw outputs go to `outputs/NN-*-output.md`, distilled artifacts go to the run root. Both are required. -- **Agent skips the slop-check and claim-check.** Require `scripts/run-check.sh runs/` to exit 0 before the run is accepted. diff --git a/.claude/agents/pagekit-claim-checker.md b/agents/pagekit-claim-checker.md similarity index 82% rename from .claude/agents/pagekit-claim-checker.md rename to agents/pagekit-claim-checker.md index 6e15a59..5fb141d 100644 --- a/.claude/agents/pagekit-claim-checker.md +++ b/agents/pagekit-claim-checker.md @@ -25,14 +25,14 @@ The orchestrator (or the user) gives you: ## Read first -- `frameworks/claim-checking.md` — flag types, severity calibration, principle. -- `frameworks/anti-slop.md` — the slop pattern catalog. -- `prompts/07-claim-check.md` — the canonical prompt body. -- `templates/claim-check-template.md` — the audit shape. +- `skills/pagekit-claim-check/references/framework.md` — flag types, severity calibration, principle. +- `skills/pagekit/references/anti-slop.md` — the slop pattern catalog. +- `skills/pagekit-claim-check/references/prompt.md` — the canonical prompt body. +- `skills/pagekit-claim-check/references/template.md` — the audit shape. ## Procedure -1. Use `scripts/claim-check.sh --severity ` to produce the expanded prompt body. (You can also load `prompts/07-claim-check.md` directly and substitute manually.) +1. Use `scripts/claim-check.sh --severity ` to produce the expanded prompt body. (You can also load `skills/pagekit-claim-check/references/prompt.md` directly and substitute manually.) 2. Run the claim check yourself: walk the draft line by line. For each potentially-weak line, identify its type from this enum: - **overclaim** — stronger than the product reality - **vague claim** — sounds concrete, resists checking @@ -41,19 +41,19 @@ The orchestrator (or the user) gives you: - **editorial voice** — brand narrating its own restraint, virtue or honesty - **unsourced quantitative modifier** — `most / usually / typically / often / many` without source - **clinical or regulatory drift** — clinical / legal / regulatory advice not supported by briefs - - **ai-slop tell** — any pattern from `frameworks/anti-slop.md` + - **ai-slop tell** — any pattern from `skills/pagekit/references/anti-slop.md` 3. For each flagged line, produce a correction with one of these three dispositions, labeled explicitly in the audit: - **rewrite** — a sharper, more accurate replacement that sits inside the proof map and reads cleaner. Precision over intensity. If a rewrite feels smaller, that is usually correct. - **remove (wrong)** — cut the line. The claim is not supportable at any severity. The audit should state why the claim is disqualified (not merely unsupported). - **remove pending verification** — cut the line from the corrected draft AND explicitly flag it in the audit as "potentially restorable if is confirmed in the briefs." The dispositions `remove (wrong)` and `remove pending verification` must not be collapsed into a silent drop; a reviewer needs to know whether the line is disqualified or held back. -4. Tally recurring patterns at the end. If a pattern fires more than once, name it as a candidate for upstream absorption into `frameworks/anti-slop.md` or `templates/page-argument-shape-template.md`. +4. Tally recurring patterns at the end. If a pattern fires more than once, name it as a candidate for upstream absorption into `skills/pagekit/references/anti-slop.md` or `skills/pagekit-page-argument-shape/references/template.md`. 5. Produce the corrected draft. Do not rewrite lines that were not flagged. Preserve verification flags. **Hard rules for the corrected draft (these are not optional):** - No inline annotation markers in body copy. `*[Rewritten: ...]*`, `*[Was: ...]*`, `*[Replaced: ...]*`, or any similar provenance marker belongs in the audit (`claim-check.md`), NOT in the corrected draft. The corrected draft is publish-ready copy. - - No new em-dashes introduced by rewrites. Per `frameworks/anti-slop.md`, body copy has zero em-dashes. Rewrites that need a pause should use a comma, colon, or parentheses. Before saving the corrected draft, scan your own rewrites for `—` or `--` and replace. + - No new em-dashes introduced by rewrites. Per the anti-slop reference, body copy has zero em-dashes. Rewrites that need a pause should use a comma, colon, or parentheses. Before saving the corrected draft, scan your own rewrites for em-dashes or double-hyphens and replace. - Before saving, mentally run `scripts/slop-check.sh` against the corrected draft. If a rewrite reintroduces any flagged pattern (em-dashes, intensifiers, copula-avoidance, etc.), fix it before saving. -6. Save the audit to `runs//claim-check.md` per `templates/claim-check-template.md`. +6. Save the audit to `runs//claim-check.md` per `skills/pagekit-claim-check/references/template.md`. 7. Save the corrected draft to `runs//first-page-draft-corrected.md` (only if any line was rewritten or removed with "remove pending verification" disposition). ## Severity calibration diff --git a/.claude/agents/pagekit-evaluator-pass.md b/agents/pagekit-evaluator-pass.md similarity index 95% rename from .claude/agents/pagekit-evaluator-pass.md rename to agents/pagekit-evaluator-pass.md index 6fda20a..5a1254c 100644 --- a/.claude/agents/pagekit-evaluator-pass.md +++ b/agents/pagekit-evaluator-pass.md @@ -25,8 +25,8 @@ Expect these inputs inside the run folder: ## Read first -- `frameworks/run-logging.md` — what the evaluator pass is for and where it fits -- `frameworks/anti-slop.md` — the patterns that matter +- `skills/pagekit/references/run-logging.md` — what the evaluator pass is for and where it fits +- `skills/pagekit/references/anti-slop.md` — the patterns that matter - The existing `evaluation.md` — to know what the run claims ## Procedure diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..6d876a6 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,28 @@ +# PageKit examples + +Worked runs that show what the full 7-step chain looks like end-to-end. +These are frozen snapshots. Use them as reference material, not as live runs. + +## What lives here + +- [`vegan-dog-food-verdel/`](vegan-dog-food-verdel/) — the canonical example. A fictional vegan dog-food product (Verdel) taken through all 7 steps including claim-check at `severity: hard`. +- [`personal-crm-founders/`](personal-crm-founders/) — a second worked example on a fictional founder-focused personal CRM. + +## How to use them + +- Open any step folder and read the artifact (`signal-doc.md`, `message-spine.md`, etc.) alongside the prompt that produced it in `prompts/` and the raw model output in `outputs/`. +- Read `evaluation.md` and `evaluator-pass.md` together. The evaluator pass is deliberately adversarial against what the evaluation quietly claims. +- Treat the per-step prompts under each example's `prompts/` folder as frozen snapshots of how the run actually executed at the time. Some YAML frontmatter in those files references the pre-restructure path layout (`framework: frameworks/X.md`). The canonical prompts now live under `skills/pagekit-/references/prompt.md`. Your own runs produced via `pagekit-new-run` will resolve to the new paths automatically. + +## Why both examples + +One example is an existence proof. Two examples start to show the pattern. The point of keeping both is that PageKit works on different objects, and the shapes of the argument differ between them. Compare `first-page-decision.md` across the two to see how the "what page comes first" decision is not a formula. + +## Running your own + +```bash +bash scripts/new-run.sh my-first-run +# fill in runs/my-first-run/goal.md and sources/, then work through prompts 01-07. +``` + +Validate with `bash scripts/run-check.sh runs/my-first-run`. diff --git a/runs/personal-crm-founders/claim-check.md b/examples/personal-crm-founders/claim-check.md similarity index 100% rename from runs/personal-crm-founders/claim-check.md rename to examples/personal-crm-founders/claim-check.md diff --git a/runs/personal-crm-founders/evaluation.md b/examples/personal-crm-founders/evaluation.md similarity index 100% rename from runs/personal-crm-founders/evaluation.md rename to examples/personal-crm-founders/evaluation.md diff --git a/runs/personal-crm-founders/evaluator-pass.md b/examples/personal-crm-founders/evaluator-pass.md similarity index 100% rename from runs/personal-crm-founders/evaluator-pass.md rename to examples/personal-crm-founders/evaluator-pass.md diff --git a/runs/personal-crm-founders/first-page-decision.md b/examples/personal-crm-founders/first-page-decision.md similarity index 100% rename from runs/personal-crm-founders/first-page-decision.md rename to examples/personal-crm-founders/first-page-decision.md diff --git a/runs/personal-crm-founders/first-page-draft-corrected.md b/examples/personal-crm-founders/first-page-draft-corrected.md similarity index 100% rename from runs/personal-crm-founders/first-page-draft-corrected.md rename to examples/personal-crm-founders/first-page-draft-corrected.md diff --git a/runs/personal-crm-founders/first-page-draft.md b/examples/personal-crm-founders/first-page-draft.md similarity index 100% rename from runs/personal-crm-founders/first-page-draft.md rename to examples/personal-crm-founders/first-page-draft.md diff --git a/runs/personal-crm-founders/goal.md b/examples/personal-crm-founders/goal.md similarity index 100% rename from runs/personal-crm-founders/goal.md rename to examples/personal-crm-founders/goal.md diff --git a/runs/personal-crm-founders/message-spine.md b/examples/personal-crm-founders/message-spine.md similarity index 100% rename from runs/personal-crm-founders/message-spine.md rename to examples/personal-crm-founders/message-spine.md diff --git a/runs/personal-crm-founders/models.md b/examples/personal-crm-founders/models.md similarity index 100% rename from runs/personal-crm-founders/models.md rename to examples/personal-crm-founders/models.md diff --git a/runs/personal-crm-founders/outputs/01-signal-doc-output.md b/examples/personal-crm-founders/outputs/01-signal-doc-output.md similarity index 100% rename from runs/personal-crm-founders/outputs/01-signal-doc-output.md rename to examples/personal-crm-founders/outputs/01-signal-doc-output.md diff --git a/runs/personal-crm-founders/outputs/02-message-spine-output.md b/examples/personal-crm-founders/outputs/02-message-spine-output.md similarity index 100% rename from runs/personal-crm-founders/outputs/02-message-spine-output.md rename to examples/personal-crm-founders/outputs/02-message-spine-output.md diff --git a/runs/personal-crm-founders/outputs/03-first-page-decision-output.md b/examples/personal-crm-founders/outputs/03-first-page-decision-output.md similarity index 100% rename from runs/personal-crm-founders/outputs/03-first-page-decision-output.md rename to examples/personal-crm-founders/outputs/03-first-page-decision-output.md diff --git a/runs/personal-crm-founders/outputs/04-page-argument-shape-output.md b/examples/personal-crm-founders/outputs/04-page-argument-shape-output.md similarity index 100% rename from runs/personal-crm-founders/outputs/04-page-argument-shape-output.md rename to examples/personal-crm-founders/outputs/04-page-argument-shape-output.md diff --git a/runs/personal-crm-founders/outputs/05-proof-map-output.md b/examples/personal-crm-founders/outputs/05-proof-map-output.md similarity index 100% rename from runs/personal-crm-founders/outputs/05-proof-map-output.md rename to examples/personal-crm-founders/outputs/05-proof-map-output.md diff --git a/runs/personal-crm-founders/outputs/06-first-page-draft-output.md b/examples/personal-crm-founders/outputs/06-first-page-draft-output.md similarity index 100% rename from runs/personal-crm-founders/outputs/06-first-page-draft-output.md rename to examples/personal-crm-founders/outputs/06-first-page-draft-output.md diff --git a/runs/personal-crm-founders/outputs/07-claim-check-output.md b/examples/personal-crm-founders/outputs/07-claim-check-output.md similarity index 100% rename from runs/personal-crm-founders/outputs/07-claim-check-output.md rename to examples/personal-crm-founders/outputs/07-claim-check-output.md diff --git a/runs/personal-crm-founders/page-argument-shape.md b/examples/personal-crm-founders/page-argument-shape.md similarity index 100% rename from runs/personal-crm-founders/page-argument-shape.md rename to examples/personal-crm-founders/page-argument-shape.md diff --git a/runs/personal-crm-founders/prompts/01-signal-doc.md b/examples/personal-crm-founders/prompts/01-signal-doc.md similarity index 100% rename from runs/personal-crm-founders/prompts/01-signal-doc.md rename to examples/personal-crm-founders/prompts/01-signal-doc.md diff --git a/runs/personal-crm-founders/prompts/02-message-spine.md b/examples/personal-crm-founders/prompts/02-message-spine.md similarity index 100% rename from runs/personal-crm-founders/prompts/02-message-spine.md rename to examples/personal-crm-founders/prompts/02-message-spine.md diff --git a/runs/personal-crm-founders/prompts/03-first-page-decision.md b/examples/personal-crm-founders/prompts/03-first-page-decision.md similarity index 100% rename from runs/personal-crm-founders/prompts/03-first-page-decision.md rename to examples/personal-crm-founders/prompts/03-first-page-decision.md diff --git a/runs/personal-crm-founders/prompts/04-page-argument-shape.md b/examples/personal-crm-founders/prompts/04-page-argument-shape.md similarity index 100% rename from runs/personal-crm-founders/prompts/04-page-argument-shape.md rename to examples/personal-crm-founders/prompts/04-page-argument-shape.md diff --git a/runs/personal-crm-founders/prompts/05-proof-map.md b/examples/personal-crm-founders/prompts/05-proof-map.md similarity index 100% rename from runs/personal-crm-founders/prompts/05-proof-map.md rename to examples/personal-crm-founders/prompts/05-proof-map.md diff --git a/runs/personal-crm-founders/prompts/06-first-page-draft.md b/examples/personal-crm-founders/prompts/06-first-page-draft.md similarity index 100% rename from runs/personal-crm-founders/prompts/06-first-page-draft.md rename to examples/personal-crm-founders/prompts/06-first-page-draft.md diff --git a/runs/personal-crm-founders/prompts/07-claim-check.md b/examples/personal-crm-founders/prompts/07-claim-check.md similarity index 100% rename from runs/personal-crm-founders/prompts/07-claim-check.md rename to examples/personal-crm-founders/prompts/07-claim-check.md diff --git a/runs/personal-crm-founders/proof-map.md b/examples/personal-crm-founders/proof-map.md similarity index 100% rename from runs/personal-crm-founders/proof-map.md rename to examples/personal-crm-founders/proof-map.md diff --git a/runs/personal-crm-founders/signal-doc.md b/examples/personal-crm-founders/signal-doc.md similarity index 100% rename from runs/personal-crm-founders/signal-doc.md rename to examples/personal-crm-founders/signal-doc.md diff --git a/runs/personal-crm-founders/sources/01-source-capture.md b/examples/personal-crm-founders/sources/01-source-capture.md similarity index 100% rename from runs/personal-crm-founders/sources/01-source-capture.md rename to examples/personal-crm-founders/sources/01-source-capture.md diff --git a/runs/personal-crm-founders/sources/02-product-brief.md b/examples/personal-crm-founders/sources/02-product-brief.md similarity index 100% rename from runs/personal-crm-founders/sources/02-product-brief.md rename to examples/personal-crm-founders/sources/02-product-brief.md diff --git a/runs/personal-crm-founders/sources/README.md b/examples/personal-crm-founders/sources/README.md similarity index 100% rename from runs/personal-crm-founders/sources/README.md rename to examples/personal-crm-founders/sources/README.md diff --git a/runs/personal-crm-founders/working-log.md b/examples/personal-crm-founders/working-log.md similarity index 100% rename from runs/personal-crm-founders/working-log.md rename to examples/personal-crm-founders/working-log.md diff --git a/runs/vegan-dog-food-verdel/claim-check.md b/examples/vegan-dog-food-verdel/claim-check.md similarity index 100% rename from runs/vegan-dog-food-verdel/claim-check.md rename to examples/vegan-dog-food-verdel/claim-check.md diff --git a/runs/vegan-dog-food-verdel/evaluation.md b/examples/vegan-dog-food-verdel/evaluation.md similarity index 100% rename from runs/vegan-dog-food-verdel/evaluation.md rename to examples/vegan-dog-food-verdel/evaluation.md diff --git a/runs/vegan-dog-food-verdel/evaluator-pass.md b/examples/vegan-dog-food-verdel/evaluator-pass.md similarity index 100% rename from runs/vegan-dog-food-verdel/evaluator-pass.md rename to examples/vegan-dog-food-verdel/evaluator-pass.md diff --git a/runs/vegan-dog-food-verdel/first-page-decision.md b/examples/vegan-dog-food-verdel/first-page-decision.md similarity index 100% rename from runs/vegan-dog-food-verdel/first-page-decision.md rename to examples/vegan-dog-food-verdel/first-page-decision.md diff --git a/runs/vegan-dog-food-verdel/first-page-draft-corrected.md b/examples/vegan-dog-food-verdel/first-page-draft-corrected.md similarity index 100% rename from runs/vegan-dog-food-verdel/first-page-draft-corrected.md rename to examples/vegan-dog-food-verdel/first-page-draft-corrected.md diff --git a/runs/vegan-dog-food-verdel/first-page-draft.md b/examples/vegan-dog-food-verdel/first-page-draft.md similarity index 100% rename from runs/vegan-dog-food-verdel/first-page-draft.md rename to examples/vegan-dog-food-verdel/first-page-draft.md diff --git a/runs/vegan-dog-food-verdel/goal.md b/examples/vegan-dog-food-verdel/goal.md similarity index 100% rename from runs/vegan-dog-food-verdel/goal.md rename to examples/vegan-dog-food-verdel/goal.md diff --git a/runs/vegan-dog-food-verdel/message-spine.md b/examples/vegan-dog-food-verdel/message-spine.md similarity index 100% rename from runs/vegan-dog-food-verdel/message-spine.md rename to examples/vegan-dog-food-verdel/message-spine.md diff --git a/runs/vegan-dog-food-verdel/models.md b/examples/vegan-dog-food-verdel/models.md similarity index 100% rename from runs/vegan-dog-food-verdel/models.md rename to examples/vegan-dog-food-verdel/models.md diff --git a/runs/vegan-dog-food-verdel/outputs/01-signal-doc-output.md b/examples/vegan-dog-food-verdel/outputs/01-signal-doc-output.md similarity index 100% rename from runs/vegan-dog-food-verdel/outputs/01-signal-doc-output.md rename to examples/vegan-dog-food-verdel/outputs/01-signal-doc-output.md diff --git a/runs/vegan-dog-food-verdel/outputs/02-message-spine-output.md b/examples/vegan-dog-food-verdel/outputs/02-message-spine-output.md similarity index 100% rename from runs/vegan-dog-food-verdel/outputs/02-message-spine-output.md rename to examples/vegan-dog-food-verdel/outputs/02-message-spine-output.md diff --git a/runs/vegan-dog-food-verdel/outputs/03-first-page-decision-output.md b/examples/vegan-dog-food-verdel/outputs/03-first-page-decision-output.md similarity index 100% rename from runs/vegan-dog-food-verdel/outputs/03-first-page-decision-output.md rename to examples/vegan-dog-food-verdel/outputs/03-first-page-decision-output.md diff --git a/runs/vegan-dog-food-verdel/outputs/04-page-argument-shape-output.md b/examples/vegan-dog-food-verdel/outputs/04-page-argument-shape-output.md similarity index 100% rename from runs/vegan-dog-food-verdel/outputs/04-page-argument-shape-output.md rename to examples/vegan-dog-food-verdel/outputs/04-page-argument-shape-output.md diff --git a/runs/vegan-dog-food-verdel/outputs/05-proof-map-output.md b/examples/vegan-dog-food-verdel/outputs/05-proof-map-output.md similarity index 100% rename from runs/vegan-dog-food-verdel/outputs/05-proof-map-output.md rename to examples/vegan-dog-food-verdel/outputs/05-proof-map-output.md diff --git a/runs/vegan-dog-food-verdel/outputs/06-first-page-draft-output.md b/examples/vegan-dog-food-verdel/outputs/06-first-page-draft-output.md similarity index 100% rename from runs/vegan-dog-food-verdel/outputs/06-first-page-draft-output.md rename to examples/vegan-dog-food-verdel/outputs/06-first-page-draft-output.md diff --git a/runs/vegan-dog-food-verdel/outputs/07-claim-check-output.md b/examples/vegan-dog-food-verdel/outputs/07-claim-check-output.md similarity index 100% rename from runs/vegan-dog-food-verdel/outputs/07-claim-check-output.md rename to examples/vegan-dog-food-verdel/outputs/07-claim-check-output.md diff --git a/runs/vegan-dog-food-verdel/page-argument-shape.md b/examples/vegan-dog-food-verdel/page-argument-shape.md similarity index 100% rename from runs/vegan-dog-food-verdel/page-argument-shape.md rename to examples/vegan-dog-food-verdel/page-argument-shape.md diff --git a/runs/vegan-dog-food-verdel/prompts/01-signal-doc.md b/examples/vegan-dog-food-verdel/prompts/01-signal-doc.md similarity index 100% rename from runs/vegan-dog-food-verdel/prompts/01-signal-doc.md rename to examples/vegan-dog-food-verdel/prompts/01-signal-doc.md diff --git a/runs/vegan-dog-food-verdel/prompts/02-message-spine.md b/examples/vegan-dog-food-verdel/prompts/02-message-spine.md similarity index 100% rename from runs/vegan-dog-food-verdel/prompts/02-message-spine.md rename to examples/vegan-dog-food-verdel/prompts/02-message-spine.md diff --git a/runs/vegan-dog-food-verdel/prompts/03-first-page-decision.md b/examples/vegan-dog-food-verdel/prompts/03-first-page-decision.md similarity index 100% rename from runs/vegan-dog-food-verdel/prompts/03-first-page-decision.md rename to examples/vegan-dog-food-verdel/prompts/03-first-page-decision.md diff --git a/runs/vegan-dog-food-verdel/prompts/04-page-argument-shape.md b/examples/vegan-dog-food-verdel/prompts/04-page-argument-shape.md similarity index 100% rename from runs/vegan-dog-food-verdel/prompts/04-page-argument-shape.md rename to examples/vegan-dog-food-verdel/prompts/04-page-argument-shape.md diff --git a/runs/vegan-dog-food-verdel/prompts/05-proof-map.md b/examples/vegan-dog-food-verdel/prompts/05-proof-map.md similarity index 100% rename from runs/vegan-dog-food-verdel/prompts/05-proof-map.md rename to examples/vegan-dog-food-verdel/prompts/05-proof-map.md diff --git a/runs/vegan-dog-food-verdel/prompts/06-first-page-draft.md b/examples/vegan-dog-food-verdel/prompts/06-first-page-draft.md similarity index 100% rename from runs/vegan-dog-food-verdel/prompts/06-first-page-draft.md rename to examples/vegan-dog-food-verdel/prompts/06-first-page-draft.md diff --git a/runs/vegan-dog-food-verdel/prompts/07-claim-check.md b/examples/vegan-dog-food-verdel/prompts/07-claim-check.md similarity index 100% rename from runs/vegan-dog-food-verdel/prompts/07-claim-check.md rename to examples/vegan-dog-food-verdel/prompts/07-claim-check.md diff --git a/runs/vegan-dog-food-verdel/proof-map.md b/examples/vegan-dog-food-verdel/proof-map.md similarity index 100% rename from runs/vegan-dog-food-verdel/proof-map.md rename to examples/vegan-dog-food-verdel/proof-map.md diff --git a/runs/vegan-dog-food-verdel/signal-doc.md b/examples/vegan-dog-food-verdel/signal-doc.md similarity index 100% rename from runs/vegan-dog-food-verdel/signal-doc.md rename to examples/vegan-dog-food-verdel/signal-doc.md diff --git a/runs/vegan-dog-food-verdel/sources/01-source-capture.md b/examples/vegan-dog-food-verdel/sources/01-source-capture.md similarity index 100% rename from runs/vegan-dog-food-verdel/sources/01-source-capture.md rename to examples/vegan-dog-food-verdel/sources/01-source-capture.md diff --git a/runs/vegan-dog-food-verdel/sources/02-product-brief.md b/examples/vegan-dog-food-verdel/sources/02-product-brief.md similarity index 100% rename from runs/vegan-dog-food-verdel/sources/02-product-brief.md rename to examples/vegan-dog-food-verdel/sources/02-product-brief.md diff --git a/runs/vegan-dog-food-verdel/sources/README.md b/examples/vegan-dog-food-verdel/sources/README.md similarity index 100% rename from runs/vegan-dog-food-verdel/sources/README.md rename to examples/vegan-dog-food-verdel/sources/README.md diff --git a/runs/vegan-dog-food-verdel/working-log.md b/examples/vegan-dog-food-verdel/working-log.md similarity index 100% rename from runs/vegan-dog-food-verdel/working-log.md rename to examples/vegan-dog-food-verdel/working-log.md diff --git a/guided-runs/01-build-signal-doc/README.md b/guided-runs/01-build-signal-doc/README.md deleted file mode 100644 index d57dfc4..0000000 --- a/guided-runs/01-build-signal-doc/README.md +++ /dev/null @@ -1,53 +0,0 @@ -# Guided Run 01: Build a Signal Doc - -## Goal - -Create a signal doc strong enough to support a real message spine. - -## Required inputs - -- product description -- any raw customer or market language -- rough audience guesses -- competitor context if available - -## Output - -- a filled signal doc - -## Steps - -1. gather raw material -2. extract repeated pains, desires and objections -3. separate generic noise from meaningful signal -4. note audience differences -5. draft candidate truths worth carrying forward - -## Quality checks - -A strong signal doc: -- contains real language, not just summaries -- distinguishes audiences where needed -- surfaces tensions and trust blockers -- reduces ambiguity - -## Common failure modes - -- too generic -- too little source language -- no meaningful audience differences -- premature positioning language -- abstract object. If the run is on a fictional product for training or testing, commit to concrete fictional facts (brand name, specific feature list, specific pricing shape, specific credentials). Drafts on an abstract object produce `[Product name]` placeholders everywhere and cannot be claim-checked meaningfully. Real objects pull facts from reality; fictional objects must invent them up front. - -## If the signal is still too weak - -Do not move forward just because the artifact exists. -If the signal doc is still too category-level, create a sharper source artifact first. -A common fix is a wedge-definition brief using: -- `templates/wedge-definition-template.md` - -## Next - -Move to: -- `guided-runs/02-reduce-to-message-spine/README.md` -only after the signal doc is strong enough to support a real reduction step. diff --git a/guided-runs/02-reduce-to-message-spine/README.md b/guided-runs/02-reduce-to-message-spine/README.md deleted file mode 100644 index d396c0a..0000000 --- a/guided-runs/02-reduce-to-message-spine/README.md +++ /dev/null @@ -1,38 +0,0 @@ -# Guided Run 02: Reduce to a Message Spine - -## Goal - -Turn the signal doc into a small set of truths strong enough to organize the site. - -## Output - -- message spine - -## Core questions - -- what patterns matter most? -- what language feels native? -- what distinctions should survive into page logic? -- what claims are strong enough to keep? - -## Quality checks - -A strong message spine: -- reduces ambiguity -- does not try to say everything -- preserves the important audience and proof differences -- feels grounded in the source signal - -## If the message spine still feels too abstract - -Do not move straight into drafting. -If the message spine still sounds broad or category-default, add sharper source material first. -Common fixes: -- mechanism brief -- proof brief -- comparison brief - -## Next - -Move to: -- `guided-runs/03-decide-first-page/README.md` diff --git a/guided-runs/03-decide-first-page/README.md b/guided-runs/03-decide-first-page/README.md deleted file mode 100644 index f0e7296..0000000 --- a/guided-runs/03-decide-first-page/README.md +++ /dev/null @@ -1,37 +0,0 @@ -# Guided Run 03: Decide the First Page - -## Goal -Decide which page should exist first instead of assuming homepage by default. - -## Output -- first-page decision - -## Core questions -- what page should exist first? -- why this page first? -- what job should it do? -- why is this stronger than starting with another page? - -## Quality checks -A strong first-page decision: -- is driven by the object, not by habit -- names the trust and proof burden clearly -- explains why this page is the right entry point - -## Common failure modes -- defaulting to homepage because it is the familiar shape -- choosing a page the object cannot yet support with proof -- deciding before the message spine is strong enough - -## If the decision feels forced -Do not advance just to keep the chain moving. -If you cannot explain why this page is the right first page, the signal doc or message spine is probably still too thin. -Go back upstream before deciding. - -## Template -Use: -- `templates/first-page-decision-template.md` - -## Next -Move to: -- `guided-runs/04-design-page-argument/README.md` diff --git a/guided-runs/04-design-page-argument/README.md b/guided-runs/04-design-page-argument/README.md deleted file mode 100644 index e523320..0000000 --- a/guided-runs/04-design-page-argument/README.md +++ /dev/null @@ -1,38 +0,0 @@ -# Guided Run 04: Design the Page Argument Shape - -## Goal -Define the page's argument shape before drafting. - -## Output -- page argument shape - -## Core questions -- what must the visitor understand first? -- what must be earned next? -- what order should the argument follow? -- what sections actually belong on this page? -- what sections would be unnecessary or harmful? - -## Quality checks -A strong page argument shape: -- fits the object -- does not rely on a default homepage rhythm -- makes trust and proof placement explicit -- names sections the page does not need, not only ones it does - -## Common failure modes -- inheriting a generic hero-features-testimonials-CTA rhythm without earning it -- hiding the trust burden inside a section that will not carry it -- planning sections that require proof the proof map cannot support - -## If the shape feels generic -Treat that as a signal that the first-page decision or message spine is underspecified. -Fix upstream before drafting. - -## Template -Use: -- `templates/page-argument-shape-template.md` - -## Next -Move to: -- `guided-runs/05-map-proof-to-pages/README.md` diff --git a/guided-runs/05-map-proof-to-pages/README.md b/guided-runs/05-map-proof-to-pages/README.md deleted file mode 100644 index 63cd1bc..0000000 --- a/guided-runs/05-map-proof-to-pages/README.md +++ /dev/null @@ -1,46 +0,0 @@ -# Guided Run 05: Map Proof to the Page - -## Goal - -Decide what proof the page needs in order to feel specific and believable, and name what it cannot yet support. - -## Output - -- proof map - -## Core questions - -- what proof burden does this page carry? -- what examples, trust objects or explanations belong where? -- what claims are still unproven? -- what should the draft avoid saying because proof is not yet there? - -## Quality checks - -A strong proof map: -- assigns proof to the specific argument moves that need it -- does not rely on generic persuasion language -- makes the gap between current proof and needed proof visible -- makes later drafting easier - -## Common failure modes - -- smoothing over missing proof with confident language -- treating logos or counts as proof when they do not answer the real trust question -- mapping only what exists, not what is still needed - -## If proof is thin - -Do not invent. -Name the gap and let the draft stay honestly narrower. -If the gap is large, a proof brief upstream is usually the right fix. - -## Template - -Use: -- `templates/proof-map-template.md` - -## Next - -Move to: -- `guided-runs/06-draft-first-page/README.md` diff --git a/guided-runs/06-draft-first-page/README.md b/guided-runs/06-draft-first-page/README.md deleted file mode 100644 index 59dc435..0000000 --- a/guided-runs/06-draft-first-page/README.md +++ /dev/null @@ -1,57 +0,0 @@ -# Guided Run 06: Draft the First Page - -## Goal - -Draft the chosen first page from the full artifact chain. - -## Output - -- first page draft - -## Rule - -Draft from the artifact chain. -Do not skip back to generic prompting. -Do not add sections the argument shape did not earn. - -## Inputs - -- signal doc -- message spine -- first-page decision -- page argument shape -- proof map - -## Quality checks - -A strong draft: -- clearly belongs to the chosen page type -- reflects the right audience and proof burden -- follows the approved argument shape -- inherits the structure of the upstream work -- stays honest where proof is thin - -## Drafting constraints - -- clarity over hype -- no fake proof -- no inflated mechanism language -- no generic category wording -- no not-X-but-Y flourishes -- no sections the argument shape did not approve - -## Draft rule - -If the draft comes out abstract, generic or overclaimed, treat that as an upstream-source failure first. -Before line-editing heavily, ask what source artifact is missing or too weak. - -## Next - -Optional durability pass: -- `guided-runs/07-claim-check/README.md` - -## What comes after PageKit v0.1 - -Later versions of PageKit should add: -- exhibit packaging -- page-family expansion diff --git a/guided-runs/07-claim-check/README.md b/guided-runs/07-claim-check/README.md deleted file mode 100644 index 27c3e0d..0000000 --- a/guided-runs/07-claim-check/README.md +++ /dev/null @@ -1,52 +0,0 @@ -# Guided Run 07: Claim Check - -## Goal - -Pass the draft through a skeptical durability layer. -Find claims that sound stronger than what the product or the proof map actually supports. - -## Output - -- a claim check pass -- an edited draft with corrected claims - -## When to run this -After the first page draft exists. -Before treating the draft as publishable. - -## Inputs - -- first page draft -- proof map -- any source briefs touching mechanism, comparison or trust - -## Core questions - -- which claims sound confident but are not actually supported? -- which claims are vague in a way that helps the draft but hides what is true? -- which claims are true but not yet provable, and need softening or sourcing? -- where does the draft say more than the mechanism can carry? - -## Quality checks - -A strong claim check: -- names specific lines, not general impressions -- separates overclaim, vague claim and unsupported claim -- proposes a sharper, more accurate replacement where possible -- does not reward defensiveness - -## Common failure modes - -- defending weak claims instead of correcting them -- replacing an overclaim with a softer overclaim -- treating a proof gap as a copy problem - -## Rule - -A claim should get stronger when it is corrected, not weaker. -Precision usually beats intensity. - -## Template - -Use: -- `templates/claim-check-template.md` diff --git a/guides/README.md b/guides/README.md deleted file mode 100644 index ce78497..0000000 --- a/guides/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# Guides - -These are fully self-contained prompt-path guides for people who want to run PageKit entirely inside a given **chat tool** (ChatGPT, Claude, Perplexity, Grok, OpenAI). - -If the tool you are using is **agentic** (Claude Code, Codex, Claude Cowork) — meaning it has file access and can run scripts on its own — see `../agentic/README.md` instead. The agentic tier is more mechanized and produces a fully-logged run on disk. - -## How to use these guides -Use one guide when you want to stay inside a single chat tool for the full artifact chain. Each guide should be usable on its own without bouncing between multiple files. - -## Where the prompts come from -The full prompt for every step lives in `../prompts/`. **Each guide references the canonical prompt by path; it does not duplicate the prompt text.** That keeps every tool's path on the same prompt — no drift across guides. If a prompt changes, edit `prompts/NN-*.md` and every guide picks it up automatically. - -## Difference from the other tiers - -| Tier | Style | Output target | -|---|---|---| -| `quickstart/` | Fastest entry. One step, copy-paste. | A signal doc you save by hand. | -| `guides/` | Full chain inside one chat tool. You paste prompts and keep the thread. | Artifacts you save by hand. | -| `agentic/` | Full chain driven by an agent with file access. | A fully-logged run on disk under `runs//`. | - -## Available guides -- `chatgpt-prompt-path.md` -- `claude-prompt-path.md` -- `perplexity-prompt-path.md` -- `grok-prompt-path.md` -- `openai-prompt-path.md` - -## Rule -The tool may differ. The artifact chain does not. - -The page shape is determined by the object. These guides should not be read as one fixed homepage template. diff --git a/guides/chatgpt-prompt-path.md b/guides/chatgpt-prompt-path.md deleted file mode 100644 index 92c92bc..0000000 --- a/guides/chatgpt-prompt-path.md +++ /dev/null @@ -1,127 +0,0 @@ -# ChatGPT Prompt Path - -## What this guide is -A fully self-contained PageKit guide for running the whole process inside ChatGPT. - -Every prompt referenced below lives canonically in `prompts/`. **Do not copy the prompt text into this file.** Edit the source prompt and this guide picks up the change automatically. - -## Best use of ChatGPT here -ChatGPT is the default baseline path. Clean, simple, comparable across runs. Good for people who want the method without tool-specific tricks. - -## What to gather before you start -- a plain-language product description -- your first audience hypothesis -- any customer language you already have -- competitors or alternatives if relevant -- the page you want to create first (optional — step 03 decides) - -## The artifact chain -Run these in order. Prompt for each step is linked; paste it into ChatGPT with the required inputs substituted. - -1. [Signal doc](../prompts/01-signal-doc.md) -2. [Message spine](../prompts/02-message-spine.md) -3. [First-page decision](../prompts/03-first-page-decision.md) -4. [Page argument shape](../prompts/04-page-argument-shape.md) -5. [Proof map](../prompts/05-proof-map.md) -6. [First page draft](../prompts/06-first-page-draft.md) -7. [Claim check](../prompts/07-claim-check.md) — optional durability pass - -**Do not skip ahead.** If an artifact is weak, fix the upstream source before moving on. - -## Step 1 — Signal doc - -Prompt: [`prompts/01-signal-doc.md`](../prompts/01-signal-doc.md). - -**Good output looks like** -- separates observation from assumption -- gives you sharper language than the category default -- exposes what is still unknown - -**If the output is weak** -Stop. Create a wedge-definition brief (`templates/wedge-definition-template.md`) before moving on. - ---- - -## Step 2 — Message spine - -Prompt: [`prompts/02-message-spine.md`](../prompts/02-message-spine.md). - -**Good output looks like** -- names the two to four truths strong enough to organize pages -- sharpens the pain -- does not yet decide which page to build - -**If the output is weak** -Add sharper source material first: mechanism brief, proof brief, or comparison brief. - ---- - -## Step 3 — First-page decision - -Prompt: [`prompts/03-first-page-decision.md`](../prompts/03-first-page-decision.md). - -**Good output looks like** -- chooses the first page on purpose -- explains why this page beats the obvious default -- lists candidates considered and rejected -- makes trust and proof burden explicit - ---- - -## Step 4 — Page argument shape - -Prompt: [`prompts/04-page-argument-shape.md`](../prompts/04-page-argument-shape.md). - -**Good output looks like** -- structure comes from the object, not category habit -- names sections the page does not need, not only sections it does -- carries the anti-slop drafting constraints forward to step 6 - ---- - -## Step 5 — Proof map - -Prompt: [`prompts/05-proof-map.md`](../prompts/05-proof-map.md). - -**Good output looks like** -- protects against overclaiming -- surfaces the gap between available and needed proof -- maps proof to specific argument moves, not to the page in general - ---- - -## Step 6 — First page draft - -Prompt: [`prompts/06-first-page-draft.md`](../prompts/06-first-page-draft.md). - -**Good output looks like** -- inherits from the upstream work -- stays honest about proof and mechanism -- reads like a person wrote it, not a machine (see `frameworks/anti-slop.md`) -- uses `*[verification flag: ...]*` for unverified product-specific claims - -**If the draft is weak** -Do not jump to line edits. Ask what upstream artifact is still too weak. That is where the real improvement lives. - ---- - -## Step 7 — Claim check (optional durability pass) - -Prompt: [`prompts/07-claim-check.md`](../prompts/07-claim-check.md). - -**Good output looks like** -- names specific lines, not general impressions -- separates claim types cleanly (overclaim / vague / unsupported / outrun proof map / editorial voice / unsourced quantitative / clinical drift / ai-slop tell) -- proposes replacements that are more precise than the originals -- names recurring patterns so upstream constraints can absorb them - -**Scripted expansion** -From the repo: `scripts/claim-check.sh --severity hard`. Writes the expanded prompt to stdout for pasting into ChatGPT. - ---- - -## Core differences vs other tools -- best as a clean baseline -- strong for comparable runs across models -- not as research-native as Perplexity -- not as naturally long-context iterative as Claude diff --git a/guides/claude-prompt-path.md b/guides/claude-prompt-path.md deleted file mode 100644 index ba6e4bc..0000000 --- a/guides/claude-prompt-path.md +++ /dev/null @@ -1,115 +0,0 @@ -# Claude Prompt Path - -## What this guide is -A fully self-contained PageKit guide for running the whole process inside Claude. - -Every prompt referenced below lives canonically in `prompts/`. Edit the source prompt, not this file. - -If you are using **Claude Code** (the CLI), skip this guide and see `agentic/claude-code-agentic-path.md` — the `.claude/skills/pagekit/` skill drives the chain end-to-end. - -## Best use of Claude here -Claude is strongest when you want to keep the full artifact chain visible in one conversation and iterate carefully from it. Long-context continuity is the reason to pick this path over others. - -## What to gather before you start -- a plain-language product description -- your first audience hypothesis -- any customer language you already have -- competitors or alternatives if relevant - -## The artifact chain -Run these in order. Keep every artifact in the thread and ask Claude to work from the full chain at every step. - -1. [Signal doc](../prompts/01-signal-doc.md) -2. [Message spine](../prompts/02-message-spine.md) -3. [First-page decision](../prompts/03-first-page-decision.md) -4. [Page argument shape](../prompts/04-page-argument-shape.md) -5. [Proof map](../prompts/05-proof-map.md) -6. [First page draft](../prompts/06-first-page-draft.md) -7. [Claim check](../prompts/07-claim-check.md) — optional - -## Step 1 — Signal doc -Prompt: [`prompts/01-signal-doc.md`](../prompts/01-signal-doc.md). - -**Good output looks like** -- separates observation from assumption -- gives sharper language than the category default -- exposes what is still unknown - -**If weak** -Create a wedge-definition brief (`templates/wedge-definition-template.md`) before moving on. - ---- - -## Step 2 — Message spine -Prompt: [`prompts/02-message-spine.md`](../prompts/02-message-spine.md). - -**Good output looks like** -- clear center of gravity -- sharpens the pain -- avoids generic category language - -**If weak** -Add sharper source material: mechanism brief, proof brief, comparison brief. - ---- - -## Step 3 — First-page decision -Prompt: [`prompts/03-first-page-decision.md`](../prompts/03-first-page-decision.md). - -**Good output looks like** -- chooses the first page on purpose -- explains why this page beats the obvious default -- lists candidates considered and rejected - ---- - -## Step 4 — Page argument shape -Prompt: [`prompts/04-page-argument-shape.md`](../prompts/04-page-argument-shape.md). - -**Good output looks like** -- derives structure from the object -- avoids default section habits -- names sections the page does not need - ---- - -## Step 5 — Proof map -Prompt: [`prompts/05-proof-map.md`](../prompts/05-proof-map.md). - -**Good output looks like** -- protects against overclaiming -- surfaces the gap between available and needed proof - ---- - -## Step 6 — First page draft -Prompt: [`prompts/06-first-page-draft.md`](../prompts/06-first-page-draft.md). - -**Good output looks like** -- inherits from the upstream work -- stays honest about proof and mechanism -- reads like a person wrote it, not a machine (see `frameworks/anti-slop.md`) - -**If weak** -Ask what upstream source artifact is still missing or too weak. Common fixes: wedge definition, mechanism brief, proof brief, comparison brief. - ---- - -## Step 7 — Claim check (optional durability pass) -Prompt: [`prompts/07-claim-check.md`](../prompts/07-claim-check.md). - -**Good output looks like** -- names specific lines, not general impressions -- separates claim types cleanly -- proposes replacements that are more precise than the originals - -**Scripted expansion** -`scripts/claim-check.sh --severity hard`. - ---- - -## Core differences vs other tools -- best for iterative refinement with the full chain visible -- strongest long-context continuity across steps -- less research-native than Perplexity -- less mechanized than Claude Code (where skills drive the chain) diff --git a/guides/grok-prompt-path.md b/guides/grok-prompt-path.md deleted file mode 100644 index 702dd12..0000000 --- a/guides/grok-prompt-path.md +++ /dev/null @@ -1,71 +0,0 @@ -# Grok Prompt Path - -## What this guide is -A fully self-contained PageKit guide for running the whole process inside Grok. - -Every prompt referenced below lives canonically in `prompts/`. Edit the source prompt, not this file. - -## Best use of Grok here -Grok is useful as a fast first-pass surface. It benefits from firmer prompt control than Claude or the OpenAI baseline path — the anti-slop constraints in the prompts are especially important. - -## What to gather before you start -- a plain-language product description -- your first audience hypothesis - -## Rule -Be more explicit with constraints than you might need elsewhere. For every step, name the artifact, say what not to do, and keep uncertainty visible. - -## The artifact chain -1. [Signal doc](../prompts/01-signal-doc.md) -2. [Message spine](../prompts/02-message-spine.md) -3. [First-page decision](../prompts/03-first-page-decision.md) -4. [Page argument shape](../prompts/04-page-argument-shape.md) -5. [Proof map](../prompts/05-proof-map.md) -6. [First page draft](../prompts/06-first-page-draft.md) -7. [Claim check](../prompts/07-claim-check.md) — optional - -## Step 1 — Signal doc -Prompt: [`prompts/01-signal-doc.md`](../prompts/01-signal-doc.md). - ---- - -## Step 2 — Message spine -Prompt: [`prompts/02-message-spine.md`](../prompts/02-message-spine.md). - ---- - -## Step 3 — First-page decision -Prompt: [`prompts/03-first-page-decision.md`](../prompts/03-first-page-decision.md). - ---- - -## Step 4 — Page argument shape -Prompt: [`prompts/04-page-argument-shape.md`](../prompts/04-page-argument-shape.md). - ---- - -## Step 5 — Proof map -Prompt: [`prompts/05-proof-map.md`](../prompts/05-proof-map.md). - ---- - -## Step 6 — First page draft -Prompt: [`prompts/06-first-page-draft.md`](../prompts/06-first-page-draft.md). Grok benefits from the anti-slop constraints block being emphasized; do not trim them when pasting. - ---- - -## Step 7 — Claim check (optional durability pass) -Prompt: [`prompts/07-claim-check.md`](../prompts/07-claim-check.md). - -**Scripted expansion** -`scripts/claim-check.sh --severity hard`. - ---- - -## If the output drifts -Treat that first as a guardrail problem: tighten the prompt. Then, if needed, strengthen the upstream source materials. - -## Core differences vs other tools -- fast and usable -- more likely to drift if the prompt gets loose -- benefits from stronger explicit control than Claude or the baseline OpenAI path diff --git a/guides/openai-prompt-path.md b/guides/openai-prompt-path.md deleted file mode 100644 index b5657e8..0000000 --- a/guides/openai-prompt-path.md +++ /dev/null @@ -1,72 +0,0 @@ -# OpenAI Prompt Path - -## What this guide is -A fully self-contained PageKit guide for running the whole process inside OpenAI model surfaces. - -Every prompt referenced below lives canonically in `prompts/`. Edit the source prompt, not this file. - -If you are using **OpenAI Codex** (the CLI), skip this guide and see `agentic/codex-agentic-path.md` — `AGENTS.md` + the scripts drive the chain. - -## Best use here -Use this as the neutral baseline prompt path. Good for users who want the method without much tool-specific behavior, and for comparable runs across models. - -## What to gather before you start -- a plain-language product description -- your first audience hypothesis - -## The artifact chain -1. [Signal doc](../prompts/01-signal-doc.md) -2. [Message spine](../prompts/02-message-spine.md) -3. [First-page decision](../prompts/03-first-page-decision.md) -4. [Page argument shape](../prompts/04-page-argument-shape.md) -5. [Proof map](../prompts/05-proof-map.md) -6. [First page draft](../prompts/06-first-page-draft.md) -7. [Claim check](../prompts/07-claim-check.md) — optional - -## Step 1 — Signal doc -Prompt: [`prompts/01-signal-doc.md`](../prompts/01-signal-doc.md). - ---- - -## Step 2 — Message spine -Prompt: [`prompts/02-message-spine.md`](../prompts/02-message-spine.md). - ---- - -## Step 3 — First-page decision -Prompt: [`prompts/03-first-page-decision.md`](../prompts/03-first-page-decision.md). - ---- - -## Step 4 — Page argument shape -Prompt: [`prompts/04-page-argument-shape.md`](../prompts/04-page-argument-shape.md). - ---- - -## Step 5 — Proof map -Prompt: [`prompts/05-proof-map.md`](../prompts/05-proof-map.md). - ---- - -## Step 6 — First page draft -Prompt: [`prompts/06-first-page-draft.md`](../prompts/06-first-page-draft.md). - ---- - -## Step 7 — Claim check (optional durability pass) -Prompt: [`prompts/07-claim-check.md`](../prompts/07-claim-check.md). - -**Scripted expansion** -`scripts/claim-check.sh --severity hard`. - ---- - -## If the draft comes back generic -Do not keep hammering the final draft prompt. Go upstream and improve the source materials. - -## Core differences vs other tools -- best neutral baseline -- strong for comparable runs -- not as research-native as Perplexity -- not as naturally iterative as Claude -- less mechanized than Codex (where AGENTS.md + scripts can drive the chain) diff --git a/guides/perplexity-prompt-path.md b/guides/perplexity-prompt-path.md deleted file mode 100644 index 5a0fd48..0000000 --- a/guides/perplexity-prompt-path.md +++ /dev/null @@ -1,95 +0,0 @@ -# Perplexity Prompt Path - -## What this guide is -A fully self-contained PageKit guide for running the whole process inside Perplexity. - -Every prompt referenced below lives canonically in `prompts/`. Edit the source prompt, not this file. - -## Best use of Perplexity here -Perplexity is strongest when outside research can strengthen the source layer early. Use it when category language, trust questions, comparisons or market context matter more than the average. - -## What to gather before you start -- a plain-language product description -- your first audience hypothesis -- any known competitors or alternatives - -## Rule -Use research to strengthen source material. Do not let the outside voice overpower the product voice. Mark any signal sourced from research as such in the signal doc. - -## The artifact chain -1. [Signal doc](../prompts/01-signal-doc.md) -2. [Message spine](../prompts/02-message-spine.md) -3. [First-page decision](../prompts/03-first-page-decision.md) -4. [Page argument shape](../prompts/04-page-argument-shape.md) -5. [Proof map](../prompts/05-proof-map.md) -6. [First page draft](../prompts/06-first-page-draft.md) -7. [Claim check](../prompts/07-claim-check.md) — optional - -## Step 1 — Signal doc -Prompt: [`prompts/01-signal-doc.md`](../prompts/01-signal-doc.md). Tell Perplexity to bring in outside category observations, but mark them clearly and keep them separate from assumptions about this product. - -**Good output looks like** -- separates outside signal from product signal -- sharpens category language without replacing the product voice - ---- - -## Step 2 — Message spine -Prompt: [`prompts/02-message-spine.md`](../prompts/02-message-spine.md). Keep any outside observations marked. - -**Good output looks like** -- grounded in the product, not in category averages -- outside observations influence the spine without dominating it - ---- - -## Step 3 — First-page decision -Prompt: [`prompts/03-first-page-decision.md`](../prompts/03-first-page-decision.md). - -**Good output looks like** -- chooses the first page on purpose -- lines up with the trust questions surfaced in research -- lists candidates considered and rejected - ---- - -## Step 4 — Page argument shape -Prompt: [`prompts/04-page-argument-shape.md`](../prompts/04-page-argument-shape.md). - -**Good output looks like** -- structure follows the object, not category habit -- makes trust placement explicit - ---- - -## Step 5 — Proof map -Prompt: [`prompts/05-proof-map.md`](../prompts/05-proof-map.md). Separate product proof from external context and category trust signals. - -**Good output looks like** -- keeps external context from masquerading as product proof -- surfaces the gap between available and needed proof - ---- - -## Step 6 — First page draft -Prompt: [`prompts/06-first-page-draft.md`](../prompts/06-first-page-draft.md). Keep the product voice primary. - -**Good output looks like** -- inherits from the upstream work -- outside research is in service of the product voice, not ahead of it -- reads like a person wrote it (see `frameworks/anti-slop.md`) - ---- - -## Step 7 — Claim check (optional durability pass) -Prompt: [`prompts/07-claim-check.md`](../prompts/07-claim-check.md). - -**Scripted expansion** -`scripts/claim-check.sh --severity hard`. - ---- - -## Core differences vs other tools -- strongest for early source enrichment and category sharpening -- especially useful for trust-heavy or comparison-heavy objects -- easiest tool to overuse if you let research replace actual positioning diff --git a/pagekit.yaml b/pagekit.yaml deleted file mode 100644 index 4961886..0000000 --- a/pagekit.yaml +++ /dev/null @@ -1,232 +0,0 @@ -# pagekit.yaml — canonical method manifest -# -# Single source of truth for the PageKit method. Scripts, skills, agents -# and the guides all read from here. Edit this file to change the method; -# everything downstream follows. -# -# Every file path is relative to the repo root. - -version: "0.2" -name: PageKit -description: A system for producing better pages by strengthening the source materials that shape the copy. - -# Canonical entry points for agents. The order here is the order an agent -# reading the repo cold should follow. -entry_points: - agent_contract: AGENTS.md # Codex-first, Claude-Code-compatible - claude_specific: CLAUDE.md # Claude Code contract (more detailed) - human_first_time: START-HERE.md - full_overview: README.md - -# Directory conventions. -paths: - frameworks: frameworks/ - templates: templates/ - guides: guides/ - quickstart: quickstart/ - agentic: agentic/ - guided_runs: guided-runs/ - runs: runs/ - prompts: prompts/ - scripts: scripts/ - skills: .claude/skills/ - -# The canonical method. Steps run in number order. -# Steps 01–06 are required. Step 07 is an optional durability pass. -method: - steps: - - number: "01" - name: signal-doc - title: Build a Signal Doc - artifact: signal-doc.md - framework: frameworks/signal-doc.md - template: templates/signal-doc-template.md - guided_run: guided-runs/01-build-signal-doc/README.md - prompt: prompts/01-signal-doc.md - required: true - inputs: - - product-brief (or raw product description) - outputs: - - signal-doc.md - - - number: "02" - name: message-spine - title: Reduce to a Message Spine - artifact: message-spine.md - framework: frameworks/message-spine.md - template: templates/message-spine-template.md - guided_run: guided-runs/02-reduce-to-message-spine/README.md - prompt: prompts/02-message-spine.md - required: true - inputs: - - signal-doc.md - outputs: - - message-spine.md - - - number: "03" - name: first-page-decision - title: Decide the First Page - artifact: first-page-decision.md - framework: frameworks/first-page-decision.md - template: templates/first-page-decision-template.md - guided_run: guided-runs/03-decide-first-page/README.md - prompt: prompts/03-first-page-decision.md - required: true - inputs: - - signal-doc.md - - message-spine.md - outputs: - - first-page-decision.md - notes: | - Does NOT default to homepage. The object decides. The decision - must list candidates considered and rejected. - - - number: "04" - name: page-argument-shape - title: Design the Page Argument Shape - artifact: page-argument-shape.md - framework: frameworks/page-argument-shape.md - template: templates/page-argument-shape-template.md - guided_run: guided-runs/04-design-page-argument/README.md - prompt: prompts/04-page-argument-shape.md - required: true - inputs: - - first-page-decision.md - outputs: - - page-argument-shape.md - - - number: "05" - name: proof-map - title: Map Proof to the Page - artifact: proof-map.md - framework: frameworks/proof-map.md - template: templates/proof-map-template.md - guided_run: guided-runs/05-map-proof-to-pages/README.md - prompt: prompts/05-proof-map.md - required: true - inputs: - - first-page-decision.md - - page-argument-shape.md - outputs: - - proof-map.md - - - number: "06" - name: first-page-draft - title: Draft the First Page - artifact: first-page-draft.md - framework: frameworks/page-argument-shape.md # drafting constraints live here - template: templates/page-argument-shape-template.md - guided_run: guided-runs/06-draft-first-page/README.md - prompt: prompts/06-first-page-draft.md - required: true - inputs: - - signal-doc.md - - message-spine.md - - first-page-decision.md - - page-argument-shape.md - - proof-map.md - outputs: - - first-page-draft.md - notes: | - The draft must respect the anti-slop constraints in - frameworks/anti-slop.md. Unverified product claims get - inline *[verification flag: ...]* markers. - - - number: "07" - name: claim-check - title: Claim Check (optional durability pass) - artifact: claim-check.md - framework: frameworks/claim-checking.md - template: templates/claim-check-template.md - guided_run: guided-runs/07-claim-check/README.md - prompt: prompts/07-claim-check.md - required: false - severity_options: [light, normal, hard] - default_severity: normal - inputs: - - first-page-draft.md - - proof-map.md - outputs: - - claim-check.md - - first-page-draft-corrected.md # optional; produced if any line was flagged - -# Anti-slop rule reference. -anti_slop: - framework: frameworks/anti-slop.md - script: scripts/slop-check.sh - -# Run-logging tiers (see frameworks/run-logging.md). -run_logging: - framework: frameworks/run-logging.md - tiers: - fully_logged: - required_files: - - goal.md - - working-log.md - - models.md - - sources/ # directory with source briefs - - prompts/ # one file per step, NN-*.md - - outputs/ # one file per step, NN-*-output.md - - evaluation.md - - evaluator-pass.md - required_artifacts: - - signal-doc.md - - message-spine.md - - first-page-decision.md - - page-argument-shape.md - - proof-map.md - - first-page-draft.md - summary_logged: - required_files: - - goal.md - - working-log.md - - models.md - - evaluation.md - required_artifacts: - - signal-doc.md - - message-spine.md - - first-page-decision.md - - page-argument-shape.md - - proof-map.md - - first-page-draft.md - -# Tooling. -tooling: - scripts: - - path: scripts/new-run.sh - description: Scaffold a fully-logged run folder. - usage: scripts/new-run.sh - - path: scripts/run-check.sh - description: Validate a run against the fully-logged / summary-logged tier. - usage: scripts/run-check.sh - - path: scripts/claim-check.sh - description: Template-expand a claim-check prompt for paste. - usage: scripts/claim-check.sh [--severity hard|normal|light] - - path: scripts/slop-check.sh - description: Heuristic regression check for AI-slop patterns. - usage: scripts/slop-check.sh [...] - - path: scripts/doctor.sh - description: Repo health pre-flight check. - usage: scripts/doctor.sh - make_targets: - - make new-run NAME= - - make run-check RUN= - - make slop-check - - make claim-check DRAFT= PROOF= [SEVERITY=hard|normal|light] - - make doctor - - make help - -# Agentic surfaces. -agentic: - claude_code: - path: agentic/claude-code-agentic-path.md - skills_dir: .claude/skills/ - subagents_dir: .claude/agents/ - settings: .claude/settings.json - codex: - path: agentic/codex-agentic-path.md - contract: AGENTS.md - claude_cowork: - path: agentic/claude-cowork-agentic-path.md - plugin_body: .claude/skills/ - plugin_reference: https://github.com/anthropics/knowledge-work-plugins diff --git a/prompts/01-signal-doc.md b/prompt-paste/01-signal-doc.md similarity index 82% rename from prompts/01-signal-doc.md rename to prompt-paste/01-signal-doc.md index ba2b916..c42668e 100644 --- a/prompts/01-signal-doc.md +++ b/prompt-paste/01-signal-doc.md @@ -1,14 +1,3 @@ ---- -step: "01" -name: signal-doc -title: Build a Signal Doc -inputs: - - product-brief (or raw product description) -outputs: - - signal-doc.md -framework: frameworks/signal-doc.md -template: templates/signal-doc-template.md ---- # Prompt: 01 — Signal Doc @@ -51,4 +40,4 @@ Source material: ``` ## If the output is weak -Stop. Before moving to step 02, create a sharper source artifact (wedge definition, mechanism brief, proof brief, comparison brief). See `templates/wedge-definition-template.md`. +Stop. Before moving to step 02, create a sharper source artifact (wedge definition, mechanism brief, proof brief, comparison brief). A wedge-definition template lives in the PageKit repo at `skills/pagekit-signal-doc/references/wedge-definition-template.md`. diff --git a/prompts/02-message-spine.md b/prompt-paste/02-message-spine.md similarity index 81% rename from prompts/02-message-spine.md rename to prompt-paste/02-message-spine.md index 89bfbaa..b439140 100644 --- a/prompts/02-message-spine.md +++ b/prompt-paste/02-message-spine.md @@ -1,14 +1,3 @@ ---- -step: "02" -name: message-spine -title: Reduce to a Message Spine -inputs: - - signal-doc.md -outputs: - - message-spine.md -framework: frameworks/message-spine.md -template: templates/message-spine-template.md ---- # Prompt: 02 — Message Spine diff --git a/prompts/03-first-page-decision.md b/prompt-paste/03-first-page-decision.md similarity index 88% rename from prompts/03-first-page-decision.md rename to prompt-paste/03-first-page-decision.md index a2f5ecd..1d9616f 100644 --- a/prompts/03-first-page-decision.md +++ b/prompt-paste/03-first-page-decision.md @@ -1,18 +1,3 @@ ---- -step: "03" -name: first-page-decision -title: Decide the First Page -inputs: - - signal-doc.md - - message-spine.md -outputs: - - first-page-decision.md -framework: frameworks/first-page-decision.md -template: templates/first-page-decision-template.md -notes: | - This step exists to stop the method from quietly defaulting to a - homepage. The decision must list candidates considered and rejected. ---- # Prompt: 03 — First-Page Decision diff --git a/prompts/04-page-argument-shape.md b/prompt-paste/04-page-argument-shape.md similarity index 82% rename from prompts/04-page-argument-shape.md rename to prompt-paste/04-page-argument-shape.md index 2439efc..d78cd00 100644 --- a/prompts/04-page-argument-shape.md +++ b/prompt-paste/04-page-argument-shape.md @@ -1,14 +1,3 @@ ---- -step: "04" -name: page-argument-shape -title: Design the Page Argument Shape -inputs: - - first-page-decision.md -outputs: - - page-argument-shape.md -framework: frameworks/page-argument-shape.md -template: templates/page-argument-shape-template.md ---- # Prompt: 04 — Page Argument Shape diff --git a/prompts/05-proof-map.md b/prompt-paste/05-proof-map.md similarity index 80% rename from prompts/05-proof-map.md rename to prompt-paste/05-proof-map.md index 88fd413..4ca220c 100644 --- a/prompts/05-proof-map.md +++ b/prompt-paste/05-proof-map.md @@ -1,15 +1,3 @@ ---- -step: "05" -name: proof-map -title: Map Proof to the Page -inputs: - - first-page-decision.md - - page-argument-shape.md -outputs: - - proof-map.md -framework: frameworks/proof-map.md -template: templates/proof-map-template.md ---- # Prompt: 05 — Proof Map diff --git a/prompts/06-first-page-draft.md b/prompt-paste/06-first-page-draft.md similarity index 79% rename from prompts/06-first-page-draft.md rename to prompt-paste/06-first-page-draft.md index e66fa8f..e2022d1 100644 --- a/prompts/06-first-page-draft.md +++ b/prompt-paste/06-first-page-draft.md @@ -1,22 +1,3 @@ ---- -step: "06" -name: first-page-draft -title: Draft the First Page -inputs: - - signal-doc.md - - message-spine.md - - first-page-decision.md - - page-argument-shape.md - - proof-map.md -outputs: - - first-page-draft.md -framework: frameworks/page-argument-shape.md -template: templates/page-argument-shape-template.md -notes: | - The draft must respect the anti-slop constraints in - frameworks/anti-slop.md. Unverified product claims get inline - *[verification flag: ...]* markers. ---- # Prompt: 06 — First Page Draft @@ -43,7 +24,7 @@ Proof and scope constraints: - no inflated mechanism claims - avoid generic category language -Anti-slop constraints (hard rules — see frameworks/anti-slop.md): +Anti-slop constraints (hard rules): - no "Not X. Not Y." heading or sentence pairs - no "Not-X-but-Y" or "X-not-Y" rhetorical pivots unless they carry specific content the affirmation cannot - no three parallel short sentences used for cadence (rule-of-three clustering) diff --git a/prompts/07-claim-check.md b/prompt-paste/07-claim-check.md similarity index 83% rename from prompts/07-claim-check.md rename to prompt-paste/07-claim-check.md index d226b77..2329b80 100644 --- a/prompts/07-claim-check.md +++ b/prompt-paste/07-claim-check.md @@ -1,23 +1,3 @@ ---- -step: "07" -name: claim-check -title: Claim Check (optional durability pass) -required: false -inputs: - - first-page-draft.md - - proof-map.md -outputs: - - claim-check.md - - first-page-draft-corrected.md -framework: frameworks/claim-checking.md -template: templates/claim-check-template.md -severity_options: [light, normal, hard] -default_severity: normal -notes: | - Severity is a required argument. Record the choice and why. - scripts/claim-check.sh expands this prompt with a draft, a proof map - and a severity setting. ---- # Prompt: 07 — Claim Check @@ -59,7 +39,7 @@ A corrected claim should be more precise, not louder. The corrected draft must be clean on its own terms: no inline annotation markers (`*[Rewritten: ...]*`, `*[Was: ...]*`) in body copy, and no new em-dashes introduced by the rewrites. The audit is where rewrite provenance lives; the corrected draft is publish-ready copy. -At the end, list any slop pattern that showed up more than once so upstream constraints (frameworks/anti-slop.md or page-argument-shape drafting constraints) can absorb it. +At the end, list any slop pattern that showed up more than once so upstream constraints (the anti-slop rules or page-argument-shape drafting constraints) can absorb it. Then produce a corrected draft that resolves every flagged claim. diff --git a/prompt-paste/README.md b/prompt-paste/README.md new file mode 100644 index 0000000..27fd31d --- /dev/null +++ b/prompt-paste/README.md @@ -0,0 +1,30 @@ +# PageKit prompts for chat apps + +If you use ChatGPT, Perplexity, Grok, Gemini, or another chat interface that does not run the Claude Code plugin, this folder is for you. + +Each file here is the same canonical prompt that the PageKit skills use, stripped of YAML frontmatter so you can paste it straight into any chat window. + +## The 7 prompts + +1. [01-signal-doc.md](01-signal-doc.md) — produce the signal doc from your source briefs +2. [02-message-spine.md](02-message-spine.md) — reduce the signal doc to a message spine +3. [03-first-page-decision.md](03-first-page-decision.md) — decide which page to build first +4. [04-page-argument-shape.md](04-page-argument-shape.md) — design the page argument shape +5. [05-proof-map.md](05-proof-map.md) — build the proof map +6. [06-first-page-draft.md](06-first-page-draft.md) — draft the first page +7. [07-claim-check.md](07-claim-check.md) — adversarial claim-check pass + +## How to run the chain manually + +1. Write a short source brief about your product. Include what it does, who it is for, and the mechanism that makes it work. +2. Open step 01. Paste the prompt into the chat window, paste your source brief below the prompt, send. +3. Save the model's output. That is your signal doc. +4. Open step 02. Paste the prompt. Paste the signal doc where the prompt asks for it. Send. +5. Save the message spine. Continue the chain: each step takes the previous step's output as input. +6. At step 06 you have a first-page draft. At step 07 you have an adversarial audit of that draft. + +## Why the plugin is better + +The Claude Code plugin runs the whole chain with one command, enforces the anti-slop rules on the draft mechanically, and produces a fully-logged run folder you can verify later. See the repo [README](../README.md) for the one-line install. + +This chat-paste path exists so the method is still usable without installing anything. The output quality depends on how honest your source briefs are; the same constraint applies to the plugin path. diff --git a/prompts/README.md b/prompts/README.md deleted file mode 100644 index cf261d6..0000000 --- a/prompts/README.md +++ /dev/null @@ -1,39 +0,0 @@ -# Prompts - -These are the canonical prompts for the PageKit method. - -Every guide, quickstart, skill and script that runs a step of the method pulls from these files. **Edit here. Do not edit copies.** - -## Why one place - -Before this directory existed, the same seven prompts were duplicated across five tool guides (5 × 7 = 35 copies). They drifted. This was visible in real runs: different bots using different guides produced measurably different output at the same step. - -One canonical source per step fixes that. - -## Files - -- `01-signal-doc.md` -- `02-message-spine.md` -- `03-first-page-decision.md` -- `04-page-argument-shape.md` -- `05-proof-map.md` -- `06-first-page-draft.md` -- `07-claim-check.md` - -Each file has: -- YAML frontmatter: step number, step name, inputs, outputs, severity options where relevant -- A prompt body ready to paste into a model (or expanded by `scripts/claim-check.sh`, or wrapped by a skill in `.claude/skills/`) - -## How guides use these - -Tool guides (`guides/*.md`) reference the canonical prompt for each step by path. They keep the per-tool narrative (what the tool is good at, what to gather before starting, how to iterate) but stop carrying the prompt text itself. - -## How skills use these - -Each per-step skill under `.claude/skills/pagekit-/SKILL.md` loads the corresponding prompt file as procedural content. The skill description determines auto-invocation; the prompt body is the instruction. - -## Editing rules - -- Changes here are the method changing. Review against `frameworks/` before editing. -- Keep the `## Prompt` section copy-paste-ready: the reader should be able to paste the fenced block into a model without stripping anything out. -- Do not embed severity or verification-flag text in the prompt; those come from the frontmatter or from the caller. diff --git a/quickstart/README.md b/quickstart/README.md deleted file mode 100644 index e7b12f8..0000000 --- a/quickstart/README.md +++ /dev/null @@ -1,38 +0,0 @@ -# Quickstart - -This is the fastest way into PageKit. - -## How to use this -Use quickstarts when you want the lightest possible path into the system. - -If you want a fuller, self-contained tool path inside a chat tool, move to `../guides/README.md`. - -If you are using an agentic tool (Claude Code, Codex, Claude Cowork) that can read files and run scripts on its own, see `../agentic/README.md` instead — it is the most mechanized path and produces a fully-logged run on disk for you. - -## Choose your path -- `start-with-prompts.md` for the simplest model-agnostic start -- `chatgpt.md` -- `claude.md` -- `perplexity.md` -- `grok.md` -- `openai.md` - -## Quickstart standard -Every quickstart path should include: -- what the user needs first -- the exact prompt to run -- what artifact to create next -- what good output looks like -- a copy/paste fallback if any launch link breaks - -## Warning -If the output comes back generic, do not keep prompting harder in place. -Go upstream and strengthen the source materials first. - -## If you want a full tool-specific chat path -Use the fully self-contained guides in: -- `../guides/README.md` - -## If you are using an agentic tool -Skip the quickstart and go to: -- `../agentic/README.md` diff --git a/quickstart/chatgpt.md b/quickstart/chatgpt.md deleted file mode 100644 index 4d433f9..0000000 --- a/quickstart/chatgpt.md +++ /dev/null @@ -1,70 +0,0 @@ -# ChatGPT Quickstart - -## What this path is for -Use this if you want to start PageKit inside ChatGPT. - -## What you need first -- a plain-language product description -- your first audience hypothesis - -## Start with this artifact -Begin with a signal doc. -Do not decide which page you are building yet. - -## Prompt to run first -Copy/paste this into ChatGPT: - -```text -I want to build a web page through the PageKit process. - -Do not write page copy yet. -Do not assume which page we are building. -Help me build a signal doc first. - -Using the product description below, produce a signal doc with these sections: -1. what the product appears to be -2. likely target audience(s) -3. recurring pains or friction -4. desired outcomes -5. trust questions or buying resistance -6. native phrases worth keeping -7. generic language to avoid -8. what still feels unknown -9. weak claims to avoid early - -Product description: -[PASTE HERE] -``` - -## What good output looks like -Good output: -- separates observation from assumption -- surfaces uncertainty honestly -- gives you sharper language than the category default - -Bad output: -- sounds like finished page copy too early -- feels generic -- hides what is still unknown - -## What good output does not sound like -Downstream drafts should not carry these AI-slop patterns (see `frameworks/anti-slop.md`): -- "Not X. Not Y." heading pairs -- three parallel short sentences in a row for cadence -- "Your…Your…Your" or "Not…Not…Not" sentence-start anaphora -- editorial voice narrating the brand's own restraint -- em-dashes in body copy -- "actually" as intensifier -- marketing-punchy one-liners as section enders - -## What to do next -Put the result into your signal-doc file, then move to: -- `guided-runs/02-reduce-to-message-spine/README.md` - -## Want the full tool-specific path? -If you want the full chain inside ChatGPT in one place, use: -- `guides/chatgpt-prompt-path.md` - -## Link note -If ChatGPT launch-link parameters are stable enough later, add them here. -Until then, the copy/paste prompt is the durable path. diff --git a/quickstart/claude.md b/quickstart/claude.md deleted file mode 100644 index 77cda2c..0000000 --- a/quickstart/claude.md +++ /dev/null @@ -1,65 +0,0 @@ -# Claude Quickstart - -## What this path is for -Use this if you want to start PageKit inside Claude. - -## What you need first -- a plain-language product description -- your first audience hypothesis - -## Start with this artifact -Begin with a signal doc. -Do not decide which page you are building yet. - -## Prompt to run first -Copy/paste this into Claude: - -```text -I want to build a web page through the PageKit process. - -Do not write page copy yet. -Do not assume which page we are building. -Help me build a signal doc first. - -Using the product description below, produce a signal doc with these sections: -1. what the product appears to be -2. likely target audience(s) -3. recurring pains or friction -4. desired outcomes -5. trust questions or buying resistance -6. native phrases worth keeping -7. generic language to avoid -8. what still feels unknown -9. weak claims to avoid early - -Product description: -[PASTE HERE] -``` - -## What good output looks like -Good output: -- gives you sharper source material -- keeps uncertainty visible -- avoids drifting into finished copy too early - -## What good output does not sound like -Downstream drafts should not carry these AI-slop patterns (see `frameworks/anti-slop.md`): -- "Not X. Not Y." heading pairs -- three parallel short sentences in a row for cadence -- "Your…Your…Your" or "Not…Not…Not" sentence-start anaphora -- editorial voice narrating the brand's own restraint -- em-dashes in body copy -- "actually" as intensifier -- marketing-punchy one-liners as section enders - -## What to do next -Put the result into your signal-doc file, then move to: -- `guided-runs/02-reduce-to-message-spine/README.md` - -## Want the full tool-specific path? -If you want the full chain inside Claude in one place, use: -- `guides/claude-prompt-path.md` - -## Link note -If Claude deep-link or prefill mechanics are reliable enough, add them here later. -The copy/paste prompt remains the stable path. diff --git a/quickstart/grok.md b/quickstart/grok.md deleted file mode 100644 index 33c3c24..0000000 --- a/quickstart/grok.md +++ /dev/null @@ -1,64 +0,0 @@ -# Grok Quickstart - -## What this path is for -Use this if you want to start PageKit inside Grok. - -## What you need first -- a plain-language product description -- your first audience hypothesis - -## Start with this artifact -Begin with a signal doc. -Do not decide which page you are building yet. - -## Prompt to run first -Copy/paste this into Grok: - -```text -I want to build a web page through the PageKit process. - -Do not write page copy yet. -Do not assume which page we are building. -Help me build a signal doc first. - -Using the product description below, produce a signal doc with these sections: -1. what the product appears to be -2. likely target audience(s) -3. recurring pains or friction -4. desired outcomes -5. trust questions or buying resistance -6. native phrases worth keeping -7. generic language to avoid -8. what still feels unknown -9. weak claims to avoid early - -Product description: -[PASTE HERE] -``` - -## What good output looks like -Good output: -- sharpens the object -- exposes uncertainty honestly -- avoids category-default sludge - -## What good output does not sound like -Downstream drafts should not carry these AI-slop patterns (see `frameworks/anti-slop.md`): -- "Not X. Not Y." heading pairs -- three parallel short sentences in a row for cadence -- "Your…Your…Your" or "Not…Not…Not" sentence-start anaphora -- editorial voice narrating the brand's own restraint -- em-dashes in body copy -- "actually" as intensifier -- marketing-punchy one-liners as section enders - -## What to do next -Put the result into your signal-doc file, then move to: -- `guided-runs/02-reduce-to-message-spine/README.md` - -## Want the full tool-specific path? -If you want the full chain inside Grok in one place, use: -- `guides/grok-prompt-path.md` - -## Link note -If reliable prompt-link support is confirmed later, add it here. diff --git a/quickstart/openai.md b/quickstart/openai.md deleted file mode 100644 index c82a327..0000000 --- a/quickstart/openai.md +++ /dev/null @@ -1,61 +0,0 @@ -# OpenAI Quickstart - -## What this path is for -Use this if you want to start PageKit inside OpenAI surfaces that support raw prompting. - -## What you need first -- a plain-language product description -- your first audience hypothesis - -## Start with this artifact -Begin with a signal doc. -Do not decide which page you are building yet. - -## Prompt to run first -Copy/paste this into the model: - -```text -I want to build a web page through the PageKit process. - -Do not write page copy yet. -Do not assume which page we are building. -Help me build a signal doc first. - -Using the product description below, produce a signal doc with these sections: -1. what the product appears to be -2. likely target audience(s) -3. recurring pains or friction -4. desired outcomes -5. trust questions or buying resistance -6. native phrases worth keeping -7. generic language to avoid -8. what still feels unknown -9. weak claims to avoid early - -Product description: -[PASTE HERE] -``` - -## What good output looks like -Good output: -- strengthens source material -- avoids premature copywriting -- makes the next artifact clearer - -## What good output does not sound like -Downstream drafts should not carry these AI-slop patterns (see `frameworks/anti-slop.md`): -- "Not X. Not Y." heading pairs -- three parallel short sentences in a row for cadence -- "Your…Your…Your" or "Not…Not…Not" sentence-start anaphora -- editorial voice narrating the brand's own restraint -- em-dashes in body copy -- "actually" as intensifier -- marketing-punchy one-liners as section enders - -## What to do next -Put the result into your signal-doc file, then move to: -- `guided-runs/02-reduce-to-message-spine/README.md` - -## Want the full tool-specific path? -If you want the full chain inside an OpenAI model in one place, use: -- `guides/openai-prompt-path.md` diff --git a/quickstart/perplexity.md b/quickstart/perplexity.md deleted file mode 100644 index 7718c67..0000000 --- a/quickstart/perplexity.md +++ /dev/null @@ -1,66 +0,0 @@ -# Perplexity Quickstart - -## What this path is for -Use this if you want to start PageKit inside Perplexity, especially when outside research should strengthen the first pass. - -## What you need first -- a plain-language product description -- your first audience hypothesis - -## Start with this artifact -Begin with a signal doc. -Do not decide which page you are building yet. - -## Prompt to run first -Copy/paste this into Perplexity: - -```text -I want to build a web page through the PageKit process. - -Do not write page copy yet. -Do not assume which page we are building. -Help me build a signal doc first. - -Using the product description below, produce a signal doc with these sections: -1. what the product appears to be -2. likely target audience(s) -3. recurring pains or friction -4. desired outcomes -5. trust questions or buying resistance -6. native phrases worth keeping -7. generic language to avoid -8. what still feels unknown -9. weak claims to avoid early - -Where useful, bring in outside category observations, but mark them clearly and keep them separate from assumptions about this product. - -Product description: -[PASTE HERE] -``` - -## What good output looks like -Good output: -- separates grounded observations from guesswork -- sharpens the category language -- still behaves like source work, not final copy - -## What good output does not sound like -Downstream drafts should not carry these AI-slop patterns (see `frameworks/anti-slop.md`): -- "Not X. Not Y." heading pairs -- three parallel short sentences in a row for cadence -- "Your…Your…Your" or "Not…Not…Not" sentence-start anaphora -- editorial voice narrating the brand's own restraint -- em-dashes in body copy -- "actually" as intensifier -- marketing-punchy one-liners as section enders - -## What to do next -Put the result into your signal-doc file, then move to: -- `guided-runs/02-reduce-to-message-spine/README.md` - -## Want the full tool-specific path? -If you want the full chain inside Perplexity in one place, use: -- `guides/perplexity-prompt-path.md` - -## Link note -If reliable launch-link support is confirmed later, add it here. diff --git a/quickstart/start-with-prompts.md b/quickstart/start-with-prompts.md deleted file mode 100644 index 3a1c499..0000000 --- a/quickstart/start-with-prompts.md +++ /dev/null @@ -1,47 +0,0 @@ -# Start With Prompts - -This is the lowest-friction way to use PageKit. - -If you want to stay inside ChatGPT, Claude, Grok or another general-purpose model, start here. - -## What you need - -Before you begin, gather: -- a short product description -- any customer language you already have -- competitors or alternatives if relevant -- rough audience ideas - -## The goal - -Start upstream, before any page copy. - -Your goal is to create these artifacts in order: -1. signal doc -2. message spine -3. first-page decision -4. page argument shape -5. proof map -6. first page draft -7. claim check (optional durability pass) - -Do not assume which page you are building until step 3. - -## Rule - -Finish each artifact before moving to the next one. -If an artifact is weak, fix the upstream source before advancing. - -## First move - -Use the signal-doc template in: -- `templates/signal-doc-template.md` - -Then follow: -- `guided-runs/01-build-signal-doc/README.md` - -## Prompt-path philosophy - -Prompts are the front door. - -The quality comes from the full artifact chain, not a single prompt. diff --git a/runs/.gitkeep b/runs/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/scripts/README.md b/scripts/README.md index f90e462..f013523 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -7,7 +7,7 @@ Tooling for the PageKit method. Every script here exits 0 on success, non-zero o | Script | Purpose | |---|---| | `new-run.sh ` | Scaffold a fully-logged run folder (`runs//`). | -| `run-check.sh ` | Validate a run against the logging tiers defined in `frameworks/run-logging.md`. | +| `run-check.sh ` | Validate a run against the logging tiers defined in `skills/pagekit/references/run-logging.md`. | | `claim-check.sh [--severity ...]` | Expand the canonical claim-check prompt for pasting. No LLM call. | | `slop-check.sh [paths...]` | Heuristic regression check for AI-slop patterns. | | `doctor.sh` | Pre-flight repo health check. Used by the SessionStart hook. | @@ -18,9 +18,9 @@ All are wrappable through `make` — see the `Makefile` at the repo root. ## new-run.sh -Scaffolds `runs//` with the full fully-logged layout: `goal.md`, `models.md`, `working-log.md`, `sources/README.md`, `prompts/01–07-*.md` (copied from canonical `prompts/` with a top-of-file note), `outputs/NN-*-output.md` placeholders, per-step artifact placeholders, `evaluation.md` and `evaluator-pass.md` templates. +Scaffolds `runs//` with the full fully-logged layout: `goal.md`, `models.md`, `working-log.md`, `sources/README.md`, `prompts/01–07-*.md` (copied from the canonical per-step prompts at `skills/pagekit-/references/prompt.md` with a top-of-file note), `outputs/NN-*-output.md` placeholders, per-step artifact placeholders, `evaluation.md` and `evaluator-pass.md` templates. -Matches the `fully_logged` tier in `pagekit.yaml`. If the manifest changes, update this script. +Matches the `fully_logged` tier in `skills/pagekit/references/run-logging.md`. If that tier changes, update this script. ## run-check.sh @@ -30,18 +30,18 @@ Exit 0 on fully-logged or summary-logged; exit 1 on artifact-only or incomplete. ## claim-check.sh -Template expansion only. Reads `prompts/07-claim-check.md`, substitutes `{{SEVERITY}}`, `{{DRAFT}}`, `{{PROOF_MAP}}`, writes to stdout. Paste the result into the model of your choice. Save the model's output as `claim-check.md` and the corrected draft as `first-page-draft-corrected.md` inside the run folder. +Template expansion only. Reads `skills/pagekit-claim-check/references/prompt.md`, substitutes `{{SEVERITY}}`, `{{DRAFT}}`, `{{PROOF_MAP}}`, writes to stdout. Paste the result into the model of your choice. Save the model's output as `claim-check.md` and the corrected draft as `first-page-draft-corrected.md` inside the run folder. ## doctor.sh -Verifies every file and directory referenced by `pagekit.yaml` exists; every script is executable; the slop-check runs clean against the tracked de-slopped drafts. Called by the SessionStart hook in `.claude/settings.json`. +Verifies the plugin layout: the top-level `skills/`, `agents/`, `.claude-plugin/` manifests, bundled references, scripts, and SessionStart hook. Runs the slop-check against tracked draft files. Called by the SessionStart hook in `.claude/settings.json`. ## slop-check.sh A heuristic grep-level regression check for AI-slop patterns in PageKit drafts. ### What it checks -It covers the mechanically detectable subset of `frameworks/anti-slop.md`: +It covers the mechanically detectable subset of `skills/pagekit/references/anti-slop.md`: - `not-x-not-y-heading` — two consecutive markdown headings that both begin with "Not " - `not-x-not-y-sentence` — a "Not X. Not Y." sentence pair on one line @@ -66,7 +66,7 @@ The semantic patterns: editorial voice narrating brand restraint, unsourced quan scripts/slop-check.sh # Check specific files or directories -scripts/slop-check.sh runs/vegan-dog-food-verdel/first-page-draft-corrected.md +scripts/slop-check.sh examples/vegan-dog-food-verdel/first-page-draft-corrected.md scripts/slop-check.sh runs/ ``` @@ -82,7 +82,7 @@ Exit code is 1 if any pattern fires, 0 if the scan is clean. You can wire this i ### Relation to the rest of PageKit -The script is a cheap pre-filter. It catches the mechanical tells so the claim-check step can focus on the harder semantic issues. See `frameworks/claim-checking.md` for the full claim-check method. See `frameworks/anti-slop.md` for the authoritative list of patterns. +The script is a cheap pre-filter. It catches the mechanical tells so the claim-check step can focus on the harder semantic issues. See `skills/pagekit-claim-check/references/framework.md` for the full claim-check method. See `skills/pagekit/references/anti-slop.md` for the authoritative list of patterns. If the script fires on a draft, the fix is usually: 1. Rewrite the flagged line. diff --git a/scripts/claim-check.sh b/scripts/claim-check.sh index 4ad24fe..cf90b0a 100755 --- a/scripts/claim-check.sh +++ b/scripts/claim-check.sh @@ -4,8 +4,9 @@ # Usage: # scripts/claim-check.sh [--severity hard|normal|light] # -# Reads prompts/07-claim-check.md, substitutes {{SEVERITY}}, {{DRAFT}}, -# and {{PROOF_MAP}}, prints the expanded prompt to stdout. +# Reads skills/pagekit-claim-check/references/prompt.md, substitutes +# {{SEVERITY}}, {{DRAFT}}, and {{PROOF_MAP}}, prints the expanded prompt +# to stdout. # # This script does not call an LLM. Paste the output into the model of # your choice, then save the model's response as claim-check.md and the @@ -54,8 +55,11 @@ esac [ -f "$PROOF" ] || { echo "error: proof map not found: $PROOF" >&2; exit 2; } REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)" -PROMPT_FILE="$REPO_ROOT/prompts/07-claim-check.md" -[ -f "$PROMPT_FILE" ] || { echo "error: prompts/07-claim-check.md not found" >&2; exit 1; } +PROMPT_FILE="$REPO_ROOT/skills/pagekit-claim-check/references/prompt.md" +if [ ! -f "$PROMPT_FILE" ]; then + echo "error: canonical claim-check prompt not found at $PROMPT_FILE" >&2 + exit 1 +fi # Extract the body of the ```text fenced block from the prompt file. # The canonical prompt has exactly one ```text block. diff --git a/scripts/doctor.sh b/scripts/doctor.sh index 2ad8a0c..418708d 100755 --- a/scripts/doctor.sh +++ b/scripts/doctor.sh @@ -8,8 +8,8 @@ # 0 healthy # 1 at least one check failed # -# This script is conservative: it reports what exists vs what is -# expected per pagekit.yaml. It does not fix anything. +# This script is conservative: it reports what exists vs what the plugin +# layout expects. It does not fix anything. set -u @@ -56,76 +56,59 @@ check_exec() { echo "PageKit doctor — $REPO_ROOT" echo -echo "Manifest and agent contract:" -check_file "pagekit.yaml" +echo "Agent contract:" check_file "AGENTS.md" check_file "CLAUDE.md" -check_file "START-HERE.md" check_file "README.md" echo -echo "Frameworks:" -for f in anti-slop claim-checking first-page-decision message-spine page-argument-shape proof-map run-logging signal-doc; do - check_file "frameworks/$f.md" -done +echo "Scripts:" +check_exec "scripts/new-run.sh" +check_exec "scripts/new-source-brief.sh" +check_exec "scripts/run-check.sh" +check_exec "scripts/claim-check.sh" +check_exec "scripts/slop-check.sh" +check_exec "scripts/doctor.sh" +check_file "scripts/README.md" echo -echo "Templates:" -for t in claim-check-template first-page-decision-template message-spine-template output-judgment-template page-argument-shape-template proof-map-template signal-doc-template wedge-definition-template; do - check_file "templates/$t.md" -done +echo "Claude Code hook:" +check_file ".claude/settings.json" echo -echo "Canonical prompts:" -for p in 01-signal-doc 02-message-spine 03-first-page-decision 04-page-argument-shape 05-proof-map 06-first-page-draft 07-claim-check; do - check_file "prompts/$p.md" -done -check_file "prompts/README.md" +echo "Plugin manifest:" +check_file ".claude-plugin/plugin.json" +check_file ".claude-plugin/marketplace.json" echo -echo "Guided runs:" -for g in 01-build-signal-doc 02-reduce-to-message-spine 03-decide-first-page 04-design-page-argument 05-map-proof-to-pages 06-draft-first-page 07-claim-check; do - check_file "guided-runs/$g/README.md" +echo "Skills (top-level plugin layout):" +check_file "skills/pagekit/SKILL.md" +for s in signal-doc message-spine first-page-decision page-argument-shape proof-map first-page-draft claim-check evaluator-pass new-run run-check slop-check; do + check_file "skills/pagekit-$s/SKILL.md" done echo -echo "Guides and quickstarts:" -check_file "guides/README.md" -for g in chatgpt claude perplexity grok openai; do - check_file "guides/$g-prompt-path.md" -done -check_file "quickstart/README.md" -check_file "quickstart/start-with-prompts.md" -for q in chatgpt claude perplexity grok openai; do - check_file "quickstart/$q.md" +echo "Shared orchestrator references:" +for r in anti-slop run-logging method; do + check_file "skills/pagekit/references/$r.md" done echo -echo "Agentic tier:" -check_file "agentic/README.md" -check_file "agentic/claude-code-agentic-path.md" -check_file "agentic/codex-agentic-path.md" -check_file "agentic/claude-cowork-agentic-path.md" -echo - -echo "Scripts:" -check_exec "scripts/new-run.sh" -check_exec "scripts/new-source-brief.sh" -check_exec "scripts/run-check.sh" -check_exec "scripts/claim-check.sh" -check_exec "scripts/slop-check.sh" -check_exec "scripts/doctor.sh" -check_file "scripts/README.md" +echo "Per-skill references (framework, template, prompt):" +# first-page-draft has its own prompt but inherits framework/template from +# upstream page-argument-shape and proof-map; it is intentionally lighter. +for s in signal-doc message-spine first-page-decision page-argument-shape proof-map claim-check; do + check_file "skills/pagekit-$s/references/framework.md" + check_file "skills/pagekit-$s/references/template.md" + check_file "skills/pagekit-$s/references/prompt.md" +done +check_file "skills/pagekit-first-page-draft/references/prompt.md" +check_file "skills/pagekit-signal-doc/references/wedge-definition-template.md" echo -echo "Claude Code bundle:" -check_file ".claude/skills/pagekit/SKILL.md" -for s in signal-doc message-spine first-page-decision page-argument-shape proof-map first-page-draft claim-check evaluator-pass new-run run-check slop-check; do - check_file ".claude/skills/pagekit-$s/SKILL.md" -done -check_file ".claude/agents/pagekit-claim-checker.md" -check_file ".claude/agents/pagekit-evaluator-pass.md" -check_file ".claude/settings.json" +echo "Subagents:" +check_file "agents/pagekit-claim-checker.md" +check_file "agents/pagekit-evaluator-pass.md" echo echo "Slop regression against tracked drafts:" diff --git a/scripts/new-run.sh b/scripts/new-run.sh index c4fd7d4..a2d5374 100755 --- a/scripts/new-run.sh +++ b/scripts/new-run.sh @@ -5,11 +5,11 @@ # scripts/new-run.sh # # Creates runs// with the full fully-logged layout per -# frameworks/run-logging.md. All files start as placeholders and carry -# instructions on what to fill in. +# skills/pagekit/references/run-logging.md. All files start as placeholders +# and carry instructions on what to fill in. # -# The scaffold matches pagekit.yaml's fully_logged tier. If pagekit.yaml -# changes, update this script. +# The scaffold matches the fully_logged tier defined in run-logging.md. +# If that tier changes, update this script. set -euo pipefail @@ -39,7 +39,7 @@ cat > "$RUN_DIR/goal.md" < "$RUN_DIR/working-log.md" < @@ -137,25 +137,40 @@ Recommended for trust-heavy objects: - \`05-proof-brief.md\` - \`06-comparison-brief.md\` -For templates see \`templates/wedge-definition-template.md\` and the pattern established in \`runs/vegan-dog-food-verdel/sources/\`. +For templates see \`skills/pagekit-signal-doc/references/wedge-definition-template.md\` and the pattern established in \`examples/vegan-dog-food-verdel/sources/\`. EOF # ----- prompts/ placeholders ---------------------------------------------- # Copy the canonical prompts into the run with a note at the top. +# Canonical prompts live under skills/pagekit-/references/prompt.md. CANONICAL_PROMPTS=( - "01-signal-doc.md" - "02-message-spine.md" - "03-first-page-decision.md" - "04-page-argument-shape.md" - "05-proof-map.md" - "06-first-page-draft.md" - "07-claim-check.md" + "01-signal-doc.md:signal-doc" + "02-message-spine.md:message-spine" + "03-first-page-decision.md:first-page-decision" + "04-page-argument-shape.md:page-argument-shape" + "05-proof-map.md:proof-map" + "06-first-page-draft.md:first-page-draft" + "07-claim-check.md:claim-check" ) -for p in "${CANONICAL_PROMPTS[@]}"; do +resolve_canonical_prompt() { + local step="$1" + local src="$REPO_ROOT/skills/pagekit-$step/references/prompt.md" + if [ -f "$src" ]; then + echo "$src" + else + echo "ERROR: canonical prompt not found at $src" >&2 + exit 1 + fi +} +for entry in "${CANONICAL_PROMPTS[@]}"; do + p="${entry%%:*}" + step="${entry##*:}" dst="$RUN_DIR/prompts/$p" + src="$(resolve_canonical_prompt "$step")" cat > "$dst" < EOF - cat "$REPO_ROOT/prompts/$p" >> "$dst" + cat "$src" >> "$dst" done # ----- outputs/ placeholders ---------------------------------------------- @@ -185,43 +200,43 @@ done cat > "$RUN_DIR/signal-doc.md" < "$RUN_DIR/message-spine.md" < "$RUN_DIR/first-page-decision.md" < "$RUN_DIR/page-argument-shape.md" < "$RUN_DIR/proof-map.md" < "$RUN_DIR/first-page-draft.md" < "$RUN_DIR/claim-check.md" < "$RUN_DIR/evaluation.md" < "$RUN_DIR/evaluator-pass.md" < [ ...] # # If no argument is given, runs against homepage-draft.md / -# first-page-draft.md / first-page-draft-corrected.md under runs/. +# first-page-draft.md / first-page-draft-corrected.md under runs/ and +# examples/. # # Exit code: # 0 no hits @@ -246,11 +247,16 @@ scan_target() { main() { if [ "$#" -eq 0 ]; then - find runs -type f \( -name 'homepage-draft.md' -o -name 'first-page-draft.md' -o -name 'first-page-draft-corrected.md' \) \ - ! -name '*-original.md' \ - -print0 | while IFS= read -r -d '' f; do - scan_file "$f" - done + local scan_roots=() + [ -d runs ] && scan_roots+=(runs) + [ -d examples ] && scan_roots+=(examples) + if [ "${#scan_roots[@]}" -gt 0 ]; then + find "${scan_roots[@]}" -type f \( -name 'homepage-draft.md' -o -name 'first-page-draft.md' -o -name 'first-page-draft-corrected.md' \) \ + ! -name '*-original.md' \ + -print0 | while IFS= read -r -d '' f; do + scan_file "$f" + done + fi else for t in "$@"; do scan_target "$t" diff --git a/.claude/skills/pagekit-claim-check/SKILL.md b/skills/pagekit-claim-check/SKILL.md similarity index 80% rename from .claude/skills/pagekit-claim-check/SKILL.md rename to skills/pagekit-claim-check/SKILL.md index 4bc727b..17fdc0d 100644 --- a/.claude/skills/pagekit-claim-check/SKILL.md +++ b/skills/pagekit-claim-check/SKILL.md @@ -8,10 +8,10 @@ description: Run a skeptical claim-check pass on a PageKit first-page draft, at You are running the optional durability pass on a first-page draft. ## Read first -- `prompts/07-claim-check.md` -- `frameworks/claim-checking.md` -- `frameworks/anti-slop.md` -- `templates/claim-check-template.md` +- `./references/prompt.md` +- `./references/framework.md` — claim-check flag types, severity calibration, principle +- `./references/template.md` +- `../pagekit/references/anti-slop.md` — the slop pattern catalog ## Inputs - `runs//first-page-draft.md` @@ -21,7 +21,7 @@ You are running the optional durability pass on a first-page draft. ## Procedure ### Option A — delegate to the subagent (preferred) -Invoke the `pagekit-claim-checker` subagent (`.claude/agents/pagekit-claim-checker.md`). Pass: +Invoke the `pagekit-claim-checker` subagent (`agents/pagekit-claim-checker.md`). Pass: - the path to the draft - the path to the proof map - the severity @@ -36,13 +36,13 @@ Use `scripts/claim-check.sh --severity ` to expand ## After the pass 1. Save the audit and corrected draft. 2. Update `working-log.md` with the severity used, count of flags by type, and any recurring patterns. -3. **If the same slop pattern showed up more than once,** add it to `frameworks/anti-slop.md` (or strengthen the existing entry) and to `templates/page-argument-shape-template.md`'s drafting-constraints list. The framework absorbs what the claim-check kept catching. +3. **If the same slop pattern showed up more than once,** add it to `../pagekit/references/anti-slop.md` (or strengthen the existing entry) and to `../pagekit-page-argument-shape/references/template.md`'s drafting-constraints list. The framework absorbs what the claim-check kept catching. ## Quality gate A strong claim-check pass: - names specific lines, not general impressions - separates claim types (overclaim / vague / unsupported / outrun proof map / editorial voice / unsourced quantitative / clinical drift / ai-slop tell) -- proposes replacements that are sharper and more accurate than the originals — not simply softer +- proposes replacements that are sharper and more accurate than the originals, not simply softer - ends with a recurring-patterns summary so upstream constraints can absorb them ## Next diff --git a/frameworks/claim-checking.md b/skills/pagekit-claim-check/references/framework.md similarity index 86% rename from frameworks/claim-checking.md rename to skills/pagekit-claim-check/references/framework.md index 2ddc515..1079e46 100644 --- a/frameworks/claim-checking.md +++ b/skills/pagekit-claim-check/references/framework.md @@ -29,7 +29,7 @@ Finding claims that: - **editorial voice** — the brand narrates its own restraint, virtue or honesty instead of demonstrating it. A show-the-work page earns trust by showing the work, not by announcing that it is showing the work. - **unsourced quantitative modifier** — `most`, `usually`, `typically`, `often`, `many` without a source to anchor the quantity. At hard severity, any unsourced quantity is a flag. - **clinical or regulatory drift** — phrasing that reads as clinical, nutritional, legal or regulatory advice when the briefs do not support it. -- **ai-slop tell** — the line carries one of the patterns in `frameworks/anti-slop.md` (negation stacking, rule-of-three clustering, anaphora, em-dash stacking, intensifier vocabulary, marketing-punchy ender, quoted antithesis, copula avoidance, signposting, filler, significance inflation). Slop lowers reader trust in every other claim on the page, which makes it a proof issue, not only a voice issue. +- **ai-slop tell** — the line carries one of the patterns in `../../pagekit/references/anti-slop.md` (negation stacking, rule-of-three clustering, anaphora, em-dash stacking, intensifier vocabulary, marketing-punchy ender, quoted antithesis, copula avoidance, signposting, filler, significance inflation). Slop lowers reader trust in every other claim on the page, which makes it a proof issue, not only a voice issue. ## Severity calibration @@ -59,7 +59,7 @@ When claim checking surfaces a real gap, the fix usually lives upstream in the p ## Upstream absorption -If a pattern shows up in claim checking on every run (for example, editorial voice or rule-of-three cadence on every page), the fix belongs in the page-argument-shape drafting constraints and in `frameworks/anti-slop.md`, not in the claim-check step. Claim checking is a safety net. It should not be the primary place a category of problems gets caught. +If a pattern shows up in claim checking on every run (for example, editorial voice or rule-of-three cadence on every page), the fix belongs in the page-argument-shape drafting constraints and in `../../pagekit/references/anti-slop.md`, not in the claim-check step. Claim checking is a safety net. It should not be the primary place a category of problems gets caught. ## Relation to the slop-check script diff --git a/skills/pagekit-claim-check/references/prompt.md b/skills/pagekit-claim-check/references/prompt.md new file mode 100644 index 0000000..cacfd00 --- /dev/null +++ b/skills/pagekit-claim-check/references/prompt.md @@ -0,0 +1,75 @@ +--- +step: "07" +name: claim-check +title: Claim Check (optional durability pass) +required: false +inputs: + - first-page-draft.md + - proof-map.md +outputs: + - claim-check.md + - first-page-draft-corrected.md +framework: ./framework.md +template: ./template.md +severity_options: [light, normal, hard] +default_severity: normal +notes: | + Severity is a required argument. Record the choice and why. + scripts/claim-check.sh expands this prompt with a draft, a proof map + and a severity setting. +--- + +# Prompt: 07 — Claim Check + +## When to use +After the first page draft exists. Before treating the draft as publishable. + +## Severity +Record the severity chosen and why. + +- **light** — flag clear overclaims, unsupported claims and the strongest slop tells only. +- **normal** — flag the full list below, tolerate mild editorial voice and mild unsourced modifiers where they sit inside common usage. +- **hard** — flag any unsourced modifier, any editorial voice, any clinical drift, any external-credential description beyond what the briefs support, any slop pattern however small. + +## What good output looks like +- names specific lines, not general impressions +- separates claim types by kind (overclaim / vague / unsupported / outrun / editorial voice / unsourced quantitative / clinical drift / ai-slop tell) +- proposes replacements that are sharper and more accurate than the originals +- ends with a list of recurring patterns so upstream constraints can absorb them + +## Prompt + +```text +Review the draft below as a skeptical claim check at severity: {{SEVERITY}}. + +For every claim that sounds stronger than the product or the proof map supports, flag it. +Also flag any line that carries an AI-slop pattern: Not-X-Not-Y stacking, rule-of-three cadence, sentence-start anaphora, editorial voice narrating brand restraint, em-dash stacking, intensifier vocabulary (actually / testament / landscape / showcasing / truly / genuinely), marketing-punchy enders, scare-quoted antithesis, copula-avoidance (serves as / boasts / features / showcases / delivers / empowers), signposting (let's dive in / here's the thing / that's the deal), filler (in order to / due to the fact that), significance inflation (pivotal moment / critical juncture). + +For each flagged claim, give: +1. the exact line +2. the type (overclaim / vague / unsupported / outruns proof map / editorial voice / unsourced quantitative modifier / clinical or regulatory drift / ai-slop tell) +3. why it is weak +4. a correction, labeled with one of these dispositions: + - **rewrite** — a sharper, more accurate replacement that lands inside the proof map and reads cleaner + - **remove (wrong)** — cut the line; the claim is not supportable at any severity + - **remove pending verification** — cut the line from the corrected draft AND flag it in the audit as "potentially restorable if is confirmed in the briefs." A dropped claim and a disqualified claim are different things; the audit must preserve the distinction so a reviewer can decide whether to restore on verification. + +Do not reward defensiveness. +A corrected claim should be more precise, not louder. + +The corrected draft must be clean on its own terms: no inline annotation markers (`*[Rewritten: ...]*`, `*[Was: ...]*`) in body copy, and no new em-dashes introduced by the rewrites. The audit is where rewrite provenance lives; the corrected draft is publish-ready copy. + +At the end, list any slop pattern that showed up more than once so upstream constraints (../../pagekit/references/anti-slop.md or page-argument-shape drafting constraints) can absorb it. + +Then produce a corrected draft that resolves every flagged claim. + +Draft: +{{DRAFT}} + +Proof map: +{{PROOF_MAP}} +``` + +## Expansion + +`scripts/claim-check.sh [--severity hard|normal|light]` substitutes `{{SEVERITY}}`, `{{DRAFT}}` and `{{PROOF_MAP}}` and writes the expanded prompt to stdout. diff --git a/templates/claim-check-template.md b/skills/pagekit-claim-check/references/template.md similarity index 89% rename from templates/claim-check-template.md rename to skills/pagekit-claim-check/references/template.md index cd5aa35..ff25fae 100644 --- a/templates/claim-check-template.md +++ b/skills/pagekit-claim-check/references/template.md @@ -23,7 +23,7 @@ Quote the exact line from the draft. - editorial voice (narrating brand restraint instead of showing the work) - unsourced quantitative modifier (`most`, `usually`, `typically`, `often`, `many`) - clinical or regulatory drift -- ai-slop tell (negation stacking, rule-of-three, anaphora, em-dash stacking, intensifier vocabulary, marketing-punchy ender, quoted antithesis, copula avoidance, signposting, filler, significance inflation — see `frameworks/anti-slop.md`) +- ai-slop tell (negation stacking, rule-of-three, anaphora, em-dash stacking, intensifier vocabulary, marketing-punchy ender, quoted antithesis, copula avoidance, signposting, filler, significance inflation — see `../../pagekit/references/anti-slop.md`) ### Why this is weak What specifically makes this claim brittle, misleading, undefended, or machine-cadenced? @@ -51,10 +51,10 @@ Do NOT include `*[Rewritten: ...]*` or any other inline annotation markers in th - ### Recurring patterns on this draft -Note any pattern that showed up more than once (repeated editorial voice, repeated unsourced modifiers, repeated slop tells of the same type). Recurring patterns are signals that the argument-shape drafting constraints or `frameworks/anti-slop.md` may need to absorb the pattern upstream, not that claim checking should keep catching it. +Note any pattern that showed up more than once (repeated editorial voice, repeated unsourced modifiers, repeated slop tells of the same type). Recurring patterns are signals that the argument-shape drafting constraints or `../../pagekit/references/anti-slop.md` may need to absorb the pattern upstream, not that claim checking should keep catching it. ### Recurring slop patterns on this draft -List the specific slop patterns found more than once, by name from `frameworks/anti-slop.md`. +List the specific slop patterns found more than once, by name from `../../pagekit/references/anti-slop.md`. ### Where proof is the real gap - diff --git a/.claude/skills/pagekit-evaluator-pass/SKILL.md b/skills/pagekit-evaluator-pass/SKILL.md similarity index 88% rename from .claude/skills/pagekit-evaluator-pass/SKILL.md rename to skills/pagekit-evaluator-pass/SKILL.md index 860f4ac..b9e1654 100644 --- a/.claude/skills/pagekit-evaluator-pass/SKILL.md +++ b/skills/pagekit-evaluator-pass/SKILL.md @@ -11,11 +11,11 @@ You are invoking the adversarial evaluator pass on a completed run. - After the run's `evaluation.md` is written. - Before declaring the run fully-logged (the fully-logged tier requires `evaluator-pass.md`). -- When a reviewer asks "is this run actually as good as the evaluation says?" +- When a reviewer asks "is this run as good as the evaluation says?" ## Read first -- `frameworks/run-logging.md` — where the evaluator pass fits in the run-logging tier -- `.claude/agents/pagekit-evaluator-pass.md` — the subagent you will delegate to +- `../pagekit/references/run-logging.md` — where the evaluator pass fits in the run-logging tier +- `agents/pagekit-evaluator-pass.md` — the subagent you will delegate to ## Inputs - path to the run folder (e.g., `runs/kind-bowl-real/`) diff --git a/.claude/skills/pagekit-first-page-decision/SKILL.md b/skills/pagekit-first-page-decision/SKILL.md similarity index 60% rename from .claude/skills/pagekit-first-page-decision/SKILL.md rename to skills/pagekit-first-page-decision/SKILL.md index 465404c..c2b9dd1 100644 --- a/.claude/skills/pagekit-first-page-decision/SKILL.md +++ b/skills/pagekit-first-page-decision/SKILL.md @@ -1,6 +1,6 @@ --- name: pagekit-first-page-decision -description: Decide which page should exist first for the object — without defaulting to homepage. Step 03 of the PageKit method. Use when the user has a signal doc + message spine and needs to choose the first page, or asks "should this be a homepage?" or "what page should we build first?" +description: Decide which page should exist first for the object, without defaulting to homepage. Step 03 of the PageKit method. Use when the user has a signal doc + message spine and needs to choose the first page, or asks "should this be a homepage?" or "what page should we build first?" --- # PageKit step 03 — First-Page Decision @@ -8,9 +8,9 @@ description: Decide which page should exist first for the object — without def You are running step 03 of the PageKit method. **This step is the one that stops the method from quietly defaulting to a homepage.** ## Read first -- `prompts/03-first-page-decision.md` -- `frameworks/first-page-decision.md` -- `templates/first-page-decision-template.md` +- `./references/prompt.md` +- `./references/framework.md` — the full decision framework +- `./references/template.md` ## Inputs - `runs//signal-doc.md` @@ -18,7 +18,7 @@ You are running step 03 of the PageKit method. **This step is the one that stops - For trust-heavy objects, also: `runs//sources/04-mechanism-brief.md`, `05-proof-brief.md`, `06-comparison-brief.md` (if they exist; absence is itself a signal that the decision will be weaker). ## Procedure -1. Load `prompts/03-first-page-decision.md`. +1. Load `./references/prompt.md`. 2. Substitute the message spine and the relevant source briefs. 3. Save the substituted prompt to `runs//prompts/03-first-page-decision.md`. 4. Prompt the model. @@ -36,12 +36,12 @@ The decision MUST list at least three candidate first pages. Minimum candidates Candidates must be peer first-page alternatives (same intent-commitment level as a homepage), NOT later-funnel pages. A pricing page, features page, docs page, integrations page, or comparison page is NOT a first-page alternative. If the rejected candidates are downstream pages, the step has not been done. -**For each candidate — the chosen one and every rejected one — write one paragraph stating the case FOR the candidate BEFORE any reason to reject.** If you cannot write a credible case for a candidate, you have not actually considered it. Either think harder about what would make that candidate strong for this object, or drop it and replace it with one you can argue for. +**For each candidate, the chosen one and every rejected one, write one paragraph stating the case FOR the candidate BEFORE any reason to reject.** If you cannot write a credible case for a candidate, you have not really considered it. Either think harder about what would make that candidate strong for this object, or drop it and replace it with one you can argue for. If any candidate is dismissed in one sentence, the step has not been done. ## The Verdel pattern -`runs/vegan-dog-food-verdel/first-page-decision.md` is the working example. Four labeled candidates (A: homepage, B: trust/safety landing, C: allergy landing, D: nutrition deep-dive), a paragraph-long case for each, a deliberate non-homepage choice with specific reasoning against the other three, plus a confidence basis. If the output you are producing does not match that shape, go back and rework it. +The canonical worked example is `runs/vegan-dog-food-verdel/first-page-decision.md`. Four labeled candidates (A: homepage, B: trust/safety landing, C: allergy landing, D: nutrition deep-dive), a paragraph-long case for each, a deliberate non-homepage choice with specific reasoning against the other three, plus a confidence basis. If the output you are producing does not match that shape, go back and rework it. ## Quality gate A strong first-page decision: @@ -51,10 +51,10 @@ A strong first-page decision: - the object drove the choice, not the category default ## Decision check -If the chosen page is "homepage," the rationale must explain why homepage actually earns it for *this* object — not simply because that is what people usually build first. If you cannot articulate the why, the message spine is probably too thin; go back to step 02. +If the chosen page is "homepage," the rationale must explain why homepage earns it for *this* object, not simply because that is what people usually build first. If you cannot articulate the why, the message spine is probably too thin; go back to step 02. ## When to escalate to the user -- The decision is genuinely close between two candidates: surface both, ask for input. +- The decision is close between two candidates: surface both, ask for input. - Mechanism / proof / comparison briefs are missing for a trust-heavy object: ask for them before deciding. ## Next diff --git a/frameworks/first-page-decision.md b/skills/pagekit-first-page-decision/references/framework.md similarity index 96% rename from frameworks/first-page-decision.md rename to skills/pagekit-first-page-decision/references/framework.md index f0af05a..69c3430 100644 --- a/frameworks/first-page-decision.md +++ b/skills/pagekit-first-page-decision/references/framework.md @@ -81,6 +81,6 @@ If the decision cannot explain why this page beats the obvious default, the sign - upstream: signal doc, message spine, source briefs - downstream: page argument shape, proof map, first page draft -The page argument shape step inherits this decision. That step is also where the anti-slop drafting constraints get attached (see `frameworks/anti-slop.md`). A wrong first-page decision at this step propagates through every downstream step including the slop-prevention layer. +The page argument shape step inherits this decision. That step is also where the anti-slop drafting constraints get attached (see `../../pagekit/references/anti-slop.md`). A wrong first-page decision at this step propagates through every downstream step including the slop-prevention layer. If the first page is wrong, every downstream step drifts. diff --git a/skills/pagekit-first-page-decision/references/prompt.md b/skills/pagekit-first-page-decision/references/prompt.md new file mode 100644 index 0000000..2e5a19c --- /dev/null +++ b/skills/pagekit-first-page-decision/references/prompt.md @@ -0,0 +1,71 @@ +--- +step: "03" +name: first-page-decision +title: Decide the First Page +inputs: + - signal-doc.md + - message-spine.md +outputs: + - first-page-decision.md +framework: ./framework.md +template: ./template.md +notes: | + This step exists to stop the method from quietly defaulting to a + homepage. The decision must list candidates considered and rejected. +--- + +# Prompt: 03 — First-Page Decision + +## When to use +After the message spine has reduced the signal into a small set of truths. Before any argument-shape or proof work. + +## What good output looks like +- chooses the first page on purpose +- explains why this page beats the obvious default +- makes the trust burden and proof burden explicit +- lists candidates at the same intent-commitment level as a homepage (not downstream pages) +- states a paragraph-long case FOR each candidate before rejecting any of them +- names the confidence basis (data / signal / hypothesis) +- the object (not the category) drove the choice + +## The Verdel pattern (reference) +`runs/vegan-dog-food-verdel/first-page-decision.md` is the working example of this step done well. Four labeled candidates, a paragraph of affirmative case for each, a deliberate non-homepage choice (a trust/safety landing page) with specific reasoning against the other three. A new step 03 output that does not match that shape is not meeting the step's quality bar. + +## Prompt + +```text +Using the message spine below, decide what page should exist first. + +Do not assume homepage by default. + +Consider at least three candidate first pages. The candidates must be peer first-page alternatives at the same intent-commitment level as a homepage — not later-funnel pages. A pricing page, a features page, a docs page, an integrations page are NOT first-page alternatives. Those are downstream pages that assume someone has already decided to evaluate the product. + +First-page alternatives are pages at the same level as a homepage: audience-specific landing pages, trust-and-safety landing pages, mechanism or ingredient-detail pages, category explainers, founder or brand-story pages, use-case or specific-scenario pages. + +For a trust-heavy object, the minimum candidates to consider are: +- homepage +- category-explainer page +- mechanism or ingredient-detail page +- founder or brand-story page +- use-case or specific-scenario page + +For each candidate (the chosen one and every rejected one), write ONE PARAGRAPH stating the case FOR the candidate BEFORE any reason to reject. If you cannot write a credible case for the candidate, you have not actually considered it — go back and think about what would make that candidate strong for this object, or drop it and replace it with one you can argue for. + +Define: +1. candidates considered (case FOR each, one paragraph each — including the chosen one) +2. the best first-page candidate (with the paragraph from above, plus the decision) +3. why this page first (beyond the case FOR — why it beats the others for THIS object) +4. candidates rejected, with the specific reason each is rejected for THIS object +5. the page's job +6. visitor state on arrival +7. main trust burden +8. main proof burden +9. what this decision rules out for now +10. confidence basis (data / signal / hypothesis) — state which, and why + +Message spine: +[PASTE HERE] +``` + +## If the decision feels forced +The signal doc or the message spine is probably too thin. Do not advance just to keep the chain moving. Go back upstream and strengthen what is missing before deciding. diff --git a/templates/first-page-decision-template.md b/skills/pagekit-first-page-decision/references/template.md similarity index 100% rename from templates/first-page-decision-template.md rename to skills/pagekit-first-page-decision/references/template.md diff --git a/.claude/skills/pagekit-first-page-draft/SKILL.md b/skills/pagekit-first-page-draft/SKILL.md similarity index 82% rename from .claude/skills/pagekit-first-page-draft/SKILL.md rename to skills/pagekit-first-page-draft/SKILL.md index 0be184e..78da801 100644 --- a/.claude/skills/pagekit-first-page-draft/SKILL.md +++ b/skills/pagekit-first-page-draft/SKILL.md @@ -5,12 +5,12 @@ description: Draft the first page from the full PageKit chain. Step 06 of the Pa # PageKit step 06 — First Page Draft -You are running step 06 of the PageKit method. **This is where slop prevention bites.** The drafting constraints in `frameworks/anti-slop.md` are not optional. +You are running step 06 of the PageKit method. **This is where slop prevention bites.** The drafting constraints in `../pagekit/references/anti-slop.md` are not optional. ## Read first -- `prompts/06-first-page-draft.md` -- `frameworks/page-argument-shape.md` (drafting constraints live here) -- `frameworks/anti-slop.md` (the patterns to avoid) +- `./references/prompt.md` +- `../pagekit-page-argument-shape/references/framework.md` (drafting constraints live here) +- `../pagekit/references/anti-slop.md` (the patterns to avoid) ## Inputs All five upstream artifacts: @@ -21,7 +21,7 @@ All five upstream artifacts: - `runs//proof-map.md` ## Procedure -1. Load `prompts/06-first-page-draft.md`. Note the embedded anti-slop constraints; do not strip them when substituting inputs. +1. Load `./references/prompt.md`. Note the embedded anti-slop constraints; do not strip them when substituting inputs. 2. Substitute the five artifacts above. 3. Save the substituted prompt to `runs//prompts/06-first-page-draft.md`. 4. Prompt the model. @@ -43,7 +43,7 @@ A strong draft: - uses `*[verification flag: ...]*` for any product-specific claim not verified against briefs - passes `scripts/slop-check.sh` clean before being handed to step 07 -If the draft is weak: stop, ask what upstream artifact is too thin. Rarely fix at the draft level — fix at the source. +If the draft is weak: stop, ask what upstream artifact is too thin. Rarely fix at the draft level, fix at the source. ## Next **The draft is not the deliverable. The logged run is.** After the draft is clean, do not stop. Continue the chain: @@ -52,7 +52,7 @@ If the draft is weak: stop, ask what upstream artifact is too thin. Rarely fix a 2. Invoke **`pagekit-claim-check`** (step 07) at a severity you choose and log. This produces `claim-check.md` and, if any line was rewritten, `first-page-draft-corrected.md`. 3. Write `evaluation.md` — the run's own honest read of what worked and what stayed thin. 4. Invoke **`pagekit-evaluator-pass`** to produce `evaluator-pass.md` — the adversarial second read. -5. Fill in `working-log.md` across every step (not the scaffold `*[Fill in]*` placeholders). +5. Fill in `working-log.md` across every step (replace all scaffold `*[Fill in]*` placeholders). 6. Invoke **`pagekit-run-check`** — it must return `tier: FULLY LOGGED` or `tier: PUBLISHABLE`. Only once run-check reports FULLY LOGGED (or PUBLISHABLE) is the run done. Stopping at this step leaves the run at ARTIFACT-ONLY, which does not count. diff --git a/skills/pagekit-first-page-draft/references/prompt.md b/skills/pagekit-first-page-draft/references/prompt.md new file mode 100644 index 0000000..489fb5c --- /dev/null +++ b/skills/pagekit-first-page-draft/references/prompt.md @@ -0,0 +1,68 @@ +--- +step: "06" +name: first-page-draft +title: Draft the First Page +inputs: + - signal-doc.md + - message-spine.md + - first-page-decision.md + - page-argument-shape.md + - proof-map.md +outputs: + - first-page-draft.md +framework: ../pagekit-page-argument-shape/references/framework.md +template: ../pagekit-page-argument-shape/references/template.md +notes: | + The draft must respect the anti-slop constraints in + ../pagekit/references/anti-slop.md. Unverified product claims get inline + *[verification flag: ...]* markers. +--- + +# Prompt: 06 — First Page Draft + +## When to use +After steps 01 through 05 are done and the proof map is tight. + +## What good output looks like +- inherits structure from the argument shape +- stays inside the proof map +- reads as written by a person with a voice, not by a machine +- uses `*[verification flag: ...]*` for any product-specific claim not verified against briefs or ground truth + +## Prompt + +```text +Using the signal doc, message spine, first-page decision, page argument shape and proof map below, draft the page. + +Do not add sections that were not earned by the argument-shape step. +Let the structure follow the approved page shape. + +Proof and scope constraints: +- clarity over hype +- no fake proof +- no inflated mechanism claims +- avoid generic category language + +Anti-slop constraints (hard rules; see ../pagekit/references/anti-slop.md): +- no "Not X. Not Y." heading or sentence pairs +- no "Not-X-but-Y" or "X-not-Y" rhetorical pivots unless they carry specific content the affirmation cannot +- no three parallel short sentences used for cadence (rule-of-three clustering) +- no sentence-start anaphora across three or more consecutive sentences +- no editorial voice narrating brand restraint, virtue or honesty +- no em-dashes in body copy (use a colon, comma, or parentheses instead) +- no "actually", "additionally", "testament", "landscape", "showcasing", "genuinely", "truly" as intensifiers +- no marketing-punchy one-liners as section enders +- no scare-quoted antithesis +- no "serves as / boasts / features / showcases / delivers / empowers" copula-avoidance +- no signposting ("let's dive in", "here's the thing", "that's the deal") +- no filler ("in order to", "due to the fact that") +- no significance inflation ("pivotal moment", "critical juncture") + +When a product-specific claim has not been verified against the briefs, mark it inline with *[verification flag: ...]*. + +Artifacts: +[PASTE HERE] +``` + +## If the draft is weak +Before heavy line editing, ask what source artifact is still too weak. Common fixes: wedge definition, mechanism brief, proof brief, comparison brief. Line edits rarely rescue a draft whose upstream materials are thin. diff --git a/.claude/skills/pagekit-message-spine/SKILL.md b/skills/pagekit-message-spine/SKILL.md similarity index 84% rename from .claude/skills/pagekit-message-spine/SKILL.md rename to skills/pagekit-message-spine/SKILL.md index cc7b1be..492b1e8 100644 --- a/.claude/skills/pagekit-message-spine/SKILL.md +++ b/skills/pagekit-message-spine/SKILL.md @@ -8,15 +8,15 @@ description: Reduce a PageKit signal doc into a message spine. Step 02 of the Pa You are running step 02 of the PageKit method. ## Read first -- `prompts/02-message-spine.md` -- `frameworks/message-spine.md` -- `templates/message-spine-template.md` +- `./references/prompt.md` +- `./references/framework.md` — what makes a strong message spine +- `./references/template.md` ## Inputs - `runs//signal-doc.md` from step 01. ## Procedure -1. Load `prompts/02-message-spine.md`. +1. Load `./references/prompt.md`. 2. Substitute the signal-doc contents. 3. Save the substituted prompt to `runs//prompts/02-message-spine.md`. 4. Prompt the model. @@ -34,7 +34,7 @@ A strong message spine: If the spine sounds like the signal doc rephrased, the reduction did not happen. Push back, or strengthen source briefs and rerun step 01 first. ## Anti-slop -Watch for "comprehensive solution," "powerful platform," and other category-default phrases sneaking into the spine. The spine should be in the product's own voice as much as possible. +Watch for "comprehensive solution," "powerful platform," and other category-default phrases sneaking into the spine. The spine should be in the product's own voice as much as possible. See `../pagekit/references/anti-slop.md`. ## Next After the spine is in place, invoke **`pagekit-first-page-decision`** (step 03). Do not stop here. diff --git a/frameworks/message-spine.md b/skills/pagekit-message-spine/references/framework.md similarity index 100% rename from frameworks/message-spine.md rename to skills/pagekit-message-spine/references/framework.md diff --git a/skills/pagekit-message-spine/references/prompt.md b/skills/pagekit-message-spine/references/prompt.md new file mode 100644 index 0000000..bb81ec3 --- /dev/null +++ b/skills/pagekit-message-spine/references/prompt.md @@ -0,0 +1,48 @@ +--- +step: "02" +name: message-spine +title: Reduce to a Message Spine +inputs: + - signal-doc.md +outputs: + - message-spine.md +framework: ./framework.md +template: ./template.md +--- + +# Prompt: 02 — Message Spine + +## When to use +After the signal doc exists and is strong enough to support a reduction. Before any first-page decision. + +## What good output looks like +- names the two to four truths strong enough to organize pages +- preserves audience distinctions worth keeping +- identifies the key trust question +- does not yet decide which page to build + +## Prompt + +```text +Using the signal doc below, reduce it into a message spine. + +Do not decide which page we are building yet. +Do not write page copy yet. +Do not invent proof. + +Give me: +1. core truth +2. target audience +3. sharp pain statement +4. desired shift or outcome +5. strongest language to preserve +6. page-level message implications +7. key trust question to answer +8. weak directions to avoid + +Signal doc: +[PASTE HERE] +``` + +## If the output is weak +The signal doc is probably too broad. Go back to step 01, sharpen it, or add a mechanism / proof / comparison brief before retrying. diff --git a/templates/message-spine-template.md b/skills/pagekit-message-spine/references/template.md similarity index 100% rename from templates/message-spine-template.md rename to skills/pagekit-message-spine/references/template.md diff --git a/.claude/skills/pagekit-new-run/SKILL.md b/skills/pagekit-new-run/SKILL.md similarity index 65% rename from .claude/skills/pagekit-new-run/SKILL.md rename to skills/pagekit-new-run/SKILL.md index faf65bd..7110722 100644 --- a/.claude/skills/pagekit-new-run/SKILL.md +++ b/skills/pagekit-new-run/SKILL.md @@ -1,11 +1,15 @@ --- name: pagekit-new-run -description: Scaffold a new fully-logged PageKit run folder by name. Wraps scripts/new-run.sh. Use when starting any PageKit run; prefer this over creating run folders by hand so structure stays consistent with frameworks/run-logging.md. +description: Scaffold a new fully-logged PageKit run folder by name. Wraps scripts/new-run.sh. Use when starting any PageKit run; prefer this over creating run folders by hand so structure stays consistent with the run-logging framework. --- # PageKit — Scaffold a New Run -Wraps `scripts/new-run.sh`. Creates `runs//` with the full fully-logged layout: goal, models, working-log, sources/README, prompts/01-07-*.md (copied from canonical prompts/), outputs/NN-*-output.md placeholders, per-step artifact placeholders, evaluation and evaluator-pass templates. +Wraps `scripts/new-run.sh`. Creates `runs//` with the full fully-logged layout: goal, models, working-log, sources/README, prompts/01-07-*.md (copied from the canonical per-step prompts), outputs/NN-*-output.md placeholders, per-step artifact placeholders, evaluation and evaluator-pass templates. + +## Read first +- `../pagekit/references/run-logging.md` — the fully-logged tier definition +- `../pagekit/references/method.md` — the method at a glance ## Procedure 1. Confirm the run name with the user. Use a slug (lowercase, hyphenated). @@ -19,3 +23,6 @@ Wraps `scripts/new-run.sh`. Creates `runs//` with the full fully-logge ## Failure modes - `runs/` already exists → suggest a different name. - Repo not at the root → `cd` to the repo root and retry. + +## Next +Hand off to the `pagekit` orchestrator, or invoke `pagekit-signal-doc` directly if the user wants to drive step by step. diff --git a/.claude/skills/pagekit-page-argument-shape/SKILL.md b/skills/pagekit-page-argument-shape/SKILL.md similarity index 82% rename from .claude/skills/pagekit-page-argument-shape/SKILL.md rename to skills/pagekit-page-argument-shape/SKILL.md index 1c0f682..4d82394 100644 --- a/.claude/skills/pagekit-page-argument-shape/SKILL.md +++ b/skills/pagekit-page-argument-shape/SKILL.md @@ -8,22 +8,22 @@ description: Design the page argument shape — what sections the chosen first p You are running step 04 of the PageKit method. ## Read first -- `prompts/04-page-argument-shape.md` -- `frameworks/page-argument-shape.md` -- `templates/page-argument-shape-template.md` -- `frameworks/anti-slop.md` — the drafting constraints the shape produces must include the anti-slop rules +- `./references/prompt.md` +- `./references/framework.md` +- `./references/template.md` +- `../pagekit/references/anti-slop.md` — the drafting constraints the shape produces must include the anti-slop rules ## Inputs - `runs//first-page-decision.md` - `runs//message-spine.md` (for context) ## Procedure -1. Load `prompts/04-page-argument-shape.md`. +1. Load `./references/prompt.md`. 2. Substitute the first-page decision. 3. Save the substituted prompt to `runs//prompts/04-page-argument-shape.md`. 4. Prompt the model. 5. Save the raw response to `runs//outputs/04-page-argument-shape-output.md`. -6. Distill into `runs//page-argument-shape.md`. **Make sure the drafting-constraints section includes the anti-slop block** from `templates/page-argument-shape-template.md`. +6. Distill into `runs//page-argument-shape.md`. **Make sure the drafting-constraints section includes the anti-slop block** from `./references/template.md`. 7. Update `working-log.md`. ## Quality gate diff --git a/frameworks/page-argument-shape.md b/skills/pagekit-page-argument-shape/references/framework.md similarity index 96% rename from frameworks/page-argument-shape.md rename to skills/pagekit-page-argument-shape/references/framework.md index 836be28..471e5c8 100644 --- a/frameworks/page-argument-shape.md +++ b/skills/pagekit-page-argument-shape/references/framework.md @@ -42,7 +42,7 @@ Do not defer this to drafting. A draft cannot save a shape that is too heavy. ## Anti-slop drafting constraints The shape step produces drafting constraints that the draft must respect. -These must include the hard anti-slop rules. See `frameworks/anti-slop.md` for the full reference and examples. +These must include the hard anti-slop rules. See `../../pagekit/references/anti-slop.md` for the full reference and examples. Minimum constraints every shape must pass to drafting: diff --git a/skills/pagekit-page-argument-shape/references/prompt.md b/skills/pagekit-page-argument-shape/references/prompt.md new file mode 100644 index 0000000..3be1468 --- /dev/null +++ b/skills/pagekit-page-argument-shape/references/prompt.md @@ -0,0 +1,47 @@ +--- +step: "04" +name: page-argument-shape +title: Design the Page Argument Shape +inputs: + - first-page-decision.md +outputs: + - page-argument-shape.md +framework: ./framework.md +template: ./template.md +--- + +# Prompt: 04 — Page Argument Shape + +## When to use +After the first-page decision is made. Before the proof map or the draft. + +## What good output looks like +- structure falls out of the argument, not a default homepage rhythm +- names sections the page needs AND sections it does not +- makes trust placement and proof placement explicit +- carries the anti-slop drafting constraints forward to the draft step + +## Prompt + +```text +Using the first-page decision below, design the page's argument shape. + +Do not draft the page yet. +Do not assume a standard homepage structure. + +Define: +1. what the visitor needs to understand first +2. what must be earned next +3. what order the argument should follow +4. what sections actually belong on this page +5. what sections would be unnecessary or harmful +6. where trust should land +7. where proof should land +8. drafting constraints (proof/scope + anti-slop) + +First-page decision: +[PASTE HERE] +``` + +## If the shape feels generic +Treat it as a signal that the first-page decision or the message spine is still too abstract. Fix upstream before drafting. A shape that looks like every page in the category has not done its job. diff --git a/templates/page-argument-shape-template.md b/skills/pagekit-page-argument-shape/references/template.md similarity index 95% rename from templates/page-argument-shape-template.md rename to skills/pagekit-page-argument-shape/references/template.md index 7a4e433..2f98c65 100644 --- a/templates/page-argument-shape-template.md +++ b/skills/pagekit-page-argument-shape/references/template.md @@ -19,7 +19,7 @@ List only the sections this page actually needs. ## Drafting constraints -Copy this block into the draft step. See `frameworks/anti-slop.md` for the full reference with examples. +Copy this block into the draft step. See `../../pagekit/references/anti-slop.md` for the full reference with examples. ### Proof and scope constraints - no bare "vet approved" / "expert approved" / "clinically proven" and object-equivalents diff --git a/.claude/skills/pagekit-proof-map/SKILL.md b/skills/pagekit-proof-map/SKILL.md similarity index 87% rename from .claude/skills/pagekit-proof-map/SKILL.md rename to skills/pagekit-proof-map/SKILL.md index 6b6964e..e8ee76c 100644 --- a/.claude/skills/pagekit-proof-map/SKILL.md +++ b/skills/pagekit-proof-map/SKILL.md @@ -8,9 +8,9 @@ description: Map proof to the chosen first page section by section. Step 05 of t You are running step 05 of the PageKit method. ## Read first -- `prompts/05-proof-map.md` -- `frameworks/proof-map.md` -- `templates/proof-map-template.md` +- `./references/prompt.md` +- `./references/framework.md` +- `./references/template.md` ## Inputs - `runs//first-page-decision.md` @@ -18,7 +18,7 @@ You are running step 05 of the PageKit method. - `runs//sources/05-proof-brief.md` (if it exists) ## Procedure -1. Load `prompts/05-proof-map.md`. +1. Load `./references/prompt.md`. 2. Substitute the artifacts above. 3. Save the substituted prompt to `runs//prompts/05-proof-map.md`. 4. Prompt the model. @@ -36,7 +36,7 @@ A strong proof map: If the proof map is "we have testimonials" and not much more, the upstream proof brief is too thin. Add specifics or accept a narrower draft. ## Hard rule -Do not invent proof. If the page wants to say something that the proof map cannot support, the draft step will mark it with `*[verification flag: ...]*` — this map is where those gaps are surfaced first. +Do not invent proof. If the page wants to say something that the proof map cannot support, the draft step will mark it with `*[verification flag: ...]*`. This map is where those gaps are surfaced first. ## Next After the proof map is in place, invoke **`pagekit-first-page-draft`** (step 06). Do not stop here. diff --git a/frameworks/proof-map.md b/skills/pagekit-proof-map/references/framework.md similarity index 100% rename from frameworks/proof-map.md rename to skills/pagekit-proof-map/references/framework.md diff --git a/skills/pagekit-proof-map/references/prompt.md b/skills/pagekit-proof-map/references/prompt.md new file mode 100644 index 0000000..5f38bae --- /dev/null +++ b/skills/pagekit-proof-map/references/prompt.md @@ -0,0 +1,44 @@ +--- +step: "05" +name: proof-map +title: Map Proof to the Page +inputs: + - first-page-decision.md + - page-argument-shape.md +outputs: + - proof-map.md +framework: ./framework.md +template: ./template.md +--- + +# Prompt: 05 — Proof Map + +## When to use +After the argument shape exists. Before the draft. + +## What good output looks like +- commits to what the page can honestly claim today +- names what the page cannot yet support +- maps proof to specific argument moves, not to the page in general +- makes the gap between available proof and needed proof visible + +## Prompt + +```text +Using the current PageKit artifacts, define the proof map for the first page. + +Do not write page copy yet. +Map: +1. what the page can honestly claim now +2. what it does not yet have proof for +3. safe credibility moves +4. risky or inflated moves to avoid +5. where proof lands in the approved argument shape (section by section) +6. what each approved section can say safely + +Artifacts: +[PASTE HERE] +``` + +## If proof is thin +Do not invent. Name the gap and let the draft stay honestly narrower. If the gap is large, a proof brief upstream (in `sources/`) is the right fix. diff --git a/templates/proof-map-template.md b/skills/pagekit-proof-map/references/template.md similarity index 100% rename from templates/proof-map-template.md rename to skills/pagekit-proof-map/references/template.md diff --git a/.claude/skills/pagekit-run-check/SKILL.md b/skills/pagekit-run-check/SKILL.md similarity index 92% rename from .claude/skills/pagekit-run-check/SKILL.md rename to skills/pagekit-run-check/SKILL.md index 1abbae6..698ca1c 100644 --- a/.claude/skills/pagekit-run-check/SKILL.md +++ b/skills/pagekit-run-check/SKILL.md @@ -5,7 +5,7 @@ description: Validate a PageKit run folder against the logging tiers (fully-logg # PageKit — Validate a Run -Wraps `scripts/run-check.sh`. Reads a run folder and classifies it per `frameworks/run-logging.md`. Lists missing files for the next tier up. +Wraps `scripts/run-check.sh`. Reads a run folder and classifies it per `../pagekit/references/run-logging.md`. Lists missing files for the next tier up. ## Procedure 1. Run: `bash scripts/run-check.sh runs/`. diff --git a/.claude/skills/pagekit-signal-doc/SKILL.md b/skills/pagekit-signal-doc/SKILL.md similarity index 72% rename from .claude/skills/pagekit-signal-doc/SKILL.md rename to skills/pagekit-signal-doc/SKILL.md index ca6d576..cabff93 100644 --- a/.claude/skills/pagekit-signal-doc/SKILL.md +++ b/skills/pagekit-signal-doc/SKILL.md @@ -8,20 +8,21 @@ description: Build a PageKit signal doc from a product description and any sourc You are running step 01 of the PageKit method. ## Read first -- `prompts/01-signal-doc.md` — the canonical prompt for this step -- `frameworks/signal-doc.md` — what makes a signal doc strong -- `templates/signal-doc-template.md` — the artifact shape +- `./references/prompt.md` — the canonical prompt for this step +- `./references/framework.md` — what makes a signal doc strong +- `./references/template.md` — the artifact shape +- `./references/wedge-definition-template.md` — use when the first signal pass is too category-level ## Inputs - A product description and any source briefs in `runs//sources/` (especially `02-product-brief.md`). ## Procedure -1. Load `prompts/01-signal-doc.md`. +1. Load `./references/prompt.md`. 2. Substitute the product description and source briefs in place of `[PASTE HERE]`. 3. If invoked inside a fully-logged run, save the substituted prompt to `runs//prompts/01-signal-doc.md`. 4. Prompt the model with the substituted prompt. 5. Save the raw response to `runs//outputs/01-signal-doc-output.md`. -6. Distill the response into `runs//signal-doc.md` per `templates/signal-doc-template.md`. +6. Distill the response into `runs//signal-doc.md` per `./references/template.md`. 7. Append a short note to `runs//working-log.md`. ## Quality gate @@ -31,10 +32,10 @@ A strong signal doc: - exposes what is still unknown - distinguishes audiences where it matters -If the doc is too generic or too category-level, **do not advance to step 02.** Create a wedge-definition brief (`templates/wedge-definition-template.md`) or a sharper product brief, then rerun this step. +If the doc is too generic or too category-level, **do not advance to step 02.** Create a wedge-definition brief (`./references/wedge-definition-template.md`) or a sharper product brief, then rerun this step. ## Anti-slop -Signal docs themselves rarely produce slop, but if the output uses confident-sounding empty words ("comprehensive," "deeply understands," "transforms"), strip them. Real signal is specific. +Signal docs themselves rarely produce slop, but if the output uses confident-sounding empty words ("comprehensive," "deeply understands," "transforms"), strip them. Real signal is specific. See `../pagekit/references/anti-slop.md` for the full catalog. ## Next After this step's artifact is in place, invoke **`pagekit-message-spine`** (step 02). Do not stop here. The signal doc is not the deliverable; the draft is, and the chain must run to completion (see the orchestrator's self-check). diff --git a/frameworks/signal-doc.md b/skills/pagekit-signal-doc/references/framework.md similarity index 100% rename from frameworks/signal-doc.md rename to skills/pagekit-signal-doc/references/framework.md diff --git a/skills/pagekit-signal-doc/references/prompt.md b/skills/pagekit-signal-doc/references/prompt.md new file mode 100644 index 0000000..e0d4df9 --- /dev/null +++ b/skills/pagekit-signal-doc/references/prompt.md @@ -0,0 +1,54 @@ +--- +step: "01" +name: signal-doc +title: Build a Signal Doc +inputs: + - product-brief (or raw product description) +outputs: + - signal-doc.md +framework: ./framework.md +template: ./template.md +--- + +# Prompt: 01 — Signal Doc + +## When to use +At the start of a PageKit run. Before any page decision, before any spine, before any draft. + +## What good output looks like +- separates observation from assumption +- gives sharper language than the category default +- exposes what is still unknown +- distinguishes audiences where it matters + +## Prompt + +```text +I want to build a web page through the PageKit process. + +Do not write page copy yet. +Do not assume which page we are building. +Help me build a signal doc first. + +Using the product description (and any source briefs) below, produce a signal doc with these sections: +1. what the product appears to be +2. likely target audience(s) +3. recurring pains or friction +4. desired outcomes +5. trust questions or buying resistance +6. native phrases worth keeping +7. generic language to avoid +8. what still feels unknown +9. weak claims to avoid early + +Rules: +- do not invent outside facts; use only what is in the briefs +- do not restate marketing language; extract real signal +- keep uncertainty visible where it is real + +Source material: +[PASTE HERE] +``` + +## If the output is weak +Stop. Before moving to step 02, create a sharper source artifact (wedge definition, mechanism brief, proof brief, comparison brief). See `./wedge-definition-template.md`. diff --git a/templates/signal-doc-template.md b/skills/pagekit-signal-doc/references/template.md similarity index 100% rename from templates/signal-doc-template.md rename to skills/pagekit-signal-doc/references/template.md diff --git a/templates/wedge-definition-template.md b/skills/pagekit-signal-doc/references/wedge-definition-template.md similarity index 100% rename from templates/wedge-definition-template.md rename to skills/pagekit-signal-doc/references/wedge-definition-template.md diff --git a/.claude/skills/pagekit-slop-check/SKILL.md b/skills/pagekit-slop-check/SKILL.md similarity index 74% rename from .claude/skills/pagekit-slop-check/SKILL.md rename to skills/pagekit-slop-check/SKILL.md index 74bbed3..7265593 100644 --- a/.claude/skills/pagekit-slop-check/SKILL.md +++ b/skills/pagekit-slop-check/SKILL.md @@ -1,11 +1,14 @@ --- name: pagekit-slop-check -description: Run the heuristic AI-slop regression check on PageKit drafts. Wraps scripts/slop-check.sh. Use before and after the claim-check step, and any time you want to sanity-check a draft for the mechanically detectable slop patterns from frameworks/anti-slop.md. +description: Run the heuristic AI-slop regression check on PageKit drafts. Wraps scripts/slop-check.sh. Use before and after the claim-check step, and any time you want to sanity-check a draft for the mechanically detectable slop patterns. --- # PageKit — Slop Check -Wraps `scripts/slop-check.sh`. Heuristic regression check covering the mechanically detectable subset of `frameworks/anti-slop.md`: Not-X-Not-Y headings and sentences, em-dash stacking, "actually" intensifier, copula avoidance, signposting, filler, significance inflation, anaphora, rule-of-three short-sentence clustering, intensifier vocabulary, quoted antithesis. +Wraps `scripts/slop-check.sh`. Heuristic regression check covering the mechanically detectable subset of `../pagekit/references/anti-slop.md`: Not-X-Not-Y headings and sentences, em-dash stacking, "actually" intensifier, copula avoidance, signposting, filler, significance inflation, anaphora, rule-of-three short-sentence clustering, intensifier vocabulary, quoted antithesis. + +## Read first +- `../pagekit/references/anti-slop.md` — the authoritative pattern catalog ## Procedure 1. Run: `bash scripts/slop-check.sh [paths...]`. With no args, scans every `homepage-draft.md` / `first-page-draft.md` / `first-page-draft-corrected.md` under `runs/`. diff --git a/.claude/skills/pagekit/SKILL.md b/skills/pagekit/SKILL.md similarity index 81% rename from .claude/skills/pagekit/SKILL.md rename to skills/pagekit/SKILL.md index a4bc916..33edc46 100644 --- a/.claude/skills/pagekit/SKILL.md +++ b/skills/pagekit/SKILL.md @@ -5,14 +5,14 @@ description: Run the full PageKit method end-to-end on an object. Use when the u # PageKit Orchestrator Skill -You are running the full PageKit method end-to-end. The method, the manifest, the canonical prompts, the scripts and the rules all live in this repo. Use them. +You are running the full PageKit method end-to-end. The method, the canonical prompts, the scripts and the rules all live in this plugin. Use them. ## Read first -1. `pagekit.yaml` — the canonical method manifest. Steps, artifacts, frameworks, templates, prompts, paths. -2. `AGENTS.md` and `CLAUDE.md` — agent contract and operational rules. -3. `frameworks/anti-slop.md` — hard no-go patterns for the draft. -4. `frameworks/run-logging.md` — what counts as fully-logged. +1. `./references/method.md` — the method at a glance: steps, artifacts, order. +2. `./references/anti-slop.md` — hard no-go patterns for the draft. +3. `./references/run-logging.md` — what counts as fully-logged. +4. `AGENTS.md` and `CLAUDE.md` at the repo root — agent contract and operational rules. ## Procedure @@ -39,13 +39,13 @@ Fill `runs//sources/`: For each step: 1. Invoke the per-step skill: `pagekit-signal-doc`, `pagekit-message-spine`, `pagekit-first-page-decision`, `pagekit-page-argument-shape`, `pagekit-proof-map`, `pagekit-first-page-draft`. -2. The per-step skill loads its canonical prompt from `prompts/NN-*.md`, substitutes the run's inputs, prompts the model. +2. The per-step skill loads its canonical prompt from its own `references/prompt.md`, substitutes the run's inputs, prompts the model. 3. Save the prompt actually used (with substitutions) to `runs//prompts/NN-*.md`. 4. Save the raw output to `runs//outputs/NN-*-output.md`. 5. Distill the output into the canonical artifact in the run root (`signal-doc.md`, `message-spine.md`, etc.). 6. Update `runs//working-log.md` with what changed and any decisions made. -**Quality gate at every step:** if the artifact does not meet the quality bar in the corresponding `frameworks/*.md`, stop and fix upstream source material before advancing. Do not paper over weakness with downstream effort. +**Quality gate at every step:** if the artifact does not meet the quality bar in the corresponding `references/framework.md` for that skill, stop and fix upstream source material before advancing. Do not paper over weakness with downstream effort. **Step 03 (first-page decision) is special.** Do not default to homepage. List candidates considered and rejected. The object decides the first page. @@ -82,7 +82,7 @@ Tell the user: - **Do not invent proof.** Use `*[verification flag: ...]*` for unverified product-specific claims. - **Do not skip slop-check before the claim-check step.** The script catches the obvious cases; the claim-check catches the rest. - **Do not skip the evaluator pass** at the fully-logged tier. -- **Do not edit the canonical prompts** in `prompts/` to fit a single run. They are shared. +- **Do not edit the canonical prompts** in any skill's `references/prompt.md` to fit a single run. They are shared. - **Do not delete or leave blank the scaffolded placeholder files** (`claim-check.md`, `evaluation.md`, `evaluator-pass.md`, `working-log.md`). They are structural; fill them in or commit them as-is until filled. ## Are you done? Self-check @@ -114,6 +114,12 @@ Only after every box is checked do you report completion to the user. ## When to delegate -Use the `pagekit-claim-checker` subagent (`.claude/agents/pagekit-claim-checker.md`) for the claim-check step. It is read-only and has a tighter focus, which keeps the main session uncluttered. +Use the `pagekit-claim-checker` subagent (`agents/pagekit-claim-checker.md`) for the claim-check step. It is read-only and has a tighter focus, which keeps the main session uncluttered. For tooling steps, invoke the corresponding skill rather than calling the script directly so the rationale is logged in the conversation. + +## Related + +- Per-step skills: `pagekit-signal-doc`, `pagekit-message-spine`, `pagekit-first-page-decision`, `pagekit-page-argument-shape`, `pagekit-proof-map`, `pagekit-first-page-draft`, `pagekit-claim-check` +- Tooling: `pagekit-new-run`, `pagekit-run-check`, `pagekit-slop-check`, `pagekit-evaluator-pass` +- Subagents: `pagekit-claim-checker` (step 07), `pagekit-evaluator-pass` (adversarial read) diff --git a/frameworks/anti-slop.md b/skills/pagekit/references/anti-slop.md similarity index 96% rename from frameworks/anti-slop.md rename to skills/pagekit/references/anti-slop.md index 834256b..4858b3e 100644 --- a/frameworks/anti-slop.md +++ b/skills/pagekit/references/anti-slop.md @@ -5,7 +5,7 @@ Slop is the collection of sentence-level, paragraph-level and structural pattern Slop hurts PageKit specifically: a page whose job is to earn trust loses trust the moment the reader notices the rhythm is artificial, even if the proof is real. This is why slop is treated as a proof issue here, not only a voice issue. This document is the authoritative list of patterns PageKit treats as slop. -It is referenced by `frameworks/page-argument-shape.md` (drafting constraints), `frameworks/claim-checking.md` (flag type), `templates/page-argument-shape-template.md`, `templates/claim-check-template.md`, the five tool guides, the five quickstarts, `CLAUDE.md` and `scripts/slop-check.sh`. +It is referenced by the page-argument-shape framework (drafting constraints), the claim-check framework (flag type), the page-argument-shape template, the claim-check template, the first-page-draft prompt, `CLAUDE.md`, and `scripts/slop-check.sh` (the mechanical subset). ## What this is not diff --git a/skills/pagekit/references/method.md b/skills/pagekit/references/method.md new file mode 100644 index 0000000..3e2ab9d --- /dev/null +++ b/skills/pagekit/references/method.md @@ -0,0 +1,42 @@ +# PageKit method + +The stable chain that every PageKit run follows. Steps 01-06 are required. Step 07 is an optional durability pass. + +``` +signal-doc -> message-spine -> first-page-decision -> page-argument-shape -> proof-map -> first-page-draft [ -> claim-check ] +``` + +## Steps + +| # | Name | Skill | Artifact | Inputs | +|---|---|---|---|---| +| 01 | Build a Signal Doc | `pagekit-signal-doc` | `signal-doc.md` | product brief + any source briefs | +| 02 | Reduce to a Message Spine | `pagekit-message-spine` | `message-spine.md` | `signal-doc.md` | +| 03 | Decide the First Page | `pagekit-first-page-decision` | `first-page-decision.md` | `signal-doc.md`, `message-spine.md` | +| 04 | Design the Page Argument Shape | `pagekit-page-argument-shape` | `page-argument-shape.md` | `first-page-decision.md` | +| 05 | Map Proof to the Page | `pagekit-proof-map` | `proof-map.md` | `first-page-decision.md`, `page-argument-shape.md` | +| 06 | Draft the First Page | `pagekit-first-page-draft` | `first-page-draft.md` | all 5 upstream artifacts | +| 07 | Claim Check (optional) | `pagekit-claim-check` | `claim-check.md`, `first-page-draft-corrected.md` | `first-page-draft.md`, `proof-map.md` | + +Step 03 does NOT default to homepage. The object decides. The decision must list candidates considered and rejected. + +Step 06 must respect the anti-slop rules in `./anti-slop.md`. Unverified product-specific claims get inline `*[verification flag: ...]*` markers. + +Step 07 has three severities: light, normal, hard. Default is normal. + +## Tooling skills + +| Skill | Script | Purpose | +|---|---|---| +| `pagekit-new-run` | `scripts/new-run.sh` | Scaffold a fully-logged run folder | +| `pagekit-run-check` | `scripts/run-check.sh` | Validate a run against the logging tiers | +| `pagekit-slop-check` | `scripts/slop-check.sh` | Heuristic regression check for AI-slop patterns | +| `pagekit-evaluator-pass` | (subagent) | Adversarial second read on a completed run | + +## Run logging + +See `./run-logging.md` for the full definition of the `fully-logged`, `summary-logged`, and `publishable` tiers. + +## Anti-slop + +See `./anti-slop.md` for the authoritative list of AI-slop patterns that are treated as hard no-goes at drafting time and at claim-check time. diff --git a/templates/output-judgment-template.md b/skills/pagekit/references/output-judgment-template.md similarity index 100% rename from templates/output-judgment-template.md rename to skills/pagekit/references/output-judgment-template.md diff --git a/frameworks/run-logging.md b/skills/pagekit/references/run-logging.md similarity index 90% rename from frameworks/run-logging.md rename to skills/pagekit/references/run-logging.md index 7821b6f..fafa9df 100644 --- a/frameworks/run-logging.md +++ b/skills/pagekit/references/run-logging.md @@ -73,12 +73,12 @@ make new-run NAME= make run-check RUN= ``` -`scripts/new-run.sh` matches the fully_logged tier in `pagekit.yaml`. If this framework changes, update both. +`scripts/new-run.sh` must stay in sync with the fully_logged tier above. If this framework changes, update the script too. `scripts/run-check.sh` exits 0 if the run is fully-logged or summary-logged, exits 1 if artifact-only or incomplete. Wire it into your end-of-run checklist. ## Related -- `frameworks/anti-slop.md` — hard no-go patterns for drafts produced by any run +- `./anti-slop.md` — hard no-go patterns for drafts produced by any run - `scripts/slop-check.sh` — regression check a run's draft should pass - `scripts/new-run.sh`, `scripts/run-check.sh` — mechanized scaffold and validation -- `pagekit.yaml` — the manifest the scripts read from +- `./method.md` — the canonical method manifest the skills read from