agent-feedback-artifact

What this skill does

# Agent Feedback Artifact

> **Self-validate after edits.** Any change to this skill's files (`SKILL.md`, `scripts/`, `references/`, `templates/`, `assets/`) must be followed by `./scripts/validate.sh` from the skill directory. Hard findings require optimizing the skill before closeout.

This skill turns an HTML artifact or local app page into an interaction space between the operator and an agent. It injects a managed annotation widget, serves the page through a local feedback server, queues marker-scoped user comments as agent work items, and lets agents fetch only the context tier they need.

## Operating Contract

| Field | Decision |
|---|---|
| Primary archetype | Server / API workflow |
| Secondary archetypes | Browser / UI workflow, deterministic script workflow, artifact modifier, agent orchestration |
| Operator trigger | The user wants in-page feedback, annotation, or marker chat inside an HTML artifact/app instead of screenshot/chat-window feedback. |
| Output | The target page is served with the feedback capability; marker comments are queued, processed, and replied to inside marker-local chat. |
| Success evidence | Browser-visible marker flow works; server queue/status confirms processing; closeout reports no unexpected queued/processing work. |
| Deterministic surface | Add/remove/preflight/closeout/server/next/details/mark/routing/dispatch scripts and validation checks. |
| Judgment surface | Deciding whether a marker needs direct main-agent handling, a cheap marker worker, or a deeper context worker. |
| Context loading | Default packet first; marker details on demand; full artifact/app/source context only when the marker requires it. |

## When To Use

Use this skill when the user asks for:

- annotation or commenting directly inside an HTML artifact or app
- Browser-style targeted feedback without screenshot copying
- per-marker chat that queues feedback while the agent works
- deterministic add/remove/toggle of the capability
- operator comments to trigger agent processing
- progressive disclosure so agents do not ingest full UI/app context by default
- preflight and closeout evidence for safe handoff

Do not use this for a plain static HTML artifact that does not need in-page feedback, server APIs, marker state, or agent processing.

## Workflow

### Preflight

1. Run:

```bash
node scripts/agent-feedback-preflight.mjs <artifact.html> --port <port>
```

2. Confirm:

- target exists and contains `</body>`
- widget install state is known
- server script exists
- selected port is available or consciously reused
- local queue is readable/writable when present
- webhook config is reported when comment-triggered processing is required

3. If the target is an app build, identify whether this is a prototype static injection or a durable app integration. For React/Next/Vite prototypes, static injection into built HTML is acceptable. Durable product integrations should wrap the same client behavior as an app component while keeping the server/API contract stable.

### Add And Serve

```bash
node scripts/add-agent-feedback.mjs <artifact.html>
AGENT_FEEDBACK_WEBHOOK_URL=http://127.0.0.1:<worker-port>/hook \
  node scripts/artifact-feedback-server.mjs <serve-root> <port>
```

The managed block is bounded by `AGENT_FEEDBACK_WIDGET_START` and `AGENT_FEEDBACK_WIDGET_END`. Do not hand-edit the injected block. Use `remove-agent-feedback.mjs` when removal is requested.

The target must be served by `artifact-feedback-server.mjs`; `file://` cannot submit feedback.

### Browser Acceptance

Browser verification is mandatory before calling the capability working. Use Chrome when the user asks for Chrome-backed testing.

Minimum browser checks:

- selecting without comment creates no marker
- first comment creates one marker
- multiple messages stay in one marker thread
- abandoned composer does not leave an empty marker
- UI tab shows selected element context
- queued message delete removes the message and removes the marker when empty
- processed message shows a done indicator and marker-local agent reply
- marker trash deletes/releases that marker thread
- global trash clears all markers
- reload preserves processed marker status and replies

Comment-triggered processing acceptance:

- submit at least one marker comment from the page
- verify the server emits webhook or otherwise creates a queued work item
- verify processing moves through `queued` -> `processing` -> `done`/`blocked`/`canceled`
- verify the agent reply appears inside that marker's chat
- do not manually poll and fix as a substitute for trigger verification

Multi-marker acceptance:

- submit at least three marker comments rapidly without waiting for the first to finish
- verify three distinct marker ids
- verify each marker receives its own reply
- verify concurrent processing does not merge markers or overwrite same-artifact edits

## Marker Work Protocol

Use the progressive-disclosure scripts instead of loading the whole artifact by default:

```bash
node scripts/agent-feedback-next.mjs
node scripts/agent-feedback-details.mjs <work-id>
node scripts/agent-feedback-mark.mjs <work-id> processing
node scripts/agent-feedback-mark.mjs <work-id> done "Agent-visible reply"
```

Default work packets should include only:

- work id
- marker id
- artifact path/title/version
- latest user message
- target selector
- visible text
- status
- compact thread summary when present

Fetch full details only when the marker requires geometry, viewport, selected text, UI snapshot, raw payload, source, data, or broader artifact context.

## Processing Model

- The main agent owns final edits, conflict resolution, and browser verification.
- Marker workers diagnose, propose, and reply through marker-scoped work packets.
- Do not keep a live subagent per marker by default. Persist compact `threadSummary` and spawn or resume work only when new marker feedback arrives.
- Same-marker follow-up should reuse the marker summary and use a cheaper worker when possible.
- Distinct markers may be diagnosed in parallel, but writes to the same artifact/app must be serialized or merged through the main agent.
- Deleting a marker releases its marker thread and cancels queued work where possible.

Routing expectations:

- simple visual/typography/copy edits can route to `no_worker_main_agent_direct`
- data/dependency/root-cause comments route to `deep_marker_worker` with narrow context first
- same-marker follow-up with enough summary can route to a cheap summary worker
- selectors are evidence, not intent; do not classify data work merely because a selector contains `data-*`

## Script Inventory

| Script | Owns |
|---|---|
| `scripts/add-agent-feedback.mjs` | Deterministic install into target HTML. |
| `scripts/remove-agent-feedback.mjs` | Deterministic removal of only the managed block/meta. |
| `scripts/artifact-feedback-server.mjs` | Static serving, feedback APIs, queue storage, webhook dispatch. |
| `scripts/agent-feedback-preflight.mjs` | Readiness checks and exact next commands. |
| `scripts/agent-feedback-closeout.mjs` | Read-only state/evidence report by default. |
| `scripts/agent-feedback-next.mjs` | Next queued marker packet. |
| `scripts/agent-feedback-details.mjs` | Full marker payload on demand. |
| `scripts/agent-feedback-mark.mjs` | Status updates and marker-visible replies. |
| `scripts/agent-feedback-routing.mjs` | Context-efficient route selection. |
| `scripts/agent-feedback-dispatch.mjs` | Direct/worker processing decision. |
| `scripts/test-agent-feedback-webhook-receiver.mjs` | Webhook delivery smoke receiver. |
| `scripts/test-agent-feedback-auto-runtime.mjs` | Event-triggered processing harness for acceptance testing. |

## Design Guidance

The widget should feel like a capability layer, not page content. Use a permanent small top-right launcher icon, similar in weight to a light/dark mode toggle. When toggled on, reveal small standalone annotate/count/trash/menu icons next to it with tran