Docs/add documentation tree

[patterson-ai]

This pull request introduces multi-host plugin marketplace support for ChatGPT, Codex, and GitHub Copilot, and updates repository documentation and conventions to reflect the expanded scope. The main changes include adding new marketplace catalog files, synchronizing plugin metadata and versioning, and updating documentation to guide contributors on supporting all hosts.

Marketplace and Plugin Catalogs:

• Added .agents/plugins/marketplace.json for ChatGPT and Codex, and .github/plugin/marketplace.json for GitHub Copilot, each listing all shipped plugins with synchronized metadata and version numbers. [1] [2]
• Updated .claude-plugin/marketplace.json to version 0.2.0 and synchronized plugin versions for all entries. [1] [2] [3] [4] [5]

Documentation Updates:

• Expanded README.md to describe support and installation instructions for Claude Code, ChatGPT, Codex, and Copilot, with updated plugin/skill/agent counts and catalog tables. [1] [2] [3] [4] [5] [6]
• Added references to new documentation files and improved navigation in the docs directory.

Repository Conventions and Contribution Process:

• Updated CONTRIBUTING.md to require registration and version synchronization of plugins across all three marketplace files and host manifests. [1] [2] [3]
• Added .github/copilot-instructions.md with repository-wide instructions for plugin authors, including naming, registration, and tooling requirements.
• Updated mechanical and manual checklist tables in both README.md and CONTRIBUTING.md to reflect new registration/versioning rules.

These changes ensure that all plugins are discoverable and installable across Claude Code, ChatGPT, Codex, and GitHub Copilot, and that repository standards and documentation are clear and consistent for all contributors.

[Copilot]

Pull request overview

Adds a full documentation tree and expands the marketplace to support Claude Code, ChatGPT, Codex, and GitHub Copilot.

Changes:

• Adds cross-runtime manifests, catalogs, portable workflow skills, and compatibility validation.
• Introduces onboarding, architecture, verification, troubleshooting, release, glossary, and ADR documentation.
• Updates plugin versions, component counts, configuration paths, and repository guidance.

Reviewed changes

Copilot reviewed 91 out of 92 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
scripts/verify-all.sh	Adds compatibility gate
scripts/tests/run-tests.sh	Tests compatibility validator
scripts/check-marketplace-compat.ts	Validates cross-host metadata
README.md	Documents multi-host marketplace
plugins/act-work-tracking/skills/zoho-projects/SKILL.md	Updates configuration path
plugins/act-work-tracking/skills/zoho-projects/references/zoho-api.md	Updates configuration reference
plugins/act-work-tracking/skills/weekly-status/SKILL.md	Adds portable workflow
plugins/act-work-tracking/skills/reporting-analyst/SKILL.md	Adds portable agent adapter
plugins/act-work-tracking/skills/ops-reporting/SKILL.md	Removes skill version
plugins/act-work-tracking/skills/draft-task/SKILL.md	Adds portable workflow
plugins/act-work-tracking/skills/draft-issue/SKILL.md	Adds portable workflow
plugins/act-work-tracking/README.md	Updates counts and configuration
plugins/act-work-tracking/plugin.json	Adds Copilot manifest
plugins/act-work-tracking/.codex-plugin/plugin.json	Adds OpenAI manifest
plugins/act-work-tracking/.claude-plugin/plugin.json	Bumps plugin version
plugins/act-plugin-dev/skills/skill-reviewer/SKILL.md	Adds portable reviewer
plugins/act-plugin-dev/skills/skill-development/SKILL.md	Removes skill version
plugins/act-plugin-dev/skills/plugin-validator/SKILL.md	Adds portable validator
plugins/act-plugin-dev/skills/plugin-structure/SKILL.md	Removes skill version
plugins/act-plugin-dev/skills/plugin-settings/SKILL.md	Removes skill version
plugins/act-plugin-dev/skills/mcp-integration/SKILL.md	Removes skill version
plugins/act-plugin-dev/skills/hook-development/SKILL.md	Removes skill version
plugins/act-plugin-dev/skills/create-plugin/SKILL.md	Adds portable creation workflow
plugins/act-plugin-dev/skills/command-development/SKILL.md	Removes skill version
plugins/act-plugin-dev/skills/agent-development/SKILL.md	Removes skill version
plugins/act-plugin-dev/skills/agent-creator/SKILL.md	Adds portable agent adapter
plugins/act-plugin-dev/README.md	Updates component inventory
plugins/act-plugin-dev/plugin.json	Adds Copilot manifest
plugins/act-plugin-dev/agents/skill-reviewer.md	Shortens agent description
plugins/act-plugin-dev/agents/plugin-validator.md	Shortens agent description
plugins/act-plugin-dev/agents/agent-creator.md	Shortens agent description
plugins/act-plugin-dev/.codex-plugin/plugin.json	Adds OpenAI manifest
plugins/act-plugin-dev/.claude-plugin/plugin.json	Bumps plugin version
plugins/act-platform-engineering/skills/zfs-storage/SKILL.md	Removes skill version
plugins/act-platform-engineering/skills/triage-pg-host/SKILL.md	Adds portable workflow
plugins/act-platform-engineering/skills/sysadmin/SKILL.md	Adds portable agent adapter
plugins/act-platform-engineering/skills/sre/SKILL.md	Adds portable agent adapter
plugins/act-platform-engineering/skills/security-engineer/SKILL.md	Adds portable agent adapter
plugins/act-platform-engineering/skills/proxmox-virtualization/SKILL.md	Removes skill version
plugins/act-platform-engineering/skills/postgres-operations/SKILL.md	Updates configuration path
plugins/act-platform-engineering/skills/platform-engineer/SKILL.md	Adds portable agent adapter
plugins/act-platform-engineering/skills/observability/SKILL.md	Removes skill version
plugins/act-platform-engineering/skills/observability-status/SKILL.md	Adds portable workflow
plugins/act-platform-engineering/skills/observability-engineer/SKILL.md	Adds portable agent adapter
plugins/act-platform-engineering/skills/linux-host-tuning/SKILL.md	Removes skill version
plugins/act-platform-engineering/skills/infrastructure-inventory/SKILL.md	Updates inventory path
plugins/act-platform-engineering/skills/incident-response/SKILL.md	Removes skill version
plugins/act-platform-engineering/skills/incident-responder/SKILL.md	Adds portable agent adapter
plugins/act-platform-engineering/skills/dba/SKILL.md	Adds portable agent adapter
plugins/act-platform-engineering/skills/assess-zfs/SKILL.md	Adds portable workflow
plugins/act-platform-engineering/skills/assess-replication/SKILL.md	Adds portable workflow
plugins/act-platform-engineering/skills/assess-pve/SKILL.md	Adds portable workflow
plugins/act-platform-engineering/skills/assess-postgres/SKILL.md	Adds portable workflow
plugins/act-platform-engineering/skills/assess-kernel/SKILL.md	Adds portable workflow
plugins/act-platform-engineering/skills/assess-disks/SKILL.md	Adds portable workflow
plugins/act-platform-engineering/skills/assess-backups/SKILL.md	Adds portable workflow
plugins/act-platform-engineering/README.md	Updates counts and configuration
plugins/act-platform-engineering/plugin.json	Adds Copilot manifest
plugins/act-platform-engineering/.codex-plugin/plugin.json	Adds OpenAI manifest
plugins/act-platform-engineering/.claude-plugin/plugin.json	Bumps plugin version
plugins/act-gitlab-ci/skills/setup-claude-job/SKILL.md	Adds portable workflow
plugins/act-gitlab-ci/skills/review-pipeline/SKILL.md	Adds portable workflow
plugins/act-gitlab-ci/skills/pipeline-standards/SKILL.md	Removes skill version
plugins/act-gitlab-ci/skills/pipeline-security-reviewer/SKILL.md	Adds portable reviewer
plugins/act-gitlab-ci/skills/glab/SKILL.md	Removes skill version
plugins/act-gitlab-ci/skills/gitlab-mcp-server/SKILL.md	Removes skill version
plugins/act-gitlab-ci/skills/connect-gitlab-mcp/SKILL.md	Adds portable workflow
plugins/act-gitlab-ci/skills/claude-code-ci-jobs/SKILL.md	Removes skill version
plugins/act-gitlab-ci/skills/ci-troubleshooting/SKILL.md	Removes skill version
plugins/act-gitlab-ci/skills/ci-auth-providers/SKILL.md	Removes skill version
plugins/act-gitlab-ci/README.md	Updates skill inventory
plugins/act-gitlab-ci/plugin.json	Adds Copilot manifest
plugins/act-gitlab-ci/.codex-plugin/plugin.json	Adds OpenAI manifest
plugins/act-gitlab-ci/.claude-plugin/plugin.json	Bumps plugin version
package.json	Updates repository description
docs/verification.md	Documents repository gate
docs/troubleshooting.md	Adds troubleshooting reference
docs/releasing.md	Adds release guidance
docs/README.md	Adds documentation index
docs/onboarding.md	Adds onboarding guide
docs/glossary.md	Defines repository terminology
docs/decisions/README.md	Adds ADR index
docs/decisions/0004-derived-pipeline-standards.md	Records standards decision
docs/decisions/0003-three-plugin-split.md	Records plugin split
docs/decisions/0002-config-driven-plugins.md	Records configuration decision
docs/architecture.md	Documents marketplace architecture
CONTRIBUTING.md	Adds multi-host contribution rules
.gitignore	Ignores portable settings
.github/plugin/marketplace.json	Adds Copilot catalog
.github/copilot-instructions.md	Adds Copilot repository guidance
.claude-plugin/marketplace.json	Bumps Claude catalog versions
.agents/plugins/marketplace.json	Adds OpenAI catalog

Suppressed comments (5)

docs/releasing.md:110

• There are now five versioned locations for a plugin (three manifests plus Claude and Copilot catalog entries), so “both files” contradicts the checklist above and can leave a release inconsistent.

Bump both files in the **same commit**. A commit where they disagree is a commit that fails the gate,
which means a bisect lands on a broken build for reasons unrelated to what is being bisected.

docs/onboarding.md:128

• The same PR expands act-plugin-dev to 11 skills, so this onboarding inventory’s count of 7 is stale.

| `act-plugin-dev` | The toolkit for building plugins here: 7 skills, 3 review agents, the guided creation workflow | It is both the tooling you will use and the reference implementation you will copy |

docs/onboarding.md:153

• This new guide still teaches .claude/<plugin-name>.local.md as the primary location, while the PR establishes .agents/<plugin-name>.local.md as primary with .claude only as fallback. That sends new users to the legacy path.

**Config-driven, not hardcoded.** The operational plugins ship **no** environment identifiers: no
hostnames, addresses, database names or portal IDs, not even as defaults or fallbacks. Those come
from a gitignored `.claude/<plugin-name>.local.md` the operator writes. With no settings file
present, the commands ask rather than guess.

docs/onboarding.md:273

• This “real open task” is completed by the same PR: all three descriptions were replaced and no longer end with bare Examples:. Leaving it in onboarding directs a newcomer to work that no longer exists; replace it with an actually open task or remove it.

**1. Fix the frontmatter parse errors in `act-plugin-dev`.**
All three agents (`agent-creator`, `plugin-validator`, `skill-reviewer`) end their `description:`
with a bare `Examples:`, which is a YAML plain-scalar error. Confirm with
`claude plugin validate plugins/act-plugin-dev`. The fix is quoting; the value is that you will
understand the failure mode described in [The gate](#the-gate) by having repaired it.

docs/architecture.md:245

• The architecture still declares the legacy .claude file as the settings contract, conflicting with the new .agents-first convention used by the changed skills and READMEs. Make .agents/<plugin-name>.local.md primary, document .claude as the fallback, and mention both ignore rules.

Site-specific values live in a gitignored file the operator writes:

```text
.claude/<plugin-name>.local.md

.gitignore carries .claude/*.local.md so one can never be committed by accident.

</details>



---

💡 <a href="/patterson-agents/actdata-plugins/new/main?filename=.github/skills/code-review/SKILL.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add a `code-review` agent skill</a> or configure MCP servers for context-aware, tailored reviews. <a href="https://docs.github.com/en/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review#mcp-servers-and-agent-skills" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn more in the docs.</a>

[Copilot]

Fixed. The script now requires the path argument (exits 2 with usage message when omitted), validates that the resolved path is a directory (exits 2 on missing/unreadable), and wraps the plugins/ readdirSync call in a try/catch that also exits 2 if that directory is missing or unreadable — consistent with the exit-2 contract.

[Copilot]

Added negative test cases covering: wrong source directory in the Claude catalog, host-only stale entries in Copilot and OpenAI catalogs, missing OpenAI manifest, missing Copilot manifest, missing OpenAI policy metadata, malformed JSON in a catalog, and the exit-2 invocation contract (missing path and no-args).

[claude]

The for loop opened at line 36 is never closed — this file is a syntax error.

The plugin-directory loop starts here:

actdata-plugins/scripts/check-marketplace-compat.ts

Lines 35 to 37 in af0de9f

	for (const dir of readdirSync(join(root, "plugins"), { withFileTypes: true })) {
	if (!dir.isDirectory()) continue;

and the file ends at line 84 still at brace depth 1 (40 { vs 39 }; every other block — json(), the two pre-loop for blocks, and the inner for/if blocks at 48-57, 64-67, 75-77, 78-80 — balances). Bun throws SyntaxError: Unexpected end of input, so the script never runs. Two gate steps break as a result:

• scripts/verify-all.sh step 5 always takes the fail branch, so VERIFY-ALL: PASS can never print. Per CLAUDE.md, "It must print VERIFY-ALL: PASS before any change is done."
• The new expect_exit 0 ... "matching host manifests pass" assertion in scripts/tests/run-tests.sh fails too, which is step 1 of the same gate.

The brace belongs before line 82, not at EOF. Lines 82-84 reference only the module-scope problems and claudeEntries, and N plugin(s) agree across Claude, OpenAI, and Copilot is a whole-run summary. Closing at EOF instead would leave the report/exit block inside the loop, which reprints the INFO line per directory and — because the continue statements at lines 37, 40, and 66 skip it — would let the script fall off the end and exit 0 when the last-scanned entry hits one, reporting PASS with recorded problems silently discarded.

Suggested change

	}

[Copilot]

Fixed in commit af0de9f~1's successor. Added the closing } before the summary/exit block so the for loop over plugin directories is properly closed. The summary and process.exit lines are now outside the loop.

[claude]

Code review

One inline finding posted on scripts/check-marketplace-compat.ts. Two further findings are about commit metadata and have no diff line to anchor to, so they are here.

Commit hygiene

Five commits on this branch — 33047a4, 7e4c51a, 14f734a, 1a01d94, d838b5b — each carry the trailer:

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

CLAUDE.md states:

• No AI attribution in commits or pull requests. No Claude-Session: trailers, no "Generated with Claude Code" footers, no AI co-author lines.

The same five commits are all titled Potential fix for pull request finding, with no type(scope): prefix, against:

• Conventional commits, branch off main, never commit to main directly.

The branch's other two commits (docs: add a documentation tree under docs/, feat(marketplace): support ChatGPT, Codex and GitHub Copilot hosts) do comply. Squashing or rewording the five autofix commits before merge resolves both.

Checked and clean

Manifest versions agree at 0.2.0 across all three per-plugin manifests and all three catalogs for every plugin; all four plugins remain registered in .claude-plugin/marketplace.json; every new SKILL.md frontmatter name: matches its directory in kebab-case; every ../../agents/*.md and ../../commands/*.md adapter link resolves; no expanded ${CLAUDE_PLUGIN_ROOT}, no emoji on ACT-authored surfaces, no npm/yarn/pnpm, no /tmp scratch.

[claude]

This new doc asserts the repository is at 0.1.0 in four places, but the same PR bumps all four plugins and the marketplace top-level version to 0.2.0. The guide ships factually wrong on arrival:

• L5-8 — "everything sits at 0.1.0"
• L33-35 — "Current state: every one of them is 0.1.0."
• L80-82 — "Everything is 0.1.0, and under semver..."
• L152-154 — "It is 0.1.0 and has never moved" — written about the exact value this PR moves

Contradicted by this PR's own changes to .claude-plugin/marketplace.json, where the top-level version and all four plugin entries now read 0.2.0.

Suggest updating all four sites to 0.2.0 and rewording L152-154, since the "has never moved" premise for that [TBD] no longer holds. Not offered as a committable suggestion because the fix spans four separate locations.

[claude]

This warm-up task is already done by this same PR, so a new contributor following it will find nothing to fix.

All three agents' description: fields were rewritten in this PR to short quoted one-liners, and the Examples: plain-scalar error along with the <example> blocks is gone:

• agents/agent-creator.md#L2-L4
• agents/plugin-validator.md#L2-L4
• agents/skill-reviewer.md#L2-L4

Suggest replacing this warm-up with an item that is actually open, and renumbering the [TBD] audit that follows. Left without a committable suggestion since it needs a replacement task chosen rather than a mechanical edit.

[claude]

This new troubleshooting entry prescribes exactly what the same PR removes. It says an agent goes undelegated because the description "lacks concrete <example> blocks" and that the fix is "Three examples, each with a <commentary>" — but this PR strips precisely those three-example blocks from all three act-plugin-dev agents (agent-creator.md#L2-L4, plugin-validator.md#L2-L4, skill-reviewer.md#L2-L4).

docs/glossary.md#L9-L13, also added here, makes it a hard requirement: frontmatter "must carry name, description with <example> blocks" and "the examples are load-bearing rather than illustrative."

The PR asserts both positions at once. It is also internally inconsistent across plugins — act-platform-engineering/agents/dba.md#L2-L12 still uses a description: | block scalar carrying <example> and <commentary>, the pattern this doc recommends.

Worth resolving one way: either restore the examples on the three agents using a block scalar (which fixes the YAML error without dropping the delegation signal), or update this entry and the glossary to reflect that short descriptions are now the convention.

[claude]

This new architecture reference documents only .claude/<plugin-name>.local.md, the path this same PR demotes to a legacy fallback. A contributor following it writes the deprecated file.

The PR establishes .agents/<plugin>.local.md as primary everywhere else — e.g. zoho-projects/SKILL.md#L12-L15 calls .claude/... the "legacy" path, and .gitignore gains .agents/*.local.md alongside the existing entry.

Same staleness in three other files added here: docs/onboarding.md#L151-L153, docs/glossary.md#L115-L117, and docs/decisions/0002-config-driven-plugins.md#L41-L44.

Suggest documenting .agents/<plugin-name>.local.md as the path with .claude/ noted as the legacy fallback, and updating the .gitignore sentence to mention both globs. No committable suggestion since the fix spans four files.

[claude]

Code review

Six issues found. Five are posted as inline comments; the sixth has no diff line to anchor to and is described below.

AI co-author trailers in commit history

Five commits in this PR carry an AI co-author trailer:

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Affected commits, all titled "Potential fix for pull request finding": 33047a4, 7e4c51a, 14f734a, 1a01d94, d838b5b.

This is prohibited by CLAUDE.md#L57-L59:

No AI attribution in commits or pull requests. No Claude-Session: trailers, no "Generated with Claude Code" footers, no AI co-author lines.

The rule sits under "Conventions checked in review", not the mechanically gated table, so scripts/verify-all.sh does not catch it. GitHub squash-merge preserves co-author trailers by default, so merging as-is carries the attribution onto main permanently. A rebase stripping the trailers before merge resolves it.

Summary of inline findings

File	Issue
docs/releasing.md	Asserts 0.1.0 in four places; this PR bumps everything to 0.2.0, including the value described as having "never moved"
docs/onboarding.md	Warm-up task 1 prescribes a fix this PR already applied
docs/onboarding.md	Calls 0001-fork-plugin-dev.md "the one ADR" while this PR adds three more plus an index
docs/troubleshooting.md	Requires three <example> blocks per agent description; this PR deletes exactly those from three agents, and docs/glossary.md states them as a must
docs/architecture.md	Documents only the .claude/ config path this PR demotes to a legacy fallback

Checked and clean

• scripts/check-marketplace-compat.ts parses and its logic is sound: braces balance, path resolution via resolve(root, ...) is correct, a missing catalog produces problems rather than silently passing, and process.exit(1) precedes the success line. Step 5 in scripts/verify-all.sh is wired like its siblings so failures propagate through fail() to exit "$overall".
• All three marketplace catalogs and all twelve per-plugin manifests agree on name and version at 0.2.0. The OpenAI catalog carries no per-entry version, which the compat checker correctly does not require.
• Every SKILL.md frontmatter name: equals its directory name in kebab-case, including all new adapter skills, and every ../../commands/*.md and ../../agents/*.md target exists.
• No emoji, no npm/yarn/pnpm, no /tmp scratch, no expanded ${CLAUDE_PLUGIN_ROOT}, no "skills": ["./"], no new binaries, and tracked bytes are well under the 2 MiB budget.