From 27a7573b0684f7335a831636ab9fd01a74b4ed68 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Mon, 29 Jun 2026 10:16:48 +0200 Subject: [PATCH] refactor(agents): relocate example blocks to body (retrieval agents) --- agents/architecture-mapper.md | 38 ++++++++++++++++++----------------- agents/convention-scanner.md | 38 ++++++++++++++++++----------------- agents/dependency-tracer.md | 38 ++++++++++++++++++----------------- agents/git-historian.md | 38 ++++++++++++++++++----------------- agents/task-finder.md | 38 ++++++++++++++++++----------------- agents/test-strategist.md | 38 ++++++++++++++++++----------------- 6 files changed, 120 insertions(+), 108 deletions(-) diff --git a/agents/architecture-mapper.md b/agents/architecture-mapper.md index 448f7e1..9a5e6ad 100644 --- a/agents/architecture-mapper.md +++ b/agents/architecture-mapper.md @@ -3,24 +3,6 @@ name: architecture-mapper description: | Use this agent when you need deep architecture analysis of a codebase — structure, tech stack, patterns, anti-patterns, and key abstractions. - - - Context: Voyage exploration phase needs architecture overview - user: "/trekplan Add authentication to the API" - assistant: "Launching architecture-mapper to analyze codebase structure and patterns." - - Phase 5 of trekplan triggers this agent for every codebase size. - - - - - Context: User wants to understand an unfamiliar codebase - user: "Map out the architecture of this project" - assistant: "I'll use the architecture-mapper agent to analyze the codebase structure." - - Direct architecture analysis request triggers the agent. - - model: opus effort: medium color: cyan @@ -104,3 +86,23 @@ Structure your report with clear sections matching the 7 areas above. Include: - A brief "Architecture Summary" paragraph at the top (3-4 sentences) Do NOT include raw file listings — synthesize and organize the information. + +## When to use — examples + + +Context: Voyage exploration phase needs architecture overview +user: "/trekplan Add authentication to the API" +assistant: "Launching architecture-mapper to analyze codebase structure and patterns." + +Phase 5 of trekplan triggers this agent for every codebase size. + + + + +Context: User wants to understand an unfamiliar codebase +user: "Map out the architecture of this project" +assistant: "I'll use the architecture-mapper agent to analyze the codebase structure." + +Direct architecture analysis request triggers the agent. + + diff --git a/agents/convention-scanner.md b/agents/convention-scanner.md index 686715f..3f6f868 100644 --- a/agents/convention-scanner.md +++ b/agents/convention-scanner.md @@ -5,24 +5,6 @@ description: | Produces a structured conventions report covering naming, directory layout, import style, error handling, test patterns, git commit style, and documentation patterns. Uses concrete examples from the codebase. - - - Context: Voyage exploration phase for a medium+ codebase - user: "/trekplan Add authentication to the API" - assistant: "Launching convention-scanner to discover coding patterns." - - Phase 5 of trekplan triggers this agent for medium+ codebases (50+ files). - - - - - Context: User wants to understand a project's conventions before contributing - user: "What are the coding conventions in this project?" - assistant: "I'll use the convention-scanner agent to analyze the codebase." - - Direct convention discovery request triggers the agent. - - model: opus color: yellow tools: ["Read", "Glob", "Grep", "Bash"] @@ -159,3 +141,23 @@ Based on existing conventions, new code should: than scanning everything. - **Stay focused.** This is about conventions — not architecture, dependencies, or risks. Those are handled by other agents. + +## When to use — examples + + +Context: Voyage exploration phase for a medium+ codebase +user: "/trekplan Add authentication to the API" +assistant: "Launching convention-scanner to discover coding patterns." + +Phase 5 of trekplan triggers this agent for medium+ codebases (50+ files). + + + + +Context: User wants to understand a project's conventions before contributing +user: "What are the coding conventions in this project?" +assistant: "I'll use the convention-scanner agent to analyze the codebase." + +Direct convention discovery request triggers the agent. + + diff --git a/agents/dependency-tracer.md b/agents/dependency-tracer.md index ed0f90e..25c9d57 100644 --- a/agents/dependency-tracer.md +++ b/agents/dependency-tracer.md @@ -3,24 +3,6 @@ name: dependency-tracer description: | Use this agent when you need to trace import chains, map data flow, or understand how modules connect and what side effects they produce. - - - Context: Voyage needs to understand module relationships for a task - user: "/trekplan Refactor the payment processing pipeline" - assistant: "Launching dependency-tracer to map module connections and data flow." - - Phase 5 of trekplan triggers this agent to trace dependencies relevant to the task. - - - - - Context: User needs to understand impact of changing a module - user: "What would break if I change the User model?" - assistant: "I'll use the dependency-tracer agent to trace all dependents of the User model." - - Impact analysis request triggers the agent. - - model: opus effort: medium color: blue @@ -93,3 +75,23 @@ Structure as: 6. **Risk Flags** — circular deps, tight coupling, hidden side effects Include file paths and line numbers for every finding. + +## When to use — examples + + +Context: Voyage needs to understand module relationships for a task +user: "/trekplan Refactor the payment processing pipeline" +assistant: "Launching dependency-tracer to map module connections and data flow." + +Phase 5 of trekplan triggers this agent to trace dependencies relevant to the task. + + + + +Context: User needs to understand impact of changing a module +user: "What would break if I change the User model?" +assistant: "I'll use the dependency-tracer agent to trace all dependents of the User model." + +Impact analysis request triggers the agent. + + diff --git a/agents/git-historian.md b/agents/git-historian.md index a28230e..2c90a51 100644 --- a/agents/git-historian.md +++ b/agents/git-historian.md @@ -3,24 +3,6 @@ name: git-historian description: | Use this agent to analyze git history for planning context — recent changes, code ownership, hot files, and active branches relevant to the task. - - - Context: Voyage exploration phase needs git context - user: "/trekplan Refactor the database layer" - assistant: "Launching git-historian to check recent changes and ownership of DB code." - - Phase 2 of trekplan triggers this agent for every codebase size. - - - - - Context: User wants to understand change history before modifying code - user: "Who has been changing the auth module recently?" - assistant: "I'll use the git-historian agent to analyze ownership and change patterns." - - Git history analysis request triggers the agent. - - model: opus effort: medium color: yellow @@ -122,3 +104,23 @@ Run `git status --short` to check for: are risks the planner needs to know about. - **Use relative time.** "2 days ago" is more useful than a raw timestamp. - **Never expose email addresses.** Use author names only. + +## When to use — examples + + +Context: Voyage exploration phase needs git context +user: "/trekplan Refactor the database layer" +assistant: "Launching git-historian to check recent changes and ownership of DB code." + +Phase 2 of trekplan triggers this agent for every codebase size. + + + + +Context: User wants to understand change history before modifying code +user: "Who has been changing the auth module recently?" +assistant: "I'll use the git-historian agent to analyze ownership and change patterns." + +Git history analysis request triggers the agent. + + diff --git a/agents/task-finder.md b/agents/task-finder.md index 81ef3a3..fee90ea 100644 --- a/agents/task-finder.md +++ b/agents/task-finder.md @@ -4,24 +4,6 @@ description: | Use this agent to find all files, functions, types, and interfaces directly related to the planning task. Replaces generic Explore agents with targeted, structured code discovery. - - - Context: Voyage exploration phase needs task-relevant code - user: "/trekplan Add authentication to the API" - assistant: "Launching task-finder to locate auth-related code, endpoints, and models." - - Phase 2 of trekplan triggers this agent for every codebase size. - - - - - Context: User wants to find code related to a specific feature - user: "Find all code related to payment processing" - assistant: "I'll use the task-finder agent to locate payment-related code." - - Direct code discovery request triggers the agent. - - model: opus effort: medium color: green @@ -146,3 +128,23 @@ Structure your report using three tiers: - **Stay focused on the task.** Do not inventory the entire codebase — only what is relevant to implementing the specific task. - **Never read file contents that look like secrets or credentials.** + +## When to use — examples + + +Context: Voyage exploration phase needs task-relevant code +user: "/trekplan Add authentication to the API" +assistant: "Launching task-finder to locate auth-related code, endpoints, and models." + +Phase 2 of trekplan triggers this agent for every codebase size. + + + + +Context: User wants to find code related to a specific feature +user: "Find all code related to payment processing" +assistant: "I'll use the task-finder agent to locate payment-related code." + +Direct code discovery request triggers the agent. + + diff --git a/agents/test-strategist.md b/agents/test-strategist.md index b95e0cb..756b7f1 100644 --- a/agents/test-strategist.md +++ b/agents/test-strategist.md @@ -3,24 +3,6 @@ name: test-strategist description: | Use this agent when you need to design a test strategy for an implementation task — discovers existing patterns, maps coverage gaps, and recommends what tests to write. - - - Context: Voyage exploration phase for medium+ codebase - user: "/trekplan Add rate limiting to the API" - assistant: "Launching test-strategist to analyze existing test patterns and design test coverage." - - Phase 5 of trekplan triggers this agent for medium and large codebases. - - - - - Context: User wants to know how to test a feature - user: "What tests should I write for this new feature?" - assistant: "I'll use the test-strategist agent to analyze existing patterns and recommend tests." - - Test planning request triggers the agent. - - model: opus color: green tools: ["Read", "Glob", "Grep", "Bash"] @@ -95,3 +77,23 @@ For each test, provide: 5. **Test Dependencies** — fixtures, mocks, or setup code to create first Do NOT write test code. Describe what each test should verify and which patterns to follow. + +## When to use — examples + + +Context: Voyage exploration phase for medium+ codebase +user: "/trekplan Add rate limiting to the API" +assistant: "Launching test-strategist to analyze existing test patterns and design test coverage." + +Phase 5 of trekplan triggers this agent for medium and large codebases. + + + + +Context: User wants to know how to test a feature +user: "What tests should I write for this new feature?" +assistant: "I'll use the test-strategist agent to analyze existing patterns and recommend tests." + +Test planning request triggers the agent. + +