# Progress Hygiene

> Progress tree methodology — single source of truth location matrix, frontmatter discipline, tree expansion protocol, and new-session handoff generation for project progress tracking. Use when creating a new progress file, opening a child subtree, generating a handoff prompt for a fresh session, or auditing an existing project for progress-file drift. Answers "where does the progress file live", "when do I open a child", and "how does a new session continue the work". Pairs with progress-hygiene-rules for MUST/NEVER constraints. MUST read SKILL.md BEFORE creating, moving, or restructuring any progress file.

- Skill: `motiful/progress-hygiene` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add motiful/progress-hygiene`
- Raw SKILL.md: https://api.skillmd.com/api/skills/motiful/progress-hygiene/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: motiful (https://skillmd.com/u/motiful)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/motiful/progress-hygiene

---


# Progress Hygiene — Progress Tree Methodology

Progress tracking in AI-agent projects has three recurring failure modes: ambiguous location (where does the file live?), lost lineage (what was decided when?), and failed handoff (new session can't pick up). This skill fixes all three by treating progress as a **tree of frontmatter-tagged documents** with exactly one location per project archetype.

Pairs with [`progress-hygiene-rules`](../progress-hygiene-rules/) which carries the MUST/NEVER constraints.

## When to Use

- Creating a progress file in a new or existing project
- Opening a child subtree because the parent is growing
- Generating a handoff prompt for a new Claude Code session
- Auditing an existing project for drift or missing frontmatter
- Deciding whether a project needs to graduate from flat `progress.md` to a tree

## Execution Procedure

Five entry points, one per action. Each sub-EP maps 1:1 to a trigger phrase in the description and is independently invocable. A primitive like `write_file` or `read` is filesystem I/O and is not sourced from a reference.

### EP — Create New Document

Triggered by: "where does this progress file go", "start a new progress doc", "add a research phase".

```python
def create_new_document(project, kind, title, body):
    """Create a progress or research document at the correct location with valid frontmatter.

    kind: one of "progress_child", "research_child", "progress_flat", "tree_entry"
    """
    root = locate_progress_root(project)               # references/location-matrix.md
    assert root is not None, "archetype unclear — ask user"

    path = derive_path(root, kind, title)              # references/naming-convention.md
    validate_naming(path, kind)                        # references/naming-convention.md

    frontmatter = render_frontmatter(                  # references/frontmatter-spec.md
        title=title, created=today(), updated=today(), status="draft",
    )
    write_file(path, frontmatter + body)               # filesystem primitive
    return path
```

### EP — Open Subtree

Triggered by: "this progress file is getting long", "open a child for this subtask".

```python
def open_subtree(parent_file):
    """Split a parent progress file into a subtree when a trigger fires."""
    if not decide_subtree(parent_file):                # references/tree-structure.md
        return None

    child_dir = create_child_tree(parent_file)         # references/tree-structure.md
    scaffold_child_readme(child_dir, parent_file)      # references/tree-structure.md
    update_parent_pointer(parent_file, child_dir)     # references/tree-structure.md
    return child_dir
```

### EP — Generate Handoff

Triggered by: "new session handoff", "end of session, hand off to next".

```python
def generate_handoff(progress_root):
    """Generate and save a new-session handoff prompt from the tree's active node."""
    active_node = find_active_node(progress_root)      # references/tree-structure.md
    prompt = generate_handoff_prompt(active_node)      # references/handoff-protocol.md
    path = save_prompt_to_tree(prompt, progress_root)  # references/handoff-protocol.md
    return path
```

### EP — Incoming Session

Triggered by: "new session, just got handed off", "continuing work from a prior session".

```python
def incoming_session(progress_root):
    """Read-order and confirmation gate for a new session entering an existing tree.
    MUST confirm understanding with the user before any work begins.
    """
    files = read_incoming_files(progress_root)         # references/handoff-protocol.md
    for path in files:
        read(path)                                     # filesystem primitive
    confirm_understanding_with_user()                  # references/handoff-protocol.md
    # Do not start work until confirmation returns
```

### EP — Audit Existing

Triggered by: "audit this project for progress drift", "how do I migrate old PROGRESS.md files".

```python
def audit_existing(project):
    """Scan a project for progress-file drift; produce a migration report (no file changes).

    Output is a markdown report saved to `<project>-backstage/plan/<project>-progress-migration.md`
    (or equivalent per archetype). The report is the input to execute_migration below.
    """
    findings = audit_project(project)                  # references/migration-playbook.md
    return report_findings(findings)                   # references/migration-playbook.md
```

### EP — Execute Migration

Triggered by: "run the migration I audited", "execute progress-file migration", "migrate this finding".

```python
def execute_migration(findings):
    """Execute migrate_file for each finding. One commit per finding — no batching.

    Typically invoked after audit_existing produced findings and the user has reviewed
    the saved plan. Blocked findings are skipped (their blocker must clear first).
    """
    for finding in findings:
        if finding["blockers"]:
            skip_with_reason(finding)
            continue
        migrate_file(finding)                          # references/migration-playbook.md
        # commit and proceed — see migration-playbook.md §What Not to Do
```

Enforcement is delegated to `progress-hygiene-rules` (companion augmenter). Any of these sub-EPs triggers its MUST/NEVER constraints on the files touched; this capability skill does not duplicate enforcement logic.

## The Core Invariants

Four invariants drive every decision in this skill. If any breaks, the methodology fails.

### I1. Exactly one progress root per project

Determined by `references/location-matrix.md`. Two roots inevitably drift — the 2026-04-18 `design-playbook` incident is the proof case. Ambiguity at the location level is structurally worse than any discipline failure because the ambiguity itself creates the discipline failure.

### I2. Every document carries frontmatter

Title, created, updated, status — minimum. `references/frontmatter-spec.md` has the full schema. An agent (or a human three months later) must be able to tell what a document is, when it was written, and whether it is still current **without reading the body**. Filesystem `mtime` is not a substitute.

### I3. Progress is a tree, not a file

When a flat progress file would exceed ~150 lines, open a child. `references/tree-structure.md` defines when and how. The parent references the child by **pointer** — summary line plus link, never duplicating content. Copy-style references always drift; pointer-style references cannot.

### I4. The tree is self-documenting for handoff

A fresh session joining the project reads at most 3-5 files to know exactly what to do next: CLAUDE.local.md → root README → active node. `references/handoff-protocol.md` defines the read order and the prompt template. If a fresh session needs 10+ files or private chat history to continue, the tree has failed and needs reshaping.

## The Archetypes at a Glance

| Archetype | Progress root |
|-----------|---------------|
| A1. Public code + backstage | `<project>-backstage/progress/` |
| A2. Standalone skill (no backstage) | `<skill>/progress.md` (flat) |
| A3. Augmented skill workspace | `<primary>-backstage/progress/` |
| B. Private monorepo | `docs/progress/` |

Full decision procedure and rationale in `references/location-matrix.md`. These are the only four legitimate patterns — everything else is a migration case.

## Naming at a Glance

| Kind | Rule |
|------|------|
| Progress root directory | `progress/` (lowercase) |
| Progress tree entry | `README.md` |
| Progress children | `NN-<slug>.md` (zero-padded two-digit prefix, kebab slug) |
| Skill references | No NN- prefix (functional modules, not timeline) |
| Research topic entries | `research/<topic-slug>/README.md` |
| Research children | `NN-<slug>.md` |

Full rules and exceptions in `references/naming-convention.md`. The NN- rule applies only to time/logic-ordered trees; applying it to skill references is a category error.

## Frontmatter at a Glance

```yaml
---
title: <human-readable>
created: YYYY-MM-DD
updated: YYYY-MM-DD
status: draft | active | stale | archived
---
```

Optional fields (`type`, `parent`, `owner`, `supersedes`, `tags`) documented in `references/frontmatter-spec.md`. Dates are always absolute `YYYY-MM-DD`, never relative.

## Handoff at a Glance

Outgoing session produces a prompt file from the active node of the tree. Incoming session reads:

1. `CLAUDE.md`, `CLAUDE.local.md`
2. Progress root `README.md`
3. Active-node file
4. Any files the active node explicitly links to

Full template and verification checklist in `references/handoff-protocol.md`.

## Relationship to Other Skills

- **progress-hygiene-rules** (companion augmenter) — MUST/NEVER constraints. Auto-loads on any progress file edit. This skill teaches; that skill enforces.
- **repo-scaffold** — defines the project archetypes (A1/A2/A3/B) that this skill's location matrix keys off of. When scaffolding a new project, repo-scaffold creates the directories; progress-hygiene fills them.
- **progress-archive** (deprecated, archived 2026-04) — single-purpose predecessor covering only the 200-line archive rule. Its constraint is absorbed into progress-hygiene-rules. Existing progress-archive installations should uninstall and switch to this pair.

## References

- [`references/location-matrix.md`](references/location-matrix.md) — Single-root location rules per archetype, forbidden locations, verification checklist
- [`references/naming-convention.md`](references/naming-convention.md) — Directory/file naming, NN- prefix rule, skill-references exception, casing
- [`references/frontmatter-spec.md`](references/frontmatter-spec.md) — Required and optional fields, status enum, date format, enforcement
- [`references/tree-structure.md`](references/tree-structure.md) — When to open a child, parent-child pointer format, max nesting depth, status propagation
- [`references/handoff-protocol.md`](references/handoff-protocol.md) — Incoming read order, outgoing prompt template, verification before handoff
- [`references/migration-playbook.md`](references/migration-playbook.md) — Generic audit/classify/migrate/report procedure for retrofitting existing projects to the methodology (no project-specific inventory — that lives in each project's backstage)