pipeline-progress

Manage durable multi-step Story-Film pipeline progress, Pi todo rendering, checkpoints, pause/resume, blockers, selective retry, and session handoff without relying on chat history.

SKILL.md

GitHub

Pipeline Progress

Use this skill whenever a Story-Film playbook contains multiple ordered steps.

Authority

00_project/pipeline_progress.json is the authoritative execution-progress ledger.

The Pi todo widget is only a renderer of that ledger. It must never invent progress, estimate counts, or mark work complete on its own.

Creative truth remains in canon, state, approved artifacts, dependency records, and media registries. Progress does not replace those systems.

Start or resume

  1. If pipeline_progress.json is inactive or the previous pipeline is complete, initialize the selected playbook:
python scripts/pipeline_progress.py init <project-root> --playbook <playbook-name>
  1. If an active, paused, or blocked ledger already exists for the requested work, read it and resume the recorded current target instead of rebuilding the plan from chat history.
  2. Read 00_project/HANDOFF.md after a restart or compaction, but treat the JSON ledger as authoritative if the two disagree.

Checkpoint rule

Do not work ahead. The current leaf in pipeline_progress.json is a hard execution boundary. Do not start a later Story-Film specialist, write its artifact, or mark a generic Pi Todo ahead until the current leaf is complete.

After each actionable leaf step/substep:

  1. perform the work
  2. validate the relevant artifact
  3. checkpoint only after validation succeeds
  4. include changed files when practical
  5. let the checkpoint advance to the next pending leaf
  6. reread the progress ledger before starting that new target

If Pi also has a generic Todo tool, use it only as a small mirror. Keep at most three Story-Film items there: the current target, the immediate next target, and the requested endpoint. Update that mirror immediately after each Story-Film checkpoint. Never duplicate the complete Story-Film playbook into Pi's generic Todo. When the host exposes a compatible generic Todo initialization tool, the Story-Film extension blocks a new mirrored list with more than three items.

Example:

python scripts/pipeline_progress.py checkpoint <project-root> \
  --status completed \
  --last-action "Approved the scene outline" \
  --file 01_story/scene_outline.md

A blocking validation failure must not advance:

python scripts/pipeline_progress.py checkpoint <project-root> \
  --status blocked \
  --blocker "SCN-014 references an unknown location ID" \
  --next "Repair SCN-014 and rerun project validation"

After correction:

python scripts/pipeline_progress.py resume <project-root>

Then validate and checkpoint the same target.

Conditional steps

Use skipped only when a conditional playbook step genuinely does not apply. A skip requires a reason:

python scripts/pipeline_progress.py checkpoint <project-root> \
  --status skipped \
  --note "No social campaign was requested"

Never skip work merely because it is difficult or a runtime is unavailable. Runtime absence is a blocker when the requested endpoint requires that runtime.

Pause and resume

Pause only when the user intentionally pauses work or a human approval boundary requires it:

python scripts/pipeline_progress.py pause <project-root> --note "Waiting for user selection of TAKE-004 or TAKE-006"

Resume from the same target:

python scripts/pipeline_progress.py resume <project-root>

Selective retry

Use reset for a bounded execution retry:

python scripts/pipeline_progress.py reset <project-root> PST-006.STEP-SCENE-TO-SHOTS-03 \
  --note "Retry only the failed shot-list step"

Resetting progress does not restore creative files or infer dependency impact. If an approved artifact changes, run project-impact separately and invalidate only its actual downstream dependency slice.

Pi UI

When the optional Pi extension is installed, it displays stage, step, and substep state above the editor and follows the current item automatically.

The Story-Film viewport starts in compact mode with three visible pipeline rows. Expanded mode shows ten rows. Both modes can scroll and follow the real current target.

Controls:

  • /story-todo status
  • /story-todo toggle|expand|collapse
  • /story-todo up|down
  • /story-todo page-up|page-down
  • /story-todo current
  • /story-todo help|keys
  • Ctrl+Alt+End toggles compact/expanded Story-Film Todo
  • Ctrl+Alt+Up/Down
  • Ctrl+Alt+PageUp/PageDown
  • Ctrl+Alt+Home

Markers:

  • ✓ completed
  • ▶ current
  • ! blocked
  • ○ pending
  • - skipped

Done

Pipeline execution is done when every applicable leaf is completed or explicitly skipped, no required blocker remains, and the requested endpoint has passed its normal Story-Film validation gates.

Resource-handoff status

00_project/resource_handoff.json is a separate deterministic runtime-status channel for exclusive local-LLM/ComfyUI handoffs. The Pi extension may render it beside the Todo and emit phase-change notifications without calling an LLM. It never replaces pipeline_progress.json as the pipeline cursor, and the resource runner must not checkpoint creative work on its own.