docs+harness: packaging phase 4 — marketplace.json + plugin install/update/migration docs (#39) - #48
Merged
Merged
Conversation
Adds .claude/.claude-plugin/marketplace.json listing the orchestrator plugin (mirrors plugin.json's name/version/description/author), and documents the extraKnownMarketplaces + enabledPlugins settings.json snippet a consuming project adds to install it. Notes the known limitation that Claude Code's GitHub marketplace source resolves marketplace.json at repo root, not a subdirectory, given this repo's plugin-root-is-.claude/ layout. Part of issue #39 (packaging phase 4).
The marketplace top-level name must equal the marketplace part of `<plugin>@<marketplace>` addressing. Rename it from `orchestrator` to `ai-project-orchestrator` (the repo/marketplace), keeping the plugin entry's own `name` as `orchestrator` (the plugin id) — this now agrees with the README's extraKnownMarketplaces key and enabledPlugins entry. Also add marketplace.json to the self build gate's JSON-parse loop so a malformed marketplace.json is caught by gates going forward.
…N guide Reframes onboarding around installing the `orchestrator` Claude Code plugin (marketplace + enable) and running /orchestrator:setup, instead of cloning this repo as a template. Leads with the working local-clone install method, presents the settings.json github-source snippet as the target flow, and documents the known marketplace.json-at-repo-root discovery gap. Renames command references to their namespaced /orchestrator:* form, adds an "Updating the plugin" section (marketplace update + /orchestrator:sync, clearly marked forthcoming per issue #38). Adds MIGRATION.md for existing hand-copied adopters: what to delete (harness now carried by the plugin), what to keep (adapter/CLAUDE.md/workflow/CI files), how to enable the plugin, and a verification checklist. Part of issue #39 (packaging phase 4).
…; sync is now shipped (#46) - Union-merge docs/USAGE.md: keep #48's plugin-flow rewrite structure, fold in main's phone-testing section for /orchestrator:test-pr (renamed from the unnamespaced /test-pr to match this branch's convention). - Update USAGE.md and MIGRATION.md: /orchestrator:sync is no longer "forthcoming" — it shipped in #46 — so document it as available and point at .claude/skills/sync/SKILL.md instead of telling readers to fall back to /orchestrator:setup.
robercano
approved these changes
Jul 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Packaging phase 4: marketplace manifest + plugin install/update docs
Closes #39.
Delivers the marketplace source manifest and rewrites the user docs around the plugin lifecycle, plus a migration guide for existing hand-copied
.claude/adopters.What changed
Harness (
.claude/).claude/.claude-plugin/marketplace.json— new Claude Code marketplace manifest. Top-level marketplace nameai-project-orchestrator; single plugin entryorchestrator(source: "./"), mirroringplugin.json(name/version/description/author)..claude/.claude-plugin/README.md— added an "Enabling in a consuming project" section with theextraKnownMarketplaces+enabledPluginssnippet for a consumer's.claude/settings.json, plus an honest note on the discovery limitation (see below)..claude/self/checks.sh— the selfbuildgate now also JSON-validatesmarketplace.json, so future malformed edits are caught (closes a coverage gap flagged in review).Docs (
docs/)docs/GETTING_STARTED.md— rewritten around the plugin flow: install (marketplace add + enable) →/orchestrator:setup(the onboarding skill that scaffolds the adapter/CLAUDE.md/fan-out workflow/CI) → normal work → update → re-stamp. Keeps the substance of what setup collects.docs/USAGE.md— opens with plugin-lifecycle context, command references namespaced to/orchestrator:*, and adds an "Updating the plugin" section.docs/MIGRATION.md— new. For adopters who hand-copied.claude/: what to delete (generic machinery the plugin now carries), what to keep (theirgates.jsonadapter,CLAUDE.md,feature-fanout.js, CI workflow), how to enable the marketplace, and a verification checklist.Accuracy notes (verified against origin/main, not assumed)
/orchestrator:setupskill (.claude/skills/setup/SKILL.md, merged in Packaging phase 2: /orchestrator:setup — scaffold the non-distributable residue on first run #37);/orchestrator:setup-orchestratorremains a legacy pointer./orchestrator:syncdoes not exist onmainyet — it is planned for packaging phase 3 (Packaging phase 3: /orchestrator:sync — re-stamp managed files after plugin updates #38). Docs mention it only as forthcoming, never as a working command, with/orchestrator:setup's scaffold step as the interim re-stamp path.Known limitation (documented honestly in the docs)
A
github-source marketplace entry makes Claude Code look formarketplace.jsonat the repo root (.claude-plugin/marketplace.json), but this repo keeps the plugin root at.claude/, so the manifest lives at.claude/.claude-plugin/marketplace.json. The reliably-working install method today is a local clone:/plugin marketplace add <clone>/.claude. The settings.json github snippet is presented as the target flow with this caveat.Deferred follow-up
Validation
build/lint/testall pass (GATES_FILE=.claude/self/gates.json).all): correctness = approve, tests = approve (tests re-approved on the combined tree once marketplace.json + docs coexist).🤖 Generated with Claude Code
https://claude.ai/code/session_01VHX2JEvD8oQGs2R9YhtSLL