diff --git a/.claude-plugin/README.md b/.claude-plugin/README.md new file mode 100644 index 0000000..2ed5ea4 --- /dev/null +++ b/.claude-plugin/README.md @@ -0,0 +1,25 @@ +# Repo-root marketplace alias + +This `marketplace.json` exists ONLY so Claude Code's `"source": "github"` marketplace resolution can find it — +that resolution looks for `.claude-plugin/marketplace.json` at the repo **root**, with no documented way to +point it at a subdirectory (see [`plugin-marketplaces` docs](https://code.claude.com/docs/en/plugin-marketplaces#relative-paths)). + +The actual plugin payload (`commands/`, `agents/`, `hooks/hooks.json`, `scripts/`) still lives under `.claude/`, +because the plugin root IS `.claude/` — this repo dogfoods its own harness (see `.claude/.claude-plugin/README.md` +for the full explanation). This file's single plugin entry points there via a relative path: +`"source": "./.claude"`, which the marketplace-source docs confirm is supported ("for plugins in the same +repository, use a path starting with `./`... paths resolve relative to the marketplace root"). + +**Two `marketplace.json` files, one payload:** +- `.claude/.claude-plugin/marketplace.json` — for the local-clone install method (`/plugin marketplace add + /.claude`), where the plugin root IS the marketplace root (`"source": "./"`). +- `.claude-plugin/marketplace.json` (this file) — for the GitHub-source install method + (`extraKnownMarketplaces` with `"source": "github", "repo": "robercano/ai-project-orchestrator"`), where the + marketplace root is the repo root and the plugin lives one level down (`"source": "./.claude"`). + +Deliberately omits `version`/`author` (present on the other manifest) — a `version` here would *pin* the +plugin to that string, so consumers using this file wouldn't see updates until this file's version is also +bumped. Omitting it lets the plugin track the git commit SHA instead, matching how the local-clone method +already behaves. If you add real content changes to the plugin (agents/commands/scripts/hooks), you don't need +to touch either `marketplace.json` — only `.claude/.claude-plugin/plugin.json`'s version, if you use pinned +versioning at all. diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..3f2eb2a --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,13 @@ +{ + "name": "ai-project-orchestrator", + "owner": { + "name": "Roberto Cano" + }, + "plugins": [ + { + "name": "orchestrator", + "source": "./.claude", + "description": "Multi-agent orchestration harness: fan out sub-tasks to isolated worktree implementers, gate them, and route results through reviewers." + } + ] +} diff --git a/.claude/.claude-plugin/README.md b/.claude/.claude-plugin/README.md index 208f780..ef34b41 100644 --- a/.claude/.claude-plugin/README.md +++ b/.claude/.claude-plugin/README.md @@ -60,12 +60,12 @@ its own `.claude/settings.json`: marketplace named `ai-project-orchestrator`; `enabledPlugins` then enables the `orchestrator` plugin from it, addressed as `@`. -**Known limitation:** Claude Code's documented `"source": "github"` marketplace source resolves -`marketplace.json` at the repo **root** (`.claude-plugin/marketplace.json`), with no documented -field to point it at a subdirectory. This repo's `marketplace.json` instead lives at -`.claude/.claude-plugin/marketplace.json`, matching the plugin-root-is-`.claude/` layout described -above. Until Claude Code supports a subdirectory marketplace source (or this repo additionally -publishes a repo-root alias), the snippet above is the intended shape but may require consumers to -add the marketplace from a local clone instead (e.g. `/plugin marketplace add -/.claude`) rather than the bare GitHub shorthand. Revisit this note if/when -subdirectory marketplace sources land upstream. +**Resolved via a repo-root alias:** Claude Code's `"source": "github"` marketplace source resolves +`marketplace.json` at the repo **root** (`.claude-plugin/marketplace.json`), not a subdirectory. +Since this repo's plugin root is `.claude/`, there's a second, thin manifest at the actual repo root +(`.claude-plugin/marketplace.json`, sibling to this one) whose single plugin entry points back down +via a relative path — `"source": "./.claude"` — which the marketplace-source docs confirm is +supported for same-repo plugins. That root file is what makes the bare GitHub snippet above resolve; +see its own `.claude-plugin/README.md` (at repo root) for the two-manifest rationale. It carries no +`version`/`author` so it never needs to be kept in sync with this file — it just points at this +directory's payload. diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 52d5324..411ec47 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -16,24 +16,10 @@ Budget ~20 minutes. - Your project's actual build/test tooling installed (so the gate commands work). ## Step 1 — Install the `orchestrator` plugin -This template ships as a Claude Code plugin named `orchestrator` (plugin root `.claude/`), with a -`marketplace.json` alongside it. Two ways to add it — lead with the one that works today: +This template ships as a Claude Code plugin named `orchestrator` (plugin root `.claude/`). Two ways to add it: -**The reliable method today — a local clone.** Claude Code's `/plugin marketplace add` accepts a plain -filesystem path, and this repo's marketplace root is `.claude/`: -```bash -git clone https://github.com/robercano/ai-project-orchestrator.git ../ai-project-orchestrator -``` -Then, in Claude Code, inside **your own project**: -``` -/plugin marketplace add ../ai-project-orchestrator/.claude -/plugin install orchestrator@ai-project-orchestrator -``` -(`/plugin` alone opens an interactive picker if you'd rather browse marketplaces/plugins than type the -commands above.) - -**The target flow — a GitHub source (has a known gap today).** The eventual "no local clone" install is to -declare the marketplace straight from GitHub in your project's `.claude/settings.json`: +**GitHub source (no local clone needed).** Declare the marketplace straight from GitHub in your project's +`.claude/settings.json`: ```json { "extraKnownMarketplaces": { @@ -44,12 +30,23 @@ declare the marketplace straight from GitHub in your project's `.claude/settings "enabledPlugins": { "orchestrator@ai-project-orchestrator": true } } ``` -> **Known limitation.** Claude Code's `"source": "github"` marketplace source resolves `marketplace.json` at -> the repo **root** (`.claude-plugin/marketplace.json`). This repo's manifest instead lives at -> `.claude/.claude-plugin/marketplace.json`, because the plugin root is `.claude/`, not the repo root — so the -> bare GitHub shorthand above may not resolve for you yet. Use the local-clone method until this repo ships a -> dedicated, standalone marketplace repo at its root (a deferred follow-up — it can't be created from inside -> this repo). See `.claude/.claude-plugin/README.md` (once cloned) for the up-to-date detail on this gap. +This works because a thin `.claude-plugin/marketplace.json` at the repo **root** (where Claude Code's +`"source": "github"` resolution looks) points at the actual plugin payload under `.claude/` via a relative +path (`"source": "./.claude"`) — see `.claude-plugin/README.md` for why there are two `marketplace.json` +files in this repo. + +**Local clone (alternative, e.g. if you want a pinned/offline copy).** Claude Code's `/plugin marketplace add` +also accepts a plain filesystem path, using `.claude/` directly as the marketplace root: +```bash +git clone https://github.com/robercano/ai-project-orchestrator.git ../ai-project-orchestrator +``` +Then, in Claude Code, inside **your own project**: +``` +/plugin marketplace add ../ai-project-orchestrator/.claude +/plugin install orchestrator@ai-project-orchestrator +``` +(`/plugin` alone opens an interactive picker if you'd rather browse marketplaces/plugins than type the +commands above.) ## Step 2 — Onboard: run `/orchestrator:setup` With the plugin enabled, run: