# Pygienium — Code Hygiene Extension

Objective: A pi extension (piolium-style sub-agent loops) that runs highly-structured code-hygiene passes over a repo to clean up common LLM-code quality issues.

Status legend: [ ] todo, [~] in-progress, [x] done

Tasks

- [x] 01 — scaffolding → `01-scaffolding.md`
- [x] 02 — recon → `02-recon.md`
- [x] 03 — agent-runner → `03-agent-runner.md`
- [x] 04 — hygiene-state → `04-hygiene-state.md`
- [x] 05 — infrastructure-utils → `05-infrastructure-utils.md`
- [x] 06 — check-registry → `06-check-registry.md`
- [x] 07 — check-comments → `07-check-comments.md`
- [x] 08 — check-deep-modules → `08-check-deep-modules.md`
- [x] 09 — check-dead-code → `09-check-dead-code.md`
- [x] 10 - check-complexity → `10-check-complexity.md` (incl. cyclomatic complexity: 50+ must-refactor, 35–49 heavy-skepticism)
- [x] 11 — check-defensive-guards → `11-check-defensive-guards.md`
- [x] 12 — orchestrator-all → `12-orchestrator-all.md`
- [x] 13 — resume-status-export → `13-resume-status-export.md`
- [x] 14 — readme-help-integration → `14-readme-help-integration.md`

Dependencies

- 02, 03, 04, 05 depend on 01
- 06 depends on 02, 03, 04, 05
- 07, 08, 09, 10, 11 depend on 06 (07 serves as the reference E2E check)
- 12 depends on 07, 08, 09, 10, 11
- 13 depends on 04, 06
- 14 depends on 12, 13

Exit criteria

- The feature is complete when `/pygienium-help` lists all commands/flags, each `/pygienium-<check>` command runs an isolated sub-agent that scans a target, applies fixes, and emits a findings+changes report; `/pygienium-all` runs every registered check in sequence with a unified status strip and resumable state; `/pygienium-resume`, `/pygienium-status`, and `/pygienium-export` work; and adding a new check requires only a new file in `checks/` plus one registry entry (no index.ts command-wiring changes).

Architecture reference

- Style: piolium (`@vigolium/piolium`) sub-agent loops via `createAgentSession`
- Distribution: local extension under `~/.pi/agent/extensions/pygienium/`, structured to be npm-publishable later
- Each check = a "mode": deterministic recon → sub-agent analysis → sub-agent fixes → verify → cleanup
- Check registry makes the system extensible: new check = new file + registry entry