From efbe364da02aab5dc7d061b34ff7998fb238631d Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Fri, 12 Jun 2026 16:29:17 -0700 Subject: [PATCH] chore: add agent baseline (AGENTS.md, skill, CI drift check) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Onboards this repo to the gleanwork agent baseline via @gleanwork/configure-agents: - Add AGENTS.md (agent instructions, with the real Bun-based dev commands) and a thin CLAUDE.md pointer. - Add skills/SKILL.md teaching a consuming AI how to use the glean-mdm CLI — fleet provisioning of the Glean editor extension and MCP server config across AI coding tools on managed devices. It points at the CLI --help and the command/schema definitions rather than transcribing flags. - Add a CI workflow that drift-checks the baseline structure on every PR. - Add a skills-install block to the README. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/agent-baseline.yml | 16 ++++++++ AGENTS.md | 18 +++++++++ CLAUDE.md | 5 +++ README.md | 14 +++++++ skills/SKILL.md | 56 ++++++++++++++++++++++++++++ 5 files changed, 109 insertions(+) create mode 100644 .github/workflows/agent-baseline.yml create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 skills/SKILL.md diff --git a/.github/workflows/agent-baseline.yml b/.github/workflows/agent-baseline.yml new file mode 100644 index 0000000..4a7dd4e --- /dev/null +++ b/.github/workflows/agent-baseline.yml @@ -0,0 +1,16 @@ +name: agent-baseline + +on: + pull_request: + push: + branches: [main] + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '20' + - run: npx -y @gleanwork/configure-agents@latest check diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b787eed --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,18 @@ +# AGENTS.md + +Agent instructions for `@gleanwork/glean-mdm`. Human-facing documentation lives in `README.md`; this file is the entry point for AI coding agents working in this repository. + +## Development + +Runtime is **Bun** (version pinned in `mise.toml`). See `README.md` for the full workflow. + +- Install dependencies: `bun install` +- Run the CLI from source: `bun run src/index.ts -- --help` (e.g. `bun run src/index.ts -- run --dry-run --user $(whoami)`) +- Run tests: `bunx vitest run` +- Build cross-platform binaries: `./build.sh` + +## Skills + +This repository ships an agent skill at `skills/SKILL.md` that teaches a consuming AI how to use `@gleanwork/glean-mdm` correctly. It is distributed via `skills.sh`. + +When working in this repository, consult `skills/SKILL.md` and keep it accurate as the public API changes. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0a198e9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,5 @@ +# CLAUDE.md + +This repository's agent instructions live in **AGENTS.md**. Read it first. + +@AGENTS.md diff --git a/README.md b/README.md index e45b256..87ec1f8 100644 --- a/README.md +++ b/README.md @@ -138,3 +138,17 @@ git push origin v1.0.0 ``` This builds cross-platform binaries (macOS arm64/x64, Linux arm64/x64, Windows x64) and publishes them as GitHub release assets. + + + +## Agent skills + +This repository ships agent skill(s) under `skills/`. Install them into your +AI agent with [`npx skills`](https://github.com/agentskills/agentskills): + +```sh +npx skills add -g gleanwork/glean-mdm # global — available in every repo +npx skills add gleanwork/glean-mdm # or scoped to the current repo +``` + + diff --git a/skills/SKILL.md b/skills/SKILL.md new file mode 100644 index 0000000..bdb99bf --- /dev/null +++ b/skills/SKILL.md @@ -0,0 +1,56 @@ +--- +name: glean-mdm +description: Use the glean-mdm CLI to provision Glean's AI-coding-tool integration on managed devices (IT/MDM fleet tooling) — install the Glean editor extension and configure MCP servers across supported AI coding tools for every user on a machine, on a system schedule. Load when operating, scripting, or troubleshooting glean-mdm on a managed device. +--- + +# glean-mdm + +A system-level CLI for IT/MDM administrators that provisions Glean's AI-coding-tool integration across every user on a managed machine. On each run it installs the Glean editor extension into supported editors, merges the organization's Glean MCP server entry into each tool's config (preserving existing settings), and self-updates. It runs unattended via the OS scheduler (launchd / systemd / Task Scheduler). + +## When to use + +Load this skill when operating, scripting, or troubleshooting `glean-mdm` on a managed device — generating its config files, installing/removing the system schedule, or running the per-user provisioner. This is **fleet** tooling, run by an admin (typically as root) to set up *all* users on a machine. It is broader than MCP setup: configuring MCP servers is one of its jobs, alongside installing the Glean editor extension. For a single developer configuring their own MCP clients interactively, that's `@gleanwork/configure-mcp-server`, not this. + +## Install & import + +`glean-mdm` is distributed as a self-contained per-platform binary (built from this repo via `./build.sh` and shipped as GitHub release assets, deployed by your MDM). It is not an npm import. Invoke the command directly: + +```bash +glean-mdm --help +``` + +The set of supported editors/tools and their config-file paths is not defined here — it comes from the [`@gleanwork/mcp-config-glean`](https://www.npmjs.com/package/@gleanwork/mcp-config-glean) registry (Claude Code, Cursor, VS Code, Windsurf, Goose, Codex, …). + +## Authoritative API + +The command surface is the source of truth, not any prose. Read it rather than guessing flags: + +- `glean-mdm --help` and each subcommand's `--help` (`run`, `config`, `install-schedule`, `uninstall-schedule`, `uninstall`) +- the commander definitions and the `CliOptions` interface in `src/index.ts` +- the config-file schemas (`McpConfigSchema`, `MdmConfigSchema`) in `src/config.ts`, and the documented shapes in `README.md` + +Don't transcribe the flag or schema lists — they drift. Check `--help` and the Zod schemas for the exact options. + +## Usage patterns + +The normal admin workflow is **config → install-schedule → run**: + +- **`config`** generates two files into the platform default directory (override with `--output-dir`): + - `mcp-config.json` — the MCP server(s) to provision (`serverName`, `url`). + - `mdm-config.json` — the binary's own update behavior (`autoUpdate`, `versionUrl`, `binaryUrlPrefix`, `pinnedVersion`). +- **`install-schedule`** registers the system runner (launchd / systemd / Task Scheduler); `uninstall-schedule` removes it; `uninstall` removes everything (schedule, config, logs, binary). +- **`run`** does the per-user work: for each local user it installs the Glean editor extension, configures the MCP server entry in each supported host tool, then checks for a self-update. Run it as root/admin so it can enumerate all users and write their configs. +- **Always dry-run first:** `glean-mdm run --dry-run [--user ]` previews changes; scope to one user with `--user`. Point at explicit configs with `--mcp-config` / `--mdm-config`. +- **Self-update** runs before the work unless suppressed; logs go to the platform log file (e.g. `/var/log/glean-mdm.log`), rotated at 10 MB. + +## Common mistakes + +- **Running `run` without admin/root** — it must enumerate all local users and write per-user configs and extensions; unprivileged runs fail or no-op. +- **Treating it as MCP-only** — `run` also installs the Glean editor extension; it's a general provisioning agent, not just an MCP config writer. +- **Confusing it with `configure-mcp-server`** — that's single-user interactive MCP setup; `glean-mdm` is unattended fleet provisioning across all users. +- **`autoUpdate: true` without a `versionUrl`** — auto-update needs the version endpoint to check against. +- **Skipping `--dry-run`** before a real run on a fleet machine, or **hand-editing tool config files** instead of letting `run` merge (it preserves existing settings). + +## Version notes + +Check the running version with `glean-mdm --version`. Binaries self-update against the `mdm-config.json` `versionUrl` (set `pinnedVersion` to opt out) and are built per-platform via `./build.sh`, published as GitHub release assets on a version tag. Don't hardcode a version — read it from the binary.