@super-hands/connect 0.1.23 → 0.1.25

package/client.mjs

@@ -42,11 +42,11 @@ function codexConfigBlock(args) {
 }
 
 // lib/connect-skill.ts
-var CONNECT_SKILL_VERSION = 16;
+var CONNECT_SKILL_VERSION = 18;
 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 = `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_CONTENT = `---
 name: ${CONNECT_SKILL_DIR}
 description: ${CONNECT_SKILL_DESCRIPTION}
@@ -63,6 +63,15 @@ describe how agents should build in this product. 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\`;
+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\`
+when an observation prompted guidance. Unknown scope stays unknown.
+
 Before you build, change, or restyle any UI:
 
 1. Call the \`superhands_get_instructions\` MCP tool with \`intent\` set to what
@@ -80,14 +89,15 @@ 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.
+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 the sidebar, then the table, then the 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,
@@ -105,17 +115,54 @@ 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. When you finish a part, call \`superhands_report_part\` with \`part\` \u2014 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. Keep each design decision explicit. 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.
+   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.
+   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
+   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
+   run, read and supersede its lifecycleId. Later outputs do not inherit approval.
+   If trace recording fails, report that gap and continue the coding task.
+
+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
    \`instructionChanges\`: for each Instruction you built that part to, its key
    exactly as it was handed to you and one line on the concrete change it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-hands/connect",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "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"