create-harness-vibe-coding 0.8.19 → 0.9.3

package/templates/common/Harness/a2a/role-graph.json

@@ -1,5 +1,18 @@
 {
   "schemaVersion": 1,
+  "roleVocabulary": {
+    "note": "Canonical roleTitle vocabulary for session role profiles (spec §3.1/§3.2). roleTitle is the session/profile vocabulary; this file remains the role graph vocabulary (agentId, kind, skills, permissions).",
+    "canonical": ["ceo", "manager", "implementer", "reviewer", "verifier", "planner", "terminal-controller"],
+    "kindToRoleTitle": {
+      "controller": "ceo",
+      "planner": "planner",
+      "architecture": "architect",
+      "implementer": "implementer",
+      "review": "reviewer",
+      "validation": "verifier",
+      "runtime": "terminal-controller"
+    }
+  },
   "rootAgentId": "ceo",
   "agents": [
     {
@@ -7,7 +20,7 @@
       "role": "CEO Leader",
       "level": 0,
       "kind": "controller",
-      "skills": ["wf", "subagent-orchestrator", "terminal-control"],
+      "skills": ["wf", "subagent-orchestrator", "terminal-control", "workflow-node-map", "workflow-ontology", "workflow-context", "workflow-node-actions"],
       "permissions": ["plan", "dispatch", "read-terminals", "send-terminal-input"]
     },
     {
@@ -31,7 +44,7 @@
       "role": "Backend Expert",
       "level": 1,
       "kind": "implementer",
-      "skills": ["runtime-detection", "terminal-control", "a2a-files"],
+      "skills": ["runtime-detection", "terminal-control", "workflow-node-map", "workflow-ontology", "workflow-context", "workflow-node-actions", "a2a-files"],
       "permissions": ["read-code", "write-backend", "terminal-io"]
     },
     {
@@ -63,7 +76,7 @@
       "role": "Terminal Controller",
       "level": 1,
       "kind": "runtime",
-      "skills": ["terminal-control"],
+      "skills": ["terminal-control", "workflow-node-map", "workflow-ontology", "workflow-context", "workflow-node-actions"],
       "permissions": ["read-terminals", "send-terminal-input"]
     }
   ],

package/templates/common/Harness/a2a/skills/terminal-control.json

@@ -4,12 +4,56 @@
   "name": "Terminal Control",
   "source": "Harness/a2a/skills/terminal-control.json",
   "description": "Bounded A2A tools for listing terminal sessions, reading output ranges, globbing terminal events, and attach-gated input forwarding.",
+  "triggers": [
+    "list sessions",
+    "read terminal",
+    "read transcript",
+    "tail output",
+    "send input",
+    "send agent message",
+    "broadcast agent message",
+    "delegate agent",
+    "agent messages",
+    "read agent output",
+    "bridge messages",
+    "terminal events"
+  ],
   "tools": [
     { "name": "list-sessions", "reads": ["Harness/tasks/**/sessions/**/STATE.json"] },
     { "name": "read-range", "reads": ["Harness/tasks/**/sessions/**/terminal.jsonl"], "args": ["session", "from", "to", "tail"] },
     { "name": "glob-events", "reads": ["Harness/tasks/**/sessions/**/events.jsonl"], "args": ["pattern", "since", "limit"] },
-    { "name": "send-input", "writes": ["Harness/tasks/**/sessions/**/input-requests.jsonl"], "args": ["session", "text"] }
+    { "name": "send-input", "writes": ["Harness/tasks/**/sessions/**/input-requests.jsonl"], "args": ["session", "text"] },
+    { "name": "send-agent-message", "writes": ["Harness/tasks/**/sessions/**/input-requests.jsonl", "Harness/a2a/bridges/**"], "args": ["to", "text"] },
+    { "name": "broadcast-agent-message", "writes": ["Harness/tasks/**/sessions/**/input-requests.jsonl", "Harness/a2a/bridges/**"], "args": ["to", "text", "topic"] },
+    { "name": "read-agent-messages", "reads": ["Harness/a2a/bridges/**"], "args": ["peer", "tail"] },
+    { "name": "delegate-agent", "writes": ["Harness/tasks/**/sessions/**/input-requests.jsonl", "Harness/a2a/bridges/**"], "args": ["node", "text"] },
+    { "name": "read-agent", "reads": ["Harness/tasks/**/sessions/**/terminal.jsonl"], "args": ["node", "action", "tail"] }
   ],
+  "tuiControl": {
+    "summary": "Rules for driving interactive TUI sessions (codex/claude) via send-input and send-key.",
+    "charByCharTyping": {
+      "rule": "TUI input must be typed char-by-char (~12ms/char). Bulk-writing a prompt and pressing Enter leaves the text unsubmitted.",
+      "backendHandled": true,
+      "note": "The backend send-input/envelope paths type char-by-char automatically; agents do not do it manually, but must not rely on bulk-paste behavior."
+    },
+    "sendKey": {
+      "command": "node Harness/scripts/wf-ui-control.mjs send-key <key>",
+      "keys": ["up", "down", "left", "right", "enter", "esc", "tab", "backspace"],
+      "usage": "Public primitive for TUI navigation (menus, pickers, model switcher)."
+    },
+    "modelPicker": {
+      "recipe": "send-input \"/model\", then send-key up/down to navigate, send-key enter to confirm, send-key esc to cancel.",
+      "verifiedAgainst": "codex 0.147.0 TUI picker"
+    },
+    "preferredModelSwitch": {
+      "action": "agent.setModel backend action",
+      "why": "Non-interactive alternative: writes the project-scoped runtime config (e.g. .codex/config.toml model field), then restartRequired."
+    },
+    "warnings": [
+      "Never send \\r\\n - double-submit risk.",
+      "A lone \\r can be interpreted as interrupt in some TUI states."
+    ]
+  },
   "defaultMode": "watch",
   "inputPolicy": "attach-mode-required"
 }

package/templates/common/Harness/a2a/skills/wf-ui-map.json

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": 1,
+  "skillId": "wf-ui-map",
+  "name": "WF UI Map Legacy Alias",
+  "source": "Harness/a2a/skills/wf-ui-map.json",
+  "compatibilityAliasFor": "workflow-node-map",
+  "description": "Compatibility alias for workflow-node-map. Prefer workflow-node-map in new Agent prompts; node-map remains supported for older nodes.",
+  "environment": [
+    "HARNESS_PEER_SESSION_ID",
+    "HARNESS_PEER_RUNTIME",
+    "HARNESS_AGENT_KIND",
+    "HARNESS_WORKFLOW_MODE",
+    "HARNESS_WORKFLOW_NODE_ID",
+    "HARNESS_WORKFLOW_MAP",
+    "HARNESS_NODE_HOME",
+    "HARNESS_NODE_INIT",
+    "HARNESS_WF_UI_URL"
+  ],
+  "policy": {
+    "mainAgent": [
+      "api-only-node-map-control",
+      "no-direct-workflow-map-writes",
+      "workflow-node-map",
+      "read-workflow-map-diagnostic-only",
+      "agent.readGraph",
+      "agent.createNode",
+      "agent.connectNodes",
+      "agent.disconnectNodes",
+      "agent.moveNode",
+      "agent.deleteNode",
+      "agent.deleteNodes",
+      "create-subagent-node",
+      "connect-managed-nodes",
+      "delete-saved-node",
+      "stop-managed-node"
+    ],
+    "subagent": [
+      "read-workflow-map-diagnostic-only",
+      "return-evidence"
+    ],
+    "subagentDenied": [
+      "create-agent-node",
+      "create-task-node",
+      "workflow-node-map-control",
+      "node-map-control",
+      "workflow-map-file-mutation",
+      "spawn-pty-subagents"
+    ]
+  }
+}

package/templates/common/Harness/a2a/skills/workflow-agent-node.json

@@ -0,0 +1,143 @@
+{
+  "schemaVersion": 1,
+  "skillId": "workflow-agent-node",
+  "name": "Workflow Agent Node",
+  "source": "Harness/a2a/skills/workflow-agent-node.json",
+  "description": "On-demand Agent guide for delegating to and reading connected Agent nodes through backend and wf-bridge actions.",
+  "nodeType": "agent",
+  "roleProfile": {
+    "howToRead": "Read your own profile with node Harness/scripts/wf-ui-control.mjs workflow-context --project . ; the context carries your roleProfile block with displayName, roleTitle, responsibility, capabilities, and roleProfileRef. roleProfileRef points at the markdown profile file under Harness/a2a/agent-roles/. Your roleTitle comes from the canonical vocabulary (ceo, manager, implementer, reviewer, verifier, planner, terminal-controller) or a free-form role. Act inside your responsibility; ask the coordinating agent before expanding scope."
+  },
+  "decisionFlow": [
+    "Understand the task from the user request.",
+    "Decide whether team collaboration is needed: simple requests are handled directly with no team; complex or multi-skill work gets a team.",
+    "Select the subagent mode per subagentModes: default to built-in-subagents; use wf-node-subagents only when the user explicitly asks for canvas Agent nodes.",
+    "Choose the required roles from the canonical roleTitle vocabulary: ceo, manager, implementer, reviewer, verifier, planner, terminal-controller.",
+    "Find existing agents by role, runtime, provider, capability, or title.",
+    "Exactly one unambiguous match: auto-connect that agent.",
+    "No match and the task target is clear: create an agent with a full role profile (displayName, roleTitle, responsibility, capabilities, roleProfileRef).",
+    "Multiple matches or an unclear target: ask the user; never blindly create or connect.",
+    "Share durable context through Markdown nodes, referenced by nodeId only.",
+    "Send structured requests with a requestId, wait via Timer wakeup messages, and aggregate replies per request.",
+    "Tick the connected Goal node's items as they finish; call goal.complete when every item is checked; report to the user in plain language."
+  ],
+  "goalPlanning": {
+    "guidance": "Plans, plan tables, and goal setting default to the workflow Goal node. Do not use runtime built-in goal/task tools for planning when a workflow map is present.",
+    "flow": [
+      "Before planning, read workflow-context to find the Goal node connected to you (direct edge or same Timer/Agent group).",
+      "Goal node found and connected: write the plan with goal.add / goal.replace, tick progress with goal.check / goal.uncheck, and call goal.complete when every item is checked.",
+      "Goal node found but not connected: connect it with node Harness/scripts/wf-ui-control.mjs connect --actor <your-graph-node-id> --from <your-graph-node-id> --to <goal-node-id> --relation goal, then move it above your node with node Harness/scripts/wf-ui-control.mjs node-map --action moveNode --node <goal-node-id> --x <your-x> --y <your-y-above>.",
+      "No Goal node exists: create one with node Harness/scripts/wf-ui-control.mjs node-map --action createNode --type goal --title '<task> goal' --x <your-x> --y <your-y-above>, then connect it as above and write the plan into it.",
+      "Respect singleGoalPerGroup: one Goal per Timer/Agent group; if goal_already_bound is returned, use the existing Goal."
+    ],
+    "preferGoalNodeOverBuiltins": true
+  },
+  "subagentModes": {
+    "note": "2x2 subagent strategy matrix. Mode is set via Agent node settings or detected from natural language; unspecified defaults to built-in-subagents.",
+    "default": "built-in-subagents",
+    "matrix": [
+      {
+        "mode": "built-in-subagents",
+        "behavior": "Use the current runtime's native subagent mechanism. Do NOT create WF canvas Agent nodes.",
+        "evidence": ["fanoutAttempted", "channel", "roles", "native subagent evidence"],
+        "nlTriggers": ["内部助手", "内置子代理", "不要开画布节点", "native subagent", "built-in"]
+      },
+      {
+        "mode": "wf-node-subagents",
+        "behavior": "Create/connect WF Agent nodes on canvas. Use mailbox for communication. Timer/Markdown/Goal nodes visible and collaborative.",
+        "evidence": ["WF Agent nodes", "edges", "mailbox evidence"],
+        "nlTriggers": ["画布Agent节点", "开Claude Code节点", "WF node协作", "可视化协作", "canvas worker"]
+      }
+    ],
+    "runtimeDegradation": "If the current runtime has no native subagent adapter and mode is built-in-subagents, record clear degradation evidence and inform the user. Codex main can use wf-node-subagents to dispatch tasks to Claude Code implementer nodes and aggregate replies."
+  },
+  "structuredRequests": {
+    "guidance": "Give every team request a requestId and reuse it for all messages of that request. Reference shared Markdown nodes in contextRefs by nodeId only — never inline Markdown bodies or long content in the message text.",
+    "inputEnvelope": "A structured request arrives in your terminal as a compact prefix before the text, e.g. [harness-request req-20260812-0001 to-role=implementer contextRefs=markdown-2a1] <text>. On receiving one, reply via send-agent-message with the SAME requestId and set --reply-to to the message id you are answering, so the sender can aggregate the replies.",
+    "envelopeFields": ["requestId", "replyTo", "contextRefs"],
+    "rules": [
+      "requestId: sender-generated; the receiver echoes it in replies so you can aggregate them.",
+      "replyTo: set to the message id you are answering.",
+      "contextRefs: nodeId references only; the receiver reads the node through typed actions."
+    ]
+  },
+  "wakeupMessages": {
+    "guidance": "Timers are the only source of wakeup messages; the Goal node never wakes agents. When a wakeup message arrives (type 'wakeup'), read it on your next turn. It carries timerNodeId, scheduledAt, firedAt, and goalNodeId when the group has a Goal node.",
+    "goalCheck": "When the wakeup message references a Goal node, read the Goal state first and tick its items before continuing work."
+  },
+  "goalTicking": {
+    "guidance": "Tick Goal plan items as you finish them with goal.check; use goal.uncheck when an item is back in progress. When every item is checked, call goal.complete. If goal.complete returns goal_items_pending, check the listed items first, then retry.",
+    "completeRequiresAllChecked": true
+  },
+  "markdownBlackboard": {
+    "guidance": "Share durable context through Markdown nodes; reference them by nodeId only in requests. Before writing, find the node, acquire a lock, write with the current revision, then release the lock. On markdown_conflict, reread, merge, and retry with the fresh revision."
+  },
+  "triggers": [
+    "agent node",
+    "delegate agent",
+    "send agent message",
+    "broadcast agent message",
+    "reply agent",
+    "agent direct message",
+    "agent group message",
+    "shared context",
+    "发送消息",
+    "群发消息",
+    "回复 Agent",
+    "共享上下文",
+    "共享 Markdown",
+    "read agent output",
+    "read transcript",
+    "start agent",
+    "stop agent",
+    "connected agent"
+  ],
+  "controlSurface": {
+    "sendMessage": "POST /api/workflow/nodes/:sender/actions/agent.sendMessage",
+    "broadcastMessage": "POST /api/workflow/nodes/:sender/actions/agent.broadcastMessage",
+    "readMessages": "POST /api/workflow/nodes/:sender/actions/agent.readMessages",
+    "sendInput": "POST /api/workflow/nodes/:node/actions/agent.sendInput",
+    "readOutput": "POST /api/workflow/nodes/:node/actions/agent.readOutput",
+    "bridge": "wf-bridge routes record Agent-to-Agent communication.",
+    "storage": "Harness/a2a/nodes/** and terminal logs are runtime records, not manual control surfaces."
+  },
+  "environment": [
+    "HARNESS_PEER_SESSION_ID",
+    "HARNESS_PEER_RUNTIME",
+    "HARNESS_AGENT_KIND",
+    "HARNESS_WORKFLOW_MODE",
+    "HARNESS_WORKFLOW_NODE_ID",
+    "HARNESS_WORKFLOW_MAP",
+    "HARNESS_NODE_HOME",
+    "HARNESS_NODE_INIT",
+    "HARNESS_WF_UI_URL"
+  ],
+  "policy": {
+    "allowed": [
+      "agent.readContext",
+      "agent.readOutput",
+      "agent.readTranscript",
+      "agent.sendMessage",
+      "agent.broadcastMessage",
+      "agent.readMessages",
+      "agent.sendInput"
+    ],
+    "requires": [
+      "connected-agent-ref",
+      "typed-backend-agent-actions"
+    ],
+    "denied": [
+      "node-home-file-mutation",
+      "terminal-log-mutation",
+      "session-state-file-mutation",
+      "direct-json-state-mutation",
+      "unmanaged-pty-spawn"
+    ]
+  },
+  "prohibitions": [
+    "Never edit `Harness/a2a/**/state.json` directly — use typed actions.",
+    "Never edit node-home files, terminal logs, or session state files.",
+    "Never spawn unmanaged PTY sessions.",
+    "Never inline Markdown node bodies in a message payload; reference them by nodeId only."
+  ]
+}

package/templates/common/Harness/a2a/skills/workflow-context.json

@@ -0,0 +1,95 @@
+{
+  "schemaVersion": 1,
+  "skillId": "workflow-context",
+  "name": "Workflow Context",
+  "source": "Harness/a2a/skills/workflow-context.json",
+  "description": "Canonical read-only workflow context commands for Agent nodes. Uses GET /api/workflow/context/:node for connected refs.",
+  "triggers": [
+    "read context",
+    "workflow context",
+    "node map context",
+    "graph context",
+    "connected nodes",
+    "what am I connected to",
+    "what is connected",
+    "nearby nodes",
+    "linked nodes",
+    "connected resources",
+    "connected agents",
+    "connected peers",
+    "goal refs",
+    "goal node",
+    "timer refs",
+    "timer node",
+    "agent node",
+    "node identity",
+    "current node",
+    "current task",
+    "current goal",
+    "workflow status",
+    "edge refs",
+    "handle refs",
+    "port refs",
+    "magnet dock",
+    "resource node",
+    "output node",
+    "effective skills",
+    "where am I",
+    "observe before acting",
+    "感知节点",
+    "读取上下文",
+    "连接了什么",
+    "连接的节点",
+    "周围节点",
+    "节点身份",
+    "当前节点",
+    "当前任务",
+    "当前目标",
+    "磁吸连接",
+    "连接状态",
+    "是否有连接",
+    "检查连接",
+    "连线",
+    "谁连着",
+    "我连着",
+    "自己连接",
+    "node map 连接"
+  ],
+  "environment": [
+    "HARNESS_PEER_SESSION_ID",
+    "HARNESS_PEER_RUNTIME",
+    "HARNESS_AGENT_KIND",
+    "HARNESS_WORKFLOW_MODE",
+    "HARNESS_WORKFLOW_NODE_ID",
+    "HARNESS_WORKFLOW_MAP",
+    "HARNESS_NODE_HOME",
+    "HARNESS_NODE_INIT",
+    "HARNESS_WF_UI_URL"
+  ],
+  "policy": {
+    "mainAgent": [
+      "workflow-context",
+      "read-connected-context",
+      "read-workflow-snapshot",
+      "read-workflow-map-diagnostic-only",
+      "read-bridge-messages"
+    ],
+    "subagent": [
+      "workflow-context",
+      "read-self-context",
+      "read-workflow-map-diagnostic-only",
+      "return-evidence"
+    ],
+    "denied": [
+      "no-source-file-reads-for-graph-state",
+      "workflow-map-file-mutation",
+      "component-state-file-mutation",
+      "event-state-file-mutation",
+      "goal-state-file-mutation",
+      "capability-state-file-mutation",
+      "direct-json-state-mutation",
+      "node-home-file-mutation",
+      "task-state-mutation"
+    ]
+  }
+}

package/templates/common/Harness/a2a/skills/workflow-diagram-node.json

@@ -0,0 +1,60 @@
+{
+  "schemaVersion": 1,
+  "skillId": "workflow-diagram-node",
+  "name": "Workflow Diagram Node",
+  "source": "Harness/a2a/skills/workflow-diagram-node.json",
+  "description": "On-demand Agent guide for reading and writing Excalidraw Diagram nodes through typed backend actions only.",
+  "nodeType": "excalidraw",
+  "createKind": "diagram",
+  "triggers": [
+    "diagram node",
+    "excalidraw node",
+    "draw diagram",
+    "draw flowchart",
+    "save scene",
+    "connected diagram",
+    "visual output"
+  ],
+  "controlSurface": {
+    "endpoint": "POST /api/workflow/nodes/:node/actions/:action",
+    "readContextFirst": "node Harness/scripts/wf-ui-control.mjs workflow-context --project .",
+    "storage": "Harness/a2a/component-nodes/**/state.json is backend-owned diagnostic storage, never an Agent control surface.",
+    "outputRouting": "Prefer connected writable Diagram nodes for flowcharts, sketches, architecture maps, and visual plans."
+  },
+  "environment": [
+    "HARNESS_PEER_SESSION_ID",
+    "HARNESS_PEER_RUNTIME",
+    "HARNESS_AGENT_KIND",
+    "HARNESS_WORKFLOW_MODE",
+    "HARNESS_WORKFLOW_NODE_ID",
+    "HARNESS_WORKFLOW_MAP",
+    "HARNESS_NODE_HOME",
+    "HARNESS_NODE_INIT",
+    "HARNESS_WF_UI_URL"
+  ],
+  "policy": {
+    "allowed": [
+      "excalidraw.readScene",
+      "excalidraw.saveScene",
+      "excalidraw.patchScene",
+      "excalidraw.renderPreview"
+    ],
+    "requires": [
+      "workflow-context-before-action",
+      "connected-resource-ref",
+      "typed-backend-node-actions"
+    ],
+    "denied": [
+      "component-state-file-mutation",
+      "direct-component-node-state-file-edit",
+      "direct-json-state-mutation",
+      "workflow-map-file-mutation"
+    ]
+  },
+  "prohibitions": [
+    "Never edit `Harness/a2a/**/state.json` directly — use typed actions.",
+    "Never edit component-node state files or the workflow map file.",
+    "Never overwrite a scene without reading it first: readScene before saveScene or patchScene.",
+    "Never invent node actions that the backend does not expose; read this manual before acting."
+  ]
+}

package/templates/common/Harness/a2a/skills/workflow-display-node.json

@@ -0,0 +1,69 @@
+{
+  "schemaVersion": 1,
+  "skillId": "workflow-display-node",
+  "name": "Workflow Display Node",
+  "source": "Harness/a2a/skills/workflow-display-node.json",
+  "description": "On-demand Agent guide for presenting reports to the USER through Display nodes (HTML reports rendered fullscreen on the canvas).",
+  "nodeType": "display",
+  "triggers": [
+    "display node",
+    "report",
+    "present findings",
+    "user-facing summary",
+    "html report"
+  ],
+  "controlSurface": {
+    "endpoint": "POST /api/workflow/nodes/:node/actions/:action",
+    "readContextFirst": "node Harness/scripts/wf-ui-control.mjs workflow-context --project .",
+    "storage": "Harness/a2a/component-nodes/**/state.json + <nodeDir>/report.html (backend-owned)"
+  },
+  "environment": [
+    "HARNESS_PEER_SESSION_ID",
+    "HARNESS_PEER_RUNTIME",
+    "HARNESS_AGENT_KIND",
+    "HARNESS_WORKFLOW_MODE",
+    "HARNESS_WORKFLOW_NODE_ID",
+    "HARNESS_WORKFLOW_MAP",
+    "HARNESS_NODE_HOME",
+    "HARNESS_NODE_INIT",
+    "HARNESS_WF_UI_URL"
+  ],
+  "policy": {
+    "allowed": [
+      "display.write",
+      "display.read"
+    ],
+    "requires": [],
+    "denied": [
+      "component-state-file-mutation",
+      "direct-component-node-state-file-edit",
+      "direct-json-state-mutation",
+      "absolute-path-leakage",
+      "secret-payloads"
+    ]
+  },
+  "usage": {
+    "whenToUse": {
+      "trigger": "When your task produces a report, research findings, comparison tables, decision summaries, or anything the USER should read on the canvas — and the user has NOT explicitly named a target file — write it to a Display node with display.write.",
+      "neverDo": "Writing or modifying .html files is normal work and always allowed. But when presenting results: do not dump long reports into chat and never try to open a browser yourself — unless the user named a specific file, present through a Display node."
+    },
+    "write": "display.write with a full self-contained HTML document (html param). The user opens the node fullscreen; the content runs with fully-open JS (same trust as your own terminal).",
+    "read": "display.read returns the current HTML plus this usage guide.",
+    "revisionGuard": "display.write accepts optional expectedRevision; a mismatch refuses the write so concurrent writers do not clobber each other.",
+    "locking": "markdown-style locks apply: acquire a lock before long multi-step edits; a lock held by another holder refuses writes."
+  },
+  "theme": {
+    "palette": "White background, blue #2563EB, ink #111827, muted #6B7280, Claude yellow/terracotta #D97757 for accents.",
+    "semanticClasses": "Use semantic classes for the clean look: .report-title, .report-meta, .report-section, .card, .metric, .highlight, .muted, .badge. The default template already ships the full stylesheet — extend it, do not fight it."
+  },
+  "diagrams": {
+    "embedExcalidraw": "Embed an Excalidraw node scene anywhere in the HTML with the placeholder {{excalidraw:<nodeId>}}. At serve time the backend expands it to a self-contained inline SVG (no CDN, no runtime JS) with a link to open the interactive node.",
+    "findingNodeIds": "Use excalidraw.readScene on the target node to confirm it exists; the placeholder needs the exact nodeId (e.g. component-diagram-abc123)."
+  },
+  "prohibitions": [
+    "Never edit `Harness/a2a/**/state.json` directly — use typed actions.",
+    "Never edit component-node state files or the workflow map file.",
+    "Never open a browser or an HTML file yourself to present results — write to the Display node instead, unless the user named a specific file.",
+    "Never put secret or credential payloads in node actions; action payloads may be recorded."
+  ]
+}

package/templates/common/Harness/a2a/skills/workflow-file-node.json

@@ -0,0 +1,92 @@
+{
+  "schemaVersion": 1,
+  "skillId": "workflow-file-node",
+  "name": "Workflow File Node",
+  "source": "Harness/a2a/skills/workflow-file-node.json",
+  "description": "On-demand Agent guide for inspecting File nodes through typed backend actions only.",
+  "nodeType": "file",
+  "triggers": [
+    "file node",
+    "read file",
+    "file metadata",
+    "workspace file",
+    "uploaded file",
+    "connected file"
+  ],
+  "controlSurface": {
+    "endpoint": "POST /api/workflow/nodes/:node/actions/:action",
+    "readContextFirst": "node Harness/scripts/wf-ui-control.mjs workflow-context --project .",
+    "storage": "Harness/a2a/component-nodes/**/state.json is backend-owned diagnostic storage, never an Agent control surface.",
+    "contentRoute": "Use backend file/meta/text routes exposed by the File node adapter; do not infer absolute filesystem paths from state files."
+  },
+  "environment": [
+    "HARNESS_PEER_SESSION_ID",
+    "HARNESS_PEER_RUNTIME",
+    "HARNESS_AGENT_KIND",
+    "HARNESS_WORKFLOW_MODE",
+    "HARNESS_WORKFLOW_NODE_ID",
+    "HARNESS_WORKFLOW_MAP",
+    "HARNESS_NODE_HOME",
+    "HARNESS_NODE_INIT",
+    "HARNESS_WF_UI_URL"
+  ],
+  "policy": {
+    "allowed": [
+      "file.readMeta",
+      "file.readText",
+      "file.readBytes",
+      "file.refresh",
+      "file.preview",
+      "file.writeText",
+      "file.acquireLock",
+      "file.releaseLock",
+      "file.readXlsx",
+      "file.readXlsxSheet",
+      "file.readPdf",
+      "file.readPdfPage",
+      "file.readZipEntries",
+      "file.readZipEntry",
+      "file.extractZipEntry"
+    ],
+    "requires": [
+      "workflow-context-before-action",
+      "connected-resource-ref",
+      "typed-backend-node-actions"
+    ],
+    "denied": [
+      "component-state-file-mutation",
+      "direct-component-node-state-file-edit",
+      "direct-json-state-mutation",
+      "absolute-path-leakage",
+      "secret-payloads"
+    ]
+  },
+  "usage": {
+    "excel": {
+      "readXlsx": "List the sheet names of the bound .xlsx workbook: {sheets: [names]}.",
+      "readXlsxSheet": "Read one sheet paged: {sheet, page, pageSize}. sheet accepts a sheet name or a 1-based index and defaults to the first sheet. Returns headers plus the requested page of data rows; rows are bounded by pageSize and totalPages is included, so a workbook is never returned whole.",
+      "errors": "Corrupt or unreadable .xlsx files fail with a machine-readable error (code XLSX_PARSE, status 400)."
+    },
+    "pdf": {
+      "readPdf": "Return the bound PDF's total page count and document metadata: {totalPages, metadata: {title, author, subject, keywords, creator, producer, ...}}.",
+      "readPdfPage": "Extract a page range as text: {page, pageCount}. Text is returned with the isEvalSupported:false security baseline — no JavaScript evaluation is ever enabled during rendering.",
+      "errors": "Corrupt or unreadable PDF files fail with a clear machine-readable error (code PDF_PARSE, status 400)."
+    },
+    "zip": {
+      "readZipEntries": "List archive entries: {name, size, compressedSize, directory, isUtf8}. The archive is walked lazily — never read whole into memory; GBK-encoded legacy file names are decoded automatically.",
+      "readZipEntry": "Preview a single text entry: {entryName, maxBytes?}. The preview is bounded by maxBytes (default 65536) and flagged truncated when capped. Only text-like extensions are allowed (.txt/.md/.json/.js/.ts/.css/.html/.csv/.log/.yaml/.yml); binary entries are refused with ZIP_ENTRY_NOT_TEXT.",
+      "extractZipEntry": "Extract a single entry into a workspace-controlled destDir: {entryName, destDir?}. destDir defaults to Harness/a2a/file-extracts/<nodeId>/ and must stay inside the workspace. Entry names with ../ or ..\\ segments or absolute paths are rejected (ZIP_SLIP), so nothing can escape the archive or the workspace."
+    },
+    "locks": {
+      "acquireLock": "Acquire (or renew) a write lease on the file node: {holder, ttlMs?, lockId?}. The lease is persisted in backend-owned state (survives restarts), expires after the TTL, and stale leases are reclaimed automatically. While a foreign lease is live, file.writeText refuses with 409 file_locked carrying holder and expiresAt.",
+      "releaseLock": "Release the lease; only the holder may release: {holder, lockId?}. Missing or already-expired leases are a no-op (released: false)."
+    }
+  },
+  "prohibitions": [
+    "Never edit `Harness/a2a/**/state.json` directly — use typed actions.",
+    "Never edit component-node state files or the workflow map file.",
+    "Never infer absolute filesystem paths from state files; use the backend file routes only.",
+    "Never put secret or credential payloads in node actions; action payloads may be recorded.",
+    "Never pass extraction destDir values that escape the workspace; file.extractZipEntry rejects them."
+  ]
+}