2 files changed, 85 insertions, 0 deletions
diff --git a/claude-templates/.ai/workflows/INDEX.org b/claude-templates/.ai/workflows/INDEX.org
index 807410d..a474b29 100644
--- a/claude-templates/.ai/workflows/INDEX.org
+++ b/claude-templates/.ai/workflows/INDEX.org
@@ -91,6 +91,8 @@ This index must list every =.org= file in =.ai/workflows/= except this one and e
 
 ** Code quality
 
+- =code-quality.org= — one trigger that sequences every behavior-preserving quality pass over a scope of existing code: =/refactor= (complexity, duplication, dead-code, simplification) then =readability-audit= (comments, headers, names, organization), then surfaces the =:refactor:= tasks readability filed and any deferred =/refactor= findings. A thin orchestrator — each pass keeps its own gate. Excludes =/simplify= (that's for the current diff, not existing code).
+  - Triggers: "code quality sweep", "quality sweep", "run every quality pass on <scope>", "give me every pass on <scope>"
 - =readability-audit.org= — make code readable to a future maintainer: audit file-top commentary, inline comments (why-not-what), names (intention-revealing), and organization (co-location / stepdown / cohesion). The cheap comment- and name-only fixes (dimensions A/B/C) land inline, verified by a green suite; the structural findings (dimension D — split a module, rename a public symbol) are *filed* as =:refactor:= tasks, not done here. Language-agnostic. Feeds =/refactor= (which executes the filed structural work); distinct from =/refactor='s metric scans and =/simplify='s diff cleanup.
   - Triggers: "let's run the readability-audit workflow", "audit the comments and commentary in <area>", "clean up the structure/organization of <module>", "readability audit"
 
diff --git a/claude-templates/.ai/workflows/code-quality.org b/claude-templates/.ai/workflows/code-quality.org
new file mode 100644
index 0000000..2406f4c
--- /dev/null
+++ b/claude-templates/.ai/workflows/code-quality.org
@@ -0,0 +1,83 @@
+#+TITLE: Code-Quality Sweep Workflow
+#+AUTHOR: Craig Jennings & Claude
+#+DATE: 2026-06-28
+
+* Overview
+
+One trigger that runs every behavior-preserving quality pass over a scope of
+*existing* code, in order, then surfaces what got filed for later. It's a thin
+orchestrator — each pass keeps its own discipline and its own confirm gate; this
+workflow only sequences them and collects the residue.
+
+The passes it chains:
+
+1. =/refactor= — structural and logic cleanup on measurable metrics (complexity,
+   duplication, dead-code) plus the simplification lens.
+2. =readability-audit= ([[file:readability-audit.org][readability-audit.org]]) — prose and human-reader clarity
+   (comments, file headers, names, organization).
+
+It deliberately does *not* run =/simplify=: that works the current uncommitted
+diff, not existing committed code, so it belongs to the moment you've just made a
+change, not to a sweep of code already in the tree (see "The /simplify boundary"
+below).
+
+* When to Use This Workflow
+
+- "code quality sweep" / "quality sweep"
+- "run every quality pass on <scope>" / "full quality pass on <scope>"
+- "give me every pass on <file/module/tree>"
+
+Do NOT use it for:
+- *In-flight diff cleanup* — that's =/simplify= on the change you just made.
+- *Bug hunting* — these passes are behavior-preserving; for defects use =debug=
+  or =/review-code=.
+- *Performing the structural refactors it files* — those become =:refactor:=
+  tasks; work them later via =/refactor rename= / =/refactor simplification= or
+  =/start-work=.
+
+* Steps
+
+** 1. Scope
+
+Pick the target: one file, a named module set, or the whole tree (honor
+=.aiignore=). The same scope is passed to both passes so they cover the same
+code.
+
+** 2. /refactor <scope>
+
+Run =/refactor= on the scope. Its default full scan covers complexity,
+duplication, dead-code, and simplification. It presents findings and applies
+only what's approved (its own gate) — structure and logic first, so the
+readability pass audits the cleaned-up code.
+
+** 3. readability-audit on <scope>
+
+Run the readability-audit workflow on the same scope. Its cheap comment- and
+name-only fixes (dimensions A/B/C) land inline and are verified by a green
+suite; its structural findings (dimension D — split a module, rename a public
+symbol) are *filed* as =:refactor:= tasks rather than done here.
+
+** 4. Surface the residue
+
+Collect and report what the sweep left behind for later work:
+
+- The =:refactor:= tasks readability-audit filed (the structural backlog).
+- Any =/refactor= findings deferred rather than applied in step 2.
+
+That residue is the "do this next" list the sweep produces; it's not a failure
+to finish, it's the structural work that needs its own design and test pass.
+
+* The /simplify boundary
+
+=/simplify= and this sweep don't overlap: =/simplify= cleans the *current diff*
+and applies its fixes directly, so reach for it right after making a change,
+before committing. This sweep works *existing committed code* and runs the
+scan-and-present passes. One trigger can't sensibly do both — a diff you're
+holding and a tree you're auditing are different inputs.
+
+* Verification
+
+Each pass owns its verification (=/refactor= runs the suite after applying;
+readability-audit verifies inline fixes against a green suite). The umbrella
+adds nothing beyond sequencing, so when both passes report green, the sweep is
+clean — confirm that before reporting done rather than assuming it.