hoatv2211/GameStudio-CodexKIT / skills/studio-goal-progress
studio-goal-progress
VerifiedUse when a KIT-managed Codex or Hermes Goal needs evidence-backed percentage, ETA range, live read-only progress views, or portable append-only progress recovery.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.3 KB |
| agents/openai.yaml | config | 313 B |
| assets/app.js | script | 13.4 KB |
| assets/index.html | other | 6.4 KB |
| assets/styles.css | other | 9.0 KB |
| references/commands.md | markdown | 5.5 KB |
| schemas/studio-goal-event.schema.json | config | 25.5 KB |
| schemas/studio-goal-manifest.schema.json | config | 5.2 KB |
| schemas/studio-goal-state.schema.json | config | 13.2 KB |
| scripts/goal_progress.py | script | 22.1 KB |
| scripts/goal_progress_app_server.py | script | 5.6 KB |
| scripts/goal_progress_core.py | script | 52.0 KB |
| scripts/goal_progress_server.py | script | 110.9 KB |
| scripts/goal_progress_store.py | script | 26.1 KB |
SKILL.md
View on GitHub---
name: studio-goal-progress
description: Use when a KIT-managed Codex or Hermes Goal needs evidence-backed percentage, ETA range, live read-only progress views, or portable append-only progress recovery.
version: 0.1.0
author: GameStudio-CodexKIT
license: MIT
compatibility:
engines: [engine-agnostic]
versions: [any]
platforms: [windows, linux, macos]
metadata:
studio:
type: interactive
lifecycle_stage: operate
risk_level: low
packs: [studio-core]
side_effects: files
artifact: progress.jsonl
required_evidence: [goal-manifest, progress-events, reduced-state]
owner: HoaTV Studio
reviewer: null
maturity: experimental
last_reviewed: 2026-09-04
provenance:
derived_from: none
patterns_from: [Codex App Server documented lifecycle events, AGENTS.md evidence labels]
copied_text: none
---
# Studio Goal Progress
## Overview
Operate an explicitly opted-in KIT Goal from one portable append-only event stream. Percentage is verified weighted work; ETA is a separate range and confidence forecast. Compact and full GUI views read the same reduced state and never control the Goal.
## When to use
Use to preflight or initialize an explicit KIT-managed Goal, append a meaningful workflow event, recover current state from `progress.jsonl`, report verified percentage and ETA, or handle an operator request to `Open Progress`.
## When NOT to use
Do not use for arbitrary Codex tasks, packet planning, speculative progress, durable session transfer, or automatic dashboard opening. Route packet construction to `feature-to-work-packets` and durable transfer to `studio-handoff`.
## Required inputs and context discovery
Require an explicit Goal opt-in, one goal ID, repository root and snapshot, plan version, scope and do-not-touch paths, ordered packets, final verification requirements, and `max_active_timed_packets: 1`. Runtime bindings are optional; declared bindings must identify a Codex thread or Hermes session. Every packet requires `workflow_id`, owner, positive integer `progress_weight`, dependencies, completion criteria, evidence kinds, and may omit or null its low/high duration estimate.
## Safety and risk level
The helpers write only beneath the selected ignored goal root. Run `preflight` before `init`. Because `init` may launch a detached private writer runtime, obtain explicit service-start approval immediately before invoking it; Goal opt-in and a passing preflight are not approval. One writer appends validated events; workflows submit candidates instead of editing JSONL. GUI, context, and handoff consumers are read-only. Never expose raw logs, unrestricted paths, credentials, runtime keys, reusable session tokens, or mutation controls. Browser or panel opening separately requires an explicit `Open Progress` request.
## Workflow
1. Confirm explicit KIT Goal participation and run report-only `preflight` against the manifest and bounded goal root before initialization.
Completion criterion: schema, root, snapshot, packet ownership, positive weights, dependencies, required evidence, any declared runtime bindings, and timing policy are valid; otherwise initialization is `BLOCKED`.
2. Immediately before `init`, obtain explicit approval to start or reuse the private writer service, then initialize one goal-local writer from the accepted preflight inputs. Do not open a GUI.
Completion criterion: without immediate service-control approval initialization remains `BLOCKED`; with approval, `goal.started` is accepted into `progress.jsonl`, reduced state is reproducible, and the Goal remains separate from other local sessions.
3. Submit candidate events only at meaningful boundaries: Goal start, packet transition, evidence observation, plan revision, context refresh, terminal state, or an explicitly bounded heartbeat for a long operation.
Completion criterion: ordinary commentary, elapsed wall time, raw tool output, and optional runtime observations never become completion evidence.
4. Reduce the full append-only stream and calculate percentage from verified weight divided by active planned weight. Recalculate on approved plan revision without changing retained verified weight.
Completion criterion: packet verification cites accepted matching `Verified` evidence, incomplete Goals display below 100%, and replay restores current state.
5. Calculate ETA as a low/high seconds range with basis, calibration, confidence, and warnings. Missing estimates return `Calculating...`; `waiting_input`, `blocked`, or stale state pauses ETA; unsupported parallel timing is `BLOCKED`.
Completion criterion: ETA remains forecast rather than evidence and no inactive time or commentary implies completion.
6. On `Open Progress`, accept an explicit goal root, or first resolve one unique nonterminal Goal from the caller's declared manifest runtime binding before repository-level ambiguity fallback. Reuse a healthy authenticated dashboard runtime without new service approval. Starting a stopped or missing runtime requires immediate explicit service-control approval. Python returns one one-time localhost URL and separate server, panel, and browser statuses; it never invokes UI or browser APIs. After URL generation, the host agent uses its panel tool when available, otherwise instructs the operator to open the URL manually.
Completion criterion: one top-level one-time URL, host-panel instruction, manual-browser instruction, and independent integration statuses are returned without reusable credentials; ambiguous selection, missing service approval, failed server start, unavailable panel/browser, or unavailable App Server is labeled `BLOCKED` while portable progress remains usable.
7. At terminal completion, require every active packet and every final verification requirement to have accepted matching evidence, then return a final evidence card.
Completion criterion: the card records goal ID, plan version, verified percentage, ETA status, event and reduced-state artifacts, commands and exit codes, integration limitations, evidence labels, final verdict, and next action.
## Evidence and output contract
Treat `progress.jsonl` as sole canonical recovery authority; `goal.json`, `state.json`, context files, runtime descriptors, and GUI output are derived. Report Goal state, verified and planned weights, exact percentage, display percentage, ETA status/range/confidence, current packet, latest evidence, next action, staleness, warnings, integration status, and artifact paths. Missing authority or evidence is `BLOCKED`, never simulated `PASS`.
## Handoff contract
Record goal root, manifest hash, plan version, last accepted sequence, current packet, verified weights, ETA status, relevant commands, integration blockers, and next action. Use `studio-handoff` for durable cross-session transfer.
## Pitfalls and anti-rationalization
- “Work feels almost done” is not verified weight.
- “It has run for an hour” is not percentage or evidence.
- Missing packet weights do not justify equal-weight defaults.
- App Server failure does not invalidate the portable KIT stream, but enrichment remains `BLOCKED`.
- Goal opt-in and preflight do not authorize `init`; service approval is required immediately before that command.
- `Open Progress` never invokes a panel or browser from Python. It reuses a healthy runtime, and starts a missing runtime only with immediate explicit service-control approval; neither path authorizes Goal mutation or reusable token disclosure.
## Verification checklist
- [ ] Explicit Goal opt-in and preflight preceded initialization, with separate service approval immediately before `init`.
- [ ] Packets have positive weights and matching evidence requirements.
- [ ] Only meaningful-boundary events were submitted through one writer.
- [ ] Percentage comes only from verified active weight.
- [ ] ETA is a labeled range or honest Calculating, Paused, or BLOCKED state.
- [ ] GUI opening was manual and views remain read-only.
- [ ] Final evidence card separates Verified, Snapshot, Unverified, and BLOCKED facts.
## References and scripts
Load [commands and interpretation](references/commands.md) before running helpers. The standalone skill bundles `scripts/goal_progress.py`, `scripts/goal_progress_core.py`, `scripts/goal_progress_store.py`, `scripts/goal_progress_server.py`, and `scripts/goal_progress_app_server.py` together with the Goal manifest, event, state, and context projection schemas.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |