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 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".

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".

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".

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".

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".

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".

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

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

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

---
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 — Single-root location rules per archetype, forbidden locations, verification checklist
• references/naming-convention.md — Directory/file naming, NN- prefix rule, skill-references exception, casing
• references/frontmatter-spec.md — Required and optional fields, status enum, date format, enforcement
• references/tree-structure.md — When to open a child, parent-child pointer format, max nesting depth, status propagation
• references/handoff-protocol.md — Incoming read order, outgoing prompt template, verification before handoff
• 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)