| name | rules-worker |
| description | Compresses and merges CLAUDE.md and rules files to fit under the 40K character cap |
Rules Worker
NOTE: Startup and cleanup are handled by worker-base. This skill defines the WORK PROCEDURE.
When to Use This Skill
Features that modify .claude/CLAUDE.md or .claude/rules/*.md files — compression, merging, restructuring, frontmatter changes, cross-reference updates.
Work Procedure
-
Read the feature description carefully. Understand exactly which files to modify, what to preserve, and what to compress/merge.
-
Baseline measurement. Before ANY changes, run the character count script from AGENTS.md to record the current total. Record individual file sizes for files you'll modify.
-
Write tests first (red). Create test file at tests/rules/<descriptive-name>.test.cjs. Tests should verify:
- Character count targets (file size assertions)
- Content preservation (grep for required concepts/markers)
- Structural integrity (frontmatter validity, cross-reference resolution)
- Merge completeness (all source content present in merged file)
Run tests — they should FAIL (red).
-
Implement changes.
- For compression: Read the file, identify verbose/redundant text, rewrite concisely. Preserve ALL semantic content — compress the expression, not the meaning.
- For merges: Read ALL source files, combine into one with logical section organization. Delete originals AFTER verifying merge.
- For frontmatter: Add valid YAML frontmatter with
--- delimiters, description: and globs: or paths: keys.
- For cross-references: Search ALL .claude/rules/*.md and .claude/CLAUDE.md for references to deleted/renamed files. Update every reference.
-
Run tests (green). All tests pass. Fix any failures.
-
Verify character count. Run the total character count script. Must be under target.
-
Run lint and format.
pnpm lint
pnpm format:check
-
Manual verification. Read each modified file end-to-end. Verify no critical content was lost. Check that the file reads naturally and coherently — not just mechanically compressed.
Example Handoff
{
"salientSummary": "Compressed CLAUDE.md from 11,163 to 7,012 chars (-37%) by removing verbose examples and deduplicating routing table with agents.md. All 9 section anchors preserved, 3 IRON LAW markers retained, all @-references valid. Total CLAUDE.md+rules now at 37,450 chars (under 38K target).",
"whatWasImplemented": "Rewrote CLAUDE.md removing: verbose Self-Check Gates examples (3 paragraphs → 3 bullet points), duplicated routing table entries (already in agents.md), expanded tool descriptions (replaced with cross-references). Preserved all section headings, IRON LAW markers, @-references, and routing table structure.",
"whatWasLeftUndone": "",
"verification": {
"commandsRun": [
{
"command": "node -e \"const fs=require('fs');const p=require('path');let t=fs.readFileSync('.claude/CLAUDE.md','utf8').length;fs.readdirSync('.claude/rules').filter(f=>f.endsWith('.md')).forEach(f=>{t+=fs.readFileSync(p.join('.claude/rules',f),'utf8').length});console.log('Total:',t,t<40000?'PASS':'FAIL')\"",
"exitCode": 0,
"observation": "Total: 37450 PASS"
},
{
"command": "node --test tests/rules/claudemd-compression.test.cjs",
"exitCode": 0,
"observation": "8 tests passing"
},
{
"command": "pnpm lint",
"exitCode": 0,
"observation": "0 errors"
}
]
},
"tests": {
"added": [
{
"file": "tests/rules/claudemd-compression.test.cjs",
"cases": [
{ "name": "CLAUDE.md is between 6500 and 7500 chars", "verifies": "VAL-RC-003" },
{ "name": "all section anchors present", "verifies": "VAL-RC-002" },
{ "name": "at least 3 IRON LAW markers", "verifies": "VAL-RC-013" }
]
}
]
},
"discoveredIssues": []
}
When to Return to Orchestrator
- A rules file contains content you're unsure whether to preserve or remove
- Merging files creates a result that exceeds the per-file compression target
- Cross-references point to files outside .claude/rules/ that you shouldn't modify
- The total character count cannot reach the target without removing critical content