@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/codex/ts-zod-integration/SKILL.md

@@ -0,0 +1,181 @@
+# TypeScript Zod Integration
+
+> Use Zod schemas as the single source of truth for runtime validation and TypeScript types
+
+## When to Use
+
+- Validating API request bodies, query parameters, or form data
+- Deriving TypeScript types from validation schemas (single source of truth)
+- Parsing and transforming unknown data from external sources
+- Building type-safe environment variable configuration
+
+## Instructions
+
+1. **Define a schema and infer the type:**
+
+```typescript
+import { z } from 'zod';
+
+const UserSchema = z.object({
+  id: z.string().cuid(),
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+  role: z.enum(['user', 'admin']),
+  createdAt: z.coerce.date(),
+});
+
+type User = z.infer<typeof UserSchema>;
+// { id: string; email: string; name: string; role: 'user' | 'admin'; createdAt: Date }
+```
+
+2. **Parse unknown data** — validates and returns typed result:
+
+```typescript
+const user = UserSchema.parse(untrustedData);
+// Throws ZodError if validation fails
+
+const result = UserSchema.safeParse(untrustedData);
+if (result.success) {
+  console.log(result.data); // Type: User
+} else {
+  console.log(result.error.issues); // Validation errors
+}
+```
+
+3. **Compose schemas** with pick, omit, extend, and merge:
+
+```typescript
+const CreateUserSchema = UserSchema.omit({ id: true, createdAt: true });
+const UpdateUserSchema = UserSchema.partial().required({ id: true });
+const UserWithPostsSchema = UserSchema.extend({
+  posts: z.array(PostSchema),
+});
+```
+
+4. **Transform data** during parsing:
+
+```typescript
+const InputSchema = z.object({
+  email: z
+    .string()
+    .email()
+    .transform((e) => e.toLowerCase().trim()),
+  tags: z.string().transform((s) => s.split(',').map((t) => t.trim())),
+  age: z.coerce.number().int().positive(),
+});
+```
+
+5. **Validate environment variables:**
+
+```typescript
+const EnvSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  PORT: z.coerce.number().default(3000),
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  API_KEY: z.string().min(1),
+});
+
+export const env = EnvSchema.parse(process.env);
+// Fails at startup if any required env var is missing or invalid
+```
+
+6. **Use with API route handlers:**
+
+```typescript
+// Next.js Route Handler
+const QuerySchema = z.object({
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  search: z.string().optional(),
+});
+
+export async function GET(request: Request) {
+  const url = new URL(request.url);
+  const query = QuerySchema.parse(Object.fromEntries(url.searchParams));
+  // query is fully typed: { page: number; limit: number; search?: string }
+}
+```
+
+7. **Discriminated union schemas:**
+
+```typescript
+const EventSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('click'), x: z.number(), y: z.number() }),
+  z.object({ type: z.literal('keypress'), key: z.string() }),
+  z.object({ type: z.literal('scroll'), offset: z.number() }),
+]);
+
+type Event = z.infer<typeof EventSchema>;
+```
+
+8. **Custom validation with `refine` and `superRefine`:**
+
+```typescript
+const PasswordSchema = z
+  .object({
+    password: z.string().min(8),
+    confirm: z.string(),
+  })
+  .refine((data) => data.password === data.confirm, {
+    message: 'Passwords do not match',
+    path: ['confirm'],
+  });
+```
+
+9. **Error formatting:**
+
+```typescript
+const result = UserSchema.safeParse(data);
+if (!result.success) {
+  const formatted = result.error.flatten();
+  // { formErrors: string[], fieldErrors: { email?: string[], name?: string[] } }
+}
+```
+
+## Details
+
+Zod provides runtime validation that TypeScript's type system cannot. TypeScript types are erased at runtime — they cannot validate data from APIs, databases, or user input. Zod bridges this gap by generating both validation logic and TypeScript types from a single schema definition.
+
+**Schema-first approach:** Define the Zod schema first, then derive the TypeScript type with `z.infer`. This eliminates the common problem of types and validation drifting apart.
+
+**`parse` vs `safeParse`:**
+
+- `parse` throws `ZodError` on failure — use in contexts where invalid data is an error (middleware, startup validation)
+- `safeParse` returns a discriminated union `{ success: true, data: T } | { success: false, error: ZodError }` — use when you need to handle validation failure gracefully
+
+**Performance:** Zod validation is faster than JSON Schema for most schemas. For very high-throughput paths (>10K validations/second), consider `valibot` or compile schemas with `@anatine/zod-openapi`.
+
+**Zod with Prisma:** Libraries like `zod-prisma-types` auto-generate Zod schemas from Prisma models:
+
+```prisma
+generator zod {
+  provider = "zod-prisma-types"
+}
+```
+
+**Trade-offs:**
+
+- Zod schemas add runtime overhead — validate at system boundaries, not inside tight loops
+- `z.infer` types can be complex in IDE tooltips — use type aliases for readability
+- `transform` changes the output type — `z.infer` reflects the OUTPUT type, not the input
+- Zod is synchronous by default — use `parseAsync` for schemas with async refinements
+
+## Source
+
+https://typescriptlang.org/docs/handbook/2/types-from-types.html
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## 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
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/ts-zod-integration/skill.yaml

@@ -0,0 +1,38 @@
+name: ts-zod-integration
+version: "1.0.0"
+description: Use Zod schemas as the single source of truth for runtime validation and TypeScript types
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "tsconfig.json"
+  - "tsconfig.*.json"
+related_skills:
+  - ts-generics-pattern
+  - ts-utility-types
+stack_signals:
+  - typescript
+keywords:
+  - zod
+  - z.infer
+  - schema-first
+  - runtime-validation
+  - type-inference
+metadata:
+  author: community
+  upstream: typescriptlang.org/docs/handbook/2/types-from-types.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/ux-active-voice/SKILL.md

@@ -0,0 +1,150 @@
+# Active Voice in UI Writing
+
+> Active voice in UI writing — active vs passive voice, when passive is acceptable, verb-first patterns for buttons and actions
+
+## When to Use
+
+- Writing button labels, menu items, and action links
+- Composing error messages that name the actor and the problem
+- Writing instructions, step-by-step guides, and onboarding flows
+- Drafting confirmation dialog text and destructive action warnings
+- Writing notification text, toast messages, and status updates
+- Labeling form fields, toggles, and navigation elements with actionable text
+- Creating help text and tooltips that explain what the user can do
+- Reviewing existing UI text to convert passive constructions to active ones
+- Auditing automated notification templates for active voice compliance
+- Converting legacy enterprise UI text from passive to active constructions
+- NOT for: legal disclaimers, privacy policies, and terms of service where passive voice is sometimes legally required
+- NOT for: system status messages where the actor is genuinely irrelevant ("Updated 5 minutes ago")
+
+## Instructions
+
+1. **Default to active voice -- the user or the system should be the subject.** Active voice puts the actor first: "We saved your changes." Passive voice hides the actor: "Your changes have been saved." Active voice is clearer, shorter, and more direct. It tells the user who did what. In UI text, the actor is either the user ("You created 3 projects"), the system ("We couldn't connect to the server"), or a third party ("Jordan commented on your pull request"). Name the actor. Stripe consistently names the actor: "We sent a receipt to your email" not "A receipt has been sent."
+
+2. **Use imperative mood for all actionable elements.** Buttons, links, and menu items should start with a verb in imperative mood: "Save draft," "Delete project," "Export data," "Upload file," "Create issue." The imperative mood eliminates the subject entirely -- the implicit "you" makes every instruction direct and concise. GitHub uses imperative mood across its entire interface: "Create repository," "Open pull request," "Merge pull request," "Close issue," "Fork repository." This pattern is so consistent that a new GitHub user can predict the label on any button by combining the action verb with the object noun.
+
+3. **Name the actor in error messages.** When something goes wrong, the user needs to know who or what is responsible. "We couldn't connect to the server" names the system as the actor. "Your card was declined by your bank" names the bank. "Connection could not be established" names nobody -- the user is left wondering who failed and what they should do about it. Apple's iOS error messages consistently name the actor: "This app cannot connect to the App Store" (the app is the actor), "Cellular data is turned off for this app" (the system is the actor). Naming the actor enables the user to determine their next action.
+
+4. **Know when passive voice is correct.** Passive voice is not always wrong. It is the right choice when the actor is irrelevant or when the object is more important than the actor. "Your account was created on March 15" -- who created it does not matter; the creation date is the point. "This page was last updated 2 hours ago" -- the updater is irrelevant; the freshness is the point. "Your payment is being processed" -- the processing system is not interesting; the status of the payment is. The test: if naming the actor would add words without adding meaning, passive is correct.
+
+5. **Use the verb-noun pattern for buttons.** Every button label should follow the structure: action verb + specific object. "Add member," "Create project," "Upload file," "Export CSV," "Remove filter," "Copy link." The verb tells the user what will happen. The noun tells the user what will be affected. Together they eliminate ambiguity. Compare "Add member" (clear: you are adding a person to the team) with "Add" (ambiguous: add what?) or "Member" (ambiguous: what about the member?). Linear follows this pattern rigorously: "Create issue," "Add label," "Set priority," "Assign to," "Move to."
+
+6. **Avoid hidden verbs -- nominalizations that bury the action.** A hidden verb is an action disguised as a noun: "perform configuration" instead of "configure," "begin the export process" instead of "export," "carry out an installation" instead of "install." Hidden verbs add words, reduce clarity, and make UI text feel bureaucratic. The fix is mechanical: find the noun that contains a verb, extract the verb, and rebuild the sentence. "We will perform a synchronization of your data" becomes "We'll sync your data." "Please carry out a verification of your email" becomes "Verify your email."
+
+7. **Test with the "by zombies" rule.** If you can insert "by zombies" after the verb and the sentence still makes grammatical sense, it is passive voice. "Your changes have been saved [by zombies]" -- passive. "We saved your changes [by zombies]" -- does not work, so it is active. "The file was uploaded [by zombies]" -- passive. "You uploaded the file [by zombies]" -- does not work, so it is active. This test is fast, memorable, and catches passive constructions that the writer has become blind to through familiarity.
+
+## Details
+
+### Active vs Passive Comparison Table
+
+Side-by-side examples showing how active voice improves common UI text patterns:
+
+| Passive (avoid)                      | Active (prefer)                 | Why active is better              |
+| ------------------------------------ | ------------------------------- | --------------------------------- |
+| Your changes have been saved         | We saved your changes           | Names the actor (the system)      |
+| The file was uploaded successfully   | You uploaded the file           | Credits the user                  |
+| An error was encountered             | We hit an error                 | Names the system as responsible   |
+| The invitation has been sent         | We sent the invitation          | Confirms who sent it              |
+| Your password was reset              | You reset your password         | Confirms the user's action        |
+| The project will be deleted          | This will delete the project    | Makes the consequence explicit    |
+| Access has been denied               | You don't have access           | Addresses the user directly       |
+| The connection was lost              | We lost the connection          | Takes responsibility              |
+| Your subscription has been cancelled | You cancelled your subscription | Confirms the user's choice        |
+| The payment was declined             | Your bank declined the payment  | Names the actual actor (the bank) |
+
+### Verb-First Patterns by Component Type
+
+Different UI components follow slightly different verb patterns:
+
+**Buttons and primary actions.** Imperative verb + specific object. "Save draft," "Create project," "Send message." Never just a noun ("Draft") and never a generic verb ("Submit," "OK," "Confirm"). The button label should be a complete instruction that makes sense without reading anything else on the screen.
+
+**Menu items.** Imperative verb + object, optionally with modifier. "Export as CSV," "Sort by date," "Filter by status," "Group by assignee." Menu items can be slightly longer than buttons because menus are lists designed for scanning.
+
+**Toggle labels.** Describe what the toggle enables, not the toggle state. "Show line numbers," "Enable dark mode," "Allow notifications." The toggle's on/off position communicates the current state visually -- the label describes what the setting does.
+
+**Link text.** Verb phrase that describes the destination or action. "View all comments," "Learn more about pricing," "See documentation." Never "Click here" -- the link text must be descriptive enough to make sense out of context (screen readers announce link text in isolation).
+
+**Notification actions.** Imperative verb that names the response. "Reply," "Dismiss," "View thread," "Mark as read." Notification actions should be single-word or two-word verbs because they appear in constrained spaces (push notifications, toast messages).
+
+### The Voice Conversion Process
+
+When converting existing UI text from passive to active voice, follow this mechanical process:
+
+1. **Identify the hidden actor.** In "The file was deleted," the hidden actor is either the user or the system. Determine who performed the action.
+2. **Move the actor to the subject position.** "The file was deleted" becomes "You deleted the file" or "We deleted the file."
+3. **Simplify the verb.** Passive constructions use "was/were/has been" + past participle. Active uses simple past or present. "Has been uploaded" becomes "uploaded." "Was being processed" becomes "is processing."
+4. **Verify the meaning is preserved.** "Your account was suspended due to unusual activity" becomes "We suspended your account due to unusual activity." The meaning is identical, but the active version is clearer about who took the action.
+5. **Check the result against the "by zombies" test.** If you can no longer add "by zombies" after the verb, the conversion is complete.
+
+Common conversion patterns:
+
+| Passive pattern               | Active pattern              |
+| ----------------------------- | --------------------------- |
+| [thing] was [verbed]          | You/We [verbed] [thing]     |
+| [thing] has been [verbed]     | You/We [verbed] [thing]     |
+| [thing] is being [verbed]     | We are [verbing] [thing]    |
+| [thing] will be [verbed]      | We will [verb] [thing]      |
+| [thing] could not be [verbed] | We could not [verb] [thing] |
+
+### When Passive Voice Is Preferred
+
+There are four specific UI contexts where passive voice is the better choice:
+
+1. **Timestamps and metadata.** "Created on March 15," "Last updated 2 hours ago," "Modified by Jordan." The date or recency is the information, not the actor.
+
+2. **Status indicators.** "Payment is being processed," "Deployment in progress," "File is being uploaded." The user cares about the status, not about which microservice is handling it.
+
+3. **Attribution where the user is not the actor.** "Assigned to Jordan," "Reviewed by the security team," "Approved by admin." Passive voice naturally emphasizes the person responsible.
+
+4. **Policy statements.** "Passwords are encrypted at rest," "Data is stored in the EU." The policy applies universally -- there is no meaningful actor to name.
+
+### Anti-Patterns
+
+1. **The Passive Blame Dodge.** Using passive voice in error messages to avoid assigning responsibility. "An error was encountered" instead of "We hit a problem." "The operation could not be completed" instead of "We couldn't complete the operation." Passive voice in errors creates ambiguity: the user cannot tell if they caused the problem, the system caused it, or an external service caused it. This ambiguity generates support tickets. The fix: name the actor. If the system failed, say "we." If the user's input was invalid, say "you." If an external service failed, name it: "Your bank declined the payment."
+
+2. **The Nominalization Cascade.** Chains of hidden verbs that turn simple actions into bureaucratic processes. "The system will perform an initialization of the configuration parameters for the deployment environment" instead of "We'll set up your deployment." Each nominalization adds a layer of abstraction between the user and the action. The cascade effect compounds: one hidden verb is tolerable, two is confusing, three is unreadable. The fix: extract every verb from its noun wrapper. "Initialization" becomes "initialize." "Configuration" becomes "configure." "Deployment" becomes "deploy." Then rebuild: "We'll configure your deployment."
+
+3. **The Actionless Button.** A button labeled with a noun or adjective instead of a verb. "Settings" as a button (where does it go?), "Next" (what happens next?), "Ready" (ready for what?). Navigation buttons that use nouns are sometimes acceptable ("Settings," "Profile," "Dashboard") because they describe the destination. But action buttons must use verbs: "Save settings" not "Settings," "Continue to payment" not "Next," "Start deployment" not "Ready." The actionless button forces the user to infer the action from context, which increases cognitive load and error rates.
+
+4. **The Verb-Object Mismatch.** Using verbs that do not accurately describe the action. "Submit" for a save action (nothing is being submitted). "Process" for a search action (the user wants results, not processing). "Execute" for a send action (the user is sending a message, not executing a command). The mismatch creates a gap between what the user expects and what happens. The fix: use the most specific, accurate verb available. "Save" for saving, "Search" for searching, "Send" for sending, "Delete" for deleting.
+
+### Real-World Examples
+
+**GitHub's Imperative Commit Message Convention.** GitHub popularized the imperative mood for commit messages: "Add feature," "Fix bug," "Remove deprecated method" -- not "Added feature" or "Fixes bug." This convention extends throughout GitHub's UI. Pull request actions are imperative: "Merge pull request," "Squash and merge," "Rebase and merge." Issue actions: "Close issue," "Reopen issue," "Pin issue." The consistency creates a predictable grammar that users internalize: every action in GitHub starts with a verb in imperative mood. This is not accidental -- GitHub's content design guidelines mandate imperative mood for all action labels.
+
+**Apple's Button Label Patterns.** Apple's Human Interface Guidelines prescribe verb-first button labels across iOS and macOS. The destructive action button in a deletion dialog says "Delete" (not "OK" or "Yes"). The save button says "Save" (not "Done" or "Continue"). The cancel button says "Cancel" (not "Go Back" or "Never Mind"). Alert actions follow the same pattern: "Allow" or "Don't Allow" for permission dialogs. "Try Again" or "Cancel" for error recovery. Apple's guidelines explicitly state: "Use a verb that describes the action the button performs." This principle makes Apple's interfaces predictable -- every button tells you exactly what it will do.
+
+**Stripe's Active-Voice Error Messages.** Stripe's error messages consistently use active voice to name the actor and the problem. "Your card was declined" names the card as the subject. "Your card number is incomplete" names the specific field. "Your card's expiration year is in the past" names the specific problem with the specific field. Compare with passive alternatives: "An error occurred with the payment" (what error?), "The transaction could not be completed" (why?), "Invalid card details" (which details?). Stripe's active voice errors enable the user to fix the problem without help. Each error names the thing that is wrong and implies the fix: incomplete number means add digits, past expiration means update the date.
+
+**Slack's Mixed Voice Strategy.** Slack uses active voice for user actions and notifications ("Jordan sent you a message," "You joined #engineering," "You have 3 unread messages") and passive voice strategically for status indicators ("Last active 2 hours ago," "Typing...," "Message delivered"). This mixed strategy is correct: the notifications name actors because the actor matters (who sent the message?), while the status indicators use passive because the actor is the system and the status is what matters. Slack's approach demonstrates that the goal is not to eliminate passive voice entirely, but to use active voice wherever the actor carries information.
+
+## Source
+
+- Apple Human Interface Guidelines -- Writing section, imperative mood and active voice guidance
+- Google Material Design -- Writing principles, active voice best practices
+- Strunk, W. and White, E.B. -- _The Elements of Style_ (2000), "Use the active voice" (Rule 14)
+- NNGroup -- "Passive vs. Active Voice in UX Writing" (2020), evidence for active voice in error recovery
+- Podmajersky, T. -- _Strategic Writing for UX_ (2019), verb-first patterns for components
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Audit existing UI text for passive constructions using the "by zombies" test.
+3. Convert passive constructions to active voice, naming the actor explicitly.
+4. Apply verb-noun patterns to all button labels, menu items, and action links.
+5. Verify your implementation against the anti-patterns listed above.
+
+## 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 button labels use verb-noun imperative patterns -- no generic "OK," "Submit," or "Confirm."
+- Error messages name the actor (user, system, or third party) explicitly.
+- Passive voice appears only in the four accepted contexts: timestamps, status, attribution, and policy.
+- No hidden verbs (nominalizations) exist in user-facing text.
+- The "by zombies" test passes -- no accidental passive voice in action-oriented text.
+- Link text describes the destination or action without using "click here" or "learn more" as standalone text.
+- Notification text names the actor who triggered the notification.

package/dist/agents/skills/codex/ux-active-voice/skill.yaml

@@ -0,0 +1,32 @@
+name: ux-active-voice
+version: "1.0.0"
+description: Active voice in UI writing — active vs passive voice, when passive is acceptable, verb-first patterns for buttons and actions
+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-plain-language
+stack_signals: []
+keywords:
+  - active-voice
+  - passive-voice
+  - verb-first
+  - action-labels
+  - imperative-mood
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,159 @@
+# Button and CTA Copy
+
+> Button and CTA copy — verb-noun pattern, specificity over vagueness, context-sensitive labels, and writing buttons that tell users exactly what will happen
+
+## When to Use
+
+- Writing primary and secondary action button labels in forms, modals, and pages
+- Naming CTA buttons in dialogs, cards, and marketing components
+- Writing link text that acts as an action trigger (not navigation)
+- Choosing between generic and specific button labels when reviewing existing copy
+- Writing stateful button labels for in-progress, success, and error states
+- NOT for: navigation links and menu items that describe destinations (see ux-navigation-labels)
+- NOT for: confirmation dialog button patterns for destructive actions (see ux-confirmation-dialogs)
+- NOT for: form submit buttons on simple single-field forms where the form name is the label
+
+## Instructions
+
+1. **Use the verb-noun pattern: action + object.** The verb names what happens; the noun names what it happens to. "Save draft" (action: save, object: draft). "Delete project" (action: delete, object: project). "Send invitation" (action: send, object: invitation). Stripe: "Add payment method." GitHub: "Create pull request." Linear: "Create issue." The pattern scales to every context — when you know what action the button performs and what it operates on, the label writes itself. When you cannot name both the verb and the noun, the button's purpose is unclear and likely needs redesign. The verb-noun pattern is also the most direct defense against generic labels — "OK" has no verb or noun, while "Delete project" has both.
+
+2. **Never use generic verbs alone.** "OK," "Submit," "Confirm," "Done," "Yes," "No," "Continue," "Next," and "Proceed" are ambiguous without reading the surrounding context. In a destructive confirmation dialog, "OK" is dangerous — users may click without reading. "Delete project" on the same button is unambiguous. On a checkout form, "Submit" could mean submit a support request, submit a form, or submit a payment. "Pay $49.99" eliminates any ambiguity. The generic verb forces the user to remember context; the specific verb provides it on the button itself. The test: cover the rest of the screen — can you identify what this button does from its label alone?
+
+3. **Match the button label to what the form or action actually does.** A form that creates an account should have "Create account" not "Submit." A form that sends a message should have "Send message" not "Done." A form that places an order should have "Place order" not "Confirm." The label describes the outcome of clicking, not the act of clicking. Shopify's checkout: "Complete order." GitHub's sign-up: "Create account." Stripe's invoice payment: "Pay invoice." Each label names the specific real-world event that clicking triggers. When onboarding a new team member, the button should say "Invite Jordan" not "Send invite" if the person's name is available in context.
+
+4. **Put the destructive button in a visually distinct style — never mirror the safe button's weight.** When a dialog has a destructive action (delete) and a safe action (cancel), the destructive button should use destructive styling (red) and the safe button should use secondary styling (outlined or ghost). Never put both buttons in identical primary styling — users click primary-styled buttons on muscle memory without reading. GitHub: red "Delete this repository" button + outlined "Cancel" link. Notion: red "Delete page" + "Keep it" as plain text. The visual hierarchy must reinforce the copy hierarchy — the button that risks data loss should never be the same visual weight as the safe button.
+
+5. **Keep button text to 1-4 words.** If you need more than four words, the action is too complex for a single button or the label is over-explaining. "Export selected transactions as CSV" should be "Export CSV" (let the context provide "selected transactions"). "Add a new team member to this project" should be "Add member." The constraint forces prioritization — what is the one most important word in this label? It should probably be first. Button labels are not descriptions. If the label requires more than four words to be unambiguous, examine whether the button's context (its page, section, or dialog title) can carry some of that meaning so the label itself can be shorter.
+
+6. **Front-load the verb — never end with the verb.** "Export CSV" not "CSV Export." "Create team" not "New team creation." "Send report" not "Report sending." The verb should be the first word so users scanning buttons see the action immediately. In a list of action buttons, every item should start with a different verb if possible: "Create," "Import," "Archive," "Delete" — each is distinguishable by its first word alone. When two buttons must start with the same verb (e.g., "Save draft" and "Save and publish"), differentiate by the noun immediately: "Save draft" and "Publish" (where "publish" implies saving).
+
+7. **For stateful buttons, reflect the current system state across all states.** A "Save" button that is saving should say "Saving..." with an in-progress indicator. After completing, it should say "Saved" with a checkmark, then return to "Save" after a few seconds. A "Follow" button that has been clicked should say "Following" or "Unfollow" (the next available action). Figma's toolbar save indicator cycles through these states. GitHub's repository star button toggles between "Star" and "Unstar." Users who click without visual feedback will click again, causing double submissions. Every stateful button needs labels for idle, in-progress, success, and error states — not just the idle state.
+
+8. **Write link-as-action text with verb phrases, not "click here" or "learn more" alone.** "Click here to view the report" should be "View the report." "Learn more" should be "Learn how billing works" or "See pricing." Generic link text like "click here" is an accessibility failure — screen readers read link text out of context, so "click here" in a list of links provides no navigational information. Verb phrases provide both the action and the destination: "Download the style guide," "View all 47 issues," "Compare plans." The link text should be meaningful when read in isolation, without the surrounding sentence.
+
+## Details
+
+### Button Label Length Guidelines
+
+When a button label exceeds the maximum, examine whether the label is trying to do two things (describe the button AND explain the context) or whether the action itself needs redesigning.
+
+| Button Type        | Target Word Count | Maximum | Example                       |
+| ------------------ | ----------------- | ------- | ----------------------------- |
+| Primary action     | 2 words           | 3 words | "Create project"              |
+| Destructive action | 2 words           | 3 words | "Delete project"              |
+| Secondary action   | 1-2 words         | 3 words | "Cancel"                      |
+| Link-as-action     | 2-3 words         | 4 words | "Learn more" / "View details" |
+| Marketing CTA      | 2-4 words         | 5 words | "Start free trial"            |
+| Checkout CTA       | 2-3 words         | 4 words | "Pay $49.99"                  |
+
+### Primary vs Secondary vs Tertiary Label Conventions
+
+**Primary buttons** (filled, high contrast) take specific verb-noun labels describing the main action: "Create project," "Save changes," "Submit form." Primary buttons represent the intended completion path.
+
+**Secondary buttons** (outlined or ghost) take safe, often reversible action labels: "Cancel," "Back," "Skip," or a competing but safe action like "Save as draft." The secondary button should always be the lower-stakes option.
+
+**Tertiary buttons** (text-only links or icon buttons) take minimal labels or tooltips: "Delete," "Edit," "More options (...)" — these are low-discovery controls where brevity is appropriate because the action is secondary to the primary workflow.
+
+Never use identical visual styling for buttons with drastically different consequences. A primary-styled "Delete" next to a primary-styled "Save" will cause accidental deletions.
+
+### Stateful Button Copy
+
+Buttons that represent an ongoing state or a toggle need copy for all states. Missing states lead to double-submission, user confusion, and silent failures.
+
+| Action Type  | Idle State  | In-Progress State | Success State | Error State          |
+| ------------ | ----------- | ----------------- | ------------- | -------------------- |
+| Save         | "Save"      | "Saving..."       | "Saved"       | "Save failed. Retry" |
+| Submit/Send  | "Send"      | "Sending..."      | "Sent"        | "Failed. Retry"      |
+| Toggle (off) | "Enable"    | "Enabling..."     | "Enabled"     | "Failed to enable"   |
+| Toggle (on)  | "Disable"   | "Disabling..."    | "Disabled"    | "Failed to disable"  |
+| Follow       | "Follow"    | —                 | "Following"   | —                    |
+| Subscribe    | "Subscribe" | "Subscribing..."  | "Subscribed"  | "Failed"             |
+
+### Context-Sensitive Label Adaptation
+
+The same action button may need different labels in different contexts to remain specific:
+
+- **Generic:** "Save" → **In a document editor:** "Save document" → **In a draft flow:** "Save draft" → **In a multi-user shared doc:** "Save and sync"
+- **Generic:** "Submit" → **On a support form:** "Send message" → **On a payment form:** "Pay $49.99" → **On a job application:** "Submit application"
+- **Generic:** "Add" → **In a team context:** "Add member" → **In a billing context:** "Add payment method" → **In a project context:** "Add task"
+
+The principle: if the context changes what happens when you click, the label should change too. Labels that are generic across all contexts miss the opportunity to confirm, for the user, exactly what clicking will do.
+
+### Marketing CTA vs Product CTA
+
+Marketing CTAs (on landing pages, emails, and ads) follow different rules than product CTAs (in app):
+
+**Marketing CTAs** may use aspirational language because the user is evaluating, not acting: "Start your free trial," "See pricing," "Get early access." The user has not committed — the CTA persuades and invites.
+
+**Product CTAs** must name the specific action because the user is executing, not evaluating: "Create project," "Export CSV," "Send invitation." The user has committed — the CTA confirms the action and its object.
+
+A common error is importing marketing CTA patterns into product UIs. "Get started" is a fine landing page CTA; in a product modal, it is the button that says nothing about what "getting started" entails. "Learn more" is a fine email CTA; in a product panel, it is the button that replaces the more specific "View documentation" or "See pricing breakdown."
+
+When reviewing CTAs, identify whether the context is evaluative (marketing) or executive (product) — and apply the appropriate pattern. Do not apply marketing aspirational language to product actions, and do not apply product specificity to marketing contexts where specificity may narrow the appeal.
+
+### Anti-Patterns
+
+1. **The Generic Submit.** Using "Submit" on every form regardless of what the form does. The form's title may say "Contact Us" and the fields may be "Name," "Email," "Message," but the button says "Submit" — not "Send message." The fix is to derive the button label from the form's action: what does clicking this button cause to happen in the real world? Name that event. "Submit" tells the user only that they are submitting a form — it says nothing about what the form does. This is the most common button anti-pattern in enterprise software because engineers often wire the button and choose a label as an afterthought.
+
+2. **The Ambiguous Pair.** Dialog buttons labeled "Yes" and "No" that require re-reading the dialog question to understand which does what. "Are you sure you want to delete this project? [Yes] [No]" — the user must hold the question in memory while clicking. The fix: replace "Yes" with the action ("Delete project") and "No" with the safe option ("Keep project"). The buttons must be independently comprehensible without the question. GitHub, Stripe, and Notion all use specific verb-noun labels on confirmation dialogs for this reason.
+
+3. **The Noun Button.** Buttons that are just nouns without verbs, leaving the action unclear. "Settings," "Report," "Export," "Archive" — are these navigation items? Action buttons? Do they trigger an immediate operation? "Settings" as a button could mean "Go to settings" (navigate) or "Save settings" (save). Adding the verb eliminates the ambiguity: "Open settings," "Generate report," "Export CSV," "Archive project." The noun alone creates uncertainty about whether the action is immediate or navigational.
+
+4. **The Identical Pair.** Two buttons with the same visual weight performing actions with vastly different consequences. A red-and-blue "Delete" next to a red-and-blue "Save" — same size, same visual prominence. Users operating on muscle memory will click the wrong button. Visual hierarchy must reinforce consequence hierarchy: destructive buttons must be visually distinct from constructive buttons, not just labeled differently.
+
+### Real-World Examples
+
+**Stripe's Checkout CTA.** Stripe's checkout button says "Pay $49.99" — three words that name the action (pay) and the consequence (the exact amount). The label is dynamically generated from the cart total, making it impossible to use a generic label. This specificity reduces the cognitive load of confirming the payment amount and the action simultaneously. Stripe's conversion data supports specific CTAs: "Pay $49.99" outperforms "Complete Purchase" in A/B tests because it tells users exactly what clicking will charge. The dynamic label also prevents the common error of clicking a payment button without knowing the amount.
+
+**GitHub's PR Merge Button States.** GitHub's merge button cycles through multiple states as the PR is reviewed: "Merge pull request" (default), "Squash and merge" / "Create a merge commit" / "Rebase and merge" (via dropdown), "Merging..." (in progress), and then the state resolves to the PR being marked merged. Each state uses a specific verb-noun pattern. The dropdown options are particularly well-labeled: each names both the action (merge, squash, rebase) and the consequence (a new commit, squashed commits, rebased commits). Users who do not understand the difference can infer it from the label alone.
+
+**Linear's Issue Creation Flow.** Linear's "Create issue" button is a primary action that opens a modal. Inside the modal, the submit button says "Create issue" — the same label used to trigger the modal, reinforcing the action throughout. When Linear introduced keyboard shortcut creation (pressing "C" anywhere), the tooltip on the button says "Create issue (C)" — the label is consistent across three invocation methods (click, keyboard, command palette). This consistency means users always know what they are doing, regardless of how they trigger it.
+
+**Notion's Page Action Buttons.** Notion's page action menu uses specific verb-noun labels for every item: "Turn into" (convert page type), "Move to" (relocate page), "Copy link" (copy), "Add to favorites" (bookmark), "Delete" (permanent deletion — the one exception to the verb-noun rule, as "Delete" is specific enough without a noun when operating on the currently visible page). The menu is an excellent example of front-loaded verbs: every item starts with its distinguishing verb, making the menu scannable by action rather than by object.
+
+## Source
+
+- NNGroup — "Writing Clear Button Labels" (2018), https://www.nngroup.com/articles/button-label-text/
+- Google Material Design — Button guidelines, https://m3.material.io/components/buttons/guidelines
+- Apple Human Interface Guidelines — Buttons, https://developer.apple.com/design/human-interface-guidelines/buttons
+- Yifrah, K. — _Microcopy: The Complete Guide_ (2017), button copy chapter
+- W3C WCAG 2.1 — Success Criterion 2.4.6: Headings and Labels, https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels
+
+## Process
+
+1. Identify the real-world event that clicking the button causes — name that event as verb + object.
+2. Verify the label is 1-4 words with the verb first.
+3. Check that no two buttons on the same screen start with the same verb unless they are intentionally parallel actions.
+4. If the button has stateful behavior, define labels for all states (idle, in-progress, success, error).
+5. Confirm primary and secondary buttons have distinct visual styling that reflects the relative risk of each action.
+
+### Button CTA Copy Review Checklist
+
+Before shipping any button or CTA, verify each item:
+
+| Check                                               | Pass Criteria                                                     |
+| --------------------------------------------------- | ----------------------------------------------------------------- |
+| Specific verb-noun pattern                          | No "OK," "Submit," "Confirm," "Done," or "Yes/No"                 |
+| Verb is the first word                              | "Export CSV" not "CSV Export"                                     |
+| Length 1-4 words                                    | No label over four words                                          |
+| Matches what the form or action does                | "Create account" not "Submit" on a sign-up form                   |
+| Stateful labels defined                             | Idle, in-progress, success, error states all written              |
+| Destructive buttons visually distinct               | Red/error color, never same weight as safe button                 |
+| Link-as-action text uses verb phrases               | "View report" not "Click here" or bare "Learn more"               |
+| No two buttons start with same verb in same context | Unless intentionally parallel (e.g., "Save" / "Save and publish") |
+
+Button labels are the most frequently written and most frequently neglected microcopy in any product. An audit of a mature product typically finds dozens of "Submit" buttons, "OK" dialogs, and stateless buttons with missing in-progress states. Running a button audit using this checklist typically surfaces improvements that directly affect conversion and error 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
+
+- Every button uses a specific verb-noun pattern — no generic "OK," "Submit," "Confirm," or "Done."
+- Button labels are 1-4 words with the verb as the first word.
+- Stateful buttons display labels for all states: idle, in-progress, success, and error.
+- Destructive buttons use destructive styling and are never visually identical to safe secondary buttons.
+- No two buttons in the same context start with the same verb unless they are intentionally parallel.
+- Link-as-action text uses verb phrases and is meaningful when read out of context (screen reader compliant).

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

@@ -0,0 +1,34 @@
+name: ux-button-cta-copy
+version: "1.0.0"
+description: Button and CTA copy — verb-noun pattern, specificity over vagueness, context-sensitive labels, and writing buttons that tell users exactly what will happen
+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-active-voice
+  - ux-plain-language
+stack_signals: []
+keywords:
+  - buttons
+  - cta
+  - call-to-action
+  - verb-noun
+  - action-labels
+  - submit-buttons
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []