From 8aae370bdb219d5c5518343f70b15bd4f4536091 Mon Sep 17 00:00:00 2001 From: Julian lechner Date: Thu, 8 Oct 2026 15:43:30 +0200 Subject: [PATCH] fix(agents): align research tools and clarify role boundaries --- adapters/claude/capabilities.tsv | 4 ++-- docs/agents.md | 12 +++++++++--- scripts/tests/test-shell-packages.ps1 | 5 +++++ scripts/tests/test-shell-packages.sh | 5 +++++ shared/agents/architect/agent.yml | 2 +- shared/agents/architect/instructions.md | 2 ++ shared/agents/implementer/agent.yml | 2 +- shared/agents/researcher/agent.yml | 2 +- shared/agents/researcher/instructions.md | 2 ++ shared/agents/reviewer/agent.yml | 2 +- shared/agents/reviewer/instructions.md | 6 ++++-- shared/agents/verifier/agent.yml | 2 +- 12 files changed, 34 insertions(+), 12 deletions(-) diff --git a/adapters/claude/capabilities.tsv b/adapters/claude/capabilities.tsv index fe16c13..def117c 100644 --- a/adapters/claude/capabilities.tsv +++ b/adapters/claude/capabilities.tsv @@ -1,6 +1,6 @@ role tools -architect Read,Grep,Glob,WebFetch,WebSearch -researcher Read,Grep,Glob,WebFetch,WebSearch +architect Read,Grep,Glob,WebFetch,WebSearch,__SHELL__ +researcher Read,Grep,Glob,WebFetch,WebSearch,__SHELL__ reviewer Read,Grep,Glob,__SHELL__ verifier Read,Grep,Glob,__SHELL__ implementer Read,Grep,Glob,Edit,Write,__SHELL__ diff --git a/docs/agents.md b/docs/agents.md index cdb0331..9cfda14 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -2,14 +2,20 @@ The five shared agents are logical roles, not mandatory steps. -- `implementer` executes the smallest complete engineering change and performs self-review. -- `researcher` investigates code, patterns, evidence, alternatives, and unknowns without modifying implementation code by default. -- `architect` evaluates technical boundaries, dependencies, interfaces, constraints, and design options. +- `implementer` implements scoped features and fixes with proportionate tests and self-review. +- `researcher` answers questions about repository behavior, external documentation, and unknowns with source evidence, without modifying implementation code by default. +- `architect` compares design options and recommends technical boundaries and interfaces before implementation; implementation changes require an explicit assignment. - `verifier` supplies execution evidence from relevant tests, builds, checks, generated output, and behavior reproduction. It inspects implementation only to choose checks and does not review the diff for general correctness. - `reviewer` starts with the actual diff and changed symbols, then examines necessary callers, dependencies, tests, and contracts for analytical correctness. It does not run tests, builds, or runtime checks; it reports missing execution evidence. Use only the roles that are likely to improve the outcome. Choose `researcher`, `reviewer`, and `verifier` based on the task's uncertainty, complexity, risk, blast radius, and verification value; none runs automatically. The agent may make evidence-based, reversible technical decisions. Ask the user when technical choices remain materially uncertain or when business behavior, user-visible behavior, UI, UX, APIs, database models, configuration formats, compatibility behavior, or other high-impact decisions are ambiguous or open to interpretation. +## Research tools + +Claude's [capability manifest](../adapters/claude/capabilities.tsv) gives `architect` and `researcher` file inspection, web research, and the package's shell tool (`PowerShell` or `Bash`). Shell access supports mandatory semantic search and Context7 research through MCPorter. Their role instructions scope shell use to inspection and research; this is an instruction-level boundary, not a read-only shell sandbox. + +The `reviewer` may inspect Git diffs and run required research commands through its shell tool. Tests, builds, and behavior reproduction belong to the `verifier` or parent. Missing execution evidence remains an explicit review gap. Codex receives the same role instructions; the Claude tool manifest is client-specific. + ## Coordination The main agent owns task state, decisions, and progress. Subagents report to their parent. The parent forwards only relevant conclusions, references, risks, and constraints; direct peer communication requires a concrete dependency and parent coordination. Subagents cannot create further subagents. diff --git a/scripts/tests/test-shell-packages.ps1 b/scripts/tests/test-shell-packages.ps1 index 2502bf2..394fbb8 100644 --- a/scripts/tests/test-shell-packages.ps1 +++ b/scripts/tests/test-shell-packages.ps1 @@ -46,6 +46,11 @@ foreach ($shell in @('powershell','bash')) { if (@(Get-ChildItem "$package/agents" -File).Count -ne $sourceAgentCount) { throw "Missing agents in $package" } $expectedReviewerShellTool = if ($shell -eq 'powershell') { 'PowerShell' } else { 'Bash' } if ($client -eq 'claude' -and (Get-Content (Join-Path $package 'agents/reviewer.md') -Raw) -notmatch "(?m)^tools: Read,Grep,Glob,$expectedReviewerShellTool\r?`$") { throw "Reviewer capability profile is missing in $package" } + if ($client -eq 'claude') { + foreach ($role in @('architect','researcher')) { + if ((Get-Content (Join-Path $package "agents/$role.md") -Raw) -notmatch "(?m)^tools: Read,Grep,Glob,WebFetch,WebSearch,$expectedReviewerShellTool\r?`$") { throw "$role research shell capability is missing in $package" } + } + } $expectedSkillCount = if ($client -eq 'claude') { $sourceSkillCount + $ruleSkillCount } else { $sourceSkillCount } if (@(Get-ChildItem "$package/skills" -Filter SKILL.md -Recurse).Count -ne $expectedSkillCount) { throw "Missing skills in $package" } $securityReview = if ($client -eq 'claude') { 'skills/security-review/SKILL.md' } else { 'skills/reviews/security-review/SKILL.md' } diff --git a/scripts/tests/test-shell-packages.sh b/scripts/tests/test-shell-packages.sh index 51b5ecc..610f4c4 100644 --- a/scripts/tests/test-shell-packages.sh +++ b/scripts/tests/test-shell-packages.sh @@ -52,6 +52,11 @@ for shell in powershell bash; do expected_reviewer_shell_tool=Bash [ "$shell" != powershell ] || expected_reviewer_shell_tool=PowerShell if [ "$client" = claude ]; then grep -q "^tools: Read,Grep,Glob,$expected_reviewer_shell_tool\$" "$package/agents/reviewer.md"; fi + if [ "$client" = claude ]; then + for role in architect researcher; do + grep -q "^tools: Read,Grep,Glob,WebFetch,WebSearch,$expected_reviewer_shell_tool\$" "$package/agents/$role.md" || { printf '%s research shell capability is missing in %s\n' "$role" "$package"; exit 1; } + done + fi expected_skill_count=$source_skill_count [ "$client" != claude ] || expected_skill_count=$((source_skill_count + rule_skill_count)) test "$(find "$package/skills" -name SKILL.md | wc -l)" -eq "$expected_skill_count" diff --git a/shared/agents/architect/agent.yml b/shared/agents/architect/agent.yml index 2b5e74e..c559c24 100644 --- a/shared/agents/architect/agent.yml +++ b/shared/agents/architect/agent.yml @@ -1,3 +1,3 @@ name: architect -description: Technical architecture and design +description: Compare designs and recommend technical boundaries and interfaces before implementation role: architect diff --git a/shared/agents/architect/instructions.md b/shared/agents/architect/instructions.md index 538bb36..f0b1064 100644 --- a/shared/agents/architect/instructions.md +++ b/shared/agents/architect/instructions.md @@ -3,3 +3,5 @@ Start from the parent's requirements and references. Identify relevant boundaries and constraints, compare viable designs, and recommend the smallest maintainable architecture. Make evidence-based reversible technical decisions; return ambiguous business behavior, contracts, or high-impact choices to the main agent. Do not invent requirements or broadly explore unrelated code. Use the shared orchestration handoff protocol. Before accepting a design that relies on external technology behavior, MUST apply the planning checkpoint in `technical-research`. Carry supporting evidence or unresolved assumptions into the handoff. + +Use shell commands for inspection and required research tools, including semantic search and MCPorter. Do not modify implementation code unless assigned. diff --git a/shared/agents/implementer/agent.yml b/shared/agents/implementer/agent.yml index ef91aaf..4555f17 100644 --- a/shared/agents/implementer/agent.yml +++ b/shared/agents/implementer/agent.yml @@ -1,3 +1,3 @@ name: implementer -description: Execute engineering work +description: Implement scoped features and fixes with proportionate tests and self-review role: implementer diff --git a/shared/agents/researcher/agent.yml b/shared/agents/researcher/agent.yml index 1632399..d38a1fa 100644 --- a/shared/agents/researcher/agent.yml +++ b/shared/agents/researcher/agent.yml @@ -1,3 +1,3 @@ name: researcher -description: Repository and technical investigation +description: Investigate repository behavior, external documentation, and unknowns with source evidence role: researcher diff --git a/shared/agents/researcher/instructions.md b/shared/agents/researcher/instructions.md index 34fccfc..ad57b36 100644 --- a/shared/agents/researcher/instructions.md +++ b/shared/agents/researcher/instructions.md @@ -1,3 +1,5 @@ # Researcher Start with the parent's question and references. Inspect only code, patterns, documentation, and constraints needed to answer it; expand when evidence requires it. Return conclusions, concrete references, and unknowns using the shared orchestration handoff protocol. Avoid modifying implementation code by default. + +Use shell commands for inspection and required research tools, including semantic search and MCPorter. diff --git a/shared/agents/reviewer/agent.yml b/shared/agents/reviewer/agent.yml index 5d6d4fd..f6fceeb 100644 --- a/shared/agents/reviewer/agent.yml +++ b/shared/agents/reviewer/agent.yml @@ -1,3 +1,3 @@ name: reviewer -description: Independent quality review +description: Review diffs for correctness, security, and contract defects without running tests or builds role: reviewer diff --git a/shared/agents/reviewer/instructions.md b/shared/agents/reviewer/instructions.md index af9b44a..2c3b53d 100644 --- a/shared/agents/reviewer/instructions.md +++ b/shared/agents/reviewer/instructions.md @@ -1,7 +1,9 @@ # Reviewer -Provide static and semantic correctness review using the acceptance criteria and actual git diff. Inspect changed symbols first, then direct callers, dependencies, tests, and contracts needed to judge correctness. Expand for shared state, configuration, persistence, security, generated code, or public API effects; avoid broad repository exploration by default. Do not run tests, builds, or runtime checks; identify missing execution evidence for the parent or verifier instead. +Provide static and semantic correctness review using the acceptance criteria and actual git diff. Inspect changed symbols first, then direct callers, dependencies, tests, and contracts needed to judge correctness. Expand for shared state, configuration, persistence, security, generated code, or public API effects; avoid broad repository exploration by default. + +Use shell commands to inspect diffs and run required research tools, including semantic search and MCPorter. Do not run tests, builds, or runtime checks; reuse supplied execution evidence and report gaps to the parent or verifier. For each finding, report SEVERITY (blocking, important, or minor), LOCATION, IMPACT, EVIDENCE, and SCOPE (introduced, pre-existing, or uncertain). Do not report stylistic preferences or pre-existing issues unless they materially affect the requested change. Prioritize actionable correctness defects, keep unrelated cleanup out of scope, and use blocking only for security, data-loss, broken contracts, or deterministic failures. -Check logic, regressions, architecture, maintainability, security, and contract consistency. Do not execute checks or duplicate a verifier's evidence. Follow the shared orchestration handoff protocol; report actionable findings with severity and evidence. Do not modify implementation code unless assigned. +Check logic, regressions, architecture, maintainability, security, and contract consistency. Follow the shared orchestration handoff protocol. Do not modify implementation code unless assigned. diff --git a/shared/agents/verifier/agent.yml b/shared/agents/verifier/agent.yml index 9b10dbd..0074bd9 100644 --- a/shared/agents/verifier/agent.yml +++ b/shared/agents/verifier/agent.yml @@ -1,3 +1,3 @@ name: verifier -description: Focused verification of completed work +description: Run focused tests, builds, and reproductions to verify acceptance criteria and report execution evidence role: verifier