From e0162d0353a2be4cf2cf7d04158db098b815151e Mon Sep 17 00:00:00 2001 From: Gale W Date: Sat, 18 Apr 2026 21:19:49 -0400 Subject: [PATCH] docs: Update socket docs and bump subtree versions --- README.md | 13 ++- ROADMAP.md | 7 +- docs/maintainers/plugin-packaging-strategy.md | 3 + docs/maintainers/subtree-workflow.md | 1 + .../.codex-plugin/plugin.json | 4 +- plugins/agent-plugin-skills/AGENTS.md | 92 +++++++++++++-- plugins/agent-plugin-skills/CONTRIBUTING.md | 110 ++++++++++++++++++ plugins/agent-plugin-skills/README.md | 87 ++++++++------ plugins/agent-plugin-skills/ROADMAP.md | 101 +++++++++++----- .../codex-plugin-install-surfaces.md | 33 ++++-- .../docs/maintainers/reality-audit.md | 2 +- .../docs/maintainers/workflow-atlas.md | 2 +- plugins/agent-plugin-skills/pyproject.toml | 2 +- .../bootstrap-skills-plugin-repo/SKILL.md | 22 +++- .../agents/openai.yaml | 2 +- .../skills/sync-skills-repo-guidance/SKILL.md | 20 +++- .../references/sync-checklist.md | 2 +- .../scripts/sync_skills_repo_guidance.py | 27 ++++- .../tests/test_sync_skills_repo_guidance.py | 18 ++- plugins/agent-plugin-skills/uv.lock | 2 +- pyproject.toml | 2 +- uv.lock | 2 +- 22 files changed, 438 insertions(+), 116 deletions(-) create mode 100644 plugins/agent-plugin-skills/CONTRIBUTING.md diff --git a/README.md b/README.md index abdfd727..3130605a 100644 --- a/README.md +++ b/README.md @@ -19,11 +19,11 @@ Mixed-model monorepo for Gale's Codex plugin and skills repositories. ### Status -This repository is active and maintained as the superproject layer. +This repository is active and maintained as the superproject coordination layer. ### What This Project Is -`socket` is the superproject Gale uses to keep several Codex plugin and skills repositories under one Git root while OpenAI's documented Codex plugin system still lacks a better shared-parent scoping model. It owns the repo-root Codex marketplace at [`.agents/plugins/marketplace.json`](./.agents/plugins/marketplace.json), the monorepo-owned nested plugin directories under [`plugins/`](./plugins/), the remaining subtree sync paths for `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer`, and the root maintainer docs that explain how the mixed model works. +`socket` is the superproject Gale uses to keep several Codex plugin and skills repositories under one Git root while OpenAI's documented Codex plugin system still lacks a better shared-parent scoping model. It owns the repo-root Codex marketplace at [`.agents/plugins/marketplace.json`](./.agents/plugins/marketplace.json), the monorepo-owned child directories under [`plugins/`](./plugins/), the remaining subtree sync paths for `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer`, and the root maintainer docs that explain how the mixed model works. ### Motivation @@ -55,6 +55,7 @@ Use `socket` when the task is about the superproject layer: - mixed monorepo policy - subtree sync flow for `apple-dev-skills`, `python-skills`, or `SpeakSwiftlyServer` - cross-repo maintainer guidance +- coordinated release-prep work that needs the root docs and child version surfaces to stay in sync When the work is really about one child repository's own behavior, start from that child directory's docs instead. @@ -68,13 +69,13 @@ Sync the root maintainer environment with: uv sync --dev ``` -Only `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer` still use subtree sync workflows. +Only `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer` still use subtree sync workflows. `socket` itself does not ship a root plugin; the marketplace is the root packaged surface here. ### Workflow Treat Gale's local `socket` checkout as the normal day-to-day checkout on `main`. Work in the monorepo copy first, and use the relevant directory under [`plugins/`](./plugins/) for child-repository changes unless the task is explicitly about the root marketplace or root maintainer docs. Reach for a feature branch or a dedicated worktree only when the change needs extra isolation. -Keep root docs and marketplace wiring in sync with packaging changes in the same pass. For monorepo-owned child directories, edit the relevant directory under [`plugins/`](./plugins/) directly and commit in `socket`. For `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer`, keep subtree sync operations explicit and isolated. +Keep root docs and marketplace wiring in sync with packaging changes in the same pass. For monorepo-owned child directories, edit the relevant directory under [`plugins/`](./plugins/) directly and commit in `socket`. For `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer`, keep subtree sync operations explicit and isolated. When a release-prep pass bumps subtree-managed child versions, update the child repo metadata in `socket` and keep the corresponding child docs aligned at the same time. Use [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the maintainer workflow boundary and [`ROADMAP.md`](./ROADMAP.md) for root planning and historical notes. @@ -136,7 +137,7 @@ The root superproject docs are: ## Plugin Surfaces -Treat `socket` as the canonical home for the monorepo-owned nested directories and as the subtree host for the remaining imported child repos. +Treat `socket` as the canonical home for the monorepo-owned child directories and as the subtree host for the remaining imported child repos. - `agent-plugin-skills`, `dotnet-skills`, `productivity-skills`, `rust-skills`, `things-app`, and `web-dev-skills` are monorepo-owned here. - `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer` preserve explicit subtree sync paths. @@ -161,4 +162,4 @@ That marketplace points at the actual packaged surface each child repository tre For `things-app`, that root marketplace path stays the same after the bundled-server move because the installable plugin root is still `./plugins/things-app`; only the child repo's internal server layout changed, from `mcp/things-app-mcp/` to top-level `mcp/`. -The mixed shape is intentional for now. `socket` does not try to flatten those child repo packaging models into one fake uniform layout. +The mixed shape is intentional for now. `socket` does not try to flatten those child repo packaging models into one fake uniform layout, and it does not define a second aggregate Codex plugin root above the child repos. diff --git a/ROADMAP.md b/ROADMAP.md index faeeab12..619c05ae 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -23,13 +23,13 @@ ## Milestone Progress - Milestone 2: subtree workflow hardening - Planned -- Milestone 3: release and sync discipline - Planned +- Milestone 3: release and sync discipline - In Progress ## Milestone 2: subtree workflow hardening ### Status -Planned +In Progress ### Scope @@ -56,10 +56,13 @@ Planned ### Tickets - [ ] Document the expected root release and sync rhythm once the current subtree migration experiment stabilizes. +- [ ] Keep the root docs aligned with the current child packaging model during coordinated release-prep passes. +- [ ] Make coordinated minor or patch bumps across `socket` and subtree-managed child repos explicit instead of relying on ad hoc release notes. ### Exit Criteria - [ ] Superproject release guidance is explicit enough that root changes can be shipped without improvising process each time. +- [ ] Root docs still describe the live packaging and versioning model after a coordinated release-prep pass. ## Backlog Candidates diff --git a/docs/maintainers/plugin-packaging-strategy.md b/docs/maintainers/plugin-packaging-strategy.md index c11daed4..23e37cee 100644 --- a/docs/maintainers/plugin-packaging-strategy.md +++ b/docs/maintainers/plugin-packaging-strategy.md @@ -34,9 +34,12 @@ The current direction is: 2. import them into `socket/plugins/` as subtrees 3. keep the `socket` marketplace ready to list each plugin independently 4. only add marketplace entries for child repos that actually ship `.codex-plugin/plugin.json` +5. keep root `socket` docs aligned with child packaging moves and coordinated release-prep changes instead of treating the marketplace file as the only source of truth Child-repo internal layout changes do not automatically imply root marketplace changes. If a child repo keeps the same packaged plugin root, keep the `socket` marketplace path stable and only update the root docs to explain the child's new internal layout. Recent example: `things-app` kept its marketplace path at `./plugins/things-app` while moving its bundled MCP server from `mcp/things-app-mcp/` to top-level `mcp/` inside that child repo. +`socket` itself still does not define an aggregate root plugin above the child repos. The root packaged surface here is the marketplace catalog, not a second shared plugin bundle. + ## Follow-up Decision Once several child repos have stable plugin packaging, decide whether `socket` needs: diff --git a/docs/maintainers/subtree-workflow.md b/docs/maintainers/subtree-workflow.md index 0b2fb6bb..62960261 100644 --- a/docs/maintainers/subtree-workflow.md +++ b/docs/maintainers/subtree-workflow.md @@ -73,6 +73,7 @@ After subtree work: - verify the directory shape under `plugins/apple-dev-skills/`, `plugins/python-skills/`, or `plugins/SpeakSwiftlyServer/` - update socket docs and marketplace wiring in a separate focused commit when needed +- if the subtree work is part of a coordinated release-prep pass, keep the child repo version metadata and child docs aligned before pushing the subtree back out ## Add A New Subtree-Managed Child Repository diff --git a/plugins/agent-plugin-skills/.codex-plugin/plugin.json b/plugins/agent-plugin-skills/.codex-plugin/plugin.json index 4170001c..ac26f1f5 100644 --- a/plugins/agent-plugin-skills/.codex-plugin/plugin.json +++ b/plugins/agent-plugin-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agent-plugin-skills", - "version": "1.2.2", + "version": "1.3.0", "description": "Installable maintainer skills for skills-export repositories.", "author": { "name": "Gale", @@ -20,7 +20,7 @@ "interface": { "displayName": "Agent Plugin Skills", "shortDescription": "Maintainer skills for skills-export repositories.", - "longDescription": "Installable maintainer skills for skills-export repositories, with blunt guidance about Codex plugin scoping limits and repo-shape maintenance workflows.", + "longDescription": "Installable maintainer skills for skills-export repositories, with clear guidance about Codex plugin boundaries and repo-shape maintenance workflows.", "developerName": "Gale", "category": "Developer Tools", "capabilities": [ diff --git a/plugins/agent-plugin-skills/AGENTS.md b/plugins/agent-plugin-skills/AGENTS.md index 2ff4d932..59c0193a 100644 --- a/plugins/agent-plugin-skills/AGENTS.md +++ b/plugins/agent-plugin-skills/AGENTS.md @@ -1,15 +1,87 @@ # AGENTS.md -## Repository Role +Use this file for durable repo-local guidance that Codex should follow before changing code, docs, or workflow surfaces in this repository. -- This repository is the canonical home for maintainer skills that target skills-export and plugin-export repositories. -- Treat `productivity-skills` as the default baseline maintainer layer for general repo docs and workflow guidance; this repo is the narrower specialist layer for exported-skill and exported-plugin repo shapes. -- Root `skills/` is the canonical authored and exported surface. -- This repo ships source-repo plugin packaging at [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json) and intentionally does not keep a repo-local Codex marketplace file for itself. +## Repository Scope -## Repo-specific Rules +### What This File Covers -- Keep Codex limitation wording blunt. When this repo discusses Codex plugin export boundaries, say plainly that repo-visible plugins come from the documented marketplace model rather than from a richer repo-private scoping system. -- Do not recreate nested staged plugin directories, repo-local installer workflows, or install-surface validation machinery in this repository unless Gale explicitly asks for that reversal. -- Keep repo-maintainer docs under [`docs/maintainers/`](./docs/maintainers/), and keep installed skills independent from those docs. -- Keep `docs/maintainers/reality-audit.md` and `docs/maintainers/workflow-atlas.md` aligned with the shipped maintainer-skill surface. +- `agent-plugin-skills` is the canonical home for maintainer skills that target skills-export and plugin-export repositories. +- This root file governs the repo-wide maintainer docs, the source-first plugin packaging surface at [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json), and the authored skill surface under [`skills/`](./skills/). + +### Where To Look First + +- Start with [README.md](./README.md), [CONTRIBUTING.md](./CONTRIBUTING.md), and [ROADMAP.md](./ROADMAP.md). +- For Codex packaging or install-surface questions, read [`docs/maintainers/codex-plugin-install-surfaces.md`](./docs/maintainers/codex-plugin-install-surfaces.md). +- For current repo-shape and inventory expectations, read [`docs/maintainers/reality-audit.md`](./docs/maintainers/reality-audit.md) and [`docs/maintainers/workflow-atlas.md`](./docs/maintainers/workflow-atlas.md). + +## Working Rules + +### Change Scope + +- Keep work bounded to the repo surface that actually changed. +- When a skill contract changes, update the nearby maintainer docs and tests in the same pass. +- Do not widen work into installer revival, nested packaging, or repo-shape experiments unless Gale explicitly asks for that scope change. + +### Source of Truth + +- Root [`skills/`](./skills/) is the canonical authored and exported surface. +- Treat maintainer docs under [`docs/maintainers/`](./docs/maintainers/) as the durable explanation layer for repo policy and packaging boundaries. +- Keep Codex plugin guidance aligned with the current OpenAI docs: only `plugin.json` belongs in `.codex-plugin/`, while `skills/` stays at the plugin root. +- Keep Codex plugin-boundary wording factual and explicit: repo-visible plugins come from the documented marketplace model, and OpenAI does not document a richer repo-private scoping model beyond that. + +### Communication and Escalation + +- Surface scope expansion before adding new maintainer workflows, new packaging layers, or new repo families. +- If docs and shipped skill behavior diverge, fix the skill or narrow the docs so they match instead of preserving soft ambiguity. +- When a wording choice could overstate Codex packaging behavior, prefer the narrower documented claim and name the exact surface involved. + +## Commands + +### Setup + +```bash +uv sync --dev +``` + +### Validation + +```bash +uv run pytest +``` + +### Optional Project Commands + +There are no additional repo-level commands worth calling out beyond the `uv` sync and test flow. + +## Review and Delivery + +### Review Expectations + +- Keep edits compact, repo-specific, and grounded in the shipped skill surface. +- When changing docs, preserve the split between public-facing project docs, contributor workflow docs, maintainer reference docs, and agent guidance. +- When changing skill behavior or audit logic, include the nearest tests or validation updates in the same pass. + +### Definition of Done + +- The changed surface is consistent across the relevant skill, maintainer doc, and test coverage. +- README, CONTRIBUTING, AGENTS, and ROADMAP stay aligned with the current repo shape when one of them materially changes. +- `uv run pytest` passes after changes that touch shipped skills, maintainer automation, or docs-backed audit expectations. + +## Safety Boundaries + +### Never Do + +- Do not recreate nested staged plugin directories or repo-local installer workflows in this repository. +- Do not invent hidden plugin install surfaces, undocumented scoping behavior, or stale packaging overlays. +- Do not treat maintainer docs as a substitute for the actual shipped skill contract. + +### Ask Before + +- Ask before adding new maintainer workflows, new repo-family support, or new packaging layers. +- Ask before turning this repo into a broader plugin-management surface beyond its current maintainer-skill role. +- Ask before deleting a maintainer reference doc unless its durable conclusions have been moved somewhere still-live. + +## Local Overrides + +There are no deeper `AGENTS.md` files in this repository today. If one is added later, that narrower file should refine this root guidance for the subtree where it lives. diff --git a/plugins/agent-plugin-skills/CONTRIBUTING.md b/plugins/agent-plugin-skills/CONTRIBUTING.md new file mode 100644 index 00000000..5f31a79a --- /dev/null +++ b/plugins/agent-plugin-skills/CONTRIBUTING.md @@ -0,0 +1,110 @@ +# Contributing to agent-plugin-skills + +Use this guide when preparing changes so the repository stays understandable, runnable, and reviewable for the next maintainer. + +## Table of Contents + +- [Overview](#overview) +- [Contribution Workflow](#contribution-workflow) +- [Local Setup](#local-setup) +- [Development Expectations](#development-expectations) +- [Pull Request Expectations](#pull-request-expectations) +- [Communication](#communication) +- [License and Contribution Terms](#license-and-contribution-terms) + +## Overview + +### Who This Guide Is For + +Use this guide if you are changing the shipped maintainer skills, the repo-local maintainer docs, or the small Python-backed audit tooling that supports those skills. + +### Before You Start + +Read [README.md](./README.md) for the public project shape, [AGENTS.md](./AGENTS.md) for durable repo rules, and the relevant maintainer docs under [`docs/maintainers/`](./docs/maintainers/) before changing packaging or guidance wording. + +If your change touches a skill contract, plan to update the nearest docs and tests in the same pass. + +## Contribution Workflow + +### Choosing Work + +Pick work that clearly belongs to this repository's narrow role: maintainer guidance for skills-export and plugin-export repos. General repo-doc cleanup belongs in `productivity-skills` unless this repo's narrower plugin-repo boundary is the real subject. + +When the work is about Codex plugin behavior, confirm the current OpenAI docs first instead of relying on older local assumptions. + +### Making Changes + +Keep root [`skills/`](./skills/) canonical, keep repo-level maintainer explanations under [`docs/maintainers/`](./docs/maintainers/), and keep source-repo plugin metadata under [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json). + +Do not reintroduce nested staged plugin directories, installer-era workflows, or vague install-surface language while making an unrelated fix. + +### Asking For Review + +A change is ready for review when the docs split still makes sense, nearby tests are updated when needed, and the final wording is explicit about which Codex surface or repo contract it is talking about. + +## Local Setup + +### Runtime Config + +This repository uses `uv` for local Python tooling. Sync the dev environment before running tests: + +```bash +uv sync --dev +``` + +This repo does not require dedicated local services or repo-specific secret configuration for normal docs and test work. + +### Runtime Behavior + +Most changes here are static docs, skill content, and small audit scripts. The main sign that the repo is healthy is that the shipped tests pass and the updated docs still match the shipped skill surface. + +Run the normal validation flow with: + +```bash +uv run pytest +``` + +## Development Expectations + +### Naming Conventions + +Keep the repo's core terms stable: + +- `skill` means the reusable workflow-authoring unit under `skills/` +- `plugin` means the installable Codex distribution bundle rooted at `.codex-plugin/plugin.json` +- `subagent` means a delegated runtime worker, not a packaged repo surface + +Match existing file, skill, and maintainer-doc names unless the change is explicitly about renaming. + +### Accessibility Expectations + +This repository is mostly docs and maintainer tooling rather than end-user UI, but contributors should still keep instructions, prompts, and audit output readable, plain, and unambiguous. + +If a change makes maintainer-facing language harder to scan or more ambiguous, treat that as a quality issue and fix it before asking for review. + +### Verification + +Prefer the grounded repo checks: + +```bash +uv sync --dev +uv run pytest +``` + +If you changed only prose, still sanity-check the nearby docs for split clarity and internal consistency before handing the work off. + +## Pull Request Expectations + +A good pull request keeps the scope narrow, explains which repo surface changed, and calls out any linked doc, test, or packaging updates that were needed to keep the repository coherent. + +If the change updates skill behavior or audit expectations, mention the validation you ran and which nearby docs moved with it. + +## Communication + +Surface uncertainty early when a change might widen the repository's role, soften a documented Codex boundary, or reintroduce old installer-era assumptions. + +If a task starts to require a new maintainer workflow, a new supported repo family, or a broader packaging model, pause and confirm that expansion before continuing. + +## License and Contribution Terms + +Contributions are governed by the repository license. See [LICENSE](./LICENSE) for the applicable terms. diff --git a/plugins/agent-plugin-skills/README.md b/plugins/agent-plugin-skills/README.md index 428eb8d2..aa2257a6 100644 --- a/plugins/agent-plugin-skills/README.md +++ b/plugins/agent-plugin-skills/README.md @@ -1,95 +1,112 @@ # agent-plugin-skills -Maintainer-skill repository for skills-export and plugin-export repos. +Installable maintainer skills for skills-export and plugin-export repositories. ## Table of Contents - [Overview](#overview) -- [Setup](#setup) +- [Quick Start](#quick-start) - [Usage](#usage) - [Development](#development) -- [Verification](#verification) +- [Repo Structure](#repo-structure) - [Release Notes](#release-notes) - [License](#license) - [Active Skills](#active-skills) -- [Repository Layout](#repository-layout) ## Overview -`agent-plugin-skills` packages maintainer-oriented skills for repositories that ship reusable skills or plugins. - ### Status -This repository is active and currently ships maintainer workflows for bootstrapping and syncing skills-export repository guidance. +This repository is active and currently ships two maintainer workflows. ### What This Project Is -This repository is the canonical home for maintainer skills that help Gale keep skills-export repositories honest about packaging, discovery, and documentation boundaries. +This repository is the canonical home for maintainer skills that help Gale keep skills-export and plugin-export repositories aligned on packaging, discovery, and documentation boundaries. + +It ships source-first Codex plugin packaging at [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json), keeps root [`skills/`](./skills/) as the authored surface, and keeps deeper maintainer explanation under [`docs/maintainers/`](./docs/maintainers/). ### Motivation -It exists so repo-maintenance guidance for skill and plugin repositories can live in one focused place instead of being duplicated across unrelated plugin repos. +It exists so repo-maintenance guidance for skills and plugin repositories can live in one focused place instead of being repeated across unrelated repos. -## Setup +## Quick Start -Sync the repo-local maintainer environment when you want to run tests for the Python-backed maintainer tooling: +Install the published skills if you want them available in your Codex environment: ```bash -uv sync --dev +npx skills add gaelic-ghost/agent-plugin-skills --all ``` +If you are inspecting or changing the repository itself, go to [Development](#development). + ## Usage -Use these skills when the target repository is itself a skills-export or plugin-export repository and the job is about repo structure, packaging guidance, or cross-surface documentation alignment. +Use this repository when the target project is itself a skills-export or plugin-export repository and the job is about repo structure, packaging guidance, discovery mirrors, or cross-surface documentation alignment. + +For general-purpose repository docs and maintainer workflow cleanup, start with `productivity-skills` first and reach for `agent-plugin-skills` only when the repository shape is narrow enough to need plugin-specific maintainer guidance. -For general repository doc and maintenance workflows, treat `productivity-skills` as the default baseline layer first. Reach for `agent-plugin-skills` only when that broader baseline is not specific enough for a repo that exports skills or plugins as its actual shipped surface. +When this repo discusses Codex packaging, it stays explicit about the current documented model: -This repo is deliberately blunt about a core limitation: OpenAI's documented Codex plugin system still exposes repo-visible plugins through the documented marketplace model rather than through a richer private repo-scoping system. +- plugins have a root manifest at `.codex-plugin/plugin.json` +- only `plugin.json` belongs in `.codex-plugin/` +- `skills/` stays at the plugin root +- repo-visible Codex plugins come from marketplace catalogs, and OpenAI does not document a richer repo-private scoping model beyond that ## Development ### Setup -Treat root [`skills/`](./skills/) as the canonical authored surface. Keep maintainer docs under [`docs/`](./docs/) and plugin metadata under [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json). - -### Workflow - -When you update a skill here, keep the surrounding maintainer guidance and tests aligned in the same pass. Do not invent hidden install surfaces or overstate Codex plugin scoping behavior. - -## Verification - -Run the repo-local maintainer tests before landing changes that touch skill behavior or metadata: +Sync the local maintainer environment before changing the Python-backed audit tooling or tests: ```bash uv sync --dev -uv run pytest ``` -## Release Notes +### Workflow -Use Git history and GitHub releases to track shipped changes to the maintainer-skill surface. +Keep root [`skills/`](./skills/) canonical, keep maintainer docs under [`docs/maintainers/`](./docs/maintainers/), and keep plugin metadata in [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json). -## License +When you update a skill here, align the nearby docs and tests in the same pass. Keep discovery mirrors, plugin packaging, marketplace catalogs, cache paths, and enabled-state wording separate instead of collapsing them into one vague install story. -See [LICENSE](./LICENSE). +Contributor workflow and review expectations live in [CONTRIBUTING.md](./CONTRIBUTING.md). -## Active Skills +### Validation -- `bootstrap-skills-plugin-repo`: bootstrap or align a skills-export repository around root `skills/`, discovery mirrors, and maintainer guidance -- `sync-skills-repo-guidance`: audit guidance drift across README, AGENTS, maintainer docs, and discovery mirrors in an existing skills-export repository +Run the repo-local tests before landing changes that touch skill behavior, docs-backed automation, or plugin metadata: -## Repository Layout +```bash +uv sync --dev +uv run pytest +``` + +## Repo Structure ```text . ├── .codex-plugin/ │ └── plugin.json ├── AGENTS.md -├── LICENSE +├── CONTRIBUTING.md ├── README.md ├── ROADMAP.md ├── docs/ -├── pyproject.toml +│ └── maintainers/ ├── skills/ +│ ├── bootstrap-skills-plugin-repo/ +│ └── sync-skills-repo-guidance/ +├── pyproject.toml └── uv.lock ``` + +## Release Notes + +Use Git history and GitHub releases to track shipped changes to the maintainer-skill surface. + +## License + +See [LICENSE](./LICENSE). + +## Active Skills + +- `bootstrap-skills-plugin-repo`: bootstrap or align a skills-export repository around root `skills/`, discovery mirrors, and maintainer guidance +- `sync-skills-repo-guidance`: audit guidance drift across README, AGENTS, maintainer docs, and discovery mirrors in an existing skills-export repository diff --git a/plugins/agent-plugin-skills/ROADMAP.md b/plugins/agent-plugin-skills/ROADMAP.md index 443c7a82..3bece091 100644 --- a/plugins/agent-plugin-skills/ROADMAP.md +++ b/plugins/agent-plugin-skills/ROADMAP.md @@ -1,91 +1,128 @@ # Project Roadmap +Use this roadmap to track milestone-level delivery through checklist sections. + +## Table of Contents + +- [Vision](#vision) +- [Product Principles](#product-principles) +- [Milestone Progress](#milestone-progress) +- [Milestone 4: Docs Visibility And Wording Hardening](#milestone-4-docs-visibility-and-wording-hardening) +- [Milestone 5: Skills Repo Migration And Split Support](#milestone-5-skills-repo-migration-and-split-support) +- [Milestone 6: Upstream Docs Watch And Change Intake](#milestone-6-upstream-docs-watch-and-change-intake) +- [Milestone 7: Skill Evals](#milestone-7-skill-evals) +- [Backlog Candidates](#backlog-candidates) +- [History](#history) + ## Vision - Keep `agent-plugin-skills` as the focused home for maintainer skills that help skills-export and plugin-export repositories stay honest about packaging, discovery, and documentation boundaries. -## Product principles +## Product Principles -- Keep the repository blunt about Codex's documented plugin-scoping limits. -- Keep maintainer workflows audit-first and bounded. -- Keep root `skills/` canonical and avoid reintroducing local installer machinery into this repo. +- Keep the repository explicit about Codex's currently documented plugin model and install surfaces. +- Keep maintainer workflows audit-first, bounded, and backed by small deterministic tests. +- Keep root `skills/` canonical and avoid reviving installer-era machinery inside this repo. ## Milestone Progress -- [ ] Milestone 4: docs visibility and wording hardening -- [ ] Milestone 5: skills repo migration and split support -- [ ] Milestone 6: upstream docs watch and change intake -- [ ] Milestone 7: `skill-evals` +- Milestone 4: docs visibility and wording hardening - In Progress +- Milestone 5: skills repo migration and split support - Planned +- Milestone 6: upstream docs watch and change intake - Planned +- Milestone 7: `skill-evals` - Planned + +## Milestone 4: Docs Visibility And Wording Hardening -## Milestone 4: docs visibility and wording hardening +### Status -Scope: +In Progress -- Keep top-level docs and shipped skills abundantly clear about what this repo exports and what Codex still cannot scope properly. +### Scope -Tickets: +- [ ] Keep top-level docs and shipped skills abundantly clear about what this repo exports and what Codex's documented plugin model does and does not describe. -- [ ] Audit exported skills for wording that softens OpenAI's Codex scoping limits. +### Tickets + +- [ ] Audit exported skills for wording that softens or blurs the current OpenAI Codex plugin guidance. - [ ] Keep global-install guidance ahead of local authoring notes. - [ ] Keep repo-local discovery mirror guidance separate from install guidance. - [ ] Add or refine troubleshooting language for confusing Codex plugin expectations. +- [ ] Keep `README.md`, `CONTRIBUTING.md`, `AGENTS.md`, and `ROADMAP.md` aligned on the same repo shape and maintainer split. -Exit criteria: +### Exit Criteria - [ ] End users can quickly tell that this repo exports installable maintainer skills and does not provide a richer repo-private Codex plugin product. -- [ ] Limitation messaging is consistent across the shipped skill surface and repo docs. +- [ ] Plugin-boundary wording is consistent across the shipped skill surface and repo docs. +- [ ] The core maintainer docs follow the current house templates without blurring their responsibilities. + +## Milestone 5: Skills Repo Migration And Split Support + +### Status -## Milestone 5: skills repo migration and split support +Planned -Scope: +### Scope -- Add a maintainer workflow for moving or re-homing skills between repositories while preserving docs and guidance. +- [ ] Add a maintainer workflow for moving or re-homing skills between repositories while preserving docs and guidance. -Tickets: +### Tickets - [ ] Define migration inputs and guardrails for moving one or more skills between repos. - [ ] Add guidance for updating install examples, docs, and roadmap references after a move. - [ ] Add deterministic validation for orphaned references and stale naming after migration. - [ ] Decide whether subtree-managed superprojects such as `socket` should become an explicitly supported repo family here. -Exit criteria: +### Exit Criteria - [ ] Maintainers can move skills between repos without manual cross-surface cleanup. -## Milestone 6: upstream docs watch and change intake +## Milestone 6: Upstream Docs Watch And Change Intake -Scope: +### Status -- Add durable process support for noticing changes in the Agent Skills standard, OpenAI docs, and Claude docs and turning those changes into actionable maintainer work. +Planned -Tickets: +### Scope + +- [ ] Add durable process support for noticing changes in the Agent Skills standard, OpenAI docs, and Claude docs and turning those changes into actionable maintainer work. + +### Tickets - [ ] Define the upstream sources and canonical refresh cadence. - [ ] Add a dated findings format for upstream changes that affect repo policy or docs. - [ ] Decide whether this belongs inside `sync-skills-repo-guidance` or becomes a separate audit skill. -Exit criteria: +### Exit Criteria - [ ] Upstream ecosystem drift can be tracked deliberately instead of ad hoc. -## Milestone 7: `skill-evals` +## Milestone 7: Skill Evals + +### Status -Scope: +Planned -- Add a workflow for evaluating shipped skills against real agent runtimes such as Codex and Claude Code. +### Scope -Tickets: +- [ ] Add a workflow for evaluating shipped skills against real agent runtimes such as Codex and Claude Code. + +### Tickets - [ ] Define the eval targets and supported runtimes. - [ ] Define the eval artifact set, including prompts, expected behaviors, failure notes, and dated run summaries. - [ ] Add deterministic guidance for comparing trigger activation, tool usage, and final output shape against the intended skill contract. - [ ] Decide whether the workflow is audit-only, report-generating, or can also scaffold eval fixtures. -Exit criteria: +### Exit Criteria - [ ] Maintainers have one coherent workflow for evaluating a skill on real agent surfaces instead of relying only on static review. +## Backlog Candidates + +- [ ] No additional backlog candidates are recorded yet. + ## History -- Completed Milestones 0 through 3 by establishing the repository, shipping the foundational maintainer skills, and removing installer-era nested packaging guidance. -- Completed Milestone 8 by retiring the old `maintain-plugin-docs` surface and aligning the shipped inventory around the remaining maintainer workflows. +- Initial roadmap scaffold established the repository and its first maintainer-skill milestones. +- Completed the foundational milestones that created the repository, shipped the first maintainer skills, and removed installer-era nested packaging guidance. +- Completed the later cleanup milestone that retired the old `maintain-plugin-docs` surface and aligned the shipped inventory around the remaining maintainer workflows. diff --git a/plugins/agent-plugin-skills/docs/maintainers/codex-plugin-install-surfaces.md b/plugins/agent-plugin-skills/docs/maintainers/codex-plugin-install-surfaces.md index 79d8eaa5..0d2a57b7 100644 --- a/plugins/agent-plugin-skills/docs/maintainers/codex-plugin-install-surfaces.md +++ b/plugins/agent-plugin-skills/docs/maintainers/codex-plugin-install-surfaces.md @@ -4,6 +4,15 @@ Use this document when maintainers need a durable map of how Codex's documented This is not a replacement for the official docs. It is a maintainer-focused translation layer for the parts that are easiest to blur together during local plugin work. +## Plugin Root Structure + +OpenAI's current plugin docs separate the plugin root from the marketplace and config surfaces: + +- every plugin has a manifest at `.codex-plugin/plugin.json` +- only `plugin.json` belongs in `.codex-plugin/` +- `skills/`, `.app.json`, `.mcp.json`, and `assets/` belong at the plugin root +- marketplace `source.path` should point at the plugin root directory, not at `.codex-plugin/` + ## Core Model Codex plugin wiring has four different jobs on four different surfaces: @@ -13,7 +22,7 @@ Codex plugin wiring has four different jobs on four different surfaces: - Personal path: `~/.agents/plugins/marketplace.json` - Repo path: `$REPO_ROOT/.agents/plugins/marketplace.json` 2. Staged plugin directory - - Purpose: hold the plugin payload on disk that a marketplace entry points at. + - Purpose: hold the plugin root payload on disk that a marketplace entry points at. - Common personal pattern: `~/.codex/plugins/` - Common repo pattern from the docs: `$REPO_ROOT/plugins/` 3. Installed plugin cache @@ -22,8 +31,7 @@ Codex plugin wiring has four different jobs on four different surfaces: - For local plugins, the documented version token is `local`. 4. Enabled-state config - Purpose: say whether a marketplace-scoped plugin is enabled or disabled. - - Personal path: `~/.codex/config.toml` - - Optional repo override path: `$REPO_ROOT/.codex/config.toml` + - Documented plugin path: `~/.codex/config.toml` ## Diagram @@ -37,8 +45,7 @@ flowchart LR B -->|Codex installs local copy| C["Installed plugin cache ~/.codex/plugins/cache///"] D["Enabled-state config - ~/.codex/config.toml - optional: $REPO_ROOT/.codex/config.toml"] -->|turn plugin identity on or off| C + ~/.codex/config.toml"] -->|turn plugin identity on or off| C ``` ## What Each Surface Is Not @@ -68,6 +75,16 @@ That means: If you later rename the marketplace or switch the plugin to a different marketplace, the config identity changes too. +## General Config Note + +The broader Codex config reference also says Codex can load trusted project-scoped overrides from `.codex/config.toml`. + +Keep that separate from the plugin install-surface map: + +- the current plugin docs explicitly describe plugin on or off state in `~/.codex/config.toml` +- the plugin docs do not describe repo-local plugin enabled-state as its own install-surface category +- if you mention project-scoped `.codex/config.toml`, label it as a general Codex config capability rather than part of the documented plugin wiring model + ## Personal Scope Personal scope means the catalog and enablement live in your home-directory Codex surfaces. @@ -85,13 +102,13 @@ Repo scope means the catalog is attached to one repository. - Catalog: `$REPO_ROOT/.agents/plugins/marketplace.json` - Common staged payload path from the docs: `$REPO_ROOT/plugins/` -- Optional project-scoped enabled-state override: `$REPO_ROOT/.codex/config.toml` +- Documented plugin enabled-state path: `~/.codex/config.toml` Important nuance: - The repo marketplace is still a catalog, not a private install vault. - If the repo tracks that marketplace in git, it is advertising those plugins as part of the repo-visible Codex surface. -- OpenAI's documented Codex plugin model does not provide true repo-private plugin scoping beyond that visible repo marketplace model. +- OpenAI's documented Codex plugin model exposes repo-visible plugins through marketplace catalogs and does not describe a richer repo-private scoping model beyond that visible marketplace model. ## Practical Reading Order @@ -102,7 +119,7 @@ When a plugin looks wrong, inspect in this order: - Does `source.path` point at the intended staged payload directory? 2. staged payload directory - Does the target directory exist? - - Does it contain `.codex-plugin/plugin.json` and the expected bundled surfaces? + - Does it contain `.codex-plugin/plugin.json` and the expected plugin-root surfaces such as `skills/`? 3. enabled-state - Is the plugin identity enabled in `config.toml`? - Is there a stale identity from an older marketplace name or scope? diff --git a/plugins/agent-plugin-skills/docs/maintainers/reality-audit.md b/plugins/agent-plugin-skills/docs/maintainers/reality-audit.md index 7eb136db..3dd4a88f 100644 --- a/plugins/agent-plugin-skills/docs/maintainers/reality-audit.md +++ b/plugins/agent-plugin-skills/docs/maintainers/reality-audit.md @@ -26,7 +26,7 @@ For the durable map of Codex plugin catalogs, staged payloads, installed cache p - Root `skills/` is canonical. - `.agents/skills` and `.claude/skills` are POSIX symlink mirrors to `../skills`. -- README and AGENTS say plainly that this repo exports installable skills and does not pretend Codex has proper repo-private plugin scope. +- README and AGENTS say plainly that this repo exports installable skills and that OpenAI documents marketplace-based plugin discovery rather than a richer repo-private plugin scope. - ROADMAP matches the live exported skill set. - Maintainer tooling guidance includes `uv sync --dev`, `uv tool install ruff`, `uv tool install mypy`, and `uv run --group dev pytest`. - No tracked file reintroduces nested staged plugin directories, repo-marketplace guidance for this repo, installer workflows, or install-validation workflows. diff --git a/plugins/agent-plugin-skills/docs/maintainers/workflow-atlas.md b/plugins/agent-plugin-skills/docs/maintainers/workflow-atlas.md index 32976636..d55ce1d7 100644 --- a/plugins/agent-plugin-skills/docs/maintainers/workflow-atlas.md +++ b/plugins/agent-plugin-skills/docs/maintainers/workflow-atlas.md @@ -18,7 +18,7 @@ For the maintainers' plugin-surface diagram and glossary, see [codex-plugin-inst - Root `skills/` is canonical. - `.agents/skills` and `.claude/skills` are local discovery mirrors. - No skill in this repo should teach a nested staged plugin directory for this repo. -- No skill in this repo should treat repo-local Codex plugin installs as proper private scoping. +- No skill in this repo should treat repo-local Codex plugin installs as a richer private scoping model than the marketplace-based behavior OpenAI documents. - No skill in this repo should resurrect installer or install-validation workflows. ## Recommended Flow diff --git a/plugins/agent-plugin-skills/pyproject.toml b/plugins/agent-plugin-skills/pyproject.toml index dd99722a..7d995363 100644 --- a/plugins/agent-plugin-skills/pyproject.toml +++ b/plugins/agent-plugin-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "agent-plugin-skills-maintenance" -version = "1.2.2" +version = "1.3.0" description = "Maintainer-only Python tooling baseline for agent-plugin-skills." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/agent-plugin-skills/skills/bootstrap-skills-plugin-repo/SKILL.md b/plugins/agent-plugin-skills/skills/bootstrap-skills-plugin-repo/SKILL.md index f70b0997..0aa801f4 100644 --- a/plugins/agent-plugin-skills/skills/bootstrap-skills-plugin-repo/SKILL.md +++ b/plugins/agent-plugin-skills/skills/bootstrap-skills-plugin-repo/SKILL.md @@ -1,15 +1,24 @@ --- name: bootstrap-skills-plugin-repo -description: Bootstrap or align a skills-export repository with root `skills/`, repo-local discovery mirrors, maintainer docs, and explicit Codex limitation wording. Use when creating a new skills repo or structurally aligning an existing one. Do not use this for narrow README-only or roadmap-only maintenance. +description: Bootstrap or align a skills-export repository with root `skills/`, repo-local discovery mirrors, maintainer docs, and clear Codex plugin-boundary wording. Use when creating a new skills repo or structurally aligning an existing one. Do not use this for narrow README-only or roadmap-only maintenance. --- # Bootstrap Skills Plugin Repo Bootstrap or align a skills-export repository. -## Codex Limitation Warning +## Codex Model Note -Warn plainly that OpenAI's documented Codex plugin system does not provide proper repo-private plugin scoping. This repository pattern allows root `.codex-plugin` packaging, but it does not normalize nested staged plugin directories or repo marketplaces for itself. +State plainly that OpenAI's documented Codex plugin system exposes repo-visible plugins through marketplace catalogs and does not document a richer repo-private scoping model beyond that. This repository pattern allows root `.codex-plugin` packaging, but it does not normalize nested staged plugin directories or repo marketplaces for itself. + +## Codex Plugin Root Structure + +When bootstrapping or aligning a plugin repo, follow the current OpenAI plugin structure: + +- every plugin has a manifest at `.codex-plugin/plugin.json` +- only `plugin.json` belongs in `.codex-plugin/` +- `skills/`, `.app.json`, `.mcp.json`, and `assets/` belong at the plugin root +- marketplace `source.path` should point at the plugin root directory ## Codex Install-Surface Map @@ -22,13 +31,14 @@ When bootstrapping or aligning repo guidance, teach Codex plugin wiring with fou - staged plugin directory - common personal pattern: `~/.codex/plugins/` - common repo pattern from the docs: `$REPO_ROOT/plugins/` - - role: the plugin payload on disk + - role: the plugin root payload on disk - installed plugin cache - `~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/` - role: Codex's installed copy for runtime loading - enabled-state config - - personal: `~/.codex/config.toml` - - optional repo override: `$REPO_ROOT/.codex/config.toml` + - documented plugin path: `~/.codex/config.toml` - role: on or off state keyed by plugin plus marketplace identity, such as `[plugins."my-plugin@socket"]` Bootstrap docs should keep discovery mirrors, plugin packaging, marketplace catalogs, staged payload directories, cache paths, and config-state separate. Do not blur "where Codex can see a plugin", "where the plugin payload lives", and "whether the plugin is enabled" into one sentence. + +If you mention project-scoped `.codex/config.toml`, describe it as a general Codex config surface from the config reference, not as a separate documented plugin install surface. diff --git a/plugins/agent-plugin-skills/skills/bootstrap-skills-plugin-repo/agents/openai.yaml b/plugins/agent-plugin-skills/skills/bootstrap-skills-plugin-repo/agents/openai.yaml index 6a9534dc..639c505c 100644 --- a/plugins/agent-plugin-skills/skills/bootstrap-skills-plugin-repo/agents/openai.yaml +++ b/plugins/agent-plugin-skills/skills/bootstrap-skills-plugin-repo/agents/openai.yaml @@ -1,2 +1,2 @@ interface: - default_prompt: "Use $bootstrap-skills-plugin-repo to audit a skills-export repository first, then create or align the source-first repo structure with root `skills/`, root `.codex-plugin` packaging, repo-local discovery mirrors, maintainer docs, AGENTS guidance, and explicit Codex limitation wording. Do not recreate nested staged plugin directories, repo marketplaces, installer workflows, or install-validation workflows for this repo family." + default_prompt: "Use $bootstrap-skills-plugin-repo to audit a skills-export repository first, then create or align the source-first repo structure with root `skills/`, root `.codex-plugin` packaging, repo-local discovery mirrors, maintainer docs, AGENTS guidance, and clear Codex plugin-boundary wording. Do not recreate nested staged plugin directories, repo marketplaces, installer workflows, or install-validation workflows for this repo family." diff --git a/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/SKILL.md b/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/SKILL.md index 9f095d3a..f812e888 100644 --- a/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/SKILL.md +++ b/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/SKILL.md @@ -7,9 +7,18 @@ description: Audit guidance across README.md, AGENTS.md, maintainer docs, and di Audit an existing skills-export repository against the current house guidance and upstream standards. -## Codex Limitation Warning +## Codex Model Note -When syncing Codex guidance, warn explicitly that OpenAI's documented Codex plugin system does not provide proper repo-private plugin scoping. +When syncing Codex guidance, state clearly that OpenAI's documented Codex plugin system exposes repo-visible plugins through marketplace catalogs and does not document a richer repo-private scoping model beyond that. + +## Codex Plugin Root Structure + +When this skill touches Codex packaging guidance, keep the plugin-root structure aligned with the current OpenAI docs: + +- every plugin has a manifest at `.codex-plugin/plugin.json` +- only `plugin.json` belongs in `.codex-plugin/` +- `skills/`, `.app.json`, `.mcp.json`, and `assets/` belong at the plugin root +- marketplace entries point `source.path` at the plugin root directory, not at `.codex-plugin/` ## Codex Install-Surface Map @@ -22,13 +31,14 @@ When this skill touches Codex plugin guidance, keep these surfaces distinct inst - staged plugin directory - common personal pattern: `~/.codex/plugins/` - common repo pattern from the docs: `$REPO_ROOT/plugins/` - - purpose: source payload the marketplace entry points at + - purpose: plugin root payload directory that the marketplace entry points at - installed plugin cache - `~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/` - purpose: Codex's installed copy; for local plugins the documented version token is `local` - enabled-state config - - personal: `~/.codex/config.toml` - - optional repo override: `$REPO_ROOT/.codex/config.toml` + - documented plugin path: `~/.codex/config.toml` - purpose: per-plugin on or off state keyed by plugin name plus marketplace name, for example `[plugins."my-plugin@local-repo"]` Do not describe `config.toml` as the place plugins install into. Do not describe a marketplace file as the install destination. Keep the wording explicit: marketplaces are catalogs, staged plugin directories are payload roots, the cache is Codex's installed copy, and `config.toml` stores enabled-state. + +If you mention project-scoped `.codex/config.toml`, label it as a general Codex config capability from the config reference rather than as part of the documented plugin install-surface map. diff --git a/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/references/sync-checklist.md b/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/references/sync-checklist.md index 5246c5d8..174e64d5 100644 --- a/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/references/sync-checklist.md +++ b/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/references/sync-checklist.md @@ -4,7 +4,7 @@ - `.agents/skills -> ../skills` - `.claude/skills -> ../skills` - README and AGENTS describe the repo as a source-first skills-export repository -- README and AGENTS keep the Codex limitation warning explicit +- README and AGENTS keep the Codex plugin-boundary note explicit - no nested staged plugin-directory guidance remains - no installer or install-validation guidance remains - maintainer tooling guidance stays explicit diff --git a/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/scripts/sync_skills_repo_guidance.py b/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/scripts/sync_skills_repo_guidance.py index 1a35e88a..33870783 100644 --- a/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/scripts/sync_skills_repo_guidance.py +++ b/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/scripts/sync_skills_repo_guidance.py @@ -10,12 +10,13 @@ EXACT_NO_FINDINGS = "No findings." README_SNIPPETS = [ "Installable maintainer skills for skills-export repositories.", - "OpenAI's current documented Codex plugin system is too restricted to provide proper repo-private plugin scoping.", + "does not document a richer repo-private scoping model", "npx skills add gaelic-ghost/agent-plugin-skills --all", "https://skills.sh/", "uv tool install ruff", "uv tool install mypy", "Claude Code continues to support direct `.claude/skills` discovery for local authoring", + "only `plugin.json` belongs in `.codex-plugin/`", ] AGENTS_SNIPPETS = [ "Root `skills/` is the canonical authored and exported surface", @@ -28,6 +29,14 @@ "This repository does not ship `install-plugin-to-socket`.", "This repository does not ship `validate-plugin-install-surfaces`.", ] +INSTALL_SURFACES_SNIPPETS = [ + "only `plugin.json` belongs in `.codex-plugin/`", + "Documented plugin path: `~/.codex/config.toml`", + "project-scoped `.codex/config.toml`, label it as a general Codex config capability", +] +WORKFLOW_ATLAS_SNIPPETS = [ + "No skill in this repo should treat repo-local Codex plugin installs as a richer private scoping model than the marketplace-based behavior OpenAI documents.", +] GITIGNORE_SNIPPETS = [".claude/settings.local.json"] @dataclass @@ -71,6 +80,22 @@ def audit_repo(repo_root: Path, plugin_name: str) -> list[Finding]: findings.extend(_check_file_contains(repo_root, repo_root / "AGENTS.md", AGENTS_SNIPPETS, "agents")) findings.extend(_check_file_contains(repo_root, repo_root / ".gitignore", GITIGNORE_SNIPPETS, "gitignore")) findings.extend(_check_file_contains(repo_root, repo_root / "docs" / "maintainers" / "reality-audit.md", AUDIT_SNIPPETS, "reality-audit")) + findings.extend( + _check_file_contains( + repo_root, + repo_root / "docs" / "maintainers" / "codex-plugin-install-surfaces.md", + INSTALL_SURFACES_SNIPPETS, + "install-surfaces", + ) + ) + findings.extend( + _check_file_contains( + repo_root, + repo_root / "docs" / "maintainers" / "workflow-atlas.md", + WORKFLOW_ATLAS_SNIPPETS, + "workflow-atlas", + ) + ) findings.extend(_check_symlink(repo_root, repo_root / ".agents" / "skills", "../skills")) findings.extend(_check_symlink(repo_root, repo_root / ".claude" / "skills", "../skills")) if not (repo_root / ".codex-plugin" / "plugin.json").exists(): diff --git a/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/tests/test_sync_skills_repo_guidance.py b/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/tests/test_sync_skills_repo_guidance.py index f8e68ff2..cf963f4a 100644 --- a/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/tests/test_sync_skills_repo_guidance.py +++ b/plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/tests/test_sync_skills_repo_guidance.py @@ -27,12 +27,13 @@ def _write_repo(repo_root: Path, _plugin_name: str) -> None: "\n".join( [ "Installable maintainer skills for skills-export repositories.", - "OpenAI's current documented Codex plugin system is too restricted to provide proper repo-private plugin scoping.", + "OpenAI's documented Codex plugin system exposes repo-visible plugins through marketplace catalogs and does not document a richer repo-private scoping model beyond that.", "npx skills add gaelic-ghost/agent-plugin-skills --all", "https://skills.sh/", "uv tool install ruff", "uv tool install mypy", "Claude Code continues to support direct `.claude/skills` discovery for local authoring while plugin packaging lives separately.", + "Follow the current OpenAI plugin structure literally: only `plugin.json` belongs in `.codex-plugin/`, while `skills/` stays at the plugin root.", ] ) + "\n", @@ -64,6 +65,21 @@ def _write_repo(repo_root: Path, _plugin_name: str) -> None: + "\n", encoding="utf-8", ) + (repo_root / "docs" / "maintainers" / "codex-plugin-install-surfaces.md").write_text( + "\n".join( + [ + "only `plugin.json` belongs in `.codex-plugin/`", + "Documented plugin path: `~/.codex/config.toml`", + "If you mention project-scoped `.codex/config.toml`, label it as a general Codex config capability rather than part of the documented plugin install-surface map.", + ] + ) + + "\n", + encoding="utf-8", + ) + (repo_root / "docs" / "maintainers" / "workflow-atlas.md").write_text( + "No skill in this repo should treat repo-local Codex plugin installs as a richer private scoping model than the marketplace-based behavior OpenAI documents.\n", + encoding="utf-8", + ) (repo_root / ".agents").mkdir() (repo_root / ".claude").mkdir() os.symlink("../skills", repo_root / ".agents" / "skills") diff --git a/plugins/agent-plugin-skills/uv.lock b/plugins/agent-plugin-skills/uv.lock index f3e5a0b1..f1932453 100644 --- a/plugins/agent-plugin-skills/uv.lock +++ b/plugins/agent-plugin-skills/uv.lock @@ -4,7 +4,7 @@ requires-python = ">=3.11" [[package]] name = "agent-plugin-skills-maintenance" -version = "1.2.2" +version = "1.3.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/pyproject.toml b/pyproject.toml index 294d60d5..2e634366 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "socket-maintenance" -version = "0.8.2" +version = "0.9.0" description = "Root uv tooling baseline for the socket superproject." requires-python = ">=3.11" dependencies = [] diff --git a/uv.lock b/uv.lock index c1845372..efc92cf8 100644 --- a/uv.lock +++ b/uv.lock @@ -59,7 +59,7 @@ wheels = [ [[package]] name = "socket-maintenance" -version = "0.8.2" +version = "0.9.0" source = { virtual = "." } [package.dev-dependencies]