Section 11

Web Choices

Set up the web-choices HITL workflow for this project before asking for any choice or feedback.


setup agent prompt
Set up the web-choices HITL workflow for this project before asking for any choice or feedback.

1. Inspect `~/.agents/skills/web-choices/SKILL.md` and use the skill-local implementation at `~/.agents/skills/web-choices`. Confirm `bun`, `tmux`, `tailscale`, and `jq` are available.

2. In `~/.agents/skills/web-choices`, run `bun run build` and confirm the Bun + Vite + Svelte + mdsvex app builds successfully. Do not replace it with a generated HTML form, Markdown page, or one-off UI. Oracle-generated choices must stay JSON data, not compiled Svelte/mdsvex content.

3. From the project directory, configure runtime state:
`export WEB_CHOICES_SKILL_DIR="$HOME/.agents/skills/web-choices"`
`export HITL_OUT_DIR="$PWD/.hitl-choice"`
`export HITL_HOST="127.0.0.1"`
`export HITL_PORT="8877"`

4. Start the skill-local server in tmux:
`bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" server --out-dir "$HITL_OUT_DIR" --host "$HITL_HOST" --port "$HITL_PORT" --tmux`

5. Confirm `$HITL_OUT_DIR/.token` exists and is non-empty. Read it as `TOKEN="$(cat "$HITL_OUT_DIR/.token")"` but do not print or paste the token except inside the final phone URL.

6. Confirm the local server is alive:
`bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" status --out-dir "$HITL_OUT_DIR" --url "http://127.0.0.1:$HITL_PORT" --token-file "$HITL_OUT_DIR/.token"`

7. Generate the choice job as strict JSON. If project context matters, use `$oracle-packx` first and wait for Oracle to finish before continuing. Ask Oracle for a job with `jobId`, `title`, `description`, `createdAt`, and `options`; each option should include stable `id`, `title`, `description`, `tags`, `risk`, `suggestedProofCommands`, and `expectedEvidence`. Save the result as `./web-choices-job.json`.

8. Validate the JSON parses cleanly and has the expected fields. Before pushing, inspect current status. If an active job already exists, report its `jobId` and do not use `--replace` unless replacement is explicitly approved.

9. Push the validated job:
`bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" push ./web-choices-job.json --url "http://127.0.0.1:$HITL_PORT" --token-file "$HITL_OUT_DIR/.token"`

10. Confirm the local API returns the expected job and option count:
`curl -fsS "http://127.0.0.1:$HITL_PORT/api/jobs/current?token=$TOKEN" | jq '{jobId:.jobId, optionCount:(.options | length)}'`

11. Start Tailscale Funnel only after local checks pass:
`tailscale funnel --bg --yes "$HITL_PORT"`
`tailscale funnel status`

12. Use the HTTPS hostname from `tailscale funnel status` as `PUBLIC_BASE`. Verify the tailnet URL returns the same `jobId` and option count:
`curl -fsS "$PUBLIC_BASE/api/jobs/current?token=$TOKEN" | jq '{jobId:.jobId, optionCount:(.options | length)}'`

13. Only after the local and tailnet checks match, report the phone URL as `$PUBLIC_BASE/?token=<HITL_TOKEN>`, the active `jobId`, the out dir path, and that the tmux server will stay running while drafts and submissions are saved server-side.

14. Wait locally without a timeout unless told otherwise:
`bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" wait --job "<jobId>" --out-dir "$HITL_OUT_DIR"`

15. After submission, inspect `$HITL_OUT_DIR/submissions.jsonl` and `$HITL_OUT_DIR/submissions/<submissionId>.json`. Report the submission id, selected option ids and titles, selected count, per-option feedback, overall feedback, and the exact saved submission path. Continue only from that saved JSON file, not chat memory.

16. Privacy and safety expectations: do not expose sensitive choices through Funnel without explicit approval. Treat the token as a short-lived gate, not full authentication. Do not paste secrets, cookies, private endpoints, API keys, raw config dumps, or full environment output into the job. Do not commit `.hitl-choice`, `.token`, drafts, or submissions unless explicitly asked and reviewed.

17. Cleanup expectations: leave the tmux server running while review is active. When finished or asked to clean up, report what is still running, stop Funnel, stop the tmux server if appropriate, and preserve `$HITL_OUT_DIR/current-job.json`, `drafts/`, `submissions.jsonl`, and `submissions/<submissionId>.json` as durable decision state.

18. If something fails, preserve state first. For tunnel issues, keep the same server, job, and token, restart Funnel, and recheck the public API. For server issues, inspect `$HITL_OUT_DIR` before restarting with the same out dir. If submission seems stuck, check `submissions.jsonl`, `submissions/`, server logs, and `http://127.0.0.1:$HITL_PORT/api/jobs/<jobId>/submissions/status?token=$TOKEN`.

Workflow route

Web Choices

Set up the web-choices HITL workflow for this project before asking for any choice or feedback.

Eggo slides a selected option into a saved JSON slot for the Web Choices workflow.
Intent

Decide when generated options need a saved human choice.

Evidence

Keep the active job, drafts, and submission as JSON evidence.

Route

Serve the choice UI through the skill-local Web Choices app.

Verify

Resume only after the decision packet is saved.

  1. Big Idea
  2. Skill Reference Or Files To Inspect
  3. When To Reach For This
  4. How This Used To Work
  5. The Mental Model
  6. Oracle Pairing
one option locks in while unchosen cards remain parked

Big Idea

Use $web-choices when the agent can generate useful options, but the next move needs an intentional pick, ranking, or written feedback before implementation continues.

The workflow turns agent-generated choices into a small Svelte/mdsvex web app, serves it from the local machine, opens it through Tailscale Funnel, waits while a phone or browser submits a decision, then resumes from saved JSON.

This is especially useful when the agent is running unattended and a quick phone review is enough to unblock it.

Skill Reference Or Files To Inspect

The skill-local app owns the UI. Project work should provide the context, generated choices, and follow-up action.

When To Reach For This

Use it when:

Good software-project choice sets:

How This Used To Work

The agent would usually paste a numbered list in chat and wait. That works for tiny decisions, but it is easy to lose context, hard to review on a phone, and awkward when feedback belongs on individual options.

With $web-choices, the choice state is durable:

The Mental Model

snippet-1
generate options -> serve a choice UI -> open phone URL -> wait -> read saved JSON -> continue

The agent is not guessing from chat memory. It should inspect the submitted JSON and treat that file as the next instruction packet.

Oracle Pairing

Pair $oracle-packx with $web-choices when choices should be grounded in repo context.

Ask Oracle for strict JSON:

snippet-2
Use $oracle-packx to inspect the relevant code and produce a strict JSON web-choices job.
Generate 6-10 concrete options for solving the billing webhook double-processing issue.
Each option should include id, title, description, tags, risk, suggestedProofCommands, and expectedEvidence.
Do not implement yet. After the job is served through $web-choices, wait for my saved choice and feedback.

Oracle generation is blocking. The agent should wait for Oracle to finish, read the local Oracle output, validate the JSON shape, then push the job into Web Choices.

If the selected option fails later, ask Oracle again with a Prior-State Ledger that includes the selected option, the failure, logs, proof commands, and what has already been tried.

Command Shape

Start the skill-local server from any project:

bash
export WEB_CHOICES_SKILL_DIR="$HOME/.agents/skills/web-choices"
export HITL_OUT_DIR="$PWD/.hitl-choice"
export HITL_HOST="127.0.0.1"
export HITL_PORT="8877"

bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" server \
  --out-dir "$HITL_OUT_DIR" \
  --host "$HITL_HOST" \
  --port "$HITL_PORT" \
  --tmux

The server writes or reuses a token:

bash
TOKEN="$(cat "$HITL_OUT_DIR/.token")"

Confirm the local server is alive:

bash
bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" status \
  --out-dir "$HITL_OUT_DIR" \
  --url "http://127.0.0.1:$HITL_PORT" \
  --token-file "$HITL_OUT_DIR/.token"

Push a generated job:

bash
bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" push ./web-choices-job.json \
  --url "http://127.0.0.1:$HITL_PORT" \
  --token-file "$HITL_OUT_DIR/.token"

Use --replace only after checking the active job and confirming replacement is intentional.

Phone Workflow

Start Tailscale Funnel for the local port:

bash
tailscale funnel --bg --yes "$HITL_PORT"
tailscale funnel status

Use the Funnel hostname reported by tailscale funnel status:

bash
PUBLIC_BASE="https://<your-tailnet-host>.ts.net"
curl -fsS "$PUBLIC_BASE/api/jobs/current?token=$TOKEN" \
  | jq '{jobId:.jobId, optionCount:(.options | length)}'

Share the phone URL only after the public API returns the expected job and option count:

snippet-9
https://<your-tailnet-host>.ts.net/?token=<HITL_TOKEN>

Keep the tmux server running while the phone page is open. Tailscale Funnel makes the local UI reachable, but the development machine and Tailscale connection still need to stay online.

Wait And Resume

Wait locally:

bash
bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" wait \
  --job "<jobId>" \
  --out-dir "$HITL_OUT_DIR"

After submission, inspect and summarize:

Then continue from the saved JSON file.

Durable State Files

FilePurpose
$HITL_OUT_DIR/current-job.jsonactive choice job
$HITL_OUT_DIR/drafts/server-side in-progress feedback
$HITL_OUT_DIR/submissions.jsonlappend-only submission log
$HITL_OUT_DIR/submissions/<submissionId>.jsonexact submitted decision packet

Ask The Agent This

snippet-11
Use $oracle-packx and $web-choices.
Pack the relevant auth/session code and generate a strict JSON choice job with 8 options for the refresh-token rotation strategy.
Serve the choices with the bundled Web Choices skill, expose it through Tailscale Funnel, give me the phone URL, and wait for my saved submission.
After I submit, read the saved submission JSON and continue only with the selected direction and feedback.
snippet-12
Use $web-choices for this CLI UX decision.
Generate 6 command naming options, serve them through the phone-friendly choice UI, and wait for my saved choice before editing code.
snippet-13
Use $web-choices as a review checkpoint.
Turn the three migration plans into selectable options with risk and proof commands.
Give me a Tailscale URL, wait for feedback, then resume from the saved submission JSON.

What To Confirm / How To Know It Worked

If It Goes Wrong

If the tunnel fails, keep the same server, job, and token when possible. Restart Funnel, check tailscale funnel status, then retry the public API check.

If the server dies, inspect $HITL_OUT_DIR first. Restart with the same out dir and verify current-job.json, drafts, and submissions are still present.

If the phone says submitted but the wait command has not returned, inspect submissions.jsonl, submissions/, server logs, and:

bash
curl -fsS "http://127.0.0.1:$HITL_PORT/api/jobs/<jobId>/submissions/status?token=$TOKEN"

If the choices are sensitive, do not expose them through Funnel without an explicit approval. The token is a gate, not a full authentication system.

References And Resources