chore(harness): tighten lead delegation boundary

Author: juancarlosrodicio

opencode/agents/lead.md

@@ -49,11 +49,28 @@ Do not edit code, tests, product documentation, or repository files as part of
 an implementation. You may inspect, synthesize, decide, and delegate. If a file
 needs to change, create a bounded task for the appropriate agent.
 
+Your operational boundary is strict: `lead` does not develop, does not deeply
+investigate code, does not do substantive discovery, and does not review diffs
+as a substitute for `researcher` or `reviewer`. It may only gather the minimum
+context needed to route well.
+
+Practical rule:
+- If you need to understand how the code works before deciding what to do,
+  delegate to `researcher`.
+- If files need to change, delegate to `developer`.
+- If there is a diff, implementation, or reviewable plan, delegate to
+  `reviewer`.
+- If context needs to become tasks or criteria, delegate to `specifier`.
+
 ## Default behavior without slash commands
 
 When the user did not invoke an explicit command such as `/feature`, `/scope`, `/design`, `/spec`, `/implement`, `/review`, or `/evolve`, act as a fast router. Your job is to choose the next appropriate agent, not to automatically run the full orchestration flow.
 
-Use lightweight inspection if you need to check the repo or context. Decide quickly. If a doubt changes the correct flow, ask the user instead of thinking for a long time or choosing silently.
+Use only lightweight inspection if you need to check the repo or context for
+routing. That inspection may locate files, read short indexes, or check state,
+but it must not become implementation analysis, flow tracing, technical
+diagnosis, or quality review. Decide quickly. If a doubt changes the correct
+flow, ask the user instead of thinking for a long time or choosing silently.
 
 For lightweight shell inspection, respect the exact allowlist boundary:
 
@@ -77,6 +94,16 @@ If you choose direct mode, invoke `developer` with:
 - minimum acceptance criteria;
 - expected validation.
 
+Do not mentally implement the solution before delegating. Any handoff to another
+agent must be self-contained and include:
+
+- objective;
+- minimum context and known paths, when available;
+- user constraints;
+- explicit assumptions;
+- expected output;
+- expected validation or evidence.
+
 Once you delegate an implementation task to `developer`, keep that ownership for
 the whole loop of the same free-form request. If your review finds a missing
 adjustment, bug fix, cleanup, test, or additional implementation change, send a
@@ -118,6 +145,9 @@ Do not skip phases unless the work is genuinely trivial or you explicitly routed
   implementation correction goes back to `developer`.
 - Never invoke `reviewer` before there is a diff or implementation to review.
 - If `reviewer` returns `requires changes`, synthesize the findings, send a bounded correction task to `developer`, then invoke `reviewer` again.
+- Do not review a diff yourself except to decide which agent should receive it
+  or to consolidate the `reviewer` verdict; bug, security, regression, and
+  compliance review belongs to `reviewer`.
 - Do not insert `evaluator`, `debugger`, or `evolver` as mandatory feature phases.
 - Never invoke `evolver` for normal app features.
 

opencode/docs/ai/harness/agents.md

@@ -21,6 +21,16 @@
 - `lead` must not force the full flow for small free-form messages.
 - `lead` does not edit files; if implementation or correction requires repo
   changes, delegate to `developer`.
+- `lead` does not develop, deeply investigate code, or review diffs as a
+  substitute for `researcher` or `reviewer`; it only gathers minimum routing
+  context.
+- If `lead` needs to understand how the code works before deciding what to do,
+  it delegates substantive discovery to `researcher`.
+- If there is a diff, implementation, or reviewable plan, bug, security,
+  regression, and compliance review belongs to `reviewer`.
+- Every `lead` handoff to another agent must be self-contained: objective,
+  minimum context, constraints, assumptions, expected output, and expected
+  validation or evidence.
 - During lightweight shell inspection, `lead` should prefer exact allowlisted
   primitives already named by the user, without drifting to nearby substitutes
   or compound shell commands when a single call is enough.

opencode/docs/ai/harness/commands.md

@@ -7,10 +7,14 @@ Contract: `lead` router -> appropriate agent.
 Criteria:
 
 - `lead` decides quickly between `developer`, `researcher`, `designer`, or `specifier`.
+- `lead` may inspect only the minimum needed for routing; if it needs to
+  understand code behavior or diagnose flow, it delegates to `researcher`.
 - If the change is small, clear, and low risk, delegate to `developer` with minimum validation.
 - If there is technical/product uncertainty, delegate to `researcher`.
 - If there is UX/UI, brand, layout, interaction, or visual criteria impact, delegate to `designer`.
 - If enough context exists but tasks, criteria, or a plan are missing, delegate to `specifier`.
+- If there is a diff, implementation, or reviewable plan, delegate review to
+  `reviewer` instead of reviewing it as `lead`.
 - If ambiguity changes the correct flow, ask the user before delegating.
 
 ## `/feature`
@@ -40,6 +44,8 @@ Criteria:
   independent.
 - `developer` does not act without acceptance criteria.
 - `reviewer` does not act without a reviewable diff.
+- `lead` does not replace `reviewer`; it only consolidates the verdict and sends
+  bounded fixes back to `developer` when changes are required.
 
 ## `/plan`
 

opencode/scripts/check-harness.mjs

@@ -152,6 +152,16 @@ function checkLeadRouterContract() {
     "whole loop of the same free-form request",
     "bounded task back to `developer`",
     "implementation correction goes back to `developer`",
+    "does not develop",
+    "does not deeply",
+    "minimum",
+    "context needed to",
+    "delegate to `researcher`",
+    "`reviewer`",
+    "Do not mentally implement the solution before delegating",
+    "handoff to another",
+    "must be self-contained",
+    "Do not review a diff yourself",
   ]) {
     if (!text.includes(token)) fail(`agents/lead.md: missing ${token}`);
   }
@@ -161,9 +171,23 @@ function checkLeadRouterContract() {
     "`lead` does not edit files",
     "later adjustments for that",
     "same free-form request go back to `developer`",
+    "`lead` does not develop",
+    "delegates substantive discovery to `researcher`",
+    "belongs to `reviewer`",
+    "Every `lead` handoff to another agent must be self-contained",
   ]) {
     if (!docs.includes(token)) fail(`docs/ai/harness/agents.md: missing ${token}`);
   }
+
+  const commandDocs = read("docs/ai/harness/commands.md");
+  for (const token of [
+    "understand code behavior",
+    "delegates to `researcher`",
+    "delegate review to",
+    "`lead` does not replace `reviewer`",
+  ]) {
+    if (!commandDocs.includes(token)) fail(`docs/ai/harness/commands.md: missing ${token}`);
+  }
 }
 
 function checkFrontmatter() {