# Agent Ops Housekeeping

> Comprehensive project hygiene: archive issues, validate schema, clean clutter, align docs, check git, update ignores.

- Skill: `majiayu000/agent-ops-housekeeping` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/agent-ops-housekeeping`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/agent-ops-housekeeping/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/agent-ops-housekeeping

---


# Housekeeping

Keep the project clean, organized, and maintainable.

**Reference**: See [REFERENCE.md](REFERENCE.md) for detailed procedures, CLI commands, gitignore checklist.

---

## Core Tasks (Always Run)

1. **Archive completed issues** → history.md
2. **Regenerate index.md** → compact issue summary
3. **Validate issue schema** → fix malformed issues
4. **Clean clutter** → remove temp files, fix ignores

---

## Issue Archival ⚡ (Auto-Run)

**Runs automatically by default.** Use `--dry-run` to preview.

**Procedure:**
1. Scan ALL issue files including splits (`*.md`, `*-*.md`)
2. Find issues with status: `done`, `cancelled`, `dropped`, `wont-fix`
3. Append to `history.md` under `## Archived [YYYY-MM-DD]`
4. Remove from source file
5. If history.md > 500 lines, rotate to `archives/history-YYYYMMDD.md`
6. Check if split files can be compacted

---

## Hygiene Checks

### 1. Issue File Management
- **Split** files > 100K into numbered files
- **Compact** split files when combined < 80K
- Keep OLDEST in numbered files, NEWEST in main

### 2. Backlog Triage
Prompt to prioritize items with `status: needs_triage` or > 2 weeks old.

### 3. Schema Validation
Validate against `.github/reference/issue-schema.json`:
- Required: `id`, `type`, `priority`, `title`, `status`
- ID format: `{TYPE}-{NNNN}@{HHHHHH}`
- Auto-fix: missing status, wrong priority file

### 4. Clutter Detection
Find generated/stale markdown outside `.agent/docs/`.

### 5. README Alignment
Check if README reflects actual project state.

### 6. Git Health
- Uncommitted changes count
- Untracked files
- Stale branches (30+ days)
- Large uncommitted files

### 7. Gitignore Audit
Check for missing ignores: node_modules, .venv, dist, build, .env

### 8. State File Health
- Required files exist
- Valid YAML frontmatter
- No orphaned references

---

## Invocation

```bash
/agent-housekeeping           # Full sweep (archives automatically)
/agent-housekeeping --dry-run # Preview only
/agent-housekeeping --fix     # Auto-fix safe issues
/agent-housekeeping issues    # Just archival
/agent-housekeeping git       # Just git health
```

---

## When to Run

- After completing milestone/feature
- Before starting new major work
- Weekly maintenance
- When context feels cluttered
- Before handoff