feat: add WorkOS plugin

README.md

@@ -34,6 +34,7 @@ Each plugin lives in `plugins/<slug>`. The directory name is the install keyword
 | `typescript-lsp` | TypeScript language service `goto_definition` support. |
 | `weather-metrics` | Demo weather tool plus runtime metrics hooks. |
 | `web-search` | Exa-backed web search as a Cline tool. |
+| `workos` | WorkOS identity platform skills for AuthKit, SSO, Directory Sync, RBAC, widgets, and migrations. |
 
 ## Install From Source
 

plugins/workos/NOTICE.workos-skills

@@ -0,0 +1,47 @@
+WorkOS skills notice
+
+This plugin bundles WorkOS skill material from WorkOS plugin metadata that declares:
+
+- Author: WorkOS
+- Homepage: https://workos.com
+- Repository: https://github.com/workos/skills
+- License: MIT
+
+MIT license text for bundled WorkOS skill material:
+
+Copyright (c) WorkOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The bundled `skills/workos-widgets/references/scripts/query-spec.cjs` helper
+contains code from `yaml`, licensed under ISC:
+
+Copyright Eemeli Aro <eemeli@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

plugins/workos/README.md

@@ -0,0 +1,21 @@
+# WorkOS
+
+WorkOS adds Cline skills for implementing and debugging enterprise identity workflows.
+
+## Cline Primitives
+
+- Skills: `workos` routes WorkOS AuthKit, SSO/SAML, Directory Sync, RBAC, FGA, MFA, Vault, Audit Logs, Admin Portal, Pipes, Feature Flags, Radar, Events, Custom Domains, API references, CLI lifecycle, and migration requests to bundled WorkOS references.
+- Skills: `workos-widgets` helps integrate WorkOS widgets such as User Management, User Profile, Admin Portal SSO Connection, and Admin Portal Domain Verification across common frontend and backend stacks.
+- The bundled skills protect secrets and production identity resources, require verified CLI/dashboard guidance, and gate mutating WorkOS operations behind explicit user confirmation.
+
+## Requirements
+
+- WorkOS account access and the relevant WorkOS environment variables for live implementation work, commonly `WORKOS_API_KEY`, `WORKOS_CLIENT_ID`, cookie/session secrets, webhook secrets, and widget token material.
+- The WorkOS CLI when the user asks Cline to run WorkOS setup or management commands. Cline should run it with `WORKOS_MODE=agent`, and with `--json` when command output is parsed.
+- Network access when the task requires current WorkOS documentation, CLI installation, or live WorkOS API calls.
+
+## Trust Boundaries
+
+The plugin does not register an MCP server, start background services, install dependencies, or call WorkOS at install time. It only contributes bundled skills. Live WorkOS changes remain user-approved runtime actions.
+
+Bundled WorkOS skill material is from WorkOS plugin metadata declaring MIT licensing. See `NOTICE.workos-skills`.

plugins/workos/index.ts

@@ -0,0 +1,10 @@
+import type { AgentPlugin } from "@cline/sdk"
+
+const plugin: AgentPlugin = {
+	name: "workos",
+	manifest: {
+		capabilities: ["skills"],
+	},
+}
+
+export default plugin

plugins/workos/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "workos",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "WorkOS skills for AuthKit, SSO, Directory Sync, RBAC, Widgets, migrations, and identity platform operations.",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "cline": {
+    "plugins": [
+      {
+        "paths": [
+          "./index.ts"
+        ],
+        "capabilities": [
+          "skills"
+        ]
+      }
+    ]
+  },
+  "peerDependencies": {
+    "@cline/sdk": "*"
+  },
+  "peerDependenciesMeta": {
+    "@cline/sdk": {
+      "optional": true
+    }
+  }
+}

plugins/workos/skills/workos-widgets/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: workos-widgets
+description: Use when the user is implementing, embedding, or debugging a WorkOS Widget -- specifically the User Management, User Profile, Admin Portal SSO Connection, or Admin Portal Domain Verification widgets. Handles the full stack -- detecting the frontend (Next.js, React, React Router, TanStack Start, Vite, SvelteKit), generating access tokens via the backend SDK in use (Node, Python, Go, Ruby, PHP, Java, .NET), and wiring up the widget component correctly per the bundled OpenAPI spec. Also use when code imports from @workos-inc/widgets or the user pastes <UserManagement /> or <UserProfile /> JSX.
+---
+
+# WorkOS Widgets
+
+## Cline Compatibility
+
+- Use Cline's available file-reading tools for bundled references.
+- Install dependencies or run `WORKOS_MODE=agent npx workos@latest install` only after explicit user approval. This command can mutate the user's project.
+- If AuthKit or WorkOS is missing and the user does not want Cline to run the installer, offer a manual integration path using the relevant bundled framework reference.
+- Treat widget access tokens, WorkOS API keys, cookies, session secrets, and organization/user data as sensitive.
+- Prefer existing project conventions over broad rewrites, and ask one focused question only when repository inspection cannot resolve a necessary implementation choice.
+- When running `query-spec.cjs`, use the absolute path to this plugin's bundled `references/scripts/query-spec.cjs` file, or `cd` into the `workos-widgets` skill directory first.
+
+## Workflow Overview
+
+1. Identify widget target from the user request (`user-management`, `user-profile`, `admin-portal-sso-connection`, `admin-portal-domain-verification`).
+2. Scan project files in this order:
+   - package/dependency manifests
+   - framework/router entrypoints
+   - auth/token utilities
+   - styling/component patterns
+3. Detect stack, data-layer style, styling, component system, and package manager using [references/detection.md](references/detection.md).
+4. Check for AuthKit/WorkOS presence:
+   - if detected, continue;
+   - if not detected, ask for approval before running `WORKOS_MODE=agent npx workos@latest install`, or offer to wire the widget manually from the relevant framework reference.
+5. If detection is ambiguous or conflicting, ask one focused question, then continue.
+6. Load only the relevant reference files for the detected stack and widget.
+7. Implement integration based on stack shape:
+   - frontend route/page + widget component when widget UI lives in the same app
+   - token endpoint/service + client integration surface when backend-first/multi-app architecture is detected
+8. Validate routing/wiring, imports, and token/API usage before finishing.
+
+## Canonical Inputs
+
+Accept these inputs from the user request when available:
+
+- widget type (or infer from request intent)
+- optional component path
+- optional page/route path
+- optional token endpoint/service preference
+- optional constraints (for example: avoid broad refactors)
+
+When input is missing, infer from existing project conventions and detected stack.
+
+## Detection and Ambiguity Protocol
+
+- Apply detection heuristics from [references/detection.md](references/detection.md).
+- Explore before asking. Ask only when ambiguity remains after checking manifests and route/auth entrypoints.
+- Ask a single concrete question that resolves one decision.
+- Default to the strongest detected ownership signals when no user response is available.
+- When installs are required, use the package manager detected from project files/lockfiles.
+
+## Reference Loading Map
+
+Always load these core references:
+
+- [references/detection.md](references/detection.md)
+- [references/token-strategies.md](references/token-strategies.md)
+- [references/fetching-apis.md](references/fetching-apis.md)
+- [references/styling-and-components.md](references/styling-and-components.md)
+
+For React/TypeScript stacks (Next.js, React Router, TanStack Router, TanStack Start, Vite), also load:
+
+- [references/react-ts-standards.md](references/react-ts-standards.md)
+
+Load stack-specific reference guidance:
+
+- Next.js: [references/framework-nextjs.md](references/framework-nextjs.md)
+- React Router: [references/framework-react-router.md](references/framework-react-router.md)
+- TanStack Router: [references/framework-tanstack-router.md](references/framework-tanstack-router.md)
+- TanStack Start: [references/framework-tanstack-start.md](references/framework-tanstack-start.md)
+- Vite: [references/framework-vite.md](references/framework-vite.md)
+- SvelteKit: [references/framework-sveltekit.md](references/framework-sveltekit.md)
+- Ruby: [references/framework-ruby.md](references/framework-ruby.md)
+- Python: [references/framework-python.md](references/framework-python.md)
+- Go: [references/framework-go.md](references/framework-go.md)
+- PHP: [references/framework-php.md](references/framework-php.md)
+- Java: [references/framework-java.md](references/framework-java.md)
+- Mixed repositories: [references/framework-mixed-repositories.md](references/framework-mixed-repositories.md)
+
+Then load exactly one widget reference:
+
+- User Management: [references/widget-user-management.md](references/widget-user-management.md)
+- User Profile: [references/widget-user-profile.md](references/widget-user-profile.md)
+- Admin Portal SSO Connection: [references/widget-admin-portal-sso-connection.md](references/widget-admin-portal-sso-connection.md)
+- Admin Portal Domain Verification: [references/widget-admin-portal-domain-verification.md](references/widget-admin-portal-domain-verification.md)
+
+## Global Widget Guidance
+
+- Implement widget operations using endpoint paths/methods from [references/fetching-apis.md](references/fetching-apis.md). When building request bodies or parsing responses, query the OpenAPI spec for the relevant widget's schemas:
+  ```bash
+  node references/scripts/query-spec.cjs --widget <widget-name>
+  ```
+  Use `--list` to see available widget groups.
+- Keep loading, empty, and error states explicit and user-visible.
+- Keep mutation outcomes visible and refresh/reload affected data after successful changes.
+- Align table/list/action UI with existing project conventions.
+- Keep behavior resilient for partial/optional data and avoid brittle UI assumptions.
+
+## Core Guidelines
+
+- Reuse existing domain types from the host project and OpenAPI schemas; avoid duplicating model definitions.
+- Build widget requests using [references/fetching-apis.md](references/fetching-apis.md) for paths, methods, and schema queries.
+- Use direct `fetch`/HTTP calls (or equivalent server HTTP client) for endpoint calls.
+- Implement a consistent authorization layer for widget requests, including elevated-token handling for sensitive endpoints when required.
+- If the app already uses React Query or SWR, use them as orchestration/cache layers around those direct calls.
+- For React/TypeScript widget code quality expectations, follow [references/react-ts-standards.md](references/react-ts-standards.md).
+- If AuthKit/WorkOS is missing, ask for approval before running `WORKOS_MODE=agent npx workos@latest install`, or offer to wire the widget manually from the relevant framework reference. `WORKOS_MODE=agent` keeps the installer deterministic (no prompts, no browser, no host-trust); pass `--json` when you need to parse the output.
+- Install additional dependencies only when strictly necessary, using the detected package manager/tooling.
+- Keep server-state handling aligned with the selected data-layer approach.
+- Use local state/reducers for UI interaction state as needed.
+- Prefer existing design system and styling conventions.
+- Avoid broad unrelated refactors and global style rewrites.
+
+## Completion Requirements
+
+Before finishing, verify all relevant items:
+
+1. Widget component exists and accepts `accessToken: string` when component-level integration is in scope.
+2. Route/page wiring is complete when route integration is in scope.
+3. Token source matches existing app architecture (AuthKit client flow or backend WorkOS token flow).
+4. API methods and paths match the bundled OpenAPI spec, and data-layer usage matches project conventions.
+5. Loading and error branches exist for required query/mutation flows.
+
+## Validation Checklist
+
+1. Confirm endpoint paths and HTTP methods come from the bundled OpenAPI spec.
+2. Confirm request/response handling follows schema expectations from the spec.
+3. Confirm query/mutation invalidation/refetch is applied after successful mutations where required.
+4. Confirm empty/error/loading states are explicit and user-visible.
+5. Confirm package installs (if any) used the detected package manager/tooling.
+6. Confirm implementation stays aligned with existing codebase conventions.
+7. Confirm no existing component has been passed `className` or `style` props to override its built-in styling. Use each component as-is or via its own props API (`variant`, `size`, etc.).

plugins/workos/skills/workos-widgets/references/detection.md

@@ -0,0 +1,89 @@
+# Detection
+
+## Objective
+
+Identify the active stack and integration surface using repository signals, then choose an approach that fits existing architecture.
+
+## Suggested Scan Order
+
+1. dependency manifests (`package.json`, `Gemfile`, `composer.json`, `pyproject.toml`, `requirements*.txt`, `go.mod`, `pom.xml`, `build.gradle*`)
+2. framework/router entrypoints
+3. auth and token utilities
+4. styling and component patterns
+5. package manager and lockfiles
+
+## Common Stack Signals
+
+### JavaScript/TypeScript
+
+- Next.js: `next`
+- TanStack Start: `@tanstack/react-start`
+- TanStack Router: `@tanstack/react-router`
+- React Router: `react-router` or `react-router-dom`
+- Vite: `vite` or `vite.config.*`
+- SvelteKit: `@sveltejs/kit` or `svelte.config.*`
+
+### Other Stacks
+
+- Ruby: `Gemfile` and WorkOS/AuthKit gems
+- PHP: `composer.json` and WorkOS/AuthKit packages
+- Python: `pyproject.toml` or `requirements*.txt` with WorkOS/AuthKit packages
+- Go: `go.mod` with `github.com/workos/workos-go`
+- Java: `pom.xml` or `build.gradle*` with WorkOS dependencies/imports
+
+## AuthKit/WorkOS Presence Signals
+
+Look for any existing AuthKit/WorkOS usage before implementing widgets.
+
+- JavaScript/TypeScript: `@workos-inc/*`, `@workos/*`, or WorkOS/AuthKit imports in app/server code
+- Ruby: WorkOS/AuthKit gems or initialization code
+- PHP: WorkOS/AuthKit composer packages or bootstrap usage
+- Python: WorkOS/AuthKit packages/imports and config usage
+- Go: WorkOS Go module imports/config
+- Java: WorkOS Java dependency/imports/config
+
+If no AuthKit/WorkOS signal is found, see SKILL.md step 4.
+
+## Detection Heuristics
+
+- Prefer entrypoint ownership over dependency names alone.
+- In mixed repositories, identify which app owns UI rendering and which service owns token generation.
+- Use the strongest cluster of signals, then validate by checking real route/auth files.
+
+## Data-Layer Signals
+
+- React Query signal: `@tanstack/react-query`
+- SWR signal: `swr`
+- No query library signal: use the project's native async/data approach with direct fetch/http calls.
+
+When React Query or SWR is already established, keep using it for caching/invalidation and wrap direct endpoint calls with it.
+
+## Package Manager/Tool Detection
+
+Use the project's existing package manager/tooling when installing missing dependencies.
+
+- JavaScript/TypeScript:
+  - `pnpm-lock.yaml` -> `pnpm`
+  - `yarn.lock` -> `yarn`
+  - `bun.lockb` or `bun.lock` -> `bun`
+  - `package-lock.json` -> `npm`
+  - if unclear, use existing install scripts or ask once
+- Ruby: use `bundle`/Bundler with `Gemfile`
+- PHP: use `composer` with `composer.json`
+- Python: follow existing tooling (`poetry.lock`, `uv.lock`, `requirements*.txt`, or existing project scripts)
+- Go: use Go modules tooling (`go mod` / existing project scripts)
+- Java: follow project tooling (`mvn`/Maven or `gradle`/Gradle wrappers)
+
+Install dependencies only when strictly necessary for the selected integration approach.
+
+## Ambiguity Handling
+
+- If multiple stacks/frameworks look active, ask one focused question.
+- If ownership is still unclear, choose the least invasive path and note assumptions.
+
+## Focused Question Examples
+
+- "I found multiple routers. Which one currently owns app routes?"
+- "I found backend and frontend apps. Which app should host the widget UI?"
+- "I found multiple data-fetching patterns. Which one should new widget code follow?"
+- "I found multiple services that could issue widget tokens. Which one should own token generation?"