pikasTech-HWLAB/docs/reference/commander-collaboration.md

HWLAB Commander Collaboration Reference

This reference defines stable commander, runner, branch, and prompt handoff rules.

Worktree Rules

• Use /workspace/hwlab as the normal runner and commander worktree.
• Start by checking the branch and working tree status.
• Keep D601 publishing and rollout work in /home/ubuntu/workspace/hwlab.
• Do not clean, reset, or reuse unrelated runner worktrees for publishing.

Branch And PR Workflow

• Create a short branch from latest origin/main.
• Do not push directly to main.
• Do not change PROD.
• Do not restart services unless a task explicitly authorizes it.
• Open a PR against pikasTech/HWLAB:main.
• Do not merge the PR from the runner.
• Let the commander review complex conflicts; runners should not perform broad conflict surgery unless explicitly assigned.

Prompt Contract

Every HWLAB runner task should be self-contained. Include:

• repository and worktree path;
• branch base and target PR branch;
• objective and linked issue context;
• current stable constraints, especially DC-DCSN-P0-2026-003 when relevant;
• forbidden actions;
• acceptance criteria;
• exact validation commands;
• final response requirements.

Do not assume the runner can read issue comments. When issue/PR visibility is needed, run:

node scripts/runner-issue-visibility-preflight.mjs

Use runner-issue-visibility-handoff.md as the detailed prompt handoff contract.

Review Guardrails

During review, reject outputs that:

• use SOURCE, LOCAL, DRY-RUN, fixtures, edge-only health, or front-end state as DEV-LIVE;
• bypass hwlab-patch-panel for M3;
• use UniDesk runtime as a substitute for HWLAB runtime;
• put Gate or diagnostics back as the default Cloud Web homepage;
• use legacy public :6666 or :6667 as current DEV entry points.

Stable Sources

• pikasTech/HWLAB#7: current commander board.
• pikasTech/HWLAB#78: M3 prompt and review constraints.
• pikasTech/HWLAB#109: documentation governance task.
• runner-issue-visibility-handoff.md: detailed runner visibility and prompt handoff.