clean-docs
Skill56 starsChanged 4 days agoMITView on GitHub
Clean up the repository's docs, comments, rules, and tests as a CAFleet team of disjoint-slice scanner members gated by a reviewer — exactly one workflow per run. Use the residue workflow when the user asks to clean up historical narration or historical residue, remove deprecation notes / "this replaces X" / "renamed from Y" / "previously … now …" prose, drop design-number provenance citations, or remove historical sentinel framing while preserving current absence tests. Use the affirmative workflow when the user asks to run an affirmative-writing sweep, fix prohibition-only rule sections, pair prohibitions with affirmatives, remove meaningless fallbacks, or make code fail fast. Use the simplification workflow when the user asks to simplify the docs or comments, tighten verbose prose, de-duplicate documentation, or remove redundant comments. Apply changes after the reviewer approves the merged run artifact. Members load clean-docs through their backend's skill-loader.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- Anggel7x/skillstheir own version, first seen Nov 15, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- Anggel7x/skills★ 4same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- cafleet-model-list-refreshSkill
- skill-authorSkill
- update-readmeSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
22 rules. About 0 are common, 16 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈16
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
Run one workflow from Dispatch using the shared orchestration below.
- Distinctive: line 77
Preserve contract and behavior: Every CLI flag, error string, schema, command example, IMPORTANT line and cross-reference survives in full …
- Distinctive: line 83
Preserve live test coverage: Keep all test logic, assertions, fixtures, parametrizations and names.
- Distinctive: line 87
Write current behavior (R1): Every edit reads as a clean present-tense statement.
- Very specific: line 129
Use the cafleet verb + pointer schema (assets/skills/cafleet-design-doc/reference/coordination.md) with these skill-local extensions:
- Very specific: line 133
Add the scanner role for COMMENT(scanner) markers.
- Very specific: line 166
Every scanner reads this protocol before application.
- Very specific: line 200
Use dot-prefixed folders for agent-only scratch: .prompts/ for spawn renders and .apply/ for staged harness-denied writes.
- Distinctive: line 224
Remove historical narration and sentinel framing while retaining current behavior and absence tests.
- Distinctive: line 231
Run every pattern pass over the assigned tracked slice with the exempt-set exclusions.
- Distinctive: line 257
Keep present-tense false positives unchanged:
- Distinctive: line 270
Read the hit and its whole surrounding sentence, docstring or test body.
- Distinctive: line 277
When (b) versus (c) remains ambiguous, choose KEEP and record the reason in the inventory's KEEP list.
- Very specific: line 298
Use every pass with -i for case-insensitive matching (Design 0000NNN, Legacy) and -P for Perl regex, required for the design-number \b …
- Very specific: line 332
Before application, re-judge every non-KEEP row against the classification and guard against over-deletion: retain KEEP and known-benign …
- Distinctive: line 351
Read those prerequisites and Review format before scanning or reviewing.
- Distinctive: line 365
Every P4 row deliberately changes fallback → fail-fast behavior and carries:
- Distinctive: line 418
Read every tracked file in the assigned slice in full, rather than relying on grep: structural and redundancy findings require judgment.
- Distinctive: line 474
Read its full section, docstring or test-body context.
- Distinctive: line 475
Check KEEP guardrails; a guarded surface produces no finding.
- Distinctive: line 486
Check each row against actual file context.
- Distinctive: line 497
After application, on the Director's request, compare the diff with approved rows, confirm only those rows changed and every assertion and …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Clean-Docs Skill (CAFleet-orchestrated)
Run one workflow from Dispatch using the shared orchestration below. Each workflow section defines its scan mechanics, classes and checks; Review format owns the shared judgment-review rules. Member roles are defined in roles.md.
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.
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. Read the
selected workflow section and its required references before scanning or
reviewing. Resolve model tokens from the selected spawn backend's Role defaults
and runtime tokens from the executing backend; use documented defaults only in
their allowed cases. Apply supplied session equivalents for absent optional
host-rule files; route essential unknown prerequisites to the Director before
dependent work.
Dispatch
Route the user's phrasing to exactly one workflow section and run its full
process through the spine below. 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 | Residue |
| Run an affirmative-writing sweep; fix prohibition-only rule sections; pair prohibitions with affirmatives; remove meaningless fallbacks; make code fail fast | Affirmative |
| Simplify the docs / comments; tighten verbose prose; de-duplicate documentation; remove redundant comments | Simplification |
Class-to-workflow split
Each candidate belongs to exactly one workflow, selected by its fix:
| 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 | Changes prohibition structure, voice, or code behavior. Approved P4 rows are the sole permitted behavior change (invariant 1). |
| simplification | P3 redundant prose, P5 verbose phrasing | Deletes redundancy or reduces words with voice and behavior unchanged; P5 uses the 30%+ word-reduction baseline. |
A fix that changes prohibition structure, voice or code behavior belongs to affirmative even when also verbose; the affirmative rewrite subsumes the tightening. Word-only reductions with unchanged voice belong to simplification. Past-tense narration belongs to residue. Record another workflow's candidates in Observations for the Director to report, so the user can schedule that workflow.
Three invariants (every workflow, every run)
- Preserve contract and behavior. Every CLI flag, error string, schema, command example, IMPORTANT line and cross-reference survives in full strength. The sole exception is an approved affirmative P4 row, whose deliberate fallback → fail-fast behavior change follows the P4 protocol. Residue and simplification remain strictly zero-behavior-change.
- Preserve live test coverage. Keep all test logic, assertions, fixtures, parametrizations and names; edit only comments, docstrings and sentinel framing. Current-behavior absence tests, including native parser rejection, retain every assertion.
- Write current behavior (R1). Every edit reads as a clean present-tense statement. Proposed text introduces no "previously / now / formerly", "this replaces X" or "renamed from Y" narration.
Scope and exempt set
Scan the whole tracked tree except design-docs/, researches/ and lock files;
these exempt paths remain untouched. The design/research folders are the
historical record.
| 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, parametrizations, names |
Team shape
User → /clean-docs (one workflow)
└─ Director (resolves BASE, registers the current session, partitions slices,
merges partials, retains native reception, holds apply behind review,
verifies and closes owned members)
├─ 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}; register the current Director atomically and arm native reception; assign disjoint whole-file slices; merge partials and hold application behind reviewer approval. Relay approval, apply denied writes through full-file staging, verify, report observations and close owned members before deregistering the fleet. |
| scanner | Scan its slice, propose actions, record observations and write its partial artifact under ${BASE}. After relayed approval, apply its slice's approved rows exactly as written, verify the diff and route denied writes. |
| reviewer | Validate the merged artifact before repository edits using the selected workflow's checks. After application, perform its workflow verification. |
Disjoint file ownership is the concurrency contract: one scanner owns every
edit to a file, regardless of class. Parallel application therefore needs no
worktrees. A useful default partition is docs+root files / skills+.claude /
source / tests; merge or split slices to fit the tree while retaining whole-file
ownership.
Coordination
Use the cafleet verb + pointer schema
(assets/skills/cafleet-design-doc/reference/coordination.md) with these skill-local
extensions:
- Add the
scannerrole forCOMMENT(scanner)markers. - The whole-run pointer denotes the canonical artifact:
inventoryfor residue,findingsfor affirmative and simplification. Scanners reportcomplete (<run pointer>); the review gate isapproved (<run pointer>)orblocked (<run pointer>). Route individual rows with<file>:<line>pointers.
Per-run process
- Resolve
${BASE}per BASE convention. - Bootstrap — run
cafleet doctor, thencafleet fleet create --name <name> --coding-agent <backend> --json; retain the returned literal IDs, then follow Director wake. - Spawn workers — scanners for disjoint slices using the other-member
defaults, plus a reviewer using
--model {reviewer_model}and supported reviewer effort. Render prompts per Spawn deltas at${BASE}/.prompts/<role>-<UTC-compact>.md. - Scan — each scanner follows its workflow's scan mechanics over its slice and writes a partial artifact with a separate Observations section.
- Merge + review — the Director merges partials into the canonical
artifact and sends the reviewer
ready (<run pointer>). Repository edits remain gated on the reviewer'sapproved (<run pointer>). - Apply — the Director relays approval; scanners apply only their slice's approved rows exactly as written, including reviewer REVISE wording. Use full-file staging for a denied write.
- Verify — pass the repository's Rust validation tasks
(
.claude/rules/commands.md) and the selected workflow verification below. - Report + teardown — report the applied set and escalated observations, commit only when the user asks, close owned ordinary members, verify the root-only roster and deregister the fleet.
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 normal post-apply checks after the Director's write.
Workflow parameter table
| Parameter | residue | affirmative | simplification |
| Scan mechanics | Every pattern pass plus 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 | Re-sweep: zero unaccounted matches; preserve live coverage and behavior, with current-state wording | Diff confined to approved rows; re-validate each P4 row's named coverage and explicit acceptance for an "uncovered" row | Diff confined to approved redundancy deletions and word reductions; voice, behavior, runtime surfaces and live assertions preserved |
Observations escalation channel
Record content drift (surface disagreements, broken cross-references, docs contradicting code) and cross-workflow candidates in the artifact's Observations section, without proposed fixes. The Director escalates these in the run report; scanners apply only the approved cleanup. The git diff plus green verification is the deliverable; the run artifact is its audit record.
BASE convention
Resolve task-scoped BASE through the shared
task-scope resolver:
researches/clean-docs-<workflow>-<UTC-compact>/ (gitignored, one folder per run).
Use dot-prefixed folders for agent-only scratch: .prompts/ for spawn renders
and .apply/ for staged harness-denied writes.
Spawn deltas
Render each member prompt from the
canonical spawn skeleton
with the role file referenced by absolute path and this delta. Render each
IMPORTANT item as a separate prompt line, verbatim with <run pointer>
substituted.
| Slot | Scanner | Reviewer |
| ROLE TITLE / TEAM | a scanner / clean-docs <workflow> | the reviewer / clean-docs <workflow> |
| role-file | roles.md | roles.md |
| ROLE-DEF SUFFIX | Follow the Scanner section. | Follow the Reviewer section. |
| cafleet-load purpose | for the broker primitives and command routing through the Director | for the broker primitives and command routing through the Director |
| EXTRA SKILL LOADS | clean-docs (shared spine and your workflow's mechanics) | clean-docs (shared spine and your workflow's mechanics) |
| CONTEXT LINES | WORKFLOW: [INSERT workflow], YOUR SLICE: [INSERT the slice's path list], OUTPUT FILE: [INSERT partial-artifact path] | WORKFLOW: [INSERT workflow], MERGED ARTIFACT: [INSERT merged-artifact path] |
| IMPORTANT / ROLE-CONSTRAINT LINES (verbatim) | IMPORTANT: Follow the CAFleet member Bash protocol (.claude/rules/commands.md § Bash tool) and the host's Bash hygiene rule for all Bash commands., 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., When you see cafleet message poll output with a message from the Director, act on those instructions. | IMPORTANT: Follow the CAFleet member Bash protocol (.claude/rules/commands.md § Bash tool) and the host's Bash hygiene rule for all Bash commands., IMPORTANT: If blocked, send a message to the Director immediately instead of assuming., IMPORTANT: Do NOT edit any repository file; your writes are verdict annotations in the run artifact., IMPORTANT: Do NOT commit code or run git write operations — the Director handles all git., When you see cafleet message poll output with a message from the Director, act on those instructions. |
| start cue (verbatim) | Begin the scan of your slice. | Wait for ready (<run pointer>) from the Director. |
Residue
Remove historical narration and sentinel framing while retaining current behavior and absence tests. This workflow changes prose only and follows the host's Removal and Affirmative Writing rules. Read those rules and the complete classification and pattern catalog below before scanning or reviewing.
Sweep mechanics and Scanner obligations
Run every pattern pass over the assigned tracked slice with the exempt-set exclusions. Hand-inspect each hit's whole sentence, docstring or test body; classify from that context. The catalog is a floor: classify relevant hits even when no listed pattern matched them.
Record every hit, including KEEP and known-benign, in the assigned partial
inventory under ${BASE}. Use a partial table or COMMENT(scanner) markers at
the hit's <file>:<line> in the inventory, as directed. Each row carries location,
quoted text anchor, rubric class and action. After approved application, re-run
every pass over the slice and report complete (inventory) or per-file
complete (<file>:<line>); the partial inventory also reports
complete (inventory).
Classification
Classify each hit once; the scanner proposes and the reviewer checks its full context before application.
| Class | Definition | Action |
| (a) Sentinel framing | Historical framing that advertises a removed or never-added feature; a test asserting current flag/key absence, including native parser rejection, is current coverage. | Remove only the framing; retain every test's logic, assertions, fixtures, parametrizations and names, including absence tests. |
| (b) Narration / citation / trajectory | Past-state prose ("previously X, now Y", "no longer / formerly / deprecated", "this replaces X", "renamed from Y", "backfills each pre-existing session"), a design-number-as-reason citation (design 0000NNN), trajectory ("inverted by 0000092", "after design 0000124"), or version qualifier ("in v1", "first cut"). | Reword to pure present-tense current behavior or drop the citation clause; retain the behavior description and all coverage. |
| (c) Keep | Current behavior, an illustrative example path / fixture slug, or a forward-looking rationale / editing guard ("do not refactor X into Y", "runtime config has no historical value; drop it"). | Keep unchanged. |
Known-benign KEEP matches
Keep present-tense false positives unchanged:
no longerdescribing current behavior: "a deleted member no longer appears" or "the loop no longer owns the slot".used tomeaning utilized to.preserved for/retained fordescribing current behavior, rather than "preserved for history / forensic visibility" justifying a removed value.\bstale\b/STALEnaming live asset-version or skill-install staleness.- Issue-provenance citations such as
(issue #174 bullet 3); the citation cleanup covers design numbers, so issue references stay.
Decision procedure for one hit
- Read the hit and its whole surrounding sentence, docstring or test body.
- For tests, retain all current-behavior coverage, including absence/rejection assertions. Classify historical framing as (a); test logic stays KEEP.
- Otherwise, classify past narration or a design-number-as-reason citation as (b), preserving the behavior description and any test.
- Classify current behavior, illustrative paths/slugs, forward-looking rationale and known-benign matches as (c).
- When (b) versus (c) remains ambiguous, choose KEEP and record the reason in the inventory's KEEP list; the reviewer guards against over-deletion.
Sweep pattern catalog
Sweep tracked files only; the tracked tree selects membership and includes newly tracked surfaces automatically. Exclude the exempt set from every pass with this pathspec. Extend the lockfile exclusions for every other lockfile in the slice; the research exclusion covers tracked research files too:
git grep -nIiP -e '<pattern>' -- \
':(exclude)design-docs/**' ':(exclude)researches/**' \
':(exclude)*.lock' ':(exclude)**/*.lock' \
':(exclude)pnpm-lock.yaml' ':(exclude)**/pnpm-lock.yaml' \
':(exclude)package-lock.json' ':(exclude)**/package-lock.json' \
':(exclude)npm-shrinkwrap.json' ':(exclude)**/npm-shrinkwrap.json' \
':(exclude)bun.lockb' ':(exclude)**/bun.lockb'Use every pass with -i for case-insensitive matching (Design 0000NNN,
Legacy) and -P for Perl regex, required for the design-number \b boundary
on macOS/BSD. -n prints line numbers; -I skips binary files.
| Pattern (regex) | Catches |
deprecat | deprecation notices |
no longer|formerly|previously|used to | past-state narration; hand-filter known-benign present-tense uses |
\blegacy\b | legacy framing; hand-filter fixture names such as legacy_squat |
sentinel | removal-sentinel framing |
historical | historical rows / narration |
forensic|preserved for|for history | forensic-visibility / history pointers; hand-filter current preserved for / retained for |
restoration | restoration-plan pointers |
design[ -]?0[0-9]{6} and \b0[0-9]{6}\b | design-number-as-reason citations across the full seven-digit ID space; boundaries exclude all-zero UUID constants (00000000-0000-…); illustrative slugs stay KEEP |
in v1|first cut | version qualifiers |
backfill|pre-existing | migration-backfill narration in prose; keep migration filenames |
this replaces|renamed from|inverted by|after design | replacement / rename / trajectory narration |
Artifact: inventory.md
Merge partial inventories into ${BASE}/inventory.md, the inventory pointer,
with these parts:
- File→action tables grouped by surface / rubric class, with location, quoted text anchor, class and action for every hit.
- An explicit KEEP list.
- A Known-benign sweep matches subsection for present-tense false positives.
- Observations for content drift and cross-workflow candidates.
The complete inventory is the ephemeral audit record under gitignored
researches/; the applied diff and green verification are the deliverable.
Reviewer checks and completeness guarantee
Before application, re-judge every non-KEEP row against the classification and guard against over-deletion: retain KEEP and known-benign matches, every runtime flag/table/column/code path and live assertion. A mixed sentinel test retains its live assertion, and absence/rejection regressions remain intact. Reworded prose states current behavior, without "previously / now / no longer (as past) / formerly", "this replaces X" or "renamed from Y" narration. Account for every catalog hit as action, KEEP or exempt.
Mark a failed check at its inventory <file>:<line> and reply
blocked (inventory), or route the fix with ready (<file>:<line>). After
application, re-run every pass or review the scanners' re-sweep results and
inspect the diff: zero unaccounted matches remain; every hit is KEEP-listed,
known-benign or exempt. Confirm that edits remove only historical framing and
narration, preserve behavior and live coverage, and introduce no new narration.
Affirmative
State desired behavior directly by enforcing the host's Affirmative Writing
rule and .claude/rules/code-quality.md, including their legitimacy carve-outs.
Read those prerequisites and Review format before scanning or
reviewing. Use its shared full-file judgment process, artifact and verdict flow;
this workflow alone permits behavior changes through P4.
Affirmative finding classes
| Class | Definition | Action |
| P1 prohibition-pile | A section mostly containing DO-NOT/NEVER bullets without the desired behavior they protect. | State what to do and what correct looks like; retain every genuine hard constraint paired with its affirmative counterpart. |
| P2 unpaired prohibition | A "never X" without "instead do Y", or a negative instruction rewritable affirmatively with the same constraint. | Add the pairing or state the same constraint as a pure affirmative instruction. |
| P4 meaningless fallback / swallowed error | A defaulting lookup where the key is guaranteed, value or fallback masking an invariant, or try/except returning a placeholder that hides a condition the caller needs. | Use direct access or raise an error through the P4 protocol below. |
The P4 BEHAVIOR-AFFECTING protocol
Every P4 row deliberately changes fallback → fail-fast behavior and carries:
- The BEHAVIOR-AFFECTING tag.
- The guaranteed invariant, explaining why the key/value must exist and the fallback masks a bug or corrupt state.
- Its covering tests, or the explicit "uncovered" mark.
- The reviewer's individual acceptance, explicitly recorded for an "uncovered" row before application.
The reviewer checks that the invariant is genuinely guaranteed, the fail-fast replacement is correct, and the named tests exist and cover the site. After application, re-validate each row's named coverage. Expected, well-specified absence retains its correct default; proposing it as P4 is a defect.
Affirmative Reviewer checks
Apply the shared meaning, contract and narration checks in Review format plus the P4 protocol. Paired prohibitions and documented correct defaults are compliant, so reject findings that rewrite them as violations. Approve genuine affirmative rewrites; reject style-only word changes that fail to improve affirmativeness. Route word-only reductions and past-state narration to Observations under the class-to-workflow split.
Simplification
Retain meaning in fewer words using the Review format full-file judgment process, artifact and verdict flow. Preserve voice and behavior; source-code edits cover comments and docstrings only. Candidates changing prohibition structure, voice or behavior belong to affirmative; past-state narration belongs to residue. Record them as Observations.
Simplification finding classes
| Class | Definition | Action |
| P3 redundant prose | A sentence, comment or docstring restating adjacent prose, a table, a code block, a linked reference or the code itself. | Delete or merge into the surviving statement; retain a code comment only for a constraint the code cannot show. |
| P5 verbose phrasing | Prose materially shorter with zero meaning loss; the aggressive baseline is a paragraph that can lose 30%+ of its words with every constraint and precision intact. | Propose the exact tighter text, preserving voice and behavior. |
Simplification Reviewer checks
Apply the shared meaning, contract and narration checks in Review format. Require word reductions or redundancy removal with voice and behavior unchanged; a runtime-surface edit, code change beyond comments/docstrings or voice rewrite is a defect. Approve genuine tightenings using the 30%+ baseline and reject style-only churn that changes words without reducing them.
Review format
This section owns the shared process for affirmative and simplification. Residue uses its own classification, pattern catalog and inventory.
Judgment reading and Scanner obligations
Read every tracked file in the assigned slice in full, rather than relying on grep: structural and redundancy findings require judgment. Use the selected workflow's classes and propose exact final text. The reviewer also reads documentation maintenance, including its Coding-agent overlay section, before judging contract or backend-neutrality changes.
Each scanner writes ${BASE}/findings-<slice>.md at its assigned output path,
with apply-ready rows and a separate Observations section. The Director merges
these into ${BASE}/findings.md, consolidating observations and preserving
verdict space per row. The canonical pointer is findings.
Report written findings as
complete (findings) — <one-line count by class>; after approved application,
diff the slice against its approved rows and report
complete (findings) — <files changed, +/− lines>. A blocker marker sits at the
offending row in the findings artifact. Every replacement follows the shared
invariants, with affirmative P4 as the sole approved behavior exception.
Apply-ready row format
One row or block per finding carries all five fields:
location (file:line) | quoted current text (first+last words for long spans)
| class | exact proposed replacement text (or "delete") | risk noteThe replacement is final wording, applicable without further judgment. The class comes from the selected workflow's rubric; affirmative P4 rows also carry the metadata and acceptance required by its protocol. Favor precise rows that survive adversarial checks for lost meaning.
KEEP guardrails
Preserve these surfaces while editing surrounding prose:
- Contract detail:
SPEC.md's exact CLI options, error strings, schemas, key order and text layouts; command facts inassets/skills/cafleet/reference/cli.md; command examples in skills and docs. - Behavioral-contract lines: IMPORTANT lines, spawn-skeleton lossless-rule items, hard role constraints and start cues survive verbatim in meaning.
- Backend neutrality: base skills retain neutral instructions under
.claude/rules/documentation-maintenance.md§ Coding-agent overlay. - Legitimate prohibitions: a strong prohibition paired with its affirmative counterpart is compliant.
- Correct defaults: documented correct behavior for expected, valid absence is compliant.
- Runtime surfaces: flags, options, columns, code paths, log/user-facing/error strings, and all test logic, assertions, fixtures, parametrizations and names. The P4 protocol supplies invariant 1's sole behavior-change exception.
- Current-state wording: proposed text follows invariant 3 (R1).
Decision procedure for one candidate
- Read its full section, docstring or test-body context.
- Check KEEP guardrails; a guarded surface produces no finding.
- Classify by the selected workflow's rubric and draft the exact replacement.
- Re-read against the original; retain every constraint, condition, qualifier and cross-reference. Revise or drop a finding that loses any of them.
- Drop marginal word changes that neither shrink nor clarify; style-only churn fails review.
- Record content disagreements and other workflows' candidates as Observations, outside the findings set.
Shared Reviewer checks and verdict flow
Check each row against actual file context. Preserve every constraint, condition, qualifier and cross-reference; exact contract detail, CLI examples, error strings, IMPORTANT lines, spawn-skeleton lossless items and backend-neutral base/overlay separation survive verbatim in meaning. Require current-state wording under invariant 3 and the selected workflow's additional checks.
Annotate every row in the merged findings.md with COMMENT(reviewer) and
APPROVE, REJECT (with reason), or REVISE (with corrected replacement
text). Send approved (findings) when every surviving row is APPROVE or REVISE;
send blocked (findings) when Director arbitration is needed.
After application, on the Director's request, compare the diff with approved
rows, confirm only those rows changed and every assertion and contract surface
is preserved, then perform the workflow-specific verification. Send
approved (findings) again, or annotate a regression with COMMENT(reviewer)
and blocked (<file>:<line>).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

