diff --git a/agents/brief-reviewer.md b/agents/brief-reviewer.md
index 1eead8d..e129fda 100644
--- a/agents/brief-reviewer.md
+++ b/agents/brief-reviewer.md
@@ -5,24 +5,6 @@ description: |
checks completeness, consistency, testability, scope clarity, and
research-plan validity. Catches problems early to avoid wasting tokens on
exploration with a flawed brief.
-
-
- Context: Voyage runs brief review before exploration
- user: "/trekplan --project .claude/projects/2026-04-18-notifications"
- assistant: "Reviewing brief quality before launching exploration agents."
-
- Orchestrator Phase 1b triggers this agent after the brief is available.
-
-
-
-
- Context: User wants to validate a brief before planning
- user: "Review this brief for completeness"
- assistant: "I'll use the brief-reviewer agent to check brief quality."
-
- Brief review request triggers the agent.
-
-
model: opus
color: magenta
tools: ["Read", "Glob", "Grep"]
@@ -302,3 +284,23 @@ information that would strengthen the brief. List only if actionable.}
files or technologies exist, but deep code analysis is not your job.
- **Research-plan checks are load-bearing.** A brief with `research_status: pending`
and missing research files is a scope hazard — flag it as a major risk.
+
+## When to use — examples
+
+
+Context: Voyage runs brief review before exploration
+user: "/trekplan --project .claude/projects/2026-04-18-notifications"
+assistant: "Reviewing brief quality before launching exploration agents."
+
+Orchestrator Phase 1b triggers this agent after the brief is available.
+
+
+
+
+Context: User wants to validate a brief before planning
+user: "Review this brief for completeness"
+assistant: "I'll use the brief-reviewer agent to check brief quality."
+
+Brief review request triggers the agent.
+
+
diff --git a/agents/plan-critic.md b/agents/plan-critic.md
index 5c08407..b2aa6ed 100644
--- a/agents/plan-critic.md
+++ b/agents/plan-critic.md
@@ -3,24 +3,6 @@ name: plan-critic
description: |
Use this agent when an implementation plan needs adversarial review — it finds
problems, never praises.
-
-
- Context: Voyage adversarial review phase
- user: "/trekplan Implement WebSocket real-time updates"
- assistant: "Launching plan-critic to stress-test the implementation plan."
-
- Phase 9 of trekplan triggers this agent to review the generated plan.
-
-
-
-
- Context: User wants a plan reviewed before execution
- user: "Review this plan and find problems"
- assistant: "I'll use the plan-critic agent to perform adversarial review."
-
- Plan review request triggers the agent.
-
-
model: opus
effort: high
color: red
@@ -297,3 +279,23 @@ short, stable id for the finding class (used for exact-match dedup). Emit
Be specific. Reference exact plan sections, step numbers, and file paths.
Never use "generally" or "usually" — cite the specific problem in this specific plan.
+
+## When to use — examples
+
+
+Context: Voyage adversarial review phase
+user: "/trekplan Implement WebSocket real-time updates"
+assistant: "Launching plan-critic to stress-test the implementation plan."
+
+Phase 9 of trekplan triggers this agent to review the generated plan.
+
+
+
+
+Context: User wants a plan reviewed before execution
+user: "Review this plan and find problems"
+assistant: "I'll use the plan-critic agent to perform adversarial review."
+
+Plan review request triggers the agent.
+
+
diff --git a/agents/research-scout.md b/agents/research-scout.md
index 09efc9a..9f3e8e8 100644
--- a/agents/research-scout.md
+++ b/agents/research-scout.md
@@ -3,24 +3,6 @@ name: research-scout
description: |
Use this agent when the implementation task involves unfamiliar technologies, external
APIs, or libraries where official documentation and known issues should be checked.
-
-
- Context: Voyage detects external technology in the task
- user: "/trekplan Integrate Stripe payment processing"
- assistant: "Launching research-scout to find Stripe documentation and best practices."
-
- Phase 5 of trekplan conditionally triggers this agent when external tech is detected.
-
-
-
-
- Context: User needs research before implementation
- user: "Research the best approach for WebSocket scaling"
- assistant: "I'll use the research-scout agent to find documentation and best practices."
-
- Research request for external technology triggers the agent.
-
-
model: opus
color: blue
tools: ["WebSearch", "WebFetch", "Read"]
@@ -118,3 +100,23 @@ End with a summary table:
- **Date everything.** Documentation ages — the reader needs to judge freshness.
- **Flag conflicts.** If official docs and community advice disagree, report both.
- **Stay focused.** Research only what the task needs. Do not explore tangentially.
+
+## When to use — examples
+
+
+Context: Voyage detects external technology in the task
+user: "/trekplan Integrate Stripe payment processing"
+assistant: "Launching research-scout to find Stripe documentation and best practices."
+
+Phase 5 of trekplan conditionally triggers this agent when external tech is detected.
+
+
+
+
+Context: User needs research before implementation
+user: "Research the best approach for WebSocket scaling"
+assistant: "I'll use the research-scout agent to find documentation and best practices."
+
+Research request for external technology triggers the agent.
+
+
diff --git a/agents/risk-assessor.md b/agents/risk-assessor.md
index 16a2531..7fd14a2 100644
--- a/agents/risk-assessor.md
+++ b/agents/risk-assessor.md
@@ -3,24 +3,6 @@ name: risk-assessor
description: |
Use this agent when you need to identify risks, edge cases, failure modes, and
technical debt that could affect an implementation task.
-
-
- Context: Voyage exploration phase identifies potential risks
- user: "/trekplan Migrate database from PostgreSQL to MongoDB"
- assistant: "Launching risk-assessor to identify failure modes and edge cases for this migration."
-
- Phase 5 of trekplan triggers this agent to find risks before planning begins.
-
-
-
-
- Context: User wants to understand risks before a change
- user: "What could go wrong with this refactor?"
- assistant: "I'll use the risk-assessor agent to map risks and failure modes."
-
- Risk analysis request triggers the agent.
-
-
model: opus
effort: high
color: yellow
@@ -106,3 +88,23 @@ Produce a prioritized risk list:
**Low** = minor concerns worth noting
Follow with a narrative section expanding on each Critical and High risk.
+
+## When to use — examples
+
+
+Context: Voyage exploration phase identifies potential risks
+user: "/trekplan Migrate database from PostgreSQL to MongoDB"
+assistant: "Launching risk-assessor to identify failure modes and edge cases for this migration."
+
+Phase 5 of trekplan triggers this agent to find risks before planning begins.
+
+
+
+
+Context: User wants to understand risks before a change
+user: "What could go wrong with this refactor?"
+assistant: "I'll use the risk-assessor agent to map risks and failure modes."
+
+Risk analysis request triggers the agent.
+
+
diff --git a/agents/scope-guardian.md b/agents/scope-guardian.md
index bd3f425..c36fd3a 100644
--- a/agents/scope-guardian.md
+++ b/agents/scope-guardian.md
@@ -3,24 +3,6 @@ name: scope-guardian
description: |
Use this agent when you need to verify that an implementation plan matches its
requirements — catches scope creep and scope gaps.
-
-
- Context: Voyage adversarial review phase checks scope alignment
- user: "/trekplan Add caching to the API layer"
- assistant: "Launching scope-guardian to verify plan matches requirements."
-
- Phase 9 of trekplan triggers this agent alongside plan-critic.
-
-
-
-
- Context: User wants to verify plan doesn't do too much or too little
- user: "Does this plan match what I asked for?"
- assistant: "I'll use the scope-guardian agent to check scope alignment."
-
- Scope verification request triggers the agent.
-
-
model: opus
color: magenta
tools: ["Read", "Glob", "Grep"]
@@ -144,3 +126,23 @@ One object per scope-creep / gap / dependency finding. `file`/`line` point at th
plan step (or the brief requirement) the finding concerns; `rule_key` is a short,
stable id for the finding class (used for exact-match dedup against plan-critic).
Emit `"findings": []` when the plan is fully aligned.
+
+## When to use — examples
+
+
+Context: Voyage adversarial review phase checks scope alignment
+user: "/trekplan Add caching to the API layer"
+assistant: "Launching scope-guardian to verify plan matches requirements."
+
+Phase 9 of trekplan triggers this agent alongside plan-critic.
+
+
+
+
+Context: User wants to verify plan doesn't do too much or too little
+user: "Does this plan match what I asked for?"
+assistant: "I'll use the scope-guardian agent to check scope alignment."
+
+Scope verification request triggers the agent.
+
+
diff --git a/agents/session-decomposer.md b/agents/session-decomposer.md
index fb82457..96526ab 100644
--- a/agents/session-decomposer.md
+++ b/agents/session-decomposer.md
@@ -4,24 +4,6 @@ description: |
Use this agent to decompose an trekplan into self-contained headless sessions.
Reads a plan file, analyzes step dependencies, groups steps into sessions,
identifies parallelism, and generates session specs + dependency graph + launch script.
-
-
- Context: User wants to run a plan across multiple headless sessions
- user: "/trekplan --decompose .claude/plans/trekplan-2026-04-06-auth-refactor.md"
- assistant: "Launching session-decomposer to split the plan into headless sessions."
-
- The --decompose flag triggers this agent to analyze and split the plan.
-
-
-
-
- Context: User has a large plan and wants parallel execution
- user: "Split this plan into sessions I can run in parallel"
- assistant: "I'll use the session-decomposer to identify parallel session groups."
-
- Plan decomposition request for parallel headless execution.
-
-
model: opus
color: green
tools: ["Read", "Glob", "Grep", "Write"]
@@ -310,3 +292,23 @@ After all sessions complete, run:
wrong sequentiality only costs time.
- **Verify file existence.** Use Glob to confirm that files referenced in the
plan actually exist before assigning them to sessions.
+
+## When to use — examples
+
+
+Context: User wants to run a plan across multiple headless sessions
+user: "/trekplan --decompose .claude/plans/trekplan-2026-04-06-auth-refactor.md"
+assistant: "Launching session-decomposer to split the plan into headless sessions."
+
+The --decompose flag triggers this agent to analyze and split the plan.
+
+
+
+
+Context: User has a large plan and wants parallel execution
+user: "Split this plan into sessions I can run in parallel"
+assistant: "I'll use the session-decomposer to identify parallel session groups."
+
+Plan decomposition request for parallel headless execution.
+
+