Md setup maintainer

MD Setup Maintainer

Overview

Maintain a small, durable Markdown control plane for agent work in a repository. Keep root agent instructions lean, keep active memory factual and current, move old history into archive, and preserve task-specific guidance in referenced files.

Default Workflow

1. Start in audit mode. Do not edit files until the user explicitly asks to apply the recommended cleanup.
2. Inspect the repo root for AGENTS.md, CLAUDE.md, MEMORY.md, ARCHIVE.md, references/, and resources/.
3. Run the audit helper:

python3 /path/to/md-setup-maintainer/scripts/md_setup_audit.py /path/to/repo --json-out /tmp/md-setup-audit.json

4. Read references/cleanup-rules.md when you need the exact classification rules, section templates, or weekly maintenance checklist.
5. Present findings before changes: missing files, bloat, misplaced rules, stale memory, archive candidates, broken references, and a file-by-file apply plan.
6. Apply changes only after explicit approval such as "proceed", "apply the cleanup", or an equivalent direct instruction.

Audit Rules

Use these defaults unless the repo already documents stricter local policy:

• Keep root agent files at 200-250 lines when possible; treat 300 lines as the hard maximum.
• Keep MEMORY.md at or below 150 lines.
• Treat ARCHIVE.md as append-only historical context that is not loaded at session start.
• Preserve existing filename casing when a file already exists; create missing root support files as MEMORY.md and ARCHIVE.md.
• If neither AGENTS.md nor CLAUDE.md exists, recommend creating AGENTS.md as the portable default root instruction file.
• If both AGENTS.md and CLAUDE.md exist, maintain both and synchronize only agent-agnostic rules. Keep tool-specific behavior in the relevant file.
• Scan root agent files, memory/archive files, local MD files linked from root files, and MD files under references/ or resources/. Do not scan every Markdown file unless the user asks.

Apply Mode

Before editing, protect the user's work:

• If the target is inside a git repo, run git status --short and inspect relevant diffs. Never overwrite unrelated user changes.
• If the target is not inside a git repo, create timestamped .bak copies of every Markdown file you will modify before editing.
• Create missing files from the lean templates in references/cleanup-rules.md.
• Move task-specific detail out of root files into references/ only when the root file becomes clearer and the pointer is enough for session start.
• Compress memory entries to one or two sentences. Archive stale status, completed work, old decisions, and long history instead of raising the memory ceiling.
• Finish with a concise summary of every changed file and why it changed.

Classification

Use the primary purpose of an entry to decide where it belongs:

• Put prescriptive behavior in root agent files or task-specific references. Examples include "always", "never", "before doing X", "do not", "ask before", and process rules.
• Put changeable facts, statuses, active projects, recurring tasks, and personal or repo facts in MEMORY.md.
• Put completed work, old statuses, replaced decisions, inactive projects, and long history in ARCHIVE.md.
• Put instructions needed only for a specific task in a referenced Markdown file and keep a one-line pointer in the root file.

Weekly Maintenance

For weekly use, run the audit helper, review the report, and apply only the accepted recommendations. A suitable automation prompt is:

Use $md-setup-maintainer to audit this repository's agent Markdown setup. Report root instruction bloat, stale memory, missing setup files, broken references, archive candidates, and misplaced rules or facts. Do not edit files until I approve the cleanup plan.

Do not create recurring automations from this skill by default. If the user asks for scheduling, provide a safe automation prompt or use the host application's automation system according to its own rules.

Expected Output

Return an audit-first response with:

• Executive summary.
• Findings grouped by severity.
• Recommended file moves or creations.
• Apply plan with safety notes.
• Test or verification steps when changes are applied.