# AGENTS.md

## Plugin Bundle Scope

This directory is the EzWebex Codex plugin bundle that ships to users.

- `.codex-plugin/plugin.json` is the plugin manifest and version source.
- `.mcp.json` defines MCP server processes exposed by the plugin.
- `server/webex-oauth-proxy.mjs` registers the native Webex, hosted EzDelegate, dashboard, profile, and helper tools.
- `server/digital-twin*.mjs` implements hosted Desktop handoff, classifier behavior, approval cards, shared-runner logic, and hosted job sync.
- `skills/*/SKILL.md` files are installed with the plugin and become user-visible agent instructions. Keep internal maintainer release instructions out of this directory.

The plugin must not depend on Cisco hosted Webex MCP servers for tool discovery. It exposes local REST-backed Webex tools and calls `https://webexapis.com/v1` with the signed-in user's OAuth token.

## Checks

Use targeted checks for touched files, plus these common validations before a plugin push or release:

```bash
python3 -m json.tool plugins/webex-messaging/.codex-plugin/plugin.json >/dev/null
python3 -m json.tool plugins/webex-messaging/.mcp.json >/dev/null
node --check plugins/webex-messaging/server/webex-oauth-proxy.mjs
node scripts/check-mcp-tools.mjs
node scripts/check-gpk2-mcp-tools.mjs
```

For digital-twin/handoff behavior, run the relevant Node tests, usually:

```bash
node --test plugins/webex-messaging/server/digital-twin.test.mjs
```

## Push And Release

- Normal development can push a feature branch and open a PR.
- A production plugin release is a `main`-backed bundle update. Do not push to `main` unless the user explicitly asks for a release/main/prod flow.
- When a plugin bundle change is released, bump the patch version in `.codex-plugin/plugin.json` unless the maintainer explicitly says not to.
- The CINT broker serves the ZIP from `main` and updates after its short cache window. Verify `https://webex-codex-auth.uscentral1-0.cint.vcra.co/bundle.json` when confirming a release.
- Use `.codex/skills/webex-plugin-release/SKILL.md` for manual release announcements to the private EzPlugin Webex space.

Keep release-channel details, room IDs, and maintainer-only instructions in `.codex/skills/webex-plugin-release/SKILL.md`, not in shipped plugin skills.
