agent-skills/skills/sitrep-panel/SKILL.md

name, description, license

name	description	license
sitrep-panel	Use when a human wants live browser visibility into a long-running or delegated agent task — asks for a sitrep panel, live status page, progress report, running narrative, screenshots, or a watchable local dashboard. Covers scaffolding, serving, resuming, updating, archiving, and stopping a private localhost report across unrelated project types and agent CLIs.	MIT

Sitrep Panel

Keep a live local HTML report updated while work proceeds: a four-column status board, a standing explanation of what is happening now, screenshots, and a newest-first log. The browser polls a tiny timestamp file and reloads when it changes. Everything stays on the machine; there is no account, publish step, dependency install, build process, or external request.

Provenance: adapted from dbl8005/sitrep-panel, released under the MIT license. The bundled server and HTML template are copied unmodified from upstream. The workflow below preserves upstream's scaffold, serve, resume, archive, and update protocol while adapting invocation and background-process guidance for this fleet's mixed agents and CLI delegates.

This is scratch visibility, not durable project documentation. Keep one active report at .sitrep-panel/report/ per project so its URL remains stable through a long session.

Commands

Interpret sitrep-panel [start | open | stop | archive]; default to start.

• start: scaffold if necessary, start or reuse the server, and print the URL.
• open: print the active report's URL, starting its server if needed; do not alter report content.
• archive: move the active report to .sitrep-panel/archive/<UTC-timestamp>-<short-slug>/, then scaffold a fresh report. Use this only for genuinely unrelated work.
• stop: stop the server process that was launched for this report. Preserve all report content.

Do not assume slash-command support. These are workflow actions a session agent or CLI delegate can carry out with its own filesystem and background execution tools.

Scaffold or resume

Resolve <skill-dir> to the directory containing this SKILL.md, and <project> to the project root. On start, if <project>/.sitrep-panel/report/ does not exist:

1. Create <project>/.sitrep-panel/report/screenshots/.

2. Copy <skill-dir>/support/assets/template.html to <project>/.sitrep-panel/report/index.html.

3. Replace {{TITLE}} with a short task name and {{SUBTITLE}} with one line saying what the report tracks and when it started. HTML-escape inserted text.

4. Write <project>/.sitrep-panel/report/meta.json with a current UTC time:

   {"updated_at": "2026-08-24T12:34:56Z"}
   

5. In a Git repository, check whether .sitrep-panel/ is already ignored (git check-ignore -q .sitrep-panel/ is suitable once it exists). If not, append .sitrep-panel/ to the project's .gitignore and tell the user. Skip this only when the user explicitly wants the report committed.

If the report already exists, resume it without overwriting content. Archive first only when the new work is unrelated. Treat any existing .gitignore changes as project changes: preserve them and append only the missing rule.

Serve on localhost

First read .sitrep-panel/report/.server.json if present. If it contains a port and a GET to http://127.0.0.1:<port>/meta.json succeeds, reuse that server and do not start a duplicate.

Otherwise launch the bundled blocking server with the current agent's detached/background mechanism:

python3 <skill-dir>/support/scripts/serve.py <project>/.sitrep-panel/report

Capture its single startup line:

SERVING http://localhost:<port>/

It binds only to 127.0.0.1, tries port 8934, and lets the OS select a free port if 8934 is occupied. Immediately record the selected port and UTC start time in .sitrep-panel/report/.server.json:

{"port": 8934, "started_at": "2026-08-24T12:34:56Z"}

Also retain the background process/session handle when the execution surface provides one; use that exact handle for stop. Never stop a server with a broad pkill python, killall, or an unverified pattern. After stopping, verify the recorded endpoint no longer answers and remove only the stale .server.json file. A stale file is harmless: start and open must probe the endpoint before trusting it.

After every start or open, show http://localhost:<port>/ prominently. The URL is the result, not an implementation detail.

Update throughout the task

A panel written once at startup is useless. Update it after each meaningful write, decision, state transition, screenshot, or verification result. Skip noise such as routine file reads.

For each update, edit index.html and then perform these operations:

1. Replace the contents of #current-work-body with plain-language prose explaining what is happening now and why. This block describes the present, not history.
2. Prepend one entry directly inside #entries, before older entries. Use the exact .entry, .entry-rail, .entry-dot, .entry-time, .entry-title, and .entry-body structure in the template comment; the timeline styling depends on it. State what happened, what was decided and why, and what was verified.
3. Add or move task cards among #board-todo, #board-progress, #board-done, and #board-blocked. A card is <div class="board-card">Step name</div>. Move the element between containers; do not invent status classes.
4. Save useful screenshots under report/screenshots/ and reference them with relative paths such as <img src="screenshots/settings-after.png" alt="Settings after update">. Put them in #shots-body, a relevant log entry, or both. Use meaningful filenames and alt text.
5. Rewrite meta.json with a new ISO-8601 UTC updated_at value last. The page polls it every two seconds; touching it before index.html is fully written can trigger a stale or partial reload.

Preserve valid HTML and HTML-escape task text, tracker titles, paths, and log content. Do not replace the whole report when a targeted block update will do; the additive protocol leaves useful partial history if an agent stops.

At completion, move the final card to Done, add the verification result to the log, and replace the current-work block with a concise completion summary or an honest blocked state. Touch meta.json last as usual.

Use real tracker data or a manual board

If a working issue-tracker connection is already available and real tickets map to this task, use their real key, title, link, and status. Refresh that mapping as work advances. Map tracker states conservatively into To do, In progress, Done, or Blocked.

Otherwise maintain a plain checklist of actual work. Never fabricate tickets to make the board look populated. If several trackers are plausible and the choice changes what the board represents, ask which one to use.

When to run this

• A user explicitly asks for a sitrep panel, live status page, progress dashboard, screenshots-as-you-go, or a browser view of agent work.
• A long-running delegated or background task needs passive human visibility without repeated transcript/status queries.
• A multi-stage operational or development session benefits from a stable, private localhost view shared across session agents and CLI delegates.

What NOT to do

• Do not start this automatically for every small task; maintaining it has a real update cost and is valuable mainly for long or explicitly watched work.
• Do not expose the server beyond loopback, tunnel it, upload the report, or add external assets without explicit authorization. This skill is local and private by design.
• Do not present it as a durable audit log. Archive preserves a snapshot, but .sitrep-panel/ is normally ignored scratch state.
• Do not fabricate status, tracker tickets, screenshots, verification, or narrative. The panel must reflect work that actually happened.
• Do not forget the final meta.json write after a content update, and do not bury the localhost URL after start or open.