cc-os/plugins/os-doc-hygiene/commands/hygiene.md

name	description	argument-hint
hygiene	Manage stale and bloated docs. `/hygiene check` scans the project for stale/bloated documentation and writes a report; `/hygiene clean` applies documented findings; `/hygiene sweep` runs check then clean; `/hygiene status` shows the last check/clean/reminded timestamps and whether a report exists.	[check [--scope <glob-or-path>] [--category <class|subtype>] | status | clean [--scope <glob-or-path>] [--category <class|subtype>] | sweep [--scope <glob-or-path>] [--category <class|subtype>]]

/hygiene — Documentation Hygiene

Single entry point for the doc-hygiene plugin. Dispatch on $ARGUMENTS.

Parse the first token of $ARGUMENTS as the subcommand; everything after it is passed through. Scripts live under ${CLAUDE_PLUGIN_ROOT}/scripts/ (mirrors hooks/hooks.json).

check [--scope <glob-or-path>] [--category <class|subtype>]

Invoke the hygiene-check skill (Skill tool, skill: "hygiene-check"), passing the --scope and --category arguments through verbatim. The skill owns the full workflow — scan → classify → finalize → validate → write report → stamp last_check. Do not scan or classify here; just route to the skill and surface its summary.

status

Read-only. No skill, no model, no scan. Run the state store directly and report the three lifecycle timestamps plus whether a report exists. state_store.py is a module (no CLI), so call it via python3 -c:

python3 -c '
import sys, os
sys.path.insert(0, os.environ["CLAUDE_PLUGIN_ROOT"] + "/scripts")
from state_store import StateStore, resolve_project_root
from pathlib import Path
s = StateStore(resolve_project_root(Path(os.getcwd())))
def fmt(dt): return dt.isoformat() if dt else "never"
print("last_check:    " + fmt(s.get_last_check()))
print("last_clean:    " + fmt(s.get_last_clean()))
print("last_reminded: " + fmt(s.get_last_reminded()))
print("report:        " + ("present" if s.read_report() else "none"))
'

Present the output as a short human summary, for example:

doc-hygiene status for: <project-root>

  last check     2026-06-20T14:03:11+00:00
  last clean     never
  last reminded  2026-06-24T09:00:00+00:00
  report         present  (run /hygiene check to refresh)

Do not classify or distill anything — these are timestamp reads only.

clean [--scope <glob-or-path>] [--category <class|subtype>]

Invoke the hygiene-clean skill (Skill tool, skill: "hygiene-clean"), passing the --scope and --category arguments through verbatim. The skill owns the full workflow — load report → gate confirm-tier entries → apply deterministic ops → dispatch generative ops → commit → stamp last_clean. Do not apply any edits here; just route to the skill and surface its summary.

A report must exist before running clean. If the user has not yet run /hygiene check, the skill will stop and instruct them to do so.

sweep [--scope <glob-or-path>] [--category <class|subtype>]

sweep is check-then-clean: a convenience that runs both skills in sequence, passing the same --scope and --category through to each.

1. First, invoke the hygiene-check skill (Skill tool, skill: "hygiene-check"), passing --scope and --category verbatim. Surface the check summary to the user.

2. Then, invoke the hygiene-clean skill (Skill tool, skill: "hygiene-clean"), passing the same --scope and --category verbatim.

The confirm gate in hygiene-clean applies identically under sweep — sweep does not auto-approve any confirm-tier or generative entries. The user will still be prompted to approve any entries that require it before any file mutation occurs (invariant #7).

sweep produces at most one cleanup commit (the clean step); the check step writes only to the gitignored .dochygiene/ and does not commit.

No arguments or unrecognized subcommand

Print usage, then run the status block above and show current state:

/hygiene — documentation hygiene

  check [--scope <glob-or-path>] [--category <class|subtype>]
                 scan for stale/bloated docs and write a report
  status         show last check/clean/reminded timestamps + report presence
  clean [--scope <glob-or-path>] [--category <class|subtype>]
                 apply documented findings (requires a report; run check first)
  sweep [--scope <glob-or-path>] [--category <class|subtype>]
                 check then clean in sequence (confirm gate still applies)