Develop Wework Plugin

Develop a Wework plugin

Treat the Wework package as the outer delivery unit. It may declare a nested Codex plugin through wework.codexPlugin; the Codex plugin must never own or gate the Wework plugin.

Use the bundled development kit

This Skill includes the complete public Wework extension catalog, one exhaustive smoke-test plugin, three focused API references, and three product-oriented showcase plugins:

• Read references/extension-points.md before choosing a UI surface. It documents descriptor fields, component props, and the browser-module boundary.
• Inspect assets/ui-extension-demo before writing a low-level UI contribution.
• Inspect assets/reference-plugins for runnable, independently installable examples of Composer augmentation, persistent workflow UI, website navigation, and typed desktop-host integration. For a left-navigation button that opens a website in the Wework built-in browser, start from sidebar-browser-panel-demo. Copy only the closest example into the user's writable project, then delete every contribution the plugin does not need.
• Start with assets/showcase-plugins when the user wants a product-quality example. Workspace Copilot, Test Explorer, and Dev Environments represent popular AI-assistant, testing, and development-environment categories with deliberately different interaction models.
• Never edit files inside an installed plugin cache. Resolve these resources relative to this Skill, and copy examples to the active project first.

The catalog covers all public host slots:

• Navigation and apps: wework.action, wework.app, wework.route, wework.sidebar.navigation, wework.settings.page, and wework.settings.section.
• Project and workspace: wework.plugins.action, wework.project.create.section, wework.project.work.section, wework.workspace.menu.section, wework.workspace.tab, wework.workspace.sidebar.tab, wework.workspace.toolbar.action, wework.workspace.bottom-panel.tab, and wework.runtime-profile.workspace-policy.
• Composer: wework.composer.action.
• Home and context: wework.home, wework.task.status, wework.conversation.summary, and wework.board.card.status.
• Shell: wework.shell.before, wework.shell.after, and wework.shell.overlay.

It also documents the public ctx.wework.host, backend, commands, composer, contributions, chat, testing, environments, context, menus, keybindings, localization, configuration, storage, and secrets services. Prefer a command-backed menu contribution when the host already owns the button surface; use a raw UI slot when the plugin needs custom rendering.

Understand the package boundaries

A Wework Core DSH plugin normally contains:

plugin-root/
├── package.json
├── cordis.patch.yml
├── index.js
├── client.js
└── codex-plugin/                  # optional nested official Codex plugin
    ├── .codex-plugin/plugin.json
    └── skills/<skill-name>/SKILL.md

Wework creates .wework/plugin-development.json beside the project files to classify the local project and enable the 插件调试 tab. Treat that file as Wework project metadata, not as part of the distributable Codex plugin.

The boundaries are strict:

• package.json, cordis.patch.yml, index.js, and client.js belong to the outer Wework package.
• New projects contain only the outer Wework package by default. Add wework.codexPlugin and a nested Codex plugin only when the requested product capability actually includes Codex Skills, MCP servers, agents, or other official Codex plugin resources.
• A nested Codex plugin uses the official .codex-plugin/plugin.json format and official Codex folders only. Do not add Wework-only keys or files to its manifest.
• index.js runs in the Core DSH Node host. client.js runs in the browser client. Share data through declared services or messages, not accidental module state or startup order.
• Third-party plugins consume public Wework DSH slots and services. Never import private Wework application modules.

Inspect before editing

1. Read .wework/plugin-development.json, package.json, and the declared dsh.bundle.patch.
2. When wework.codexPlugin is present, read its .codex-plugin/plugin.json and every affected Skill or MCP entry below that directory.
3. Read every declared host, browser, or sidecar entry affected by the change.
4. Reuse public Wework DSH slots and services. Do not import private Wework application modules from a user plugin.
5. Remove duplicate loaders, watchers, compatibility paths, and generated examples that no longer serve the plugin.

Choose the smallest extension surface

Start from the user-visible outcome, then select the narrowest matching slot:

• Add a complete application with wework.app.
• Register the full-content route rendered by an existing workspace tab with wework.route. It does not create a tab; when the tab's contentRoute matches, the route component replaces that tab's entire content surface.
• Add left navigation with wework.sidebar.navigation.
• Create a selectable top-level workspace tab with wework.workspace.tab.
• Add project-scoped inspection or controls with wework.workspace.sidebar.tab.
• Add compact workspace-level actions with wework.workspace.toolbar.action.
• Add a full bottom-panel tool with wework.workspace.bottom-panel.tab.
• Add an input-adjacent action with wework.composer.action.
• Add plugin-management actions with wework.plugins.action.
• Add a standalone settings page with wework.settings.page.
• Add controls to an existing settings page with wework.settings.section; declare the target page in the contribution descriptor.
• Replace the empty-task hero above the Composer with wework.home; use the provided heading and call onSelectSuggestion to fill the active draft.
• Use contextual and shell slots only when the UI genuinely belongs to that lifecycle.

Do not build a parallel navigation, panel, or settings system when a public slot already owns that surface.

When a left-navigation item should open a website beside the current workspace, register a descriptor-only wework.workspace.sidebar.tab with mode: 'iframe' and url, then point the navigation descriptor's workspaceSidebarTab to that tab id. Do not register wework.app or create a top-level workspace tab for this interaction.

Open a route in its own workspace tab

When a sidebar item must preserve the current tab and open the plugin route in another top-level tab, put the public workspace-tab parameters in the navigation descriptor's path:

function workspaceTabPath(path, id, title) {
  const separator = path.includes('?') ? '&' : '?'
  const params = new URLSearchParams({
    workspaceTab: id,
    workspaceTabTitle: title,
  })
  return `${path}${separator}${params}`
}

ctx.slots.inject('wework.sidebar.navigation', () =>
  ctx.wework.contributions.register(ctx, 'wework.sidebar.navigation', {
    id: 'example.navigation',
    label: 'Example',
    path: workspaceTabPath('/example', 'auxiliary-example', 'Example'),
  })
)

Register the matching /example content with wework.route. A stable workspaceTab value creates the tab on the first navigation and selects that same tab later. Omitting workspaceTab intentionally replaces the active tab's route. Use a generated ID only when every action must create another tab. Do not import WorkspaceTabsContext, navigateTo, or other private Wework modules into a plugin.