From a968e669c0ca81d8249390409b4a912d3bebcd1f Mon Sep 17 00:00:00 2001 From: Kyle Merritt Date: Thu, 12 Nov 2026 07:52:45 -0500 Subject: [PATCH] Add guidance-writing questions to the README Co-Authored-By: Claude Opus 5.5 --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 503674d..2ee0043 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,16 @@ To use a user fork, place its closed package directory under the owner's configu To use a maintained Planner or Implementer 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 a Planner or Implementer future assignment. RelayView pins and assigns the Issue Designer default automatically; its optional methods use `workflowPresets.designerSkills`. Planner guidance uses existing read and planning tools; Implementer guidance uses existing implementation and reporting tools. Guidance selection does not change a role's tools, credentials, lifecycle stages, validation requirements, Gitea effects, review, merge, or Human acceptance. The owner keeps the existing Gitea task workflow. +## Write the guidance + +A package's instructions are read by a model, so write them for one. Before adding an instruction, especially in response to behavior seen in a run, ask: + +- Can RelayView's owner determine the result from facts it holds? Then the owner should produce it, and the guidance should use it. +- Does the text state the action to take and a check the agent can run on the result, rather than what to avoid? +- Does the environment the agent works in differ from the familiar one it expects? Name each difference and the action that handles it. + +Judge a change over several runs, using the tool calls each run made, not one successful conversation. RelayView's `docs/authoritative/architecture-heuristics.md`, under "Model-Facing Work", records these defaults in full. + ## 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.