From d74cb58821a6e51240d4e9d14a5e8b616c9386fe Mon Sep 17 00:00:00 2001 From: Giancarmine Salucci Date: Thu, 10 Sep 2026 01:34:26 +0200 Subject: [PATCH] docs: verify and clarify agent-namespacing vs skill-namespacing, add stale-session note --- README.md | 16 +++++++++++++--- docs/QUICKSTART.md | 16 +++++++++++++--- 2 files changed, 26 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 9559b38..cd17b58 100644 --- a/README.md +++ b/README.md @@ -129,9 +129,19 @@ Then, in Copilot CLI or VS Code Copilot: > **Agent name note:** inside this repo (or any repo where the harness lives natively in > `.github/agents`), `@conductor` works unprefixed. Once installed as a *plugin* into another -> project, Copilot CLI namespaces plugin agents to avoid name collisions — use -> `@redsen-lean-harness:conductor` (tab-complete via `/agent` shows the full list). Skills -> (`/fast-track`, `/design`, etc.) are not namespaced and work either way. +> project, Copilot CLI namespaces **agents only** — use `@redsen-lean-harness:conductor`, +> `@redsen-lean-harness:architect`, etc. (`/agent` lists the full namespaced set). **Skills are +> never namespaced** — `/fast-track`, `/design`, `/build`, `/verify`, `/onboard`, etc. work as +> plain slash commands regardless of install method. Verified with +> `copilot plugins list --kind skill --json` (skill `name` fields have no prefix) vs. +> `copilot --agent ` (the "available" list always shows plugin agents as +> `plugin-name:agent-name`). +> +> If `@redsen-lean-harness:conductor` (or any plugin skill) still isn't found: the plugin was +> likely loaded before a fix landed. Run +> `copilot plugin marketplace update redsen && copilot plugin update redsen-lean-harness`, +> then start a **new** `copilot` session — an already-running session keeps the plugin +> snapshot it loaded at startup and won't pick up the update until restarted. For a small brownfield change, skip the ceremony: diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index c8fabdb..a4b1f98 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -111,9 +111,19 @@ size of the change. > **Agent name note:** inside this repo (or any repo where the harness lives natively in > `.github/agents`), `@conductor` works unprefixed. Once installed as a *plugin* into another -> project, Copilot CLI namespaces plugin agents to avoid name collisions — use -> `@redsen-lean-harness:conductor` (tab-complete via `/agent` shows the full list). Skills -> (`/fast-track`, `/design`, etc.) are not namespaced and work either way. +> project, Copilot CLI namespaces **agents only** — use `@redsen-lean-harness:conductor`, +> `@redsen-lean-harness:architect`, etc. (`/agent` lists the full namespaced set). **Skills are +> never namespaced** — `/fast-track`, `/design`, `/build`, `/verify`, `/onboard`, etc. work as +> plain slash commands regardless of install method. Verified with +> `copilot plugins list --kind skill --json` (skill `name` fields have no prefix) vs. +> `copilot --agent ` (the "available" list always shows plugin agents as +> `plugin-name:agent-name`). +> +> If `@redsen-lean-harness:conductor` (or any plugin skill) still isn't found: the plugin was +> likely loaded before a fix landed. Run +> `copilot plugin marketplace update redsen && copilot plugin update redsen-lean-harness`, +> then start a **new** `copilot` session — an already-running session keeps the plugin +> snapshot it loaded at startup and won't pick up the update until restarted. This runs the whole pipeline: `interrogator` asks clarifying questions with recommended answers (you must answer before it proceeds — this is a deliberate gate), `architect` writes