Progress tree discipline — one root per project, zero drift between AI sessions.
Agent Skills compatible — works with Claude Code, Codex, Cursor, Windsurf, and any Agent Skills adopter.
Pairs with progress-hygiene-rules for MUST/NEVER enforcement. Replaces the deprecated progress-archive (its archive rules are absorbed into the rule-skill companion).
AI projects that span multiple sessions lose state in predictable ways. Progress files land in .claude/ and in docs/ in the same repo; a split-repo project ends up with two PROGRESS.md files that drift the same afternoon one of them is edited; a new Claude Code session opens the repo and has no idea which phase is active or which of the seven markdown files to read first.
The fixes are all local: pick one location, use frontmatter, keep a tree. But "all local" is why no one ships them together. progress-hygiene is that bundle — the location matrix, the naming rules, the frontmatter schema, the tree protocol, and the handoff procedure, in one skill that loads when you're about to touch a progress file.
- Location matrix — exactly one progress root per project across four archetypes (public-code + backstage, standalone skill, augmented-skill workspace, private monorepo). No "either is fine".
- NN- naming rule —
01-scaffold.md,02-integration.md… with an explicit exception for skillreferences/(functional modules, not a timeline). - Frontmatter standard — required
title/created/updated/statuson every progress and research document; absoluteYYYY-MM-DDdates only. - Tree-structure protocol — when to open a child subtree (150-line trigger, session-scope trigger, business-dimension trigger), pointer-style parent-child references, 3-level nesting ceiling.
- Handoff generation — produce a new-session kickoff prompt from the tree's active node; incoming session has a fixed read order and a confirmation gate before starting work.
- Audit & migration procedure — scan an existing project, classify findings by archetype, generate a per-file migration plan.
- Augmenter pair — companion
progress-hygiene-rulescarries the MUST/NEVER constraints enforced on every progress file edit.
Four distinct operations, one trigger phrase each:
"create a progress file for this project" — derives location, writes frontmatter, opens in tree
"this progress file is getting long" — opens a child subtree, wires parent-pointer
"hand off to a new session" — generates kickoff prompt from tree's active node
"audit this project for progress drift" — scans repo, reports findings, no file changes
- Starting a multi-session project and want the progress tree right from day one
- A flat
progress.mdis approaching 150 lines and you need to open a child subtree - Ending a session and handing off work to a fresh Claude Code / Codex instance
- Joining a project mid-flight and need the incoming read order
- Retrofitting an existing repo with scattered or drifting progress files
Not for: single-file throwaway scripts, projects without a CLAUDE.md or equivalent, code-formatting concerns.
npx skills add motiful/progress-hygiene
npx skills add motiful/progress-hygiene-rules # paired augmenter — installs togetherManual registration:
git clone https://github.com/motiful/progress-hygiene ~/skills/progress-hygiene
ln -sfn ~/skills/progress-hygiene ~/.claude/skills/progress-hygiene # Claude Code
ln -sfn ~/skills/progress-hygiene ~/.agents/skills/progress-hygiene # Codex
ln -sfn ~/skills/progress-hygiene ~/.cursor/skills/progress-hygiene # Cursor
ln -sfn ~/skills/progress-hygiene ~/.codeium/windsurf/skills/progress-hygiene # WindsurfRepeat for progress-hygiene-rules — the two ship as a pair; installing only one leaves the methodology taught but unenforced.
All phrases that activate this skill:
"create a progress file"
"where does the progress file live"
"start a new progress doc"
"open a child progress"
"this progress file is getting long"
"split this progress into subtasks"
"hand off to a new session"
"generate a session kickoff prompt"
"new session, continuing from prior work"
"audit this project for progress drift"
"migrate an existing PROGRESS.md"
Example — handing off at session end:
User: "hand off to a new session"
progress-hygiene will:
- Walk the progress tree from the root, find the single
activeleaf- Extract goal, scope, next-actions, and required-reading from the leaf
- Generate a kickoff prompt that includes a mandatory confirmation gate
- Save the prompt as
NN-session-prompt-<slug>.mdin the tree; return the path
motiful/progress-hygiene-rules— required pair. MUST/NEVER constraints enforced on every progress file edit. Without it, the methodology is documented but not bound. Install:npx skills add motiful/progress-hygiene-rulesmotiful/repo-scaffold— scaffolds the project archetypes (A1 / A2 / A3 / B) this skill's location matrix keys off of. Use when standing up a new project.motiful/rules-as-skills— activates the meta-rule protocol that elevates any*-rulesskill (including the augmenter above) to MUST-level priority across agents.
SKILL.md — Methodology EP, 5 sub-entries (create / open / handoff / incoming / audit)
references/
location-matrix.md — 4 archetypes → exactly one progress root each
naming-convention.md — NN- prefix rule + skill-references exception
frontmatter-spec.md — title/created/updated/status schema + render/validate defs
tree-structure.md — Subtree triggers, pointer-style parent-child, depth ceiling
handoff-protocol.md — Incoming read order, outgoing prompt template, confirmation gate
migration-playbook.md — Generic audit_project / classify_finding / migrate_file / report_findings procedure
The deprecated motiful/progress-archive covered only the 200-line archive threshold and verbatim-preservation rules. Those are absorbed into progress-hygiene-rules §Archive Constraints. Existing progress-archive installs should uninstall and switch to this pair.
MIT — See LICENSE for details.
Crafted with Readme Craft