From 7f7ce8c5e377c4dabf1bb403d02420fbdd7544a7 Mon Sep 17 00:00:00 2001
From: Nikolas Hor <116851567+nikolasdehor@users.noreply.github.com>
Date: Thu, 12 Mar 2026 00:46:56 -0300
Subject: [PATCH] docs: document which agent triggers require arguments (#1908)

Adds a "Trigger Types" section to the agents reference page
explaining the difference between workflow triggers (no arguments)
and conversational triggers (arguments required). Lists all
Technical Writer triggers that expect user-provided input with
examples of proper usage.

Fixes #1682
---
 docs/reference/agents.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/reference/agents.md b/docs/reference/agents.md
index be7ab8ecb..072bdb84e 100644
--- a/docs/reference/agents.md
+++ b/docs/reference/agents.md
@@ -26,3 +26,33 @@ This page lists the default BMM (Agile suite) agents that install with BMad Meth
 | Quick Flow Solo Dev (Barry) | `bmad-master`        | `QS`, `QD`, `CR`                   | Quick Spec, Quick Dev, Code Review                                                                  |
 | UX Designer (Sally)         | `bmad-ux-designer`   | `CU`                               | Create UX Design                                                                                    |
 | Technical Writer (Paige)    | `bmad-tech-writer`   | `DP`, `WD`, `US`, `MG`, `VD`, `EC` | Document Project, Write Document, Update Standards, Mermaid Generate, Validate Doc, Explain Concept |
+
+## Trigger Types
+
+Agent menu triggers use two different invocation types. Knowing which type a trigger uses helps you provide the right input.
+
+### Workflow triggers (no arguments needed)
+
+Most triggers load a structured workflow file. Type the trigger code and the agent starts the workflow, prompting you for input at each step.
+
+Examples: `CP` (Create PRD), `DS` (Dev Story), `CA` (Create Architecture), `QS` (Quick Spec)
+
+### Conversational triggers (arguments required)
+
+Some triggers start a free-form conversation instead of a structured workflow. These expect you to describe what you need alongside the trigger code.
+
+| Agent | Trigger | What to provide |
+| --- | --- | --- |
+| Technical Writer (Paige) | `WD` | Description of the document to write |
+| Technical Writer (Paige) | `US` | Preferences or conventions to add to standards |
+| Technical Writer (Paige) | `MG` | Diagram description and type (sequence, flowchart, etc.) |
+| Technical Writer (Paige) | `VD` | Document to validate and focus areas |
+| Technical Writer (Paige) | `EC` | Concept name to explain |
+
+**Example:**
+
+```text
+WD Write a deployment guide for our Docker setup
+MG Create a sequence diagram showing the auth flow
+EC Explain how the module system works
+```