@harness-engineering/cli 1.24.0 → 1.24.3

package/dist/agents/skills/codex/ux-microcopy-principles/skill.yaml

@@ -0,0 +1,37 @@
+name: ux-microcopy-principles
+version: "1.0.0"
+description: Microcopy principles — clarity, brevity, human voice, active voice, and the core rules all UI text follows
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-voice-tone
+  - ux-plain-language
+  - ux-active-voice
+  - ux-content-hierarchy
+  - ux-writing-for-scanning
+  - ux-inclusive-language
+  - ux-internationalization-writing
+stack_signals: []
+keywords:
+  - microcopy
+  - ui-text
+  - clarity
+  - brevity
+  - human-voice
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/ux-navigation-labels/SKILL.md

@@ -0,0 +1,163 @@
+# Navigation Labels
+
+> Navigation label writing — menu item naming, breadcrumb clarity, tab labels, and sidebar organization that users scan without reading
+
+## When to Use
+
+- Writing sidebar navigation items and categories
+- Naming tabs in tabbed interfaces
+- Writing breadcrumb labels for hierarchical navigation
+- Naming top-level menu items and dropdown menu entries
+- Auditing existing navigation for clarity, consistency, and scannability
+- NOT for: action buttons within pages (see ux-button-cta-copy)
+- NOT for: link text that triggers an action rather than navigation (see ux-button-cta-copy)
+- NOT for: onboarding step names in setup wizards (see ux-onboarding-copy)
+
+## Instructions
+
+1. **Navigation labels are nouns, not verbs.** "Settings" not "Configure settings." "Projects" not "Browse projects." "Billing" not "Manage billing." Navigation items name destinations — places the user goes, not actions they take. The distinction matters because verbs imply an immediate action will occur on click; nouns imply navigation to a place. "Delete" as a nav item suggests immediate deletion. "Archive" as a nav item is ambiguous. The exception: top-level navigations in settings panels sometimes use verb phrases like "Sign out" (an action, not a destination) — these are acceptable because the action IS the destination.
+
+2. **Front-load the distinguishing word.** "Project settings" not "Settings for your project." "Team members" not "Members of your team." "API keys" not "Keys for the API." Users scan the first word of every navigation item — the distinguishing word must come first. In a sidebar with ten items, each item's first word must be different enough to be distinguishable by the first word alone. Compare: "Account preferences / Billing preferences / Notification preferences" — "Account," "Billing," "Notification" are the distinguishing words, front-loaded. Compare the failure mode: "Preferences for your account / Preferences for billing / Preferences for notifications" — all start with "Preferences," which is useless for scanning.
+
+3. **Keep labels to 1-2 words maximum for sidebar and tab navigation.** Sidebar items: "Projects," "Issues," "Members," "Settings." Tab labels: "Overview," "Activity," "Files," "Settings." Three-word labels are acceptable when specificity genuinely requires it: "API keys," "Audit log," "Team members." Four-word labels are almost never justified in navigation — if four words are needed, the item is likely trying to do two things at once and should be split. GitHub's sidebar labels are all 1-2 words. Linear's navigation labels are all 1-2 words. Stripe's dashboard navigation labels are all 1-2 words. The pattern is consistent across best-in-class products.
+
+4. **Breadcrumbs reflect the page hierarchy exactly — no summarization.** The breadcrumb "Acme Corp / Projects / Acme Dashboard / Settings" maps to the exact navigation path. Do not summarize: "Acme Corp / ... / Settings" hides the hierarchy. Do not reorder: "Settings / Acme Dashboard / Projects / Acme Corp" reverses the direction. Do not rename: if the page is titled "Notification preferences," the breadcrumb reads "Notification preferences," not "Notifications" (a shortening) or "Manage your notification preferences" (an expansion). Breadcrumbs are a navigational record — they show where the user is, derived from where they were, in the exact order they navigated there.
+
+5. **Avoid "Misc," "Other," and "General" as category labels.** These are the navigation equivalent of dumping everything that does not fit neatly into a drawer labeled "stuff." Users cannot predict what is inside. "General settings" is slightly better than "Misc" because at least the category is named, but "Display settings" or "Workspace settings" or "Account settings" are all more useful because users can predict their contents. When forced to create a "miscellaneous" category, name it by its most significant members: "Integrations & API" or "Advanced" or "Developer settings" — each signals a user profile and a topic, not a catch-all.
+
+6. **Group related items under category labels and limit groups to 5-7 items.** A sidebar with 20 ungrouped items is a wall of text. Grouped by category — "Workspace: Projects, Members, Settings" and "Account: Profile, Billing, Security" — the sidebar becomes scannable. Category labels function as section headers that allow users to skip irrelevant categories entirely. GitHub's repository sidebar groups: "Code," "Issues," "Pull requests," "Actions," "Projects," "Wiki," "Security," "Insights," "Settings" — nine top-level items, each representing a distinct workflow area. The grouping is implicit (no category headers) but the items are organized by workflow proximity.
+
+7. **Use the word users would search for — not internal product naming.** If users type "dark mode" into a search bar, the setting should be labeled "Dark mode" or at minimum live in a section labeled "Appearance," not "Theme rendering options." If users search for "payment method," the page should be labeled "Payment methods," not "Billing instruments." Internal product naming (technical or marketing terms that are not in common use) creates a scannability failure — users cannot find the item because they are scanning for a word that does not appear in the navigation. The test: what would a new user type into the product's search bar to find this section?
+
+8. **Tab labels describe the content of the tab, not actions performed there.** "Overview" not "See overview." "Members" not "Manage members." "Files" not "View files." Tab labels are destinations within a page — they follow the same noun-not-verb rule as navigation items. The one exception: tabs that represent distinct workflows where the action distinguishes two tabs with similar content. "Edit" and "Preview" are acceptable action-based tab labels because the action (edit vs. preview) is precisely what distinguishes them. "Compare" and "Diff" are acceptable because both are actions with distinct outputs.
+
+## Details
+
+### Navigation Label Length by Context
+
+Navigation labels have strict length constraints by context:
+
+| Navigation Type | Maximum Words | Maximum Characters | Example              |
+| --------------- | ------------- | ------------------ | -------------------- |
+| Sidebar item    | 2 words       | 20 characters      | "Team members"       |
+| Tab label       | 2 words       | 15 characters      | "Activity"           |
+| Top-level menu  | 1-2 words     | 15 characters      | "Settings"           |
+| Dropdown item   | 3 words       | 30 characters      | "Export as CSV"      |
+| Breadcrumb node | 3-4 words     | 40 characters      | "Notification prefs" |
+| Category header | 1-2 words     | 20 characters      | "Workspace"          |
+
+### Navigation Naming Conventions by Product Type
+
+Navigation terminology varies by product type — use the terms users of that product type already know:
+
+| Product Type    | Dashboard Label | Users Label | Settings Label | Activity Label |
+| --------------- | --------------- | ----------- | -------------- | -------------- |
+| Developer tool  | "Overview"      | "Members"   | "Settings"     | "Activity"     |
+| E-commerce      | "Dashboard"     | "Customers" | "Preferences"  | "Orders"       |
+| Design tool     | "Home"          | "Team"      | "Settings"     | "History"      |
+| Project manager | "Dashboard"     | "People"    | "Settings"     | "Activity"     |
+| Communication   | "Inbox"         | "Contacts"  | "Preferences"  | "All messages" |
+
+Match the convention of adjacent products in the same category — users carry navigation expectations from product to product. Surprising a user who expects "Preferences" with "Configuration" creates unnecessary friction.
+
+### Sidebar Organization Principles
+
+**Maximum depth:** 2 levels (top-level items and one level of subitems). Three-level navigation requires the user to remember three layers of hierarchy while navigating — excessive cognitive load. If a third level is necessary, use breadcrumbs to show the user's position.
+
+**Maximum items per level:** 7 items at the top level, 5-7 subitems per category. Beyond these limits, grouping is needed. The "7 plus or minus 2" rule (Miller's Law) applies directly to navigation — users can hold 5-9 items in working memory.
+
+**Order:** Most frequently accessed items first (not alphabetical, not chronological). GitHub puts "Code" first because that is the most-accessed section for most repositories. Linear puts "Issues" first. Stripe puts "Dashboard" first. Alphabetical ordering is a failure mode — it prioritizes the organization system over user behavior.
+
+### Breadcrumb Patterns
+
+Well-formed breadcrumbs:
+
+- Show the full path: "Acme Corp / Projects / Acme Dashboard / Settings"
+- Use the exact page titles as labels (no renaming, no abbreviation)
+- Are clickable at every level except the current page (which is not a link)
+- Use "/" or ">" as a separator — "/" for URL-style products, ">" for app-style products
+- Do NOT include "Home" unless the product's first level is literally called "Home"
+
+Malformed breadcrumbs that fail users:
+
+- Truncated paths: "Acme Corp / ... / Settings" hides the middle navigation
+- Renamed labels: "Settings" when the page title is "Workspace settings"
+- Missing levels: "Acme Corp / Settings" when the actual path is "Acme Corp / Projects / Settings"
+
+### Navigation Labels for Localization
+
+Navigation labels must survive translation without breaking scannability or layout:
+
+- **Prefer short nouns that translate compactly:** "Settings" is 8 characters; "Einstellungen" (German) is 14 characters. Navigation containers must be wide enough for common translations.
+- **Avoid culturally specific terms:** "Inbox" is widely understood; "Cubbies" or branded terms are not.
+- **Test with German and Arabic:** German tests character expansion (labels grow 20-35% in translation); Arabic tests RTL layout (navigation order reverses).
+- **Front-loaded distinguishing words survive translation better:** "Project settings" becomes "Projekteinstellungen" in German — the noun stays at the start, preserving scannability.
+
+Navigation labels that are 1-2 words in English are typically still 1-3 words in most European languages. Labels that are 3-4 words in English frequently become 6-8 words in German, breaking sidebar layout. The character budget for navigation labels should be designed for the widest common translation, not the English original.
+
+### Anti-Patterns
+
+1. **The Verb Nav Label.** Navigation items that use verbs: "Configure settings," "Manage team," "View projects," "Browse issues." Navigation items name destinations (nouns), not the actions taken there (verbs). "Manage team" tells the user what they will do, but navigation labels should tell the user where they are going. The verb-as-label pattern also creates visual inconsistency when mixed with noun labels — a sidebar with "Projects / Members / Configure settings / Activity" reads as inconsistent. Fix: convert all navigation labels to nouns.
+
+2. **The Misc Catch-All.** A navigation section labeled "Misc," "Other," "More," or "General" that contains items that do not fit into any other category. Users cannot predict what is inside and avoid it. Product teams that create catch-all categories are usually working around an information architecture problem — the primary categories are wrong, or there are too many primary categories. The fix is to either create a specific category for the displaced items, or combine them with the closest related category and rename.
+
+3. **The Ambiguous Icon-Only.** Icon-only navigation in a collapsed sidebar with no label and no tooltip. The "house" icon might mean "Home" or "Dashboard" or "Overview." The "star" icon might mean "Favorites" or "Starred items" or "Featured." Without labels, users must learn the icon vocabulary through exploration, which creates a barrier for new users and a recurring tax for infrequent users. The fix: always show labels on navigation items, or at minimum show labels on hover. Tooltips are not sufficient for primary navigation — they require hovering over each item to identify it.
+
+4. **The Deep Nest.** Navigation with three or more levels of hierarchy: "Settings / Workspace / Members / Roles / Permissions / Edit." At three levels, users lose track of where they are. At four levels, navigation becomes a maze. The fix is to flatten the hierarchy: move the most important subpages to the top level, merge less-important subpages into their parent, and use in-page tabs or sections for remaining sub-navigation. If the hierarchy genuinely requires depth, use breadcrumbs to show position and ensure every level has a clear parent link.
+
+### Real-World Examples
+
+**GitHub's Repository Sidebar.** GitHub's repository sidebar uses 9 top-level items: Code, Issues, Pull requests, Actions, Projects, Wiki, Security, Insights, Settings. Each is 1-2 words, each is a noun, each names a distinct workflow area. The sidebar is ungrouped but naturally clusters into workflow areas: content (Code), collaboration (Issues, Pull requests), automation (Actions), organization (Projects, Wiki), and administration (Security, Insights, Settings). Users familiar with GitHub can navigate to any section without reading — they scan for the first word of the target item. The sidebar has been stable for years, which means user muscle memory is deeply established.
+
+**Stripe's Dashboard Navigation.** Stripe's sidebar groups navigation items into workflow areas: "Payments" (contains Payments, Customers, Subscriptions, Products), "Connect" (for marketplace products), "Reporting" (contains Reports, Revenue recognition), and "Developers" (contains API keys, Webhooks, Logs). The grouping by workflow rather than alphabetically or by feature type means merchants can find related items without understanding Stripe's internal product taxonomy. Each top-level item and sub-item uses 1-2 words. The navigation is learnable within one or two sessions.
+
+**Linear's Left Rail.** Linear's navigation rail is organized by workspace and project: workspace-level items (Inbox, My issues, Favorites) at the top, followed by project items (Issues, Cycles, Projects, Views, Members, Settings) under each project. The personal vs. project distinction creates a mental model that matches how users think about their work. Label naming is minimal: "Inbox" (one word), "Issues" (one word), "Cycles" (one word). The navigation terminology is Linear-specific ("Cycles" instead of "Sprints") but is introduced during onboarding and consistent throughout.
+
+**Figma's Toolbar Organization.** Figma's toolbar is organized by tool category: move/select tools at the left, shape tools grouped together, text and component tools, and view tools at the right. The organization follows the order in which tools are used in a typical design workflow — from layout (move, frame) to content (shapes, text) to review (zoom, inspect). Navigation labels are not used — the toolbar is icon-only — but the organization follows a left-to-right workflow logic that users can internalize. The tooltip pattern ("Frame (F)", "Rectangle (R)") provides labels on demand without cluttering the toolbar with text.
+
+## Source
+
+- NNGroup — "Navigation Labels: Signposts That Direct People" (2016), https://www.nngroup.com/articles/navigation-labels/
+- NNGroup — "Breadcrumb Navigation Increasingly Useful" (2007), https://www.nngroup.com/articles/breadcrumb-navigation-useful/
+- Google Material Design — Navigation drawer, https://m3.material.io/components/navigation-drawer/guidelines
+- Apple Human Interface Guidelines — Tab bars and navigation, https://developer.apple.com/design/human-interface-guidelines/tab-bars
+- Morville, P. & Rosenfeld, L. — _Information Architecture for the Web and Beyond_ (2015), labeling and navigation taxonomy
+
+## Process
+
+1. Audit all existing navigation items and convert any verb labels to noun labels.
+2. Verify each label is 1-2 words with the distinguishing word first.
+3. Group items into categories of 5-7 items with specific category names (no "Misc" or "Other").
+4. Verify breadcrumbs match the exact page title hierarchy — no renaming, no summarization.
+5. Test navigation labels against the "search word" test: would a new user type this word into a search bar to find this section?
+
+### Navigation Label Copy Review Checklist
+
+Before shipping navigation labels, verify each item:
+
+| Check                                    | Pass Criteria                                            |
+| ---------------------------------------- | -------------------------------------------------------- |
+| All labels use nouns, not verbs          | No "Manage," "Configure," "Browse" as primary nav labels |
+| Distinguishing word leads each label     | First word is unique and meaningful, not generic         |
+| Sidebar/tab labels are 1-2 words         | No label over three words in primary navigation          |
+| No catch-all categories                  | No "Misc," "Other," "General" without specific content   |
+| Groups contain 5-7 items maximum         | Larger sections are split or reorganized                 |
+| Breadcrumbs match exact page titles      | No renaming, no summarization, no skipped levels         |
+| Labels pass the search-word test         | A new user would type the label's key word to find it    |
+| Icon-only navigation has labels on hover | Tooltips with the label name on all icon-only nav items  |
+
+Navigation label audits should include a card-sorting test with representative users: give users cards labeled with the current navigation items and ask them to sort them into groups they find logical. Discrepancies between user groupings and current navigation reveal mental model mismatches that cannot be found through copy review alone.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- All navigation labels use nouns, not verbs — no "Manage," "Configure," or "Browse" as navigation items.
+- Labels are 1-2 words maximum for sidebar and tab navigation.
+- The distinguishing word leads each label — no labels starting with a generic qualifier ("Settings for...").
+- No catch-all categories ("Misc," "Other," "General") appear in the navigation.
+- Breadcrumb labels match the exact page titles at each level of the hierarchy.
+- Navigation items are testable by the search-word test: a new user would type the label's key word to find the section.

package/dist/agents/skills/codex/ux-navigation-labels/skill.yaml

@@ -0,0 +1,35 @@
+name: ux-navigation-labels
+version: "1.0.0"
+description: Navigation label writing — menu item naming, breadcrumb clarity, tab labels, and sidebar organization that users scan without reading
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-content-hierarchy
+  - ux-microcopy-principles
+  - design-information-architecture
+  - design-navigation-ux
+stack_signals: []
+keywords:
+  - navigation
+  - menu-labels
+  - breadcrumbs
+  - tabs
+  - sidebar
+  - information-architecture
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/ux-notification-copy/SKILL.md

@@ -0,0 +1,150 @@
+# Notification Copy
+
+> Notification and alert copy — urgency calibration, actionability, toast vs banner vs modal selection, and writing messages that inform without overwhelming
+
+## When to Use
+
+- Writing toast and snackbar messages for completed or failed actions
+- Composing persistent banners for warnings, system status, and billing alerts
+- Writing push notifications and in-app notification feed copy
+- Creating alert copy for blocking system states (maintenance, outage, permission required)
+- Writing notification center entries and email notification subject lines
+- NOT for: error messages attached to form fields (see ux-error-messages)
+- NOT for: confirmation dialogs for destructive actions (see ux-confirmation-dialogs)
+- NOT for: success feedback that follows a specific user action (see ux-success-feedback)
+
+## Instructions
+
+1. **Match notification type to urgency level — the component choice is a copy decision.** Toast for completed actions and low-urgency info (auto-dismisses in 3-5 seconds). Banner for persistent warnings and system status (stays until dismissed or resolved). Modal for blocking system states that require immediate action. Using a toast for a billing failure that requires action — and having it auto-dismiss — means the user misses critical information. Using a modal for a routine "changes saved" message interrupts the user unnecessarily. The component type is the first line of urgency communication; the copy reinforces it.
+
+2. **Front-load the subject — actor, then action.** "Jordan commented on your PR" not "You have a new notification from Jordan." "Deployment failed" not "There was a failure in your deployment." "Payment of $49.99 succeeded" not "Your recent payment transaction has been successfully processed." The first word of a notification is the most important word — it determines whether the user reads the rest. In a notification list, ten notifications all starting with "You have" are indistinguishable at a glance. Ten notifications starting with different actors or objects are scannable.
+
+3. **Include one action maximum — never two.** "Reply" or "View" — not both. When a notification offers two actions of equal weight, the user is paralyzed: which one do they need? Two actions also increase the risk of accidental taps on mobile. If two actions are necessary, make the primary action a button and the secondary action a plain text link — the visual hierarchy communicates the priority. Slack's notifications offer "Reply" as the only action. Linear's notifications offer "Open issue" as the only action. The constraint forces the writer to decide: what is the single most important thing the user might want to do?
+
+4. **Calibrate length to dismissal behavior.** Toasts auto-dismiss in 3-5 seconds — the user reads approximately 7-10 words in that window. Keep toast copy to 40-80 characters. Banners are persistent — the user can read more. Keep banner copy to 80-120 characters for the primary message, with a "Learn more" link for detail. Push notifications have a subject line (40-50 chars) and a body (100-120 chars) — front-load the most critical information in the subject. The character limit is a function of the time the user has to read the notification, not an arbitrary constraint.
+
+5. **Never say "notification" in a notification — it is redundant.** "You have a new notification" is a notification telling the user they have a notification. "Jordan commented on your pull request" is a notification. "New message from Jordan: 'Can you review the PR?'" is a notification. The word "notification" adds nothing to the message and wastes space in a character-constrained format. The same principle applies to "alert," "message," and "update" — lead with the actual content, not the content category.
+
+6. **Name the actor in social and activity notifications.** "Jordan" not "Someone." "The Acme team" not "A team." "You" only when there is no other actor (system-generated, user-initiated). Social notifications that anonymize the actor are less actionable and less engaging. GitHub names the specific user who commented, reviewed, or merged. Slack names the specific person who messaged or reacted. Linear names the assignee or commenter. The name creates context for the notification's relevance — "Jordan commented" is more actionable than "Someone commented" because the user knows if Jordan's opinion matters to them right now.
+
+7. **Use past tense for completed events, present for ongoing, future for upcoming.** "Deployment completed" (past, done). "Deployment in progress — 2 of 4 steps complete" (present, active). "Deployment scheduled for 3:00 PM EST" (future, upcoming). The tense communicates the state without additional words. "Your deployment is complete" wastes "is" when "Deployment complete" communicates the same state. "There has been a completion of the deployment process" is the robot-voice version of "Deployment complete." Match tense to state.
+
+8. **For actionable notifications, make the action obvious without requiring the user to open the source.** "Jordan requested a review on PR #247: Fix authentication timeout" gives enough context that the user can decide whether to act without opening GitHub. "Jordan requested review" requires opening GitHub to understand what to review. "New request" requires two clicks to understand. The notification should answer: who, what, and enough context to decide whether to act now. The action button provides the "act now" path; the copy provides the "should I act now?" context.
+
+## Details
+
+### Notification Type Decision Matrix
+
+Select the notification type based on urgency and whether the user can safely continue:
+
+| Type           | Urgency    | Dismissal      | Max Length | Action Required? | Example                               |
+| -------------- | ---------- | -------------- | ---------- | ---------------- | ------------------------------------- |
+| Toast          | Low        | Auto (3-5s)    | 80 chars   | Optional         | "Changes saved"                       |
+| Snackbar       | Low-medium | Auto + dismiss | 120 chars  | One optional     | "Message sent. Undo"                  |
+| Banner         | Medium     | Manual         | 160 chars  | One recommended  | "Your trial ends in 3 days. Upgrade." |
+| Alert banner   | High       | Manual         | 200 chars  | One required     | "Payment failed. Update billing."     |
+| Blocking modal | Critical   | Action only    | Full modal | Required         | "Your account has been suspended."    |
+
+### Notification Copy Patterns by Category
+
+**Completed action (success toast):** Past tense, object named. "Issue #247 closed." "Report exported." "Team member invited." Never: "Done!" or "Success!" — these are too vague to be meaningful.
+
+**Social activity:** Actor + action + object. "Jordan commented on your PR." "The Acme team assigned you to Issue #42." "Sarah approved your expense report." Name the actor first.
+
+**System alert:** System + consequence + action. "Deployment failed. View logs →." "Sync paused. Check your connection." "Storage 90% full. Manage files →."
+
+**Scheduled event:** Time + event. "Team standup in 15 minutes." "Invoice due in 3 days." "Subscription renews on April 30."
+
+**Billing:** Specific amount + action. "Payment of $149 failed. Update card →." "Your plan renews for $49 on May 1." Always include the dollar amount — "payment failed" without an amount is less actionable than "payment of $149 failed."
+
+### Push Notification Subject Lines
+
+Push notifications are read in a notification tray without opening the app — the subject line must be independently comprehensible:
+
+| Category | Pattern                 | Example                                 |
+| -------- | ----------------------- | --------------------------------------- |
+| Social   | Actor + action + object | "Jordan commented on your pull request" |
+| Reminder | Event + time            | "Team standup starts in 10 minutes"     |
+| Alert    | System + consequence    | "Deployment failed on acme-api"         |
+| Billing  | Amount + action needed  | "$149 payment failed — action required" |
+| Progress | Operation + status      | "Your export is ready to download"      |
+
+### Anti-Patterns
+
+1. **The Notification Notification.** "You have a new notification from Jordan about your project." Every word except "Jordan" and "project" is structural overhead. The notification says it is a notification — obvious — that it's new — obvious — from a person — obvious. The content is "Jordan did something to your project." What did Jordan do? What project? These are the words that belong in the notification. The fix: delete every word that describes the notification format rather than the notification content.
+
+2. **The Action Overload.** A notification with three or four action buttons: "Reply," "Mark as read," "Snooze," "View in app." On mobile, four action buttons on a notification makes tapping the correct one difficult. In a notification feed, four buttons per notification creates visual noise that makes scanning impossible. The fix: one primary action button. Surface secondary actions in the full notification view, not in the notification itself.
+
+3. **The Urgency Inflation.** Marking routine events as urgent using all-caps, exclamation points, or "URGENT:" prefixes. "URGENT: Jordan commented on your issue" — Jordan's comment is not an emergency. Urgency inflation trains users to ignore urgency signals, which means real urgent notifications (payment failure, security alert) are ignored alongside the inflated ones. Reserve urgency markers for genuinely time-sensitive events: "ACTION REQUIRED: Payment failed — account suspended in 24 hours."
+
+4. **The Vague Alert.** "Something happened to your project." "There's a problem with your account." "An error occurred." The user cannot act on a vague alert. They must open the app, navigate to the relevant section, and investigate what happened — and by then, the notification has already failed at its primary job (giving the user enough context to decide whether to act). Every notification must name the specific subject, action, and consequence. "Payment failed" is a vague alert. "Payment of $149.00 declined — update your billing info to keep your subscription" is actionable.
+
+### Real-World Examples
+
+**GitHub's PR Notification System.** GitHub's notifications follow a strict format: actor + action + context. "Jordan Doe reviewed your pull request: Fix authentication timeout in auth.ts." The reviewer's full name, the action (reviewed), the PR title (which adds context), and the file context. In the notification feed, each notification is independently scannable — users can triage 20 PR notifications in seconds because each one names a different actor and action. GitHub's mobile push notifications truncate the PR title but always lead with the actor's name: "Jordan Doe reviewed your PR."
+
+**Slack's Message Notifications.** Slack's in-app notifications are minimal and conversational: "Jordan: Can you review this before the meeting?" — sender name, message content. No preamble, no "You have a new message from," no "In #engineering." The channel context is provided visually (the notification appears under the channel or DM), so the copy does not need to repeat it. Slack's push notifications add the channel for non-DM messages: "Jordan in #engineering: Can you review this before the meeting?" — adding exactly the context needed for a push notification where visual context is absent.
+
+**Linear's Issue Assignment Notifications.** Linear's notifications follow: "Jordan assigned you to: #247 Fix authentication timeout." Assignee, action, issue number, issue title. The issue number allows users who track by number to identify the issue without opening it. The issue title provides enough context to prioritize. Linear's notification feed is sorted by recency and can be filtered by type (assigned, mentioned, commented) — the copy format is consistent across types, making the feed scannable by the leading action word.
+
+**Stripe's Payment Alert System.** Stripe's payment failure notifications balance technical precision with human language: "A payment of $149.00 from Acme Corp failed. The card was declined. Update your payment method to keep Acme Corp's subscription active." Three sentences: amount and payer (context), reason (cause), consequence and action (next step). Stripe names the specific customer, the specific amount, and the specific consequence — which is critical for merchants who process multiple customers' payments simultaneously. Vague "payment failed" notifications are useless for a merchant with 1,000 active subscriptions.
+
+## Source
+
+- NNGroup — "Mobile Notifications: 8 Design Guidelines" (2019), https://www.nngroup.com/articles/mobile-notifications/
+- NNGroup — "When to Use Which User-Experience Research Methods" (2014), selecting feedback surfaces by urgency
+- Wroblewski, L. — _Mobile First_ (2011), notification and alert patterns in constrained-screen contexts
+- Apple Human Interface Guidelines — Notifications, https://developer.apple.com/design/human-interface-guidelines/notifications
+- Google Material Design — Snackbars and banners, https://m3.material.io/components/snackbar/guidelines
+- Yifrah, K. — _Microcopy: The Complete Guide_ (2017), notification and alert copy patterns
+- Podmajersky, T. — _Strategic Writing for UX_ (2019), notification taxonomy and copy frameworks
+
+### Notification Copy for Email Subjects
+
+Email notifications extend the in-app notification's reach. Subject lines must function without opening the email:
+
+- **Actor first:** "Jordan Lee requested your review on PR #247" not "New pull request review request"
+- **Specificity over brevity when specificity is actionable:** "Payment of $149 failed — update billing" is better than "Payment issue" for email subjects
+- **Preheader text:** The preview text after the subject line should add context, not repeat: Subject "Jordan requested review", preheader "Fix authentication timeout — PR ready for your input"
+- **Avoid:** "You have a notification," "Action required" (without specifying the action), "Important update" (without specificity)
+
+Email notification subjects follow the same actor-first, specificity-over-brevity rules as in-app notifications, with the additional constraint that subjects compete with dozens of other emails in an inbox — they must be distinguishable at a glance.
+
+## Process
+
+1. Select the notification type (toast, banner, modal, push) based on urgency and whether the user can safely continue.
+2. Write the copy with actor-first structure: who did what to which object.
+3. Trim to the character limit for the selected notification type (toast: 80 chars, banner: 160 chars).
+4. Include one action maximum — identify the single most important thing the user might want to do.
+5. Verify tense matches state: past for completed, present for ongoing, future for upcoming.
+
+### Notification Copy Review Checklist
+
+Before shipping notification copy, verify each item:
+
+| Check                                 | Pass Criteria                                                |
+| ------------------------------------- | ------------------------------------------------------------ |
+| Component type matches urgency        | Toast = low, banner = medium, modal = blocking               |
+| Actor-first structure                 | Subject/actor is the first word, not structural preamble     |
+| Length within limit                   | Toast ≤80 chars, banner ≤160 chars, push subject ≤50 chars   |
+| One action maximum                    | Single primary action button or link                         |
+| No redundant category word            | "Notification," "alert," "message" not as first word         |
+| Correct tense                         | Past for completed, present for ongoing, future for upcoming |
+| Social notifications name the actor   | Person's name used, not "Someone" or "A user"                |
+| Billing notifications name the amount | "$149" not "a payment" — specific amounts always             |
+
+Notification copy failure has a compounding effect: poor notifications train users to dismiss all notifications without reading, which means critical notifications (payment failures, security alerts) are also dismissed. Investment in notification copy quality pays back in user trust and actionability of the entire notification system.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- Notification component type matches urgency level — toasts for low urgency, banners for medium, modals for blocking.
+- Copy leads with the actor or subject, not a structural preamble ("You have a new...").
+- No notification exceeds the character limit for its component type.
+- Notifications include at most one action — the single most important next step.
+- "Notification," "alert," "message," and "update" do not appear as the first word of notification copy.
+- Tense matches the state: past tense for completed events, present for ongoing, future for upcoming.

package/dist/agents/skills/codex/ux-notification-copy/skill.yaml

@@ -0,0 +1,35 @@
+name: ux-notification-copy
+version: "1.0.0"
+description: Notification and alert copy — urgency calibration, actionability, toast vs banner vs modal selection, and writing messages that inform without overwhelming
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-microcopy-principles
+  - ux-error-messages
+  - ux-success-feedback
+  - design-feedback-patterns
+stack_signals: []
+keywords:
+  - notification
+  - alert
+  - toast
+  - banner
+  - urgency
+  - actionability
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/ux-onboarding-copy/SKILL.md

@@ -0,0 +1,156 @@
+# Onboarding Copy
+
+> Onboarding copy — progressive disclosure, value-first framing, reducing anxiety, and welcome flows that convert sign-ups into active users
+
+## When to Use
+
+- Writing welcome screens and first-run experiences for new users
+- Creating setup wizard step descriptions and progress indicators
+- Writing feature discovery tooltips and coach marks during initial use
+- Composing trial or freemium upgrade prompts that appear during onboarding
+- Writing personalization questions, permission requests, and team invite screens
+- NOT for: empty states after onboarding is complete (see ux-empty-states)
+- NOT for: tooltip and contextual help patterns outside onboarding (see ux-tooltip-contextual-help)
+- NOT for: marketing copy and acquisition messaging (different audience, different goals)
+
+## Instructions
+
+1. **Lead with value, not features.** The user's first question is "What's in it for me?" not "What can this product do?" "Start tracking your team's progress" answers the user's question. "Welcome to ProjectTool v3.2, featuring over 40 productivity-enhancing features" does not. Slack's onboarding: "You're all set. Now invite your team." — the instruction points immediately to value (team collaboration) rather than feature enumeration. Every onboarding headline should complete the sentence: "After this step, you'll be able to..." The answer to that sentence is the headline. The feature is the mechanism; the value is the message.
+
+2. **One action per screen.** Multi-step wizards must focus each step on a single decision or input. The moment a screen asks the user to do two things simultaneously, one of them will not get done. Notion's onboarding asks one question per screen: "What will you use Notion for? / Learning / Work / Personal" — one question, multiple-choice, no text input. Stripe's business setup wizard sequences role, business type, and business details across separate screens rather than a single long form. The cognitive load of a single focused question is an order of magnitude lower than a form with five fields — even if the total information collected is identical.
+
+3. **Show progress transparently.** "Step 2 of 4" removes the anxiety of not knowing how much time remains. Never hide the total number of steps. Showing "Step 2 of 4" communicates both current position and scope — the user can commit because they understand the investment. If you cannot show a linear step count because the flow is branching, use a progress bar or phase indicators ("Profile," "Team," "Preferences") with the current phase highlighted. Figma's onboarding uses a visual step map that shows all phases upfront. Hidden progress bars — that grow but never show the total — increase anxiety rather than reduce it.
+
+4. **Use progressive disclosure — do not explain everything on the first screen.** Introduce concepts and features when the user first encounters them, not in a pre-use overview. Figma does not explain layers, components, and frames before the user opens a file — it introduces each concept through contextual coach marks the first time the user encounters the relevant UI. A product tour that runs before the user has any context for what they are seeing is the onboarding equivalent of reading a manual before touching the product. The most effective onboarding teaches through doing, not through explaining before doing.
+
+5. **Reduce anxiety about reversibility.** "You can change this later in Settings" removes commitment paralysis at every decision point. Users will rush through setup or abandon if they believe they are making permanent choices. Stripe's onboarding reassures at each step: "You can update your business details anytime." Airbnb's listing setup says "Don't worry — you can edit this later" on every section. The reversibility note should appear immediately after the input or question, not in a small disclaimer at the bottom of the screen. Inline reversibility statements convert hesitant users into committed ones.
+
+6. **Make skipping available on non-critical steps.** "Skip for now" should be a clearly visible, secondary option on every optional step. Forced completion of optional steps drives abandonment, especially on mobile. LinkedIn, Spotify, and GitHub all offer prominent skip options on profile completion, recommendation setup, and optional integrations during onboarding. The skip option should not be hidden in small text — it should be a proper secondary button or link that is easy to find without feeling like a failure to complete. A "Skip for now" option signals that the product respects the user's time and does not gatekeep progress behind optional inputs.
+
+7. **Celebrate completion — do not just end.** The final onboarding screen should confirm that setup is complete, express genuine enthusiasm appropriate to the product's voice, and point to the first real action. "You're ready. Create your first project." Slack: "Your workspace is set up. Time to explore." The completion screen is the onboarding team's last opportunity to establish positive sentiment before the user enters the product for the first time. A silent redirect to the dashboard wastes that opportunity. The completion moment is the onboarding product's "curtain call" — it closes the loop and creates a memory of success that shapes how the user approaches the product.
+
+8. **Write permission requests as value exchanges, not demands.** "Enable notifications so you never miss a reply from your team" frames the permission as a benefit. "Enable notifications" alone is a demand. Apple's notification permission timing guidance says to ask for permissions when the user is in the context that makes the permission's value obvious — not on the first screen. Spotify asks for notification permissions after the user has played their first track, not during sign-up. The permission request copy should name the specific value the permission enables and should never appear before the user has experienced the feature that uses it.
+
+## Details
+
+### Onboarding Flow Types
+
+Three distinct onboarding patterns, each with different copy requirements:
+
+**Setup wizard:** Sequential screens that collect required information before first use. Stripe, Shopify, and Airbnb use this for merchant/host setup where the product cannot function without certain data. Copy for setup wizards must be maximally efficient — each field must justify its presence, and unnecessary questions must be removed. Every screen should have a single, specific title ("Tell us about your business"), one primary input group, and a progress indicator.
+
+**Progressive coach marks:** Contextual callouts that appear as the user encounters interface elements for the first time. Figma, Notion, and Linear use this approach. Coach mark copy must be brief (under 60 characters), tied to a specific element the user can see, and offer a single action ("Try it" or "Got it"). The coach mark appears at the moment of relevance, not upfront.
+
+**Contextual discovery:** Inline prompts and suggestions that appear as the user performs actions, surfacing advanced features only when the user is ready for them. GitHub's contextual CLI hints appear after several terminal commands, suggesting GitHub CLI as a faster workflow. This approach requires no separate onboarding flow — learning happens within the product's natural use.
+
+### Step Copy Structure
+
+Each wizard step needs these text elements in order of priority:
+
+| Element            | Purpose                               | Length        | Example                              |
+| ------------------ | ------------------------------------- | ------------- | ------------------------------------ |
+| Step title         | Name the decision or action           | 3-8 words     | "Tell us about your team"            |
+| Step description   | Explain why this step matters         | 1-2 sentences | "We'll use this to suggest features" |
+| Progress indicator | Show position and scope               | Step N of M   | "Step 2 of 4"                        |
+| Primary CTA        | Name the next action specifically     | 2-4 words     | "Set up your team"                   |
+| Skip option        | Offer graceful deferral (if optional) | 2-4 words     | "Skip for now"                       |
+
+The step description is optional for self-explanatory steps. If the title is clear ("Add your profile photo"), the description may add only noise. Only include the description when the step's purpose or consequence is non-obvious.
+
+### Anxiety Reducers
+
+Four patterns that eliminate onboarding abandonment from commitment fear:
+
+**Reversibility statements:** "You can change this later." Appears immediately after an input or decision, not in a footer disclaimer. Reduces commitment paralysis on decisions that feel permanent.
+
+**Social proof:** "Join 40,000 teams already using [product]." Reduces the fear of making the wrong choice by normalizing the decision. Works best on product selection or plan selection screens where the user is uncertain.
+
+**Time estimates:** "Takes about 2 minutes." Reduces abandonment from unknown time investment. Accurate estimates build trust; inaccurate ones destroy it. If the estimate is uncertain, use "usually takes 2-3 minutes" to set a range rather than overpromising.
+
+**Consequence framing:** "This only affects what you see in your workspace." Narrows the blast radius of a decision in the user's mind, making it easier to commit. Works for any decision that seems consequential but is actually low-stakes.
+
+### Onboarding Copy Metrics
+
+Copy quality in onboarding is measurable. Track these outcomes to evaluate whether onboarding copy is working:
+
+- **Step completion rate:** Each step should have >80% completion (users who see it complete it). Below 60% suggests the step is too complex, unclear, or the value is not evident.
+- **Skip rate on optional steps:** If >50% of users skip a step, consider removing it or reframing its value.
+- **Time per step:** Steps requiring >90 seconds of engagement suggest the input or decision is too complex.
+- **Onboarding completion rate:** Overall flow should complete at >70% for B2C, >50% for B2B with verification requirements.
+
+### Anti-Patterns
+
+1. **The Feature Tour.** Walking users through every feature before they can use the product — a 12-screen slideshow of features, screenshots, and capabilities that runs before the user touches anything real. Feature tours have low completion rates because users cannot make sense of features they have never seen in context. The fix: get the user to first value as fast as possible, then introduce advanced features contextually through coach marks and progressive disclosure.
+
+2. **The Commitment Trap.** Forcing users to make irreversible decisions during onboarding without a "change later" option. "Choose your username (cannot be changed)" or "Select your plan (changes take effect at next billing cycle)" without any alternative. Users encountering permanent decisions during onboarding will hesitate, second-guess, and frequently abandon. Every onboarding decision should either be reversible, or be framed with the exact process for changing it later ("Contact support to change your username").
+
+3. **The Information Dump.** Presenting all settings, options, and configuration choices on a single screen rather than sequencing them progressively. A single-screen setup form with 15 fields is not an onboarding wizard — it is a registration form disguised as onboarding. The cognitive load of 15 simultaneous decisions drives abandonment. Identify which 3-5 pieces of information are truly necessary for first use, sequence them as separate screens, and defer everything else to in-product settings.
+
+4. **The Buried Skip.** Placing the skip option in 11px gray text below the primary button, visually indistinguishable from legal text. Users who need to skip — because they are exploring without commitment, on mobile with limited time, or returning after a session break — cannot find the skip option and abandon the onboarding entirely. The skip option must be a visible secondary button or a clearly styled link, not a footnote.
+
+### Real-World Examples
+
+**Slack's Workspace Setup Flow.** Slack's onboarding asks three questions across three screens: name, workspace name, and first teammate to invite. Each screen has a single input, a progress indicator, and a specific next button ("Next: Set your username"). The final screen is an invitation screen, not a feature tour — Slack understands that the first step to product value is inviting a team member. The onboarding ends not with a walkthrough but with an action that creates immediate value. This design is why Slack's activation metric ("team sends 2,000 messages") is so closely tied to the team invite step in onboarding.
+
+**Notion's Personalization Onboarding.** Notion asks "How are you planning to use Notion?" with four choices (Personal use, School, Work, Teams). This single question branches the subsequent experience — Work users see team templates, Personal users see personal planning templates. One question, branching value. The personalization is used immediately (template recommendations), proving its relevance and building trust in the onboarding process. Notion's onboarding shows users a populated template based on their answer — the product feels useful before they have added a single piece of their own data.
+
+**Stripe's Business Verification Wizard.** Stripe's onboarding for new merchants is thorough because it has to be — regulatory requirements mandate identity verification. Stripe makes this explicit: "We're required by law to verify your identity." The transparency turns a friction-heavy requirement into a trust signal. Each verification step includes a progress indicator, an explanation of why the information is needed, and a privacy statement. High-friction onboarding can succeed when the friction is explained and justified — users accept necessary friction but resent unexplained friction.
+
+**Figma's Interactive Tutorial.** Figma's first-time experience is a design file containing the tutorial — the user learns by doing within the actual product, not in a separate tour layer. The tutorial uses coach marks that point to real UI elements: "Click the Move tool in the toolbar." The immediate feedback loop (click the thing, see it work) is more effective than any amount of explanation. Features are introduced in order of frequency: move, select, resize, then more advanced operations. The user finishes the tutorial having used the product, not just having watched it — which produces dramatically higher retention than passive product tours.
+
+## Source
+
+- NNGroup — "User Onboarding UX Patterns" (2019), https://www.nngroup.com/articles/onboarding-ux/
+- Samuel Hulick — _The Elements of User Onboarding_ (2013), value-first onboarding philosophy
+- Appcues — State of User Onboarding (annual report), https://www.appcues.com/state-of-user-onboarding
+- Podmajersky, T. — _Strategic Writing for UX_ (2019), onboarding copy frameworks
+- Weinschenk, S. — _100 Things Every Designer Needs to Know About People_ (2011), progressive disclosure and cognitive load
+
+### Onboarding Copy for Re-Engagement Flows
+
+Re-onboarding — when users return after a long absence, when they are invited to a new workspace, or when they encounter a major product update — requires different copy from first-run onboarding:
+
+**Returning user:** "Welcome back. A few things have changed since you last used [product]." Not "Welcome to [product]!" — they already know it. Lead with what is new, not with the basics. Spotify's year-end Wrapped is a masterclass in re-engagement — it celebrates the user's history, not the product's features.
+
+**New workspace member:** "Jordan invited you to join Acme Corp. Here's what you can do..." The value proposition is the workspace context, not the product. The user already knows the product; they need to understand this specific workspace.
+
+**Post-major-update:** "We've redesigned [feature]. Here's what changed and how to find everything." The user needs a delta from their existing mental model — not a full product tour. Name what changed, show where things moved, confirm what stayed the same.
+
+## Process
+
+1. Map each step of the onboarding flow to one of the three flow types (setup wizard, coach marks, contextual discovery).
+2. Write a value-first headline for each wizard step that names the outcome, not the action.
+3. Add reversibility statements after any decision point that might create commitment paralysis.
+4. Ensure progress is always visible: step count, phase indicator, or progress bar.
+5. Write a completion screen that confirms success and directs to the first high-value action.
+
+### Onboarding Copy Review Checklist
+
+Before shipping an onboarding flow, verify each item:
+
+| Check                               | Pass Criteria                                              |
+| ----------------------------------- | ---------------------------------------------------------- |
+| Value-first headline                | Completes "After this step, you'll be able to..."          |
+| One action per screen               | Single input or decision per wizard step                   |
+| Progress visible                    | Step N of M, phase indicator, or progress bar present      |
+| Reversibility stated                | "You can change this later" after any non-trivial decision |
+| Skip available                      | Visible secondary button or link on optional steps         |
+| Completion screen present           | Confirms success, names first high-value action            |
+| No feature tour                     | Users interact with the product, not watch a slideshow     |
+| Permission requests framed as value | Names specific benefit the permission enables              |
+
+Onboarding is the highest-stakes copy surface in a product because first impressions are disproportionately influential. Users who have a positive onboarding experience are significantly more likely to reach activation milestones. A single unnecessary step, a single missing reversibility statement, or a single missing completion screen can measurably reduce activation rates.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- Each wizard screen contains exactly one decision or input, with a single primary CTA.
+- Every step shows transparent progress (step count, phase indicator, or progress bar).
+- Reversibility statements appear after every non-trivial decision point.
+- The completion screen confirms success and points to the first real product action.
+- Optional steps offer a visible, non-stigmatizing skip option as a proper secondary button or link.
+- Permission requests frame the permission as a named user benefit, not a demand.