feat(harness): repo-root marketplace alias so GitHub-source install resolves

.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
+  <path-to-clone>/.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.

.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."
+    }
+  ]
+}

.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 `<plugin-name>@<marketplace-name>`.
 
-**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
-<path-to-clone>/.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.

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: