pikasTech-HWLAB/skills/hwpod-cli/SKILL.md

name, description

name	description
hwpod-cli	Use HWLAB HWPOD from a code agent runner for hardware-development tasks. The hwpod-cli skill resolves an HWPOD by hwpod-id through the HWLAB runtime service, submits hwpod-node-ops through hwlab-api, and waits for hwpod-node results.

hwpod-cli

This skill follows Skill(cli-spec). It is the standard task entry for operating an HWPOD from the HWLAB v0.2 Code Agent workspace.

Standard Path

hwpod from PATH
  -> tools/hwpod-cli.ts
    -> runtime HWPOD registry by hwpod-id
    -> compiler-backed hwpod-node-ops plan
      -> /v1/hwpod-node-ops on hwlab-api
        -> hwpod-node on the host side

The HWPOD definition is runtime service state. The standard runner contract is --hwpod-id <id> plus --workspace-path <run-worktree> when the task is bound to a run-local workspace. A task may provide the complete hwpodWorkspaceArgs string; reuse it exactly. --spec <path> is only an explicit debug/import path for a local exported YAML, not the default runner contract.

Commands

• Inspect the HWPOD path: hwpod inspect --hwpod-id d601-f103-v2 --workspace-path <run-worktree>.
• Workspace search/read/edit: use hwpod workspace ls|cat|read|rg|grep|search|apply-patch --hwpod-id d601-f103-v2 --workspace-path <run-worktree>. read is an alias for cat; grep and search are aliases for rg; --file and --remote-path are accepted as path aliases for file-oriented commands.
• For symbol lookup or ARM-2D header hunting, prefer hwpod workspace rg <pattern> [path] --context 3 --hwpod-id d601-f103-v2 --workspace-path <run-worktree> instead of cat | grep.
• Build/download/reset: use hwpod build, hwpod download, and hwpod reset; the compiler must translate these through existing file ops and cmd.run where possible.
• Keil async status: after build/download returns a job id, use separate short hwpod job status <jobId> --hwpod-id d601-f103-v2 --workspace-path <run-worktree> calls instead of shell polling wrappers such as sleep &&, timeout, watch, head, pipes, or loops.
• UART read: use hwpod uart read --hwpod-id d601-f103-v2 --workspace-path <run-worktree> --port uart1; the compiler runs the configured serial-monitor CLI through cmd.run.

Boundaries

• Do not pass manual API URLs in locked AgentRun runtimes. Let HWLAB_RUNTIME_API_URL / HWLAB_RUNTIME_NAMESPACE select the current lane.
• Do not put full hwpod-spec on hwpod-node. The node only accepts hwpod-node-ops.
• Do not create, copy, restore, or repair runner-local .hwlab/hwpod-spec.yaml as a workaround. Use hwpod-id through the runtime service.
• Do not use deprecated workspace mutation commands (workspace write, replace, or insert-after) for normal source edits. Use workspace apply-patch.
• Treat cmd.run as the full-capability host execution op. Do not request new hwpod-node ops for build, download, job status, UART, PowerShell/cmd passthrough, or tool maintenance; improve hwpod-compiler-cli / hwpod-cli combinations first.
• Use workspace file operations for subject text edits. Do not use PowerShell/cmd heredocs for normal source edits unless debugging cmd.run itself.
• For multi-line edits, prefer hwpod workspace apply-patch with a Codex/UniDesk apply_patch v2 envelope from stdin or --patch-content. Put file paths in *** Update File: / *** Add File: / *** Delete File: headers. Do not pass raw unified diff (---, +++, @@ -N) as the whole patch; HWPOD deliberately rejects that format with a clear hint.
• If HWPOD returns a blocker, report and fix that blocker in this path.