open/voyage
1
0
Fork 0
Code Issues Releases 2 Activity

refactor(agents): relocate example blocks to body (reviewer/planning agents)

Browse source
This commit is contained in:
Kjell Tore Guttormsen 2026-06-29 10:19:24 +02:00
commit b148b6f8b8
6 changed files with 120 additions and 108 deletions
Download patch file Download diff file Expand all files Collapse all files

38
agents/brief-reviewer.md
View file

@ -5,24 +5,6 @@ description: |
checks completeness, consistency, testability, scope clarity, and checks completeness, consistency, testability, scope clarity, and
research-plan validity. Catches problems early to avoid wasting tokens on research-plan validity. Catches problems early to avoid wasting tokens on
exploration with a flawed brief. exploration with a flawed brief.
<example>
Context: Voyage runs brief review before exploration
user: "/trekplan --project .claude/projects/2026-04-18-notifications"
assistant: "Reviewing brief quality before launching exploration agents."
<commentary>
Orchestrator Phase 1b triggers this agent after the brief is available.
</commentary>
</example>
<example>
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."
<commentary>
Brief review request triggers the agent.
</commentary>
</example>
model: opus model: opus
color: magenta color: magenta
tools: ["Read", "Glob", "Grep"] 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. files or technologies exist, but deep code analysis is not your job.
- **Research-plan checks are load-bearing.** A brief with `research_status: pending` - **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. and missing research files is a scope hazard — flag it as a major risk.
## When to use — examples
<example>
Context: Voyage runs brief review before exploration
user: "/trekplan --project .claude/projects/2026-04-18-notifications"
assistant: "Reviewing brief quality before launching exploration agents."
<commentary>
Orchestrator Phase 1b triggers this agent after the brief is available.
</commentary>
</example>
<example>
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."
<commentary>
Brief review request triggers the agent.
</commentary>
</example>

38
agents/plan-critic.md
View file

@ -3,24 +3,6 @@ name: plan-critic
description: | description: |
Use this agent when an implementation plan needs adversarial review — it finds Use this agent when an implementation plan needs adversarial review — it finds
problems, never praises. problems, never praises.
<example>
Context: Voyage adversarial review phase
user: "/trekplan Implement WebSocket real-time updates"
assistant: "Launching plan-critic to stress-test the implementation plan."
<commentary>
Phase 9 of trekplan triggers this agent to review the generated plan.
</commentary>
</example>
<example>
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."
<commentary>
Plan review request triggers the agent.
</commentary>
</example>
model: opus model: opus
effort: high effort: high
color: red 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. Be specific. Reference exact plan sections, step numbers, and file paths.
Never use "generally" or "usually" — cite the specific problem in this specific plan. Never use "generally" or "usually" — cite the specific problem in this specific plan.
## When to use — examples
<example>
Context: Voyage adversarial review phase
user: "/trekplan Implement WebSocket real-time updates"
assistant: "Launching plan-critic to stress-test the implementation plan."
<commentary>
Phase 9 of trekplan triggers this agent to review the generated plan.
</commentary>
</example>
<example>
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."
<commentary>
Plan review request triggers the agent.
</commentary>
</example>

38
agents/research-scout.md
View file

@ -3,24 +3,6 @@ name: research-scout
description: | description: |
Use this agent when the implementation task involves unfamiliar technologies, external Use this agent when the implementation task involves unfamiliar technologies, external
APIs, or libraries where official documentation and known issues should be checked. APIs, or libraries where official documentation and known issues should be checked.
<example>
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."
<commentary>
Phase 5 of trekplan conditionally triggers this agent when external tech is detected.
</commentary>
</example>
<example>
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."
<commentary>
Research request for external technology triggers the agent.
</commentary>
</example>
model: opus model: opus
color: blue color: blue
tools: ["WebSearch", "WebFetch", "Read"] tools: ["WebSearch", "WebFetch", "Read"]
@ -118,3 +100,23 @@ End with a summary table:
- **Date everything.** Documentation ages — the reader needs to judge freshness. - **Date everything.** Documentation ages — the reader needs to judge freshness.
- **Flag conflicts.** If official docs and community advice disagree, report both. - **Flag conflicts.** If official docs and community advice disagree, report both.
- **Stay focused.** Research only what the task needs. Do not explore tangentially. - **Stay focused.** Research only what the task needs. Do not explore tangentially.
## When to use — examples
<example>
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."
<commentary>
Phase 5 of trekplan conditionally triggers this agent when external tech is detected.
</commentary>
</example>
<example>
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."
<commentary>
Research request for external technology triggers the agent.
</commentary>
</example>

38
agents/risk-assessor.md
View file

@ -3,24 +3,6 @@ name: risk-assessor
description: | description: |
Use this agent when you need to identify risks, edge cases, failure modes, and Use this agent when you need to identify risks, edge cases, failure modes, and
technical debt that could affect an implementation task. technical debt that could affect an implementation task.
<example>
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."
<commentary>
Phase 5 of trekplan triggers this agent to find risks before planning begins.
</commentary>
</example>
<example>
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."
<commentary>
Risk analysis request triggers the agent.
</commentary>
</example>
model: opus model: opus
effort: high effort: high
color: yellow color: yellow
@ -106,3 +88,23 @@ Produce a prioritized risk list:
**Low** = minor concerns worth noting **Low** = minor concerns worth noting
Follow with a narrative section expanding on each Critical and High risk. Follow with a narrative section expanding on each Critical and High risk.
## When to use — examples
<example>
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."
<commentary>
Phase 5 of trekplan triggers this agent to find risks before planning begins.
</commentary>
</example>
<example>
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."
<commentary>
Risk analysis request triggers the agent.
</commentary>
</example>

38
agents/scope-guardian.md
View file

@ -3,24 +3,6 @@ name: scope-guardian
description: | description: |
Use this agent when you need to verify that an implementation plan matches its Use this agent when you need to verify that an implementation plan matches its
requirements — catches scope creep and scope gaps. requirements — catches scope creep and scope gaps.
<example>
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."
<commentary>
Phase 9 of trekplan triggers this agent alongside plan-critic.
</commentary>
</example>
<example>
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."
<commentary>
Scope verification request triggers the agent.
</commentary>
</example>
model: opus model: opus
color: magenta color: magenta
tools: ["Read", "Glob", "Grep"] 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, 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). stable id for the finding class (used for exact-match dedup against plan-critic).
Emit `"findings": []` when the plan is fully aligned. Emit `"findings": []` when the plan is fully aligned.
## When to use — examples
<example>
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."
<commentary>
Phase 9 of trekplan triggers this agent alongside plan-critic.
</commentary>
</example>
<example>
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."
<commentary>
Scope verification request triggers the agent.
</commentary>
</example>

38
agents/session-decomposer.md
View file

@ -4,24 +4,6 @@ description: |
Use this agent to decompose an trekplan into self-contained headless sessions. Use this agent to decompose an trekplan into self-contained headless sessions.
Reads a plan file, analyzes step dependencies, groups steps into sessions, Reads a plan file, analyzes step dependencies, groups steps into sessions,
identifies parallelism, and generates session specs + dependency graph + launch script. identifies parallelism, and generates session specs + dependency graph + launch script.
<example>
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."
<commentary>
The --decompose flag triggers this agent to analyze and split the plan.
</commentary>
</example>
<example>
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."
<commentary>
Plan decomposition request for parallel headless execution.
</commentary>
</example>
model: opus model: opus
color: green color: green
tools: ["Read", "Glob", "Grep", "Write"] tools: ["Read", "Glob", "Grep", "Write"]
@ -310,3 +292,23 @@ After all sessions complete, run:
wrong sequentiality only costs time. wrong sequentiality only costs time.
- **Verify file existence.** Use Glob to confirm that files referenced in the - **Verify file existence.** Use Glob to confirm that files referenced in the
plan actually exist before assigning them to sessions. plan actually exist before assigning them to sessions.
## When to use — examples
<example>
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."
<commentary>
The --decompose flag triggers this agent to analyze and split the plan.
</commentary>
</example>
<example>
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."
<commentary>
Plan decomposition request for parallel headless execution.
</commentary>
</example>