mustflow 2.107.3 → 2.108.0

package/templates/default/locales/en/.mustflow/skills/small-service-platform-architecture-review/SKILL.md

@@ -0,0 +1,273 @@
+---
+mustflow_doc: skill.small-service-platform-architecture-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: small-service-platform-architecture-review
+description: Apply this skill when a multi-product platform, app factory, solo-developer portfolio platform, many-small-services architecture, shared account portal, Product Registry, shared auth, billing, credits, entitlements, admin console, deployment factory, analytics, logging, i18n, common UI, templates, or operations automation for multiple product apps is created, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.small-service-platform-architecture-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Small Service Platform Architecture Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review a shared platform for many small products as an app factory, not as many copied services.
+
+The core question is: "Can a new product be added mostly by declaring product facts, while auth,
+billing, credits, entitlements, admin, analytics, observability, legal, deployment, and operations
+stay shared and explainable?" If not, the portfolio is just copy-paste debt with domains attached.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A repository, architecture plan, template, generator, or product platform is intended to support
+  many small apps, micro-SaaS products, SEO tools, AI tools, API products, downloads, extensions,
+  or similar product shells.
+- Code, docs, schemas, templates, or reviews touch a Product Registry, app catalog, shared account
+  portal, shared identity, organization, billing, credit ledger, usage meter, entitlement, admin,
+  analytics, logging, notification, i18n, legal, feature flag, app template, deployment factory,
+  file service, job queue, integration service, outbound webhook, AI Gateway, or license service.
+- A review or final report claims that creating another service is easy, the platform is reusable,
+  templates are shared, billing or credits are common, apps are tenant-safe, or operations can scale
+  beyond a few products.
+- A solo developer or small team wants to avoid reimplementing account, payment, admin, deploy,
+  telemetry, localization, support, and incident workflows for each product.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task concerns one standalone app with no multi-product platform, app factory, shared package,
+  or cross-product operational surface.
+- The task only changes a single auth flow, OAuth callback, session, token, or permission rule. Use
+  `auth-permission-change`, `auth-flow-triage`, or `api-access-control-review`.
+- The task only changes one payment, subscription, refund, webhook, credit, or usage path. Use
+  `payment-integrity-review` or `credit-ledger-integrity-review`.
+- The task only changes an admin screen, notification path, i18n path, deployment pipeline,
+  component library, AI feature, file upload, queue, or service boundary. Use the matching
+  specialist skill first.
+- The task is an organization-scale microservice split decision rather than a product-app factory.
+  Use `service-boundary-architecture` first.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal, target product count, product types, expected shared versus app-specific behavior,
+  repository layout, current diff or target files, and configured command intents.
+- Product Registry ledger: `app_id`, domains, environments, product names, auth modes, plan and
+  price mapping, entitlement keys, usage meters, credit costs, analytics namespace, admin panels,
+  i18n namespace, email templates, legal and consent versions, data categories, and deploy config.
+- Identity ledger: users, identities, sessions, organizations, workspaces, memberships, roles,
+  permissions, invitations, API keys, service accounts, account linking, and account portal scope.
+- Money and access ledger: customers, provider customers, subscriptions, invoices, tax profiles,
+  webhook events, refunds, disputes, wallets, credit grants, credit transactions, usage events,
+  reservations, quotas, limits, grace periods, and local entitlement state.
+- Operations ledger: support view, admin action log, resource change history, impersonation,
+  refunds, manual credits, feature overrides, account merge or delete, job logs, webhook logs,
+  email logs, runbooks, alerts, backups, and restore tests.
+- App factory ledger: app templates, `create-product` or equivalent generator, shared packages,
+  thin app shells, CI/CD, preview, staging, production, migration policy, smoke tests, rollback,
+  secrets, environment variables, DNS, TLS, CDN, storage, cache, queue, cron, and workers.
+- Observability and analytics ledger: event schema, first-value-created event, revenue metrics,
+  usage rollups, structured logs, traces, request IDs, app IDs, tenant IDs, alerts, status pages,
+  and cost monitors.
+- Shared product surface ledger: i18n, legal, consent, notifications, file service, job service,
+  integrations, outbound webhooks, SEO, marketing pages, shared UI, feature flags, remote config,
+  AI Gateway, license service, and developer portal where relevant.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the
+  current scope.
+- Existing local platform, template, package, registry, billing, auth, admin, analytics, deploy,
+  and operations patterns have been searched before proposing a new platform layer.
+- If the change touches money, auth, privacy, admin, deployment, AI, localization, files, queues, or
+  notifications, also apply the narrower matching skill for that boundary.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Create or refine platform architecture docs, skill procedures, route metadata, templates, tests,
+  registry schemas, app factory contracts, shared package boundaries, operational runbooks, and
+  directly synchronized template copies tied to the multi-product platform surface.
+- Tighten platform boundaries by moving copied product logic into shared packages, registries,
+  policy services, ledgers, generators, runbooks, or explicit app-specific extension points.
+- Add focused tests for registry validation, entitlement resolution, credit ledger behavior,
+  webhook idempotency, template generation, app profile installation, admin permissions,
+  analytics event shape, i18n key coverage, smoke checks, and operation runbooks when existing
+  project patterns support them.
+- Do not migrate to a new cloud, framework, auth provider, billing provider, queue, database,
+  analytics tool, or orchestration platform unless the current task explicitly requires that
+  migration.
+- Do not turn every possible future product feature into mandatory platform scope. Separate the
+  phase-one spine from phase-two and phase-three extensions.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Decide whether this is a platform factory or a single product.
+   - A platform factory has several product shells, shared packages, shared ledgers, common
+     operations, and a path for adding a product through declaration plus thin app code.
+   - If the surface is one app, route to the narrower product or framework skill and report that
+     this skill does not apply.
+2. Build the Product Registry ledger first.
+   - Require one source of truth for app identity, domains, environments, auth policy, billing
+     catalog mapping, entitlement keys, usage meters, credit costs, analytics namespace, admin
+     panels, i18n namespace, email templates, legal versions, data categories, and deploy config.
+   - Flag product facts scattered across routes, Stripe dashboards, environment variables,
+     seed scripts, marketing pages, and app-specific constants.
+3. Review identity as a shared account operating system.
+   - Separate `User` from `Identity` so email, OAuth, passkeys, and account linking can evolve.
+   - Require common organization, workspace, membership, invitation, role, permission, API key,
+     service account, session management, device session, forced logout, and account portal paths.
+   - Keep billing, security, data export, data deletion, and login methods anchored in the account
+     portal even when product apps have their own settings.
+4. Review billing, entitlements, credits, and usage as local ledgers.
+   - Treat the payment provider as an event source, not as the application's only authority.
+   - Require provider webhooks to be stored, signature-checked, idempotent, replayable, and mapped
+     into local customer, subscription, invoice, refund, dispute, tax, and entitlement state.
+   - Reject feature gates such as `plan === "pro"`; require entitlement and limit checks.
+   - Reject balance-only credits; require append-only credit transactions, grants, usage events,
+     reservations, capture, release, partial capture, expiry, reconciliation, and audit evidence.
+5. Review admin and support as production control planes.
+   - Require a support view that connects user, organization, apps used, plan, payment state,
+     credit ledger, usage, recent errors, jobs, webhooks, notifications, experiments, and blocks.
+   - Separate audit logs from resource change history.
+   - Require scoped operator permissions, impersonation controls, dangerous-action confirmation,
+     reason capture, step-up authentication where needed, production guardrails, and PII masking.
+6. Review the app factory.
+   - Prefer a generator that registers a product and creates thin app shell files over a large
+     template copy that drifts.
+   - Keep shared auth, billing, credits, entitlements, analytics, logging, i18n, UI, email, jobs,
+     files, deployment, and support behavior in packages or services that remain upgradeable.
+   - Require templates for common product shapes only when they still depend on shared packages.
+7. Review deployment and database rollout.
+   - Require preview, staging, and production separation, environment-scoped secrets, provider
+     sandbox separation, migration checks, expand-migrate-contract sequencing, smoke tests,
+     rollback or rollback-forward runbooks, and post-deploy observation.
+   - Treat manual DNS, TLS, storage, queue, cron, backup, or monitoring setup as product launch
+     debt unless it is captured in a reproducible checklist or generator.
+8. Review analytics, logging, and operations before product count grows.
+   - Standardize event names, `app_id`, anonymous and authenticated user identity, tenant identity,
+     locale, country, campaign, plan, experiment, and request or trace identifiers.
+   - Require each product to declare its first-value-created event.
+   - Require structured logs, traces, alerts, dashboards, runbooks, backup checks, restore tests,
+     cost spike alerts, domain and certificate expiry alerts, job dead-letter handling, and webhook
+     replay.
+9. Review shared product surfaces.
+   - Keep notification categories, transactional versus marketing consent, i18n namespaces,
+     fallback behavior, legal and consent versions, shared UI layouts, file ownership, job
+     idempotency, integration tokens, outbound webhook signing, SEO templates, feature flags,
+     remote config, AI Gateway calls, and license keys common unless product-specific behavior is
+     deliberately declared.
+10. Review privacy and security as cross-product invariants.
+    - Require `app_id`, `tenant_id`, `user_id`, `request_id`, and `trace_id` on records where they
+      explain ownership, access, audit, or support.
+    - Require PII redaction, retention policy, consent records, cookie and marketing preferences,
+      data export, delete, anonymize, backup encryption, dependency scanning, abuse detection,
+      card-testing detection, and admin read audit for sensitive data.
+11. Phase the platform spine.
+    - Phase one should cover Product Registry, identity and organization, billing basics, credit
+      ledger, entitlement, basic admin, analytics events, structured logging, app template or
+      generator, CI/CD, and basic transactional email.
+    - Phase two should cover account portal depth, webhook replay, usage rollups, feature flags,
+      file service, job queue, support view, i18n, legal and consent, SEO templates, monitoring,
+      backups, and restore checks.
+    - Phase three should cover AI Gateway, affiliate or referral, license service, outbound
+      webhooks, developer portal, advanced experiments, advanced RBAC, warehouse, churn automation,
+      abuse detection, and cost optimization.
+12. Route specialist risks deliberately.
+    - Apply `payment-integrity-review`, `credit-ledger-integrity-review`,
+      `admin-control-plane-safety-review`, `notification-delivery-integrity-review`,
+      `frontend-localization-review`, `frontend-component-library-review`,
+      `deployment-rollout-safety-review`, `ai-product-readiness-review`,
+      `file-upload-security-review`, `queue-processing-integrity-review`, or
+      `service-boundary-architecture` when the platform review exposes a narrower implementation
+      risk.
+13. Report evidence level honestly.
+    - Separate architecture inspection, schema or registry evidence, package boundary evidence,
+      generated template evidence, test evidence, operational runbook evidence, provider webhook
+      fixture evidence, and real production-readiness evidence.
+    - Name missing configured intents or manual review for provider dashboards, cloud consoles,
+      browser smoke tests, visual review, or deployment checks instead of claiming readiness.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Product Registry, identity, billing, credit, entitlement, admin, app factory, deployment,
+  analytics, logging, shared product surface, security, privacy, operations, and phased rollout
+  ledgers are fixed, ruled out, or reported.
+- New product creation depends more on declared product facts and thin app code than on duplicated
+  auth, payment, admin, analytics, i18n, deployment, and operations code.
+- Product-specific behavior is declared as product-specific, and shared behavior has a clear owner.
+- Missing provider, deployment, telemetry, security, privacy, localization, or operational evidence
+  is named instead of hidden.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use the narrowest configured unit, template, registry, docs, release, package, build, or mustflow
+intent that covers the changed platform contract. Do not infer provider dashboard, cloud console,
+deployment, browser, visual-regression, package-manager, or dev-server commands outside the command
+contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If no Product Registry or equivalent source of truth exists, stop treating the platform as
+  reusable and report the missing product authority.
+- If payment, credit, entitlement, or usage facts are split between provider dashboards and app
+  constants, apply the money and ledger specialist skills before claiming platform readiness.
+- If templates are copied but shared packages cannot be upgraded across product shells, report
+  template drift risk instead of calling the generator complete.
+- If admin or support paths require direct database edits, apply `admin-control-plane-safety-review`
+  and report the operational safety gap.
+- If verification fails, preserve the configured intent name and failure evidence, then fix the
+  platform contract surface rather than weakening tests or removing installed files.
+- If release impact is unclear, apply `date-number-audit` before editing versions or release notes.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Platform surface reviewed
+- Product Registry, identity, billing, credit, entitlement, admin, app factory, deployment,
+  analytics, observability, shared surface, security, privacy, operations, and phase ledgers
+- Findings, fixes, or recommendations
+- Shared versus product-specific ownership decisions
+- Specialist skills used or deferred
+- Evidence level by registry, schema, package, template, tests, provider, deployment, telemetry,
+  and runbook surface
+- Command intents run
+- Skipped platform-readiness checks and reasons
+- Remaining small-service platform architecture risk

package/templates/default/locales/en/.mustflow/skills/third-party-api-integration-review/SKILL.md

@@ -0,0 +1,188 @@
+---
+mustflow_doc: skill.third-party-api-integration-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: third-party-api-integration-review
+description: Apply this skill when integrating, reviewing, debugging, or upgrading a third-party SDK or external API service, including authentication, scopes, sandbox versus production behavior, request timeouts, retries, rate limits, idempotency, pagination, webhooks, SDK/API drift, provider error mapping, changelogs, deprecations, migration guides, observability, or production-readiness tests.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.third-party-api-integration-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - test_audit
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Third-Party API Integration Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Make third-party SDK and API integrations production-safe instead of merely making the first demo call succeed.
+
+Developers usually suffer when provider complexity is pushed into the consuming product: unclear auth scopes, stale docs, SDK/API mismatch, opaque errors, rate limits, unsafe retries, duplicate webhooks, undocumented version drift, and missing recovery evidence. This skill turns those failure paths into explicit design and test requirements.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A product calls, wraps, replaces, upgrades, or removes a third-party SDK, external REST/GraphQL/RPC API, hosted auth provider, payment provider, messaging provider, storage provider, analytics provider, AI provider, search provider, CRM, email/SMS/push provider, geocoding provider, or SaaS integration.
+- Code handles provider authentication, authorization scopes, refresh tokens, tenant or organization ids, sandbox/production environments, API keys, service accounts, or webhook signing secrets.
+- Code implements or reviews provider request timeouts, retry policy, rate-limit handling, pagination, idempotency keys, webhook event handling, provider error mapping, request ids, logs, metrics, traces, or dead-letter/replay behavior.
+- A provider SDK version, API version, changelog, migration guide, deprecation notice, webhook payload, response shape, error shape, pagination model, or rate-limit policy changes.
+- Integration tests, fakes, fixtures, docs, runbooks, or recovery tools must prove the integration handles unhappy paths.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The API is owned by the same repository or organization and the task is primarily public contract design; use `api-contract-change`, `api-misuse-resistance-review`, or `http-api-semantics-review`.
+- The only question is where to place the provider boundary or how to hide provider types from core logic; use `adapter-boundary` first, then return here for provider operational behavior.
+- The task is only a rate-limit implementation, retry loop, idempotency mechanism, queue consumer, or payment ledger change with no third-party provider integration; use the narrower integrity skill.
+- The task is a one-off local script that is not production, repeated, automated, or connected to customer, money, entitlement, privacy, or operational state.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Provider name, SDK package and version, API version, environment, endpoint or event names, and whether the integration is inbound, outbound, or both.
+- Source-of-truth ledger: provider reference docs, OpenAPI or schema files, SDK docs, changelog, migration guide, status page or incident notes when relevant, and local wrapper or adapter patterns.
+- Auth ledger: credential source, secret storage boundary, auth flow, token lifetime, refresh behavior, scopes, tenant or organization binding, sandbox/production separation, and failure behavior for 401 versus 403.
+- Operation ledger: reads, writes, mutating operations, money or entitlement effects, external side effects, pagination model, idempotency support, rate limits, retryability, unknown-outcome recovery, and rollback or reconciliation path.
+- Webhook ledger when inbound events exist: signature verification, raw-body requirement, event id, duplicate policy, ordering assumptions, retry behavior, ack timing, async processing, replay tooling, and retention.
+- Error and observability ledger: provider error codes, HTTP statuses, request id, retry-after or reset headers, local error taxonomy, redaction policy, logs, metrics, traces, alerts, and support diagnostics.
+- Existing tests, fakes, sandbox credentials policy, fixtures, runbooks, and command-intent entries for verification.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- Secrets, credentials, tokens, webhook secrets, customer payloads, and provider console output are treated as sensitive. Do not copy them into code, fixtures, docs, logs, test output, or final reports.
+- If provider docs and SDK behavior disagree, record the mismatch and choose an explicit compatibility path instead of guessing.
+- If the provider operation can cause money movement, entitlement changes, customer communication, irreversible mutation, or external side effects, classify unknown outcomes before adding retries.
+- If the provider boundary would leak provider SDK objects, raw provider ids, private URLs, or dashboard-only truth into core logic, use `adapter-boundary` for that boundary before implementing production behavior.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or update provider adapters, wrappers, clients, request/response mappers, error mappers, webhook handlers, fakes, fixtures, sandbox tests, contract tests, runbooks, and docs directly tied to the integration.
+- Add explicit timeout, retry, backoff, jitter, rate-limit, idempotency, pagination, webhook dedupe, observability, and redaction behavior when the repository already supports the required primitives or the change can stay local.
+- Add typed local errors and provider result models that preserve request id, retryability, support evidence, and safe diagnostic detail.
+- Do not hardcode credentials, broaden provider scopes, introduce a new runtime dependency, enable live production calls, or change provider dashboard settings without explicit approval and command authority.
+- Do not implement infinite retries, retry permanent errors, generate a new idempotency key for every retry of the same logical operation, trust webhook payloads before signature verification, or treat success-page redirects as proof of provider completion.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the integration surface.
+   - Outbound: SDK or API call made by the product.
+   - Inbound: webhook, callback, redirect, polling response, or provider event consumed by the product.
+   - Bidirectional: outbound request plus later webhook or callback that confirms, rejects, or updates the same operation.
+2. Establish source of truth before coding. Prefer current provider API reference or schema for wire shape, provider changelog or migration guide for version behavior, local wrapper patterns for code placement, and tests for repository expectations. Treat blog posts, examples, AI output, and stale snippets as hints only.
+3. Choose SDK versus raw API explicitly.
+   - Prefer the official SDK only when it supports the needed endpoint, runtime, auth method, timeout control, retry control, pagination, idempotency, error access, and request id access.
+   - Use raw API only when the SDK lacks coverage or blocks a production requirement, and then provide typed local request/response models, timeout, retry policy, pagination, error mapping, and tests.
+   - Do not let SDK convenience hide auth scopes, retries, idempotency, pagination, or error taxonomy.
+4. Build the auth and environment contract.
+   - Separate sandbox from production credentials.
+   - Load credentials from approved secret surfaces.
+   - Bind tokens or API keys to tenant, organization, account, or environment when applicable.
+   - Validate required scopes before business logic.
+   - Distinguish authentication failure from authorization or scope failure.
+   - Handle token expiration and refresh without logging token values.
+5. Classify every operation before adding retry behavior.
+   - Reads may be retried when timeout and retry budget are bounded.
+   - Mutating requests need a stable idempotency key or another documented duplicate-safety mechanism before retry.
+   - Unknown outcomes after timeout or connection loss must trigger provider lookup, reconciliation, or manual recovery instead of blind replay.
+   - Validation, authentication, authorization, missing-resource, malformed-request, and domain-rejection errors are not transient.
+6. Implement request safety.
+   - Set explicit per-attempt timeout and total attempt budget.
+   - Respect documented rate-limit headers, reset times, and retry-after hints.
+   - Use exponential backoff with jitter for transient failures.
+   - Bound concurrency when provider capacity can starve local work.
+   - Use documented pagination cursors, iterators, or link headers; do not invent next-page URLs or assume stable offset pagination unless the provider promises it.
+7. Implement provider error mapping.
+   - Map provider status, code, message, field errors, request id, retryability, and endpoint into local typed errors.
+   - Preserve enough detail for support without logging secrets, full customer payloads, raw tokens, or payment data.
+   - Make rate-limit, auth, validation, provider outage, timeout, and unknown-outcome errors distinguishable to callers.
+   - Keep provider error classes and SDK response objects out of core logic.
+8. Implement webhook and callback safety when events exist.
+   - Verify signature using the raw body when the provider requires it.
+   - Acknowledge quickly and move expensive work to an internal queue or use case when possible.
+   - Store event id or delivery id before side effects.
+   - Deduplicate repeated events and return safe success for already-processed duplicates.
+   - Do not assume events arrive once, in order, immediately, or only after the user-facing redirect.
+   - Make handlers idempotent and add replay or dead-letter handling when failures need recovery.
+9. Handle SDK/API version drift.
+   - Check changelog and migration guide before SDK or API version upgrades.
+   - Identify breaking changes in auth, endpoint paths, request fields, response fields, error shape, pagination, rate limits, idempotency, webhook payloads, and retry behavior.
+   - Keep old and new behavior side by side when migration risk is high.
+   - Add compatibility tests before replacing production behavior.
+10. Add observability that helps support without leaking data.
+    - Record local operation id, provider request id, endpoint or event name, retry attempt count, final provider status category, retry-after timing, idempotency key hash or local operation id, and redacted error code.
+    - Add metrics or logs for rate-limit hits, retries exhausted, webhook duplicates, invalid signatures, unknown outcomes, SDK version, and migration path when local patterns support them.
+    - Avoid raw provider payload dumps in logs and fixtures.
+11. Test failure paths, not only the first successful call.
+    - Cover auth failure, scope failure, validation failure, timeout, transient 5xx, rate limit, retry exhaustion, idempotent duplicate request, pagination continuation, SDK error mapping, webhook invalid signature, webhook duplicate event, webhook out-of-order event when relevant, and version-upgrade fixture compatibility.
+    - Prefer fakes or sandbox tests unless the repository has explicit live-provider test authority.
+    - Do not mark the integration complete when only the happy path is tested.
+12. Report provider ambiguity honestly. Name undocumented behavior, doc/SDK mismatch, skipped live checks, missing sandbox evidence, manual console steps, missing idempotency support, missing webhook replay tooling, and remaining operational risk.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The integration has explicit auth, environment, timeout, retry, rate-limit, idempotency, pagination, webhook, error, observability, version, and test decisions.
+- Provider-specific behavior is contained at the integration boundary or explicitly classified as a public contract.
+- Failure paths and recovery states are tested, faked, documented, or reported as missing evidence.
+- Secrets and sensitive provider data are not copied into code, fixtures, logs, docs, or reports.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `test_audit`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use the narrowest configured tests that cover the changed provider adapter, webhook handler, error mapping, retry behavior, idempotency behavior, SDK version migration, and docs or template surfaces touched.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If provider docs are missing or contradictory, stop relying on inferred behavior and report the mismatch with the safest local fallback.
+- If mutating operations lack idempotency support, avoid automatic retry and require reconciliation or manual recovery for unknown outcomes.
+- If webhook signatures cannot be verified with current framework parsing, fix the raw-body handling before trusting the event.
+- If tests would require live production credentials, skip them and report the missing configured sandbox or fake instead of using real credentials.
+- If SDK retry behavior is implicit or unconfigurable, wrap or disable it when local retry budgets must be enforced.
+- If a provider dashboard setting is required, document it as manual or config-owned evidence; do not claim code alone enforces it.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Third-party provider and SDK/API surface reviewed
+- Source-of-truth docs, SDK version, changelog, and migration evidence checked
+- Auth, environment, scope, and secret boundary decisions
+- Timeout, retry, rate-limit, idempotency, pagination, and unknown-outcome decisions
+- Webhook or callback delivery, signature, dedupe, ordering, and replay decisions
+- Error mapping, observability, redaction, and support diagnostics
+- Tests added, reused, skipped, or missing for happy and unhappy paths
+- Command intents run
+- Skipped checks and reasons
+- Remaining provider, SDK drift, documentation, sandbox, or operational risk

package/templates/default/locales/en/.mustflow/skills/website-task-friction-review/SKILL.md

@@ -0,0 +1,139 @@
+---
+mustflow_doc: skill.website-task-friction-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: website-task-friction-review
+description: Apply this skill when a public website, landing page, marketing page, ecommerce flow, signup flow, checkout flow, account page, support surface, navigation, search, form, mobile web surface, cookie or consent surface, pricing page, or conversion path is planned, edited, reviewed, or reported and common user complaints such as slowness, popups, forced signup, confusing navigation, broken mobile layout, unclear errors, hidden costs, dark patterns, weak trust, or missing recovery paths must be prevented.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.website-task-friction-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Website Task Friction Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Prevent website changes from blocking the user's intended task. Review the site by whether a real visitor can find, understand, decide, enter information, recover from errors, trust the service, and complete the action without surprise or coercion.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A change touches a public website, landing page, ecommerce page, product page, pricing page, signup flow, checkout flow, account flow, support page, help center, contact path, search path, cookie or consent surface, promotional overlay, or mobile web experience.
+- A task asks for website UX review, conversion review, landing-page polish, navigation improvement, form or checkout improvement, mobile usability, trust signals, dark-pattern removal, or complaint prevention.
+- A report claims a website is usable, fast, clear, trustworthy, accessible, mobile-ready, conversion-ready, or ready to ship.
+- A UI change could add friction through overlays, forced account creation, hidden fees, vague copy, long forms, weak error recovery, hard-to-find support, inaccessible controls, or slow first interaction.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task changes only backend internals, CLI output, data processing, or documentation with no public website or user task path.
+- The task is only visual component geometry, hostile content, responsive container behavior, or layout stress; use `frontend-stress-layout-review` for that focused layer.
+- The task is only accessibility-tree semantics, keyboard behavior, focus, ARIA, labels, or assistive-technology evidence; use `frontend-accessibility-tree-review` for that focused layer.
+- The task is only first-render performance, Core Web Vitals field instrumentation, image delivery, bundle size, or frame rendering; use the narrower performance skill for that focused layer.
+- The task is an internal dashboard or app UI with no public website, acquisition, support, signup, checkout, or visitor conversion path; use `ui-quality-gate`.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The primary visitor task, target audience, entry point, and expected completion point.
+- The changed route, page, component, copy, form, navigation, search, checkout, support, consent, or conversion surface.
+- Existing product constraints, legal requirements, pricing, account requirements, support policy, privacy boundary, and trust or compliance claims relevant to the flow.
+- The likely devices and input modes, especially small-screen touch use, keyboard use, slow networks, logged-out users, new users, returning users, and users with incomplete information.
+- Current evidence from code, tests, screenshots, analytics, complaints, support tickets, field metrics, or product requirements when available.
+- Relevant command-intent contract entries for status, diff, docs, build, test, release, visual, browser, accessibility, or mustflow validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- The primary user task can be named. If it cannot, stop and ask for or infer the smallest plausible task from repository evidence, then report the uncertainty.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Change website copy, navigation labels, page order, form fields, validation, error states, mobile layout, support links, trust disclosures, pricing visibility, consent behavior, and recovery paths when they directly reduce task friction.
+- Remove or defer overlays, decorative content, forced account gates, vague marketing blocks, nonessential form fields, misleading urgency, and interruptions that do not help the current task.
+- Add focused tests, fixtures, docs, or template updates that preserve the website task contract.
+- Do not invent pricing, policy, compliance, delivery, guarantee, refund, legal, or support claims.
+- Do not add dark patterns, hidden costs, coerced consent, preselected paid add-ons, fake urgency, nagging opt-ins, or visually weakened rejection controls.
+- Do not claim visual, mobile, accessibility, performance, or interactive verification without actual evidence or a named verification gap.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Name the primary visitor task in plain language. Use the user's words, not the company's internal taxonomy.
+2. Walk the task from entry to completion: arrive, orient, find, compare, decide, enter information, submit or pay, recover from failure, and get help.
+3. Identify the first blocking point. Treat a delay, forced decision, hidden requirement, unclear label, missing price, broken mobile control, or vague error as a product defect, not a cosmetic nit.
+4. Check interruption pressure. Avoid first-task-blocking newsletter modals, app-install prompts, surveys, promotional overlays, cookie banners beyond legal need, chat widgets covering controls, and upsells that block completion.
+5. Check account pressure. Do not force account creation before checkout, booking, inquiry, download, trial, or support unless the product cannot function without an account. Offer guest, passkey, magic-link, or deferred-account paths when the business rules allow them.
+6. Check cost and commitment clarity. Show total price, taxes, shipping, fees, renewal terms, cancellation terms, delivery estimates, refund rules, and required commitments before the user reaches the final commit action.
+7. Check navigation and search. Labels should match user vocabulary, sibling categories should be distinguishable, search should be discoverable on content-heavy sites, and no-results states should offer spelling help, related links, popular paths, or a way back to browsing.
+8. Check mobile task completion. Core tasks must work on small screens without zooming, hover, tiny targets, horizontal scrolling, covered bottom actions, keyboard-covered inputs, or sticky elements hiding validation messages.
+9. Check form load. Every field must earn its place for the current task. Use labels, input types, autocomplete, examples, sane defaults, grouped fields, inline recovery, preserved entered data, and field-level errors.
+10. Check error language. Replace developer-centered messages with what happened, which field or action needs attention, how to fix it, and whether the user's entered data or payment state is safe.
+11. Check trust and proof. Make operator identity, contact, support, security, privacy, returns, cancellation, unsubscribe, delete-account, and policy paths findable where users expect them. Do not bury trust-critical information behind marketing copy.
+12. Check content for scanning. Put the next decision near the top, use concrete headings, remove vague claims, shorten paragraphs, and expose requirements, limits, risk, price, and next steps before asking for commitment.
+13. Check accessibility as task completion. Keyboard-only users, screen-reader users, zoomed users, users with reduced motion, and users who cannot rely on color should complete the same task with visible focus, labels, error associations, contrast, target size, and no focus traps.
+14. Check performance from the user's patience budget. Prefer evidence for Core Web Vitals, responsive first interaction, stable layout, reserved media dimensions, bounded third-party scripts, and no render-blocking decorative assets.
+15. Check recovery and support. Users should have a next useful action after search failure, validation failure, payment failure, permission denial, empty state, unavailable inventory, timeout, expired session, or partial submission.
+16. Check coercion and dark patterns. Remove hidden opt-outs, fake urgency, confirmshaming, cancellation mazes, prechecked add-ons, subscription traps, unclear consent, and asymmetric accept or reject controls.
+17. If the issue belongs to a narrower skill, route the focused fix there after naming the website-level friction. Examples: Core Web Vitals, image delivery, bundle pruning, accessibility tree, layout stress, localization, payment integrity, or support-surface selection.
+18. For implemented fixes, preserve existing style, component, data, policy, and localization patterns. Do not add a one-off UX framework or dependency for a flow-level problem.
+19. Use the narrowest configured verification that covers the changed website, docs, package, template, or mustflow contract.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The primary visitor task is named and can be followed without unnecessary interruption.
+- Navigation, search, mobile use, forms, errors, accessibility, performance, trust, cost clarity, account pressure, support, and recovery paths are checked or explicitly reported as unverified.
+- Any dark pattern, hidden commitment, invented claim, or support-policy uncertainty is removed, deferred, or reported.
+- Focused follow-up skills are named when a narrower performance, accessibility, layout, payment, support, localization, or security review is still needed.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use a narrower configured build, browser, screenshot, accessibility, performance, or related-test intent when it better proves the changed website task path.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the primary task is unclear, stop broad polishing and identify the task before editing.
+- If business, legal, pricing, support, or compliance facts are missing, do not invent them; add placeholders only when the repository already uses placeholder policy text and report the unresolved authority.
+- If visual or interactive inspection is unavailable, report the unverified viewport, device, state, and interaction instead of claiming the website is ready.
+- If a stakeholder asks for a friction pattern, such as forced signup or an interrupting popup, implement the least coercive version allowed by direct instructions and report the conversion, trust, support, and regulatory risk.
+- If a fix conflicts with a narrower skill's rule, follow the stricter task-safety or public-contract rule and report the conflict.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Website task reviewed
+- Entry point and completion point
+- Friction findings by severity
+- User complaint in the user's likely words
+- Cause, fix, and acceptance test
+- Navigation, search, mobile, form, error, accessibility, performance, trust, pricing, consent, support, and recovery checks
+- Narrower skills used or recommended
+- Command intents run
+- Skipped visual or interactive checks and reasons
+- Remaining website task risk