From c66dd3a58e5dd72aeac5abe542f9c855fdf44154 Mon Sep 17 00:00:00 2001 From: fullsend-code Date: Tue, 26 May 2026 20:01:42 +0000 Subject: [PATCH 1/2] docs(#1544): add ADR 0040 for /fs- slash command prefix Create ADR 0040 documenting the decision to namespace all fullsend slash commands with the /fs- prefix. This decision was previously captured only as a one-liner in the glossary, causing two separate issues (#1473, #1477) where agents proposed changes that contradicted the undocumented choice. The ADR records context (multiple AI tools claim bare slash command verbs), the decision (/fs- prefix for all commands), rejected alternatives (bare commands, /fullsend- prefix), and consequences. Also adds a note to ADR 0002 clarifying that its bare command examples (/triage, /implement, /review) are illustrative and superseded by the /fs- prefix convention. Note: make lint could not run (Go toolchain download permission denied in sandbox). This is a docs-only change with no Go code affected. Closes #1544 Signed-off-by: fullsend-code --- docs/ADRs/0002-initial-fullsend-design.md | 6 ++ .../ADRs/0040-fs-prefix-for-slash-commands.md | 78 +++++++++++++++++++ 2 files changed, 84 insertions(+) create mode 100644 docs/ADRs/0040-fs-prefix-for-slash-commands.md diff --git a/docs/ADRs/0002-initial-fullsend-design.md b/docs/ADRs/0002-initial-fullsend-design.md index db53f6c5c2..c0cd045878 100644 --- a/docs/ADRs/0002-initial-fullsend-design.md +++ b/docs/ADRs/0002-initial-fullsend-design.md @@ -54,6 +54,12 @@ We propose adopting the following **reference workflow** as the mental model for **Slash commands (illustrative, configurable per repo):** +> **Note:** The bare command names below (`/triage`, `/implement`, +> `/review`) are illustrative. All production fullsend commands use the +> `/fs-` prefix (e.g., `/fs-triage`, `/fs-code`, `/fs-review`) to avoid +> collisions with other AI tools. See +> [ADR 0040](0040-fs-prefix-for-slash-commands.md). + - `/triage` — run or re-run triage on the issue **from scratch** (clears **`duplicate`** and other triage/ downstream labels at run start; **reopens** the issue if **`closed`**—see **When a triage run starts**) - `/implement` — hand off to the **Implementation** stage (implementation agent; expects **`ready-to-implement`** or forces with human ack — policy per repo) - `/review` — enqueue review swarm for current PR head diff --git a/docs/ADRs/0040-fs-prefix-for-slash-commands.md b/docs/ADRs/0040-fs-prefix-for-slash-commands.md new file mode 100644 index 0000000000..ed98f38896 --- /dev/null +++ b/docs/ADRs/0040-fs-prefix-for-slash-commands.md @@ -0,0 +1,78 @@ +--- +title: "40. Use /fs- prefix for all slash commands" +status: Accepted +relates_to: + - agent-architecture +topics: + - slash-commands + - namespace + - ux +--- + +# 40. Use /fs- prefix for all slash commands + +Date: 2026-05-26 + +## Status + +Accepted + +Supersedes the bare command examples in +[ADR 0002](0002-initial-fullsend-design.md). + +## Context + +Multiple AI-powered tools respond to slash commands in GitHub issue and +PR comments. GitHub Copilot uses `/fix` and `/review`; other bots use +similar bare verbs. When fullsend agents listen for the same bare +commands (e.g., `/triage`, `/implement`, `/review`), any of these tools +may intercept the command, causing unintended side effects or ambiguous +behavior. + +The original design document ([ADR 0002](0002-initial-fullsend-design.md)) +used bare commands as illustrative examples. As the ecosystem matured, +the collision risk became concrete — Copilot and other tools already +claim several of the same verbs. + +Two separate issues (#1473, #1477) were filed proposing workarounds for +command collisions, both unaware that a namespacing decision had already +been made but was recorded only in the +[glossary](../glossary.md#slash-command). This ADR formalizes that +decision so it is discoverable alongside other architectural choices. + +## Options + +### A. Bare commands (`/triage`, `/implement`, `/review`) + +- Pro: shorter to type, familiar syntax. +- Con: collides with Copilot and other tools that claim the same verbs. + +### B. `/fs-` prefixed commands (`/fs-triage`, `/fs-code`, `/fs-review`) + +- Pro: unique namespace; no known collision with existing tools. +- Pro: short enough to remain ergonomic. +- Con: users must learn the prefix. + +### C. `/fullsend-` prefixed commands + +- Pro: unambiguous namespace. +- Con: too verbose for frequent interactive use. + +## Decision + +All fullsend slash commands use the `/fs-` prefix +(e.g., `/fs-triage`, `/fs-code`, `/fs-review`). The entry point's slash +command parser must recognize only `/fs-`-prefixed commands and ignore +bare verbs. + +## Consequences + +- Fullsend commands will not collide with Copilot, other AI bots, or + future GitHub-native slash commands. +- Users and documentation must use the `/fs-` prefix; bare commands are + not recognized. +- The glossary already reflects this convention. ADR 0002's illustrative + examples of bare commands (`/triage`, `/implement`, `/review`) are + superseded by this decision. +- Agent prompt instructions, harness definitions, and dispatch + configuration that reference slash commands must use the `/fs-` form. From 7b5a89f8fb8adeafbf2359687e8479a496803fa3 Mon Sep 17 00:00:00 2001 From: fullsend-fix Date: Wed, 27 May 2026 06:37:50 +0000 Subject: [PATCH 2/2] fix(docs): renumber ADR 0040 to 0042 to resolve collision ADR 0040 (org-pool-for-parallel-e2e-tests) and ADR 0041 already exist on main. Renumber the /fs- prefix ADR to 0042 to avoid ambiguity. Updates the filename, title, heading, and cross-reference in ADR 0002. Addresses review feedback on #1549 Co-Authored-By: Claude Opus 4.6 Signed-off-by: fullsend-fix --- docs/ADRs/0002-initial-fullsend-design.md | 2 +- ...slash-commands.md => 0042-fs-prefix-for-slash-commands.md} | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) rename docs/ADRs/{0040-fs-prefix-for-slash-commands.md => 0042-fs-prefix-for-slash-commands.md} (96%) diff --git a/docs/ADRs/0002-initial-fullsend-design.md b/docs/ADRs/0002-initial-fullsend-design.md index c0cd045878..73f99ac401 100644 --- a/docs/ADRs/0002-initial-fullsend-design.md +++ b/docs/ADRs/0002-initial-fullsend-design.md @@ -58,7 +58,7 @@ We propose adopting the following **reference workflow** as the mental model for > `/review`) are illustrative. All production fullsend commands use the > `/fs-` prefix (e.g., `/fs-triage`, `/fs-code`, `/fs-review`) to avoid > collisions with other AI tools. See -> [ADR 0040](0040-fs-prefix-for-slash-commands.md). +> [ADR 0042](0042-fs-prefix-for-slash-commands.md). - `/triage` — run or re-run triage on the issue **from scratch** (clears **`duplicate`** and other triage/ downstream labels at run start; **reopens** the issue if **`closed`**—see **When a triage run starts**) - `/implement` — hand off to the **Implementation** stage (implementation agent; expects **`ready-to-implement`** or forces with human ack — policy per repo) diff --git a/docs/ADRs/0040-fs-prefix-for-slash-commands.md b/docs/ADRs/0042-fs-prefix-for-slash-commands.md similarity index 96% rename from docs/ADRs/0040-fs-prefix-for-slash-commands.md rename to docs/ADRs/0042-fs-prefix-for-slash-commands.md index ed98f38896..813808b77a 100644 --- a/docs/ADRs/0040-fs-prefix-for-slash-commands.md +++ b/docs/ADRs/0042-fs-prefix-for-slash-commands.md @@ -1,5 +1,5 @@ --- -title: "40. Use /fs- prefix for all slash commands" +title: "42. Use /fs- prefix for all slash commands" status: Accepted relates_to: - agent-architecture @@ -9,7 +9,7 @@ topics: - ux --- -# 40. Use /fs- prefix for all slash commands +# 42. Use /fs- prefix for all slash commands Date: 2026-05-26