scrum-metrics

Files (1)

• SKILL.md

SKILL.md (first lines)

- For a project, use `project_metrics(project,days=30)`; default summary excludes chart series. Use include_series=true only for a requested chart or date-level analysis. days accepts 1..365, counting UTC calendar dates including today.
- Distribution/open counts reflect current state. Done transitions count re-completions; completed_tasks counts distinct tasks with a Done transition in the period. Cancelled is separate and never successful completion.
- Average lead time is creation to the latest Done in the period; cycle time is first In Progress to that Done. Report sample counts. Tasks whose first record is a migration baseline are excluded from these averages because earlier history is unknown. Observed state averages include partial visits clipped to the selected period; do not present them as full lifecycle averages.
- For one task, call task_timing(project,id). It returns cumulative calendar seconds per state, including repeat visits and current residence. history=true adds up to 20 recent visits; before=oldest and limit (max50) paginate. Metadata edits, renewals and task release do not reset state clocks. Done/Cancelled residence also accumulates and can be followed by reopening.
- partial_history=true means tracking began after the task existed. Never invent earlier durations. These metrics measure calendar flow including waiting, not CPU time, agent effort, tokens or financial cost.
- Use metrics when requested or when a specific process question needs evidence, not after every task or in idle polling. Summarize the useful bottleneck and limits briefly. The website's Metrics page offers current distribution, observed state times and daily completion/cancellation flow.

For coordination cost use coordination_metrics(project), also visible under web Metrics. It aggregates local MCP calls, failures, UTF-8 request/response bytes and server elapsed milliseconds by tool. Excludes web requests, model execution and pre-instrumentation history. Stores no arguments, tokens or response contents and is not exported. Tokens are unavailable, not estimated from bytes. Compare equivalent workloads before claiming savings; aggregate timings alone cannot establish an improvement. No routine per-task measurement calls.

work_start returns measurement_session. Include it in later project MCP calls; new sessions get a new ID, reconnects may explicitly reuse it. coordination_metrics(filter_session?,task?) filters measurements; web Metrics shows latest20 sessions and top50 tasks. Untagged calls stay unattributed, no guessed attribution; task IDs are local. start_mode is startup eligibility, not proof of all operations using that mode. Compare equivalent workloads; bytes/time are not provider tokens, and legacy totals may predate scoped instrumentation.

Optional cost: task_create/task_update accept estimated_tokens and estimated_quota_percent (null clears). task_update/work_finish accept usage_report={run_id,source,input_tokens,output_tokens}. Supply only actual client telemetry attributable to this task and agent; use stable task-specific run IDs, cumulative monotonic counts and the same source. Input includes cached tokens; never add cache again. Retries replace the same agent/run snapshot, separate agents/runs accumulate. Do not copy whole-chat counts to several tasks, guess missing usage, convert bytes into tokens, or allocate shared account quota. Reports survive Done/Cancelled; missing data stays unavailable and reported coverage may be partial. Reuse existing completion/update calls; no model estimation or quota polling solely for cost.

Cost is opt-in: task_get(include_cost=true) returns estimates and reported totals. Default task_get, next_work, work_start and snapshot omit cost. Versions identify the selected view; keep separate cached versions for cost/non-cost reads. Routine task execution should not load this skill unless a metric or existing telemetry needs handling. For repeatable isolated payload comparisons run scripts/benchmark_coordination.py; it measures response bytes, not tokens/quota, and uses disposable fixtures.

Actual CLI counters are optional on-demand data: coordination_metrics(project,include_cli_usage=true) adds cli_usage with execution count, known-run coverage and reported input/output/cache/reasoning counters. It never adds these to startup/task context. The supervisor reads existing terminal CLI log events and attaches cli_usage_report to its existing checkpoint, with a unique run ID. Duplicate callbacks count once. Batch execution counters stay shared at project level, not copied or divided into task costs. Codex coverage is the terminal completed turn, Claude the terminal run summary; missing counters/failed runs remain unknown, never zero. Cache/reasoning counters are subsets of provider totals; do not add them twice or convert them into account quota/money. No extra provider/model request is used for measurement.

Work-period filtering: `coordination_metrics(include_periods=true)` returns a bounded `periods` catalog only on request, keeping default agent responses compact (observed provider 5-hour quota windows, Wakeup-to-Wakeup campaigns including automatic continuations, and explicitly named internal MCP runs). Pass the same `filter_period` to `project_metrics` and `coordination_metrics`, or use numeric `start_at`/`end_at` Unix seconds. Flow/durations/tasks use exact interval bounds; the website separates current board counts. Native hooks reuse existing reset/control events; never request extra quota readings, models or polling solely for statistics. Old unrecorded quota windows and pre-timestamp coordination data remain unavailable/partial; never infer token/quota cost from bytes or elapsed time.

Human-requested local usage audit: `coordination_metrics(include_audit=true, include_logs=true, start_at=..., end_at=...)` returns recorded counters/top executions, verification reuse/repeated failure counts and optional bounded historical Codex-log totals. Metrics offers an on-demand audit/download button. No provider/model request. Lifetime logs overlap recorded executions; never add them or assign them to a selected interval. Coverage is explicit; no coding/testing/evidence token split or quota conversion is inferred. Do not load audits during ordinary task execution.

Flow distinguishes attempted_tasks (actual In Progress overlap), metadata_only_tasks, todo_returns_after_work and reopened_done_tasks. The worked-status chart also includes planning edits, so TODO bars are not failed agent attempts.

Audits also include `live_executions`: incremental native tool counts, elapsed time, reported token coverage and advisory thresholds. Check observed_at/active; these are last local observations, not proof the OS process still runs. Missing live tokens remain null; terminal reports and live snapshots overlap and must never be added. No extra provider/model request or idle polling is used.

For an explicitly requested before/after experiment, scripts/measure_usage.py start --project ID [--actor HUMAN --wakeup] saves a fresh Codex account reading and project audit before model launch. Existing supervisor events record run IDs and finish on quota/Stop, no eligible work or disconnect; no model/idle metric polling is added. get/finish read or close the local measurement. Metrics audit includes measurement summary; full reports stay in .scrum/local/measurements. Quota change is shared account percentage points, never project attribution; resets or stale readings leave it unknown. Project token coverage is independent and reported completed runs only.


Coordination metrics include `channels` and `channel_tools`: `mcp`, `cli`, `supervisor` (native, not inference), and older unattributed history. Apply the same interval/session/task filters to each comparison. CLI is counted once without a nested MCP call. JSON bytes are not shell context, tokens or quota. Old MCP history may include native automation before channel attribution; do not call it exclusively agent usage.

From martiin3d/scrumstudio, MIT.

More from martiin3d/scrumstudio