---
name: ao-housekeeping
description: "Project hygiene: validate ao consistency, clean clutter, align docs, check git, update ignores."
category: core
invokes: [ao-state, ao-docs, ao-task, ao-usage]
invoked_by: []
state_files:
  read: [issues/events.jsonl, issues/active.jsonl, focus.json, memory.md]
  write: [focus.json]
reference: [REFERENCE.md]
---

# 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. **Verify ao consistency** → run `ao rebuild` to detect drift
2. **Validate issue health** → use `ao ls` to surface blocked/stale issues
3. **Clean clutter** → remove temp files, fix ignores

---

## ao Consistency Check ⚡ (Auto-Run)

**Runs automatically by default.** Verifies the JSONL store is consistent.

**Procedure:**
1. Run `ao rebuild` — rebuilds `active.jsonl` from `events.jsonl`
2. Check for any reported errors or drift warnings
3. Count active issues: `ao ls | wc -l`
4. Spot-check a few issues: `ao ls --limit 5`
5. Report summary to user

---

## Hygiene Checks

### 1. Issue Health Review
- Run `ao ls --status blocked` — review blocked issues
- Run `ao ls --status in_progress` — check for stale in-progress issues
- Prompt to triage issues with `priority: backlog` that are > 2 weeks old via `ao ls priority:backlog`

### 2. Schema Validation
Run `ao rebuild` — this rebuilds active.jsonl from events.jsonl and ensures structural integrity. Any invalid events are reported.

### 4. Clutter Detection
Find generated/stale markdown outside `.agent/ops/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

### 9. Instruction File Size Analysis ⚠️

**Large instruction files waste context tokens and slow agent initialization.**

**Target files and thresholds:**

| File Pattern | Max Size | Location |
|--------------|----------|----------|
| `copilot-instructions.md` | 15KB | `.github/` |
| `AGENTS.md` | 10KB | Root or `.github/` |
| `CLAUDE.md` | 10KB | Root |
| State files (`*.md`) | 5KB | `.agent/ops/` (except issues/) |

**Analysis procedure:**

```bash
# PowerShell
Get-ChildItem -Path ".github/copilot-instructions.md","AGENTS.md","CLAUDE.md" -ErrorAction SilentlyContinue | 
  ForEach-Object { "{0}: {1:N1}KB" -f $_.Name, ($_.Length/1KB) }

# Bash
for f in .github/copilot-instructions.md AGENTS.md CLAUDE.md; do
  [ -f "$f" ] && echo "$f: $(du -k "$f" | cut -f1)KB"
done
```

**Warning output format:**

```markdown
## Instruction File Size Warnings

| File | Size | Threshold | Status |
|------|------|-----------|--------|
| copilot-instructions.md | 22KB | 15KB | ⚠️ OVER |
| AGENTS.md | 8KB | 10KB | ✅ OK |

### Recommendations

**copilot-instructions.md** (22KB, 7KB over limit):
- Extract language-specific sections to `.github/references/lang-*.md`
- Move detailed procedures to skill files
- Keep only: core principles, quick reference, links to details
```

**Configuration** (in constitution.md):

```yaml
housekeeping:
  instruction_file_limits:
    copilot_instructions_kb: 15
    agents_md_kb: 10
    claude_md_kb: 10
    state_files_kb: 5
  warn_only: true  # Never auto-modify instruction files
```

---

## Invocation

```bash
/ao-housekeeping           # Full sweep
/ao-housekeeping --dry-run # Preview only
/ao-housekeeping --fix     # Auto-fix safe issues
/ao-housekeeping issues    # Issue health check
/ao-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
