| name | markdown-compression |
| description | Safely compresses narrative Markdown using deterministic compaction plus validator checks. Only for allowlisted non-parser-sensitive artifacts. |
Markdown Compression
Use this only for safe narrative Markdown. This is not a general rewrite tool.
Safe Targets
README.md
docs/**/*.md
specs/<feature>/research.md
specs/<feature>/analysis-report.md
specs/<feature>/manual-test.md
Blocked Targets
project-instructions.md, AGENTS.md, CLAUDE.md
- all workflow, agent, instruction, and wrapper Markdown under
.github/, .agents/, .claude/, .windsurf/, .opencode/, .codex/
specs/prd.md, specs/sad.md, specs/dod.md, specs/project-plan.md, specs/adrs/*.md, specs/plan/*.md
- feature-workspace parser-sensitive artifacts:
spec.md, plan.md, tasks.md, qc-report.md, checklists/*.md, autopilot-log.md
Process
- Run
node scripts/compress-markdown.mjs --check <path> to confirm the path is allowlisted and validator-safe.
- For preview only, run
node scripts/compress-markdown.mjs --stdout <path>.
- To write the compressed file, run
node scripts/compress-markdown.mjs <path>.
- The script creates
<name>.original.md once, then preserves it on later runs.
- If validation fails, stop. Do not write partial output.
Validation Guarantees
The validator preserves these elements exactly:
- headings
- fenced code blocks
- inline code
- bare URLs and Markdown links
- requirement and task identifiers
- table rows
- checkbox lines
Compression Rules
- Trim filler and redundant phrasing only.
- Keep commands, paths, and structural lines exact.
- Prefer concise normal prose, not stylized shorthand, for persisted files.
Fallback
- If Node is unavailable, do not auto-compress.
- If the target is blocked, leave it unchanged and tighten the source workflow instructions instead.