@super-hands/connect 0.1.24 → 0.1.26

package/client.mjs

@@ -42,11 +42,11 @@ function codexConfigBlock(args) {
 }
 
 // lib/connect-skill.ts
-var CONNECT_SKILL_VERSION = 17;
+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.`;
+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.
@@ -89,15 +92,16 @@ Before you build, change, or restyle any UI:
      example \`["app/marketing/pricing.tsx"]\`. The team writes down where
      Instructions apply, and a path answers that far better than a description
      does. Leave it out if you do not know yet; it narrows nothing away.
-2. Plan against what comes back, and note which parts of your plan each set of
-   keys covers. The first answer renders what to read first, then names
-   under **Reachable** the modules judged to matter to parts you have not
-   started \u2014 those keys are what the next step asks with \u2014 and ends with an
-   index of the modules it did **not** choose, for anything the selection
-   missed. A part of your plan with no keys against it is a real gap in what
-   the team has written down; say so rather than quietly using your own
-   defaults.
-3. As you start each part \u2014 the sidebar, then the table, then the form \u2014 call
+2. Plan against the selected Instructions. The first answer names them under
+   **Reachable**, with keys and opening text; it does not render them in full.
+   Fetch every selected entry when its scope is reached, including review-enforced
+   decisions. Superhands has already selected these for the task: sequence their
+   use, not a second shortlist based on your preferences. Map every selected key
+   to the work it governs. The closing **Not selected** index is available for
+   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 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
@@ -114,40 +118,72 @@ Before you build, change, or restyle any UI:
      the start. These are instructions to follow, not facts to know, so modules
      for a part you are not building are a page of directions about the wrong
      thing sitting in your context while you work.
-   - Review-enforced decision entries from step 1 need no such loop. They are
-     concise enough to stay in the opening brief, so one read at the start is
-     the right read.
+   - Fetch instructions governing the whole task, agent behaviour or communication
+     before starting that work, and continue applying them throughout the task.
+     Fetch copy instructions before writing text, including placeholder copy,
+     headings, buttons and footers, even during layout or styling work. A part
+     includes its copy, controls, accessibility and states as well as its styling.
+   - If an entry's full text excludes the actual work, or the task changes so its
+     scope is no longer reached, state the concrete reason it does not apply.
+     Do not silently omit it.
    - If that tool is not available on this server,
      build from what step 1 already returned and skip this step. Do not ask
      for the whole library instead \u2014 that is the wall of text step 1 avoided.
+     Say which entries could not be read; never claim to have followed unavailable text.
 4. Build to what comes back. Use the selected Instructions together. When two
    entries pull in different directions, prefer the more specific instruction,
    preserve explicit exceptions, and call out any conflict you cannot honestly
-   resolve.
-5. Keep each design decision explicit. Use \`superhands_report_trace\` with the
+   resolve. Do not dismiss an explicit requirement as a leftover test, placeholder,
+   accidental entry or bad brand choice because it looks unusual. Do not ask for
+   confirmation merely because you would prefer a different result. An explicit
+   agent-specific text prefix is an exception to general copy style: apply the
+   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. 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.24",
+  "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"