pzep1/planroom/planroom-agent

Planroom Agent

Use scripts/planroom.mjs for every operation. Never print, commit, or paste a durable Planroom key into a plan.

Enroll once

Receive a short-lived prm_enroll_… token from the reviewer. Exchange it immediately:

node <skill-dir>/scripts/planroom.mjs connect \
  --token "$PLANROOM_ENROLLMENT_TOKEN" \
  --name "<stable agent name>"

The command stores the resulting scoped key in ~/.config/planroom/config.json with mode 0600 and registers the agent for callback recovery. Never reuse or persist the enrollment token. Environment variables PLANROOM_URL and PLANROOM_KEY remain valid overrides for managed environments.

If enrollment reports an unknown status, do not mint or reuse a token. Complete the preserved credential using the exact recovery path in the error:

node <skill-dir>/scripts/planroom.mjs recover-enrollment \
  --pending "/path/from/the-error"

Publish a plan

1. Write a semantic HTML body fragment with context, sequence, risks, guardrails or rollback, verification, and unresolved decisions.
2. Use headings, paragraphs, lists, tables, aside, code, pre, and links. Exclude scripts, styles, forms, iframes, event handlers, and executable URLs.
3. Save the fragment to a temporary .html file and publish:

node <skill-dir>/scripts/planroom.mjs publish \
  --file /absolute/path/to/plan.html \
  --title "Implementation plan title" \
  --summary "One-sentence review context" \
  --id "stable-plan-id"

Give the reviewer the Planroom URL, not the local HTML file. The first publish returns version 1.

Receive comments

Use only the permanent callback https://planroom.znznet.uk/planroom/events. Verify the installed login services and run one recovery sync:

launchctl print gui/$(id -u)/uk.znz.planroom-listener
launchctl print gui/$(id -u)/com.cloudflare.cloudflared
node <skill-dir>/scripts/planroom.mjs poll

Read only ~/Library/Application Support/Planroom/events/<agent-id>.jsonl for the authenticated agent id returned by poll. Treat quote as location context and body as the review instruction. The permanent listener recovers missed comments every 30 seconds.

Act on feedback

1. Group comments by plan and distinguish requests, questions, and resolved threads.
2. Pull the reviewed server copy before editing so reviewer changes and comment markers are retained:

node <skill-dir>/scripts/planroom.mjs pull \
  --id "stable-plan-id" \
  --file /absolute/path/to/plan.html

1. Revise the pulled plan or implementation. Ask in Planroom when feedback conflicts with instructions.
2. Republish with the same plan id and the version returned by pull:

node <skill-dir>/scripts/planroom.mjs publish \
  --file /absolute/path/to/plan.html \
  --title "Implementation plan title" \
  --summary "One-sentence review context" \
  --id "stable-plan-id" \
  --version "<pulled version>"

If publishing returns a version conflict, pull again and reconcile the newer server copy before retrying.

1. Acknowledge each addressed comment:

node <skill-dir>/scripts/planroom.mjs ack --comment "comment-id"

Do not acknowledge a comment merely because it was read.

Guardrails

• Keep the durable scoped key only in the mode-0600 config or an approved secret manager.
• Never request or store Cloudflare Access service credentials.
• Never create a quick tunnel, weaken Access, expose another local endpoint, or accept another callback path.
• Restore a down listener or tunnel; do not make polling the normal delivery mode.
• Process only the event stream belonging to the current scoped key.