agent-progress-visualizer

Agent Progress Visualizer

This skill creates and maintains a user-facing progress cockpit for UI/UX Agent Skill System projects. It translates canonical task-plan state into plain-language HTML for non-technical users.

It does not execute project tasks and does not own canonical status. Before planning, project-request.json and workflow-log.jsonl are only bootstrap sources. After planning, TASK-PLAN.md becomes the source of truth.

Operating Modes

bootstrap: create the first visible progress screen immediately after the system accepts a substantial user request, before TASK-PLAN.md exists.
init: create or replace the first task-plan-derived progress-state and progress screen after TASK-PLAN.md exists.
update: regenerate state and HTML after task-plan, report, artifact, feedback, or wiki changes.
review: inspect an existing progress screen for source-of-truth drift, fake status, privacy leaks, or confusing copy.
feedback-gate: expose user decisions and comments, then hand them to design-feedback-collector.
developer-view: reveal technical task ids, skill routes, dependencies, and artifact paths without changing customer copy.

Required Workflow

Read references/data-source-contract.md.
Read references/decision-framework.md.
Read references/safety-boundaries.md.
In bootstrap mode, do not wait for TASK-PLAN.md. Immediately create project-request.json, append workflow-log.jsonl, build a minimal progress-state.json, render agent-progress-screen.html, and open it in the browser. In the local project implementation, use bootstrap_progress_screen.py --open-browser.
After the bootstrap screen exists, route to task-plan-v2-orchestrator to create canonical TASK-PLAN.md.
In init or update mode, locate canonical TASK-PLAN.md. If no canonical task plan exists and bootstrap has not run, run bootstrap first, then route to task-plan-v2-orchestrator.
Build or update progress-state.json from canonical task-plan fields, reports, artifacts, feedback state, and sanitized wiki decisions.
If a declared journey exists, include journey_alignment from the journey registry and route skip/rework/block decisions through workflow-compliance-supervisor.
Render agent-progress-screen.html as a derived view. Do not edit HTML as the only state change.
In task-plan-derived init mode, open the rendered HTML in the browser immediately after creation. In the local project implementation, pass --open-browser to render_progress_screen.py. In update mode, open it only when the user asks or is actively reviewing.
For user choices, comments, approvals, or rejections, route durable capture to design-feedback-collector.
For large multi-session projects, route accepted decisions to project-wiki-manager after sanitization.
Validate consistency before claiming the progress screen is ready.

Source-Of-Truth Rules

In bootstrap mode, project-request.json and workflow-log.jsonl are temporary startup sources.
After planning, TASK-PLAN.md is canonical.
progress-state.json is derived machine-readable state.
agent-progress-screen.html is a derived visual layer.
If Markdown, JSON, and HTML disagree, fix Markdown or the generator first, then regenerate.
Browser-only localStorage or clipboard state is not accepted as the only record of a decision.

What To Generate

Default local artifacts:

project-request.json
TASK-PLAN.md
progress-state.json
agent-progress-screen.html
workflow-log.jsonl
feedback/progress-feedback-register.schema.json
reports/progress-validation-summary.txt

Use assets/progress-state.template.json when a project needs a starter state before a generator exists.

Human-Language Rules

Customer mode says "Collecting search queries", not serp-keyword-harvester.
Customer mode says "Waiting for your selection", not required_approvals.
Developer mode may show task ids, skill routes, dependencies, and artifact paths.
Never show secrets, tokens, recovery codes, cookies, .env values, private screenshots, or private URLs.

Validation

When using the local project implementation, prefer these checks:

python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/bootstrap_progress_screen.py" --project-root "$PROJECT_ROOT" --project-title "$PROJECT_TITLE" --user-request "$USER_REQUEST" --journey-registry "$UIUX_SKILL_SYSTEM_ROOT/data/journey-registry.json" --declared-journey new-premium-site --open-browser
python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/check_bootstrap_progress.py" --project-root "$PROJECT_ROOT"
python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/generate_progress_state.py" --task-plan "$UIUX_SKILL_SYSTEM_ROOT/TASK-PLAN.md" --out "$UIUX_SKILL_SYSTEM_ROOT/progress-state.json"
python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/render_progress_screen.py" --state "$UIUX_SKILL_SYSTEM_ROOT/progress-state.json" --out "$UIUX_SKILL_SYSTEM_ROOT/agent-progress-screen.html"
python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/check_progress_consistency.py" --task-plan "$UIUX_SKILL_SYSTEM_ROOT/TASK-PLAN.md" --state "$UIUX_SKILL_SYSTEM_ROOT/progress-state.json" --html "$UIUX_SKILL_SYSTEM_ROOT/agent-progress-screen.html"
python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/validate_workflow_compliance.py" --fixtures
python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/no_secret_scan.py" "$UIUX_SKILL_SYSTEM_ROOT"

For first creation of a user-facing project progress screen before TASK-PLAN.md, bootstrap with browser opening:

python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/bootstrap_progress_screen.py" --project-root "$PROJECT_ROOT" --project-title "$PROJECT_TITLE" --user-request "$USER_REQUEST" --open-browser

After TASK-PLAN.md exists, replace the bootstrap state with task-plan-derived state:

python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/render_progress_screen.py" --state "$PROJECT_ROOT/progress-state.json" --out "$PROJECT_ROOT/agent-progress-screen.html" --open-browser

Skill package checks:

python3 $CODEX_HOME/skills/.system/skill-creator/scripts/quick_validate.py $CODEX_HOME/skills/agent-progress-visualizer
python3 $CODEX_HOME/skills/senior-skill-architect/scripts/lint_production_skill.py $CODEX_HOME/skills/agent-progress-visualizer

Handoff Shape

Progress mode:
Bootstrap request:
Canonical task plan:
Generated state:
Generated HTML:
User gates:
Feedback artifact:
Wiki sync:
Checks run:
Skipped checks:
Next owner: