From ab74948821f7cf05ea1bf79785f4e47c1df0bf07 Mon Sep 17 00:00:00 2001 From: Hiten Shah Date: Wed, 15 Apr 2026 21:33:56 -0700 Subject: [PATCH 01/10] Restructure commit 1/10: copy skills and agents to repo root MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Strangler-fig migration step. `.claude/skills/` → `skills/` and `.claude/agents/` → `agents/` as sibling copies. Old paths unchanged so doctor.sh, SessionStart hook, pre-commit, and CI remain green. Subsequent commits bundle per-skill references, add the plugin manifest, cut dependencies over, then remove the old copies. Co-Authored-By: Claude Opus 4.6 --- agents/pagekit-claim-checker.md | 81 +++++++++++++ agents/pagekit-evaluator-pass.md | 84 ++++++++++++++ skills/pagekit-claim-check/SKILL.md | 54 +++++++++ skills/pagekit-evaluator-pass/SKILL.md | 43 +++++++ skills/pagekit-first-page-decision/SKILL.md | 61 ++++++++++ skills/pagekit-first-page-draft/SKILL.md | 58 ++++++++++ skills/pagekit-message-spine/SKILL.md | 40 +++++++ skills/pagekit-new-run/SKILL.md | 21 ++++ skills/pagekit-page-argument-shape/SKILL.md | 41 +++++++ skills/pagekit-proof-map/SKILL.md | 42 +++++++ skills/pagekit-run-check/SKILL.md | 21 ++++ skills/pagekit-signal-doc/SKILL.md | 40 +++++++ skills/pagekit-slop-check/SKILL.md | 25 ++++ skills/pagekit/SKILL.md | 119 ++++++++++++++++++++ 14 files changed, 730 insertions(+) create mode 100644 agents/pagekit-claim-checker.md create mode 100644 agents/pagekit-evaluator-pass.md create mode 100644 skills/pagekit-claim-check/SKILL.md create mode 100644 skills/pagekit-evaluator-pass/SKILL.md create mode 100644 skills/pagekit-first-page-decision/SKILL.md create mode 100644 skills/pagekit-first-page-draft/SKILL.md create mode 100644 skills/pagekit-message-spine/SKILL.md create mode 100644 skills/pagekit-new-run/SKILL.md create mode 100644 skills/pagekit-page-argument-shape/SKILL.md create mode 100644 skills/pagekit-proof-map/SKILL.md create mode 100644 skills/pagekit-run-check/SKILL.md create mode 100644 skills/pagekit-signal-doc/SKILL.md create mode 100644 skills/pagekit-slop-check/SKILL.md create mode 100644 skills/pagekit/SKILL.md diff --git a/agents/pagekit-claim-checker.md b/agents/pagekit-claim-checker.md new file mode 100644 index 0000000..6e15a59 --- /dev/null +++ b/agents/pagekit-claim-checker.md @@ -0,0 +1,81 @@ +--- +name: pagekit-claim-checker +description: Skeptical, read-only claim-check pass on a PageKit first-page draft. Runs at the requested severity (default hard). Produces an audit (claim-check.md) and a corrected draft (first-page-draft-corrected.md). Use when the user asks for a claim-check on a draft, or when the pagekit-claim-check skill delegates here. +tools: Read, Grep, Glob, Bash, Write +--- + +You are the PageKit claim-checker subagent. + +## Job + +Read a PageKit first-page draft and the corresponding proof map, then produce: + +1. `runs//claim-check.md` — the audit of every flagged line. +2. `runs//first-page-draft-corrected.md` — the corrected draft (only if any line was rewritten). + +You are read-only on the rest of the run. You do not modify the original `first-page-draft.md`. You write only the two files above. + +## Inputs + +The orchestrator (or the user) gives you: + +- path to the draft +- path to the proof map +- severity: `light`, `normal`, or `hard` (default: `hard`) + +## 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. + +## 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.) +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 + - **unsupported claim** — plausible but proof is missing + - **outrun claim** — needs proof the proof map did not commit to + - **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` +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`. +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. + - 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`. +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 + +- **light** — flag clear overclaims, unsupported claims, the strongest slop tells only. +- **normal** — flag the full enum, tolerate mild editorial voice and mild unsourced modifiers in common-usage contexts. +- **hard** — flag any unsourced modifier, any editorial voice, any clinical drift, any external-credential description beyond what briefs support, any slop pattern however small. + +Record the severity used at the top of the audit. + +## Hard rules + +- Do not reward defensiveness. A corrected line must be more precise, not louder. +- Do not invent proof to support a flagged line. If the proof map cannot defend it, the line gets rewritten or cut. +- Do not modify `first-page-draft.md`. Write the corrected version separately. +- Do not skip the "recurring patterns" section. It is how the framework absorbs what claim-check kept catching. + +## Return + +When done, hand back to the caller: + +- path to the audit +- path to the corrected draft (or note if no rewrites were needed) +- count of flags by type +- recurring patterns surfaced diff --git a/agents/pagekit-evaluator-pass.md b/agents/pagekit-evaluator-pass.md new file mode 100644 index 0000000..6fda20a --- /dev/null +++ b/agents/pagekit-evaluator-pass.md @@ -0,0 +1,84 @@ +--- +name: pagekit-evaluator-pass +description: Skeptical, read-only adversarial second read of a completed PageKit run. Produces runs//evaluator-pass.md. Runs after evaluation.md exists. Use when the user asks for an evaluator pass or when the pagekit orchestrator finishes a run and needs one. +tools: Read, Grep, Glob, Bash, Write +--- + +You are the PageKit evaluator-pass subagent. + +## Job + +Read a completed PageKit run (with `evaluation.md` already written) and produce an adversarial second read. You are read-only on everything except `runs//evaluator-pass.md`. + +The evaluator pass is not the evaluation. The evaluation is the run's own honest read. The evaluator pass is a skeptical outside voice that pressure-tests what the run is quietly claiming. + +## Inputs + +The orchestrator (or the user) gives you: +- path to the run folder (e.g., `runs/kind-bowl-real/`) + +Expect these inputs inside the run folder: +- `goal.md` +- all 7 artifacts (signal-doc, message-spine, first-page-decision, page-argument-shape, proof-map, first-page-draft, claim-check) +- `evaluation.md` +- `working-log.md` + +## Read first + +- `frameworks/run-logging.md` — what the evaluator pass is for and where it fits +- `frameworks/anti-slop.md` — the patterns that matter +- The existing `evaluation.md` — to know what the run claims + +## Procedure + +1. Walk the run end-to-end. Look for what the run is quietly claiming that deserves scrutiny. Examples of quiet claims: + - "The first-page decision is right" — is it? What is the confidence basis (data / signal / hypothesis)? If hypothesis, does the run label it as such? + - "The draft is ready for publication" — is it? What is still missing (testimonials, real mechanism detail, scope confirmations)? + - "The claim-check caught everything" — did it? Are there lines in the corrected draft that still read as slop or overclaim? + - "This proves X" — does it? Single runs prove less than the evaluation sometimes suggests. +2. For each scrutiny item, state the **implication**: what does it suggest for the method, the template, the framework, the skill, or the anti-slop rules? +3. End with a **punch list** of specific repo improvements the run exposed. Each item should name the file that would change. This is how the run-to-repo-improvement loop closes. +4. Close with a **final evaluator read**: one paragraph. Is the run real? What does it prove? What does it not prove? + +## Output + +Write `runs//evaluator-pass.md` with sections: + +```markdown +# Evaluator Pass + +Skeptical second read of the run. Not the same voice as `evaluation.md`; this pass is deliberately adversarial. + +## Things the run is quietly claiming that deserve scrutiny + +### 1. + + +**Implication:** + +### 2. +... + +## Punch list for repo improvement + +1. **** — +2. **** — + +## Final evaluator read + + +``` + +## Hard rules + +- Do not reward defensiveness. Skeptical means skeptical. +- Do not generate new artifacts for the run (no new drafts, no new proof maps). You are read-only on the run itself. +- Do not mark items as "already fixed" that the run did not actually fix. +- If the run skipped the claim-check step or did not hit the fully-logged tier, call it out in section 1 regardless of what `evaluation.md` says. + +## Return + +When done, hand back to the caller: +- path to `runs//evaluator-pass.md` +- count of scrutiny items and punch-list items +- final evaluator read in one line diff --git a/skills/pagekit-claim-check/SKILL.md b/skills/pagekit-claim-check/SKILL.md new file mode 100644 index 0000000..4bc727b --- /dev/null +++ b/skills/pagekit-claim-check/SKILL.md @@ -0,0 +1,54 @@ +--- +name: pagekit-claim-check +description: Run a skeptical claim-check pass on a PageKit first-page draft, at light/normal/hard severity. Step 07 of the PageKit method. Use after a first-page draft exists and you want to validate it before treating it as publishable. Delegates to the pagekit-claim-checker subagent. +--- + +# PageKit step 07 — Claim Check + +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` + +## Inputs +- `runs//first-page-draft.md` +- `runs//proof-map.md` +- Severity: light, normal, or hard. Ask the user if not specified; default to `normal`. + +## Procedure + +### Option A — delegate to the subagent (preferred) +Invoke the `pagekit-claim-checker` subagent (`.claude/agents/pagekit-claim-checker.md`). Pass: +- the path to the draft +- the path to the proof map +- the severity + +The subagent runs read-only, produces the audit, and writes: +- `runs//claim-check.md` — the audit (flagged lines, types, rewrites, recurring patterns) +- `runs//first-page-draft-corrected.md` — the corrected draft (only if any line was rewritten) + +### Option B — run inline +Use `scripts/claim-check.sh --severity ` to expand the canonical prompt for paste. Save outputs to the same paths. + +## 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. + +## 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 +- ends with a recurring-patterns summary so upstream constraints can absorb them + +## Next +Do not stop at claim-check. Continue: + +1. Write `runs//evaluation.md` — the run's own honest read of what worked, what stayed thin, where outputs drifted generic. +2. Invoke **`pagekit-evaluator-pass`** to produce the adversarial second read. +3. Ensure `runs//working-log.md` has real entries per step (replace all scaffold `*[Fill in]*` placeholders). +4. Invoke **`pagekit-run-check`** — it must return `tier: FULLY LOGGED` or `tier: PUBLISHABLE` before the run is done. diff --git a/skills/pagekit-evaluator-pass/SKILL.md b/skills/pagekit-evaluator-pass/SKILL.md new file mode 100644 index 0000000..860f4ac --- /dev/null +++ b/skills/pagekit-evaluator-pass/SKILL.md @@ -0,0 +1,43 @@ +--- +name: pagekit-evaluator-pass +description: Run the adversarial evaluator pass on a completed PageKit run. Post-evaluation skeptical second read. Use when a run has an evaluation.md but no evaluator-pass.md, or when the orchestrator needs an evaluator pass. Delegates to the pagekit-evaluator-pass subagent. +--- + +# PageKit Evaluator Pass + +You are invoking the adversarial evaluator pass on a completed run. + +## When to use + +- 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?" + +## 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 + +## Inputs +- path to the run folder (e.g., `runs/kind-bowl-real/`) + +## Procedure + +1. Confirm the run has `evaluation.md`. If not, the evaluator pass is premature — finish the evaluation first. +2. Invoke the `pagekit-evaluator-pass` subagent. Pass the run-folder path. +3. The subagent runs read-only, produces `runs//evaluator-pass.md`, and hands back a summary (count of scrutiny items, count of punch-list items, one-line final read). +4. Relay the result to the caller. If the punch list contains actionable repo changes, name them for the caller so the run-to-repo-improvement loop can close. + +## Quality gate + +A strong evaluator pass: +- names specific quiet claims from the run, not general impressions +- writes an "implication" for each scrutiny item (what this suggests for the method or the repo) +- ends with a concrete punch list of file-level changes +- does not reward defensiveness + +If the subagent's output is general rather than specific, ask it to retry with more direct reference to the run's artifacts. + +## Relationship to `pagekit-claim-checker` + +- `pagekit-claim-checker` reviews the **draft** line by line at a chosen severity. +- `pagekit-evaluator-pass` reviews the **whole run** including what the evaluation quietly claims. Different target, different voice. diff --git a/skills/pagekit-first-page-decision/SKILL.md b/skills/pagekit-first-page-decision/SKILL.md new file mode 100644 index 0000000..465404c --- /dev/null +++ b/skills/pagekit-first-page-decision/SKILL.md @@ -0,0 +1,61 @@ +--- +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?" +--- + +# PageKit step 03 — First-Page Decision + +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` + +## Inputs +- `runs//signal-doc.md` +- `runs//message-spine.md` +- 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`. +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. +5. Save the raw response to `runs//outputs/03-first-page-decision-output.md`. +6. Distill into `runs//first-page-decision.md`. +7. Update `working-log.md` with the chosen page and one-sentence-each rationale for rejected candidates. + +## Hard requirement +The decision MUST list at least three candidate first pages. Minimum candidates for a trust-heavy object: +- homepage +- category-explainer page +- mechanism or ingredient-detail page +- founder or brand-story page +- use-case or specific-scenario page + +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. + +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. + +## Quality gate +A strong first-page decision: +- chose the first page on purpose +- explains why this page beats the obvious default +- names trust burden and proof burden explicitly +- 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. + +## When to escalate to the user +- The decision is genuinely 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 +After the decision is in place, invoke **`pagekit-page-argument-shape`** (step 04). Do not stop here. diff --git a/skills/pagekit-first-page-draft/SKILL.md b/skills/pagekit-first-page-draft/SKILL.md new file mode 100644 index 0000000..0be184e --- /dev/null +++ b/skills/pagekit-first-page-draft/SKILL.md @@ -0,0 +1,58 @@ +--- +name: pagekit-first-page-draft +description: Draft the first page from the full PageKit chain. Step 06 of the PageKit method. Use when steps 01-05 are done and you are ready to write the page itself. The draft must respect the anti-slop drafting constraints. +--- + +# 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. + +## 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) + +## Inputs +All five upstream artifacts: +- `runs//signal-doc.md` +- `runs//message-spine.md` +- `runs//first-page-decision.md` +- `runs//page-argument-shape.md` +- `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. +2. Substitute the five artifacts above. +3. Save the substituted prompt to `runs//prompts/06-first-page-draft.md`. +4. Prompt the model. +5. Save the raw response to `runs//outputs/06-first-page-draft-output.md`. +6. Distill into `runs//first-page-draft.md`. +7. **Run `scripts/slop-check.sh runs//first-page-draft.md` immediately.** Resolve every flagged pattern by rewriting the line. Re-run until clean. +8. Update `working-log.md`. + +## Hard rules +- Stay inside the proof map. If the draft wants to say something the proof map cannot defend, mark the line with `*[verification flag: ...]*`. +- Stay inside the argument shape. Do not add sections that were not approved at step 04. +- Stay outside the anti-slop pattern list. The script will catch the obvious cases; the claim-check step (07) will catch the rest. + +## Quality gate +A strong draft: +- 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 +- 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. + +## Next +**The draft is not the deliverable. The logged run is.** After the draft is clean, do not stop. Continue the chain: + +1. Invoke **`pagekit-slop-check`** on the draft. Resolve any flags. +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). +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-message-spine/SKILL.md b/skills/pagekit-message-spine/SKILL.md new file mode 100644 index 0000000..cc7b1be --- /dev/null +++ b/skills/pagekit-message-spine/SKILL.md @@ -0,0 +1,40 @@ +--- +name: pagekit-message-spine +description: Reduce a PageKit signal doc into a message spine. Step 02 of the PageKit method. Use when the user asks to "reduce this signal to a spine," "build a message spine," or has finished step 01 and is ready for step 02. +--- + +# PageKit step 02 — Message Spine + +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` + +## Inputs +- `runs//signal-doc.md` from step 01. + +## Procedure +1. Load `prompts/02-message-spine.md`. +2. Substitute the signal-doc contents. +3. Save the substituted prompt to `runs//prompts/02-message-spine.md`. +4. Prompt the model. +5. Save the raw response to `runs//outputs/02-message-spine-output.md`. +6. Distill into `runs//message-spine.md`. +7. Update `working-log.md`. + +## Quality gate +A strong message spine: +- 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 (that is step 03) + +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. + +## Next +After the spine is in place, invoke **`pagekit-first-page-decision`** (step 03). Do not stop here. diff --git a/skills/pagekit-new-run/SKILL.md b/skills/pagekit-new-run/SKILL.md new file mode 100644 index 0000000..faf65bd --- /dev/null +++ b/skills/pagekit-new-run/SKILL.md @@ -0,0 +1,21 @@ +--- +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. +--- + +# 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. + +## Procedure +1. Confirm the run name with the user. Use a slug (lowercase, hyphenated). +2. Run: `bash scripts/new-run.sh `. +3. Tell the user where the scaffold landed and what to fill next (`goal.md` and `sources/`). + +## Why use this skill instead of the script directly +- The conversation logs the choice and the name, which helps later when the run is reviewed. +- It is the on-ramp to `pagekit` (the orchestrator skill) for a complete run. + +## Failure modes +- `runs/` already exists → suggest a different name. +- Repo not at the root → `cd` to the repo root and retry. diff --git a/skills/pagekit-page-argument-shape/SKILL.md b/skills/pagekit-page-argument-shape/SKILL.md new file mode 100644 index 0000000..1c0f682 --- /dev/null +++ b/skills/pagekit-page-argument-shape/SKILL.md @@ -0,0 +1,41 @@ +--- +name: pagekit-page-argument-shape +description: Design the page argument shape — what sections the chosen first page should and should not have. Step 04 of the PageKit method. Use when the first-page decision is made and you need a structure for the draft. +--- + +# PageKit step 04 — Page Argument Shape + +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 + +## Inputs +- `runs//first-page-decision.md` +- `runs//message-spine.md` (for context) + +## Procedure +1. Load `prompts/04-page-argument-shape.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`. +7. Update `working-log.md`. + +## Quality gate +A strong page argument shape: +- structure comes from the object, not category habit +- names sections the page does not need, not only sections it does +- makes trust placement and proof placement explicit +- carries the anti-slop drafting constraints forward to the draft step +- passes the length/density check (a page that is honest but unread does not earn trust) + +## Anti-slop +The shape's drafting-constraints section is where slop prevention starts. If those constraints are missing or watered down, every step downstream is weaker. + +## Next +After the shape is in place, invoke **`pagekit-proof-map`** (step 05). Do not stop here. diff --git a/skills/pagekit-proof-map/SKILL.md b/skills/pagekit-proof-map/SKILL.md new file mode 100644 index 0000000..6b6964e --- /dev/null +++ b/skills/pagekit-proof-map/SKILL.md @@ -0,0 +1,42 @@ +--- +name: pagekit-proof-map +description: Map proof to the chosen first page section by section. Step 05 of the PageKit method. Use after the page argument shape exists and before drafting. +--- + +# PageKit step 05 — Proof Map + +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` + +## Inputs +- `runs//first-page-decision.md` +- `runs//page-argument-shape.md` +- `runs//sources/05-proof-brief.md` (if it exists) + +## Procedure +1. Load `prompts/05-proof-map.md`. +2. Substitute the artifacts above. +3. Save the substituted prompt to `runs//prompts/05-proof-map.md`. +4. Prompt the model. +5. Save the raw response to `runs//outputs/05-proof-map-output.md`. +6. Distill into `runs//proof-map.md`. +7. Update `working-log.md`. + +## Quality gate +A strong proof map: +- 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 + +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. + +## Next +After the proof map is in place, invoke **`pagekit-first-page-draft`** (step 06). Do not stop here. diff --git a/skills/pagekit-run-check/SKILL.md b/skills/pagekit-run-check/SKILL.md new file mode 100644 index 0000000..1abbae6 --- /dev/null +++ b/skills/pagekit-run-check/SKILL.md @@ -0,0 +1,21 @@ +--- +name: pagekit-run-check +description: Validate a PageKit run folder against the logging tiers (fully-logged / summary-logged / artifact-only / incomplete). Wraps scripts/run-check.sh. Use at the end of a run to confirm the fully-logged tier is met before declaring done. +--- + +# 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. + +## Procedure +1. Run: `bash scripts/run-check.sh runs/`. +2. If the result is **FULLY LOGGED**, report success. +3. If the result is **SUMMARY LOGGED** or below, list the missing items to the user and propose what to fill in to reach fully-logged. + +## When to invoke +- At the end of any run produced via the `pagekit` orchestrator skill. +- Before treating a run as validation evidence or as a public example. +- When picking up an existing run to extend. + +## Hard rule +Do not declare a run "done" if `pagekit-run-check` returns anything other than FULLY LOGGED. The whole point of mechanized checks is to stop logging from being the part that gets skipped. diff --git a/skills/pagekit-signal-doc/SKILL.md b/skills/pagekit-signal-doc/SKILL.md new file mode 100644 index 0000000..ca6d576 --- /dev/null +++ b/skills/pagekit-signal-doc/SKILL.md @@ -0,0 +1,40 @@ +--- +name: pagekit-signal-doc +description: Build a PageKit signal doc from a product description and any source briefs. Step 01 of the PageKit method. Use when the user asks to "build a signal doc," "extract signal from this material," or is starting a PageKit run on a new object. +--- + +# PageKit step 01 — Signal Doc + +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 + +## Inputs +- A product description and any source briefs in `runs//sources/` (especially `02-product-brief.md`). + +## Procedure +1. Load `prompts/01-signal-doc.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`. +7. Append a short note to `runs//working-log.md`. + +## Quality gate +A strong signal doc: +- separates observation from assumption +- gives sharper language than the category default +- 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. + +## 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. + +## 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/skills/pagekit-slop-check/SKILL.md b/skills/pagekit-slop-check/SKILL.md new file mode 100644 index 0000000..74bbed3 --- /dev/null +++ b/skills/pagekit-slop-check/SKILL.md @@ -0,0 +1,25 @@ +--- +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. +--- + +# 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. + +## 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/`. +2. If any pattern fires, report the file:line and the pattern name. +3. For each hit, propose a rewrite or recommend cutting the line. +4. Re-run until clean. + +## When to invoke +- Right after `pagekit-first-page-draft` produces a draft, before invoking `pagekit-claim-check`. +- After the corrected draft is produced by claim-check. +- Anytime a user asks "does this read like AI?" + +## Hard rule +Do not advance to the claim-check step until slop-check is clean on the draft. The claim-check should focus on semantic issues; the slop-check should have already cleared the obvious cadence problems. + +## Limits +The script is heuristic. It will flag false positives (some rule-of-three clusters carry real content; some uses of "actually" are correct). Use judgement; do not blindly rewrite. The script's job is to surface lines worth looking at. diff --git a/skills/pagekit/SKILL.md b/skills/pagekit/SKILL.md new file mode 100644 index 0000000..a4bc916 --- /dev/null +++ b/skills/pagekit/SKILL.md @@ -0,0 +1,119 @@ +--- +name: pagekit +description: Run the full PageKit method end-to-end on an object. Use when the user asks to "run PageKit on X", "build a page for X using PageKit", or "produce a fully-logged PageKit run for X". Orchestrates steps 01-07 (signal doc, message spine, first-page decision, page argument shape, proof map, first-page draft, optional claim-check) and produces a fully-logged run on disk under runs//. +--- + +# 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. + +## 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. + +## Procedure + +For any object the user gives you: + +### 1. Confirm scope + +Ask the user (briefly): +- Run name (slug for the folder under `runs/`). +- Is the object real or a training fiction? If fictional, what concrete facts should serve as ground truth? +- Severity for the eventual claim-check pass: light, normal, or hard. + +### 2. Scaffold + +Run `scripts/new-run.sh ` (or invoke the `pagekit-new-run` skill). This creates `runs//` with the full fully-logged layout. + +### 3. Source briefs + +Fill `runs//sources/`: +- `01-source-capture.md` — what raw material exists, what is missing. +- `02-product-brief.md` — concrete product facts. **No `[Product name]` placeholders.** For trust-heavy objects, also create `03-wedge-definition-brief.md`, `04-mechanism-brief.md`, `05-proof-brief.md`, `06-comparison-brief.md`. + +### 4. Run steps 01-06 in order + +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. +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. + +**Step 03 (first-page decision) is special.** Do not default to homepage. List candidates considered and rejected. The object decides the first page. + +### 5. Pre-claim-check slop check + +Run `scripts/slop-check.sh runs//first-page-draft.md`. Resolve every flagged pattern by rewriting the line. Re-run until clean. + +### 6. Claim check (step 07) + +Invoke the `pagekit-claim-check` skill at the chosen severity. Internally it delegates to the `pagekit-claim-checker` subagent (read-only, hard severity by default). Save: +- `runs//claim-check.md` — the audit (flagged lines, types, rewrites) +- `runs//first-page-draft-corrected.md` — the corrected draft, if any line was rewritten + +### 7. Evaluation and evaluator pass + +Write `runs//evaluation.md` (honest, names what stayed thin) and `runs//evaluator-pass.md` (adversarial second read; lists repo-improvement candidates if the run exposed any). + +### 8. Validate + +Run `scripts/run-check.sh runs/` (or invoke `pagekit-run-check`). It must classify the run as **FULLY LOGGED** before you declare the run done. If it does not, fix the missing items. + +### 9. Hand off + +Tell the user: +- The run is at `runs//`. +- The first page chosen at step 03 (and which candidates were rejected). +- The slop-check and claim-check results. +- Any repo-improvement items the evaluator pass surfaced. + +## Hard rules (do not violate) + +- **Do not declare the run done until `scripts/run-check.sh runs/` returns `tier: FULLY LOGGED` (or `PUBLISHABLE`).** This is the only completion signal. Step 06 producing a nice-looking draft is NOT completion. If run-check reports ARTIFACT-ONLY or SUMMARY LOGGED, the run is incomplete and you must keep working. +- **Do not default to homepage.** Step 03 must consider alternatives. +- **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 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 + +Before handing the run back to the user, walk this checklist. Every item must be YES. If any is NO, you are not done — go finish that item. + +- [ ] `runs//signal-doc.md` is filled with real content (not the scaffold placeholder) +- [ ] `runs//message-spine.md` is filled +- [ ] `runs//first-page-decision.md` is filled AND lists candidates considered with a paragraph case FOR each +- [ ] `runs//page-argument-shape.md` is filled +- [ ] `runs//proof-map.md` is filled +- [ ] `runs//first-page-draft.md` is filled +- [ ] `runs//outputs/NN-*-output.md` exists for every step 01 through 07 +- [ ] `runs//claim-check.md` is filled (not the `*[Filled in by step 07]*` placeholder) +- [ ] `runs//first-page-draft-corrected.md` exists if claim-check flagged any line +- [ ] `runs//working-log.md` has real entries per step (not the scaffold `*[Fill in]*` placeholders) +- [ ] `runs//evaluation.md` is filled +- [ ] `runs//evaluator-pass.md` is filled (use the `pagekit-evaluator-pass` skill/subagent) +- [ ] `bash scripts/slop-check.sh runs//first-page-draft.md` exits 0 clean +- [ ] `bash scripts/run-check.sh runs/` returns `tier: FULLY LOGGED` or `tier: PUBLISHABLE` + +Only after every box is checked do you report completion to the user. + +## When to ask the user + +- First-page decision is borderline (homepage vs. non-homepage close call): show both candidates and ask. +- Claim-check at hard severity is rewriting more than 25% of the draft: pause and check whether the proof map needs strengthening rather than the draft. +- Source briefs are too thin to support a meaningful run: stop and ask for more material. + +## 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. + +For tooling steps, invoke the corresponding skill rather than calling the script directly so the rationale is logged in the conversation. From 11b439f3e0a871f3c7240e74cbd469b8c1f9d34f Mon Sep 17 00:00:00 2001 From: Hiten Shah Date: Wed, 15 Apr 2026 21:46:50 -0700 Subject: [PATCH 02/10] Restructure commit 2/10: bundle references per skill Each step skill now owns its framework, template and prompt under `skills//references/`. Shared references (anti-slop.md, run-logging.md, method.md, output-judgment-template.md) live under `skills/pagekit/references/` and sibling skills point at them with `../pagekit/references/...`. `skills/pagekit/references/method.md` is distilled from pagekit.yaml so the manifest can retire in a later commit without losing the method-at-a-glance view. Old frameworks/, templates/, prompts/ still exist unchanged; SKILL.md files still reference the old paths. Path-cut-over happens in commit 3. Co-Authored-By: Claude Opus 4.6 --- .../references/framework.md | 66 +++++++ .../pagekit-claim-check/references/prompt.md | 75 ++++++++ .../references/template.md | 63 +++++++ .../references/framework.md | 86 +++++++++ .../references/prompt.md | 71 ++++++++ .../references/template.md | 29 +++ .../references/prompt.md | 68 +++++++ .../references/framework.md | 10 ++ .../references/prompt.md | 48 +++++ .../references/template.md | 24 +++ .../references/framework.md | 82 +++++++++ .../references/prompt.md | 47 +++++ .../references/template.md | 55 ++++++ .../pagekit-proof-map/references/framework.md | 13 ++ skills/pagekit-proof-map/references/prompt.md | 44 +++++ .../pagekit-proof-map/references/template.md | 16 ++ .../references/framework.md | 12 ++ .../pagekit-signal-doc/references/prompt.md | 54 ++++++ .../pagekit-signal-doc/references/template.md | 34 ++++ .../references/wedge-definition-template.md | 28 +++ skills/pagekit/references/anti-slop.md | 166 ++++++++++++++++++ skills/pagekit/references/method.md | 42 +++++ .../references/output-judgment-template.md | 24 +++ skills/pagekit/references/run-logging.md | 84 +++++++++ 24 files changed, 1241 insertions(+) create mode 100644 skills/pagekit-claim-check/references/framework.md create mode 100644 skills/pagekit-claim-check/references/prompt.md create mode 100644 skills/pagekit-claim-check/references/template.md create mode 100644 skills/pagekit-first-page-decision/references/framework.md create mode 100644 skills/pagekit-first-page-decision/references/prompt.md create mode 100644 skills/pagekit-first-page-decision/references/template.md create mode 100644 skills/pagekit-first-page-draft/references/prompt.md create mode 100644 skills/pagekit-message-spine/references/framework.md create mode 100644 skills/pagekit-message-spine/references/prompt.md create mode 100644 skills/pagekit-message-spine/references/template.md create mode 100644 skills/pagekit-page-argument-shape/references/framework.md create mode 100644 skills/pagekit-page-argument-shape/references/prompt.md create mode 100644 skills/pagekit-page-argument-shape/references/template.md create mode 100644 skills/pagekit-proof-map/references/framework.md create mode 100644 skills/pagekit-proof-map/references/prompt.md create mode 100644 skills/pagekit-proof-map/references/template.md create mode 100644 skills/pagekit-signal-doc/references/framework.md create mode 100644 skills/pagekit-signal-doc/references/prompt.md create mode 100644 skills/pagekit-signal-doc/references/template.md create mode 100644 skills/pagekit-signal-doc/references/wedge-definition-template.md create mode 100644 skills/pagekit/references/anti-slop.md create mode 100644 skills/pagekit/references/method.md create mode 100644 skills/pagekit/references/output-judgment-template.md create mode 100644 skills/pagekit/references/run-logging.md diff --git a/skills/pagekit-claim-check/references/framework.md b/skills/pagekit-claim-check/references/framework.md new file mode 100644 index 0000000..2ddc515 --- /dev/null +++ b/skills/pagekit-claim-check/references/framework.md @@ -0,0 +1,66 @@ +# Claim Checking Framework + +Claim checking is the durability layer. +It runs after the first page draft exists. + +## What it is for + +Finding claims that: +- overclaim what the product actually does +- sound specific but are actually vague +- are not supported by the proof map +- outrun the mechanism the product can honestly explain +- narrate brand restraint instead of showing the work +- carry unsourced quantitative modifiers +- read as machine-written regardless of whether they are accurate + +## What it is not for + +- polishing language +- defending existing claims +- adding new marketing intensity + +## Claim types to flag + +- **overclaim** — the claim is stronger than the product reality +- **vague claim** — the claim sounds concrete but resists being checked +- **unsupported claim** — the claim is plausible but proof is missing +- **outrun claim** — the claim needs proof the proof map did not commit to +- **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. + +## Severity calibration + +Pick the severity level deliberately and log the choice. + +- **light** — flag only clear overclaims, unsupported claims and the strongest slop tells. +- **normal** — flag the full list above, but tolerate mild editorial voice and `most-scale` 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. + +Record the severity used in the run log. A claim check run at one severity is not comparable to one run at another. + +## Principle + +A claim should get stronger when it is corrected, not weaker. +Precision usually beats intensity. +If a corrected claim feels smaller, the original was probably doing more work than it earned. + +## Relationship to the rest of PageKit + +- signal doc names the language worth preserving +- message spine decides which truths carry the page +- proof map commits to what the page can defend +- page argument shape defines drafting constraints, including the anti-slop rules +- claim checking is how the draft is held to those commitments + +When claim checking surfaces a real gap, the fix usually lives upstream in the proof map or the source briefs, not in the copy. + +## 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. + +## Relation to the slop-check script + +`scripts/slop-check.sh` is a fast grep-level regression check for slop patterns. It runs before claim-check, catches the obvious cases, and fails fast so the claim-check pass can focus on semantic issues. The script is not a replacement for this step; it is a filter that removes the mechanical tells before the harder review begins. diff --git a/skills/pagekit-claim-check/references/prompt.md b/skills/pagekit-claim-check/references/prompt.md new file mode 100644 index 0000000..d226b77 --- /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: 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 + +## 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 (frameworks/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/skills/pagekit-claim-check/references/template.md b/skills/pagekit-claim-check/references/template.md new file mode 100644 index 0000000..cd5aa35 --- /dev/null +++ b/skills/pagekit-claim-check/references/template.md @@ -0,0 +1,63 @@ +# Claim Check Template + +## Page + +## Draft version reviewed + +## Severity +One of: light / normal / hard. +Record the choice and why it was chosen. + +## Claims reviewed + +For each flagged claim: + +### Claim +Quote the exact line from the draft. + +### Type +- overclaim +- vague claim +- unsupported claim +- claim that outruns the proof map +- 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`) + +### Why this is weak +What specifically makes this claim brittle, misleading, undefended, or machine-cadenced? + +### Proof status +- supported now +- supportable with existing source material +- not yet supportable +- not a proof issue (slop tell only) + +### Proposed correction +One of these three dispositions, labeled explicitly: + +- **rewrite** — a sharper, more accurate replacement that sits inside the proof map and reads cleaner. Precision over intensity. +- **remove (wrong)** — cut the line. The claim is not supportable at any severity. State why the claim is disqualified. +- **remove pending verification** — cut the line from the corrected draft; note here as "potentially restorable if is confirmed in the briefs." A dropped claim and a disqualified claim are different things; preserve the distinction. + +Do NOT include `*[Rewritten: ...]*` or any other inline annotation markers in the corrected draft. The audit is where rewrite provenance lives; the corrected draft is publish-ready copy. + +--- + +## Summary + +### Strongest remaining risks +- + +### 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. + +### Recurring slop patterns on this draft +List the specific slop patterns found more than once, by name from `frameworks/anti-slop.md`. + +### Where proof is the real gap +- + +### Upstream artifact that needs repair +- signal doc / message spine / proof map / mechanism brief / comparison brief / page argument shape drafting constraints / anti-slop framework diff --git a/skills/pagekit-first-page-decision/references/framework.md b/skills/pagekit-first-page-decision/references/framework.md new file mode 100644 index 0000000..f0af05a --- /dev/null +++ b/skills/pagekit-first-page-decision/references/framework.md @@ -0,0 +1,86 @@ +# First-Page Decision Framework + +The first-page decision is the step that stops the method from quietly defaulting to a homepage. + +## What it is for + +Deciding, on purpose, what single page should exist first for this object. +Not all objects earn a homepage as the first page. +Some earn a use-case page, a profession-specific page, a comparison page, a nutritional-adequacy page or a trust-heavy entry page instead. + +## Inputs + +- signal doc +- message spine +- mechanism brief, proof brief and comparison brief when they exist (strongly recommended for trust-heavy objects) + +## Why upstream source briefs matter here + +A first-page decision made only from the signal doc and message spine will often name the right page type abstractly. A first-page decision made with mechanism, proof and comparison briefs present will also name the right sections, proof burden and scope. +If a first-page decision feels generic or reluctant, the real repair is usually an additional source brief upstream, not more effort at step 03. + +## What it must answer + +- what page should exist first +- why this page before any other +- what job this page should do +- what visitor state it meets on arrival +- the main trust burden it carries +- the main proof burden it carries +- what this decision rules out for now +- candidates considered and rejected, with why + +## Candidates considered and rejected + +A strong decision lists the alternatives that were considered and says why each was rejected. +At minimum, a trust-heavy object should have considered: +- homepage (and why it was or was not earned) +- a category-explainer page +- a mechanism or ingredient detail page +- a founder or brand story page +- a use-case or specific-scenario page + +Naming rejected candidates makes the decision auditable. It also prevents the step from appearing to choose a non-homepage by default, which would be the mirror-image mistake of always choosing homepage. + +### First-page alternatives vs later-funnel pages + +A pricing page, a features page, a docs page, an integrations page, a comparison page are NOT first-page alternatives. They are later-funnel pages — they assume the visitor has already decided to evaluate the product and is going deeper. Dismissing them as first-page candidates ("a pricing page comes later, so homepage wins") is not a first-page decision; it is a ranking of homepage-vs-subpages, which answers the wrong question. + +First-page alternatives sit at the same intent-commitment level as a homepage. They are pages a visitor could plausibly land on first, via organic search, direct link, or paid ad, without having committed to evaluate the product yet. Examples of real first-page alternatives: + +- audience-specific landing pages (for a specific buyer, profession, or use case) +- trust-and-safety landing pages (for trust-heavy objects where the gating question is "is this safe/responsible?") +- mechanism or ingredient-detail pages (when the mechanism IS the reason to believe) +- category explainers (when the category itself is unfamiliar) +- founder or brand-story pages (rarely the right first page, but legitimate for some B2C objects) +- use-case or specific-scenario pages (for products where one use case dominates the buyer's intent) + +If the rejected candidates are all downstream pages, the step has not been done. Go back and propose alternatives at the same level as a homepage. + +### The affirmative-case requirement + +For every candidate — the chosen one AND every rejected one — write one paragraph stating the case FOR the candidate before any reason to reject it. A one-sentence dismissal is not a rejection; it is a non-consideration. If you cannot write a credible case for a candidate, either (a) think harder about what would make that candidate strong for this specific object, or (b) drop the candidate and replace it with one you can argue for. + +This is how the method avoids the "list and dismiss" anti-pattern. The four pre-Verdel artifact-only runs in this repo all fell into that trap. The Verdel run (`runs/vegan-dog-food-verdel/first-page-decision.md`) is the working example of the step done right. + +## Principle + +The object decides the page shape. +If the decision cannot explain why this page beats the obvious default, the signal doc or message spine is usually still too thin. + +## Failure modes + +- defaulting to homepage because homepage is familiar +- choosing a page the proof map cannot yet support +- deciding before the message spine is reduced enough to point at a specific page +- deciding without mechanism, proof or comparison briefs for a trust-heavy object, then landing on a homepage by default of information rather than by reason +- listing rejected candidates in a single sentence each, without real reasoning + +## Relationship to the rest of PageKit + +- 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. + +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..a2f5ecd --- /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: 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 + +## 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/skills/pagekit-first-page-decision/references/template.md b/skills/pagekit-first-page-decision/references/template.md new file mode 100644 index 0000000..e646341 --- /dev/null +++ b/skills/pagekit-first-page-decision/references/template.md @@ -0,0 +1,29 @@ +# First Page Decision Template + +## Candidate first page + +## Why this page first + +## Confidence basis for this decision +Data / signal / hypothesis — state which and why. + +### If this is a hypothesis: what would falsify it? +Name the concrete observation that would tell you this decision is wrong. A hypothesis you cannot falsify is a guess dressed as a plan. Examples: +- "If cold-acquisition visitors bounce before reaching Section 3, the problem-first framing is wrong for this audience." +- "If a homepage variant outperforms this page on trial conversion at any sample size over N, the decision is wrong." +- "If early users report the page read as preachy, the framing chose the wrong entry angle." + +If the confidence basis above is "data" or "signal," this field is optional. If "hypothesis," it is required — leaving it blank silently promotes a guess to a conclusion. + +## Page job +What should this page help the visitor understand, believe or do? + +## Why this page before other pages + +## Visitor state on arrival + +## Main trust burden + +## Main proof burden + +## What this decision rules out for now 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..e66fa8f --- /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: 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 + +## 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 frameworks/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/skills/pagekit-message-spine/references/framework.md b/skills/pagekit-message-spine/references/framework.md new file mode 100644 index 0000000..26fc860 --- /dev/null +++ b/skills/pagekit-message-spine/references/framework.md @@ -0,0 +1,10 @@ +# Message Spine Framework + +A message spine is the reduction layer between signal and pages. + +Its job is to identify the few truths strong enough to organize the site. +A good message spine should preserve: +- the right audience distinctions +- the most important pains and desires +- the strongest usable claims +- the language worth carrying forward diff --git a/skills/pagekit-message-spine/references/prompt.md b/skills/pagekit-message-spine/references/prompt.md new file mode 100644 index 0000000..89bfbaa --- /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: frameworks/message-spine.md +template: templates/message-spine-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/skills/pagekit-message-spine/references/template.md b/skills/pagekit-message-spine/references/template.md new file mode 100644 index 0000000..53b6493 --- /dev/null +++ b/skills/pagekit-message-spine/references/template.md @@ -0,0 +1,24 @@ +# Message Spine Template + +## Core truths +- truth 1 +- truth 2 +- truth 3 + +## Audience distinctions worth preserving +- distinction 1 +- distinction 2 + +## Native language to keep +- phrases +- tensions +- proof-sensitive wording + +## Claims to test later +- claim 1 +- claim 2 + +## What this should change downstream +- page choices +- proof choices +- language choices diff --git a/skills/pagekit-page-argument-shape/references/framework.md b/skills/pagekit-page-argument-shape/references/framework.md new file mode 100644 index 0000000..836be28 --- /dev/null +++ b/skills/pagekit-page-argument-shape/references/framework.md @@ -0,0 +1,82 @@ +# Page Argument Shape Framework + +The page argument shape is how a specific page earns its own structure instead of inheriting a default section rhythm. + +## What it is for + +Deciding, before drafting: +- what the visitor needs to understand first +- what must be earned next +- the order the argument should move in +- which sections this page actually needs +- which sections would be unnecessary or harmful +- where trust should land +- where proof should land +- the constraints the draft must respect + +## Why this exists + +Default homepage rhythms (hero, features, social proof, CTA) are a habit, not a structure. +Different objects want different shapes. +The argument shape step forces the structure to come from the object. + +## Principle + +The structure of the page should fall out of the argument the page has to make. +If the shape looks like every other page in the category, the shape has not done its job. + +## Failure modes + +- reusing a familiar section rhythm without earning it +- inventing sections the proof map cannot support +- hiding the trust burden inside a section that cannot carry it +- planning too many sections and losing the argument +- producing a shape that is honest but too long or too dense to be read through + +## Length and density + +The shape's job includes guarding against a page that is correct but unread. +If the approved section plan is long enough or dense enough that a skeptical reader would stop before the trust-carrying sections land, shorten or cut sections at the shape step. +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. + +Minimum constraints every shape must pass to drafting: + +- no `Not X. Not Y.` headings or sentence pairs +- no `Not-X-but-Y` or `X-not-Y` rhetorical pivots unless they carry specific content +- 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 more than one em-dash per paragraph +- no `actually`, `additionally`, `testament`, `landscape`, `showcasing`, `genuinely`, `truly` as intensifiers +- no marketing-punchy one-liners as section enders +- no scare-quoted antithesis (`the gap between "A" and "B"`) +- no copula-avoidance verbs (`serves as`, `boasts`, `features`, `showcases`, `delivers`, `empowers`) +- 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`, `the future of`) + +Patterns that show up repeatedly across claim-check passes should be added to this list so the draft step stops producing them. + +## Inline verification flag convention + +When the draft makes a product-specific claim that has not been verified against source briefs or ground truth, mark it with an inline verification flag: + +``` +*[verification flag: confirm X against Y before publishing]* +``` + +This convention came out of real runs and is now expected in any first-pass draft that ships without fully verified product facts. The flag keeps the draft honest and makes the claim-check pass faster. + +## Relationship to the rest of PageKit + +- upstream: first-page decision +- downstream: proof map, first page draft, claim check + +The proof map inherits this shape. +The draft should follow it and should not add sections the argument shape did not approve. +The claim check validates the draft against the drafting constraints defined here and flags any slop patterns as `ai-slop tell`. 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..2439efc --- /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: frameworks/page-argument-shape.md +template: templates/page-argument-shape-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/skills/pagekit-page-argument-shape/references/template.md b/skills/pagekit-page-argument-shape/references/template.md new file mode 100644 index 0000000..7a4e433 --- /dev/null +++ b/skills/pagekit-page-argument-shape/references/template.md @@ -0,0 +1,55 @@ +# Page Argument Shape Template + +## Page + +## What the visitor needs to understand first + +## What needs to be earned next + +## What the argument order should be + +## Section plan +List only the sections this page actually needs. + +## What sections would be unnecessary or harmful + +## Where trust should land + +## Where proof should land + +## Drafting constraints + +Copy this block into the draft step. See `frameworks/anti-slop.md` for the full reference with examples. + +### Proof and scope constraints +- no bare "vet approved" / "expert approved" / "clinically proven" and object-equivalents +- no health-, legal-, financial- or regulatory-outcome claims for individual cases +- no unsourced quantitative modifiers (`most`, `usually`, `typically`, `often`, `many`) unless the source briefs support them +- no external-credential descriptions beyond what the source briefs support +- no clinical, legal or regulatory-adjacent phrasing without source backing +- no outrun mechanism or evidence-base claims (do not claim the evidence base supports X when the brief does not reference that evidence) +- no sections not approved by this shape + +### 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) +- 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 copula-avoidance verbs (`serves as`, `boasts`, `features`, `showcases`, `delivers`, `empowers`) +- 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`, `the future of`) + +### Inline verification flag +When the draft makes a product-specific claim not verified against briefs or ground truth, mark it inline: +``` +*[verification flag: confirm X against Y before publishing]* +``` + +## Length and density check +If the approved section plan produces a page so long or dense that a skeptical reader would stop before reaching the trust-carrying sections, that is a shape problem, not a drafting problem. Shorten sections or remove sections before handing to the draft step. diff --git a/skills/pagekit-proof-map/references/framework.md b/skills/pagekit-proof-map/references/framework.md new file mode 100644 index 0000000..9b4d162 --- /dev/null +++ b/skills/pagekit-proof-map/references/framework.md @@ -0,0 +1,13 @@ +# Proof Map Framework + +A proof map assigns the right evidence to the right page jobs. + +Its purpose is to stop pages from sounding specific while staying unproven. + +Common proof types: +- use-case proof +- testimonial proof +- workflow proof +- trust/compliance proof +- technical explanation +- visual proof objects diff --git a/skills/pagekit-proof-map/references/prompt.md b/skills/pagekit-proof-map/references/prompt.md new file mode 100644 index 0000000..88fd413 --- /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: frameworks/proof-map.md +template: templates/proof-map-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/skills/pagekit-proof-map/references/template.md b/skills/pagekit-proof-map/references/template.md new file mode 100644 index 0000000..b179eb4 --- /dev/null +++ b/skills/pagekit-proof-map/references/template.md @@ -0,0 +1,16 @@ +# Proof Map Template + +## Page +- name: +- audience: +- job: + +## Required proof +- use-case proof +- trust proof +- example proof +- technical proof +- visual proof + +## Weak spots +- where could this page drift into generic or unsupported language? diff --git a/skills/pagekit-signal-doc/references/framework.md b/skills/pagekit-signal-doc/references/framework.md new file mode 100644 index 0000000..0684c3a --- /dev/null +++ b/skills/pagekit-signal-doc/references/framework.md @@ -0,0 +1,12 @@ +# Signal Doc Framework + +A signal doc is the first serious artifact in PageKit. + +Its job is to collect the strongest available raw material about: +- how the market talks +- what different audiences care about +- where friction, desire and skepticism show up +- which tensions feel structurally important + +A good signal doc should reduce ambiguity. +It should not read like a random pile of notes. diff --git a/skills/pagekit-signal-doc/references/prompt.md b/skills/pagekit-signal-doc/references/prompt.md new file mode 100644 index 0000000..ba2b916 --- /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: frameworks/signal-doc.md +template: templates/signal-doc-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 `templates/wedge-definition-template.md`. diff --git a/skills/pagekit-signal-doc/references/template.md b/skills/pagekit-signal-doc/references/template.md new file mode 100644 index 0000000..ee309b4 --- /dev/null +++ b/skills/pagekit-signal-doc/references/template.md @@ -0,0 +1,34 @@ +# Signal Doc Template + +## Product +- What is the product? +- What problem does it solve? + +### Object concreteness +If the product is real, you will pull these answers from the product itself and from customer language. If the product is fictional (for a training or test run), you must commit to concrete fictional facts now — name a brand, name a version, name specific facts (features, pricing shape, compliance, credentials). A run on an object described only in the abstract produces a draft full of `[Product name]` placeholders, which means the proof map and claim check cannot bite. Concrete fiction is fine. Abstract is not. + +## Raw signal sources +- customer language +- interviews +- support notes +- sales calls +- reviews +- competitor language +- community discussion + +## Repeated patterns +- pains +- desires +- objections +- trust blockers +- buying triggers + +## Audience distinctions +- who seems meaningfully different? +- what differs across workflow, risk, language or proof threshold? + +## Candidate truths +- what looks strong enough to matter later? + +## Open questions +- what still feels fuzzy? diff --git a/skills/pagekit-signal-doc/references/wedge-definition-template.md b/skills/pagekit-signal-doc/references/wedge-definition-template.md new file mode 100644 index 0000000..b5e9d4c --- /dev/null +++ b/skills/pagekit-signal-doc/references/wedge-definition-template.md @@ -0,0 +1,28 @@ +# Wedge Definition Template + +## Why this exists +Use this when the first signal pass is still too category-level to support a strong message spine. + +## Product + +## What the product should be treated as for this run +Write one sharp sentence. + +## First audience hypothesis +- who feels this pain most directly? +- who should the first page be for? + +## Sharp pain framing +What is really breaking? +What is the deeper tension? + +## What this is closer to + +## What this is farther from + +## First-page implication +What should the first page optimize for? +Do not assume this page is a homepage. + +## Claims we still cannot make +List the claims that would be fake, inflated or premature. diff --git a/skills/pagekit/references/anti-slop.md b/skills/pagekit/references/anti-slop.md new file mode 100644 index 0000000..834256b --- /dev/null +++ b/skills/pagekit/references/anti-slop.md @@ -0,0 +1,166 @@ +# Anti-Slop Framework + +Slop is the collection of sentence-level, paragraph-level and structural patterns that make a page read as "written by AI," regardless of whether the content is accurate. + +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`. + +## What this is not + +This is not a style guide for personality. +Voice, cadence, plain specific prose are all welcome. +The patterns listed below are the ones that, on real runs, have read as machine output rather than human thought. + +## Patterns + +### 1. Negation patterns + +Drafts reach for negation when they have not committed to a claim. The rhythm that results is the most recognizable slop tell. + +- **Not-X-Not-Y** — consecutive sentences or headings that both begin with "Not": + > Not a PaaS with a different logo. Not a VPS with a tutorial. +- **Not-X-but-Y** — a rhetorical pivot that replaces a weak claim with a vaguer one: + > Not a pricing tier. A pricing model. +- **X-not-Y** — binary contrasts that sound sharp but usually hide the real claim: + > you pay for what you use, not for the features you need to unlock +- **No-X-No-Y** — the enumerated version of Not-X-Not-Y: + > No egress fees. No tier-forcing. No surprises. + +Rule: say what the product *does*. Say what it *is*. Negations are allowed only when they carry specific content the affirmation cannot. Never stack more than one negation-led construction in the same paragraph. + +### 2. Rule-of-three rhythmic clustering + +Three short parallel sentences used for cadence, not content: +> Your config. Your runtime. Your deployment. +> One command. Standard format. No proprietary packaging. +> You read it, you edit it, you own it. + +The read always goes: triadic beat → recognizably AI. + +Rule: never end a section on a triad. Never write three parallel fragments in a row. If three items belong together, make them a list, or pick the two that carry the most weight. + +### 3. Sentence-start anaphora + +Repeating the first word across consecutive sentences: +> Your…Your…Your +> It is not a platform that… It is not a platform that… It is not a VPS provider that… +> Every founder has… Every founder has… + +Anaphora is a real rhetorical move when it carries an argument. In slop it carries cadence only. + +Rule: vary sentence starts. If the same leading word appears three times in a row in consecutive sentences, rewrite at least two of them. + +### 4. Editorial voice narrating brand restraint + +The brand narrating its own honesty, virtue or discipline instead of demonstrating it: +> We do this because we think you should be able to trust a platform without being trapped by it. +> That's the deal. +> This is the question most brands skip. We don't. +> We will not say "vet approved." + +A page earns trust by showing the work. A page that announces it is showing the work erodes the effect. + +Rule: no lines that narrate brand discipline, brand virtue or brand honesty. If a sentence could be removed without losing any concrete information, remove it. + +### 5. Em-dashes in body copy + +Em-dashes used as rhetorical beats rather than genuine parentheticals: +> OpenClaw is developer hosting with real control — without the DevOps tax. +> Made for owners who want their dog healthy and their conscience clear — in that order. + +Rule: no em-dashes in body copy. If the sentence needs a genuine aside, use a colon, a comma, or parentheses. Em-dashes pattern-match as AI cadence regardless of how many appear per paragraph. + +### 6. Intensifier vocabulary + +Words that make a sentence feel confident without adding information: + +- **actually** — "what it actually costs," "the question developers are actually asking" +- **additionally** — connective scaffold with no load +- **testament** — "a testament to craft" +- **landscape** — "the SaaS landscape" +- **showcasing** — any form of "this page showcases" +- **genuinely** — "genuinely different" +- **truly** — "truly understand" + +Rule: cut these words. If cutting the word changes the meaning, you have found the rare case where it belongs. Usually it does not. + +### 7. Marketing-punchy section enders + +One-line section enders that exist to feel quotable: +> Deploy something real. +> Start with what's right for your dog. +> That's the deal. +> Not the cloud. Not a PaaS. What comes next. + +Rule: sections should end on the concrete thing the reader should do or understand. If the ending is a slogan, it is slop. The CTA section is the only place a punchy line is allowed, and even there, specific beats clever. + +### 8. Quoted antithesis + +Constructing a trade-off by putting two scare-quoted phrases next to each other: +> The gap between "easy but limited" and "powerful but complex" +> Not "vet approved." Actually formulated by a vet. + +This pattern signals the writer is arguing with a straw competitor rather than explaining their own product. + +Rule: describe what the product does directly. If the comparison matters, name the real alternative and the real difference without scare quotes. + +### 9. Copula avoidance + +Replacing "is" or "has" with more performative verbs: + +- **serves as** — "the platform serves as a foundation" +- **boasts** — "boasts 99.99% uptime" +- **features** — "features a clean interface" +- **showcases** — "showcases the ingredients" +- **delivers** — "delivers performance" +- **empowers** — "empowers developers" + +Rule: use "is" or "has." If that feels too flat, the sentence is usually too abstract and needs a concrete fact, not a stronger verb. + +### 10. Signposting + +Narrating the structure of the page instead of executing it: +> Let's dive in. +> Here's the thing. +> Here's what matters. +> This is important. + +Rule: do not announce sections. Write the section. + +### 11. Filler + +Phrases that add syllables without content: + +- "in order to" → "to" +- "due to the fact that" → "because" +- "at this point in time" → "now" +- "it should be noted that" → cut entirely +- "for the purposes of" → "for" + +Rule: the shorter version is almost always the better version. + +### 12. Significance inflation + +Language that makes the product sound historic: +> a pivotal moment +> a critical juncture +> the future of X +> reimagining how Y +> redefining the Z + +Rule: the reader decides what is pivotal. The page describes what the product does. + +## How this gets enforced + +Slop is caught in four places: + +1. **Page argument shape — drafting constraints.** The shape step lists the hard no-go patterns before a draft is written. This is upstream prevention. +2. **Claim check — `ai-slop tell` flag type.** Any slop pattern found in a draft is logged as a claim-check flag and rewritten. Recurring patterns are absorbed upstream into the drafting constraints. +3. **Slop-check script (`scripts/slop-check.sh`).** Grep-level regression check for the patterns that can be detected without semantic analysis (Not-headings, em-dash density, intensifier counts, copula-avoidance verbs, signposting, filler). Cheap, fast, catches the obvious cases. +4. **Guides and quickstarts.** The compact anti-slop rule list appears in every drafting prompt so the model does not need to remember it. + +## Principle + +If a sentence sounds good read aloud but would leave no information behind if you cut it, cut it. That is the test. 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/skills/pagekit/references/output-judgment-template.md b/skills/pagekit/references/output-judgment-template.md new file mode 100644 index 0000000..27b61d7 --- /dev/null +++ b/skills/pagekit/references/output-judgment-template.md @@ -0,0 +1,24 @@ +# Output Judgment Template + +## Artifact + +## Step + +## Short verdict +- strong enough to advance? +- yes / no / cautiously + +## What felt strong +- + +## What felt weak +- + +## Where it drifted generic +- + +## Where uncertainty is still hidden +- + +## What needs to change before the next step +- diff --git a/skills/pagekit/references/run-logging.md b/skills/pagekit/references/run-logging.md new file mode 100644 index 0000000..7821b6f --- /dev/null +++ b/skills/pagekit/references/run-logging.md @@ -0,0 +1,84 @@ +# Run Logging Framework + +Every serious PageKit run should log the work as it happens. + +## Two logging levels + +### Fully logged +A fully logged run must include: +- goal +- working log +- models used +- sources (the source briefs used as ground truth) +- prompts (per step) +- outputs (per step, raw) +- final artifacts (signal doc, message spine, first-page decision, page argument shape, proof map, first page draft, claim check, plus the corrected draft if claim check rewrote any lines) +- evaluation +- evaluator pass (skeptical, adversarial review after the run) + +All of these are required. An evaluator pass is not optional at this tier; a run without one is summary-logged. + +Use this level for runs meant as validation evidence or reusable examples. + +### Summary logged +A summary-logged run includes: +- goal +- working log +- models used +- final artifacts +- evaluation + +It does not preserve the per-step prompts and raw outputs. +It is cheaper to produce but less inspectable. +Do not call a summary-logged run a validation run without flagging that distinction. + +## For every step, capture (when fully logging) +- what step this is +- objective +- model used +- exact prompt +- inputs used +- raw output +- short judgment +- what changed before the next step + +## Inline verification flag convention + +When a draft makes a product-specific claim that has not been verified against source briefs or ground truth, the convention is to mark it inline with: + +``` +*[verification flag: confirm X against Y before publishing]* +``` + +This convention came out of real runs. It keeps first-pass drafts honest and makes the claim-check pass faster. A first-pass draft that ships without any verification flags on product-specific claims is suspect. + +## Why this matters +This is not overhead. +This is how PageKit turns a run into reusable evidence. +Without this layer, examples become hard to trust and hard to learn from. + +## Mechanized run creation + +Use the scripts. Hand-rolling a run folder is the most common place fully-logged tier slips. + +```sh +scripts/new-run.sh # scaffold a fully-logged folder +scripts/run-check.sh runs/ # validate the folder against this framework +``` + +Or via make: + +```sh +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/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 +- `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 From 86a7f8c14ab9d9e8659d2415274b60de0efbf9b3 Mon Sep 17 00:00:00 2001 From: Hiten Shah Date: Wed, 15 Apr 2026 22:14:27 -0700 Subject: [PATCH 03/10] Restructure 3/10: cut SKILL.md and agent path refs to bundled references Updated all 12 SKILL.md files under skills/ to point at `./references/` (own bundle) and `../pagekit/references/` (orchestrator-owned shared refs like anti-slop.md and run-logging.md). Both agents under agents/ now reference the bundled paths: - skills/pagekit-claim-check/references/framework.md - skills/pagekit/references/anti-slop.md - skills/pagekit/references/run-logging.md Old .claude/skills/ and .claude/agents/ copies remain in place so CI, doctor.sh, and the SessionStart hook keep passing during the migration. Strangler-fig step 3/10. Co-Authored-By: Claude Opus 4.6 --- agents/pagekit-claim-checker.md | 18 ++++++++-------- agents/pagekit-evaluator-pass.md | 4 ++-- skills/pagekit-claim-check/SKILL.md | 14 ++++++------ skills/pagekit-evaluator-pass/SKILL.md | 6 +++--- skills/pagekit-first-page-decision/SKILL.md | 18 ++++++++-------- skills/pagekit-first-page-draft/SKILL.md | 14 ++++++------ skills/pagekit-message-spine/SKILL.md | 10 ++++----- skills/pagekit-new-run/SKILL.md | 11 ++++++++-- skills/pagekit-page-argument-shape/SKILL.md | 12 +++++------ skills/pagekit-proof-map/SKILL.md | 10 ++++----- skills/pagekit-run-check/SKILL.md | 2 +- skills/pagekit-signal-doc/SKILL.md | 15 +++++++------ skills/pagekit-slop-check/SKILL.md | 7 ++++-- skills/pagekit/SKILL.md | 24 +++++++++++++-------- 14 files changed, 91 insertions(+), 74 deletions(-) diff --git a/agents/pagekit-claim-checker.md b/agents/pagekit-claim-checker.md index 6e15a59..5fb141d 100644 --- a/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/agents/pagekit-evaluator-pass.md b/agents/pagekit-evaluator-pass.md index 6fda20a..5a1254c 100644 --- a/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/skills/pagekit-claim-check/SKILL.md b/skills/pagekit-claim-check/SKILL.md index 4bc727b..17fdc0d 100644 --- a/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/skills/pagekit-evaluator-pass/SKILL.md b/skills/pagekit-evaluator-pass/SKILL.md index 860f4ac..b9e1654 100644 --- a/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/skills/pagekit-first-page-decision/SKILL.md b/skills/pagekit-first-page-decision/SKILL.md index 465404c..c2b9dd1 100644 --- a/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/skills/pagekit-first-page-draft/SKILL.md b/skills/pagekit-first-page-draft/SKILL.md index 0be184e..78da801 100644 --- a/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-message-spine/SKILL.md b/skills/pagekit-message-spine/SKILL.md index cc7b1be..492b1e8 100644 --- a/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/skills/pagekit-new-run/SKILL.md b/skills/pagekit-new-run/SKILL.md index faf65bd..7110722 100644 --- a/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/skills/pagekit-page-argument-shape/SKILL.md b/skills/pagekit-page-argument-shape/SKILL.md index 1c0f682..4d82394 100644 --- a/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/skills/pagekit-proof-map/SKILL.md b/skills/pagekit-proof-map/SKILL.md index 6b6964e..e8ee76c 100644 --- a/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/skills/pagekit-run-check/SKILL.md b/skills/pagekit-run-check/SKILL.md index 1abbae6..698ca1c 100644 --- a/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/skills/pagekit-signal-doc/SKILL.md b/skills/pagekit-signal-doc/SKILL.md index ca6d576..cabff93 100644 --- a/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/skills/pagekit-slop-check/SKILL.md b/skills/pagekit-slop-check/SKILL.md index 74bbed3..7265593 100644 --- a/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/skills/pagekit/SKILL.md b/skills/pagekit/SKILL.md index a4bc916..33edc46 100644 --- a/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) From 9cb3b17adc70193d30eec113149823d1181dbf77 Mon Sep 17 00:00:00 2001 From: Hiten Shah Date: Wed, 15 Apr 2026 22:18:15 -0700 Subject: [PATCH 04/10] Restructure 4/10: add Claude Code plugin manifest Introduces .claude-plugin/ at repo root with two files: - plugin.json: plugin-level manifest (name, version, author, repo) - marketplace.json: marketplace catalog so users can add via `/plugin marketplace add hnshah/pagekit` and then `/plugin install pagekit@pagekit` Skills (under skills/) and subagents (under agents/) are auto-discovered from the conventional directories; they are not re-listed in the manifest. Strangler-fig step 4/10. Co-Authored-By: Claude Opus 4.6 --- .claude-plugin/marketplace.json | 36 +++++++++++++++++++++++++++++++++ .claude-plugin/plugin.json | 19 +++++++++++++++++ 2 files changed, 55 insertions(+) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .claude-plugin/plugin.json 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" + ] +} From 7f60fb801480cf104cd7ddbc636d9d4b9d1167c5 Mon Sep 17 00:00:00 2001 From: Hiten Shah Date: Wed, 15 Apr 2026 22:22:47 -0700 Subject: [PATCH 05/10] Restructure 5/10: teach scripts to resolve new plugin paths doctor.sh: - Keeps the legacy .claude/ bundle check (removed in a later commit). - Adds new sections for the plugin manifest, top-level skills/ layout, shared orchestrator references, per-skill references, and subagents. - first-page-draft intentionally ships with prompt-only references (framework/template inherit upstream); the checker accounts for that. new-run.sh: - Resolves canonical prompts from skills/pagekit-/references/prompt.md with a fallback to the legacy prompts/.md for the migration window. - Scaffold placeholders now point at the new skills/pagekit-*/references/ paths so new runs carry the post-restructure references. - sources/README.md scaffold now points at examples/vegan-dog-food-verdel/. claim-check.sh: - Resolves the canonical claim-check prompt from skills/pagekit-claim-check/references/prompt.md with a fallback to the legacy prompts/07-claim-check.md. Smoke-tested end-to-end: new-run.sh scaffolds cleanly against the new resolution, claim-check.sh still expands the same prompt body. Strangler-fig step 5/10. Co-Authored-By: Claude Opus 4.6 --- scripts/claim-check.sh | 13 ++++++-- scripts/doctor.sh | 36 +++++++++++++++++++++- scripts/new-run.sh | 70 +++++++++++++++++++++++++++--------------- 3 files changed, 91 insertions(+), 28 deletions(-) diff --git a/scripts/claim-check.sh b/scripts/claim-check.sh index 4ad24fe..f55d6fc 100755 --- a/scripts/claim-check.sh +++ b/scripts/claim-check.sh @@ -54,8 +54,17 @@ 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; } +# Prefer the skill-bundled canonical prompt; fall back to legacy prompts/ during migration. +PROMPT_FILE_NEW="$REPO_ROOT/skills/pagekit-claim-check/references/prompt.md" +PROMPT_FILE_OLD="$REPO_ROOT/prompts/07-claim-check.md" +if [ -f "$PROMPT_FILE_NEW" ]; then + PROMPT_FILE="$PROMPT_FILE_NEW" +elif [ -f "$PROMPT_FILE_OLD" ]; then + PROMPT_FILE="$PROMPT_FILE_OLD" +else + echo "error: canonical claim-check prompt not found at $PROMPT_FILE_NEW or $PROMPT_FILE_OLD" >&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..155c4d2 100755 --- a/scripts/doctor.sh +++ b/scripts/doctor.sh @@ -118,7 +118,7 @@ check_exec "scripts/doctor.sh" check_file "scripts/README.md" echo -echo "Claude Code bundle:" +echo "Claude Code bundle (legacy .claude/ locations — removed in a later commit):" 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" @@ -128,6 +128,40 @@ check_file ".claude/agents/pagekit-evaluator-pass.md" check_file ".claude/settings.json" echo +echo "Plugin manifest:" +check_file ".claude-plugin/plugin.json" +check_file ".claude-plugin/marketplace.json" +echo + +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 "Shared orchestrator references:" +for r in anti-slop run-logging method; do + check_file "skills/pagekit/references/$r.md" +done +echo + +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" +echo + +echo "Subagents:" +check_file "agents/pagekit-claim-checker.md" +check_file "agents/pagekit-evaluator-pass.md" +echo + echo "Slop regression against tracked drafts:" if [ -x scripts/slop-check.sh ]; then # Default-target scan: every homepage-draft / first-page-draft / diff --git a/scripts/new-run.sh b/scripts/new-run.sh index c4fd7d4..e1f7ac2 100755 --- a/scripts/new-run.sh +++ b/scripts/new-run.sh @@ -39,7 +39,7 @@ cat > "$RUN_DIR/goal.md" < "$RUN_DIR/working-log.md" < @@ -137,25 +137,45 @@ 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. +# During the migration, fall back to the legacy prompts/.md location. 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 file="$2" + local new="$REPO_ROOT/skills/pagekit-$step/references/prompt.md" + local old="$REPO_ROOT/prompts/$file" + if [ -f "$new" ]; then + echo "$new" + elif [ -f "$old" ]; then + echo "$old" + else + echo "ERROR: canonical prompt not found at $new or $old" >&2 + exit 1 + fi +} +for entry in "${CANONICAL_PROMPTS[@]}"; do + p="${entry%%:*}" + step="${entry##*:}" dst="$RUN_DIR/prompts/$p" + src="$(resolve_canonical_prompt "$step" "$p")" cat > "$dst" < EOF - cat "$REPO_ROOT/prompts/$p" >> "$dst" + cat "$src" >> "$dst" done # ----- outputs/ placeholders ---------------------------------------------- @@ -185,43 +205,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" < Date: Thu, 16 Apr 2026 07:31:17 -0700 Subject: [PATCH 06/10] Restructure 6/10: runs to examples/, add prompt-paste/, update slop-check Worked runs now live in examples/: - examples/vegan-dog-food-verdel/ (canonical) - examples/personal-crm-founders/ (second) - examples/README.md explains the frozen-snapshot framing (pre-restructure YAML frontmatter in each example's prompts/ reflects the repo state at the time the run executed; new runs resolve prompts from the skills/pagekit-*/references/ paths via scripts/new-run.sh) runs/ is now user scratch space only (empty, .gitkeep holds the dir). prompt-paste/ is a thin chat-app path: - 7 canonical prompts copied verbatim from prompts/ - README explains how to run the chain manually in ChatGPT, Perplexity, Grok, Gemini, or any non-Claude-Code chat window scripts/slop-check.sh now scans both runs/ and examples/ in its default target mode so CI catches regression in the canonical examples. Strangler-fig step 6/10. Co-Authored-By: Claude Opus 4.6 --- examples/README.md | 28 +++++++ .../personal-crm-founders/claim-check.md | 0 .../personal-crm-founders/evaluation.md | 0 .../personal-crm-founders/evaluator-pass.md | 0 .../first-page-decision.md | 0 .../first-page-draft-corrected.md | 0 .../personal-crm-founders/first-page-draft.md | 0 .../personal-crm-founders/goal.md | 0 .../personal-crm-founders/message-spine.md | 0 .../personal-crm-founders/models.md | 0 .../outputs/01-signal-doc-output.md | 0 .../outputs/02-message-spine-output.md | 0 .../outputs/03-first-page-decision-output.md | 0 .../outputs/04-page-argument-shape-output.md | 0 .../outputs/05-proof-map-output.md | 0 .../outputs/06-first-page-draft-output.md | 0 .../outputs/07-claim-check-output.md | 0 .../page-argument-shape.md | 0 .../prompts/01-signal-doc.md | 0 .../prompts/02-message-spine.md | 0 .../prompts/03-first-page-decision.md | 0 .../prompts/04-page-argument-shape.md | 0 .../prompts/05-proof-map.md | 0 .../prompts/06-first-page-draft.md | 0 .../prompts/07-claim-check.md | 0 .../personal-crm-founders/proof-map.md | 0 .../personal-crm-founders/signal-doc.md | 0 .../sources/01-source-capture.md | 0 .../sources/02-product-brief.md | 0 .../personal-crm-founders/sources/README.md | 0 .../personal-crm-founders/working-log.md | 0 .../vegan-dog-food-verdel/claim-check.md | 0 .../vegan-dog-food-verdel/evaluation.md | 0 .../vegan-dog-food-verdel/evaluator-pass.md | 0 .../first-page-decision.md | 0 .../first-page-draft-corrected.md | 0 .../vegan-dog-food-verdel/first-page-draft.md | 0 .../vegan-dog-food-verdel/goal.md | 0 .../vegan-dog-food-verdel/message-spine.md | 0 .../vegan-dog-food-verdel/models.md | 0 .../outputs/01-signal-doc-output.md | 0 .../outputs/02-message-spine-output.md | 0 .../outputs/03-first-page-decision-output.md | 0 .../outputs/04-page-argument-shape-output.md | 0 .../outputs/05-proof-map-output.md | 0 .../outputs/06-first-page-draft-output.md | 0 .../outputs/07-claim-check-output.md | 0 .../page-argument-shape.md | 0 .../prompts/01-signal-doc.md | 0 .../prompts/02-message-spine.md | 0 .../prompts/03-first-page-decision.md | 0 .../prompts/04-page-argument-shape.md | 0 .../prompts/05-proof-map.md | 0 .../prompts/06-first-page-draft.md | 0 .../prompts/07-claim-check.md | 0 .../vegan-dog-food-verdel/proof-map.md | 0 .../vegan-dog-food-verdel/signal-doc.md | 0 .../sources/01-source-capture.md | 0 .../sources/02-product-brief.md | 0 .../vegan-dog-food-verdel/sources/README.md | 0 .../vegan-dog-food-verdel/working-log.md | 0 prompt-paste/01-signal-doc.md | 54 +++++++++++++ prompt-paste/02-message-spine.md | 48 ++++++++++++ prompt-paste/03-first-page-decision.md | 71 ++++++++++++++++++ prompt-paste/04-page-argument-shape.md | 47 ++++++++++++ prompt-paste/05-proof-map.md | 44 +++++++++++ prompt-paste/06-first-page-draft.md | 68 +++++++++++++++++ prompt-paste/07-claim-check.md | 75 +++++++++++++++++++ prompt-paste/README.md | 30 ++++++++ runs/.gitkeep | 0 scripts/slop-check.sh | 18 +++-- 71 files changed, 477 insertions(+), 6 deletions(-) create mode 100644 examples/README.md rename {runs => examples}/personal-crm-founders/claim-check.md (100%) rename {runs => examples}/personal-crm-founders/evaluation.md (100%) rename {runs => examples}/personal-crm-founders/evaluator-pass.md (100%) rename {runs => examples}/personal-crm-founders/first-page-decision.md (100%) rename {runs => examples}/personal-crm-founders/first-page-draft-corrected.md (100%) rename {runs => examples}/personal-crm-founders/first-page-draft.md (100%) rename {runs => examples}/personal-crm-founders/goal.md (100%) rename {runs => examples}/personal-crm-founders/message-spine.md (100%) rename {runs => examples}/personal-crm-founders/models.md (100%) rename {runs => examples}/personal-crm-founders/outputs/01-signal-doc-output.md (100%) rename {runs => examples}/personal-crm-founders/outputs/02-message-spine-output.md (100%) rename {runs => examples}/personal-crm-founders/outputs/03-first-page-decision-output.md (100%) rename {runs => examples}/personal-crm-founders/outputs/04-page-argument-shape-output.md (100%) rename {runs => examples}/personal-crm-founders/outputs/05-proof-map-output.md (100%) rename {runs => examples}/personal-crm-founders/outputs/06-first-page-draft-output.md (100%) rename {runs => examples}/personal-crm-founders/outputs/07-claim-check-output.md (100%) rename {runs => examples}/personal-crm-founders/page-argument-shape.md (100%) rename {runs => examples}/personal-crm-founders/prompts/01-signal-doc.md (100%) rename {runs => examples}/personal-crm-founders/prompts/02-message-spine.md (100%) rename {runs => examples}/personal-crm-founders/prompts/03-first-page-decision.md (100%) rename {runs => examples}/personal-crm-founders/prompts/04-page-argument-shape.md (100%) rename {runs => examples}/personal-crm-founders/prompts/05-proof-map.md (100%) rename {runs => examples}/personal-crm-founders/prompts/06-first-page-draft.md (100%) rename {runs => examples}/personal-crm-founders/prompts/07-claim-check.md (100%) rename {runs => examples}/personal-crm-founders/proof-map.md (100%) rename {runs => examples}/personal-crm-founders/signal-doc.md (100%) rename {runs => examples}/personal-crm-founders/sources/01-source-capture.md (100%) rename {runs => examples}/personal-crm-founders/sources/02-product-brief.md (100%) rename {runs => examples}/personal-crm-founders/sources/README.md (100%) rename {runs => examples}/personal-crm-founders/working-log.md (100%) rename {runs => examples}/vegan-dog-food-verdel/claim-check.md (100%) rename {runs => examples}/vegan-dog-food-verdel/evaluation.md (100%) rename {runs => examples}/vegan-dog-food-verdel/evaluator-pass.md (100%) rename {runs => examples}/vegan-dog-food-verdel/first-page-decision.md (100%) rename {runs => examples}/vegan-dog-food-verdel/first-page-draft-corrected.md (100%) rename {runs => examples}/vegan-dog-food-verdel/first-page-draft.md (100%) rename {runs => examples}/vegan-dog-food-verdel/goal.md (100%) rename {runs => examples}/vegan-dog-food-verdel/message-spine.md (100%) rename {runs => examples}/vegan-dog-food-verdel/models.md (100%) rename {runs => examples}/vegan-dog-food-verdel/outputs/01-signal-doc-output.md (100%) rename {runs => examples}/vegan-dog-food-verdel/outputs/02-message-spine-output.md (100%) rename {runs => examples}/vegan-dog-food-verdel/outputs/03-first-page-decision-output.md (100%) rename {runs => examples}/vegan-dog-food-verdel/outputs/04-page-argument-shape-output.md (100%) rename {runs => examples}/vegan-dog-food-verdel/outputs/05-proof-map-output.md (100%) rename {runs => examples}/vegan-dog-food-verdel/outputs/06-first-page-draft-output.md (100%) rename {runs => examples}/vegan-dog-food-verdel/outputs/07-claim-check-output.md (100%) rename {runs => examples}/vegan-dog-food-verdel/page-argument-shape.md (100%) rename {runs => examples}/vegan-dog-food-verdel/prompts/01-signal-doc.md (100%) rename {runs => examples}/vegan-dog-food-verdel/prompts/02-message-spine.md (100%) rename {runs => examples}/vegan-dog-food-verdel/prompts/03-first-page-decision.md (100%) rename {runs => examples}/vegan-dog-food-verdel/prompts/04-page-argument-shape.md (100%) rename {runs => examples}/vegan-dog-food-verdel/prompts/05-proof-map.md (100%) rename {runs => examples}/vegan-dog-food-verdel/prompts/06-first-page-draft.md (100%) rename {runs => examples}/vegan-dog-food-verdel/prompts/07-claim-check.md (100%) rename {runs => examples}/vegan-dog-food-verdel/proof-map.md (100%) rename {runs => examples}/vegan-dog-food-verdel/signal-doc.md (100%) rename {runs => examples}/vegan-dog-food-verdel/sources/01-source-capture.md (100%) rename {runs => examples}/vegan-dog-food-verdel/sources/02-product-brief.md (100%) rename {runs => examples}/vegan-dog-food-verdel/sources/README.md (100%) rename {runs => examples}/vegan-dog-food-verdel/working-log.md (100%) create mode 100644 prompt-paste/01-signal-doc.md create mode 100644 prompt-paste/02-message-spine.md create mode 100644 prompt-paste/03-first-page-decision.md create mode 100644 prompt-paste/04-page-argument-shape.md create mode 100644 prompt-paste/05-proof-map.md create mode 100644 prompt-paste/06-first-page-draft.md create mode 100644 prompt-paste/07-claim-check.md create mode 100644 prompt-paste/README.md create mode 100644 runs/.gitkeep 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/prompt-paste/01-signal-doc.md b/prompt-paste/01-signal-doc.md new file mode 100644 index 0000000..ba2b916 --- /dev/null +++ b/prompt-paste/01-signal-doc.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: frameworks/signal-doc.md +template: templates/signal-doc-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 `templates/wedge-definition-template.md`. diff --git a/prompt-paste/02-message-spine.md b/prompt-paste/02-message-spine.md new file mode 100644 index 0000000..89bfbaa --- /dev/null +++ b/prompt-paste/02-message-spine.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: frameworks/message-spine.md +template: templates/message-spine-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/prompt-paste/03-first-page-decision.md b/prompt-paste/03-first-page-decision.md new file mode 100644 index 0000000..a2f5ecd --- /dev/null +++ b/prompt-paste/03-first-page-decision.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: 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 + +## 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/prompt-paste/04-page-argument-shape.md b/prompt-paste/04-page-argument-shape.md new file mode 100644 index 0000000..2439efc --- /dev/null +++ b/prompt-paste/04-page-argument-shape.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: frameworks/page-argument-shape.md +template: templates/page-argument-shape-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/prompt-paste/05-proof-map.md b/prompt-paste/05-proof-map.md new file mode 100644 index 0000000..88fd413 --- /dev/null +++ b/prompt-paste/05-proof-map.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: frameworks/proof-map.md +template: templates/proof-map-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/prompt-paste/06-first-page-draft.md b/prompt-paste/06-first-page-draft.md new file mode 100644 index 0000000..e66fa8f --- /dev/null +++ b/prompt-paste/06-first-page-draft.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: 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 + +## 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 frameworks/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/prompt-paste/07-claim-check.md b/prompt-paste/07-claim-check.md new file mode 100644 index 0000000..d226b77 --- /dev/null +++ b/prompt-paste/07-claim-check.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: 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 + +## 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 (frameworks/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/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/runs/.gitkeep b/runs/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/scripts/slop-check.sh b/scripts/slop-check.sh index 465084e..005664a 100755 --- a/scripts/slop-check.sh +++ b/scripts/slop-check.sh @@ -10,7 +10,8 @@ # scripts/slop-check.sh [ ...] # # 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" From 1d98d83c7280033c104f77229438d3471c71b6d2 Mon Sep 17 00:00:00 2001 From: Hiten Shah Date: Fri, 17 Apr 2026 07:55:10 -0700 Subject: [PATCH 07/10] Restructure 7/10: rewrite README as skills-first, slim AGENTS and CLAUDE README.md: - Opens with the skills-first tagline. - One-line plugin install (/plugin marketplace add, /plugin install). - Table of the 12 skills and what each one does. - Links the two examples and the chat-paste path. - Drops START-HERE, quickstart, guides, agentic, guided-runs entry points (those folders get removed in a later commit). Shortened ~140 lines. AGENTS.md: - Neutral contract for any agent cold-reading the repo. - Points Claude Code at skills/ and agents/; points other agents at prompt-paste/. Slimmed to ~45 lines. CLAUDE.md: - Repo contract for the orchestrator skill (same instructions it gets via the project CLAUDE.md hook). ~50 lines. - Rules now cite skills/pagekit/references/ paths rather than frameworks/. All three docs pass scripts/slop-check.sh cleanly. Strangler-fig step 7/10. Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 93 +++++++++-------------------- CLAUDE.md | 126 +++++++++++++++------------------------- README.md | 170 +++++++++++++++++------------------------------------- 3 files changed, 128 insertions(+), 261 deletions(-) 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/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/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). From 1fda10b8ec5b85e6a42189302c3e2bb516091069 Mon Sep 17 00:00:00 2001 From: Hiten Shah Date: Fri, 17 Apr 2026 08:01:37 -0700 Subject: [PATCH 08/10] Restructure 8/10: remove legacy entry-point dirs - Delete START-HERE.md, quickstart/, guides/, guided-runs/, agentic/. The rewritten README, AGENTS.md, and CLAUDE.md no longer reference any of them; the prompt-paste path covers chat-app users; the orchestrator skill covers Claude Code. - Trim scripts/doctor.sh: drop the START-HERE.md line and the three legacy sections (Guided runs, Guides and quickstarts, Agentic tier). - CONTRIBUTING.md: drop the stale START-HERE.md reference from the "must agree with" list. doctor.sh and slop-check.sh still pass. Co-Authored-By: Claude Opus 4.7 (1M context) --- CONTRIBUTING.md | 2 +- START-HERE.md | 81 ----------- agentic/README.md | 44 ------ agentic/claude-code-agentic-path.md | 90 ------------- agentic/claude-cowork-agentic-path.md | 72 ---------- agentic/codex-agentic-path.md | 58 -------- guided-runs/01-build-signal-doc/README.md | 53 -------- .../02-reduce-to-message-spine/README.md | 38 ------ guided-runs/03-decide-first-page/README.md | 37 ----- guided-runs/04-design-page-argument/README.md | 38 ------ guided-runs/05-map-proof-to-pages/README.md | 46 ------- guided-runs/06-draft-first-page/README.md | 57 -------- guided-runs/07-claim-check/README.md | 52 ------- guides/README.md | 31 ----- guides/chatgpt-prompt-path.md | 127 ------------------ guides/claude-prompt-path.md | 115 ---------------- guides/grok-prompt-path.md | 71 ---------- guides/openai-prompt-path.md | 72 ---------- guides/perplexity-prompt-path.md | 95 ------------- quickstart/README.md | 38 ------ quickstart/chatgpt.md | 70 ---------- quickstart/claude.md | 65 --------- quickstart/grok.md | 64 --------- quickstart/openai.md | 61 --------- quickstart/perplexity.md | 66 --------- quickstart/start-with-prompts.md | 47 ------- scripts/doctor.sh | 26 ---- 27 files changed, 1 insertion(+), 1615 deletions(-) delete mode 100644 START-HERE.md delete mode 100644 agentic/README.md delete mode 100644 agentic/claude-code-agentic-path.md delete mode 100644 agentic/claude-cowork-agentic-path.md delete mode 100644 agentic/codex-agentic-path.md delete mode 100644 guided-runs/01-build-signal-doc/README.md delete mode 100644 guided-runs/02-reduce-to-message-spine/README.md delete mode 100644 guided-runs/03-decide-first-page/README.md delete mode 100644 guided-runs/04-design-page-argument/README.md delete mode 100644 guided-runs/05-map-proof-to-pages/README.md delete mode 100644 guided-runs/06-draft-first-page/README.md delete mode 100644 guided-runs/07-claim-check/README.md delete mode 100644 guides/README.md delete mode 100644 guides/chatgpt-prompt-path.md delete mode 100644 guides/claude-prompt-path.md delete mode 100644 guides/grok-prompt-path.md delete mode 100644 guides/openai-prompt-path.md delete mode 100644 guides/perplexity-prompt-path.md delete mode 100644 quickstart/README.md delete mode 100644 quickstart/chatgpt.md delete mode 100644 quickstart/claude.md delete mode 100644 quickstart/grok.md delete mode 100644 quickstart/openai.md delete mode 100644 quickstart/perplexity.md delete mode 100644 quickstart/start-with-prompts.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c2f38b..48264e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,7 +38,7 @@ The most useful contribution for strengthening the method is a real run. ### 4. Docs (README, guides, quickstarts, 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. +- Anything in `README.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. ## Required checks before a PR 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/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/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/scripts/doctor.sh b/scripts/doctor.sh index 155c4d2..47068ff 100755 --- a/scripts/doctor.sh +++ b/scripts/doctor.sh @@ -60,7 +60,6 @@ echo "Manifest and agent contract:" check_file "pagekit.yaml" check_file "AGENTS.md" check_file "CLAUDE.md" -check_file "START-HERE.md" check_file "README.md" echo @@ -83,31 +82,6 @@ done check_file "prompts/README.md" 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" -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" -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" From 19f464ace3682a9a2abfa63799b72b26ca748bd7 Mon Sep 17 00:00:00 2001 From: Hiten Shah Date: Fri, 17 Apr 2026 09:12:15 -0700 Subject: [PATCH 09/10] Restructure 9/10: remove legacy plumbing and cut cross-refs - Remove `.claude/skills/`, `.claude/agents/`, `frameworks/`, `templates/`, `prompts/`, `pagekit.yaml`. Their content now lives (or is absorbed into) `skills/`, `agents/`, `.claude-plugin/`, and `skills/pagekit/references/method.md`. - Update every surviving live reference: - `skills/pagekit-*/references/prompt.md` YAML frontmatter now points at `./framework.md` and `./template.md` (or the upstream siblings for first-page-draft). - `skills/pagekit-*/references/*.md` body mentions of `frameworks/anti-slop.md` now use `../../pagekit/references/anti-slop.md`. - `skills/pagekit/references/anti-slop.md` and `run-logging.md` updated to reference bundled siblings instead of the deleted root files. - `skills/pagekit-signal-doc/references/wedge-definition-template.md` is the new home for the wedge-definition template. - Strip YAML frontmatter from `prompt-paste/*.md` (the README promised stripped-for-paste prompts; deliver on that). Update body references to plain wording so the chat-paste path does not point at deleted files. - Scripts: drop the legacy-path fallback in `new-run.sh` and `claim-check.sh`; update `run-check.sh` and `slop-check.sh` comments to point at the bundled references; rewrite `scripts/README.md` to match. - `doctor.sh`: drop the Frameworks, Templates, Canonical prompts, and legacy `.claude/` bundle sections. Add a check for the new wedge-definition-template location. - Rewrite `CONTRIBUTING.md` against the new layout. - Update `.github/PULL_REQUEST_TEMPLATE.md` to reference skills/. doctor.sh, slop-check.sh, run-check.sh on both examples, claim-check.sh, and new-run.sh all pass after the cut. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/agents/pagekit-claim-checker.md | 81 ------ .claude/agents/pagekit-evaluator-pass.md | 84 ------- .claude/skills/pagekit-claim-check/SKILL.md | 54 ---- .../skills/pagekit-evaluator-pass/SKILL.md | 43 ---- .../pagekit-first-page-decision/SKILL.md | 61 ----- .../skills/pagekit-first-page-draft/SKILL.md | 58 ----- .claude/skills/pagekit-message-spine/SKILL.md | 40 --- .claude/skills/pagekit-new-run/SKILL.md | 21 -- .../pagekit-page-argument-shape/SKILL.md | 41 ---- .claude/skills/pagekit-proof-map/SKILL.md | 42 ---- .claude/skills/pagekit-run-check/SKILL.md | 21 -- .claude/skills/pagekit-signal-doc/SKILL.md | 40 --- .claude/skills/pagekit-slop-check/SKILL.md | 25 -- .claude/skills/pagekit/SKILL.md | 119 --------- .github/PULL_REQUEST_TEMPLATE.md | 2 +- CONTRIBUTING.md | 34 +-- frameworks/anti-slop.md | 166 ------------- frameworks/claim-checking.md | 66 ----- frameworks/first-page-decision.md | 86 ------- frameworks/message-spine.md | 10 - frameworks/page-argument-shape.md | 82 ------- frameworks/proof-map.md | 13 - frameworks/run-logging.md | 84 ------- frameworks/signal-doc.md | 12 - pagekit.yaml | 232 ------------------ prompt-paste/01-signal-doc.md | 13 +- prompt-paste/02-message-spine.md | 11 - prompt-paste/03-first-page-decision.md | 15 -- prompt-paste/04-page-argument-shape.md | 11 - prompt-paste/05-proof-map.md | 12 - prompt-paste/06-first-page-draft.md | 21 +- prompt-paste/07-claim-check.md | 22 +- prompts/01-signal-doc.md | 54 ---- prompts/02-message-spine.md | 48 ---- prompts/03-first-page-decision.md | 71 ------ prompts/04-page-argument-shape.md | 47 ---- prompts/05-proof-map.md | 44 ---- prompts/06-first-page-draft.md | 68 ----- prompts/07-claim-check.md | 75 ------ prompts/README.md | 39 --- scripts/README.md | 16 +- scripts/claim-check.sh | 17 +- scripts/doctor.sh | 35 +-- scripts/new-run.sh | 23 +- scripts/run-check.sh | 2 +- scripts/slop-check.sh | 2 +- .../references/framework.md | 4 +- .../pagekit-claim-check/references/prompt.md | 6 +- .../references/template.md | 6 +- .../references/framework.md | 2 +- .../references/prompt.md | 4 +- .../references/prompt.md | 8 +- .../references/prompt.md | 4 +- .../references/framework.md | 2 +- .../references/prompt.md | 4 +- .../references/template.md | 2 +- skills/pagekit-proof-map/references/prompt.md | 4 +- .../pagekit-signal-doc/references/prompt.md | 6 +- skills/pagekit/references/anti-slop.md | 2 +- skills/pagekit/references/run-logging.md | 6 +- templates/claim-check-template.md | 63 ----- templates/first-page-decision-template.md | 29 --- templates/message-spine-template.md | 24 -- templates/output-judgment-template.md | 24 -- templates/page-argument-shape-template.md | 55 ----- templates/proof-map-template.md | 16 -- templates/signal-doc-template.md | 34 --- templates/wedge-definition-template.md | 28 --- 68 files changed, 82 insertions(+), 2414 deletions(-) delete mode 100644 .claude/agents/pagekit-claim-checker.md delete mode 100644 .claude/agents/pagekit-evaluator-pass.md delete mode 100644 .claude/skills/pagekit-claim-check/SKILL.md delete mode 100644 .claude/skills/pagekit-evaluator-pass/SKILL.md delete mode 100644 .claude/skills/pagekit-first-page-decision/SKILL.md delete mode 100644 .claude/skills/pagekit-first-page-draft/SKILL.md delete mode 100644 .claude/skills/pagekit-message-spine/SKILL.md delete mode 100644 .claude/skills/pagekit-new-run/SKILL.md delete mode 100644 .claude/skills/pagekit-page-argument-shape/SKILL.md delete mode 100644 .claude/skills/pagekit-proof-map/SKILL.md delete mode 100644 .claude/skills/pagekit-run-check/SKILL.md delete mode 100644 .claude/skills/pagekit-signal-doc/SKILL.md delete mode 100644 .claude/skills/pagekit-slop-check/SKILL.md delete mode 100644 .claude/skills/pagekit/SKILL.md delete mode 100644 frameworks/anti-slop.md delete mode 100644 frameworks/claim-checking.md delete mode 100644 frameworks/first-page-decision.md delete mode 100644 frameworks/message-spine.md delete mode 100644 frameworks/page-argument-shape.md delete mode 100644 frameworks/proof-map.md delete mode 100644 frameworks/run-logging.md delete mode 100644 frameworks/signal-doc.md delete mode 100644 pagekit.yaml delete mode 100644 prompts/01-signal-doc.md delete mode 100644 prompts/02-message-spine.md delete mode 100644 prompts/03-first-page-decision.md delete mode 100644 prompts/04-page-argument-shape.md delete mode 100644 prompts/05-proof-map.md delete mode 100644 prompts/06-first-page-draft.md delete mode 100644 prompts/07-claim-check.md delete mode 100644 prompts/README.md delete mode 100644 templates/claim-check-template.md delete mode 100644 templates/first-page-decision-template.md delete mode 100644 templates/message-spine-template.md delete mode 100644 templates/output-judgment-template.md delete mode 100644 templates/page-argument-shape-template.md delete mode 100644 templates/proof-map-template.md delete mode 100644 templates/signal-doc-template.md delete mode 100644 templates/wedge-definition-template.md diff --git a/.claude/agents/pagekit-claim-checker.md b/.claude/agents/pagekit-claim-checker.md deleted file mode 100644 index 6e15a59..0000000 --- a/.claude/agents/pagekit-claim-checker.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -name: pagekit-claim-checker -description: Skeptical, read-only claim-check pass on a PageKit first-page draft. Runs at the requested severity (default hard). Produces an audit (claim-check.md) and a corrected draft (first-page-draft-corrected.md). Use when the user asks for a claim-check on a draft, or when the pagekit-claim-check skill delegates here. -tools: Read, Grep, Glob, Bash, Write ---- - -You are the PageKit claim-checker subagent. - -## Job - -Read a PageKit first-page draft and the corresponding proof map, then produce: - -1. `runs//claim-check.md` — the audit of every flagged line. -2. `runs//first-page-draft-corrected.md` — the corrected draft (only if any line was rewritten). - -You are read-only on the rest of the run. You do not modify the original `first-page-draft.md`. You write only the two files above. - -## Inputs - -The orchestrator (or the user) gives you: - -- path to the draft -- path to the proof map -- severity: `light`, `normal`, or `hard` (default: `hard`) - -## 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. - -## 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.) -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 - - **unsupported claim** — plausible but proof is missing - - **outrun claim** — needs proof the proof map did not commit to - - **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` -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`. -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. - - 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`. -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 - -- **light** — flag clear overclaims, unsupported claims, the strongest slop tells only. -- **normal** — flag the full enum, tolerate mild editorial voice and mild unsourced modifiers in common-usage contexts. -- **hard** — flag any unsourced modifier, any editorial voice, any clinical drift, any external-credential description beyond what briefs support, any slop pattern however small. - -Record the severity used at the top of the audit. - -## Hard rules - -- Do not reward defensiveness. A corrected line must be more precise, not louder. -- Do not invent proof to support a flagged line. If the proof map cannot defend it, the line gets rewritten or cut. -- Do not modify `first-page-draft.md`. Write the corrected version separately. -- Do not skip the "recurring patterns" section. It is how the framework absorbs what claim-check kept catching. - -## Return - -When done, hand back to the caller: - -- path to the audit -- path to the corrected draft (or note if no rewrites were needed) -- count of flags by type -- recurring patterns surfaced diff --git a/.claude/agents/pagekit-evaluator-pass.md b/.claude/agents/pagekit-evaluator-pass.md deleted file mode 100644 index 6fda20a..0000000 --- a/.claude/agents/pagekit-evaluator-pass.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -name: pagekit-evaluator-pass -description: Skeptical, read-only adversarial second read of a completed PageKit run. Produces runs//evaluator-pass.md. Runs after evaluation.md exists. Use when the user asks for an evaluator pass or when the pagekit orchestrator finishes a run and needs one. -tools: Read, Grep, Glob, Bash, Write ---- - -You are the PageKit evaluator-pass subagent. - -## Job - -Read a completed PageKit run (with `evaluation.md` already written) and produce an adversarial second read. You are read-only on everything except `runs//evaluator-pass.md`. - -The evaluator pass is not the evaluation. The evaluation is the run's own honest read. The evaluator pass is a skeptical outside voice that pressure-tests what the run is quietly claiming. - -## Inputs - -The orchestrator (or the user) gives you: -- path to the run folder (e.g., `runs/kind-bowl-real/`) - -Expect these inputs inside the run folder: -- `goal.md` -- all 7 artifacts (signal-doc, message-spine, first-page-decision, page-argument-shape, proof-map, first-page-draft, claim-check) -- `evaluation.md` -- `working-log.md` - -## Read first - -- `frameworks/run-logging.md` — what the evaluator pass is for and where it fits -- `frameworks/anti-slop.md` — the patterns that matter -- The existing `evaluation.md` — to know what the run claims - -## Procedure - -1. Walk the run end-to-end. Look for what the run is quietly claiming that deserves scrutiny. Examples of quiet claims: - - "The first-page decision is right" — is it? What is the confidence basis (data / signal / hypothesis)? If hypothesis, does the run label it as such? - - "The draft is ready for publication" — is it? What is still missing (testimonials, real mechanism detail, scope confirmations)? - - "The claim-check caught everything" — did it? Are there lines in the corrected draft that still read as slop or overclaim? - - "This proves X" — does it? Single runs prove less than the evaluation sometimes suggests. -2. For each scrutiny item, state the **implication**: what does it suggest for the method, the template, the framework, the skill, or the anti-slop rules? -3. End with a **punch list** of specific repo improvements the run exposed. Each item should name the file that would change. This is how the run-to-repo-improvement loop closes. -4. Close with a **final evaluator read**: one paragraph. Is the run real? What does it prove? What does it not prove? - -## Output - -Write `runs//evaluator-pass.md` with sections: - -```markdown -# Evaluator Pass - -Skeptical second read of the run. Not the same voice as `evaluation.md`; this pass is deliberately adversarial. - -## Things the run is quietly claiming that deserve scrutiny - -### 1. - - -**Implication:** - -### 2. -... - -## Punch list for repo improvement - -1. **** — -2. **** — - -## Final evaluator read - - -``` - -## Hard rules - -- Do not reward defensiveness. Skeptical means skeptical. -- Do not generate new artifacts for the run (no new drafts, no new proof maps). You are read-only on the run itself. -- Do not mark items as "already fixed" that the run did not actually fix. -- If the run skipped the claim-check step or did not hit the fully-logged tier, call it out in section 1 regardless of what `evaluation.md` says. - -## Return - -When done, hand back to the caller: -- path to `runs//evaluator-pass.md` -- count of scrutiny items and punch-list items -- final evaluator read in one line diff --git a/.claude/skills/pagekit-claim-check/SKILL.md b/.claude/skills/pagekit-claim-check/SKILL.md deleted file mode 100644 index 4bc727b..0000000 --- a/.claude/skills/pagekit-claim-check/SKILL.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -name: pagekit-claim-check -description: Run a skeptical claim-check pass on a PageKit first-page draft, at light/normal/hard severity. Step 07 of the PageKit method. Use after a first-page draft exists and you want to validate it before treating it as publishable. Delegates to the pagekit-claim-checker subagent. ---- - -# PageKit step 07 — Claim Check - -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` - -## Inputs -- `runs//first-page-draft.md` -- `runs//proof-map.md` -- Severity: light, normal, or hard. Ask the user if not specified; default to `normal`. - -## Procedure - -### Option A — delegate to the subagent (preferred) -Invoke the `pagekit-claim-checker` subagent (`.claude/agents/pagekit-claim-checker.md`). Pass: -- the path to the draft -- the path to the proof map -- the severity - -The subagent runs read-only, produces the audit, and writes: -- `runs//claim-check.md` — the audit (flagged lines, types, rewrites, recurring patterns) -- `runs//first-page-draft-corrected.md` — the corrected draft (only if any line was rewritten) - -### Option B — run inline -Use `scripts/claim-check.sh --severity ` to expand the canonical prompt for paste. Save outputs to the same paths. - -## 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. - -## 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 -- ends with a recurring-patterns summary so upstream constraints can absorb them - -## Next -Do not stop at claim-check. Continue: - -1. Write `runs//evaluation.md` — the run's own honest read of what worked, what stayed thin, where outputs drifted generic. -2. Invoke **`pagekit-evaluator-pass`** to produce the adversarial second read. -3. Ensure `runs//working-log.md` has real entries per step (replace all scaffold `*[Fill in]*` placeholders). -4. Invoke **`pagekit-run-check`** — it must return `tier: FULLY LOGGED` or `tier: PUBLISHABLE` before the run is done. diff --git a/.claude/skills/pagekit-evaluator-pass/SKILL.md b/.claude/skills/pagekit-evaluator-pass/SKILL.md deleted file mode 100644 index 860f4ac..0000000 --- a/.claude/skills/pagekit-evaluator-pass/SKILL.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: pagekit-evaluator-pass -description: Run the adversarial evaluator pass on a completed PageKit run. Post-evaluation skeptical second read. Use when a run has an evaluation.md but no evaluator-pass.md, or when the orchestrator needs an evaluator pass. Delegates to the pagekit-evaluator-pass subagent. ---- - -# PageKit Evaluator Pass - -You are invoking the adversarial evaluator pass on a completed run. - -## When to use - -- 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?" - -## 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 - -## Inputs -- path to the run folder (e.g., `runs/kind-bowl-real/`) - -## Procedure - -1. Confirm the run has `evaluation.md`. If not, the evaluator pass is premature — finish the evaluation first. -2. Invoke the `pagekit-evaluator-pass` subagent. Pass the run-folder path. -3. The subagent runs read-only, produces `runs//evaluator-pass.md`, and hands back a summary (count of scrutiny items, count of punch-list items, one-line final read). -4. Relay the result to the caller. If the punch list contains actionable repo changes, name them for the caller so the run-to-repo-improvement loop can close. - -## Quality gate - -A strong evaluator pass: -- names specific quiet claims from the run, not general impressions -- writes an "implication" for each scrutiny item (what this suggests for the method or the repo) -- ends with a concrete punch list of file-level changes -- does not reward defensiveness - -If the subagent's output is general rather than specific, ask it to retry with more direct reference to the run's artifacts. - -## Relationship to `pagekit-claim-checker` - -- `pagekit-claim-checker` reviews the **draft** line by line at a chosen severity. -- `pagekit-evaluator-pass` reviews the **whole run** including what the evaluation quietly claims. Different target, different voice. diff --git a/.claude/skills/pagekit-first-page-decision/SKILL.md b/.claude/skills/pagekit-first-page-decision/SKILL.md deleted file mode 100644 index 465404c..0000000 --- a/.claude/skills/pagekit-first-page-decision/SKILL.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -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?" ---- - -# PageKit step 03 — First-Page Decision - -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` - -## Inputs -- `runs//signal-doc.md` -- `runs//message-spine.md` -- 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`. -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. -5. Save the raw response to `runs//outputs/03-first-page-decision-output.md`. -6. Distill into `runs//first-page-decision.md`. -7. Update `working-log.md` with the chosen page and one-sentence-each rationale for rejected candidates. - -## Hard requirement -The decision MUST list at least three candidate first pages. Minimum candidates for a trust-heavy object: -- homepage -- category-explainer page -- mechanism or ingredient-detail page -- founder or brand-story page -- use-case or specific-scenario page - -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. - -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. - -## Quality gate -A strong first-page decision: -- chose the first page on purpose -- explains why this page beats the obvious default -- names trust burden and proof burden explicitly -- 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. - -## When to escalate to the user -- The decision is genuinely 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 -After the decision is in place, invoke **`pagekit-page-argument-shape`** (step 04). Do not stop here. diff --git a/.claude/skills/pagekit-first-page-draft/SKILL.md b/.claude/skills/pagekit-first-page-draft/SKILL.md deleted file mode 100644 index 0be184e..0000000 --- a/.claude/skills/pagekit-first-page-draft/SKILL.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -name: pagekit-first-page-draft -description: Draft the first page from the full PageKit chain. Step 06 of the PageKit method. Use when steps 01-05 are done and you are ready to write the page itself. The draft must respect the anti-slop drafting constraints. ---- - -# 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. - -## 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) - -## Inputs -All five upstream artifacts: -- `runs//signal-doc.md` -- `runs//message-spine.md` -- `runs//first-page-decision.md` -- `runs//page-argument-shape.md` -- `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. -2. Substitute the five artifacts above. -3. Save the substituted prompt to `runs//prompts/06-first-page-draft.md`. -4. Prompt the model. -5. Save the raw response to `runs//outputs/06-first-page-draft-output.md`. -6. Distill into `runs//first-page-draft.md`. -7. **Run `scripts/slop-check.sh runs//first-page-draft.md` immediately.** Resolve every flagged pattern by rewriting the line. Re-run until clean. -8. Update `working-log.md`. - -## Hard rules -- Stay inside the proof map. If the draft wants to say something the proof map cannot defend, mark the line with `*[verification flag: ...]*`. -- Stay inside the argument shape. Do not add sections that were not approved at step 04. -- Stay outside the anti-slop pattern list. The script will catch the obvious cases; the claim-check step (07) will catch the rest. - -## Quality gate -A strong draft: -- 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 -- 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. - -## Next -**The draft is not the deliverable. The logged run is.** After the draft is clean, do not stop. Continue the chain: - -1. Invoke **`pagekit-slop-check`** on the draft. Resolve any flags. -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). -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/.claude/skills/pagekit-message-spine/SKILL.md b/.claude/skills/pagekit-message-spine/SKILL.md deleted file mode 100644 index cc7b1be..0000000 --- a/.claude/skills/pagekit-message-spine/SKILL.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -name: pagekit-message-spine -description: Reduce a PageKit signal doc into a message spine. Step 02 of the PageKit method. Use when the user asks to "reduce this signal to a spine," "build a message spine," or has finished step 01 and is ready for step 02. ---- - -# PageKit step 02 — Message Spine - -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` - -## Inputs -- `runs//signal-doc.md` from step 01. - -## Procedure -1. Load `prompts/02-message-spine.md`. -2. Substitute the signal-doc contents. -3. Save the substituted prompt to `runs//prompts/02-message-spine.md`. -4. Prompt the model. -5. Save the raw response to `runs//outputs/02-message-spine-output.md`. -6. Distill into `runs//message-spine.md`. -7. Update `working-log.md`. - -## Quality gate -A strong message spine: -- 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 (that is step 03) - -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. - -## Next -After the spine is in place, invoke **`pagekit-first-page-decision`** (step 03). Do not stop here. diff --git a/.claude/skills/pagekit-new-run/SKILL.md b/.claude/skills/pagekit-new-run/SKILL.md deleted file mode 100644 index faf65bd..0000000 --- a/.claude/skills/pagekit-new-run/SKILL.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -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. ---- - -# 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. - -## Procedure -1. Confirm the run name with the user. Use a slug (lowercase, hyphenated). -2. Run: `bash scripts/new-run.sh `. -3. Tell the user where the scaffold landed and what to fill next (`goal.md` and `sources/`). - -## Why use this skill instead of the script directly -- The conversation logs the choice and the name, which helps later when the run is reviewed. -- It is the on-ramp to `pagekit` (the orchestrator skill) for a complete run. - -## Failure modes -- `runs/` already exists → suggest a different name. -- Repo not at the root → `cd` to the repo root and retry. diff --git a/.claude/skills/pagekit-page-argument-shape/SKILL.md b/.claude/skills/pagekit-page-argument-shape/SKILL.md deleted file mode 100644 index 1c0f682..0000000 --- a/.claude/skills/pagekit-page-argument-shape/SKILL.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -name: pagekit-page-argument-shape -description: Design the page argument shape — what sections the chosen first page should and should not have. Step 04 of the PageKit method. Use when the first-page decision is made and you need a structure for the draft. ---- - -# PageKit step 04 — Page Argument Shape - -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 - -## Inputs -- `runs//first-page-decision.md` -- `runs//message-spine.md` (for context) - -## Procedure -1. Load `prompts/04-page-argument-shape.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`. -7. Update `working-log.md`. - -## Quality gate -A strong page argument shape: -- structure comes from the object, not category habit -- names sections the page does not need, not only sections it does -- makes trust placement and proof placement explicit -- carries the anti-slop drafting constraints forward to the draft step -- passes the length/density check (a page that is honest but unread does not earn trust) - -## Anti-slop -The shape's drafting-constraints section is where slop prevention starts. If those constraints are missing or watered down, every step downstream is weaker. - -## Next -After the shape is in place, invoke **`pagekit-proof-map`** (step 05). Do not stop here. diff --git a/.claude/skills/pagekit-proof-map/SKILL.md b/.claude/skills/pagekit-proof-map/SKILL.md deleted file mode 100644 index 6b6964e..0000000 --- a/.claude/skills/pagekit-proof-map/SKILL.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: pagekit-proof-map -description: Map proof to the chosen first page section by section. Step 05 of the PageKit method. Use after the page argument shape exists and before drafting. ---- - -# PageKit step 05 — Proof Map - -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` - -## Inputs -- `runs//first-page-decision.md` -- `runs//page-argument-shape.md` -- `runs//sources/05-proof-brief.md` (if it exists) - -## Procedure -1. Load `prompts/05-proof-map.md`. -2. Substitute the artifacts above. -3. Save the substituted prompt to `runs//prompts/05-proof-map.md`. -4. Prompt the model. -5. Save the raw response to `runs//outputs/05-proof-map-output.md`. -6. Distill into `runs//proof-map.md`. -7. Update `working-log.md`. - -## Quality gate -A strong proof map: -- 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 - -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. - -## Next -After the proof map is in place, invoke **`pagekit-first-page-draft`** (step 06). Do not stop here. diff --git a/.claude/skills/pagekit-run-check/SKILL.md b/.claude/skills/pagekit-run-check/SKILL.md deleted file mode 100644 index 1abbae6..0000000 --- a/.claude/skills/pagekit-run-check/SKILL.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: pagekit-run-check -description: Validate a PageKit run folder against the logging tiers (fully-logged / summary-logged / artifact-only / incomplete). Wraps scripts/run-check.sh. Use at the end of a run to confirm the fully-logged tier is met before declaring done. ---- - -# 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. - -## Procedure -1. Run: `bash scripts/run-check.sh runs/`. -2. If the result is **FULLY LOGGED**, report success. -3. If the result is **SUMMARY LOGGED** or below, list the missing items to the user and propose what to fill in to reach fully-logged. - -## When to invoke -- At the end of any run produced via the `pagekit` orchestrator skill. -- Before treating a run as validation evidence or as a public example. -- When picking up an existing run to extend. - -## Hard rule -Do not declare a run "done" if `pagekit-run-check` returns anything other than FULLY LOGGED. The whole point of mechanized checks is to stop logging from being the part that gets skipped. diff --git a/.claude/skills/pagekit-signal-doc/SKILL.md b/.claude/skills/pagekit-signal-doc/SKILL.md deleted file mode 100644 index ca6d576..0000000 --- a/.claude/skills/pagekit-signal-doc/SKILL.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -name: pagekit-signal-doc -description: Build a PageKit signal doc from a product description and any source briefs. Step 01 of the PageKit method. Use when the user asks to "build a signal doc," "extract signal from this material," or is starting a PageKit run on a new object. ---- - -# PageKit step 01 — Signal Doc - -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 - -## Inputs -- A product description and any source briefs in `runs//sources/` (especially `02-product-brief.md`). - -## Procedure -1. Load `prompts/01-signal-doc.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`. -7. Append a short note to `runs//working-log.md`. - -## Quality gate -A strong signal doc: -- separates observation from assumption -- gives sharper language than the category default -- 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. - -## 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. - -## 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/.claude/skills/pagekit-slop-check/SKILL.md b/.claude/skills/pagekit-slop-check/SKILL.md deleted file mode 100644 index 74bbed3..0000000 --- a/.claude/skills/pagekit-slop-check/SKILL.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -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. ---- - -# 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. - -## 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/`. -2. If any pattern fires, report the file:line and the pattern name. -3. For each hit, propose a rewrite or recommend cutting the line. -4. Re-run until clean. - -## When to invoke -- Right after `pagekit-first-page-draft` produces a draft, before invoking `pagekit-claim-check`. -- After the corrected draft is produced by claim-check. -- Anytime a user asks "does this read like AI?" - -## Hard rule -Do not advance to the claim-check step until slop-check is clean on the draft. The claim-check should focus on semantic issues; the slop-check should have already cleared the obvious cadence problems. - -## Limits -The script is heuristic. It will flag false positives (some rule-of-three clusters carry real content; some uses of "actually" are correct). Use judgement; do not blindly rewrite. The script's job is to surface lines worth looking at. diff --git a/.claude/skills/pagekit/SKILL.md b/.claude/skills/pagekit/SKILL.md deleted file mode 100644 index a4bc916..0000000 --- a/.claude/skills/pagekit/SKILL.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -name: pagekit -description: Run the full PageKit method end-to-end on an object. Use when the user asks to "run PageKit on X", "build a page for X using PageKit", or "produce a fully-logged PageKit run for X". Orchestrates steps 01-07 (signal doc, message spine, first-page decision, page argument shape, proof map, first-page draft, optional claim-check) and produces a fully-logged run on disk under runs//. ---- - -# 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. - -## 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. - -## Procedure - -For any object the user gives you: - -### 1. Confirm scope - -Ask the user (briefly): -- Run name (slug for the folder under `runs/`). -- Is the object real or a training fiction? If fictional, what concrete facts should serve as ground truth? -- Severity for the eventual claim-check pass: light, normal, or hard. - -### 2. Scaffold - -Run `scripts/new-run.sh ` (or invoke the `pagekit-new-run` skill). This creates `runs//` with the full fully-logged layout. - -### 3. Source briefs - -Fill `runs//sources/`: -- `01-source-capture.md` — what raw material exists, what is missing. -- `02-product-brief.md` — concrete product facts. **No `[Product name]` placeholders.** For trust-heavy objects, also create `03-wedge-definition-brief.md`, `04-mechanism-brief.md`, `05-proof-brief.md`, `06-comparison-brief.md`. - -### 4. Run steps 01-06 in order - -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. -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. - -**Step 03 (first-page decision) is special.** Do not default to homepage. List candidates considered and rejected. The object decides the first page. - -### 5. Pre-claim-check slop check - -Run `scripts/slop-check.sh runs//first-page-draft.md`. Resolve every flagged pattern by rewriting the line. Re-run until clean. - -### 6. Claim check (step 07) - -Invoke the `pagekit-claim-check` skill at the chosen severity. Internally it delegates to the `pagekit-claim-checker` subagent (read-only, hard severity by default). Save: -- `runs//claim-check.md` — the audit (flagged lines, types, rewrites) -- `runs//first-page-draft-corrected.md` — the corrected draft, if any line was rewritten - -### 7. Evaluation and evaluator pass - -Write `runs//evaluation.md` (honest, names what stayed thin) and `runs//evaluator-pass.md` (adversarial second read; lists repo-improvement candidates if the run exposed any). - -### 8. Validate - -Run `scripts/run-check.sh runs/` (or invoke `pagekit-run-check`). It must classify the run as **FULLY LOGGED** before you declare the run done. If it does not, fix the missing items. - -### 9. Hand off - -Tell the user: -- The run is at `runs//`. -- The first page chosen at step 03 (and which candidates were rejected). -- The slop-check and claim-check results. -- Any repo-improvement items the evaluator pass surfaced. - -## Hard rules (do not violate) - -- **Do not declare the run done until `scripts/run-check.sh runs/` returns `tier: FULLY LOGGED` (or `PUBLISHABLE`).** This is the only completion signal. Step 06 producing a nice-looking draft is NOT completion. If run-check reports ARTIFACT-ONLY or SUMMARY LOGGED, the run is incomplete and you must keep working. -- **Do not default to homepage.** Step 03 must consider alternatives. -- **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 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 - -Before handing the run back to the user, walk this checklist. Every item must be YES. If any is NO, you are not done — go finish that item. - -- [ ] `runs//signal-doc.md` is filled with real content (not the scaffold placeholder) -- [ ] `runs//message-spine.md` is filled -- [ ] `runs//first-page-decision.md` is filled AND lists candidates considered with a paragraph case FOR each -- [ ] `runs//page-argument-shape.md` is filled -- [ ] `runs//proof-map.md` is filled -- [ ] `runs//first-page-draft.md` is filled -- [ ] `runs//outputs/NN-*-output.md` exists for every step 01 through 07 -- [ ] `runs//claim-check.md` is filled (not the `*[Filled in by step 07]*` placeholder) -- [ ] `runs//first-page-draft-corrected.md` exists if claim-check flagged any line -- [ ] `runs//working-log.md` has real entries per step (not the scaffold `*[Fill in]*` placeholders) -- [ ] `runs//evaluation.md` is filled -- [ ] `runs//evaluator-pass.md` is filled (use the `pagekit-evaluator-pass` skill/subagent) -- [ ] `bash scripts/slop-check.sh runs//first-page-draft.md` exits 0 clean -- [ ] `bash scripts/run-check.sh runs/` returns `tier: FULLY LOGGED` or `tier: PUBLISHABLE` - -Only after every box is checked do you report completion to the user. - -## When to ask the user - -- First-page decision is borderline (homepage vs. non-homepage close call): show both candidates and ask. -- Claim-check at hard severity is rewriting more than 25% of the draft: pause and check whether the proof map needs strengthening rather than the draft. -- Source briefs are too thin to support a meaningful run: stop and ask for more material. - -## 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. - -For tooling steps, invoke the corresponding skill rather than calling the script directly so the rationale is logged in the conversation. 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/CONTRIBUTING.md b/CONTRIBUTING.md index 48264e3..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`, `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/frameworks/anti-slop.md b/frameworks/anti-slop.md deleted file mode 100644 index 834256b..0000000 --- a/frameworks/anti-slop.md +++ /dev/null @@ -1,166 +0,0 @@ -# Anti-Slop Framework - -Slop is the collection of sentence-level, paragraph-level and structural patterns that make a page read as "written by AI," regardless of whether the content is accurate. - -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`. - -## What this is not - -This is not a style guide for personality. -Voice, cadence, plain specific prose are all welcome. -The patterns listed below are the ones that, on real runs, have read as machine output rather than human thought. - -## Patterns - -### 1. Negation patterns - -Drafts reach for negation when they have not committed to a claim. The rhythm that results is the most recognizable slop tell. - -- **Not-X-Not-Y** — consecutive sentences or headings that both begin with "Not": - > Not a PaaS with a different logo. Not a VPS with a tutorial. -- **Not-X-but-Y** — a rhetorical pivot that replaces a weak claim with a vaguer one: - > Not a pricing tier. A pricing model. -- **X-not-Y** — binary contrasts that sound sharp but usually hide the real claim: - > you pay for what you use, not for the features you need to unlock -- **No-X-No-Y** — the enumerated version of Not-X-Not-Y: - > No egress fees. No tier-forcing. No surprises. - -Rule: say what the product *does*. Say what it *is*. Negations are allowed only when they carry specific content the affirmation cannot. Never stack more than one negation-led construction in the same paragraph. - -### 2. Rule-of-three rhythmic clustering - -Three short parallel sentences used for cadence, not content: -> Your config. Your runtime. Your deployment. -> One command. Standard format. No proprietary packaging. -> You read it, you edit it, you own it. - -The read always goes: triadic beat → recognizably AI. - -Rule: never end a section on a triad. Never write three parallel fragments in a row. If three items belong together, make them a list, or pick the two that carry the most weight. - -### 3. Sentence-start anaphora - -Repeating the first word across consecutive sentences: -> Your…Your…Your -> It is not a platform that… It is not a platform that… It is not a VPS provider that… -> Every founder has… Every founder has… - -Anaphora is a real rhetorical move when it carries an argument. In slop it carries cadence only. - -Rule: vary sentence starts. If the same leading word appears three times in a row in consecutive sentences, rewrite at least two of them. - -### 4. Editorial voice narrating brand restraint - -The brand narrating its own honesty, virtue or discipline instead of demonstrating it: -> We do this because we think you should be able to trust a platform without being trapped by it. -> That's the deal. -> This is the question most brands skip. We don't. -> We will not say "vet approved." - -A page earns trust by showing the work. A page that announces it is showing the work erodes the effect. - -Rule: no lines that narrate brand discipline, brand virtue or brand honesty. If a sentence could be removed without losing any concrete information, remove it. - -### 5. Em-dashes in body copy - -Em-dashes used as rhetorical beats rather than genuine parentheticals: -> OpenClaw is developer hosting with real control — without the DevOps tax. -> Made for owners who want their dog healthy and their conscience clear — in that order. - -Rule: no em-dashes in body copy. If the sentence needs a genuine aside, use a colon, a comma, or parentheses. Em-dashes pattern-match as AI cadence regardless of how many appear per paragraph. - -### 6. Intensifier vocabulary - -Words that make a sentence feel confident without adding information: - -- **actually** — "what it actually costs," "the question developers are actually asking" -- **additionally** — connective scaffold with no load -- **testament** — "a testament to craft" -- **landscape** — "the SaaS landscape" -- **showcasing** — any form of "this page showcases" -- **genuinely** — "genuinely different" -- **truly** — "truly understand" - -Rule: cut these words. If cutting the word changes the meaning, you have found the rare case where it belongs. Usually it does not. - -### 7. Marketing-punchy section enders - -One-line section enders that exist to feel quotable: -> Deploy something real. -> Start with what's right for your dog. -> That's the deal. -> Not the cloud. Not a PaaS. What comes next. - -Rule: sections should end on the concrete thing the reader should do or understand. If the ending is a slogan, it is slop. The CTA section is the only place a punchy line is allowed, and even there, specific beats clever. - -### 8. Quoted antithesis - -Constructing a trade-off by putting two scare-quoted phrases next to each other: -> The gap between "easy but limited" and "powerful but complex" -> Not "vet approved." Actually formulated by a vet. - -This pattern signals the writer is arguing with a straw competitor rather than explaining their own product. - -Rule: describe what the product does directly. If the comparison matters, name the real alternative and the real difference without scare quotes. - -### 9. Copula avoidance - -Replacing "is" or "has" with more performative verbs: - -- **serves as** — "the platform serves as a foundation" -- **boasts** — "boasts 99.99% uptime" -- **features** — "features a clean interface" -- **showcases** — "showcases the ingredients" -- **delivers** — "delivers performance" -- **empowers** — "empowers developers" - -Rule: use "is" or "has." If that feels too flat, the sentence is usually too abstract and needs a concrete fact, not a stronger verb. - -### 10. Signposting - -Narrating the structure of the page instead of executing it: -> Let's dive in. -> Here's the thing. -> Here's what matters. -> This is important. - -Rule: do not announce sections. Write the section. - -### 11. Filler - -Phrases that add syllables without content: - -- "in order to" → "to" -- "due to the fact that" → "because" -- "at this point in time" → "now" -- "it should be noted that" → cut entirely -- "for the purposes of" → "for" - -Rule: the shorter version is almost always the better version. - -### 12. Significance inflation - -Language that makes the product sound historic: -> a pivotal moment -> a critical juncture -> the future of X -> reimagining how Y -> redefining the Z - -Rule: the reader decides what is pivotal. The page describes what the product does. - -## How this gets enforced - -Slop is caught in four places: - -1. **Page argument shape — drafting constraints.** The shape step lists the hard no-go patterns before a draft is written. This is upstream prevention. -2. **Claim check — `ai-slop tell` flag type.** Any slop pattern found in a draft is logged as a claim-check flag and rewritten. Recurring patterns are absorbed upstream into the drafting constraints. -3. **Slop-check script (`scripts/slop-check.sh`).** Grep-level regression check for the patterns that can be detected without semantic analysis (Not-headings, em-dash density, intensifier counts, copula-avoidance verbs, signposting, filler). Cheap, fast, catches the obvious cases. -4. **Guides and quickstarts.** The compact anti-slop rule list appears in every drafting prompt so the model does not need to remember it. - -## Principle - -If a sentence sounds good read aloud but would leave no information behind if you cut it, cut it. That is the test. diff --git a/frameworks/claim-checking.md b/frameworks/claim-checking.md deleted file mode 100644 index 2ddc515..0000000 --- a/frameworks/claim-checking.md +++ /dev/null @@ -1,66 +0,0 @@ -# Claim Checking Framework - -Claim checking is the durability layer. -It runs after the first page draft exists. - -## What it is for - -Finding claims that: -- overclaim what the product actually does -- sound specific but are actually vague -- are not supported by the proof map -- outrun the mechanism the product can honestly explain -- narrate brand restraint instead of showing the work -- carry unsourced quantitative modifiers -- read as machine-written regardless of whether they are accurate - -## What it is not for - -- polishing language -- defending existing claims -- adding new marketing intensity - -## Claim types to flag - -- **overclaim** — the claim is stronger than the product reality -- **vague claim** — the claim sounds concrete but resists being checked -- **unsupported claim** — the claim is plausible but proof is missing -- **outrun claim** — the claim needs proof the proof map did not commit to -- **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. - -## Severity calibration - -Pick the severity level deliberately and log the choice. - -- **light** — flag only clear overclaims, unsupported claims and the strongest slop tells. -- **normal** — flag the full list above, but tolerate mild editorial voice and `most-scale` 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. - -Record the severity used in the run log. A claim check run at one severity is not comparable to one run at another. - -## Principle - -A claim should get stronger when it is corrected, not weaker. -Precision usually beats intensity. -If a corrected claim feels smaller, the original was probably doing more work than it earned. - -## Relationship to the rest of PageKit - -- signal doc names the language worth preserving -- message spine decides which truths carry the page -- proof map commits to what the page can defend -- page argument shape defines drafting constraints, including the anti-slop rules -- claim checking is how the draft is held to those commitments - -When claim checking surfaces a real gap, the fix usually lives upstream in the proof map or the source briefs, not in the copy. - -## 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. - -## Relation to the slop-check script - -`scripts/slop-check.sh` is a fast grep-level regression check for slop patterns. It runs before claim-check, catches the obvious cases, and fails fast so the claim-check pass can focus on semantic issues. The script is not a replacement for this step; it is a filter that removes the mechanical tells before the harder review begins. diff --git a/frameworks/first-page-decision.md b/frameworks/first-page-decision.md deleted file mode 100644 index f0af05a..0000000 --- a/frameworks/first-page-decision.md +++ /dev/null @@ -1,86 +0,0 @@ -# First-Page Decision Framework - -The first-page decision is the step that stops the method from quietly defaulting to a homepage. - -## What it is for - -Deciding, on purpose, what single page should exist first for this object. -Not all objects earn a homepage as the first page. -Some earn a use-case page, a profession-specific page, a comparison page, a nutritional-adequacy page or a trust-heavy entry page instead. - -## Inputs - -- signal doc -- message spine -- mechanism brief, proof brief and comparison brief when they exist (strongly recommended for trust-heavy objects) - -## Why upstream source briefs matter here - -A first-page decision made only from the signal doc and message spine will often name the right page type abstractly. A first-page decision made with mechanism, proof and comparison briefs present will also name the right sections, proof burden and scope. -If a first-page decision feels generic or reluctant, the real repair is usually an additional source brief upstream, not more effort at step 03. - -## What it must answer - -- what page should exist first -- why this page before any other -- what job this page should do -- what visitor state it meets on arrival -- the main trust burden it carries -- the main proof burden it carries -- what this decision rules out for now -- candidates considered and rejected, with why - -## Candidates considered and rejected - -A strong decision lists the alternatives that were considered and says why each was rejected. -At minimum, a trust-heavy object should have considered: -- homepage (and why it was or was not earned) -- a category-explainer page -- a mechanism or ingredient detail page -- a founder or brand story page -- a use-case or specific-scenario page - -Naming rejected candidates makes the decision auditable. It also prevents the step from appearing to choose a non-homepage by default, which would be the mirror-image mistake of always choosing homepage. - -### First-page alternatives vs later-funnel pages - -A pricing page, a features page, a docs page, an integrations page, a comparison page are NOT first-page alternatives. They are later-funnel pages — they assume the visitor has already decided to evaluate the product and is going deeper. Dismissing them as first-page candidates ("a pricing page comes later, so homepage wins") is not a first-page decision; it is a ranking of homepage-vs-subpages, which answers the wrong question. - -First-page alternatives sit at the same intent-commitment level as a homepage. They are pages a visitor could plausibly land on first, via organic search, direct link, or paid ad, without having committed to evaluate the product yet. Examples of real first-page alternatives: - -- audience-specific landing pages (for a specific buyer, profession, or use case) -- trust-and-safety landing pages (for trust-heavy objects where the gating question is "is this safe/responsible?") -- mechanism or ingredient-detail pages (when the mechanism IS the reason to believe) -- category explainers (when the category itself is unfamiliar) -- founder or brand-story pages (rarely the right first page, but legitimate for some B2C objects) -- use-case or specific-scenario pages (for products where one use case dominates the buyer's intent) - -If the rejected candidates are all downstream pages, the step has not been done. Go back and propose alternatives at the same level as a homepage. - -### The affirmative-case requirement - -For every candidate — the chosen one AND every rejected one — write one paragraph stating the case FOR the candidate before any reason to reject it. A one-sentence dismissal is not a rejection; it is a non-consideration. If you cannot write a credible case for a candidate, either (a) think harder about what would make that candidate strong for this specific object, or (b) drop the candidate and replace it with one you can argue for. - -This is how the method avoids the "list and dismiss" anti-pattern. The four pre-Verdel artifact-only runs in this repo all fell into that trap. The Verdel run (`runs/vegan-dog-food-verdel/first-page-decision.md`) is the working example of the step done right. - -## Principle - -The object decides the page shape. -If the decision cannot explain why this page beats the obvious default, the signal doc or message spine is usually still too thin. - -## Failure modes - -- defaulting to homepage because homepage is familiar -- choosing a page the proof map cannot yet support -- deciding before the message spine is reduced enough to point at a specific page -- deciding without mechanism, proof or comparison briefs for a trust-heavy object, then landing on a homepage by default of information rather than by reason -- listing rejected candidates in a single sentence each, without real reasoning - -## Relationship to the rest of PageKit - -- 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. - -If the first page is wrong, every downstream step drifts. diff --git a/frameworks/message-spine.md b/frameworks/message-spine.md deleted file mode 100644 index 26fc860..0000000 --- a/frameworks/message-spine.md +++ /dev/null @@ -1,10 +0,0 @@ -# Message Spine Framework - -A message spine is the reduction layer between signal and pages. - -Its job is to identify the few truths strong enough to organize the site. -A good message spine should preserve: -- the right audience distinctions -- the most important pains and desires -- the strongest usable claims -- the language worth carrying forward diff --git a/frameworks/page-argument-shape.md b/frameworks/page-argument-shape.md deleted file mode 100644 index 836be28..0000000 --- a/frameworks/page-argument-shape.md +++ /dev/null @@ -1,82 +0,0 @@ -# Page Argument Shape Framework - -The page argument shape is how a specific page earns its own structure instead of inheriting a default section rhythm. - -## What it is for - -Deciding, before drafting: -- what the visitor needs to understand first -- what must be earned next -- the order the argument should move in -- which sections this page actually needs -- which sections would be unnecessary or harmful -- where trust should land -- where proof should land -- the constraints the draft must respect - -## Why this exists - -Default homepage rhythms (hero, features, social proof, CTA) are a habit, not a structure. -Different objects want different shapes. -The argument shape step forces the structure to come from the object. - -## Principle - -The structure of the page should fall out of the argument the page has to make. -If the shape looks like every other page in the category, the shape has not done its job. - -## Failure modes - -- reusing a familiar section rhythm without earning it -- inventing sections the proof map cannot support -- hiding the trust burden inside a section that cannot carry it -- planning too many sections and losing the argument -- producing a shape that is honest but too long or too dense to be read through - -## Length and density - -The shape's job includes guarding against a page that is correct but unread. -If the approved section plan is long enough or dense enough that a skeptical reader would stop before the trust-carrying sections land, shorten or cut sections at the shape step. -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. - -Minimum constraints every shape must pass to drafting: - -- no `Not X. Not Y.` headings or sentence pairs -- no `Not-X-but-Y` or `X-not-Y` rhetorical pivots unless they carry specific content -- 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 more than one em-dash per paragraph -- no `actually`, `additionally`, `testament`, `landscape`, `showcasing`, `genuinely`, `truly` as intensifiers -- no marketing-punchy one-liners as section enders -- no scare-quoted antithesis (`the gap between "A" and "B"`) -- no copula-avoidance verbs (`serves as`, `boasts`, `features`, `showcases`, `delivers`, `empowers`) -- 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`, `the future of`) - -Patterns that show up repeatedly across claim-check passes should be added to this list so the draft step stops producing them. - -## Inline verification flag convention - -When the draft makes a product-specific claim that has not been verified against source briefs or ground truth, mark it with an inline verification flag: - -``` -*[verification flag: confirm X against Y before publishing]* -``` - -This convention came out of real runs and is now expected in any first-pass draft that ships without fully verified product facts. The flag keeps the draft honest and makes the claim-check pass faster. - -## Relationship to the rest of PageKit - -- upstream: first-page decision -- downstream: proof map, first page draft, claim check - -The proof map inherits this shape. -The draft should follow it and should not add sections the argument shape did not approve. -The claim check validates the draft against the drafting constraints defined here and flags any slop patterns as `ai-slop tell`. diff --git a/frameworks/proof-map.md b/frameworks/proof-map.md deleted file mode 100644 index 9b4d162..0000000 --- a/frameworks/proof-map.md +++ /dev/null @@ -1,13 +0,0 @@ -# Proof Map Framework - -A proof map assigns the right evidence to the right page jobs. - -Its purpose is to stop pages from sounding specific while staying unproven. - -Common proof types: -- use-case proof -- testimonial proof -- workflow proof -- trust/compliance proof -- technical explanation -- visual proof objects diff --git a/frameworks/run-logging.md b/frameworks/run-logging.md deleted file mode 100644 index 7821b6f..0000000 --- a/frameworks/run-logging.md +++ /dev/null @@ -1,84 +0,0 @@ -# Run Logging Framework - -Every serious PageKit run should log the work as it happens. - -## Two logging levels - -### Fully logged -A fully logged run must include: -- goal -- working log -- models used -- sources (the source briefs used as ground truth) -- prompts (per step) -- outputs (per step, raw) -- final artifacts (signal doc, message spine, first-page decision, page argument shape, proof map, first page draft, claim check, plus the corrected draft if claim check rewrote any lines) -- evaluation -- evaluator pass (skeptical, adversarial review after the run) - -All of these are required. An evaluator pass is not optional at this tier; a run without one is summary-logged. - -Use this level for runs meant as validation evidence or reusable examples. - -### Summary logged -A summary-logged run includes: -- goal -- working log -- models used -- final artifacts -- evaluation - -It does not preserve the per-step prompts and raw outputs. -It is cheaper to produce but less inspectable. -Do not call a summary-logged run a validation run without flagging that distinction. - -## For every step, capture (when fully logging) -- what step this is -- objective -- model used -- exact prompt -- inputs used -- raw output -- short judgment -- what changed before the next step - -## Inline verification flag convention - -When a draft makes a product-specific claim that has not been verified against source briefs or ground truth, the convention is to mark it inline with: - -``` -*[verification flag: confirm X against Y before publishing]* -``` - -This convention came out of real runs. It keeps first-pass drafts honest and makes the claim-check pass faster. A first-pass draft that ships without any verification flags on product-specific claims is suspect. - -## Why this matters -This is not overhead. -This is how PageKit turns a run into reusable evidence. -Without this layer, examples become hard to trust and hard to learn from. - -## Mechanized run creation - -Use the scripts. Hand-rolling a run folder is the most common place fully-logged tier slips. - -```sh -scripts/new-run.sh # scaffold a fully-logged folder -scripts/run-check.sh runs/ # validate the folder against this framework -``` - -Or via make: - -```sh -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/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 -- `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 diff --git a/frameworks/signal-doc.md b/frameworks/signal-doc.md deleted file mode 100644 index 0684c3a..0000000 --- a/frameworks/signal-doc.md +++ /dev/null @@ -1,12 +0,0 @@ -# Signal Doc Framework - -A signal doc is the first serious artifact in PageKit. - -Its job is to collect the strongest available raw material about: -- how the market talks -- what different audiences care about -- where friction, desire and skepticism show up -- which tensions feel structurally important - -A good signal doc should reduce ambiguity. -It should not read like a random pile of notes. 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/prompt-paste/01-signal-doc.md b/prompt-paste/01-signal-doc.md index ba2b916..c42668e 100644 --- a/prompt-paste/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/prompt-paste/02-message-spine.md b/prompt-paste/02-message-spine.md index 89bfbaa..b439140 100644 --- a/prompt-paste/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/prompt-paste/03-first-page-decision.md b/prompt-paste/03-first-page-decision.md index a2f5ecd..1d9616f 100644 --- a/prompt-paste/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/prompt-paste/04-page-argument-shape.md b/prompt-paste/04-page-argument-shape.md index 2439efc..d78cd00 100644 --- a/prompt-paste/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/prompt-paste/05-proof-map.md b/prompt-paste/05-proof-map.md index 88fd413..4ca220c 100644 --- a/prompt-paste/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/prompt-paste/06-first-page-draft.md b/prompt-paste/06-first-page-draft.md index e66fa8f..e2022d1 100644 --- a/prompt-paste/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/prompt-paste/07-claim-check.md b/prompt-paste/07-claim-check.md index d226b77..2329b80 100644 --- a/prompt-paste/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/prompts/01-signal-doc.md b/prompts/01-signal-doc.md deleted file mode 100644 index ba2b916..0000000 --- a/prompts/01-signal-doc.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -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 - -## 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 `templates/wedge-definition-template.md`. diff --git a/prompts/02-message-spine.md b/prompts/02-message-spine.md deleted file mode 100644 index 89bfbaa..0000000 --- a/prompts/02-message-spine.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -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 - -## 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/prompts/03-first-page-decision.md b/prompts/03-first-page-decision.md deleted file mode 100644 index a2f5ecd..0000000 --- a/prompts/03-first-page-decision.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -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 - -## 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/prompts/04-page-argument-shape.md b/prompts/04-page-argument-shape.md deleted file mode 100644 index 2439efc..0000000 --- a/prompts/04-page-argument-shape.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -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 - -## 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/prompts/05-proof-map.md b/prompts/05-proof-map.md deleted file mode 100644 index 88fd413..0000000 --- a/prompts/05-proof-map.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -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 - -## 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/prompts/06-first-page-draft.md b/prompts/06-first-page-draft.md deleted file mode 100644 index e66fa8f..0000000 --- a/prompts/06-first-page-draft.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -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 - -## 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 frameworks/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/prompts/07-claim-check.md b/prompts/07-claim-check.md deleted file mode 100644 index d226b77..0000000 --- a/prompts/07-claim-check.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -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 - -## 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 (frameworks/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/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/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 f55d6fc..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,15 +55,9 @@ esac [ -f "$PROOF" ] || { echo "error: proof map not found: $PROOF" >&2; exit 2; } REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)" -# Prefer the skill-bundled canonical prompt; fall back to legacy prompts/ during migration. -PROMPT_FILE_NEW="$REPO_ROOT/skills/pagekit-claim-check/references/prompt.md" -PROMPT_FILE_OLD="$REPO_ROOT/prompts/07-claim-check.md" -if [ -f "$PROMPT_FILE_NEW" ]; then - PROMPT_FILE="$PROMPT_FILE_NEW" -elif [ -f "$PROMPT_FILE_OLD" ]; then - PROMPT_FILE="$PROMPT_FILE_OLD" -else - echo "error: canonical claim-check prompt not found at $PROMPT_FILE_NEW or $PROMPT_FILE_OLD" >&2 +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 diff --git a/scripts/doctor.sh b/scripts/doctor.sh index 47068ff..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,32 +56,12 @@ 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 "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 - -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 - -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 - echo "Scripts:" check_exec "scripts/new-run.sh" check_exec "scripts/new-source-brief.sh" @@ -92,13 +72,7 @@ check_exec "scripts/doctor.sh" check_file "scripts/README.md" echo -echo "Claude Code bundle (legacy .claude/ locations — removed in a later commit):" -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" +echo "Claude Code hook:" check_file ".claude/settings.json" echo @@ -129,6 +103,7 @@ for s in signal-doc message-spine first-page-decision page-argument-shape proof- 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 "Subagents:" diff --git a/scripts/new-run.sh b/scripts/new-run.sh index e1f7ac2..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 @@ -143,7 +143,6 @@ 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. -# During the migration, fall back to the legacy prompts/.md location. CANONICAL_PROMPTS=( "01-signal-doc.md:signal-doc" "02-message-spine.md:message-spine" @@ -155,15 +154,11 @@ CANONICAL_PROMPTS=( ) resolve_canonical_prompt() { local step="$1" - local file="$2" - local new="$REPO_ROOT/skills/pagekit-$step/references/prompt.md" - local old="$REPO_ROOT/prompts/$file" - if [ -f "$new" ]; then - echo "$new" - elif [ -f "$old" ]; then - echo "$old" + local src="$REPO_ROOT/skills/pagekit-$step/references/prompt.md" + if [ -f "$src" ]; then + echo "$src" else - echo "ERROR: canonical prompt not found at $new or $old" >&2 + echo "ERROR: canonical prompt not found at $src" >&2 exit 1 fi } @@ -171,7 +166,7 @@ for entry in "${CANONICAL_PROMPTS[@]}"; do p="${entry%%:*}" step="${entry##*:}" dst="$RUN_DIR/prompts/$p" - src="$(resolve_canonical_prompt "$step" "$p")" + src="$(resolve_canonical_prompt "$step")" cat > "$dst" < 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 diff --git a/templates/claim-check-template.md b/templates/claim-check-template.md deleted file mode 100644 index cd5aa35..0000000 --- a/templates/claim-check-template.md +++ /dev/null @@ -1,63 +0,0 @@ -# Claim Check Template - -## Page - -## Draft version reviewed - -## Severity -One of: light / normal / hard. -Record the choice and why it was chosen. - -## Claims reviewed - -For each flagged claim: - -### Claim -Quote the exact line from the draft. - -### Type -- overclaim -- vague claim -- unsupported claim -- claim that outruns the proof map -- 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`) - -### Why this is weak -What specifically makes this claim brittle, misleading, undefended, or machine-cadenced? - -### Proof status -- supported now -- supportable with existing source material -- not yet supportable -- not a proof issue (slop tell only) - -### Proposed correction -One of these three dispositions, labeled explicitly: - -- **rewrite** — a sharper, more accurate replacement that sits inside the proof map and reads cleaner. Precision over intensity. -- **remove (wrong)** — cut the line. The claim is not supportable at any severity. State why the claim is disqualified. -- **remove pending verification** — cut the line from the corrected draft; note here as "potentially restorable if is confirmed in the briefs." A dropped claim and a disqualified claim are different things; preserve the distinction. - -Do NOT include `*[Rewritten: ...]*` or any other inline annotation markers in the corrected draft. The audit is where rewrite provenance lives; the corrected draft is publish-ready copy. - ---- - -## Summary - -### Strongest remaining risks -- - -### 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. - -### Recurring slop patterns on this draft -List the specific slop patterns found more than once, by name from `frameworks/anti-slop.md`. - -### Where proof is the real gap -- - -### Upstream artifact that needs repair -- signal doc / message spine / proof map / mechanism brief / comparison brief / page argument shape drafting constraints / anti-slop framework diff --git a/templates/first-page-decision-template.md b/templates/first-page-decision-template.md deleted file mode 100644 index e646341..0000000 --- a/templates/first-page-decision-template.md +++ /dev/null @@ -1,29 +0,0 @@ -# First Page Decision Template - -## Candidate first page - -## Why this page first - -## Confidence basis for this decision -Data / signal / hypothesis — state which and why. - -### If this is a hypothesis: what would falsify it? -Name the concrete observation that would tell you this decision is wrong. A hypothesis you cannot falsify is a guess dressed as a plan. Examples: -- "If cold-acquisition visitors bounce before reaching Section 3, the problem-first framing is wrong for this audience." -- "If a homepage variant outperforms this page on trial conversion at any sample size over N, the decision is wrong." -- "If early users report the page read as preachy, the framing chose the wrong entry angle." - -If the confidence basis above is "data" or "signal," this field is optional. If "hypothesis," it is required — leaving it blank silently promotes a guess to a conclusion. - -## Page job -What should this page help the visitor understand, believe or do? - -## Why this page before other pages - -## Visitor state on arrival - -## Main trust burden - -## Main proof burden - -## What this decision rules out for now diff --git a/templates/message-spine-template.md b/templates/message-spine-template.md deleted file mode 100644 index 53b6493..0000000 --- a/templates/message-spine-template.md +++ /dev/null @@ -1,24 +0,0 @@ -# Message Spine Template - -## Core truths -- truth 1 -- truth 2 -- truth 3 - -## Audience distinctions worth preserving -- distinction 1 -- distinction 2 - -## Native language to keep -- phrases -- tensions -- proof-sensitive wording - -## Claims to test later -- claim 1 -- claim 2 - -## What this should change downstream -- page choices -- proof choices -- language choices diff --git a/templates/output-judgment-template.md b/templates/output-judgment-template.md deleted file mode 100644 index 27b61d7..0000000 --- a/templates/output-judgment-template.md +++ /dev/null @@ -1,24 +0,0 @@ -# Output Judgment Template - -## Artifact - -## Step - -## Short verdict -- strong enough to advance? -- yes / no / cautiously - -## What felt strong -- - -## What felt weak -- - -## Where it drifted generic -- - -## Where uncertainty is still hidden -- - -## What needs to change before the next step -- diff --git a/templates/page-argument-shape-template.md b/templates/page-argument-shape-template.md deleted file mode 100644 index 7a4e433..0000000 --- a/templates/page-argument-shape-template.md +++ /dev/null @@ -1,55 +0,0 @@ -# Page Argument Shape Template - -## Page - -## What the visitor needs to understand first - -## What needs to be earned next - -## What the argument order should be - -## Section plan -List only the sections this page actually needs. - -## What sections would be unnecessary or harmful - -## Where trust should land - -## Where proof should land - -## Drafting constraints - -Copy this block into the draft step. See `frameworks/anti-slop.md` for the full reference with examples. - -### Proof and scope constraints -- no bare "vet approved" / "expert approved" / "clinically proven" and object-equivalents -- no health-, legal-, financial- or regulatory-outcome claims for individual cases -- no unsourced quantitative modifiers (`most`, `usually`, `typically`, `often`, `many`) unless the source briefs support them -- no external-credential descriptions beyond what the source briefs support -- no clinical, legal or regulatory-adjacent phrasing without source backing -- no outrun mechanism or evidence-base claims (do not claim the evidence base supports X when the brief does not reference that evidence) -- no sections not approved by this shape - -### 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) -- 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 copula-avoidance verbs (`serves as`, `boasts`, `features`, `showcases`, `delivers`, `empowers`) -- 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`, `the future of`) - -### Inline verification flag -When the draft makes a product-specific claim not verified against briefs or ground truth, mark it inline: -``` -*[verification flag: confirm X against Y before publishing]* -``` - -## Length and density check -If the approved section plan produces a page so long or dense that a skeptical reader would stop before reaching the trust-carrying sections, that is a shape problem, not a drafting problem. Shorten sections or remove sections before handing to the draft step. diff --git a/templates/proof-map-template.md b/templates/proof-map-template.md deleted file mode 100644 index b179eb4..0000000 --- a/templates/proof-map-template.md +++ /dev/null @@ -1,16 +0,0 @@ -# Proof Map Template - -## Page -- name: -- audience: -- job: - -## Required proof -- use-case proof -- trust proof -- example proof -- technical proof -- visual proof - -## Weak spots -- where could this page drift into generic or unsupported language? diff --git a/templates/signal-doc-template.md b/templates/signal-doc-template.md deleted file mode 100644 index ee309b4..0000000 --- a/templates/signal-doc-template.md +++ /dev/null @@ -1,34 +0,0 @@ -# Signal Doc Template - -## Product -- What is the product? -- What problem does it solve? - -### Object concreteness -If the product is real, you will pull these answers from the product itself and from customer language. If the product is fictional (for a training or test run), you must commit to concrete fictional facts now — name a brand, name a version, name specific facts (features, pricing shape, compliance, credentials). A run on an object described only in the abstract produces a draft full of `[Product name]` placeholders, which means the proof map and claim check cannot bite. Concrete fiction is fine. Abstract is not. - -## Raw signal sources -- customer language -- interviews -- support notes -- sales calls -- reviews -- competitor language -- community discussion - -## Repeated patterns -- pains -- desires -- objections -- trust blockers -- buying triggers - -## Audience distinctions -- who seems meaningfully different? -- what differs across workflow, risk, language or proof threshold? - -## Candidate truths -- what looks strong enough to matter later? - -## Open questions -- what still feels fuzzy? diff --git a/templates/wedge-definition-template.md b/templates/wedge-definition-template.md deleted file mode 100644 index b5e9d4c..0000000 --- a/templates/wedge-definition-template.md +++ /dev/null @@ -1,28 +0,0 @@ -# Wedge Definition Template - -## Why this exists -Use this when the first signal pass is still too category-level to support a strong message spine. - -## Product - -## What the product should be treated as for this run -Write one sharp sentence. - -## First audience hypothesis -- who feels this pain most directly? -- who should the first page be for? - -## Sharp pain framing -What is really breaking? -What is the deeper tension? - -## What this is closer to - -## What this is farther from - -## First-page implication -What should the first page optimize for? -Do not assume this page is a homepage. - -## Claims we still cannot make -List the claims that would be fake, inflated or premature. From 78a7ea1ab74bd56d8147724424bd6da58601d8a7 Mon Sep 17 00:00:00 2001 From: Hiten Shah Date: Fri, 17 Apr 2026 09:42:00 -0700 Subject: [PATCH 10/10] Restructure 10/10: CHANGELOG v0.3 entry and run-check polish - Add a v0.3.0 CHANGELOG entry covering the skills-first restructure: plugin manifests, top-level skills/ with bundled references/, agents/ at repo root, examples/ (two worked runs), prompt-paste/ for chat windows. Method integrity note: anti-slop rules, run-logging tiers, claim-check severities, and the 7 steps are unchanged from v0.2. - run-check.sh: guard the `missing_pub[@]` expansion against the unbound-variable warning that fired when PUBLISHABLE had zero gaps. Cosmetic; tier output was always correct. Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 38 +++++++++++++++++++++++++++++++++++++- scripts/run-check.sh | 4 +++- 2 files changed, 40 insertions(+), 2 deletions(-) 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/scripts/run-check.sh b/scripts/run-check.sh index 2b4e933..d1b620a 100755 --- a/scripts/run-check.sh +++ b/scripts/run-check.sh @@ -155,7 +155,9 @@ check_publishable() { fi fi - printf '%s\n' "${missing_pub[@]}" + if [ "${#missing_pub[@]}" -gt 0 ]; then + printf '%s\n' "${missing_pub[@]}" + fi } if [ "${#missing_fully[@]}" -eq 0 ]; then