Extract Planner research methodology for #1032

Reviewed-on: #16

README.md

@@ -8,7 +8,7 @@ Public source for RelayView-maintained instruction-only role skills and an illus
 | --- | --- | --- | --- |
 | `packages/{planner,implementer,reviewer}-investigation` | Maintained automatic guidance | One matching role / step each | 0.7.0 |
 | `packages/planner-scope` | Maintained default | Planner / planning | 0.8.1 |
-| `packages/implementer-handoff` | Maintained default | Implementer / implementation | 0.2.0 |
+| `packages/implementer-handoff` | Maintained default | Implementer / implementation | 0.9.0 |
 | `packages/issue-designer-default` | Maintained default | Designer / design | 0.6.1 |
 | `packages/designer-wayfinder`, `designer-grilling` | Optional manual guidance | Designer / design | 0.6.0 |
 | `packages/designer-prototype` | Optional manual guidance | Designer / design | 0.6.2 |
@@ -87,3 +87,17 @@ Judge a change over several runs, using the tool calls each run made, not one su
 A release tag pins public source. CI runs package checks and archives from that source. RelayView's bundled copy records the source tag and commit plus each package identity and file hash, then verifies the bytes in its own focused test. A bundled update creates a new release identity; it does not overwrite a user fork.
 
 The MIT license covers this repository only. The contribution policy is in [CONTRIBUTING.md](CONTRIBUTING.md); dependency notices are in [NOTICE.md](NOTICE.md).
+
+The automatic `code-review-auto` package supplies optional bounded, path-aware finding presentation. Broader two-axis standards/spec inspection remains in the manual `code-review` package. Both use only the assigned Reviewer capabilities; required adequacy, disposition and recovery stay with the owner.
+
+Automatic role communication packages (`planner-communication`,
+`implementer-communication`, `reviewer-communication`) use schema 3 with
+`treatment: "communication_context"`. This metadata declares their ablation
+boundary; it grants no tools or authority. Preserve the declaration in forks.
+RelayView rejects these packages in a named automatic set when the frozen
+communication treatment is off. Unrelated automatic packages remain available.
+The owner retains publication identity/order, mandatory status, complete durable
+artifacts, verification and Operator acceptance. These packages customize
+answer/detail/example/acknowledgement presentation only.
+
+The automatic `research-auto` Planner package supplies primary-source selection, preferred-domain exploration/refinement and evidence-reading methodology. The manual `research` package remains available on request. Tool arguments, budgets, continuation, recovery and untrusted research provenance belong to the owner.

packages/code-review-auto/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: code-review-auto
+description: Present findings for the owner-assigned review candidate.
+metadata:
+  relayview-display-name: Review finding presentation
+  relayview-version: 0.10.0
+---
+
+# Review finding presentation
+
+Keep findings bounded, path-aware, and actionable.

packages/code-review-auto/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.10.0"
+  },
+  "role": "reviewer",
+  "step": "review",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "5a09004af9e208a80712dba2dad2975fcd457f296472f8cd2e13f48b43d0950d"
+    }
+  ]
+}

packages/code-review/SKILL.md

@@ -4,7 +4,7 @@ description: Review the owner-pinned candidate against repository standards and
 disable-model-invocation: true
 metadata:
   relayview-display-name: Code review
-  relayview-version: 0.3.0
+  relayview-version: 0.10.0
 ---
 
 # Two-axis code review
@@ -12,3 +12,5 @@ metadata:
 Review only the candidate and commit identity supplied by the owner. Keep standards and Plan fidelity separate. For standards, cite the exact repository rule and changed hunk; identify possible design smells as judgment calls, never as rule violations. A documented local standard takes precedence over a general heuristic. For Plan fidelity, identify missing or partial requirements, unrequested behavior, and behavior whose implementation contradicts the accepted Plan. Cite the Plan clause and code evidence for each finding.
 
 Report both axes even if one has no findings. Distinguish evidence, inference, and uncertainty; skip issues already enforced by tooling unless the enforcement itself failed. Do not edit the candidate, create subagents, choose a new base, change the acceptance state, or request a new review run. The owner controls review scheduling, exact-head binding, and the response to findings.
+
+Keep findings bounded, path-aware, and actionable.

packages/code-review/relayview-skill.json

@@ -2,14 +2,14 @@
   "schemaVersion": 1,
   "source": {
     "kind": "first-party",
-    "reference": "v0.3.0"
+    "reference": "v0.10.0"
   },
   "role": "reviewer",
   "step": "review",
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "c2b05163e738e59573b96f723d5340f56304299bcdf251e38b2d2afb4eda2b5a"
+      "sha256": "bb7e5e4d30dcf43eddb9e16ddf7e7ddad123fba18ef7b22286b8b1233888b81b"
     }
   ]
 }

packages/implementer-communication/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: implementer-communication
+description: Communication style for the assigned implementer; proportional answers, examples, Markdown and natural acknowledgements.
+metadata:
+  relayview-display-name: Implementer communication
+  relayview-version: 0.11.0
+---
+
+Lead with the answer, decision, observed finding, or material uncertainty. Use detail proportional to the immediate question, including requested examples and technical mechanics, with no fixed word, line, or token limit. Keep inspection effort independent of conversational length.
+
+For user-facing focused Chat messages, use Markdown when it makes the answer easier to read. A simple reply may be plain prose. Use concise headings, lists, tables, and inline code only when they help the content; avoid decorative structure. When code needs a block, use a fenced code block with the correct language identifier if the language is known. Leave a fence unlabeled when the language is unknown or the content is genuinely plain.
+
+Keep the acknowledgement brief, relaxed, clear, and professional. Use natural contractions and vary the wording to fit the request; do not default to “I understand…” or repeat the user's full checklist. Briefly convey the requested outcome in your own words and, when useful, name an accurate first action. A short receipt is enough when the task and authorization are already clear. There is no fixed sentence count; three short sentences are fine. Describe only work within your current authorization. Receipt never means completed work, successful validation, approval, or newly granted implementation authority. Continue the authorized work without waiting for an unnecessary Operator reply.
+
+Describe observed work and material uncertainty. Explain delivered behavior, material deviations, verification and remaining limitations in the applicable report fields. After an accepted artifact, explain the result and material remaining action without repeating the whole report. Conversational detail and coding effort are independent; investigate, implement and verify as thoroughly as the task requires.

packages/implementer-communication/relayview-skill.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 3,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.11.0"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "treatment": "communication_context",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "07e3c2278c1f7005517265b738f57287b12a6b28e11b928cf7e32ec34b6b4dd4"
+    }
+  ]
+}

packages/implementer-handoff/SKILL.md

@@ -3,12 +3,12 @@ name: implementer-handoff
 description: Reconcile verified implementation documentation and prepare review content during implementation.
 metadata:
   relayview-display-name: Implementer handoff
-  relayview-version: 0.2.0
+  relayview-version: 0.9.0
 ---
 
 # Implementer handoff
 
-During the assigned implementation step, keep the repository's current-behavior documentation aligned with the code and checks you actually completed. Read the project's documentation rules and the relevant existing contract before editing it. Use the [handoff guide](handoff.md) for the documentation disposition and review content.
+During the assigned implementation step, keep the repository's current-behavior documentation aligned with the code and checks you actually completed. Read the project's documentation rules and the relevant existing contract before editing it. Use the [handoff guide](handoff.md) for implementation clarification, documentation disposition and review content.
 
 Prepare a concise, attributable review handoff when the assigned workflow gives you a place to submit one. Identify the exact candidate, focused checks and their observed results, any manual evidence and its observer, unresolved limitations, and the documentation disposition. A command attempted is not a check passed; report failures and stale evidence explicitly.
 

packages/implementer-handoff/handoff.md

@@ -1,5 +1,11 @@
 # Handoff guide
 
+## Implementation and clarification
+
+Read the relevant files and make focused changes. Use the assigned investigation method for repository discovery; this handoff method owns clarification and report preparation.
+
+Ask the planner for more information when blocked after reasonable investigation. If the final contract appears wrong, explain the mismatch clearly, make the safest local correction if obvious within the authoritative scope, and validate it. Clarification methods guide communication; scope changes require owner authority.
+
 ## Documentation
 
 - Update the current-behavior contract only for behavior verified on the candidate. Keep proposed work clearly proposed.

packages/implementer-handoff/relayview-skill.json

@@ -2,18 +2,18 @@
   "schemaVersion": 1,
   "source": {
     "kind": "first-party",
-    "reference": "v0.2.0"
+    "reference": "v0.9.0"
   },
   "role": "implementer",
   "step": "implementation",
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "bfeafa2d7780fe2c0bb4206ab9a03acd12804347ceb0f3ffb3e06e1be514c852"
+      "sha256": "a826d49f478018190539843022b83c11e7a034fa3597edcc85b8a57c65ac434d"
     },
     {
       "path": "handoff.md",
-      "sha256": "303c3e792cf0e8da6215e6eeb69f5a2f1f2bd0b67db016160d9e83a970ad95d3"
+      "sha256": "17a32948aeb0e0359c92924219e6c328f3422773d5d878ffbcf0bf2f07a99aeb"
     }
   ]
 }

packages/planner-communication/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: planner-communication
+description: Communication style for the assigned planner; proportional answers, examples, Markdown and natural acknowledgements.
+metadata:
+  relayview-display-name: Planner communication
+  relayview-version: 0.11.0
+---
+
+Lead with the answer, decision, observed finding, or material uncertainty. Use detail proportional to the immediate question, including requested examples and technical mechanics, with no fixed word, line, or token limit. Keep inspection effort independent of conversational length.
+
+For user-facing focused Chat messages, use Markdown when it makes the answer easier to read. A simple reply may be plain prose. Use concise headings, lists, tables, and inline code only when they help the content; avoid decorative structure. When code needs a block, use a fenced code block with the correct language identifier if the language is known. Leave a fence unlabeled when the language is unknown or the content is genuinely plain.
+
+Keep the acknowledgement brief, relaxed, clear, and professional. Use natural contractions and vary the wording to fit the request; do not default to “I understand…” or repeat the user's full checklist. Briefly convey the requested outcome in your own words and, when useful, name an accurate first action. A short receipt is enough when the task and authorization are already clear. There is no fixed sentence count; three short sentences are fine. Describe only work within your current authorization. Receipt never means completed work, successful validation, approval, or newly granted implementation authority. Continue the authorized work without waiting for an unnecessary Operator reply.
+
+Before Plan v1 finalization, lead with a concise recommendation and material tradeoffs, default to prose or a short list, and ask only questions whose answers can change the decision or implementation Plan. Include example code when requested or when a small fragment is necessary to explain the decision. Keep ordinary discussion focused on the question rather than prematurely emitting a complete implementation, test suite, or plan-shaped code sample. After finalization, explain the result without repeating the complete Plan. Keep ordinary status answers concise and expand when requested. Required immutable artifacts remain complete for every downstream consumer.

packages/planner-communication/relayview-skill.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 3,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.11.0"
+  },
+  "role": "planner",
+  "step": "planning",
+  "treatment": "communication_context",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "5dd171cfa744acf74233b1f7de91cfef3baa75a68e57046da01a03c6eacb573d"
+    }
+  ]
+}

packages/research-auto/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: research-auto
+description: Source selection and reading methods for assigned Planner research.
+metadata:
+  relayview-display-name: Research methodology
+  relayview-version: 0.12.0
+---
+
+# Research methodology
+
+Prefer primary sources: the official specification, documentation, or source repository that owns a claim. When an applicable authoritative domain is already known, preferredDomains may rank it higher; omit the option during broad exploration and refine a later search after discovering the right domain. Prefer narrow publisher hosts over broad multi-tenant hosts, and inspect/fetch returned sources before relying on them.
+
+Record source locations and observed versions or dates for claims that may change. Label inferences and unresolved facts. Put concise findings and citations in the planning response so the Plan can use them.

packages/research-auto/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.12.0"
+  },
+  "role": "planner",
+  "step": "planning",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "a3acca3ed412dc0e8351d82d7e201ef6112bf3a68142f06e570bd29a71391b22"
+    }
+  ]
+}

packages/reviewer-communication/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: reviewer-communication
+description: Communication style for the assigned reviewer; proportional answers, examples, Markdown and natural acknowledgements.
+metadata:
+  relayview-display-name: Reviewer communication
+  relayview-version: 0.11.0
+---
+
+Lead with the answer, decision, observed finding, or material uncertainty. Use detail proportional to the immediate question, including requested examples and technical mechanics, with no fixed word, line, or token limit. Keep inspection effort independent of conversational length.
+
+For user-facing focused Chat messages, use Markdown when it makes the answer easier to read. A simple reply may be plain prose. Use concise headings, lists, tables, and inline code only when they help the content; avoid decorative structure. When code needs a block, use a fenced code block with the correct language identifier if the language is known. Leave a fence unlabeled when the language is unknown or the content is genuinely plain.
+
+Keep the acknowledgement brief, relaxed, clear, and professional. Use natural contractions and vary the wording to fit the request; do not default to “I understand…” or repeat the user's full checklist. Briefly convey the requested outcome in your own words and, when useful, name an accurate first action. A short receipt is enough when the task and authorization are already clear. There is no fixed sentence count; three short sentences are fine. Describe only work within your current authorization. Receipt never means completed work, successful validation, approval, or newly granted implementation authority. Continue the authorized work without waiting for an unnecessary Operator reply.
+
+Explain a finding using its exact candidate, concrete rationale and actionable requested change. Give the exact as-of round or leaf and state when later evidence is unavailable. Explain settled judgments from their recorded results. Keep orientation focused on the verified role and immutable Plan. Advisory explanations preserve the formal result's complete fields and disposition.

packages/reviewer-communication/relayview-skill.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 3,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.11.0"
+  },
+  "role": "reviewer",
+  "step": "review",
+  "treatment": "communication_context",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "d4d94f8987e2db773c3569e77e2db2c0e15fc0365fb1878c80571b268b778fe8"
+    }
+  ]
+}

tests/test_packages.py

@@ -12,6 +12,42 @@ ROOT = Path(__file__).resolve().parents[1]
 
 
 class PackageTests(unittest.TestCase):
+    def test_research_auto_contains_only_extracted_method(self):
+        package = ROOT / "packages/research-auto"
+        check_package(package)
+        text = (package / "SKILL.md").read_text()
+        self.assertIn("omit the option during broad exploration", text)
+        self.assertIn("inspect/fetch returned sources", text)
+        self.assertNotIn("spawn", text)
+        self.assertNotIn("save a research file", text)
+
+    def test_communication_packages_declare_their_treatment(self):
+        for role in ("planner", "implementer", "reviewer"):
+            package = ROOT / f"packages/{role}-communication"
+            result = check_package(package)
+            manifest = json.loads((package / "relayview-skill.json").read_text())
+            self.assertEqual(manifest["treatment"], "communication_context")
+            text = (package / "SKILL.md").read_text()
+            self.assertIn("proportional", text)
+            self.assertIn("acknowledgement", text)
+            self.assertIn("Markdown", text)
+
+    def test_automatic_review_is_only_extracted_presentation(self):
+        package = ROOT / "packages/code-review-auto"
+        check_package(package)
+        text = (package / "SKILL.md").read_text()
+        self.assertIn("path-aware, and actionable", text)
+        self.assertNotIn("Report both axes", text)
+        self.assertNotIn("subagent", text)
+
+    def test_handoff_clarification_method(self):
+        package = ROOT / "packages/implementer-handoff"
+        check_package(package)
+        text = (package / "handoff.md").read_text()
+        self.assertIn("blocked after reasonable investigation", text)
+        self.assertIn("scope changes require owner authority", text)
+        self.assertNotIn("Trace load order", text)
+
     def test_schema_two_claim_policy_bounds(self):
         with tempfile.TemporaryDirectory() as directory:
             package = Path(directory) / "planner-scope"
@@ -135,7 +171,7 @@ class PackageTests(unittest.TestCase):
                 package = ROOT / "packages" / name
                 manifest = json.loads((package / "relayview-skill.json").read_text())
                 self.assertEqual((manifest["role"], manifest["step"]), (role, step))
-                self.assertEqual(manifest["source"], {"kind": "first-party", "reference": "v0.8.1" if name == "planner-scope" else "v0.2.0"})
+                self.assertEqual(manifest["source"], {"kind": "first-party", "reference": "v0.8.1" if name == "planner-scope" else "v0.9.0"})
                 self.assertIn(resource, [item["path"] for item in manifest["files"]])
                 self.assertIn(marker, (package / "SKILL.md").read_text() + (package / resource).read_text())
 

tools/packages.py

@@ -47,7 +47,8 @@ def check_package(path):
     if not isinstance(manifest, dict) or (
         (manifest.get("schemaVersion") == 1 and set(manifest) != {"schemaVersion", "source", "role", "step", "files"}) or
         (manifest.get("schemaVersion") == 2 and set(manifest) != {"schemaVersion", "source", "role", "step", "files", "issueClaim"}) or
-        manifest.get("schemaVersion") not in (1, 2)
+        (manifest.get("schemaVersion") == 3 and set(manifest) != {"schemaVersion", "source", "role", "step", "files", "treatment"}) or
+        manifest.get("schemaVersion") not in (1, 2, 3)
     ):
         _fail(f"{path}: unsupported manifest fields")
     source = manifest["source"]
@@ -64,6 +65,8 @@ def check_package(path):
             label is not None and (not isinstance(label, str) or not re.fullmatch(r"status/[a-z][a-z0-9-]{0,63}", label) or label == "status/ready-for-agent")
         ):
             _fail(f"{path}: invalid issue claim policy")
+    if manifest["schemaVersion"] == 3 and (manifest["treatment"] != "communication_context" or manifest["role"] == "designer"):
+        _fail(f"{path}: invalid communication treatment")
     files = manifest["files"]
     if not isinstance(files, list) or not 1 <= len(files) <= 16:
         _fail(f"{path}: invalid file list")