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 skill references/ (functional modules, not a timeline).
• Frontmatter standard — required title / created / updated / status on every progress and research document; absolute YYYY-MM-DD dates 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-rules carries 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.md is 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 together

Manual 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  # Windsurf

Repeat 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:

1. Walk the progress tree from the root, find the single active leaf
2. Extract goal, scope, next-actions, and required-reading from the leaf
3. Generate a kickoff prompt that includes a mandatory confirmation gate
4. Save the prompt as NN-session-prompt-<slug>.md in 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-rules
• motiful/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 *-rules skill (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