feat: add sitrep-panel skill
Live local HTML progress report (status board, running narrative, screenshots, newest-first log) served on localhost via a stdlib-only Python server, so a human can watch a long/delegated agent task without reading the raw transcript. Adapted from dbl8005/sitrep-panel (MIT), evaluated and drafted via Codex per this fleet's standard skill-candidate review process. Bundled server and HTML template copied unmodified from upstream. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Claude Sonnet 5
@@ -0,0 +1,176 @@
|
||||
---
|
||||
name: sitrep-panel
|
||||
description: 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.
|
||||
license: 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`](https://github.com/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:
|
||||
|
||||
```json
|
||||
{"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:
|
||||
|
||||
```bash
|
||||
python3 <skill-dir>/support/scripts/serve.py <project>/.sitrep-panel/report
|
||||
```
|
||||
|
||||
Capture its single startup line:
|
||||
|
||||
```text
|
||||
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`:
|
||||
|
||||
```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`.
|
||||
Reference in New Issue
Block a user