Progress

Published from docs/extensions/progress.md at 835522e. Edit the source in the repository, not this page.

Purpose: show a live report for one Spec Kit feature: lanes, tasks, blockers, decisions and what the orchestrating agent is using. The report is a deterministic projection of tasks.md, the optional Workflow ledger and the host's native hook payloads. No agent is spent keeping it current.

Lifecycle phase	After tasks through implement; native hooks keep it fresh
Hooks	Two optional lifecycle hooks and five native host events (hooks)
Commands	init, refresh, status, theme, export (reference) and a CLI with 16 verbs (full reference)
Requires	Spec Kit 1.1.1 or later; Python 3.11 or later. Workflow (1.17.0 or later) and Illustrate are optional
Standalone	Yes
License	MIT

Setup

specify extension add progress

Add the Sanduq catalog first if you have not (install by host). With Workflow, use install.py --with progress --apply instead.

Progress needs Spec Kit 1.1.1 or later. On an older Spec Kit the Workflow installer refuses it before changing anything, with OPTIONAL_PACKAGE_SPECKIT_INCOMPATIBLE naming both versions: upgrade Spec Kit, or install without --with progress.

/speckit-progress-init Create the progress report for specs/412-refund-approval.

Open specs/412-refund-approval/progress/.view/index.html in a browser. It polls every 3 seconds and needs no server.

Example

/speckit-progress-status Show the one-line progress status.
/speckit-progress-theme Use the cobalt theme for the progress report.
/speckit-progress-export Export the progress report as Markdown.

Record a lane when you assign work:

python .specify/extensions/progress/scripts/progress.py lane L1 --tasks T001-T003 --owner worker-a

progress: L1 open 3 tasks

The agent records only what no other source holds: a lane assignment, a blocker, a plain Spec Kit decision or a note. The skill at extensions/progress/skills/progress/SKILL.ext.md lists the verbs. Task state comes from tasks.md; model, effort and context come from host hooks and are shown as unknown when a host does not send them.

With Workflow

Progress is optional for Workflow. Install it with install.py --with progress. Workflow then reports through Progress and no longer asks an agent to keep a report current. With Workflow installed, Progress needs 1.17.0 or later: an older Workflow asks for the removed v2 document and gets PROGRESS_REMOVED with the upgrade command, and progress status names the upgrade while it is installed. If you leave Progress out, Workflow's own report runs as before. progress_bridge.py mode prints the mode in use (projection, refresh or legacy); the modes and the old-call mapping are in the operations guide. Details:

• Workflow's legacy progress.py no longer forwards to Progress. With Progress installed and enabled, a legacy call writes nothing, exits 2 with error PROGRESS_INSTALLED: ... and names the Progress command to use. Switch old prompts and scripts to .specify/extensions/progress/scripts/progress.py.
• Workflow's status carries Progress's one text status line as progress_status.
• Workflow's lean run status reads progress runs --json (schema progress.runs.v1).
• Two optional progress: keys in .specify/workflow.yml, applied by the installer: hook_wiring: native writes hooks that run scripts/hook.py directly instead of through Spec Kit's dispatcher (about half the time per tool call), and post_tool_matcher limits the per-tool-call hook to the tools it matches, at the cost of a coarser stale banner. A new Progress install is wired natively; an existing one keeps its wiring until you set the key. The package README has the details.

Plans outside Spec Kit

Progress also tracks a plain Markdown plan: progress init --plan docs/plan.md creates .progress/plan/, and progress hooks install --host claude|codex adds the native hooks without editing other settings. Target a report with --plan NAME or --feature DIR. The steps are in the package README.

Vendored code

The scripts, report page and reference docs come from the MIT progress-report skill in sanduq-skills, pinned in vendor.lock.json. This extension's own entry point is extensions/progress/skills/progress/SKILL.ext.md; the skill's upstream SKILL.md is not vendored. The README screenshots stay in the repository and are not packaged.

Limits

• Active work time is always shown as unknown. Hosts do not report it.
• Codex fields and the stop event of a background child are unverified against a running host.
• A session must be bound to a feature before its hooks are recorded. If the report does not update, start with troubleshooting.
• Removed: the v2 status document (progress status --json --schema v2) and the classic layout (progress theme --layout classic). Either request exits 2 with PROGRESS_REMOVED. Read progress status --json (sanduq.progress.v3). A stored layout: classic shows the Timeline with one notice; progress theme --layout timeline clears it.

More

The package README has the install steps, what each report block shows, file layout, theming, token results, upgrading and troubleshooting. The command reference lists every verb, flag, output line, exit code, schema and the benchmark tools.