Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 2 additions & 8 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -7,16 +7,10 @@
"plugins": [
{
"name": "workiq",
"description": "Full WorkIQ tool surface \u2014 agentic queries via ask plus direct reads and writes (create, update, delete, send) across emails, meetings, calendar, Planner tasks, documents, Teams, people and contacts, OneDrive, and SharePoint.",
"version": "2.0.2",
"description": "WorkIQ for Microsoft 365 mail, calendar, Teams, files, SharePoint, people, Planner and Business Applications. Use retrieve with source-based strategy selection to find evidence and summarize locally. Use ask only for a requested Copilot or named-agent answer; use entity tools for specific reads and operations, with confirmation before mutations. If workiq and workiq-preview are both installed, prefer workiq-preview only if its installed version is higher than workiq's; otherwise prefer workiq.",
"version": "3.0.0",
"source": "./plugins/workiq"
},
{
"name": "workiq-preview",
"description": "Preview WorkIQ for Microsoft 365 email, calendars, meetings, Teams messages, SharePoint and OneDrive files, people and contacts, and Planner tasks. Search, summarize, read, create, update, delete, send, and download using supported tools, with confirmation for mutations. Use retrieve-first context with explicit Grounding when available, intentional Copilot or named-agent delegation via ask, and entity tools for exact operations.",
"version": "2.1.0",
"source": "./plugins/workiq-preview"
},
{
"name": "microsoft-365-agents-toolkit",
"description": "Toolkit for building and evaluating Microsoft 365 Copilot declarative agents \u2014 scaffolding, JSON manifest development, capability configuration, and eval workflows.",
Expand Down
12 changes: 9 additions & 3 deletions .github/workflows/workiq-guidance.yml
Original file line number Diff line number Diff line change
@@ -1,21 +1,25 @@
name: WorkIQ preview guidance contracts
name: WorkIQ guidance contracts

on:
pull_request:
paths:
- 'plugins/workiq-preview/**'
- 'plugins/workiq/**'
- 'plugins/workiq/tests/**'
- '*.md'
- 'marketplace.json'
- '.claude-plugin/marketplace.json'
- '.github/plugin/marketplace.json'
- 'tests/workiq-guidance/**'
- '.github/workflows/workiq-guidance.yml'
push:
branches: [main]
paths:
- 'plugins/workiq-preview/**'
- 'plugins/workiq/**'
- 'plugins/workiq/tests/**'
- '*.md'
- 'marketplace.json'
- '.claude-plugin/marketplace.json'
- '.github/plugin/marketplace.json'
- 'tests/workiq-guidance/**'
- '.github/workflows/workiq-guidance.yml'
workflow_dispatch:
Expand Down Expand Up @@ -43,3 +47,5 @@ jobs:
- name: Static documentation and contract checks
run: npm run test:static
working-directory: tests/workiq-guidance
- name: Promoted stable plugin contracts
run: node --test plugins/workiq/tests/guidance.test.mjs
48 changes: 27 additions & 21 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,14 @@ Work IQ is a **Copilot CLI plugin marketplace** for managing AI agent plugins fo

```
work-iq/
├── .github/
│ └── plugin/
│ └── marketplace.json # Plugin marketplace registry
├── marketplace.json # Copilot marketplace registry
├── .claude-plugin/
│ └── marketplace.json # Equivalent Claude marketplace registry
├── plugins/ # Plugin packages (skills + MCP servers)
│ ├── workiq/
│ ├── workiq-preview/
│ ├── microsoft-365-agents-toolkit/
│ └── workiq-productivity/
├── tests/workiq-guidance/ # Offline preview guidance and trace-contract checks
├── server.json # MCP server manifest
├── tests/workiq-guidance/ # Offline stable guidance and trace-contract checks
├── ADMIN-INSTRUCTIONS.md # Tenant admin consent guide
├── CONTRIBUTING.md # Guide for adding new plugins
├── PLUGINS.md # Plugin catalog — skills, agents, and commands
Expand All @@ -30,7 +28,6 @@ This repo is a [Copilot CLI plugin marketplace](https://docs.github.com/en/copil

```bash
copilot plugin install ./plugins/workiq
copilot plugin install ./plugins/workiq-preview
copilot plugin install ./plugins/microsoft-365-agents-toolkit
copilot plugin install ./plugins/workiq-productivity
```
Expand All @@ -47,7 +44,6 @@ copilot plugin list

```bash
copilot plugin uninstall workiq
copilot plugin uninstall workiq-preview
copilot plugin uninstall microsoft-365-agents-toolkit
copilot plugin uninstall workiq-productivity
```
Expand All @@ -68,16 +64,18 @@ plugins/<plugin-name>/

### Available plugins

- **workiq** — Full WorkIQ tool surface for Microsoft 365 (read + write). Bundles:
- `workiq` skill — Guides usage of `ask` for semantic questions plus the entity tools for fast, structured M365 and Business Applications reads and writes
- Hosted MCP server (`workiq`) with tools: `ask_work_iq`, `fetch_work_iq`, `fetch_blob_work_iq`, `get_schema_work_iq`, `search_paths_work_iq`, `create_entity_work_iq`, `update_entity_work_iq`, `delete_entity_work_iq`, `do_action_work_iq`, `call_function_work_iq`, `get_debug_link`
- SharePoint library-metadata requests dispatch to `references/sharepoint-library-metadata.md`; read it before the workflow. Detailed procedures and safeguards live there rather than being duplicated in `SKILL.md`.
- **workiq** — Stable 3.0.0, agent-host-neutral Microsoft 365 guidance (read + write). Bundles:
- `workiq` skill — Source-based `retrieve` and local synthesis, `ask` only for requested Copilot/named-agent answers, and entity tools for exact reads and operations.
- Hosted MCP server (`workiq`): discover exact names and schemas in the host catalog. Installing the plugin does not enable tenant-dependent retrieval; missing retrieval never silently falls back to `ask`.
- Progressive loading: read the domain index, owning leaf and its `Required before use` dependencies before the call. Load mutation safeguards before writes, recovery before repair/replay, and result-status safeguards before final claims.
- File objects and transfer client actions route to `references/workiq-files-cli.md`; Graph drive-content/mail-attachment bytes remain on `fetch_blob`. CLI installation and EULA acceptance are separate, with explicit permission for acceptance.
- Agent/plugin lifecycle requests route to `references/wiqd.md` and the external, experimental WIQD plugin. Installation requires approval and a restart; WIQD is not bundled.
- Offline checks: `npm ci --prefix tests/workiq-guidance --ignore-scripts --no-audit --no-fund`, then `npm --prefix tests/workiq-guidance test` and `node --test plugins/workiq/tests/guidance.test.mjs` (Node 22+). No model or live M365 operations.
- Observed trace validation requires nonblank package-hash provenance; authoritative state claims are compared by property presence, including falsey values.

- **workiq-preview** — Preview build with agent-host-neutral, retrieve-first guidance (read + write). Bundles:
- `workiq-preview` skill — Retrieve caller-owned context with explicit Grounding when available; use `ask` only for intentional delegation, and entity tools for exact reads, writes, and downloads. Load the skill before using WorkIQ tools.
- Hosted MCP server (`workiq-preview`): discover exact tool names and schemas in the connected host catalog. Preview retrieval is tenant-dependent; installation does not enable it, and missing `retrieve` never silently falls back to `ask`.
- Preview-only offline checks: `npm ci --prefix tests/workiq-guidance --ignore-scripts --no-audit --no-fund` then `npm --prefix tests/workiq-guidance test` (Node 22+). CI does not run models or live M365 operations. The public `workiq` package retains its existing routing policy and version; its SharePoint metadata documentation is consolidated separately.
- Observed trace validation requires nonblank package-hash provenance, including direct validator calls; authoritative state claims are compared by property presence, including falsey values.
The public preview package is retired. Do not recreate it or register it.
Existing installations must follow [migration instructions](README.md#migrating-from-workiq-preview)
and restart; removing registry entries alone does not unload installed skills.

- **microsoft-365-agents-toolkit** — Toolkit for building M365 Copilot declarative agents. Bundles:
- `install-atk` skill — Install or update the M365 Agents Toolkit CLI and VS Code extension
Expand All @@ -100,7 +98,8 @@ plugins/<plugin-name>/

## Prerequisites

- **Node.js 18+** — Required for the workiq MCP server (`npx`)
- **Hosted workiq** — No local Node.js runtime required.
- **Local CLI/productivity skills** — Node.js 18+; optional WorkIQ Files CLI transfers require Node.js 20+ and a separate installation.
- **Admin consent** — The WorkIQ MCP server requires tenant admin consent on first use. See the [Tenant Administrator Enablement Guide](./ADMIN-INSTRUCTIONS.md) for details.

## Creating a New Plugin
Expand Down Expand Up @@ -142,20 +141,27 @@ Skill instructions here...
```

After creating a plugin:
1. Register it in `.github/plugin/marketplace.json` by adding an entry to the `plugins` array
1. Register it consistently in `marketplace.json` and `.claude-plugin/marketplace.json`
2. Install it with `copilot plugin install ./plugins/my-plugin`

---

## Self-Maintenance Instructions

Follow [CONTRIBUTING.md](CONTRIBUTING.md) for WorkIQ source ownership,
MAJOR.MINOR.PATCH versioning and internal preview-to-stable promotion.
Publish only the stable snapshot after its internal promotion merges. An earlier
publication PR must stay draft until the merge and source recheck. Keep public
marketplace identity `work-iq`; preserve unrelated plugin entries and workflows.
Never copy internal registries or preview into this repository.

> **Important:** When making changes to this repository — adding new plugins or modifying workflows — update this AGENTS.md file to reflect those changes. This file serves as the primary context document for AI agents working in this repo. Keep it accurate and current. Specifically:
>
> - Add new plugins to the "Available plugins" section when they are created
> - Register new plugins in `.github/plugin/marketplace.json`
> - Register new plugins consistently in both public marketplace registries
> - Update "Getting Started" if new setup steps are required
> - Update "Repository Structure" if top-level directories change
> - **After editing any skill or plugin content**, reinstall the affected plugin so the running session picks up the changes:
> - Validate edits offline first. Do not install plugins or access live Microsoft 365 data without authorization. For separately approved runtime validation, reload the affected plugin and restart so the session picks up its content:
> ```bash
> copilot plugin uninstall <plugin-name>
> copilot plugin install ./plugins/<plugin-name>
Expand Down
63 changes: 49 additions & 14 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,38 @@

Thank you for your interest in contributing to the Work IQ plugin collection! This document provides guidelines for adding new plugins and improving existing ones.

## WorkIQ development and publication

This public repository publishes promoted stable `workiq` releases, alongside
the other independently maintained marketplace plugins. The public
`workiq-preview` package is retired; do not re-add its package or registration.

WorkIQ feature changes for capabilities already public in production rings
belong in the Work IQ team's internal `workiq-preview` channel. Unreleased
features stay in team forks until ready to be made public. Public contributors
can submit issues or PRs here; Work IQ maintainers must carry accepted changes
back into the internal preview source before the next promotion, rather than
letting a later export overwrite public-only fixes.

The Work IQ team promotes preview to stable at least every two weeks, sooner
when warranted. Merge the reviewed internal promotion before publishing its stable
snapshot here. Draft publication PRs may be prepared earlier, but must remain
draft until the internal promotion merges and the exported source is rechecked.

Both internal channels use numeric MAJOR.MINOR.PATCH: patch for compatible
fixes, minor for compatible additions, major for breaking routing/behavior
changes. Stable stays pinned between promotions; future promotions preserve
the selected preview version. Stable 3.0.0 is the initial transition from the
older preview version sequence. Record the source commit/version and review
any public README/install-path adaptations separately from the package content.

Update the stable entry in both public registries while preserving marketplace
identity `work-iq` and unrelated plugin entries. Never copy the internal
two-plugin marketplace wholesale, publish internal preview, or overwrite ATK
sync, security/legal files or unrelated packages. Update user-facing migration
instructions for breaking changes and preserve host manifests, MCP identity,
authentication and required reference links.

## 🔌 Plugin Structure

Each plugin lives in `plugins/{plugin-name}/` and follows this structure:
Expand All @@ -26,7 +58,9 @@ plugins/{plugin-name}/

### Marketplace Registry

All plugins must be registered in `.github/plugin/marketplace.json`. Add your plugin entry:
All public plugins must be registered consistently in `marketplace.json` and
`.claude-plugin/marketplace.json`. Keep name, version and description consistent
with the plugin's host manifests. Add your plugin entry:

```json
{
Expand All @@ -43,7 +77,7 @@ All plugins must be registered in `.github/plugin/marketplace.json`. Add your pl
1. **Fork** the repository and create a feature branch
2. **Create** your plugin directory under `plugins/`
3. **Add** the required files (`.mcp.json`, `README.md`, `skills/*/SKILL.md`)
4. **Register** your plugin in `.github/plugin/marketplace.json`
4. **Register** your plugin in `marketplace.json` and `.claude-plugin/marketplace.json`
5. **Update** the root `README.md` plugin table
6. **Submit** a pull request

Expand Down Expand Up @@ -83,32 +117,33 @@ Description and parameters...
- Test your MCP server starts correctly
- Ensure your skill documentation is accurate

For `workiq-preview` guidance changes, use Node 22+:
For stable `workiq` guidance changes, use Node 22+:

```bash
npm ci --prefix tests/workiq-guidance --ignore-scripts --no-audit --no-fund
npm --prefix tests/workiq-guidance test
```

The [preview guidance contract](tests/workiq-guidance/README.md) covers parsed
frontmatter, local links, routing, metadata, and synthetic trace checks. It does
not apply the preview policy to the public `workiq` package or require their
versions to match. Keep preview metadata consistent across its host manifests,
`marketplace.json`, and `.claude-plugin/marketplace.json`.
The [guidance contract](tests/workiq-guidance/README.md) covers parsed
frontmatter, local links, progressive routing, metadata and synthetic trace
checks. The promoted plugin-local contracts also run directly:

```powershell
node --test plugins\workiq\tests\guidance.test.mjs
```

Preview guidance is agent-host-neutral; resolve logical tools against the current
host's catalog. After editing it, reinstall/reload `workiq-preview` using that
host's supported mechanism. Offline checks do not prove agent compliance, live
endpoint behavior, or support across hosts; any loading evidence applies only to
the host and version actually exercised.
Guidance is agent-host-neutral; resolve logical tools against the connected
host's catalog. Reinstall/reload through the chosen host for separately approved
runtime checks. Offline checks do not install plugins, access tenants, run
models, prove agent compliance or establish live tool availability.

## 📋 Pull Request Checklist

- [ ] Plugin directory created under `plugins/`
- [ ] `.mcp.json` with valid MCP server configuration
- [ ] `README.md` with installation instructions
- [ ] `SKILL.md` with YAML frontmatter and documentation
- [ ] Plugin registered in `.github/plugin/marketplace.json`
- [ ] Plugin registered consistently in `marketplace.json` and `.claude-plugin/marketplace.json`
- [ ] Root `README.md` updated with new plugin entry
- [ ] `PLUGINS.md` updated with new plugin entry, skills, and examples

Expand Down
Loading
Loading