diff --git a/README.md b/README.md index cd17b58..6213c69 100644 --- a/README.md +++ b/README.md @@ -124,22 +124,36 @@ lh doctor # confirm everything is wired Then, in Copilot CLI or VS Code Copilot: ``` -@conductor build a rate limiter for the public API +Use the conductor agent to build a rate limiter for the public API ``` -> **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 **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`). +> **How agent invocation actually works** (per the [official docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/invoke-custom-agents)): +> `@` in Copilot CLI **only mentions files**, never agents. There are three real ways to invoke +> a custom agent: +> 1. `/agent` — opens an interactive picker to browse and select. +> 2. Name it in your prompt — `Use the conductor agent to ...` — Copilot infers which agent you mean. +> 3. `copilot --agent=NAME -p "..."` — force a specific agent non-interactively. > -> 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`, +> **Agent name note:** inside this repo (or any repo where the harness lives natively in +> `.github/agents`), the bare name `conductor` resolves. Once installed as a *plugin* into +> another project, Copilot CLI namespaces **agents only** — the resolvable name becomes +> `redsen-lean-harness:conductor`, `redsen-lean-harness:architect`, etc. (confirmed via +> `copilot --agent `, whose error message lists every real agent name it knows, +> always namespaced for plugin-sourced agents). **Skills are never namespaced** — +> `/fast-track`, `/design`, `/build`, `/verify`, `/onboard`, etc. work as plain slash commands +> regardless of install method (confirmed via `copilot plugins list --kind skill --json`, whose +> `name` fields carry no prefix). +> +> **Known limitation:** a plugin-sourced agent can be launched (by full name in a prompt, or +> via `--agent=plugin-name:agent-name`) even when it isn't proactively *suggested*. Copilot's +> own `copilot plugins list` command documents that "custom agents ... require a live session +> and will be added in a follow-up" — i.e. the CLI's own agent-introspection tooling doesn't +> yet fully cover plugin-contributed agents, which likely also affects what the `/agent` picker +> surfaces and what the model volunteers unprompted. Naming the agent explicitly +> (`Use the conductor agent to ...`) reliably works around this today. +> +> If naming the agent explicitly still fails: 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. diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index a4b1f98..7ab5540 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -28,7 +28,7 @@ path below gets you the behaviour layer; only B and C also give you `lh` on `PAT This is the primary distribution path for **GitHub Copilot CLI** users. It registers the agents/skills/instructions host-wide, so every repo you open in that Copilot CLI account can -use `@conductor`, `/fast-track`, etc. — verified end-to-end on this machine: +invoke its agents (e.g. `redsen-lean-harness:conductor`) and skills (e.g. `/fast-track`) — verified end-to-end on this machine: ```bash # preferred: via the marketplace this repo publishes (no npm publish required, no deprecation warning) @@ -106,22 +106,36 @@ size of the change. **Full pipeline** (new feature, non-trivial change): ``` -@conductor build a rate limiter for the public API +Use the conductor agent to build a rate limiter for the public API ``` -> **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 **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`). +> **How agent invocation actually works** (per the [official docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/invoke-custom-agents)): +> `@` in Copilot CLI **only mentions files**, never agents. There are three real ways to invoke +> a custom agent: +> 1. `/agent` — opens an interactive picker to browse and select. +> 2. Name it in your prompt — `Use the conductor agent to ...` — Copilot infers which agent you mean. +> 3. `copilot --agent=NAME -p "..."` — force a specific agent non-interactively. > -> 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`, +> **Agent name note:** inside this repo (or any repo where the harness lives natively in +> `.github/agents`), the bare name `conductor` resolves. Once installed as a *plugin* into +> another project, Copilot CLI namespaces **agents only** — the resolvable name becomes +> `redsen-lean-harness:conductor`, `redsen-lean-harness:architect`, etc. (confirmed via +> `copilot --agent `, whose error message lists every real agent name it knows, +> always namespaced for plugin-sourced agents). **Skills are never namespaced** — +> `/fast-track`, `/design`, `/build`, `/verify`, `/onboard`, etc. work as plain slash commands +> regardless of install method (confirmed via `copilot plugins list --kind skill --json`, whose +> `name` fields carry no prefix). +> +> **Known limitation:** a plugin-sourced agent can be launched (by full name in a prompt, or +> via `--agent=plugin-name:agent-name`) even when it isn't proactively *suggested*. Copilot's +> own `copilot plugins list` command documents that "custom agents ... require a live session +> and will be added in a follow-up" — i.e. the CLI's own agent-introspection tooling doesn't +> yet fully cover plugin-contributed agents, which likely also affects what the `/agent` picker +> surfaces and what the model volunteers unprompted. Naming the agent explicitly +> (`Use the conductor agent to ...`) reliably works around this today. +> +> If naming the agent explicitly still fails: 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.