From b883e084c8d87a626af4baa95858ed49d8ac0157 Mon Sep 17 00:00:00 2001 From: z4gunn Date: Sun, 4 Oct 2026 15:25:24 -0700 Subject: [PATCH 1/2] feat(schemas): add the PRD activation event and the minimum path to value A saas or mobile PRD now names the one user action that proves the product delivered its value, with an observable definition and the analytics event that counts it. spgr-scope-mvp inventories every step between signup and that event, keeps the essential ones, and names the event each remaining step emits, so onboarding is measured as a path to value from the first release and the entitlement map can forbid a paywall before it. The field is absent on brochure. Procedure mapped from the onboarding and signup skills in https://github.com/coreyhaines31/marketingskills (MIT), rewritten, with the unsourced figures left out. Co-Authored-By: Claude Fable 5.1 --- .claude/skills/spgr-scope-mvp/SKILL.md | 10 ++++++---- .claude/skills/spgr-write-prd/SKILL.md | 11 ++++++----- schemas/prd-v1.json | 18 ++++++++++++++++++ 3 files changed, 30 insertions(+), 9 deletions(-) diff --git a/.claude/skills/spgr-scope-mvp/SKILL.md b/.claude/skills/spgr-scope-mvp/SKILL.md index 9c59c5c..6b3a66f 100644 --- a/.claude/skills/spgr-scope-mvp/SKILL.md +++ b/.claude/skills/spgr-scope-mvp/SKILL.md @@ -17,12 +17,13 @@ Define the minimum viable product scope by cutting everything that is not requir | `value-proposition` | One-line statement of the core value the product delivers. | | `target-icp` | Ideal Customer Profile the MVP must serve. | | `capacity-estimate` | Available development capacity for the MVP window. | +| `activation-event` | The PRD `activation_event` on `saas` and `mobile`, the action that proves the value proposition reached the user. Read from the PRD via spgr-read-artifact. | ## Outputs | Artifact | Description | |----------|-------------| -| `mvp-scope` | MVP definition statement (one paragraph on what the MVP is and is not), in-scope feature list with a rationale per inclusion, out-of-scope feature list with a rationale and a planned deferral phase per item, the end-to-end core user journey the MVP must support, and success criteria stating the user behavior or metric that confirms the value proposition is validated. | +| `mvp-scope` | MVP definition statement (one paragraph on what the MVP is and is not), in-scope feature list with a rationale per inclusion, out-of-scope feature list with a rationale and a planned deferral phase per item, the end-to-end core user journey the MVP must support, the minimum path to value from signup to the activation event, and success criteria stating the user behavior or metric that confirms the value proposition is validated. | ## Procedure @@ -32,9 +33,10 @@ Define the minimum viable product scope by cutting everything that is not requir 4. Test each backlog item against the journey. Ask: if we remove this, does the core user journey break? If yes, mark it in-scope and write the rationale. If no, mark it a deferral candidate. 5. Apply the standing priors. Authentication is almost always in scope, since users need an identity. Billing is frequently out of scope, since you validate before monetizing. Record any departure from these priors as a decision with spgr-log-decision. 6. Assign each out-of-scope item a planned deferral phase and a rationale. Defer, do not reject. A user who definitely wants a feature will still want it in a later sprint. -7. Write the success criteria. State the observable user behavior or metric that confirms the core value proposition is validated. -8. When a deferral or inclusion touches a vertical domain (for example deferring billing, or scoping auth), consult the owning vertical with spgr-tag-vertical-agent and fold the recommendation in before finalizing. -9. Write the mvp-scope artifact with spgr-write-artifact. If a downstream go/no-go gate or scope change requires human judgment, route it with spgr-notify-human. +7. Write the minimum path to value on `saas` and `mobile`. Inventory every step between signup and the activation event, including each screen, each form field, each confirmation, and each wait, because teams undercount their own steps. Mark each step essential or removable, where essential means the activation event cannot fire without it. Remove or defer the removable steps, reorder what remains so the user reaches value before any setup that can wait, and move deferred setup behind the activation event with progressive disclosure. Name the analytics event each remaining step emits, so the funnel from signup to activation is measurable from the first release. The step list is a section of the artifact, and the step count before and after is recorded with spgr-log-decision. +8. Write the success criteria. State the observable user behavior or metric that confirms the core value proposition is validated. +9. When a deferral or inclusion touches a vertical domain (for example deferring billing, or scoping auth), consult the owning vertical with spgr-tag-vertical-agent and fold the recommendation in before finalizing. +10. Write the mvp-scope artifact with spgr-write-artifact. If a downstream go/no-go gate or scope change requires human judgment, route it with spgr-notify-human. ## Notes diff --git a/.claude/skills/spgr-write-prd/SKILL.md b/.claude/skills/spgr-write-prd/SKILL.md index 85106ca..6c62025 100644 --- a/.claude/skills/spgr-write-prd/SKILL.md +++ b/.claude/skills/spgr-write-prd/SKILL.md @@ -35,11 +35,12 @@ Write the PRD, the primary contract between the PM Agent and every downstream ag 6. Write the out-of-scope list. Treat it as equal in weight to the scope list. Name what is not being built so dev agents have clear authority to reject features outside scope, and give each item a reason for exclusion. 7. Apply scope drift prevention. If human vision inputs reference features not connected to any pain point in the taxonomy, surface them as open questions rather than adding them to scope silently. 8. Write the NFR summary section covering performance, security, availability, scalability, and compliance. -9. Write success metrics, the user-stories overview, and open questions, each open question carrying an owner and a deadline. -10. Run inter-section consistency checks: every scope feature ties to a goal, every goal has a metric, every problem claim has evidence. -11. After the NFR section is written, tag the Architect with spgr-tag-vertical-agent so architecture decisions are grounded in the PRD NFR, and tag Security, Compliance, and Accessibility as early vertical consultants. Fold any required amendment back into the relevant section. -12. Write the artifact with spgr-write-artifact against the `prd` schema, set per-section confidence signals, and run spgr-validate-artifact inline before the write completes. Resolve every itemized issue before proceeding. -13. Pause at the approval gate with spgr-notify-human. The PRD must receive human approval before routing to the architect or the backlog-building phase. Record the human response on return and version with spgr-version-artifact. +9. Write the activation event on `saas` and `mobile`: the one user action that shows the product delivered its value, with a name, an observable definition, and the analytics event or query that counts it. It is the `activation_event` field of the `prd` schema. The scope-mvp step measures onboarding as the path to it, and the entitlement map forbids a paywall before it. Leave the field absent on `brochure`, where there is no product action to activate. A goal metric that reads like an activation event (first workflow completed, first report sent) is the candidate, and when the discovery evidence does not settle which action it is, record the field as needs-human-input rather than picking one. +10. Write success metrics, the user-stories overview, and open questions, each open question carrying an owner and a deadline. +11. Run inter-section consistency checks: every scope feature ties to a goal, every goal has a metric, every problem claim has evidence. +12. After the NFR section is written, tag the Architect with spgr-tag-vertical-agent so architecture decisions are grounded in the PRD NFR, and tag Security, Compliance, and Accessibility as early vertical consultants. Fold any required amendment back into the relevant section. +13. Write the artifact with spgr-write-artifact against the `prd` schema, set per-section confidence signals, and run spgr-validate-artifact inline before the write completes. Resolve every itemized issue before proceeding. +14. Pause at the approval gate with spgr-notify-human. The PRD must receive human approval before routing to the architect or the backlog-building phase. Record the human response on return and version with spgr-version-artifact. ## Notes diff --git a/schemas/prd-v1.json b/schemas/prd-v1.json index 36252ea..795d343 100644 --- a/schemas/prd-v1.json +++ b/schemas/prd-v1.json @@ -100,6 +100,24 @@ } } }, + "activation_event": { + "type": "object", + "description": "The one user action that shows the product delivered its value. Required by spgr-write-prd on saas and mobile, absent on brochure. Onboarding is scoped to the shortest path to it, and no paywall shows before it.", + "required": ["name", "definition", "measured_by"], + "properties": { + "name": { "type": "string", "minLength": 1 }, + "definition": { + "type": "string", + "minLength": 1, + "description": "What the user has done when the event fires, in observable terms." + }, + "measured_by": { + "type": "string", + "minLength": 1, + "description": "The analytics event or query that counts it, named so the event taxonomy can carry it." + } + } + }, "open_questions": { "type": "array", "description": "The intake question sweep: every fact, asset, preference, and constraint the run will need from the human, asked once at the first gate.", From c27b15bc4c1d75224db895603ed98339789f0131 Mon Sep 17 00:00:00 2001 From: z4gunn Date: Sun, 4 Oct 2026 15:25:36 -0700 Subject: [PATCH 2/2] feat(skills): fold pricing-page, form, signup, listing, and site-architecture rules into the product skills The entitlement map gains a pricing-page spec section derived from the plan table and the matrix, with a reference carrying the tier, price legibility, structured data, FAQ, paywall timing, and dark-pattern rules plus the paste test that accepts the built page. The component skill gains form and empty-state rules, the interaction spec fixes when validation fires and where focus goes, the error UX spec fixes the field-level error text and keeps entered values, and the auth flow holds the signup form to three fields with deferred collection, audience- ordered social sign-in, a magic-link alternative, deferred verification, and the anti-pattern list. The app store listing names the indexed fields per store, the search-visible screenshot set, and the Play title rules. The IA skill holds brochure and docs sites to the click-depth, slug, header, footer, breadcrumb, and no-orphan rules. Touch targets and label association stay with the accessibility skills and are cited. Procedures mapped from the pricing, cro, signup, paywalls, aso, and site-architecture skills in https://github.com/coreyhaines31/marketingskills (MIT), rewritten in Springer voice, with every unsourced percentage left out. Co-Authored-By: Claude Fable 5.1 --- .../spgr-write-app-store-listing/SKILL.md | 23 ++--- .claude/skills/spgr-write-auth-flow/SKILL.md | 8 +- .claude/skills/spgr-write-component/SKILL.md | 12 ++- .../spgr-write-entitlement-map/SKILL.md | 10 +- .../references/pricing-page.md | 95 +++++++++++++++++++ .../skills/spgr-write-error-ux-spec/SKILL.md | 9 +- .claude/skills/spgr-write-ia/SKILL.md | 11 ++- .../spgr-write-interaction-spec/SKILL.md | 7 +- 8 files changed, 140 insertions(+), 35 deletions(-) create mode 100644 .claude/skills/spgr-write-entitlement-map/references/pricing-page.md diff --git a/.claude/skills/spgr-write-app-store-listing/SKILL.md b/.claude/skills/spgr-write-app-store-listing/SKILL.md index 86438d3..b66caf0 100644 --- a/.claude/skills/spgr-write-app-store-listing/SKILL.md +++ b/.claude/skills/spgr-write-app-store-listing/SKILL.md @@ -28,17 +28,18 @@ Write the store-facing listing content for both iOS App Store and Google Play as ## Procedure 1. Read each input with spgr-read-file. If a target-keyword list, a value proposition, or screenshots at the required sizes are missing, stop and raise spgr-escalate rather than inventing them. The keyword and screenshot inputs drive ASO ranking and conversion and cannot be assumed. -2. Write the App Store app name and subtitle first, since these carry the most keyword weight in App Store search. Place the primary keyword in the app name when the brand name does not already contain it. Keep the app name and subtitle each within 30 characters. -3. Write the iOS keywords field as a comma-separated, case-insensitive list within 100 characters. Exclude the app name and any word already in the app name, since the algorithm indexes those. Do not pad with spaces after commas, which waste the character budget. -4. Write the App Store description (<=4000 chars) and promotional text (<=170 chars). Note in the artifact that promotional text updates without app review, so reserve it for time-sensitive messaging. -5. Write the Google Play title (<=30 chars), short description (<=80 chars), and full description (<=4000 chars). Map the same value proposition and keywords to Play's fields, since Play indexes the full description text. -6. Plan the screenshots as an ordered story rather than a UI tour. Mark the first screenshot as the highest-priority asset, since most users decide to install or skip before scrolling past it. Specify the required device sizes per platform and the feature graphic for Play. -7. Specify the App Preview video (iOS) and promotional video (Play): orientation, length, and the user flow each shows. -8. Set the localization scope: list which markets require a localized listing and which inherit the default-language listing. -9. Write a product-page A/B test plan: App Store Connect product page optimization and Google Play Console store listing experiments both support testing screenshots and descriptions. Name the elements under test, the variant hypotheses, and the conversion metric each test reads. -10. Screen every element against store content policy before writing the artifact. Reject and rewrite any screenshot that shows a competitor app, is a mockup rather than an actual app screen, or any description that makes an unsubstantiated superlative claim such as "best app ever". If an input forces a policy violation that cannot be rewritten away, raise spgr-escalate with the conflicting input named. -11. Write the artifact with spgr-write-artifact and validate inline with spgr-validate-artifact. Record the keyword strategy and any policy-driven rewrites in the decision log with spgr-log-decision. Version with spgr-version-artifact on revision. -12. Route any recommendation to the design agent (for example a screenshot recapture) or the PM agent through spgr-tag-vertical-agent as a consultation. Do not edit another agent's artifact directly. +2. Fix the indexed surface per store before writing a word, because each store ranks on different fields. App Store search indexes the app name (30 characters), the subtitle (30 characters), and the keywords field (100 bytes), and does not index the description. Google Play indexes the title (30 characters), the short description (80 characters), and the full description (4000 characters). Spend the primary keywords on the indexed fields of each store and treat the App Store description as conversion copy only. +3. Write the App Store app name and subtitle first, since these carry the most keyword weight in App Store search. Place the primary keyword in the app name when the brand name does not already contain it. Keep the app name and subtitle each within 30 characters. +4. Write the iOS keywords field as a comma-separated, case-insensitive list within 100 characters. Exclude the app name and any word already in the app name, since the algorithm indexes those. Do not pad with spaces after commas, which waste the character budget. +5. Write the App Store description (<=4000 chars) and promotional text (<=170 chars). Note in the artifact that promotional text updates without app review, so reserve it for time-sensitive messaging. +6. Write the Google Play title (<=30 chars), short description (<=80 chars), and full description (<=4000 chars). Map the same value proposition and keywords to Play's fields, since Play indexes the full description text. Keep the Play title free of emoji, all-caps words, superlatives such as best, and calls to action such as download now, which Play's metadata policy rejects. +7. Plan the screenshots as an ordered story rather than a UI tour. The first three screenshots are the set shown in search results on both stores, and their caption text is indexed, so the first three carry the value proposition in order and their captions carry keywords. Mark the first screenshot as the highest-priority asset, since most users decide to install or skip before scrolling past it. Specify the required device sizes per platform and the feature graphic for Play. +8. Specify the App Preview video (iOS) and promotional video (Play): orientation, length, and the user flow each shows. The App Store autoplays the preview in search results and on the product page, so its first seconds show the core action with no title card. Play shows the video behind a play control on the listing, so its first frame is the poster. +9. Set the localization scope: list which markets require a localized listing and which inherit the default-language listing. +10. Write a product-page A/B test plan: App Store Connect product page optimization and Google Play Console store listing experiments both support testing screenshots and descriptions. Name the elements under test, the variant hypotheses, and the conversion metric each test reads. +11. Screen every element against store content policy before writing the artifact. Reject and rewrite any screenshot that shows a competitor app, is a mockup rather than an actual app screen, or any description that makes an unsubstantiated superlative claim such as "best app ever". If an input forces a policy violation that cannot be rewritten away, raise spgr-escalate with the conflicting input named. +12. Write the artifact with spgr-write-artifact and validate inline with spgr-validate-artifact. Record the keyword strategy and any policy-driven rewrites in the decision log with spgr-log-decision. Version with spgr-version-artifact on revision. +13. Route any recommendation to the design agent (for example a screenshot recapture) or the PM agent through spgr-tag-vertical-agent as a consultation. Do not edit another agent's artifact directly. ## Notes diff --git a/.claude/skills/spgr-write-auth-flow/SKILL.md b/.claude/skills/spgr-write-auth-flow/SKILL.md index a1ae442..d8c84e3 100644 --- a/.claude/skills/spgr-write-auth-flow/SKILL.md +++ b/.claude/skills/spgr-write-auth-flow/SKILL.md @@ -39,11 +39,13 @@ Write the sequence-level specification for each authentication flow so a develop - Password reset: request, email delivery, token validation, token expiry. Reset tokens carry an explicit expiry of 15 to 60 minutes and are single-use. Document the invalidation mechanism so a used or expired token cannot be replayed. - MFA: enrollment, challenge, and recovery code flow. -5. Generate one Mermaid sequence diagram per flow from the written steps so the diagram and text share a single source. Include both the happy path and the failure branches in the diagram via alt and opt blocks. Verify each diagram parses as valid Mermaid before write. +5. Specify the signup flow's field set and friction rules alongside its security paths, because the signup form is where an auth flow loses most of its users. Hold the first step to three fields or fewer, and when the requirements need more, split into steps with a progress indicator and the easy questions first. Defer every field that can be inferred or asked later: company from the email domain, role, phone, and team size are collected after the activation event, not at signup. Order social sign-in by audience: Google, Apple, then Facebook for a consumer product, and Google, Microsoft, then SSO for a business product, and omit any provider the auth model does not name. Offer a magic-link alternative to the password where the auth model allows it. Defer email verification until the user takes an action that needs a verified address, and let them into the product first. Reject these in the flow: a confirm-email field, paste disabled on the password field, a placeholder standing in for a label, a CAPTCHA shown to every user by default rather than after a risk signal, and phone verification required by default. The form's visual and accessibility rules live in spgr-write-component and spgr-write-accessibility-annotations. -6. Tag the Auth vertical for review with spgr-tag-vertical-agent on any flow that deviates from the auth model or the provider's documented sequence, and record the recommendation. Use spgr-log-decision to capture consequential choices (lockout thresholds, token lifetimes, account-linking rules) with their rationale and rejected alternatives. +6. Generate one Mermaid sequence diagram per flow from the written steps so the diagram and text share a single source. Include both the happy path and the failure branches in the diagram via alt and opt blocks. Verify each diagram parses as valid Mermaid before write. -7. Write the artifact with spgr-write-artifact. Because auth-flow is not yet a registered schema type, the envelope header, confidence map, and decision log still apply, and the content is validated against the auth-flow schema once it is registered in a later build increment. +7. Tag the Auth vertical for review with spgr-tag-vertical-agent on any flow that deviates from the auth model or the provider's documented sequence, and record the recommendation. Use spgr-log-decision to capture consequential choices (lockout thresholds, token lifetimes, account-linking rules) with their rationale and rejected alternatives. + +8. Write the artifact with spgr-write-artifact. Because auth-flow is not yet a registered schema type, the envelope header, confidence map, and decision log still apply, and the content is validated against the auth-flow schema once it is registered in a later build increment. ## Notes diff --git a/.claude/skills/spgr-write-component/SKILL.md b/.claude/skills/spgr-write-component/SKILL.md index 08fd985..d674c91 100644 --- a/.claude/skills/spgr-write-component/SKILL.md +++ b/.claude/skills/spgr-write-component/SKILL.md @@ -37,13 +37,15 @@ Produce one UI component that is visually identical to the approved design spec, 5. Implement each state. Resolve every style value to a design token reference. Do not write a hardcoded hex value, pixel value, or font size into the component styles. A raw style value is a token violation and fails this skill. 6. Implement the accessibility annotations exactly as written: ARIA roles, focus behavior, keyboard interactions, and screen reader announcements. Do not paraphrase or omit an annotation. 7. Apply YAGNI. Build only the states and props the spec and contract specify. Do not add states, variants, or props the spec does not list. -8. Write one Storybook story per state so design QA can review every state in isolation. -9. Run the component and visual regression suite via spgr-run-tests. Confirm every state renders as the spec describes and every regression case passes. Then capture the stories or the screen with `.claude/skills/spgr-render-design-comps/scripts/capture-comps.py` when the Playwright CLI is installed, read the captures, and self-critique against the craft floor, the motion standards, and the interface rules in `.claude/references/design-quality.md`. Fix a calibration-cluster hit or a floor miss before the PR opens. -10. Lint and format the component, stories, and contract clean before commit. For TypeScript or JavaScript, conform to `.claude/references/typescript-standards.md` and pass `tsc --noEmit`. Keep the component to one logical change per commit. -11. Write the files via spgr-write-file. Record any consequential implementation choice, such as a token chosen where the spec was ambiguous, via spgr-log-decision. +8. When the component is a form or a form field, hold it to the form rules. Count the fields: three is the baseline for a signup or lead form, four to six costs completions, and seven or more needs a written reason in the spec. Every field has a visible label, never a placeholder standing in for one. Lay fields out in a single column. Set the input type and keyboard that match the data (email, tel, number, url) and leave autofill on with the matching autocomplete attribute. On mobile keep the submit control reachable without scrolling back, sticky at the bottom when the form is longer than the viewport. Write the button copy as the action plus what the user gets, never Submit or Learn more. Build the loading state on the submit control so a double tap cannot send twice. Touch target size, label association, and error association are accessibility annotations and come from spgr-write-accessibility-annotations, so implement them as written rather than re-deriving them here. +9. When the component has an empty state, make it an entry point rather than a notice. Show the exact next action and offer it as one click or one field. Show the action the user can take, not a description of the capability. Where the product allows it, let the user try the feature with sample data before any setup. Empty-state copy comes from the screen spec, and a missing empty-state action is an escalation to the Design agent, not an invention. +10. Write one Storybook story per state so design QA can review every state in isolation. +11. Run the component and visual regression suite via spgr-run-tests. Confirm every state renders as the spec describes and every regression case passes. Then capture the stories or the screen with `.claude/skills/spgr-render-design-comps/scripts/capture-comps.py` when the Playwright CLI is installed, read the captures, and self-critique against the craft floor, the motion standards, and the interface rules in `.claude/references/design-quality.md`. Fix a calibration-cluster hit or a floor miss before the PR opens. +12. Lint and format the component, stories, and contract clean before commit. For TypeScript or JavaScript, conform to `.claude/references/typescript-standards.md` and pass `tsc --noEmit`. Keep the component to one logical change per commit. +13. Write the files via spgr-write-file. Record any consequential implementation choice, such as a token chosen where the spec was ambiguous, via spgr-log-decision. ## Notes -- This skill produces source code. Verification is by spgr-run-tests, the visual regression suite, CI, and the self-critique in step 9, not by an envelope schema. The design bar the Code Reviewer holds the PR to is `.claude/references/design-quality.md`, so clear it here first. For full accessibility conformance against a WCAG target, the component is later audited by spgr-run-accessibility-audit. +- This skill produces source code. Verification is by spgr-run-tests, the visual regression suite, CI, and the self-critique in step 11, not by an envelope schema. The design bar the Code Reviewer holds the PR to is `.claude/references/design-quality.md`, so clear it here first. For full accessibility conformance against a WCAG target, the component is later audited by spgr-run-accessibility-audit. - Escalate via spgr-escalate when the spec does not define a required state's appearance or behavior, when a style value the spec calls for has no matching design token, when the accessibility annotations are missing or contradict the component contract, or when the spec and the component contract disagree on props or events. Return the precise list of what is missing rather than guessing. - When the component touches a vertical concern such as accessibility conformance or an auth-gated state, consult the specialist via spgr-tag-vertical-agent before finalizing. diff --git a/.claude/skills/spgr-write-entitlement-map/SKILL.md b/.claude/skills/spgr-write-entitlement-map/SKILL.md index 7f4ab27..f73d581 100644 --- a/.claude/skills/spgr-write-entitlement-map/SKILL.md +++ b/.claude/skills/spgr-write-entitlement-map/SKILL.md @@ -23,7 +23,7 @@ The Feature Flag Agent owns this artifact as a vertical specialist. The map advi | Artifact | Description | |----------|-------------| -| `entitlement-map` | Envelope artifact written via spgr-write-artifact, holding the plan definitions table, the feature-by-plan matrix with per-plan usage limits, the add-on entitlement list, the enforcement-point specification per entitlement, and the graceful-degradation behavior per gate | +| `entitlement-map` | Envelope artifact written via spgr-write-artifact, holding the plan definitions table, the feature-by-plan matrix with per-plan usage limits, the add-on entitlement list, the enforcement-point specification per entitlement, the graceful-degradation behavior per gate, and the pricing-page spec section | ## Procedure @@ -33,13 +33,15 @@ The Feature Flag Agent owns this artifact as a vertical specialist. The map advi 4. List add-on entitlements. Record each feature that is available as a paid add-on regardless of plan, with its add-on price and the plans it can attach to. 5. Specify the enforcement point for each entitlement. Name where the check runs: API middleware, service layer, or UI gate. Require a service-layer check on every entitlement, since a UI that hides an upgrade-gated control is UX and the service-layer check is the security boundary. State that checks route through one centralized `hasEntitlement(user, feature)` function that consults the entitlement service, not per-feature ad-hoc checks scattered across controllers. 6. Specify graceful-degradation behavior per gate. Record what a non-entitled user sees: paywall, upgrade prompt, or hidden feature. For every usage limit, specify both a hard enforcement gate that errors when the limit is reached and a soft warning that fires when the user approaches the limit. -7. Derive the enforcement test list. For each feature-by-plan cell, list the tests that an implementer must generate: an entitled user can access the feature, and a non-entitled user receives the gate response specified in step 6. Carry this list in the artifact so the Billing or Feature Flag implementer builds tests from the matrix. -8. Record consequential choices with spgr-log-decision: the rationale for each enforcement point, each usage limit, and each degradation behavior, with alternatives considered. -9. Validate and version. Run spgr-validate-artifact inline before marking the artifact confirmed, then version it with spgr-version-artifact. If the feature inventory has features no plan covers, the billing model contradicts the plan definitions, or a required input is missing, stop and raise spgr-escalate with the precise list of what is missing or contradictory rather than assigning a default. Do not fill gaps with assumptions. +7. Write the pricing-page spec section as a projection of the plan table and the matrix, so the page that sells the plans cannot drift from the limits the service layer enforces. Read [references/pricing-page.md](references/pricing-page.md) for the rules: three or four tiers with one recommended and anchored, a monthly and annual toggle with the discount stated, limits in words, prices as visible text, Product and Offer JSON-LD in the server response, the FAQ questions, the paywall timing rules, the dark-pattern ban list, and the paste test that accepts the built page. The paywall rules reference the PRD `activation_event` where the profile requires one, since a paywall never shows before it. +8. Derive the enforcement test list. For each feature-by-plan cell, list the tests that an implementer must generate: an entitled user can access the feature, and a non-entitled user receives the gate response specified in step 6. Carry this list in the artifact so the Billing or Feature Flag implementer builds tests from the matrix. +9. Record consequential choices with spgr-log-decision: the rationale for each enforcement point, each usage limit, and each degradation behavior, with alternatives considered. +10. Validate and version. Run spgr-validate-artifact inline before marking the artifact confirmed, then version it with spgr-version-artifact. If the feature inventory has features no plan covers, the billing model contradicts the plan definitions, or a required input is missing, stop and raise spgr-escalate with the precise list of what is missing or contradictory rather than assigning a default. Do not fill gaps with assumptions. ## Notes - Output type is an envelope spec artifact (`entitlement-map`). Call spgr-validate-artifact regardless. The `entitlement-map` content schema is not registered yet, so envelope-only validation applies for now (header, confidence map, decision log, and version are checked). Its content schema is registered in a later increment. - The registered content-schema artifact types are listed in the schema registry. Reference the registry rather than restating field lists here. +- The pricing-page section is re-derived whenever the plan table or the matrix changes, and the paste test in the reference is re-run against the built page after every pricing change. - A pricing change is a scope change in billing terms. When the map is revised under a pricing change, route the human gate through spgr-notify-human and surface the diff so downstream billing configuration is re-derived. - A recommendation to the Billing Agent flows through spgr-tag-vertical-agent as a registered consultation, not as a direct edit of the billing artifact. diff --git a/.claude/skills/spgr-write-entitlement-map/references/pricing-page.md b/.claude/skills/spgr-write-entitlement-map/references/pricing-page.md new file mode 100644 index 0000000..8480a8c --- /dev/null +++ b/.claude/skills/spgr-write-entitlement-map/references/pricing-page.md @@ -0,0 +1,95 @@ +# pricing-page + +The pricing-page spec section of the entitlement map: what the page that sells the plans must show, how a paywall behaves inside the product, and the check that proves the page is readable by a human buyer and by a machine. Read when the procedure reaches the pricing-page step. + +## Contents + +- [Why the map owns this](#why-the-map-owns-this) +- [Tier presentation](#tier-presentation) +- [Price and limit legibility](#price-and-limit-legibility) +- [Structured data](#structured-data) +- [FAQ coverage](#faq-coverage) +- [Paywall timing](#paywall-timing) +- [Dark-pattern ban list](#dark-pattern-ban-list) +- [The paste test](#the-paste-test) +- [Spec section shape](#spec-section-shape) + +## Why the map owns this + +The entitlement map is the one place the plan-to-feature relationship is written down, so it is also the one place the pricing page can be derived from without drift. A pricing page written from memory of the plans shows a limit the service layer does not enforce, or hides one it does. The spec section here is a projection of the plan table and the matrix, and a change to either re-derives it. + +## Tier presentation + +- Show three or four tiers. Two tiers give no anchor, five or more force a comparison the buyer will not finish. +- Mark exactly one tier recommended, and place it so the eye lands on it first. The recommended tier is the one the target ICP in the plan table buys, not the most expensive one. +- Anchor the recommended tier against the one above it, so its price reads as the sensible choice rather than the cheapest. +- Offer a monthly and an annual toggle and state the annual discount as a number next to the toggle. A toggle with no stated discount asks the buyer to do arithmetic. +- Order the tiers from least to most expensive, left to right or top to bottom, and keep the feature rows in the same order on every tier. +- A tier whose price is quoted on request is allowed once, on the top tier only. A page where every tier says contact us is not a pricing page. + +## Price and limit legibility + +- Write every price as visible text in the HTML, not inside an image, a canvas, or a script-rendered node that is empty in the server response. +- Write per-tier limits in words, with the number and the unit, for example "5 projects, 3 seats, 10 GB storage". A checkmark alone says a feature exists and hides the limit the matrix enforces. +- Use the same feature names on the page as in the entitlement matrix, so a support question about a limit resolves to one row. +- Name the unit of the billing model on the page (per seat, per month, per thousand events) wherever a price appears. + +## Structured data + +- Emit Product and Offer JSON-LD for the plans, one Offer per tier per billing period, with `price`, `priceCurrency`, and the billing period, rendered in the server response. A pricing block that only exists after client-side JavaScript runs is not read by every crawler that matters. +- Keep the structured prices equal to the visible prices. A mismatch is a defect in the page, not in the schema. +- The SEO baseline check in `.claude/references/seo-standards.md`, when present in the repository, verifies the JSON-LD shape. This section fixes the content. + +## FAQ coverage + +The page answers these questions in plain text, each as its own heading and short answer, because they are the questions a buyer asks before paying and the questions a model is asked when a buyer delegates the research: + +- What the trial includes, how long it runs, and whether a card is required. +- How cancellation works and what happens to data after it. +- What each limit means and what happens when it is reached (the hard gate and the soft warning from the degradation section of the map). +- How plan changes are prorated. +- Which payment methods and currencies are accepted. + +## Paywall timing + +A paywall is an upgrade gate the product shows a user who has reached the edge of their plan. The entitlement map specifies when it may appear. + +- Show the paywall after a value moment and before a frustration moment: once the user has done the thing the product is for, and before a repeated block makes them leave. +- Never show a paywall during onboarding. A user who has not reached the activation event has nothing to upgrade for. +- Never interrupt a workflow mid-step with a paywall. Gate at the boundary of the action, before it starts or after it completes, never between. +- Warn about a trial ending at seven days, three days, and one day before the end, each warning naming the date and what changes. +- A soft warning fires at the approach threshold the degradation section sets, and the hard gate fires at the limit. The paywall is the hard gate's UI. + +## Dark-pattern ban list + +None of these appear on the pricing page or in a paywall. A finding on one is a blocking finding in review. + +- A close or dismiss control that is hidden, delayed, low contrast, or placed off the visible area. +- A plan selector where the pre-selected or visually dominant option is not the one the user came for, or where the recommended tier changes between the page and the checkout. +- Guilt copy on the decline path, for example a decline button that reads as a self-criticism. +- A trial that converts to paid without the three warnings above. +- A monthly price shown large with the annual commitment in small print. +- A countdown or scarcity claim that is not true. +- A cancellation path longer than the signup path. + +## The paste test + +The acceptance check for the pricing-page spec section, run against the built page before the story is done and again after any pricing change: + +1. Give the page URL to a web-capable model with no other context and ask it to list every plan, its monthly and annual price, and its limits. +2. Every tier, every price, and every limit from the plan table must come back correctly. A missing tier, a wrong price, or a limit reported as a checkmark fails the check. +3. Record the model, the date, and the transcript excerpt in the decision log. + +A page that fails the paste test is not readable by the buyers who delegate the research, and usually fails a human skimming it as well. + +## Spec section shape + +The pricing-page section of the entitlement-map artifact carries: + +- `tiers_shown`: the ordered list of tiers on the page, the recommended one flagged, each with monthly and annual price and the limit phrases in words. +- `annual_discount`: the stated discount. +- `structured_data`: the Product and Offer JSON-LD plan, one Offer per tier per period. +- `faq`: the question list and the answer source for each (the map section or the billing spec it is derived from). +- `paywall_rules`: the timing rules above with the activation event the PRD names and the trial warning schedule. +- `banned_patterns_checked`: the ban list, each item marked checked at review. +- `paste_test`: the acceptance check record. diff --git a/.claude/skills/spgr-write-error-ux-spec/SKILL.md b/.claude/skills/spgr-write-error-ux-spec/SKILL.md index c58b466..5ffba87 100644 --- a/.claude/skills/spgr-write-error-ux-spec/SKILL.md +++ b/.claude/skills/spgr-write-error-ux-spec/SKILL.md @@ -39,10 +39,11 @@ Each error category entry carries: 2. For each error category, classify user-perceived severity on both axes (blocking or non-blocking, permanent or transient). This classification drives the message, the recovery actions, and the UI treatment. 3. Write the user-facing message for each category. Apply the message rules: never ship "Something went wrong" alone, since it gives no information and no recovery path. State what happened and what to do, for a generic 500 use a form like "We're having trouble loading this page. Try refreshing, and if the problem persists, contact support." Never blame the user for a server error. Own the failure on the product's behalf ("We couldn't process your request right now"), not on the user's ("Your request failed"). 4. Assign recovery actions and UI treatment per category, matched to severity. A transient error offers a retry with minimal friction. A permanent error offers an alternative path or an escalation to support. -5. Separate empty states from error states. For any flow that can return no results, specify the empty-state copy and treatment distinctly from the error-state copy, and confirm the two are never collapsed into one message. -6. Build the error message registry: collect every user-facing message into a single keyed list inside the artifact so the messages can be reviewed for consistency, translated for i18n, and updated in one place rather than hunted through the codebase. Give each message a stable key. -7. Write the artifact via spgr-write-artifact and validate inline with spgr-validate-artifact. Set the per-section confidence map (confirmed, proposed, needs-human-input). Mark any category whose recovery path depends on an unbuilt support channel or an undecided alternative flow as needs-human-input. Record consequential choices with spgr-log-decision. -8. Route the design-facing recommendation to the Design Agent through spgr-tag-vertical-agent as a consultation. Do not edit the Design Agent's component or design artifacts directly. If global reach is in scope, tag the i18n vertical so the registry keys feed translation. +5. Specify field-level validation errors as their own treatment. The message names the field and the fix in one sentence ("Enter a date after today", not "Invalid input"), and it is positioned at the field it describes, never only in a banner at the top of the form. A form that fails validation or a submit that fails on the server keeps every value the user entered. Clearing the form on error is a defect. The timing of the validation and the focus move belong to spgr-write-interaction-spec, this step fixes the text and the placement. +6. Separate empty states from error states. For any flow that can return no results, specify the empty-state copy and treatment distinctly from the error-state copy, and confirm the two are never collapsed into one message. +7. Build the error message registry: collect every user-facing message into a single keyed list inside the artifact so the messages can be reviewed for consistency, translated for i18n, and updated in one place rather than hunted through the codebase. Give each message a stable key. +8. Write the artifact via spgr-write-artifact and validate inline with spgr-validate-artifact. Set the per-section confidence map (confirmed, proposed, needs-human-input). Mark any category whose recovery path depends on an unbuilt support channel or an undecided alternative flow as needs-human-input. Record consequential choices with spgr-log-decision. +9. Route the design-facing recommendation to the Design Agent through spgr-tag-vertical-agent as a consultation. Do not edit the Design Agent's component or design artifacts directly. If global reach is in scope, tag the i18n vertical so the registry keys feed translation. ## Notes diff --git a/.claude/skills/spgr-write-ia/SKILL.md b/.claude/skills/spgr-write-ia/SKILL.md index 5841578..d903c07 100644 --- a/.claude/skills/spgr-write-ia/SKILL.md +++ b/.claude/skills/spgr-write-ia/SKILL.md @@ -28,11 +28,12 @@ Make the full scope of the product's screens and navigation explicit before any 2. Build the site map as the hierarchical structure of all screens, grouped to reflect how a user understands the product rather than how the data is stored. 3. Write the screen inventory. List every screen with its name, purpose, entry points, and exit points. Entry points define how a user can reach the screen, and multiple entry points are common, so list all of them. Exit points define what a user can do from the screen, including navigate to, trigger, and dismiss. 4. Define the navigation model: primary navigation, secondary navigation, and contextual navigation patterns. Match the navigation model to the selected design direction's interaction model. If the requirements demand a navigation pattern the selected direction cannot support, call spgr-escalate rather than diverging from the direction. -5. Record the content hierarchy for the product: what content is prominent, what is secondary, and what is on-demand. -6. Add the screen-count metric to the artifact so the screen scope is a concrete number for sizing design and development effort. -7. Cross-reference the screen inventory against the user stories. Confirm every story maps to at least one screen. List any story with no associated screen and any screen that traces to no story. If a story has no screen, call spgr-escalate, because the inventory is incomplete or the story is out of design scope. -8. Set the confidence signal on each section (confirmed, proposed, or needs-human-input). Mark a section needs-human-input where the requirements or direction did not settle it. -9. Write the artifact with spgr-write-artifact and run spgr-validate-artifact inline. On a validation failure, fix the artifact and revalidate before returning. Log the IA decisions with spgr-log-decision. +5. On a `brochure` run, a docs site, or any public marketing surface, hold the site map and navigation to the site-architecture rules. Every important page is reachable within three clicks of the home page, and the hierarchy is two or three levels deep, never more. Slugs are lowercase and hyphenated and mirror the breadcrumb path, so the URL and the breadcrumb say the same thing. The header carries four to seven items with the primary call to action last. The footer groups links under Product, Resources, Company, and Legal. Every page below the home page shows breadcrumbs. No page is an orphan: each one has at least one inbound link from the navigation or from another page in the inventory, and the cross-reference in step 8 reports any page with none. +6. Record the content hierarchy for the product: what content is prominent, what is secondary, and what is on-demand. +7. Add the screen-count metric to the artifact so the screen scope is a concrete number for sizing design and development effort. +8. Cross-reference the screen inventory against the user stories. Confirm every story maps to at least one screen. List any story with no associated screen and any screen that traces to no story. If a story has no screen, call spgr-escalate, because the inventory is incomplete or the story is out of design scope. +9. Set the confidence signal on each section (confirmed, proposed, or needs-human-input). Mark a section needs-human-input where the requirements or direction did not settle it. +10. Write the artifact with spgr-write-artifact and run spgr-validate-artifact inline. On a validation failure, fix the artifact and revalidate before returning. Log the IA decisions with spgr-log-decision. ## Notes diff --git a/.claude/skills/spgr-write-interaction-spec/SKILL.md b/.claude/skills/spgr-write-interaction-spec/SKILL.md index bd583d4..8bd8fc7 100644 --- a/.claude/skills/spgr-write-interaction-spec/SKILL.md +++ b/.claude/skills/spgr-write-interaction-spec/SKILL.md @@ -32,9 +32,10 @@ Specify every intentional interaction on the approved screens so that different 5. Write the reduced-motion equivalent for every animation, the behavior when `prefers-reduced-motion` is active. A jump cut, an instant state change with no animation, is the minimum acceptable fallback. 6. Specify interactions that need fixed timing, for example a toast that auto-dismisses after a set interval, with the explicit value and a rationale for that value. 7. For each mobile gesture interaction, specify the trigger threshold, the cancellation behavior, and the conflict resolution against platform gestures. -8. Complete the keyboard and focus path for every interaction, the keyboard equivalent and the screen reader announcement when a state changes. Do not document only the mouse or touch path. -9. Write the artifact with spgr-write-artifact and validate it inline with spgr-validate-artifact. Version it with spgr-version-artifact and record the motion decisions with spgr-log-decision. -10. If any animation has no reduced-motion equivalent, any animation has no stated purpose, any keyboard or focus path is missing, or the screen specs are not approved, stop and raise spgr-escalate with the precise list of what is missing rather than filling the gaps with assumptions. Tag the Accessibility vertical with spgr-tag-vertical-agent for reduced-motion and screen-reader review before the artifact is marked confirmed. +8. Specify form validation timing for every form on the screens. Validate a field when the user leaves it, not while they type, so an error never appears under a half-typed value. Re-validate a field that already shows an error on each change, so the error clears as soon as the value is right. On submit, move focus to the first field in error and announce it, and never clear the values the user entered. The error text and its placement come from spgr-write-error-ux-spec, this step fixes when it appears and where focus goes. +9. Complete the keyboard and focus path for every interaction, the keyboard equivalent and the screen reader announcement when a state changes. Do not document only the mouse or touch path. +10. Write the artifact with spgr-write-artifact and validate it inline with spgr-validate-artifact. Version it with spgr-version-artifact and record the motion decisions with spgr-log-decision. +11. If any animation has no reduced-motion equivalent, any animation has no stated purpose, any keyboard or focus path is missing, or the screen specs are not approved, stop and raise spgr-escalate with the precise list of what is missing rather than filling the gaps with assumptions. Tag the Accessibility vertical with spgr-tag-vertical-agent for reduced-motion and screen-reader review before the artifact is marked confirmed. ## Notes