Publish planner and implementer role guidance v0.2.0

.gitea/workflows/check.yml

@@ -13,6 +13,8 @@ jobs:
       - run: python3 --version
       - run: python3 -m unittest discover -s tests -v
       - run: python3 -m tools.packages check packages/planner-scope
+      - run: python3 -m tools.packages check packages/implementer-handoff
       - run: python3 -m tools.packages check examples/starter-planner
       - run: python3 -m tools.packages pack packages/planner-scope dist/planner-scope.zip
+      - run: python3 -m tools.packages pack packages/implementer-handoff dist/implementer-handoff.zip
       - run: python3 -m tools.packages pack examples/starter-planner dist/starter-planner.zip

README.md

@@ -6,7 +6,8 @@ Public source for RelayView-maintained instruction-only role skills and an illus
 
 | Directory | Status | Role / step | Version |
 | --- | --- | --- | --- |
-| `packages/planner-scope` | Maintained default | Planner / planning | 0.1.0 |
+| `packages/planner-scope` | Maintained default | Planner / planning | 0.2.0 |
+| `packages/implementer-handoff` | Maintained default | Implementer / implementation | 0.2.0 |
 | `examples/starter-planner` | Illustrative starter; not a production default | Planner / planning | 0.1.0 |
 
 Only named releases of maintained defaults receive RelayView compatibility testing and maintenance. User forks are maintained by their publishers. This release uses the instruction package schema version 1 admitted by RelayView's Community MVP. It contains only `SKILL.md`, declared `.md`/`.txt` resources, and `relayview-skill.json` within each package. Scripts, executable files, undeclared files, and requested permissions fail checks and owner admission. There is no fixed release calendar: maintained packages are versioned when their content or compatibility changes. A breaking owner contract requires a new compatible maintained release before the product depends on it.
@@ -25,6 +26,8 @@ Replace `examples/starter-planner` in the last two commands with your package di
 
 To import a user fork, place its closed package directory under the owner's configured trusted root, use Settings → Skills to import the relative `SKILL.md` path under a new unique ID, and assign it to the matching future role step. Saving a new assignment takes effect after owner restart; existing sessions retain their captured bytes. The Settings catalog displays source, version, digest, role, step, and pending versus effective assignment. The owner's admission remains authoritative even when these local checks pass.
 
+To use a maintained default, copy its release package under the same trusted root, admit its `SKILL.md` through the owner catalog, then select it for its declared role in Settings. Settings import accepts user-source packages; configure first-party packages in the owner catalog. Select a fork with `source.kind: user` and a distinct ID to replace that role's future assignment. Planner guidance uses existing read and planning tools; Implementer guidance uses existing implementation and reporting tools. Neither selection changes a role's tools, credentials, lifecycle stages, validation requirements, Gitea effects, review, merge, or Human acceptance. The owner keeps the existing Gitea task workflow.
+
 ## Release identity
 
 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.

packages/implementer-handoff/SKILL.md

@@ -0,0 +1,15 @@
+---
+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
+---
+
+# 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.
+
+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.
+
+Use only the Implementer's assigned tools and owner interfaces. The owner verifies validation, review, provider effects, and stage readiness; your prose is a report for that process. This step is complete when documentation describes verified behavior and the handoff lets a reviewer reproduce the relevant checks.

packages/implementer-handoff/handoff.md

@@ -0,0 +1,14 @@
+# Handoff guide
+
+## Documentation
+
+- Update the current-behavior contract only for behavior verified on the candidate. Keep proposed work clearly proposed.
+- Record one disposition: `updated`, `not_required` with a concrete reason, `deferred`, or `blocked`.
+- Put run-specific logs, screenshots, and command results in the review handoff, not the enduring contract, unless the contract explicitly depends on one identified run.
+
+## Review content
+
+- Summarize the user-visible change and its bounded impact.
+- Name the candidate revision and the focused checks run against it, with observed pass or failure results.
+- Give a reviewer executable steps and expected observations for any behavior that automated checks cannot establish.
+- State remaining uncertainty and recovery steps. Attribute provider or Human observations to their actual source.

packages/implementer-handoff/relayview-skill.json

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

packages/planner-scope/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: planner-scope
-description: Check a Planner's issue scope and evidence before drafting a Plan.
+description: Check assigned issue scope, neighboring work, and verification before drafting a Plan.
 metadata:
   relayview-display-name: Planner scope
-  relayview-version: 0.1.0
+  relayview-version: 0.2.0
 ---
 
 # Planner scope
 
-When drafting the assigned Plan, identify the requested behavior, its boundary, dependencies, and the evidence needed to verify it. Read the task's authoritative project context and relevant neighboring work before deciding scope. Use the [scope guide](scope.md) to keep assumptions and open decisions visible in the Plan.
+When drafting the assigned Plan, identify the requested behavior, its boundary, dependencies, and the evidence needed to verify it. Read the task's authoritative project context, corresponding code and tests, and relevant neighboring work before deciding scope. Use the [scope guide](scope.md) to keep assumptions and open decisions visible in the Plan.
 
-Work within the Planner's assigned tools and read access. Send the Plan through the owner's existing planning interface. Instructions here provide guidance; owner-controlled workflow stages and checks remain the source of execution authority.
+If the owner supplies an admitted work-item identity, use the assigned read tools to inspect it. Preserve source attribution; an issue description is a request, not evidence that its proposed behavior exists. Where tracker access is unavailable, state the missing context instead of guessing a work-item identity.
+
+Write the Plan through the owner's assigned planning interface. The Plan is ready when each requested outcome has an implementation boundary and a checkable success or recovery observation. Owner-controlled workflow stages and checks determine execution authority.

packages/planner-scope/relayview-skill.json

@@ -2,18 +2,18 @@
   "schemaVersion": 1,
   "source": {
     "kind": "first-party",
-    "reference": "v0.1.0"
+    "reference": "v0.2.0"
   },
   "role": "planner",
   "step": "planning",
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "5c52e8c6183472c03f039475c6df9ce1fadf7aecd06a846ad74d7a741f5f95e0"
+      "sha256": "31399ba322d8a4d3ed9814e7fd5d54883b4773c5b7dc3a241b8e14f8f7c16072"
     },
     {
       "path": "scope.md",
-      "sha256": "a59376ba22a7c1eacf5af03533908badb36a00154adc894b5454bf4dbcb850ec"
+      "sha256": "fc365d5f5c90f878992204235f32b1148aa4934a31f8c10eb063292fb64cf248"
     }
   ]
 }

packages/planner-scope/scope.md

@@ -2,6 +2,7 @@
 
 - State the user-visible outcome and the exact part of the system affected.
 - Name prerequisites and neighboring work that change the boundary.
+- Cite the current contract, code, or test that supports each existing-behavior claim.
 - Distinguish verified current behavior from a proposal.
 - Identify one observable success path and one meaningful failure or recovery path.
 - Record uncertainty as an open decision; do not turn silence into approval.

tests/test_packages.py

@@ -13,13 +13,42 @@ ROOT = Path(__file__).resolve().parents[1]
 
 class PackageTests(unittest.TestCase):
     def test_release_package_and_starter_are_valid(self):
-        for path in (ROOT / "packages/planner-scope", ROOT / "examples/starter-planner"):
+        for path in (ROOT / "packages/planner-scope", ROOT / "packages/implementer-handoff", ROOT / "examples/starter-planner"):
             check_package(path)
             with tempfile.TemporaryDirectory() as directory:
                 first = package_archive(path, Path(directory) / "one.zip")
                 second = package_archive(path, Path(directory) / "two.zip")
                 self.assertEqual(first, second)
 
+    def test_maintained_guidance_covers_distinct_role_steps(self):
+        expected = {
+            "planner-scope": ("planner", "planning", "scope.md", "Plan"),
+            "implementer-handoff": ("implementer", "implementation", "handoff.md", "documentation"),
+        }
+        for name, (role, step, resource, marker) in expected.items():
+            with self.subTest(name=name):
+                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.2.0"})
+                self.assertIn(resource, [item["path"] for item in manifest["files"]])
+                self.assertIn(marker, (package / "SKILL.md").read_text() + (package / resource).read_text())
+
+    def test_user_fork_is_distinct_under_same_role_limits(self):
+        with tempfile.TemporaryDirectory() as directory:
+            package = Path(directory) / "implementer-handoff"
+            shutil.copytree(ROOT / "packages/implementer-handoff", package)
+            original = check_package(package)
+            resource = package / "handoff.md"
+            resource.write_text(resource.read_text() + "\n- Prefer the team's concise PR summary format.\n")
+            manifest_path = package / "relayview-skill.json"
+            manifest = json.loads(manifest_path.read_text())
+            manifest["source"] = {"kind": "user", "reference": "team-fork-1"}
+            next(item for item in manifest["files"] if item["path"] == "handoff.md")["sha256"] = hashlib.sha256(resource.read_bytes()).hexdigest()
+            manifest_path.write_text(json.dumps(manifest))
+            self.assertNotEqual(check_package(package), original)
+            self.assertEqual((manifest["role"], manifest["step"]), ("implementer", "implementation"))
+
     def test_rejects_scripts_and_undeclared_files(self):
         with tempfile.TemporaryDirectory() as directory:
             package = Path(directory) / "planner-scope"
@@ -74,7 +103,7 @@ class PackageTests(unittest.TestCase):
     def test_rejects_owner_incompatible_frontmatter_values(self):
         for old, new in (
             ("metadata:\n", "disable-model-invocation: yes\nmetadata:\n"),
-            ("description: Check a Planner's issue scope and evidence before drafting a Plan.", "description: "),
+            ("description: Check assigned issue scope, neighboring work, and verification before drafting a Plan.", "description: "),
         ):
             with self.subTest(new=new), tempfile.TemporaryDirectory() as directory:
                 package = Path(directory) / "planner-scope"