Clean-Docs Skill (CAFleet-orchestrated)

One skill, three workflows — residue, affirmative, simplification — run as the same CAFleet team shape over the same per-run process. This page is the dispatcher and the single home of the shared orchestration spine; each workflow body (<workflow>/<workflow>.md) carries only its own trigger scenario, scan mechanics, artifact spec, and guarantees, citing the spine here rather than restating it.

Resolve runtime tools from the executing agent's backend. For spawns, read the selected member backend's Model catalog and Role defaults under the CAFleet Director's model-selection policy; validate its effort and launch capabilities there. Monitor bootstrap and recovery inherit the Director's backend. Interpret captured panes using the observed member's backend cues.

Required reading

Identify the executing backend (members use CODING AGENT), resolve its runtime bindings, and load cafleet for BASE, member startup or Director orchestration. Read coordination for verbs, pointers and marker pairing, then this shared spine once. A workflow's Required reading adds only its phase-specific prerequisites. Resolve model tokens from the selected spawn backend's Role defaults, runtime tokens from the executing backend, and capture cues from the observed backend; use documented defaults only in their allowed cases.

Dispatch

Route the user's request into exactly one workflow body by phrasing, then run that body's orchestration in full over the spine below. One workflow per run — never a combined pass. When a request names families from more than one workflow, the Director asks the user which single workflow to run via {decision_surface}.

When the user wants to…	Run
Clean up historical narration / historical residue; remove deprecation notes, "this replaces X" / "renamed from Y" / "previously … now …" prose; drop design-number provenance citations; remove historical sentinel framing while preserving current absence tests	the residue workflow (residue/residue.md)
Run an affirmative-writing sweep; fix prohibition-only rule sections; pair prohibitions with affirmatives; remove meaningless fallbacks; make code fail fast	the affirmative workflow (affirmative/affirmative.md)
Simplify the docs / comments; tighten verbose prose; de-duplicate documentation; remove redundant comments	the simplification workflow (simplification/simplification.md)

Class-to-workflow split

Every candidate a scanner may act on belongs to exactly one workflow. The class identifiers are canonical in each workflow's classification section; ownership is:

Workflow	Owns	Fix character
residue	(a) sentinel framing, (b) narration/citation/trajectory, (c) keep + known-benign	Remove historical framing; preserve current absence tests and reword narration to present tense. Strictly zero behavior change.
affirmative	P1 prohibition-pile, P2 unpaired prohibition (including negatively-phrased instructions rewritable in affirmative voice), P4 meaningless fallback / swallowed error	Fixes that change prohibition structure, voice, or code behavior. P4 rows are BEHAVIOR-AFFECTING — the only permitted behavior change in any workflow (invariant 1).
simplification	P3 redundant prose, P5 verbose phrasing (verbosity only — the 30%+ word-reduction baseline; voice rewrites belong to P2)	Fixes that only delete redundancy or reduce words, with voice and behavior unchanged. Strictly zero behavior change.

Boundary tie-break. A candidate whose fix would change prohibition structure, voice, or code behavior belongs to affirmative, even when it is also verbose — the affirmative rewrite subsumes the tightening. A candidate whose fix only removes words or duplication with unchanged voice belongs to simplification. Past-tense narration always belongs to residue. A scanner never proposes another workflow's classes: it records cross-workflow candidates in its artifact's Observations section (see Observations escalation channel below) for the Director to report, so the user can schedule the other workflow.

Three invariants (every workflow, every run)

1. No contract or behavior lost. Every CLI flag, error string, schema, command example, IMPORTANT line, and cross-reference survives — in fewer words, never in weaker form. Sole exception: an approved affirmative-workflow P4 row, which changes behavior deliberately (fallback → fail-fast); each P4 row names its covering tests or is explicitly marked "uncovered", and lands only with the reviewer's individual acceptance — an "uncovered" row only with that acceptance made explicit. Residue and simplification runs are strictly zero-behavior-change.
2. No live test coverage lost. Test logic, assertions, fixtures, and parametrizations are untouchable; only comments, docstrings, and sentinel framing are in scope. Preserve current-behavior absence tests, including native parser rejection; a framing edit retains all test logic and assertions.
3. No new narration (R1). Every edit reads as a clean present-tense statement of current behavior — no "previously / now / formerly", no "this replaces X", no "renamed from Y".

Scope and exempt set

In scope: the whole tracked tree minus the exempt set. Exempt (never modified): design-docs/, researches/, and lock files. The design/research folders are the historical record.

Per surface, the scope of what may change:

Surface	In scope	Untouchable
docs/, README.md, SPEC.md, skills, rules	prose structure and wording	contract detail (exact flags, error strings, schemas, layouts), command examples, IMPORTANT / lossless-rule lines, backend-neutral base/overlay separation
source code	comments, docstrings, affirmative-workflow P4 fallback sites	flags, options, columns, code paths, log/user-facing/error strings
tests	comments, docstrings, sentinel framing	all logic, assertions, fixtures, names

Team shape

User → /clean-docs (one workflow)
 └─ Director (main session — resolves BASE, bootstraps fleet + monitor
              member atomically, partitions slices, merges partials,
              holds the apply behind review, verifies, commits when asked,
              deletes the monitor member first at teardown)
     ├─ scanner-1  (owns a disjoint file slice: scan → propose → apply after gate)
     ├─ scanner-N  (…)
     └─ reviewer   (the workflow's guard, --model {reviewer_model})

Role	Responsibility
Director	Resolve task-scoped ${BASE}; bootstrap the fleet with the monitor member included (cafleet fleet create --monitor-file <abs path> --monitor-model {monitor_model}) and gate the first ordinary spawn on its monitor live message (the CLI monitor-first guard backstops); partition the in-scope tree into disjoint file-ownership slices (one file → one scanner, whole surfaces per scanner); merge partial artifacts into the run's canonical artifact; route it to the reviewer and hold the apply until the reviewer's approval; relay approval to scanners; apply a denied write through the full-file staging protocol; run verification; escalate observations to the user; delete the monitor member first (first-out) at teardown.
scanner (×N)	For its slice: run the workflow's scan mechanics, propose actions per the workflow's rubric, record observations separately, write its partial artifact under ${BASE}. After approval is relayed: apply its own slice's approved rows exactly as written, re-verify its diff, route harness-denied writes to the Director.
reviewer	Validate the merged artifact before any edit, per the workflow's guarantees and guardrails. After apply: run the workflow verification (parameter table below).

Disjoint file-ownership is the concurrency contract. No two scanners edit the same file, so parallel apply is safe without worktrees. One scanner owns every edit to a given file, regardless of class — a file touched by several classes is assigned whole to one scanner. A useful default partition: docs+root files / skills+.claude / source+admin / tests — merge or split slices to balance the scanner count against the tree size.

Coordination

The skill adopts the cafleet verb + pointer schema (skills/cafleet-design-doc/reference/coordination.md) with two skill-local extensions, since a run produces a run artifact, not a design document:

• Role taxonomy gains a scanner role for COMMENT(scanner) markers.
• Pointer: a per-workflow whole-run pointer denotes the run artifact as a whole — inventory for residue, findings for affirmative and simplification. Scanners report complete (<run pointer>); the reviewer's gate is approved (inventory) / approved (findings) (or blocked (<run pointer>)); per-row routing uses <file>:<line> pointers.

Per-run process

1. Resolve ${BASE} — task-scoped per the cafleet skill's reference/base-dir.md, convention researches/clean-docs-<workflow>-<UTC-compact>/ (gitignored, one folder per run).
2. Bootstrap — cafleet doctor (gating), then cafleet fleet create --monitor-file <abs path to ${BASE}/.prompts/monitor-<UTC-compact>.md> --monitor-model {monitor_model} (one atomic command: fleet + Director + monitor member; members spawned {permission_flags}); gate the first ordinary spawn on the monitor's monitor live message (the CLI monitor-first guard backstops).
3. Spawn workers — scanners (one per disjoint slice) and the reviewer (--model {reviewer_model}), each from a rendered prompt at ${BASE}/.prompts/<role>-<UTC-compact>.md.
4. Scan (fan-out) — each scanner runs the workflow's scan mechanics (parameter table below) over its slice and writes its partial artifact under ${BASE}, with a separate Observations section.
5. Merge + review (gate) — the Director merges partials into the run's canonical artifact and routes it to the reviewer with ready (<run pointer>). No repository edit happens before the reviewer's approved (<run pointer>).
6. Apply — the Director relays approval; each scanner applies its own slice's approved rows exactly as written. Use the full-file staging protocol for a denied write.
7. Verify — mise //cafleet:test, mise //cafleet:lint, mise //cafleet:typecheck green, plus the workflow verification (parameter table below).
8. Report + teardown — the Director reports the applied set and the escalated observations, commits only when the user asks, and tears down (delete the monitor member first — the pane kill takes the loop down — → delete the remaining members → verify via member list → fleet delete).

Full-file staging

Every scanner reads this protocol before application. For a harness-denied target write, stage the complete replacement file under ${BASE}/.apply/, retaining its relative target path. Compare it with the current repository file: the diff must contain exactly the Director-relayed approved rows, including reviewer REVISE text. Send the Director the target and staged paths; continue independent approved work in the rest of your slice.

The Director reads the staged file and diff, checks both against approved rows and current user authorization, then applies that exact file. A mismatch or changed authorization returns to review/arbitration before writing. Staging preserves the gate; it is not approval. Scanners and reviewer perform the normal post-apply checks after the Director's write.

Workflow parameter table

The spine is parameterized by exactly three per-workflow values:

Parameter	residue	affirmative	simplification
Scan mechanics	multi-pass pattern-catalog sweep + hand-inspection of every hit	full-file judgment read of every file in the slice	full-file judgment read of every file in the slice
Artifact / pointer	inventory.md / inventory	findings.md / findings	findings.md / findings
Workflow verification	post-apply re-sweep → zero unaccounted matches	reviewer confirms the diff is confined to approved rows and each P4 row's named coverage is validated (an "uncovered" row requires the reviewer's explicit acceptance)	reviewer confirms the diff is confined to approved rows

Observations escalation channel

While scanning, a scanner records — and never fixes — content drift (two surfaces disagreeing, a broken cross-reference, a doc contradicting the code) and cross-workflow candidates (Class-to-workflow split above) in its artifact's Observations section. The Director escalates them to the user in the run report. The applied cleanup — the git diff plus green verification — is the real deliverable; observations are escalated, never self-applied.

${BASE} convention

Task-scoped per the cafleet skill's reference/base-dir.md: researches/clean-docs-<workflow>-<UTC-compact>/ (gitignored, one folder per run). Agent-only scratch is dot-prefixed: .prompts/ (spawn-prompt renders), .apply/ (staged harness-denied writes).

Spawn-prompt skeleton

One skeleton for all three workflows, with the workflow named in the role line and the role-definition path pointing into <workflow>/roles/. The Director renders each [INSERT …] marker to a literal before writing; leaves the four {fleet_id} / {member_id} / {director_member_id} / {coding_agent} identity placeholders for the CLI's str.format at spawn; doubles every OTHER literal brace as {{ / }}:

You are the <role> in a clean-docs <workflow> team (CAFleet-native).

ROLE DEFINITION: Open [INSERT abs path to <workflow>/roles/<role>.md] with an available text reader BEFORE any other action.

Load these skills at startup:
- the clean-docs skill — for the shared spine and your workflow's mechanics
- the cafleet skill — for the broker primitives and bash-via-Director routing

FLEET ID: {fleet_id}
DIRECTOR MEMBER ID: {director_member_id}
YOUR MEMBER ID: {member_id}
BASE: [INSERT abs BASE path the Director resolved]
CODING AGENT: {coding_agent}

<role-specific assignment: the scanner's slice path list + partial-artifact path,
 or the reviewer's merged-artifact path>

IMPORTANT: Read and follow .claude/rules/bash-tool.md (CAFleet-member Bash protocol) and ~/.claude/rules/bash-command.md (general Bash hygiene) for all Bash commands.
Host-rule source: [INSERT equivalent session instructions for any absent optional host files]. Apply those supplied equivalents; route an essential unknown prerequisite to the Director before dependent work.
IMPORTANT: If blocked, send a message to the Director immediately instead of assuming.
IMPORTANT: Do NOT edit any repository file until the Director relays the reviewer's approved (<run pointer>). The scan phase is read + propose only.
IMPORTANT: Do NOT commit code or run git write operations — the Director handles all git.

Use an available non-shell text reader for prerequisites; shell file reads may precede ready when shell is the only reader.

On spawn, as your first operational broker shell command, send the ready signal: cafleet message send --from-member-id {member_id} --to-member-id {director_member_id} "ready"

When you see cafleet message poll output with a message from the Director, act on those instructions.

<start cue: scanner — begin the scan of your slice; reviewer — wait for ready (<run pointer>)>

Backend-neutrality

SKILL.md, the workflow bodies, and every <workflow>/roles/*.md are backend-neutral: they use {bg_run} / {reviewer_model} / {skill_loader} / {decision_surface} / {permission_flags} tokens resolved from the executing agent's Runtime bindings or, for model placeholders, the selected spawn backend's Role defaults in ../../../skills/cafleet/reference/coding-agents.md. Capture interpretation uses the observed member's backend cues, and every member's spawn-prompt identity block carries a CODING AGENT: {coding_agent} line so the member resolves its overlay. Role files are referenced by absolute path in spawn prompts (never inlined); spawns use --file.

Skill file layout

.claude/skills/clean-docs/
  SKILL.md                        # this file — dispatch + shared spine, backend-neutral
  reference/
    review-format.md              # shared by affirmative + simplification: row format, guardrails, verdict flow
  residue/
    residue.md                    # workflow body — sweep mechanics + completeness guarantee
    roles/scanner.md              # sweep → hand-inspect → classify → apply own slice
    roles/reviewer.md             # over-deletion / lost-coverage / R1 guard
    reference/patterns.md         # pattern catalog + exempt-set exclusion — canonical
  affirmative/
    affirmative.md                # workflow body — P1/P2/P4 judgment review
    roles/scanner.md              # full read → propose → apply own slice after the gate
    roles/reviewer.md             # lost-meaning / lost-contract / behavior-change guard
  simplification/
    simplification.md             # workflow body — P3/P5 judgment review
    roles/scanner.md
    roles/reviewer.md