progress-brief

Shows an agent how to plan or hand off "progress brief" so the concrete output is a design-system pass with tokens. The procedure moves through progress-brief · handoff docs, and when to restart, Hard rules, Flow. Use it when a new assignment calls for this craft.

Qu'est-ce que progress-brief ?

progress-brief is a Claude Code agent skill that shows an agent how to plan or hand off "progress brief" so the concrete output is a design-system pass with tokens. The procedure moves through progress-brief · handoff docs, and when to restart, Hard rules, Flow. Use it when a new assignment calls for this craft.

Compatible avec✓Claude Code~Codex CLI~Cursor✓OpenCode
npx skills add https://github.com/ming-coal/progress-brief/tree/HEAD

Installed? Explore more Productivité et collaboration skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

progress-brief · handoff docs, and when to restart

Goal: the next conversation understands the project in 30 seconds, for the price of ~700 tokens.

Outputs:

  1. PROGRESS.md — state doc for humans and models (≤120 lines)
  2. status.png — 1080×1350 card (optional, for reporting / social)
  3. doctor.py verdict — continue / update / restart

$SKILL_DIR below means the folder containing this SKILL.md — for example ~/.config/opencode/skills/progress-brief or ~/.claude/skills/progress-brief. If a shell is not available, run the same command with the absolute path you resolved.

Hard rules

  • Scan first, read second. Never ls the whole repo, never read a dozen source files.
  • Read at most three things: scan.py output, an existing PROGRESS.md, and 1–2 files needed to confirm one fact.
  • Don't restate code. Write "where it stands, what blocks it, what's next", never a function inventory.
  • Never append. Rewrite the sections that changed; total length must converge.
  • Use absolute dates (2026-11-20), never "today".
  • No browser is not a failure. Ship the HTML, don't retry, don't install anything.
  • A doc that fails lint is not a handoff. Run lint.py before saying it's ready.

Flow

0. Decide first (1 second)

python3 "$SKILL_DIR/scripts/doctor.py" <path>
  • exit 0 fresh → hand off as-is, don't rewrite
  • exit 1 drifted / overlong → rewrite only the progress table and next steps
  • exit 2 no doc → run the full flow
  • its "context hygiene" block also answers should I compact / restart

1. Scan (~0 tokens)

python3 "$SKILL_DIR/scripts/scan.py" <path> --days 7

50–65 lines: directory sizes, 12 most recent files, existing progress docs, TODO counts, git branch and last 5 commits, package scripts, plus a token ledger. --json for metrics only, --no-ledger to keep stats clean.

2. Read what exists

Existing PROGRESS.md → read only that, judge which lines are stale. No doc → don't read source. Open one file only when a row of the status table can't be inferred from the scan.

3. Write PROGRESS.md

At the project root (or per-episode directory for series). Fixed order, always:

# <project or episode name>

> Status: **<one line>** · updated <YYYY-MM-DD>

## One-liner
What this is and who it's for. Two lines max.

## Output
| file | spec | note |

## Progress
| # | item | where | state |
States: ✅ done / 🟡 in progress / ⬜ todo / ⛔ blocked

## Where things live
- docs:
- code:
- assets:

## Decisions
| topic | choice | why |

## Pitfalls
1. symptom → cause → fix

## Next
1. executable actions, in order, ≤5

## Open questions
- things only a human can answer (delete the section if none)

Write in the user's language. If they write Chinese, translate the headings: 一句话 / 成品 / 进度表 / 文件在哪 / 关键决策 / 踩过的坑 / 下一步 / 待确认.

Requirements:

  • Every line is executable: reshoot shots 00 / 06, not "keep polishing".
  • Real numbers: duration, fps, file size, shot count.
  • Never write keys, emails, account IDs.
  • ≤120 lines. Longer means it wasn't distilled.

3.5 Lint before handing off

python3 "$SKILL_DIR/scripts/lint.py" <path>

It checks the rules this skill keeps preaching: ≤120 lines, sections present and in order, absolute date, no vague words ("basically done", "继续完善"), every next step actionable, allowed state markers, leaked keys, real email addresses (example.com and localhost are allowed on purpose, so examples can be written) and local absolute paths (warning only). Fix what it reports, then rerun until ✓.

4. Status card (optional)

cat > status.json <<'JSON'
{
  "kicker": "VIDEO PRODUCTION",
  "title": "EP.002 · shipping it alone",
  "highlight": ["shipping"],
  "status": "in progress · 5/7 shots",
  "stats": [{"k": "shots", "v": "5 / 7"}, {"k": "spec", "v": "1080×1920 · 60fps"}],
  "done": ["docs", "github", "screen capture"],
  "next": ["map", "summary", "voiceover"],
  "foot": "episodes/002-invoice2sheet",
  "mark": "WIP"
}
JSON
python3 "$SKILL_DIR/scripts/card.py" status.json

mark = WIP / DONE / BLOCKED; words listed in highlight render in green. Missing fields are fine — the card degrades instead of breaking.

5. Updating an existing doc

  • Touch only four blocks: status line, progress table, next steps, pitfalls (only if new).
  • Done items collapse into one line; never expand them.
  • Bump the update date.

Token ledger

Every scan.py run prints and records:

## token ledger (±20% estimate)
  worst    read every text file   210 files  ~289k tok
  typical  docs + 20 largest       22 files  ~66k tok
  brief    scan output + PROGRESS.md          ~843 tok
  => 99% less than reading those 22 files
  cumulative 3 runs  ~121k tok saved
  • worst = every text file: the real ceiling for "start from zero".
  • typical = root docs + 20 largest source files. A model of one pickup, not a measurement: an agent that greps well reads fewer files, and then the saving is smaller.
  • brief = this tool's cost.
  • Quote the baseline with the number — "99% less than reading those 22 files", never a bare "saves 99%". The percentage is a ceiling for a repo of that shape.
  • Exact when tiktoken is installed; otherwise calibrated estimate (±20%, median error 6.8% on a 263-file corpus). The label in the output says which. Never report it as precise.
  • Re-fit on a new corpus with scripts/calibrate.py --fit <dirs>.
  • Ledger lives at .usage.jsonl next to scripts/; delete it to reset.

Context hygiene: compact or restart?

Higher-frequency need than writing docs. Read the signal, then act:

SignalAction
Task switched domains (backend→frontend, video→copywriting)update doc, new window
A delivery / merge / release just finishednew window, keep the old one read-only
You explain the same background a second timecompact or restart
An answer needs 3+ whole files pastedcompact, paste diffs instead
Over half the context used, more than 3 steps leftcompact, drop finished sections
The model says "as I mentioned earlier" and gets it wrongrestart now, don't correct it
Small edits inside one modulekeep going

Standard handoff, all three required:

  1. a fresh PROGRESS.md (confirm with doctor.py)
  2. one executable opener: read PROGRESS.md, continue from step 2
  3. branch name / paths written inside the doc, not left to guesswork

When to use

SituationMove
Project spans days / windowswrite the brief, new window reads it
Conversation long and driftingdoctor.py + hygiene table, decide compact vs restart
Series (video, articles)one doc per episode, index README at root
Before a reportcard.py
Taking over a reposcan.py git section drives the progress table

Don't: one-off scripts, folders under ~15 text files (scan.py says so itself), unstarted projects.

Anti-patterns

  • ❌ pasting the README into PROGRESS.md
  • ❌ "basically done", "continuously improving"
  • ❌ appending a paragraph per step until it hits 500 lines
  • ❌ reading all source to write the doc
  • ❌ pushing on with a full context because "restarting means re-explaining"

Files

filewhat
scripts/scan.pyproject digest + token ledger
scripts/doctor.pycontinue / update / restart
scripts/lint.pyrule check on the doc (--json, --strict)
scripts/card.pyJSON → status.html + status.png
scripts/calibrate.pyre-fit the token estimate against tiktoken
scripts/install.pycross-platform installer
tests/python3 -m unittest discover -s tests

Platform

  • Pure python3 (3.10+), identical on macOS / Linux / Windows.
  • PNG needs Chrome / Chromium / Edge / Brave; auto-detected, HTML fallback otherwise.
  • Override: PROGRESS_BRIEF_CHROME=/path/to/chrome python3 card.py status.json
  • Install: python3 scripts/install.py (detects skills vs skill), --project <path> for per-project, --dest <dir> for any layout, --agents-md <file> to wire agents without a skill format, --prompt to print a paste-ready block.

Skills associés