Why · Enforces · Install · Capability Pair

Hard constraints on every progress file edit — so the methodology you adopted stays bound, not just documented.

Augmenter rule-skill for progress-hygiene. Install the pair together. Absorbs and deprecates progress-archive.

Any skill whose name ends with -rules is treated as a MUST-level hard constraint by rules-as-skills. Install that protocol first to activate global enforcement; otherwise these rules load as a normal skill (still useful, but without elevated priority).

---

The Problem

A documented methodology is not an enforced methodology. progress-hygiene teaches where progress files live, how to name them, what frontmatter to write, when to open a subtree, and how to hand off to a new session. But a teaching skill cannot stop an agent from dropping progress.md into .claude/ at 2am because nobody triggered the methodology on that particular edit.

progress-hygiene-rules is the enforcement half: activates on any progress file edit, migration, or handoff, and carries MUST/NEVER boundaries the agent is obligated to satisfy before committing.

What It Enforces

Location

• MUST locate exactly one progress root per project (per the location matrix)
• NEVER place progress files under .claude/, .agents/, or any agent-workspace directory
• NEVER maintain two progress files with mutual cross-references

Frontmatter

• MUST include title, created, updated, status on every progress and research document
• MUST use absolute ISO dates (YYYY-MM-DD); NEVER relative phrasing
• MUST use one of four status values: draft, active, stale, archived

Naming

• MUST use zero-padded two-digit NN-<slug>.md prefix for children of progress/ and research/ trees
• NEVER apply NN- prefix to skill references/, scripts/, or design/ directories

Tree structure

• MUST open a child subtree before parent exceeds ~150 lines
• MUST reference children from parents by pointer (summary + link); NEVER duplicate child content into parent
• MUST use relative paths in parent-child and archive links

Archive (absorbed from the deprecated progress-archive)

• MUST archive completed phases when a progress file exceeds ~200 lines
• MUST preserve archived text verbatim; NEVER summarize or rewrite
• MUST keep incomplete tasks and their context untouched in the main file
• NEVER delete completed content — archive is move, not delete
• SHOULD keep recent update-log entries (~2 weeks) in the main file

Handoff

• MUST generate handoff prompts from the progress tree, not chat history
• MUST name 3-5 specific files for the incoming session; NEVER "read everything"
• MUST include a confirmation gate before any new-session work begins

Full catalog (with rationale, verification pseudocode, and the compression-stub template) lives in SKILL.md.

Install

npx skills add motiful/progress-hygiene-rules
npx skills add motiful/progress-hygiene           # paired capability — installs together

Manual registration:

git clone https://github.com/motiful/progress-hygiene-rules ~/skills/progress-hygiene-rules

ln -sfn ~/skills/progress-hygiene-rules ~/.claude/skills/progress-hygiene-rules
ln -sfn ~/skills/progress-hygiene-rules ~/.agents/skills/progress-hygiene-rules

For MUST-level priority across agents (Claude Code, Codex, Cursor, Windsurf, OpenClaw), also install and activate rules-as-skills. Its meta-rule protocol treats every -rules suffix skill — including this one — as a hard constraint.

Usage

This skill auto-activates. Environment-trigger description matches any of:

editing a progress file
creating a new progress document
migrating an old PROGRESS.md
archiving a completed phase
generating a session handoff
auditing a project for drift

No explicit invocation needed. When the skill loads, it reads SKILL.md and runs the verify_compliance(file, tree) procedure against the file about to be edited.

How It Fits

This is one half of an Augmented Skill collection. The pair:

Skill	Role	Trigger
progress-hygiene	Capability — teaches methodology	Intent ("create a progress file", "open a subtree", "hand off")
progress-hygiene-rules	Augmenter — enforces constraints	Environment (any progress-file edit)

Intent triggers and environment triggers target different dimensions of the agent's context, so the capability and the augmenter do not compete for the same match — double coverage, no contention.

Replaces progress-archive

The deprecated motiful/progress-archive carried two rules: archive at 200 lines, preserve content verbatim. Both are absorbed into this skill's §Archive Constraints plus the new SHOULD on update-log handling. The original repo is archived on GitHub and kept for historical reference.

What's Inside

SKILL.md        — Full constraint catalog, verify_compliance() EP, compression stub template
LICENSE         — MIT
.github/
  logo-*.svg    — Dark/light logo variants
  repo-meta.yml — GitHub description + topics

No references/ directory — rule-skills carry their full content in the body, by convention.

License

MIT — See LICENSE for details.

---

Crafted with Readme Craft