{"id":"4547056a-d35d-4511-b18f-21a43fc498b9","slug":"progress-hygiene","kind":"skill","name":"progress-hygiene","summary":"Progress tree discipline — one root per project, zero drift between AI sessions. Location matrix, NN- naming, frontmatter, tree protocol, handoff generation. Pairs with progress-hygiene-rules.","owner":"motiful","repoUrl":"https://github.com/motiful/progress-hygiene","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-04-21T18:22:10.000Z","addedAt":"2026-10-21T10:56:58.252Z","logoUrl":"https://avatars.githubusercontent.com/u/263427193?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","communication","writing"],"tags":["claude-code","codex","cursor","documentation","progress-tracking","project-management","session-handoff"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T19:05:05.991Z","sample":false,"url":"https://conduits.dev/tools/progress-hygiene","language":"","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\".github/logo-dark.svg\">\n    <source media=\"(prefers-color-scheme: light)\" srcset=\".github/logo-light.svg\">\n    <img alt=\"progress-hygiene\" src=\".github/logo-light.svg\" width=\"440\">\n  </picture>\n</div>\n\n<div align=\"center\">\n\n[![License: MIT][license-shield]][license-url]\n[![Version][version-shield]][version-url]\n[![Agent Skills][skills-shield]][skills-url]\n\n</div>\n\n<div align=\"center\">\n  <a href=\"#the-problem\">Why</a> &middot;\n  <a href=\"#quick-start\">Quick Start</a> &middot;\n  <a href=\"#install\">Install</a> &middot;\n  <a href=\"#usage\">Usage</a>\n</div>\n\n> Progress tree discipline — one root per project, zero drift between AI sessions.\n\n[Agent Skills](https://agentskills.io) compatible — works with Claude Code, Codex, Cursor, Windsurf, and any Agent Skills adopter.\n\nPairs with [`progress-hygiene-rules`](https://github.com/motiful/progress-hygiene-rules) for MUST/NEVER enforcement. Replaces the deprecated [`progress-archive`](https://github.com/motiful/progress-archive) (its archive rules are absorbed into the rule-skill companion).\n\n---\n\n## The Problem\n\nAI 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.\n\nThe 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.\n\n## Features\n\n- **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\".\n- **NN- naming rule** — `01-scaffold.md`, `02-integration.md`… with an explicit exception for skill `references/` (functional modules, not a timeline).\n- **Frontmatter standard** — required `title` / `created` / `updated` / `status` on every progress and research document; absolute `YYYY-MM-DD` dates only.\n- **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.\n- **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.\n- **Audit & migration procedure** — scan an existing project, classify findings by archetype, generate a per-file migration plan.\n- **Augmenter pair** — companion `progress-hygiene-rules` carries the MUST/NEVER constraints enforced on every progress file edit.\n\n## Quick Start\n\nFour distinct operations, one trigger phrase each:\n\n```text\n\"create a progress file for this project\"        — derives location, writes frontmatter, opens in tree\n\"this progress file is getting long\"              — opens a child subtree, wires parent-pointer\n\"hand off to a new session\"                       — generates kickoff prompt from tree's active node\n\"audit this project for progress drift\"           — scans repo, reports findings, no file changes\n```\n\n## When to Use\n\n- Starting a multi-session project and want the progress tree right from day one\n- A flat `progress.md` is approaching 150 lines and you need to open a child subtree\n- Ending a session and handing off work to a fresh Claude Code / Codex instance\n- Joining a project mid-flight and need the incoming read order\n- Retrofitting an existing repo with scattered or drifting progress files\n\nNot for: single-file throwaway scripts, projects without a `CLAUDE.md` or equivalent, code-formatting concerns.\n\n## Install\n\n```bash\nnpx skills add motiful/progress-hygiene\nnpx skills add motiful/progress-hygiene-rules     # paired augmenter — installs together\n```\n\n**Manual registration:**\n\n```bash\ngit clone https://github.com/motiful/progress-hygiene ~/skills/progress-hygiene\n\nln -sfn ~/skills/progress-hygiene ~/.claude/skills/progress-hygiene      # Claude Code\nln -sfn ~/skills/progress-hygiene ~/.agents/skills/progress-hygiene      # Codex\nln -sfn ~/skills/progress-hygiene ~/.cursor/skills/progress-hygiene      # Cursor\nln -sfn ~/skills/progress-hygiene ~/.codeium/windsurf/skills/progress-hygiene  # Windsurf\n```\n\nRepeat for `progress-hygiene-rules` — the two ship as a pair; installing only one leaves the methodology taught but unenforced.\n\n## Usage\n\nAll phrases that activate this skill:\n\n```text\n\"create a progress file\"\n\"where does the progress file live\"\n\"start a new progress doc\"\n\"open a child progress\"\n\"this progress file is getting long\"\n\"split this progress into subtasks\"\n\"hand off to a new session\"\n\"generate a session kickoff prompt\"\n\"new session, continuing from prior work\"\n\"audit this project for progress drift\"\n\"migrate an existing PROGRESS.md\"\n```\n\n**Example** — handing off at session end:\n\n> User: \"hand off to a new session\"\n>\n> progress-hygiene will:\n> 1. Walk the progress tree from the root, find the single `active` leaf\n> 2. Extract goal, scope, next-actions, and required-reading from the leaf\n> 3. Generate a kickoff prompt that includes a mandatory confirmation gate\n> 4. Save the prompt as `NN-session-prompt-<slug>.md` in the tree; return the path\n\n## Works Better With\n\n- [`motiful/progress-hygiene-rules`](https://github.com/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`\n- [`motiful/repo-scaffold`](https://github.com/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.\n- [`motiful/rules-as-skills`](https://github.com/motiful/rules-as-skills) — activates the meta-rule protocol that elevates any `*-rules` skill (including the augmenter above) to MUST-level priority across agents.\n\n## What's Inside\n\n```text\nSKILL.md                              — Methodology EP, 5 sub-entries (create / open / handoff / incoming / audit)\nreferences/\n  location-matrix.md                  — 4 archetypes → exactly one progress root each\n  naming-convention.md                — NN- prefix rule + skill-references exception\n  frontmatter-spec.md                 — title/created/updated/status schema + render/validate defs\n  tree-structure.md                   — Subtree triggers, pointer-style parent-child, depth ceiling\n  handoff-protocol.md                 — Incoming read order, outgoing prompt template, confirmation gate\n  migration-playbook.md               — Generic audit_project / classify_finding / migrate_file / report_findings procedure\n```\n\n## Replaces progress-archive\n\nThe deprecated [`motiful/progress-archive`](https://github.com/motiful/progress-archive) covered only the 200-line archive threshold and verbatim-preservation rules. Those are absorbed into [`progress-hygiene-rules`](https://github.com/motiful/progress-hygiene-rules) §Archive Constraints. Existing `progress-archive` installs should uninstall and switch to this pair.\n\n## License\n\nMIT — See [LICENSE](LICENSE) for details.\n\n---\n\nCrafted with [Readme Craft](https://github.com/motiful/readme-craft)\n\n[license-shield]: https://img.shields.io/badge/License-MIT-green.svg\n[license-url]: https://github.com/motiful/progress-hygiene/blob/main/LICENSE\n[version-shield]: https://img.shields.io/badge/version-1.0-blue.svg\n[version-url]: https://github.com/motiful/progress-hygiene/releases\n[skills-shield]: https://img.shields.io/badge/Agent%20Skills-compatible-DA7857?logo=anthropic\n[skills-url]: https://agentskills.io\n"}