fix(agents): align research tools and clarify role boundaries

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__

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.

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' }

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"

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

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.

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

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

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.

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

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.

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