# Rules Worker

> Compresses and merges CLAUDE.md and rules files to fit under the 40K character cap

- Skill: `oimiragieo/rules-worker` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oimiragieo/rules-worker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/rules-worker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: oimiragieo (https://skillmd.com/u/oimiragieo)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/oimiragieo/rules-worker

---


# 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

1. **Read the feature description carefully.** Understand exactly which files to modify, what to preserve, and what to compress/merge.

2. **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.

3. **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).

4. **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.

5. **Run tests (green).** All tests pass. Fix any failures.

6. **Verify character count.** Run the total character count script. Must be under target.

7. **Run lint and format.**
   ```
   pnpm lint
   pnpm format:check
   ```

8. **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

```json
{
  "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