From aa524ba05b5079db0418500493b76c24811e34db Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Mon, 13 Jul 2026 19:34:04 -0700 Subject: [PATCH 1/3] feat: add Codex plugin target --- .github/workflows/publish.yml | 22 ++ README.md | 26 ++- package-lock.json | 10 +- package.json | 4 +- pluginpack.config.ts | 72 +++++++ roots/codex/README.md | 51 +++++ scripts/sync-changelog.mjs | 7 +- skills/connect-glean/targets/codex/SKILL.md | 71 +++++++ skills/project-handoff/targets/codex/SKILL.md | 201 ++++++++++++++++++ .../targets/codex/SKILL.md | 69 ++++++ sources/codex/CHANGELOG.md | 43 ++++ sources/codex/LICENSE | 21 ++ sources/codex/README.md | 55 +++++ sources/codex/plugin.pluginpack.json | 3 + sources/dev-docs/targets/codex/README.md | 39 ++++ 15 files changed, 675 insertions(+), 19 deletions(-) create mode 100644 roots/codex/README.md create mode 100644 skills/connect-glean/targets/codex/SKILL.md create mode 100644 skills/project-handoff/targets/codex/SKILL.md create mode 100644 skills/skill-creation-guide/targets/codex/SKILL.md create mode 100644 sources/codex/CHANGELOG.md create mode 100644 sources/codex/LICENSE create mode 100644 sources/codex/README.md create mode 100644 sources/codex/plugin.pluginpack.json create mode 100644 sources/dev-docs/targets/codex/README.md diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 31d65a4..19ac8e7 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -18,8 +18,28 @@ permissions: contents: read jobs: + validate: + name: Validate all targets + runs-on: ubuntu-latest + steps: + - name: Checkout source + uses: actions/checkout@v5 + + - name: Setup Node.js + uses: actions/setup-node@v5 + with: + node-version: 24 + cache: npm + + - name: Install + run: npm ci + + - name: Build and validate + run: npm test + publish: name: ${{ matrix.target }} → ${{ matrix.repo }} + needs: validate runs-on: ubuntu-latest strategy: fail-fast: false @@ -29,6 +49,8 @@ jobs: repo: claude-plugins - target: cursor repo: cursor-plugins + - target: codex + repo: codex-plugins concurrency: group: pluginpack-sync-${{ matrix.target }} cancel-in-progress: true diff --git a/README.md b/README.md index b0dea63..2b2d4b5 100644 --- a/README.md +++ b/README.md @@ -4,20 +4,21 @@ The source-of-truth repository for Glean's official plugins for AI coding assistants. One portable library of skills, agents, rules, commands, and hooks is authored here once, and [`pluginpack`](https://github.com/gleanwork/pluginpack) compiles it into the native plugin layout each host expects — today **Claude -Code** and **Cursor**. The same skills ship to every target; only each host's -manifest layer differs, and pluginpack generates that. +Code**, **Cursor**, and **Codex**. Most skills share one base source; target +overrides handle the few host-specific setup and capability differences. ## Layout | Path | What it is | |------|------------| -| `skills/` | The portable skill library — one `SKILL.md` (plus optional `references/`) per capability, in the open Agent Skills format. Host-agnostic; **the source of truth.** | -| `sources/shared/` | Components shared by every target (subagents). | +| `skills/` | The portable skill library — one `SKILL.md` (plus optional `references/`) per capability, with host-specific files only under `targets//`. **The source of truth.** | +| `sources/shared/` | Components shared by targets that support them (subagents). | | `sources/claude/` | Claude-only components (slash-commands, hooks). | +| `sources/codex/` | Codex-only plugin documentation and static files. | | `sources/cursor/` | Cursor-only components (rules, commands, assets). | | `sources/dev-docs/` | Source for the separate `glean-dev-docs` plugin. | | `pluginpack.config.ts` | Build config — which sources compose into which plugin, per target. | -| `plugins/`, `glean/`, `glean-dev-docs/`, `.claude-plugin/`, `.cursor-plugin/` | **Generated** output. Don't edit by hand — it's rebuilt from source. | +| `plugins/`, `glean/`, `glean-dev-docs/`, `.agents/`, `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | **Generated** output. Don't edit by hand — it's rebuilt from source. | ## Plugins produced @@ -38,11 +39,13 @@ components, and emits each host's native format: skills, commands, and hooks. - **Cursor** — a marketplace + `plugin.json` referencing skills, agents, rules, and commands. +- **Codex** — a marketplace + `.codex-plugin/plugin.json` for each plugin, + with bundled skills and install-surface metadata. Skills use the open Agent Skills format — `SKILL.md` with `name`/`description` frontmatter and optional `references/` loaded on demand — which Claude Code, -Cursor, Gemini CLI, and Copilot all support. Write a skill once; it ships -everywhere, and per-host quirks are neutralized at build time. +Codex, Cursor, Gemini CLI, and Copilot all support. Base skills ship everywhere; +target overrides handle the few host-specific differences. > The plugins don't bundle a Glean MCP server — users connect one themselves > (your host's Glean MCP setup guides that). The skills then use whatever Glean MCP @@ -56,7 +59,7 @@ Requires Node >= 24. Install once with `npm install`. |---------|--------------| | `npm run build` | Compile all targets into the generated plugin output. | | `npm run validate` | Validate each target's generated output. | -| `npm test` | Diff a fresh build against the committed output (staleness gate). | +| `npm test` | Build every target, then validate each generated output. | | `npm run prune` | Remove stale generated files. | | `npm run clean` | Remove all generated output. | @@ -65,7 +68,8 @@ Requires Node >= 24. Install once with `npm install`. 1. Edit or create `skills//SKILL.md` (add `references/*.md` for deep, load-on-demand detail). 2. `npm run build` to regenerate the plugins. -3. `npm test` to confirm the output is well-formed and in sync. +3. `npm test` to confirm every target builds and validates cleanly. -Because every target compiles from the same `skills/` source, a change lands in -all of them at once. +Base skill changes reach every target that includes them. When one host needs +different instructions, add a full replacement at +`skills//targets//SKILL.md`; other targets keep the base file. diff --git a/package-lock.json b/package-lock.json index 33e414a..794b4b6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,7 +9,7 @@ "version": "3.0.0", "license": "MIT", "devDependencies": { - "@gleanwork/pluginpack": "^0.6.0", + "@gleanwork/pluginpack": "^0.7.0", "@release-it/conventional-changelog": "^11.0.1", "release-it": "^20.2.0" }, @@ -45,9 +45,9 @@ } }, "node_modules/@gleanwork/pluginpack": { - "version": "0.6.0", - "resolved": "https://registry.npmjs.org/@gleanwork/pluginpack/-/pluginpack-0.6.0.tgz", - "integrity": "sha512-kamtHC7aLNvGPIyVJPU66XKRpJxENHwEot5zd3P5P1UdCkvpofUbL23lX78+II6WwUEMatHs8FmHnNEPOJ11WQ==", + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/@gleanwork/pluginpack/-/pluginpack-0.7.0.tgz", + "integrity": "sha512-XcOlmxTiuVeR/fqxIia+8TiilmbiQ6jR6YJ0yk+94vOA/0ZjtgSA8PXTb5v+EOP6d2guqR8LGc45IjEiz76QIw==", "dev": true, "license": "MIT", "dependencies": { @@ -61,7 +61,7 @@ "pluginpack": "dist/cli.js" }, "engines": { - "node": ">=24.15.0" + "node": ">=22.12.0" } }, "node_modules/@inquirer/ansi": { diff --git a/package.json b/package.json index 1812dbd..b44ec57 100644 --- a/package.json +++ b/package.json @@ -13,13 +13,13 @@ "build": "pluginpack build", "clean": "pluginpack clean", "prune": "pluginpack prune", - "validate": "pluginpack validate --target claude --dir dist/claude && pluginpack validate --target cursor --dir dist/cursor", + "validate": "pluginpack validate --target claude --dir dist/claude && pluginpack validate --target cursor --dir dist/cursor && pluginpack validate --target codex --dir dist/codex", "test": "npm run build && npm run validate", "prebuild": "node scripts/sync-changelog.mjs", "release": "release-it" }, "devDependencies": { - "@gleanwork/pluginpack": "^0.6.0", + "@gleanwork/pluginpack": "^0.7.0", "@release-it/conventional-changelog": "^11.0.1", "release-it": "^20.2.0" }, diff --git a/pluginpack.config.ts b/pluginpack.config.ts index fad81a7..165708e 100644 --- a/pluginpack.config.ts +++ b/pluginpack.config.ts @@ -83,5 +83,77 @@ export default defineConfig({ }, }, }, + codex: { + outDir: "dist/codex", + rootFiles: { + "README.md": "roots/codex/README.md", + LICENSE: "LICENSE", + }, + manifest: { + name: "glean-codex-plugins", + interface: { displayName: "Glean for Codex" }, + }, + plugins: { + glean: { + from: ["glean-lib", "codex"], + components: ["skills"], + description: + "Official Glean plugin — search documents, Slack, and email; explore code across repos; find experts and stakeholders; prep for meetings and onboarding.", + manifest: { + interface: { + displayName: "Glean", + shortDescription: "Enterprise knowledge in Codex", + longDescription: + "Search enterprise documents, Slack, email, code, and people; prepare for meetings; and synthesize trusted company knowledge in Codex.", + developerName: "Glean", + category: "Productivity", + capabilities: ["Read", "Search"], + defaultPrompt: [ + "Search Glean for the latest project decision.", + "Find an expert on this codebase.", + "Prepare me for my next meeting.", + ], + }, + }, + entry: { + policy: { + installation: "AVAILABLE", + authentication: "ON_INSTALL", + }, + category: "Productivity", + }, + }, + "glean-dev-docs": { + from: ["dev-docs"], + components: ["skills"], + description: + "Search the public Glean developer documentation — APIs, SDKs, MCP, and integration guides for building with Glean.", + manifest: { + homepage: "https://developers.glean.com/", + interface: { + displayName: "Glean Developer Docs", + shortDescription: "Build with Glean in Codex", + longDescription: + "Search public Glean API, SDK, MCP, authentication, and integration documentation while you build in Codex.", + developerName: "Glean", + category: "Productivity", + capabilities: ["Read", "Search"], + defaultPrompt: [ + "How do I authenticate with the Glean API?", + "Find the Glean Indexing API documentation.", + "Show me a Glean SDK example.", + ], + }, + }, + entry: { + policy: { + installation: "AVAILABLE", + authentication: "ON_INSTALL", + }, + category: "Productivity", + }, + }, + }, + }, }, }); diff --git a/roots/codex/README.md b/roots/codex/README.md new file mode 100644 index 0000000..d4d14d4 --- /dev/null +++ b/roots/codex/README.md @@ -0,0 +1,51 @@ +# Glean Plugins for Codex + +> **Generated repository.** Built from +> [gleanwork/agent-plugins](https://github.com/gleanwork/agent-plugins) via +> [pluginpack](https://github.com/gleanwork/pluginpack). Don't hand-edit managed +> files here — changes are made in `agent-plugins` and synced through generated +> pull requests. + +Official Glean plugins for [Codex](https://developers.openai.com/codex) — +enterprise knowledge, search, people, code, meetings, and Glean developer docs. + +## Install + +```bash +codex plugin marketplace add gleanwork/codex-plugins +codex plugin add glean@glean-codex-plugins +codex plugin add glean-dev-docs@glean-codex-plugins +``` + +Before starting Codex, connect the MCP server used by the plugin you installed: + +- **Glean enterprise knowledge:** get your server URL and name from the + [Glean MCP configurator](https://app.glean.com/settings/install?mcpConfigure=true), + then run `codex mcp add glean --url /mcp/` followed by + `codex mcp login glean`. +- **Glean developer docs:** run + `codex mcp add glean-dev-docs --url https://developers.glean.com/mcp`. + +Then start a new Codex task so the bundled skills and MCP tools are available. + +## Plugins + +| Plugin | Description | +|--------|-------------| +| **[glean](plugins/glean)** | Enterprise knowledge — search docs/Slack/email, cross-repo code exploration, people & experts, meetings, onboarding, and productivity. | +| **[glean-dev-docs](plugins/glean-dev-docs)** | Search Glean's public developer documentation — APIs, SDKs, MCP, and integration guides. | + +## Requirements + +- [Codex](https://developers.openai.com/codex) with plugin support +- A Glean account with MCP access (for the `glean` plugin) + +## Support + +- [Glean MCP Documentation](https://docs.glean.com/mcp) +- [Glean Support](https://help.glean.com) +- [GitHub Issues](https://github.com/gleanwork/codex-plugins/issues) + +## License + +MIT License — see [LICENSE](LICENSE) for details. diff --git a/scripts/sync-changelog.mjs b/scripts/sync-changelog.mjs index 52c2034..cc5ef99 100644 --- a/scripts/sync-changelog.mjs +++ b/scripts/sync-changelog.mjs @@ -9,7 +9,12 @@ import { dirname, join } from "node:path"; const root = join(dirname(fileURLToPath(import.meta.url)), ".."); const source = join(root, "CHANGELOG.md"); -const buckets = ["sources/claude", "sources/cursor", "sources/dev-docs"]; +const buckets = [ + "sources/claude", + "sources/codex", + "sources/cursor", + "sources/dev-docs", +]; for (const bucket of buckets) { copyFileSync(source, join(root, bucket, "CHANGELOG.md")); diff --git a/skills/connect-glean/targets/codex/SKILL.md b/skills/connect-glean/targets/codex/SKILL.md new file mode 100644 index 0000000..790eacb --- /dev/null +++ b/skills/connect-glean/targets/codex/SKILL.md @@ -0,0 +1,71 @@ +--- +name: connect-glean +description: Help the user connect a Glean MCP server so the Glean skills have tools to call — use when setting up Glean for the first time, adding another Glean server, checking whether Glean is connected, or troubleshooting missing Glean tools. Trigger phrases include "set up Glean", "connect Glean", "configure Glean MCP", "add a Glean server", "is Glean connected", "check Glean status", "Glean isn't working", "no Glean tools", "the Glean tools aren't showing up", "I installed the Glean plugin but nothing happens". Don't use it for actual enterprise queries once connected (use the using-glean skill); this skill only sets up and verifies the connection. +--- + +# Connect Glean + +The Glean plugin ships skills but **does not bundle an MCP server** — the skills +call whatever Glean MCP tools Codex exposes. If no Glean MCP server is connected, +the skills have nothing to call. This skill connects one, or verifies and +troubleshoots an existing connection. + +## When this applies + +- **First-time setup** — the Glean plugin is installed but no Glean tools appear. +- **Adding another server** — e.g. a second backend or a code-search server. +- **Status / troubleshooting** — "is Glean connected?", "no Glean tools showing". + +## What you need first + +Gather these once, then use them in the Codex setup below: + +1. **Server URL** — the Glean backend, found at + . Looks like + `https://acme-be.glean.com` or `https://be-4f5226e2.glean.com`. +2. **Server name** — organization-specific, from the user's Glean admin. Often + `default`. +3. **Friendly name** — what to call it in the host. Use `glean` for a single + server, or `glean-` when adding several (e.g. `glean-default`, + `glean-code`). + +The MCP endpoint is always `/mcp/`. It is a **remote +HTTP** server and uses OAuth — there is no API key to paste. + +## Configure Codex + +Run: + +```bash +codex mcp add --url /mcp/ +codex mcp login +``` + +Complete the browser OAuth flow, then verify with `codex mcp list` (look for a +`glean.com/mcp` URL). Start a new Codex task so the MCP tools are available. + +## Checking status / troubleshooting "no Glean tools" + +If the Glean skills run but report missing tools, Codex has no usable Glean MCP +server in the current task: + +1. Run `codex mcp list` and look for a `glean.com/mcp` URL. +2. If none is configured, run the setup above. +3. If it is configured but not authenticated, run + `codex mcp login `. +4. Start a new Codex task after configuration or authentication. + +## Glean developer docs server (separate, optional) + +The `glean-dev-docs` plugin uses a **different, public** server — no Glean +account or OAuth is required: + +```bash +codex mcp add glean-dev-docs --url https://developers.glean.com/mcp +``` + +Start a new Codex task after adding it. + +## Related skills + +- **using-glean** — once connected, drives enterprise search, Q&A, and synthesis. diff --git a/skills/project-handoff/targets/codex/SKILL.md b/skills/project-handoff/targets/codex/SKILL.md new file mode 100644 index 0000000..2492643 --- /dev/null +++ b/skills/project-handoff/targets/codex/SKILL.md @@ -0,0 +1,201 @@ +--- +name: project-handoff +description: Generate a comprehensive handoff document so someone new can take over a project — current state, key people, essential knowledge, open items, and a first-30-days plan. Use when the user is handing off a project (trigger phrases include "generate a handoff", "hand off this project", "create a handoff doc", "I'm going on PTO / leaving / changing teams and need to document", "help someone take over") rather than a quick status read (use project-awareness for that). +--- + +# Project Handoff + +Generate a comprehensive handoff document so someone new can take over a +project. Gather everything they'd need: current state, the people who matter, +tribal knowledge, open items, and a concrete ramp-up plan. + +Determine the project from the user's request. If no project is clear, ask +which project they mean before proceeding. + +This is the heavyweight counterpart to the **project-awareness** skill (quick +status reads). Use that one if the user just wants current status. + +## Tools + +This skill drives the standard Glean MCP tools. If Codex exposes subagent tools, +delegate project research to a general research subagent; otherwise gather the +same material directly in the current task. For the param shape and pitfalls of +`search`, `chat`, `meeting_lookup`, and `employee_search`, see the using-glean +reference at `using-glean/reference/`. If no Glean tools are visible, the user +hasn't connected a Glean MCP server — point them at the Codex setup instructions. + +## Core Principles + +- **Complete context**: include everything needed to take over +- **Actionable items**: clear next steps and open items +- **Tribal knowledge**: capture what's not in docs +- **Be skeptical**: not every doc found is relevant to a handoff +- **Quality over quantity**: focus on what the new owner actually needs + +## Phase 1: Gather current context + +Understand the project's current state. + +1. Ask the user for handoff context: + - Their role on the project (Owner/Lead, Contributor, Advisor/Stakeholder) + - What's driving the handoff (new role/team, PTO coverage, reorg, leaving) +2. If subagent tools are available, delegate the research to a general subagent. + Otherwise gather it directly. Cover documentation, people and their roles, + recent meetings and decisions, and current status / open items. + +## Phase 2: Gather undocumented knowledge + +Capture tribal knowledge not in formal docs. Ask the current owner: + +- "What's the #1 thing someone taking over needs to know?" +- "What are the biggest risks or gotchas?" +- "What relationships are critical to maintain?" +- "What recurring tasks or ceremonies exist?" +- "What access/permissions are needed?" +- "What decisions are pending?" + +## Phase 3: Identify open items + +1. Search for open work: `search "[project] TODO OR action item OR blocked OR in progress"` +2. Check recent commitments: `meeting_lookup "[project]"` over the past ~2 weeks (extract transcript) +3. Synthesize: `chat "What are the open action items, pending decisions, and blockers for [project]?"` +4. Categorize: Immediate (1-2 weeks), Upcoming (next month), Future (backlog). + +## Phase 4: Vet all content (CRITICAL) + +Filter to what's genuinely needed — be skeptical. + +**Handoff relevance** — ✅ essential / 📚 reference / ❌ skip (historical, tangential) +**Currency** — ✅ current / ⚠️ aging (note it) / ❌ stale (exclude) +**Actionability** — ✅ action needed / 📋 awareness only / ❌ FYI + +For each person: are they still relevant, what's the real relationship, why +would the new owner need them? For each open item: is it actually still open, +is it the new owner's responsibility, what's the real urgency? + +## Phase 5: Generate the handoff document + +```markdown +# Project Handoff: [Project Name] + +**Prepared by**: [Current owner] +**Date**: [Today's date] +**Reason for handoff**: [From Phase 1] + +## Content Quality +| Category | Items Found | Included | Reason for Filtering | +|----------|-------------|----------|----------------------| +| Documents | [X] | [Y] | [Z] historical/tangential | +| People | [X] | [Y] | [Z] no longer relevant | +| Open Items | [X] | [Y] | [Z] already resolved | + +## Executive Summary +[3-4 paragraphs: what the project is, where it stands, critical context for success, most important next steps] + +## Project Overview +### What This Project Is +[Purpose and scope] +### Why It Exists +[Business context, problem being solved] +### Current Status +| Attribute | Value | +|-----------|-------| +| **Phase** | [Planning/In Progress/Launch Prep/etc.] | +| **Health** | [Green/Yellow/Red] - [Why] | +| **% Complete** | [Estimate] | +| **Target Date** | [Date] | + +## People & Relationships (Vetted) +### Key Contacts (must maintain these relationships) +| Person | Role | Relationship | How to Engage | Why Critical | +|--------|------|--------------|---------------|--------------| +| [Name] | [Role] | [Critical/Important] | [Best approach] | [Specific reason] | +### Stakeholders to Keep Updated +- [Name/Group] - [What they care about] - [How often] +### Not Included +| Person | Reason | +|--------|--------| +| [Name] | Historical involvement only | + +## Essential Knowledge +### The #1 Thing to Know +[Critical context from current owner — from Phase 2] +### Key Decisions Made (that still matter) +| Decision | When | Why | Implications | +|----------|------|-----|--------------| +| [Decision] | [Date] | [Rationale] | [What this means for new owner] | +### Risks & Gotchas +| Risk | Likelihood | Impact | Mitigation | +|------|------------|--------|------------| +| [Risk] | H/M/L | H/M/L | [How to handle] | +### What's Not Documented +[Tribal knowledge that only exists in people's heads] + +## Documentation Guide (Vetted) +### Must-Read Docs (in order) +1. **[Doc Title]** ([link]) — why essential, ~[X] min, last updated [date] +### Reference When Needed +- **[Doc Title]** — [when you'd need it] +### Skipped Documents +| Doc | Reason | +|-----|--------| +| [Title] | Historical — superseded by [other doc] | +### Where Things Live +| Resource | Location | Access Needed | +|----------|----------|---------------| +| [Code] | [Repo link] | [Permissions] | + +## Open Items (Vetted) +### Immediate (Next 2 Weeks) +| Item | Status | Deadline | What To Do | Notes | +|------|--------|----------|------------|-------| +| [Item] | [Status] | [Date] | [Specific action] | [Context] | +### Pending Decisions +| Decision | Options | Who Decides | Deadline | +|----------|---------|-------------|----------| +| [Decision] | [A, B, C] | [Person] | [Date] | +### Blockers +| Blocker | Impact | Who Can Unblock | +|---------|--------|-----------------| +| [Blocker] | [Impact] | [Person] | + +## Operations +### Recurring Tasks +| Task | Frequency | When | How | +|------|-----------|------|-----| +| [Task] | [Weekly/etc.] | [Day/time] | [Instructions] | +### Meetings to Attend +| Meeting | Frequency | Purpose | Your Role | +|---------|-----------|---------|-----------| +| [Meeting] | [Frequency] | [Purpose] | [What to do] | +### Access & Permissions Needed +- [ ] [System/tool] — request from [person/team] + +## First 30 Days +### Week 1: Orientation +- [ ] Read essential docs (above) +- [ ] Meet with [key contact] +- [ ] Get access to [systems] +### Week 2: Immersion +- [ ] Take ownership of [first item] +- [ ] Attend [key meeting] +### Week 3-4: Transition +- [ ] Lead [responsibility] +- [ ] Make decision on [pending item] + +## Questions? +Contact [current owner] until [date]. After that, [backup person]. +``` + +## Troubleshooting + +- **Sparse information**: lean on the Phase 2 tribal-knowledge questions, mark + gaps clearly, and don't pad with marginally relevant docs. +- **Owner unavailable**: generate from available documentation, mark + "Needs Input" on sections requiring owner knowledge, and note limitations at + the top. + +## Related Skills + +- **project-awareness** — quick status read (lighter weight) +- **onboarding** — get up to speed on a team or area diff --git a/skills/skill-creation-guide/targets/codex/SKILL.md b/skills/skill-creation-guide/targets/codex/SKILL.md new file mode 100644 index 0000000..a90a8bb --- /dev/null +++ b/skills/skill-creation-guide/targets/codex/SKILL.md @@ -0,0 +1,69 @@ +--- +name: skill-creation-guide +description: Discover and vet reusable skill opportunities from the user's Glean work patterns. Use when the user asks "what should I automate", "find skill opportunities", or wants to turn recurring work into skills. For authoring a known skill in Codex, hand off to the built-in skill-creator. +--- + +# Skill Creation Guide + +Help the user identify valuable agent-skill opportunities from Glean context. +Vet candidates carefully, then hand actual authoring to Codex's built-in +`$skill-creator`. + +## BE SKEPTICAL + +Not every idea makes a good skill. Evaluate before creating: + +**Recurrence** — Will this be used repeatedly? +- ✅ Weekly or more → create +- ⚠️ Monthly → reconsider, may not be worth it +- ❌ One-time → skip + +**Automation** — Can it actually be automated? +- ✅ Clear, repeatable process → create +- ⚠️ Needs significant judgment each time → reconsider +- ❌ Too context-dependent, each case unique → skip + +**Value** — Is the cumulative time saved significant? +- ✅ Meaningful savings per use → create +- ❌ Slower to invoke than doing manually → skip + +**Duplication** — Does it already exist? +- ✅ Novel, unaddressed need → create +- ⚠️ Similar to an existing skill → enhance that instead +- ❌ Already covered → skip + +Don't create skills for one-time events, tasks that differ fundamentally each +time, sub-30-second manual tasks, or things the user will forget exist. + +## Workflow A — Discover opportunities + +When the user asks what they should automate, analyze their work patterns first. + +Requires the Glean MCP tools. If they aren't visible, the user hasn't connected +a Glean MCP server — point them at the **connect-glean** skill. + +1. Gather context with Glean: `memory` (roles, responsibilities, active + projects), `user_activity` (past ~2 weeks), and `search` for process docs + (`"runbook OR checklist OR process owner:me"`). +2. If subagent tools are available, delegate this analysis to a general + subagent with the gathered context and recurrence/value tests. Otherwise + analyze the patterns directly in the current task. +3. Present vetted recommendations grouped by cumulative value, and show the + rejected candidates with reasons. A few high-quality candidates beat many + weak ones — "no automatable patterns" is a valid outcome. + +See `using-glean/reference/` for the param shape of `memory`, `user_activity`, +and `search`. + +## Workflow B — Generate a skill + +When the user selects a candidate or already has a specific skill in mind: + +1. Pass the vetted concept, requirements, available-tools context, and relevant + Glean findings to `$skill-creator`. +2. Let `$skill-creator` determine the final structure, files, and installation + location. Do not duplicate its generation workflow here. + +## Related skill + +- `$skill-creator` — authors and validates the selected skill for Codex. diff --git a/sources/codex/CHANGELOG.md b/sources/codex/CHANGELOG.md new file mode 100644 index 0000000..c27e8e0 --- /dev/null +++ b/sources/codex/CHANGELOG.md @@ -0,0 +1,43 @@ +# Changelog + +## 3.0.0 (2026-06-14) + +### Features + +* add connect-glean skill for Glean MCP setup ([45e6864](https://github.com/gleanwork/agent-plugins/commit/45e6864dd672aec90362e54d2c86891e04ffec7d)) +* consolidate Glean agent plugins ([67c689e](https://github.com/gleanwork/agent-plugins/commit/67c689e0e6a5b008e35423638af9494e9a1c5c1f)) +* consolidate sources, add skills authoring + project-handoff, scaffold release-it ([c79492c](https://github.com/gleanwork/agent-plugins/commit/c79492c9dc8fab8cd2c5aec4f098df488c09dce7)) +* unify skills into one source compiled to one plugin per target ([0f60738](https://github.com/gleanwork/agent-plugins/commit/0f607387890a735fffc94b1742d2dd8debaa7a54)) + +### Bug Fixes + +* bump create-github-app-token to v3 (Node 24) ([eb6183d](https://github.com/gleanwork/agent-plugins/commit/eb6183ddc294b965e87dc740cf09dd5b4705557b)) +* pin node-version in publish workflow ([d3c91af](https://github.com/gleanwork/agent-plugins/commit/d3c91afd984d9f17981af7cc5a97eaca9c6bddc2)) +* pin pluginpack-action by full commit SHA ([7624de5](https://github.com/gleanwork/agent-plugins/commit/7624de574a3864456bf398b8afedf4b453c965d2)) +* read App ID from variable or secret ([0f02ecc](https://github.com/gleanwork/agent-plugins/commit/0f02ecc4465e56e8eefef2a4e0f0c2044771be3c)) +* rev package.json on release via release-it ([9b36785](https://github.com/gleanwork/agent-plugins/commit/9b36785a38278d2e7f4f79f6ac52499ccec030a9)) +* use client-id for create-github-app-token v3 ([1f949a3](https://github.com/gleanwork/agent-plugins/commit/1f949a3e5a5acab9ef3ca7ca511307b55c50ce75)) + +## [2.1.1](https://github.com/gleanwork/cursor-plugins/compare/v2.1.0...v2.1.1) (2026-03-17) + +## [2.1.0](https://github.com/gleanwork/cursor-plugins/compare/v2.0.0...v2.1.0) (2026-02-26) + +### Features + +* update plugin category and keywords for Cursor marketplace ([7991c0e](https://github.com/gleanwork/cursor-plugins/commit/7991c0eeb31bac044d7750973c36ee9973e34a02)) + +## [2.0.0](https://github.com/gleanwork/cursor-plugins/compare/v1.0.0...v2.0.0) (2026-02-25) + +## 1.0.0 (2026-02-21) + +All notable changes to this project will be documented in this file. + +## 0.1.0 (Unreleased) + +### Features + +- **glean-core**: Foundation plugin with 6 skills, 2 rules, and 2 commands +- **glean-search**: Enterprise search agent and command +- **glean-code**: Cross-repo code exploration with 2 agents and 5 commands +- **glean-people**: People finder agent and stakeholder discovery commands +- Validation script and CI workflow diff --git a/sources/codex/LICENSE b/sources/codex/LICENSE new file mode 100644 index 0000000..eb02a81 --- /dev/null +++ b/sources/codex/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Glean + +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. diff --git a/sources/codex/README.md b/sources/codex/README.md new file mode 100644 index 0000000..76a8b67 --- /dev/null +++ b/sources/codex/README.md @@ -0,0 +1,55 @@ +# Glean for Codex + +Official Glean plugin for [Codex](https://developers.openai.com/codex) — enterprise search, +code exploration, and people discovery directly in your development workflow. + +## Setup + +### 1. Install the plugin + +```bash +codex plugin marketplace add gleanwork/codex-plugins +codex plugin add glean@glean-codex-plugins +``` + +### 2. Configure your Glean MCP server + +Get your server URL and server name from the +[Glean MCP configurator](https://app.glean.com/settings/install?mcpConfigure=true), then run: + +```bash +codex mcp add glean --url https://YOUR-INSTANCE-be.glean.com/mcp/YOUR-SERVER-NAME +codex mcp login glean +``` + +Complete the browser OAuth flow, then verify with `codex mcp list`. Start a new +Codex task so both the bundled skills and Glean MCP tools are available. + +## What's Included + +The plugin ships a library of skills that auto-trigger by task — there's no +per-skill install. They cover: + +- **Enterprise search & knowledge** — find documents, Slack messages, and email; vet results for freshness and authority. +- **Code across repos** — explore implementations, find usage examples and similar code, identify code owners, and gather architectural context. +- **People & org** — find experts by contribution, and identify stakeholders for a change or project. +- **Meetings** — prep for upcoming meetings and catch up on what you missed. +- **Onboarding & projects** — ramp up on a team or area, read quick project status, and generate comprehensive project handoffs. +- **Personal productivity** — summarize your own activity, prep status updates, and surface what needs your attention. +- **Skill authoring** — discover automation opportunities and generate new skills. + +## Requirements + +- [Codex](https://developers.openai.com/codex) with plugin support +- A Glean account with MCP access +- Your Glean MCP server URL and server name + +## Support + +- [Glean MCP Documentation](https://docs.glean.com/mcp) +- [Glean Support](https://help.glean.com) +- [GitHub Issues](https://github.com/gleanwork/agent-plugins/issues) + +## License + +MIT — see [LICENSE](LICENSE) for details. diff --git a/sources/codex/plugin.pluginpack.json b/sources/codex/plugin.pluginpack.json new file mode 100644 index 0000000..0840a54 --- /dev/null +++ b/sources/codex/plugin.pluginpack.json @@ -0,0 +1,3 @@ +{ + "description": "Codex-specific documentation and static files for the Glean plugin." +} diff --git a/sources/dev-docs/targets/codex/README.md b/sources/dev-docs/targets/codex/README.md new file mode 100644 index 0000000..ce0eca7 --- /dev/null +++ b/sources/dev-docs/targets/codex/README.md @@ -0,0 +1,39 @@ +# Glean Developer Docs + +Search the public [Glean developer documentation](https://docs.glean.com) — APIs, SDKs, +MCP, authentication, indexing, and integration guides for building *with* Glean. + +This is a separate, focused plugin for people building on the Glean platform. For +searching your own company's internal knowledge, use the main **Glean** plugin instead. + +## Setup + +### 1. Install the plugin + +Install the plugin from the Codex marketplace. + +### 2. Configure the Glean Dev Docs MCP server + +This plugin uses the public Glean Developer Docs MCP server. No Glean account +is required. Add it to Codex with: + +```bash +codex mcp add glean-dev-docs --url https://developers.glean.com/mcp +``` + +Start a new Codex task so the MCP tools are available. + +## What's Included + +A single skill that auto-triggers when you ask about building with Glean — API +syntax, SDK usage, MCP setup, indexing, authentication, and platform integration. +It searches the public developer documentation and returns cited answers. + +## Support + +- [Glean Developer Documentation](https://docs.glean.com) +- [GitHub Issues](https://github.com/gleanwork/agent-plugins/issues) + +## License + +MIT — see [LICENSE](LICENSE) for details. From 632bf677a449909a082d6f610d0fc5f8434585e0 Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Tue, 14 Jul 2026 07:32:09 -0700 Subject: [PATCH 2/3] feat: add Codex plugin icons --- pluginpack.config.ts | 12 ++++++++---- sources/codex-assets/assets/avatar.png | Bin 0 -> 2481 bytes 2 files changed, 8 insertions(+), 4 deletions(-) create mode 100644 sources/codex-assets/assets/avatar.png diff --git a/pluginpack.config.ts b/pluginpack.config.ts index 165708e..4d94c2f 100644 --- a/pluginpack.config.ts +++ b/pluginpack.config.ts @@ -95,8 +95,8 @@ export default defineConfig({ }, plugins: { glean: { - from: ["glean-lib", "codex"], - components: ["skills"], + from: ["glean-lib", "codex", "codex-assets"], + components: ["skills", "assets"], description: "Official Glean plugin — search documents, Slack, and email; explore code across repos; find experts and stakeholders; prep for meetings and onboarding.", manifest: { @@ -113,6 +113,8 @@ export default defineConfig({ "Find an expert on this codebase.", "Prepare me for my next meeting.", ], + composerIcon: "./assets/avatar.png", + logo: "./assets/avatar.png", }, }, entry: { @@ -124,8 +126,8 @@ export default defineConfig({ }, }, "glean-dev-docs": { - from: ["dev-docs"], - components: ["skills"], + from: ["dev-docs", "codex-assets"], + components: ["skills", "assets"], description: "Search the public Glean developer documentation — APIs, SDKs, MCP, and integration guides for building with Glean.", manifest: { @@ -143,6 +145,8 @@ export default defineConfig({ "Find the Glean Indexing API documentation.", "Show me a Glean SDK example.", ], + composerIcon: "./assets/avatar.png", + logo: "./assets/avatar.png", }, }, entry: { diff --git a/sources/codex-assets/assets/avatar.png b/sources/codex-assets/assets/avatar.png new file mode 100644 index 0000000000000000000000000000000000000000..14e232fae59dbd6b4f55236db116b9d77014ee2a GIT binary patch literal 2481 zcmai$=|9wqAH}~jX2u|E#xl0aTDIsa$~p{ViLzvij4iU22sg_NBaEF}CRt)|uMi?N zWEo2+W#8AqwPmt~af#dg2Y$Z?=e*C;^Lg-j9nwt;EGIjX9RL7M6Jw0kFB1L}9QMoG zbzFM@fGx}fgSH6+ea|z$Zez#a)h7Z|WRFRbm(MEb=tIDiYP+7&?~| zx|to0C$+L!c59x7_tmfDhUXiWkIx)pM`hPpYOGn6dIDq&5V$4(p5C!h#UHw#J@YG> zsRv}geUsfUZb1?gW-l`fAHP{$cQY^3eL1z`b||GJf`2!jUVEV~?+g;RlyuKm7n9zG zt%z`s$g9>IOfrjP=G4h)jyNigYM&#7v&t7j8}o;^(fyGCYh4aj1yj7du~ zQB^P;I6fI@FNxHNjh=}vGE)JcC$1b20doJ?RCSwqX(})68lC!na+6%Nt|vA_?UhqD zwnl)6p6^C)9=%(NpUXUSnHw6qV%|5dwiiK?l}*}Md6>(jMwz#`a2@CLkdbTjdBNgq z6;Ob<`K|O3OLeHGuboh%C{KIGq9Ib)xgg^WSUbnjX*)7^cWn1)i5l`#Vu4WiVYhF` z46TZL0C7s7E$+PMX@5QcJF-uZjr;HA{=4(1NBdg}4JsODqBt18vRSpd%h_&+n2eE!dJ>(LLXyZN@Rarw9c(-~gMIF|y7C+<& za1?|}U{<2iuLaCyg`73j)NC8!GL7cjYQOBm=9K<|y>s-mJx?}~{dlX1l_M2kFFX-T z&FNM#LV#mK6W2`i%76_nb*$shu&ou?T}kXbHqZY!wl=efT4+5pR0u5v54r&r&F4F@ zkkng(UA$**(YVu^BHBG;qkZG6)j+t9q(OXCRwdWR+xM|W-PkUdhHWA|K|$k6oGC9L z{&e+Q{PyNd)t3noPaH#@BB^3t2x{HG7?TrL?=sQBf!T7{e0y|RaU4n&^D2Sk=4Q8U z%Nz$yPeomzbMTfA=E-z8OW#<&)xOpcfuew z>+7RCpw-qWE2B&-Ok*sG0nW8xA#u>wC%D-oTE0Mfy6wZZJujIKkApK-?C{&vDa%f2{dB% zW961F*S0kxP~FfaX8?QYy5mH2z4#rF&4b%$6C1$t^Xp4&Q%CCV5FQEnV%zpkW%OO{ zQhf^e`SUXp{Y^u%2gXmRGK~6JDuM4ho0`Qt6N@rNP@V!LaSMVaGtSB-wLRM zlB#tt5InTa7Jv-oQHFsC-|O1Nh8OUf$AXxQUtex`JX%v# zIvSK*vJ560glxvZtssCp>Y;6%0u8rpnh3m}p`_$F-DUYFLlO`=-QUt8(JkhKG5z8} zG4P4z=8MSbo_tB%URqAMYis=@uR9v(Hocp27CGgCy8^>6Az4a2j!mJ5uO(90gU0U(^sAK;OkJg zZuyP%iXiL8K+b%I#B)zgd7}oPUn_9;u{DDvF71A-3_I0rc(izORVCsS=;IC4BRRAN zQo+Kw^{x~*i;~JOsmP+v7E0S`+P_coNw$XrIC`Um<;I0*t3+ZQ(@>&%JRY>2;`pgG=Jix&N3^p z%5w~n416Xa(#$SMk}+daq}DOC3fP_nv+um=pHO$dpF8>GFn#@DHG)89l6;ZzEe`xM zZO`PVOFbfJw!p^GlRTfP9g#MH8Os1>Vh2~Ic1bMAKwYiaRyrk9Xp3<#i|g?RC>h--y#WS7{B?(uvtA2)8Z1<(<{B`be`rHPp?ouIS8^h>E?Dbi&v zw)rK%w33S}MJ-dB(+m`L;$m3+t%~dGoBE5m5W;iX@LADqDrW*t4q)P+y-;{F^T9#; zPqM)To8GgLv{iAtNh)%dm>}a@n)({75I=#QA#AzSc{Aj0FY2o*xL;HX_OW+CY1LH6Fe{RL z#?kF|Dxg@?B1g;`9xeXIS~smJul7?j2KJipRbuI#)*~YAWAIl8Nrf9QrE2fB_eNvO zRX0F~(^-Na-`34BAS2v Date: Tue, 14 Jul 2026 08:30:31 -0700 Subject: [PATCH 3/3] refactor: consolidate Codex skill overrides --- skills/connect-glean/SKILL.md | 45 ++-- skills/connect-glean/targets/codex/SKILL.md | 71 ------- skills/project-handoff/SKILL.md | 18 +- skills/project-handoff/targets/codex/SKILL.md | 201 ------------------ 4 files changed, 42 insertions(+), 293 deletions(-) delete mode 100644 skills/connect-glean/targets/codex/SKILL.md delete mode 100644 skills/project-handoff/targets/codex/SKILL.md diff --git a/skills/connect-glean/SKILL.md b/skills/connect-glean/SKILL.md index ac3ad2e..e20dfaf 100644 --- a/skills/connect-glean/SKILL.md +++ b/skills/connect-glean/SKILL.md @@ -5,11 +5,10 @@ description: Help the user connect a Glean MCP server so the Glean skills have t # Connect Glean -The Glean plugin ships skills and agents but **does not bundle an MCP server** — -the skills call whatever Glean MCP tools the host exposes. If no Glean MCP server -is connected, the skills have nothing to call. This skill connects one, or -verifies and troubleshoots an existing connection. Follow the section for the -user's host. +The Glean plugin ships skills but **does not bundle an MCP server** — the skills +call whatever Glean MCP tools the host exposes. If no Glean MCP server is +connected, the skills have nothing to call. This skill connects one, or verifies +and troubleshoots an existing connection. Follow the section for the user's host. ## When this applies @@ -31,8 +30,8 @@ Gather these once, then apply them in the host-specific step: `glean-code`). The MCP endpoint is always `/mcp/`. It is a **remote -HTTP** server, and the host prompts for **OAuth on first tool use** — there is no -API key to paste. **Restart the host** after configuring. +HTTP** server and uses OAuth — there is no API key to paste. Follow the +host-specific authentication and reload steps below. ## Claude Code @@ -45,6 +44,18 @@ claude mcp add /mcp/ --transport http - Verify with `claude mcp list` (look for a `glean.com/mcp` URL). Restart Claude Code; authenticate on first use. +## Codex + +Run: + +```bash +codex mcp add --url /mcp/ +codex mcp login +``` + +Complete the browser OAuth flow, then verify with `codex mcp list` (look for a +`glean.com/mcp` URL). Start a new Codex task so the MCP tools are available. + ## Cursor Add an entry to `~/.cursor/mcp.json`: @@ -70,14 +81,17 @@ config lives and the exact field names. ## Checking status / troubleshooting "no Glean tools" -If the Glean skills run but report missing tools, the host has no Glean MCP server -connected for the current session: +If the Glean skills run but report missing tools, the host has no usable Glean +MCP server in the current session or task: -1. Confirm a server is configured (Claude Code: `claude mcp list`; other hosts: - check the MCP config above for a `glean.com/mcp` URL). -2. If none, run the host setup above. -3. If configured but tools are still missing: restart the host, then trigger - OAuth by running any Glean tool once. +1. Confirm a server is configured: use `claude mcp list` in Claude Code, + `codex mcp list` in Codex, or inspect the host's MCP config for a + `glean.com/mcp` URL. +2. If none is configured, run the host setup above. +3. If Codex is configured but not authenticated, run + `codex mcp login `, then start a new task. +4. In other hosts, restart the host and trigger OAuth by running any Glean tool + once. ## Glean developer docs server (separate, optional) @@ -86,6 +100,9 @@ name, or auth needed: - **Claude Code:** `claude mcp add glean-dev-docs https://developers.glean.com/mcp --transport http --scope user` +- **Codex:** + `codex mcp add glean-dev-docs --url https://developers.glean.com/mcp`, then + start a new task. - **Other hosts:** register `https://developers.glean.com/mcp` as a remote HTTP MCP server (no OAuth required). diff --git a/skills/connect-glean/targets/codex/SKILL.md b/skills/connect-glean/targets/codex/SKILL.md deleted file mode 100644 index 790eacb..0000000 --- a/skills/connect-glean/targets/codex/SKILL.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -name: connect-glean -description: Help the user connect a Glean MCP server so the Glean skills have tools to call — use when setting up Glean for the first time, adding another Glean server, checking whether Glean is connected, or troubleshooting missing Glean tools. Trigger phrases include "set up Glean", "connect Glean", "configure Glean MCP", "add a Glean server", "is Glean connected", "check Glean status", "Glean isn't working", "no Glean tools", "the Glean tools aren't showing up", "I installed the Glean plugin but nothing happens". Don't use it for actual enterprise queries once connected (use the using-glean skill); this skill only sets up and verifies the connection. ---- - -# Connect Glean - -The Glean plugin ships skills but **does not bundle an MCP server** — the skills -call whatever Glean MCP tools Codex exposes. If no Glean MCP server is connected, -the skills have nothing to call. This skill connects one, or verifies and -troubleshoots an existing connection. - -## When this applies - -- **First-time setup** — the Glean plugin is installed but no Glean tools appear. -- **Adding another server** — e.g. a second backend or a code-search server. -- **Status / troubleshooting** — "is Glean connected?", "no Glean tools showing". - -## What you need first - -Gather these once, then use them in the Codex setup below: - -1. **Server URL** — the Glean backend, found at - . Looks like - `https://acme-be.glean.com` or `https://be-4f5226e2.glean.com`. -2. **Server name** — organization-specific, from the user's Glean admin. Often - `default`. -3. **Friendly name** — what to call it in the host. Use `glean` for a single - server, or `glean-` when adding several (e.g. `glean-default`, - `glean-code`). - -The MCP endpoint is always `/mcp/`. It is a **remote -HTTP** server and uses OAuth — there is no API key to paste. - -## Configure Codex - -Run: - -```bash -codex mcp add --url /mcp/ -codex mcp login -``` - -Complete the browser OAuth flow, then verify with `codex mcp list` (look for a -`glean.com/mcp` URL). Start a new Codex task so the MCP tools are available. - -## Checking status / troubleshooting "no Glean tools" - -If the Glean skills run but report missing tools, Codex has no usable Glean MCP -server in the current task: - -1. Run `codex mcp list` and look for a `glean.com/mcp` URL. -2. If none is configured, run the setup above. -3. If it is configured but not authenticated, run - `codex mcp login `. -4. Start a new Codex task after configuration or authentication. - -## Glean developer docs server (separate, optional) - -The `glean-dev-docs` plugin uses a **different, public** server — no Glean -account or OAuth is required: - -```bash -codex mcp add glean-dev-docs --url https://developers.glean.com/mcp -``` - -Start a new Codex task after adding it. - -## Related skills - -- **using-glean** — once connected, drives enterprise search, Q&A, and synthesis. diff --git a/skills/project-handoff/SKILL.md b/skills/project-handoff/SKILL.md index 0abdc1b..b437f79 100644 --- a/skills/project-handoff/SKILL.md +++ b/skills/project-handoff/SKILL.md @@ -17,11 +17,13 @@ status reads). Use that one if the user just wants current status. ## Tools -This skill drives the standard Glean MCP tools and spawns the -`project-synthesizer` agent. For the param shape and pitfalls of `search`, -`chat`, `meeting_lookup`, and `employee_search`, see the using-glean reference -at `using-glean/reference/`. If no Glean tools are visible, the user hasn't -connected a Glean MCP server for this host — point them at their host's setup. +This skill drives the standard Glean MCP tools. If the host exposes the +`project-synthesizer` agent, use it for project research. Otherwise delegate to +a suitable research subagent when subagents are available, or gather the same +material directly. For the param shape and pitfalls of `search`, `chat`, +`meeting_lookup`, and `employee_search`, see the using-glean reference at +`using-glean/reference/`. If no Glean tools are visible, point the user to the +**connect-glean** skill. ## Core Principles @@ -38,8 +40,10 @@ Understand the project's current state. 1. Ask the user for handoff context: - Their role on the project (Owner/Lead, Contributor, Advisor/Stakeholder) - What's driving the handoff (new role/team, PTO coverage, reorg, leaving) -2. Spawn the `project-synthesizer` agent to gather documentation, people and - their roles, recent meetings and decisions, and current status / open items. +2. Use `project-synthesizer` when available; otherwise delegate to a suitable + research subagent if possible, or gather the material directly. Cover + documentation, people and their roles, recent meetings and decisions, and + current status / open items. ## Phase 2: Gather undocumented knowledge diff --git a/skills/project-handoff/targets/codex/SKILL.md b/skills/project-handoff/targets/codex/SKILL.md deleted file mode 100644 index 2492643..0000000 --- a/skills/project-handoff/targets/codex/SKILL.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -name: project-handoff -description: Generate a comprehensive handoff document so someone new can take over a project — current state, key people, essential knowledge, open items, and a first-30-days plan. Use when the user is handing off a project (trigger phrases include "generate a handoff", "hand off this project", "create a handoff doc", "I'm going on PTO / leaving / changing teams and need to document", "help someone take over") rather than a quick status read (use project-awareness for that). ---- - -# Project Handoff - -Generate a comprehensive handoff document so someone new can take over a -project. Gather everything they'd need: current state, the people who matter, -tribal knowledge, open items, and a concrete ramp-up plan. - -Determine the project from the user's request. If no project is clear, ask -which project they mean before proceeding. - -This is the heavyweight counterpart to the **project-awareness** skill (quick -status reads). Use that one if the user just wants current status. - -## Tools - -This skill drives the standard Glean MCP tools. If Codex exposes subagent tools, -delegate project research to a general research subagent; otherwise gather the -same material directly in the current task. For the param shape and pitfalls of -`search`, `chat`, `meeting_lookup`, and `employee_search`, see the using-glean -reference at `using-glean/reference/`. If no Glean tools are visible, the user -hasn't connected a Glean MCP server — point them at the Codex setup instructions. - -## Core Principles - -- **Complete context**: include everything needed to take over -- **Actionable items**: clear next steps and open items -- **Tribal knowledge**: capture what's not in docs -- **Be skeptical**: not every doc found is relevant to a handoff -- **Quality over quantity**: focus on what the new owner actually needs - -## Phase 1: Gather current context - -Understand the project's current state. - -1. Ask the user for handoff context: - - Their role on the project (Owner/Lead, Contributor, Advisor/Stakeholder) - - What's driving the handoff (new role/team, PTO coverage, reorg, leaving) -2. If subagent tools are available, delegate the research to a general subagent. - Otherwise gather it directly. Cover documentation, people and their roles, - recent meetings and decisions, and current status / open items. - -## Phase 2: Gather undocumented knowledge - -Capture tribal knowledge not in formal docs. Ask the current owner: - -- "What's the #1 thing someone taking over needs to know?" -- "What are the biggest risks or gotchas?" -- "What relationships are critical to maintain?" -- "What recurring tasks or ceremonies exist?" -- "What access/permissions are needed?" -- "What decisions are pending?" - -## Phase 3: Identify open items - -1. Search for open work: `search "[project] TODO OR action item OR blocked OR in progress"` -2. Check recent commitments: `meeting_lookup "[project]"` over the past ~2 weeks (extract transcript) -3. Synthesize: `chat "What are the open action items, pending decisions, and blockers for [project]?"` -4. Categorize: Immediate (1-2 weeks), Upcoming (next month), Future (backlog). - -## Phase 4: Vet all content (CRITICAL) - -Filter to what's genuinely needed — be skeptical. - -**Handoff relevance** — ✅ essential / 📚 reference / ❌ skip (historical, tangential) -**Currency** — ✅ current / ⚠️ aging (note it) / ❌ stale (exclude) -**Actionability** — ✅ action needed / 📋 awareness only / ❌ FYI - -For each person: are they still relevant, what's the real relationship, why -would the new owner need them? For each open item: is it actually still open, -is it the new owner's responsibility, what's the real urgency? - -## Phase 5: Generate the handoff document - -```markdown -# Project Handoff: [Project Name] - -**Prepared by**: [Current owner] -**Date**: [Today's date] -**Reason for handoff**: [From Phase 1] - -## Content Quality -| Category | Items Found | Included | Reason for Filtering | -|----------|-------------|----------|----------------------| -| Documents | [X] | [Y] | [Z] historical/tangential | -| People | [X] | [Y] | [Z] no longer relevant | -| Open Items | [X] | [Y] | [Z] already resolved | - -## Executive Summary -[3-4 paragraphs: what the project is, where it stands, critical context for success, most important next steps] - -## Project Overview -### What This Project Is -[Purpose and scope] -### Why It Exists -[Business context, problem being solved] -### Current Status -| Attribute | Value | -|-----------|-------| -| **Phase** | [Planning/In Progress/Launch Prep/etc.] | -| **Health** | [Green/Yellow/Red] - [Why] | -| **% Complete** | [Estimate] | -| **Target Date** | [Date] | - -## People & Relationships (Vetted) -### Key Contacts (must maintain these relationships) -| Person | Role | Relationship | How to Engage | Why Critical | -|--------|------|--------------|---------------|--------------| -| [Name] | [Role] | [Critical/Important] | [Best approach] | [Specific reason] | -### Stakeholders to Keep Updated -- [Name/Group] - [What they care about] - [How often] -### Not Included -| Person | Reason | -|--------|--------| -| [Name] | Historical involvement only | - -## Essential Knowledge -### The #1 Thing to Know -[Critical context from current owner — from Phase 2] -### Key Decisions Made (that still matter) -| Decision | When | Why | Implications | -|----------|------|-----|--------------| -| [Decision] | [Date] | [Rationale] | [What this means for new owner] | -### Risks & Gotchas -| Risk | Likelihood | Impact | Mitigation | -|------|------------|--------|------------| -| [Risk] | H/M/L | H/M/L | [How to handle] | -### What's Not Documented -[Tribal knowledge that only exists in people's heads] - -## Documentation Guide (Vetted) -### Must-Read Docs (in order) -1. **[Doc Title]** ([link]) — why essential, ~[X] min, last updated [date] -### Reference When Needed -- **[Doc Title]** — [when you'd need it] -### Skipped Documents -| Doc | Reason | -|-----|--------| -| [Title] | Historical — superseded by [other doc] | -### Where Things Live -| Resource | Location | Access Needed | -|----------|----------|---------------| -| [Code] | [Repo link] | [Permissions] | - -## Open Items (Vetted) -### Immediate (Next 2 Weeks) -| Item | Status | Deadline | What To Do | Notes | -|------|--------|----------|------------|-------| -| [Item] | [Status] | [Date] | [Specific action] | [Context] | -### Pending Decisions -| Decision | Options | Who Decides | Deadline | -|----------|---------|-------------|----------| -| [Decision] | [A, B, C] | [Person] | [Date] | -### Blockers -| Blocker | Impact | Who Can Unblock | -|---------|--------|-----------------| -| [Blocker] | [Impact] | [Person] | - -## Operations -### Recurring Tasks -| Task | Frequency | When | How | -|------|-----------|------|-----| -| [Task] | [Weekly/etc.] | [Day/time] | [Instructions] | -### Meetings to Attend -| Meeting | Frequency | Purpose | Your Role | -|---------|-----------|---------|-----------| -| [Meeting] | [Frequency] | [Purpose] | [What to do] | -### Access & Permissions Needed -- [ ] [System/tool] — request from [person/team] - -## First 30 Days -### Week 1: Orientation -- [ ] Read essential docs (above) -- [ ] Meet with [key contact] -- [ ] Get access to [systems] -### Week 2: Immersion -- [ ] Take ownership of [first item] -- [ ] Attend [key meeting] -### Week 3-4: Transition -- [ ] Lead [responsibility] -- [ ] Make decision on [pending item] - -## Questions? -Contact [current owner] until [date]. After that, [backup person]. -``` - -## Troubleshooting - -- **Sparse information**: lean on the Phase 2 tribal-knowledge questions, mark - gaps clearly, and don't pad with marginally relevant docs. -- **Owner unavailable**: generate from available documentation, mark - "Needs Input" on sections requiring owner knowledge, and note limitations at - the top. - -## Related Skills - -- **project-awareness** — quick status read (lighter weight) -- **onboarding** — get up to speed on a team or area