@super-hands/connect 0.1.25 → 0.1.26

package/client.mjs

@@ -42,11 +42,11 @@ function codexConfigBlock(args) {
 }
 
 // lib/connect-skill.ts
-var CONNECT_SKILL_VERSION = 18;
+var CONNECT_SKILL_VERSION = 19;
 var CONNECT_SKILL_DIR = MCP_SERVER_KEY;
 var CONNECT_SKILL_FILENAME = "SKILL.md";
 var VERSION_MARKER = `[//]: # (superhands-skill-version: ${CONNECT_SKILL_VERSION})`;
-var CONNECT_SKILL_DESCRIPTION = `Build UI the way this team has decided it should be built. Use BEFORE building, changing, or restyling any page, screen, view, form, or component \u2014 "build a page", "add a screen", "create a form", "make a dashboard", "redesign this", "new landing page" \u2014 and when asked how this product should look or behave. Reads the team's build-time Instructions from their Superhands MCP server, fetches task-wide requirements before starting and each part's selected instructions before building, including copy, and follows explicit requirements even when unusual or agent-specific.`;
+var CONNECT_SKILL_DESCRIPTION = `Follow this team's instructions and trace decisions in any kind of work. Use BEFORE research, writing, analysis, planning, operations, design or code \u2014 "research this", "write a report", "analyze this data", "plan the launch", "build a page", "redesign this" \u2014 including work without a repository or UI. Reads the team's build-time Instructions from their Superhands MCP server, fetches task-wide requirements before starting and each part's selected instructions before building, including copy, and follows explicit requirements even when unusual or agent-specific.`;
 var CONNECT_SKILL_CONTENT = `---
 name: ${CONNECT_SKILL_DIR}
 description: ${CONNECT_SKILL_DESCRIPTION}
@@ -59,24 +59,27 @@ ${VERSION_MARKER}
 This machine is connected to the team's Superhands server over MCP (server
 key \`${MCP_SERVER_KEY}\`). It holds the team's build-time **Instructions**:
 team-authored decisions, imported procedures, examples and conventions that all
-describe how agents should build in this product. Source labels tell you where
+describe how agents should work for this team. Source labels tell you where
 an instruction came from and how to read it; they are not a choice about which
 half to follow.
 
-Design traces connect guidance to reported changes, evidence and designer review.
-For this task, create a stable task reference once (for example a UUID), and send
-it as \`trace.taskId\` on the first Instructions read. Reuse it if that read
-needs retrying. Save the returned \`trace.runId\` and \`trace.decisionId\`;
+Work traces record explicit choices, stated reasons, sources, outputs and human
+feedback for any kind of work. Create a stable task reference once (for example
+a UUID). Call \`superhands_start_trace\` with \`taskId\` and a plain-language
+\`task\`, even without a repository, UI or matching instruction. Reuse taskId on
+retries and keep the returned runId. If this tool is unavailable, send the same
+reference as \`trace.taskId\` on the first Instructions read instead.
+Save the returned \`trace.runId\` and \`trace.decisionId\` when supplied;
 send \`trace.runId\` on every later read and report. Do not use a transport
 session or a shared credential as a task identity. Send \`trace.target\` for
-known screens/parts, \`trace.phase\` (before or during), and \`trace.trigger\`
+known parts or work products, \`trace.phase\` (before or during), and \`trace.trigger\`
 when an observation prompted guidance. Unknown scope stays unknown.
 
-Before you build, change, or restyle any UI:
+Before you build, research, write, analyze, plan or carry out other work:
 
 1. Call the \`superhands_get_instructions\` MCP tool with \`intent\` set to what
-   you have been asked to build, in plain language \u2014 for example "a sign-in
-   page with email and password and an error state", and
+   you have been asked to do, in plain language \u2014 for example "research customer
+   retention and write a findings report", and
    \`skill_version: ${CONNECT_SKILL_VERSION}\` \u2014 the version of this file, so
    the server can tell you when this file is out of date. The corpus comes
    back narrowed to that work, with everything not chosen still named.
@@ -98,7 +101,7 @@ Before you build, change, or restyle any UI:
    anything selection missed; fetch an entry there if the work reaches its scope.
    If no entry covers a part, say guidance was not found for it, rather than
    assuming the team has never written any.
-3. As you start each part \u2014 the sidebar, then the table, then the form \u2014 call
+3. As you start each part \u2014 source selection, analysis, then the report; or the sidebar, table and form \u2014 call
    \`superhands_get_instruction_modules\` with the reachable keys covering the
    part you are starting now and \`part\` set to that part in a few words,
    for example \`"the form's validation errors"\`. A key ending in \`*\` takes
@@ -137,30 +140,50 @@ Before you build, change, or restyle any UI:
    prefix and follow the general style for the rest of the text. If requirements
    remain incompatible after applying their scopes and exceptions, identify the
    exact conflict and ask a focused question; continue work independent of the answer.
-5. Keep each design decision explicit. Use \`superhands_report_trace\` with the
+5. Record each consequential decision as it happens in any kind of work. Use \`superhands_report_trace\` with the
    runId, a stable eventId and occurredAt timestamp (reuse both on retries).
-   Send a \`decision\` event with the returned delivery IDs when one context
-   response supports several decisions; use \`replaces\` to refine a provisional
-   group without counting both. Title it \u201CSuggested \u2026\u201D until output inspection
-   establishes reuse. Keep conflicting sources and any explicit resolution.
+   Send a \`decision\` event whose decision has id, key, title (the choice), target
+   (the affected work), provisional: false, a concise stated reason and optional
+   sources (title, URL, version or excerpt). Use returned delivery IDs when
+   instructions informed the choice, and \`deliveryIds: []\` otherwise. A choice
+   needs no existing instruction or output to be recorded. Use \`replaces\` to
+   refine a provisional group without counting both. Keep conflicting sources
+   and any explicit resolution. Cited sources remain agent reports.
    Register each identifiable output with an \`output\` event: revision,
    identity (commit:<sha>[:dirty-digest], deployment:<build-id>, or
-   artifact:<digest>), label and target. A preview URL is only a locator.
+   artifact:<digest>), label and target. Documents, datasets, messages and plans
+   use artifact:<content-digest>; a URL is only a locator. Do not invent an output
+   for work that produced none. Match its target to the decision's affected work.
    Later revisions name the preceding revision in \`supersedes\`.
    Send \`response\` events with decisionId, revision, description and
    \`reported_applied\`, \`reported_adapted\`, or \`reported_rejected\`.
    Include a concise explicit reason when useful; never provide private reasoning.
    Agent reports and agent-run checks are labelled **Agent reported**, not
    independent verification. A screenshot is an artifact, not a passed check.
-   Use \`superhands_add_trace_artifact\` for available images or evidence links,
-   with their route, viewport and UI state. Missing capture capability is a gap;
-   it must not stop coding. Never invent a before image or an unguided baseline.
-   Read \`superhands_get_trace\` before responding to designer feedback. Feedback
+   Use \`superhands_add_trace_artifact\` for plain text, images or evidence links.
+   Link other formats such as spreadsheets, PDFs, audio or video. Route, viewport
+   and UI state apply only to visual captures. Missing capture capability must
+   not stop work. Never invent a before image or an unguided baseline.
+   Read \`superhands_get_trace\` before responding to human feedback. Feedback
    belongs to its reviewed revision. After addressing it, register the new output
-   and send a \`ready\` event naming feedbackId; only the designer may approve.
-   Report interrupted/failed/resumed lifecycle explicitly; to resume a terminal
+   and send a \`ready\` event naming feedbackId; only a human may approve.
+   Report completed/interrupted/failed/resumed lifecycle explicitly for every
+   kind of work, even without outputs or instruction changes. To resume a terminal
    run, read and supersede its lifecycleId. Later outputs do not inherit approval.
-   If trace recording fails, report that gap and continue the coding task.
+   If trace recording fails, tell the person and continue the task. Only reported
+   activity is covered; never claim every internal decision was captured.
+   When a person corrects or amends a decision, report a \`correction\` event with
+   decisionId, optional revision, title, the proposed reusable wording in body,
+   and usedWhen describing the similar decisions it should guide. Keep the
+   correction faithful to the person's request; respect requests not to retain it.
+   This is an agent-reported proposal, not human acceptance. The run page lets a
+   member edit and save it into the team's instructions. It never changes review
+   policy. Read acceptedCorrections from \`superhands_get_trace\` to see what
+   was saved. Before a consequential decision outside the opening task's scope,
+   call \`superhands_get_instructions\` with that decision as intent and the same
+   trace.runId, then fetch the relevant keys. Accepted corrections travel through
+   this same search and per-part fetch; do not assume an earlier read has newer
+   instructions. Link later responses to the exact returned key and delivery.
 
 6. When you finish a part, call \`superhands_report_part\` with \`part\` \u2014 the
    part you just finished, in the words you fetched it under \u2014 and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-hands/connect",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Connect the coding agents on this machine to your team's Superhands MCP server — with `start`, from a machine that has no Superhands account at all. Refresh it later with `update` (no token needed), and take it back off again with `uninstall`. Writes each client's own config; reads no repository, uploads nothing.",
   "bin": {
     "superhands-connect": "client.mjs"