Documentation Index
Fetch the complete documentation index at: https://mintlify.com/modiqo/skillspec/llms.txt
Use this file to discover all available pages before exploring further.
The progress family of subcommands maintains the execution evidence ledger for a SkillSpec-guided run. All subcommands write to or read from <run-dir>/execution.jsonl, the append-only file that trace align uses to verify obligations.
The key rule: use progress checkpoint --quiet for all routine successful evidence rows. It keeps the ledger exact without making the user watch a progress-command parade and without hand-authoring event files. Use progress record only as an escape hatch for failures, blockers, debugging, or explicit proof-detail requests that cannot be expressed with typed checkpoint flags.
progress checkpoint
Appends several routine successful progress and proof events to execution.jsonl in one atomic checkpoint. This is the preferred path for recording satisfied requirements, completed phases, fulfilled routes, answered elicitations, and attached evidence.
skillspec progress checkpoint <run-dir> \
[--requirement-satisfied <phase>/<requirement>=<kind>:<ref>] \
[--phase-completed <phase>=<kind>:<ref>] \
[--route-fulfilled <id>=<kind>:<ref>] \
[--route-check-completed <id>=<kind>:<ref>] \
[--after-success-completed <id>=<kind>:<ref>] \
[--obligation-satisfied <id>=<kind>:<ref>] \
[--elicitation-answered <id>=<kind>:<ref>] \
[--evidence-attached <kind>:<ref>] \
[--checkpoint <label>] \
[--quiet] \
[--summary] \
[--json]
--requirement-satisfied, --phase-completed, --route-fulfilled, --route-check-completed, --after-success-completed, --obligation-satisfied, --elicitation-answered, and --evidence-attached flags are repeatable.
Options
| Flag | Type | Default | Description |
|---|
<run-dir> | path | (required) | Trace run directory containing execution.jsonl. |
--requirement-satisfied | PHASE/REQUIREMENT=KIND:REF | (repeatable) | Record a requirement_satisfied event. KIND is the evidence kind (e.g. command, file, trace); REF is the evidence reference. |
--phase-completed | PHASE=KIND:REF | (repeatable) | Record a phase_completed event for the named phase. |
--route-fulfilled | ID=KIND:REF | (repeatable) | Record a route_fulfilled event for the named route id. |
--route-check-completed | ID=KIND:REF | (repeatable) | Record a route_check_completed event for the named check id. |
--after-success-completed | ID=KIND:REF | (repeatable) | Record an after_success_completed event for the named closure id. |
--obligation-satisfied | ID=KIND:REF | (repeatable) | Record an obligation_satisfied event for the named obligation id. |
--elicitation-answered | ID=KIND:REF | (repeatable) | Record an elicitation_answered event for the named elicitation id. |
--evidence-attached | KIND:REF | (repeatable) | Record an evidence_attached event with no phase or requirement scope. |
--checkpoint | string | (none) | Human-readable checkpoint label written to the batch report. |
--quiet | flag | off | Suppress all output. Successful quiet checkpoints produce no stdout. Use this for normal agent execution. |
--summary | flag | off | Print a compact summary instead of full event detail. Use for debugging or proof inspection only. |
--json | flag | off | Emit the batch report as JSON. |
Example
Record a satisfied requirement, completed phase, and fulfilled route in one checkpoint:
skillspec progress checkpoint .skillspec/traces/run-1712345678-12345 \
--requirement-satisfied qa_and_proof/validate_spec=command:validate.log \
--phase-completed qa_and_proof=trace:execution.jsonl \
--route-fulfilled prove_skill_value=trace:execution.jsonl \
--checkpoint "qa phase complete" \
--quiet
progress record
Appends one structured event to <run-dir>/execution.jsonl. This is a low-level escape hatch for failures, blockers, debugging, or explicit proof-detail requests. For routine successful rows, use progress checkpoint --quiet.
skillspec progress record <run-dir> <event> [<phase>] [<requirement>] \
[--id <id>] \
[--status <status>] \
[--evidence-kind <kind>] \
[--evidence-ref <ref>] \
[--source-skill <id>] \
[--message <text>] \
[--quiet] \
[--json]
Options
| Flag | Type | Default | Description |
|---|
<run-dir> | path | (required) | Trace run directory. |
<event> | event name | (required) | Event name. See the event table below. |
[phase] | string | (none) | Phase id. Required when <event> is phase- or requirement-scoped. |
[requirement] | string | (none) | Requirement id within the phase. |
--id | string | (none) | Obligation, route, elicitation, or handoff id. |
--status | string | (none) | Outcome status, e.g. pass, fail, blocked. |
--evidence-kind | string | (none) | Kind of evidence artifact, e.g. command, file, trace. |
--evidence-ref | string | (none) | Path, id, or reference for the evidence artifact. |
--source-skill | string | (none) | Skill id that produced this event when recording cross-skill evidence. |
--message | string | (none) | Free-text annotation. |
--quiet | flag | off | Suppress output. |
--json | flag | off | Echo the written event as JSON. |
Example
Record a failed requirement with evidence:
skillspec progress record .skillspec/traces/run-1712345678-12345 \
requirement-failed qa_and_proof validate_spec \
--status fail \
--evidence-kind command \
--evidence-ref validate.log \
--message "schema validation rejected two fields"
progress stats
Appends a stats_collected event with workspace and token metrics. Use this so quiet trace align can report measured consumption, savings, and economy when running --summary.
skillspec progress stats <run-dir> \
[--workspace <name>] \
[--workspace-stats-json <path>] \
[--workspace-stats-report <path>] \
[--total-tokens <n>] \
[--context-tokens <n>] \
[--query-result-tokens <n>] \
[--response-tokens-cached <n>] \
[--saved-tokens <n>] \
[--reduction-percent <pct>] \
[--agent-visible-tokens <n>] \
[--artifact-tokens-preserved <n>] \
[--avoided-tokens <n>] \
[--metrics-source <source>] \
[--phase <id>] \
[--requirement <id>] \
[--message <text>] \
[--quiet] \
[--json]
Options
| Flag | Type | Default | Description |
|---|
<run-dir> | path | (required) | Trace run directory. |
--workspace | string | (none) | Workspace name to record alongside the stats. |
--workspace-stats-json | path | (none) | Path to a JSON workspace stats file. Parsed for token fields. |
--workspace-stats-report | path | (none) | Path to a plain-text workspace stats report. Parsed for token fields. |
--total-tokens | integer | (none) | Total API request+response tokens. |
--context-tokens | integer | (none) | One-time context-window tokens consumed during exploration. |
--query-result-tokens | integer | (none) | Tokens in extracted query results. |
--response-tokens-cached | integer | (none) | Cached response/source tokens before query reduction. |
--saved-tokens | integer | (none) | Tokens saved by query reduction or cache reuse. |
--reduction-percent | float | (none) | Percent reduction from cached/source tokens to query-result tokens. |
--agent-visible-tokens | integer | (none) | Number of tokens visible in the agent context at this checkpoint. |
--artifact-tokens-preserved | integer | (none) | Total token count of artifacts preserved outside the context window. |
--avoided-tokens | integer | (none) | Tokens avoided by using SkillSpec instead of full-context execution. Defaults to artifact_tokens_preserved - agent_visible_tokens when both are supplied. |
--metrics-source | string | (none) | Source label for the metrics, e.g. estimated, measured. |
--phase | string | (none) | Phase id to associate with this stats event. |
--requirement | string | (repeatable) | Requirement id(s) satisfied by recording this event. Requires --phase. |
--message | string | (none) | Free-text annotation. |
--quiet | flag | off | Suppress output. Use during normal agent execution. |
--json | flag | off | Echo the written event as JSON. |
Example
Record estimated direct-run token metrics quietly:
skillspec progress stats .skillspec/traces/run-1712345678-12345 \
--agent-visible-tokens 190 \
--artifact-tokens-preserved 96190 \
--avoided-tokens 96000 \
--metrics-source estimated \
--quiet
progress final-response
Appends a final_response_sent event that proves the final answer included the required sections: result, evidence, alignment status, and token savings. Run this immediately before sending the final response to the user.
skillspec progress final-response <run-dir> \
[--result] \
[--evidence] \
[--alignment] \
[--token-savings] \
[--phase <id>] \
[--requirement <id>] \
[--message <text>] \
[--quiet] \
[--json]
Options
| Flag | Type | Default | Description |
|---|
<run-dir> | path | (required) | Trace run directory. |
--result | flag | off | Final response includes a result section. |
--evidence | flag | off | Final response includes an evidence section. |
--alignment | flag | off | Final response includes an alignment status or report path. |
--token-savings | flag | off | Final response includes token math. |
--phase | string | (none) | Phase id to associate with this event. |
--requirement | string | (repeatable) | Requirement id(s) satisfied by recording this event. Requires --phase. |
--message | string | (none) | Free-text annotation. |
--quiet | flag | off | Suppress output. Use during normal agent execution. |
--json | flag | off | Echo the written event as JSON. |
Example
Record that the final response included all required sections:
skillspec progress final-response .skillspec/traces/run-1712345678-12345 \
--result \
--evidence \
--alignment \
--token-savings \
--quiet
progress show
Reads the decision trace and execution.jsonl, computes a progress.json snapshot, and reports completed, current, blocked, and remaining phases. Use this as an internal gate check; do not surface it in normal execution unless details are needed for a blocker or failure.
skillspec progress show <path> \
--run <run-dir> \
[--quiet] \
[--json]
Options
| Flag | Type | Default | Description |
|---|
<path> | path | (required) | Path to the skill.spec.yml file. |
--run | directory path | (required) | Trace run directory whose execution.jsonl to evaluate. |
--quiet | flag | off | Skip transcript output; still writes progress.json to the run directory. |
--json | flag | off | Emit the progress report as JSON. |
Example
skillspec progress show ./skill.spec.yml \
--run .skillspec/traces/run-1712345678-12345 \
--quiet
progress batch
Appends several structured progress and proof events from an existing JSONL or JSON array file to execution.jsonl. Use this only when a JSONL or JSON array proof artifact was already captured at a natural phase boundary — not to manufacture missing route, obligation, elicitation, or phase proof after alignment.
skillspec progress batch <run-dir> \
--file <jsonl-or-json-array> \
[--checkpoint <label>] \
[--quiet] \
[--summary] \
[--json]
Options
| Flag | Type | Default | Description |
|---|
<run-dir> | path | (required) | Trace run directory. |
--file | path | (required) | Path to a JSONL file or a JSON array file containing execution events. --events is a compatibility alias. |
--checkpoint | string | (none) | Human-readable label for this batch. |
--quiet | flag | off | Suppress output for successful batches. |
--summary | flag | off | Print a compact summary. Use for debugging or proof inspection only. |
--json | flag | off | Emit the batch report as JSON. |
Example
skillspec progress batch .skillspec/traces/run-1712345678-12345 \
--file .skillspec/traces/run-1712345678-12345/final-proof.jsonl \
--checkpoint "checkpointing evidence" \
--quiet
Event Reference
progress record and progress batch accept the following event values. Hyphens and underscores are both accepted (e.g. requirement-satisfied and requirement_satisfied are equivalent).
| Event | Meaning |
|---|
phase-started | A declared phase has begun. |
requirement-started | Work began for a phase requirement. |
requirement-satisfied | A phase requirement has structured proof. |
requirement-failed | A phase requirement failed. |
stats-collected | Workspace or token metrics were recorded. Prefer progress stats --quiet. |
obligation-satisfied | A route, forbid, elicitation, or other obligation has explicit proof. |
route-fulfilled | The selected route was fulfilled. |
route-check-completed | A route-local check completed. |
after-success-completed | A scheduled after-success closure completed. |
elicitation-answered | A required elicitation was answered. |
elicitation-waived | A required elicitation was explicitly waived. |
evidence-attached | Extra evidence was attached to the run. |
handoff-started | A declared handoff began. |
handoff-completed | A declared handoff completed. |
phase-completed | A declared phase completed. |
phase-blocked | A declared phase cannot continue. |
final-response-sent | The final answer was sent. Prefer progress final-response --quiet. |
The events final_response_sent, forbidden_action, forbidden_action_observed, and forbid_violated are accepted by progress batch (which uses a broader allowlist) but are not valid for progress record. Use progress batch to append a pre-captured JSONL file containing those event types, or use the dedicated progress final-response subcommand for final-response proof.
