Docs/add documentation tree

.agents/plugins/marketplace.json

@@ -0,0 +1,10 @@
+{
+  "name": "actdata-plugins",
+  "interface": { "displayName": "ACT Data Plugins" },
+  "plugins": [
+    { "name": "act-plugin-dev", "source": { "source": "local", "path": "./plugins/act-plugin-dev" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Development" },
+    { "name": "act-platform-engineering", "source": { "source": "local", "path": "./plugins/act-platform-engineering" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Operations" },
+    { "name": "act-work-tracking", "source": { "source": "local", "path": "./plugins/act-work-tracking" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Workflow" },
+    { "name": "act-gitlab-ci", "source": { "source": "local", "path": "./plugins/act-gitlab-ci" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Engineering" }
+  ]
+}

.claude-plugin/marketplace.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
   "name": "actdata-plugins",
   "description": "ACT Data's agent plugin catalog. Installable capability for the teams building and operating ACT Data's software: plugin development, engineering standards, and delivery workflow.",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "owner": {
     "name": "ACT Data",
     "url": "https://github.com/patterson-agents"
@@ -16,7 +16,7 @@
       "source": "./plugins/act-plugin-dev",
       "displayName": "ACT Plugin Development Toolkit",
       "description": "Everything needed to build a plugin for this marketplace: seven skills covering plugin structure, skills, commands, agents, hooks, MCP integration and plugin settings; three review agents (agent-creator, plugin-validator, skill-reviewer); and a guided eight-phase creation workflow that registers the finished plugin in the marketplace. Relevant to anyone authoring or reviewing a Claude Code plugin, skill, slash command, subagent, or hook, or wiring an MCP server into a plugin.",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "author": {
         "name": "Daniel Bodnar"
       },
@@ -54,7 +54,7 @@
       "source": "./plugins/act-platform-engineering",
       "displayName": "ACT Platform Engineering",
       "description": "Assessment and operations for PostgreSQL, ZFS, Linux hosts and Proxmox VE. Seven skills covering database performance, backups and replication, pool health and tuning, drive and kernel diagnostics, hypervisor and VM hygiene, observability coverage and incident response; seven role-based reasoning agents; and nine one-shot assessment commands with green/red criteria. Reads its host inventory from a site-local settings file and ships no environment identifiers. Relevant to anyone diagnosing a database or storage host, planning failover, assessing backups, or running an incident.",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "author": {
         "name": "Daniel Bodnar"
       },
@@ -94,7 +94,7 @@
       "source": "./plugins/act-work-tracking",
       "displayName": "ACT Work Tracking",
       "description": "Zoho Projects work tracking and operations reporting. Covers the task-versus-issue distinction, drafting templates for both, the REST API's quirks including the Zoho-oauthtoken header and the bugs endpoint, bulk creation from JSON with a credential-free dry run, weekly status structure, and the writing conventions that keep issues and reports actionable. Reads portal and project IDs from a site-local settings file. Relevant to anyone filing engineering work into Zoho Projects, writing a status report, or maintaining an assessment document set.",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "author": {
         "name": "Daniel Bodnar"
       },
@@ -128,7 +128,7 @@
       "source": "./plugins/act-gitlab-ci",
       "displayName": "ACT GitLab CI/CD",
       "description": "GitLab CI/CD and GitLab tooling for Claude Code. Six skills covering running Claude Code as a CI job across the Claude API, Amazon Bedrock and Vertex providers; the GitLab MCP server with its full tool catalogue and version requirements; the glab CLI; CI troubleshooting; and pipeline standards translated to GitLab and marked as derived. Ships a GitLab MCP server configuration, a pipeline security review agent, and a zero-dependency pipeline checker. Relevant to anyone writing a .gitlab-ci.yml, wiring Claude into a pipeline, connecting to GitLab over MCP, or reviewing a pipeline for credential and scan compliance.",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "author": {
         "name": "Daniel Bodnar"
       },

.github/copilot-instructions.md

@@ -0,0 +1,18 @@
+# Repository instructions
+
+This repository distributes ACT Data plugins for Claude Code, ChatGPT, Codex, and GitHub Copilot.
+It is a catalog of agent workflows, not an application package.
+
+- Keep plugin names, skill directories, commands, and agents in lowercase kebab-case.
+- Keep each `skills/<name>/SKILL.md` frontmatter `name` identical to its directory.
+- Register every shipped plugin in `.claude-plugin/marketplace.json`,
+  `.agents/plugins/marketplace.json`, and `.github/plugin/marketplace.json`.
+- Keep versions synchronized across all marketplace entries and the plugin's
+  `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, and root `plugin.json`.
+- Preserve `${CLAUDE_PLUGIN_ROOT}` only in Claude-specific components. Portable skills must resolve
+  bundled resources from the installed plugin or skill directory.
+- Store site configuration in `.agents/<plugin>.local.md`; support `.claude/<plugin>.local.md` as a
+  legacy fallback. Never commit environment identifiers or credentials.
+- Use Bun for JavaScript and TypeScript tooling. Do not add npm, Yarn, or pnpm lockfiles.
+- Use `apply_patch` for edits and run `sh scripts/verify-all.sh` before considering a change done.
+- Do not commit fonts, archives, Office files, PDFs, or raster images over 50 KiB.

.github/plugin/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "actdata-plugins",
+  "owner": { "name": "ACT Data" },
+  "metadata": { "description": "ACT Data's agent plugin catalog for engineering, operations, and delivery workflows.", "version": "0.2.0" },
+  "plugins": [
+    { "name": "act-plugin-dev", "description": "Create and review portable agent plugins.", "version": "0.2.0", "source": "./plugins/act-plugin-dev", "category": "Development" },
+    { "name": "act-platform-engineering", "description": "Assess and operate PostgreSQL, ZFS, Linux, Proxmox VE, and observability systems.", "version": "0.2.0", "source": "./plugins/act-platform-engineering", "category": "Operations" },
+    { "name": "act-work-tracking", "description": "Draft Zoho Projects work and engineering status reports.", "version": "0.2.0", "source": "./plugins/act-work-tracking", "category": "Workflow" },
+    { "name": "act-gitlab-ci", "description": "Build, review, and troubleshoot GitLab CI/CD integrations.", "version": "0.2.0", "source": "./plugins/act-gitlab-ci", "category": "Engineering" }
+  ]
+}

.gitignore

@@ -158,3 +158,4 @@ pnpm-lock.yaml
 # in a `.local.md` the operator writes for their own site. Committing one would put the
 # very identifiers the plugins are designed to exclude back into the repository.
 .claude/*.local.md
+.agents/*.local.md

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing to actdata-plugins
 
-`actdata-plugins` is ACT Data's Claude Code plugin marketplace: capability shipped as installable
-plugins. This document is how a person or an agent proposes a change to it.
+`actdata-plugins` is ACT Data's plugin marketplace for Claude Code, ChatGPT, Codex, and GitHub
+Copilot. This document is how a person or an agent proposes a change to it.
 
 ## The short version
 
@@ -24,8 +24,8 @@ checked mechanically; the rest are checked in review.
 | **kebab-case** | Plugin names, skill directory names, command filenames, agent filenames, issue and PR template filenames. |
 | **Skill name equals directory name** | A skill's directory name and its `SKILL.md` frontmatter `name:` must be the identical kebab-case string. This is the single most common defect when importing a skill written elsewhere, because Title Case names (`name: Plugin Structure`) are the norm outside this repository. The gate fails on a mismatch. |
 | **Plugins live at `plugins/<name>/`** | Never at the repository root, never nested deeper. `marketplace.json` declares `metadata.pluginRoot: "./plugins"`. |
-| **Registration is part of shipping** | A plugin with no entry in `.claude-plugin/marketplace.json` is invisible to `claude plugin install`. Every shipped plugin needs an entry with a `relevance` block. A plugin that is still a scaffold should stay unregistered — the gate recognises TODO placeholders and reports it as a draft rather than failing. |
-| **Version in two places** | `plugins/<name>/.claude-plugin/plugin.json` and the plugin's `marketplace.json` entry must carry the same version. Bump both in the same commit; the gate compares them. |
+| **Registration is part of shipping** | Register shipped plugins in `.claude-plugin/marketplace.json`, `.agents/plugins/marketplace.json`, and `.github/plugin/marketplace.json`. |
+| **Version everywhere** | Keep the Claude, OpenAI, and Copilot manifests and versioned catalog entries synchronized. |
 | **`${CLAUDE_PLUGIN_ROOT}` stays literal** | Every intra-plugin reference uses the literal token, never an absolute path a tool happened to resolve it to on someone's machine. The gate greps for expanded forms and fails on them. |
 | **Bun only** | `bun install`, `bun run`, `bunx`, `bun test`. `bun.lock` is the only lockfile; an `npm`, `yarn`, or `pnpm` lockfile in this repository is a bug to remove. |
 | **No `/tmp`** | Nothing is created or stored under `/tmp` — not scratch files, not build intermediates, not test fixtures. Scratch lives in the repository's gitignored `.tmp/`. This is a Patterson house standard enforced by a workspace hook. |
@@ -57,13 +57,12 @@ registers the marketplace entry, and runs the gate:
 
 By hand, the checklist is:
 
-1. `plugins/<name>/.claude-plugin/plugin.json` — `name` matching the directory, semver `version`,
-   real `description`, `license`.
+1. Create the Claude, OpenAI, and Copilot manifests with matching names and semver versions.
    Do **not** add `"skills": ["./"]` if the plugin has a `skills/` directory; that field is the
    single-skill template shape and breaks auto-discovery.
 2. `plugins/<name>/README.md` — model on `plugins/act-plugin-dev/README.md`.
-3. An entry in `.claude-plugin/marketplace.json` with `source: "./plugins/<name>"`, a `version`
-   matching `plugin.json`, and a `relevance` block.
+3. Add matching entries to all three marketplace files. Keep Claude `relevance` and OpenAI policy
+   metadata intact.
 4. A row in the catalog table in the root `README.md`.
 5. `sh scripts/verify-all.sh` printing `VERIFY-ALL: PASS`.
 6. `claude plugin validate .` clean.

README.md

@@ -7,11 +7,11 @@
 
 # actdata-plugins
 
-ACT Data's institutional knowledge, encoded as installable
-[agent plugins](https://code.claude.com/docs/en/plugin-marketplaces).
+ACT Data's institutional knowledge, encoded as installable agent plugins for Claude Code,
+ChatGPT, Codex, and GitHub Copilot.
 
 ![plugins](https://img.shields.io/badge/plugins-4-00A8E1?labelColor=003767)
-![skills](https://img.shields.io/badge/skills-22-003767)
+![skills](https://img.shields.io/badge/skills-50-003767)
 ![agents](https://img.shields.io/badge/agents-12-147EC2)
 ![runtime](https://img.shields.io/badge/runtime-Bun_·_no_build_step-00817D)
 ![gate](https://img.shields.io/badge/gate-verify--all.sh-58585B)
@@ -35,16 +35,19 @@ ACT Data's institutional knowledge, encoded as installable
 
 ## What this is
 
-A Claude Code plugin marketplace for ACT Data. It holds capability that is true across ACT's
-software teams, packaged so an agent working in an ACT repository behaves the way a well-oriented
-ACT colleague would.
-
-Right now it holds one thing: the toolkit for building the rest of it.
+An agent plugin marketplace for ACT Data. It packages shared engineering and operations knowledge
+for Claude Code, ChatGPT, Codex, and GitHub Copilot.
 
 ## Quick start
 
-```sh
-# inside Claude Code
+> [!TIP]
+> New to this repository? [`docs/onboarding.md`](docs/onboarding.md) is the day-one guide: what a
+> plugin marketplace is, how to get the gate running, what to read in what order, and real first
+> tasks.
+
+### Claude Code
+
+```text
 /plugin marketplace add patterson-agents/actdata-plugins
 /plugin install act-plugin-dev@actdata-plugins
 ```
@@ -66,6 +69,25 @@ Then:
 "how do I write a PreToolUse hook?"                  ← hook-development skill fires
 ```
 
+### ChatGPT and Codex
+
+The ChatGPT desktop app discovers `.agents/plugins/marketplace.json` from the repository. Restart
+the app, open the Plugins Directory, choose **ACT Data Plugins**, and install a plugin. From Codex:
+
+```sh
+codex plugin marketplace add .
+codex plugin add act-plugin-dev@actdata-plugins
+```
+
+### GitHub Copilot
+
+GitHub Copilot CLI reads `.github/plugin/marketplace.json`:
+
+```sh
+copilot plugin marketplace add .
+copilot plugin install act-plugin-dev@actdata-plugins
+```
+
 > [!WARNING]
 > Marketplace names occupy one **flat global namespace**. Registering a second marketplace under
 > the name `actdata-plugins` replaces this one rather than merging with it.
@@ -74,10 +96,10 @@ Then:
 
 | Plugin | What it is | Components |
 |---|---|---|
-| **[`act-plugin-dev`](plugins/act-plugin-dev/)**<br>Development | Everything needed to build a plugin for this marketplace, and the conventions that keep one from breaking at install time. A fork of Claude Code's `plugin-dev`, adapted to ACT's layout, Bun, and marketplace registration. | 7 skills · 3 agents · 1 command |
-| **[`act-platform-engineering`](plugins/act-platform-engineering/)**<br>Operations | Assessment and operations for PostgreSQL, ZFS, Linux hosts and Proxmox VE. Diagnostic commands with green/red criteria, role-based reasoning agents, and incident practice. Reads its host inventory from a site-local settings file and ships no environment identifiers. | 7 skills · 7 agents · 9 commands |
-| **[`act-work-tracking`](plugins/act-work-tracking/)**<br>Workflow | Zoho Projects work tracking and operations reporting: the task-versus-issue distinction, the API's quirks, bulk creation with a credential-free dry run, and the writing conventions that keep issues and reports actionable. | 2 skills · 1 agent · 3 commands |
-| **[`act-gitlab-ci`](plugins/act-gitlab-ci/)**<br>Engineering | GitLab CI/CD and GitLab tooling: Claude Code as a CI job across three providers, the GitLab MCP server, the `glab` CLI, and pipeline standards translated to GitLab. Ships an MCP server and a zero-dependency pipeline checker. | 6 skills · 1 agent · 3 commands · 1 MCP |
+| **[`act-plugin-dev`](plugins/act-plugin-dev/)**<br>Development | Build and review portable plugins while retaining host-specific guidance for commands, agents, hooks, and MCP. | 11 skills · 3 agents · 1 command |
+| **[`act-platform-engineering`](plugins/act-platform-engineering/)**<br>Operations | Assessment and operations for PostgreSQL, ZFS, Linux hosts and Proxmox VE. | 23 skills · 7 agents · 9 commands |
+| **[`act-work-tracking`](plugins/act-work-tracking/)**<br>Workflow | Zoho Projects work tracking and operations reporting. | 6 skills · 1 agent · 3 commands |
+| **[`act-gitlab-ci`](plugins/act-gitlab-ci/)**<br>Engineering | GitLab CI/CD jobs, MCP, authentication, troubleshooting, and pipeline standards. | 10 skills · 1 agent · 3 commands · 1 MCP |
 
 ### Not yet shipped
 
@@ -97,11 +119,14 @@ than failing the build. Once a draft has real content, registering it becomes ma
 
 ```text
 actdata-plugins/
-├── .claude-plugin/
-│   └── marketplace.json          # the catalog agents read -- a plugin is invisible without an entry here
+├── .claude-plugin/marketplace.json       # Claude Code catalog
+├── .agents/plugins/marketplace.json      # ChatGPT and Codex catalog
+├── .github/plugin/marketplace.json       # GitHub Copilot catalog
 ├── plugins/
 │   └── act-plugin-dev/
-│       ├── .claude-plugin/plugin.json
+│       ├── .claude-plugin/plugin.json    # Claude manifest
+│       ├── .codex-plugin/plugin.json     # OpenAI manifest
+│       ├── plugin.json                   # Copilot manifest
 │       ├── README.md
 │       ├── skills/<name>/        # SKILL.md · references/ · examples/ · scripts/
 │       ├── agents/
@@ -111,7 +136,12 @@ actdata-plugins/
 │   ├── check-no-binaries.ts      # fonts / office / archive / oversized-raster validator
 │   ├── verify-all.sh             # the gate battery -- CI and pre-commit both call this
 │   └── tests/run-tests.sh        # TDD fixtures for the two validators
-├── docs/
+├── docs/                         # see docs/README.md for the index
+│   ├── onboarding.md             # start here on day one
+│   ├── architecture.md           # how the marketplace works
+│   ├── verification.md           # every gate check, and what nothing checks
+│   ├── troubleshooting.md        # symptom -> cause -> fix
+│   ├── releasing.md · glossary.md
 │   ├── assets/                   # placeholder wordmark -- see docs/assets/README.md
 │   └── decisions/                # ADRs
 ├── .github/                      # issue + PR templates, ci.yml
@@ -129,8 +159,8 @@ Load-bearing, not stylistic. `scripts/verify-all.sh` enforces the mechanical one
 | **kebab-case everywhere** | Plugin names, skill directory names, command and agent filenames. |
 | **Skill name equals directory name** | `skills/foo/SKILL.md` must carry `name: foo`. Title Case fails the gate. The most common defect when importing a skill from elsewhere. |
 | **Plugins live at `plugins/<name>/`** | `marketplace.json` declares `metadata.pluginRoot: "./plugins"`. |
-| **Register, or it does not exist** | Every shipped plugin needs a `marketplace.json` entry with a `relevance` block. |
-| **Version in two places** | `plugin.json` and the marketplace entry must agree. Bump both together; the gate checks it. |
+| **Register, or it does not exist** | Every shipped plugin needs entries in the Claude, OpenAI, and Copilot marketplaces. |
+| **Version everywhere** | All host manifests and versioned marketplace entries must agree. The gate checks them. |
 | **`${CLAUDE_PLUGIN_ROOT}` stays literal** | Never an absolute path a tool happened to resolve. The gate greps for expanded forms. |
 | **Bun only** | `bun install`, `bun run`, `bunx`, `bun test`. `bun.lock` is the only lockfile; an npm/yarn/pnpm lockfile here is a bug. |
 | **No `/tmp`** | Scratch goes in the repository's gitignored `.tmp/`. |
@@ -206,14 +236,16 @@ files — follows `patterson-corp`, so someone moving between them finds the sam
 
 | File | Purpose |
 |---|---|
+| [`docs/`](docs/README.md) | Full documentation: onboarding, architecture, verification, troubleshooting, releasing, glossary |
+| [`docs/onboarding.md`](docs/onboarding.md) | Start here on day one: environment setup, orientation, and first tasks |
 | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Repository conventions, the gate, and how to add a plugin |
 | [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | Contributor Covenant, adapted for a B2B engineering context |
 | [`SECURITY.md`](SECURITY.md) | Private vulnerability reporting |
 | [`CODEOWNERS`](CODEOWNERS) | A reviewing team for every top-level path |
 | [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/) | Bug, feature, and new-plugin proposal forms |
 | [`.github/workflows/ci.yml`](.github/workflows/ci.yml) | Runs `scripts/verify-all.sh` on every push and pull request |
 | [`.githooks/pre-commit`](.githooks/pre-commit) | The fast local gate (opt in with `git config core.hooksPath .githooks`) |
-| [`docs/decisions/`](docs/decisions/) | ADRs |
+| [`docs/decisions/`](docs/decisions/README.md) | ADRs, with an index and the format |
 
 ## Status and open items