Meta Maintain Config

---
name: meta-maintain-config
description: 'Use when creating or editing skills, rules, agents, or hooks under `.claude/`. Also when AI knowledge has drifted from project patterns, a new Claude Code feature lands, or syncing artifacts to current state. Modes: `create`, `audit`, `refresh`, `review`, `research <topic>`.'
user-invocable: true
argument-hint: "create | audit | refresh | review | research topic"
disable-model-invocation: true
triggers:
  - "maintain the config"
  - "update the rules"
  - "update the skills"
  - "ai config drift"
  - "add a skill"
  - "edit the agent"
---

# AI Configuration Maintenance

Keep `.claude/` directory living knowledge base. Stay current with project + AI tooling best practices.

**Read `.claude/rules/meta-ai-config.md` first** — defines conventions, budget constraints, anti-patterns this skill enforces.

## Modes

### `create` — New Artifact

1. **Discover + Research** — Invoke canonical multi-agent research primitive from `/hex-plan` (Phases 1-2). Spawn workers parallel:
   - an explorer pass (1-2): existing `.claude/` patterns, conventions, cross-references, neighbors of artifact
   - researcher pass (1-3, split by axis): Claude Code docs (`code.claude.com/docs`), domain best practices, community patterns for artifact topic

   Persist substantial findings as `.agents/research/research_[topic].md` for reuse. See `/hex-plan` "Research as a Reusable Primitive".

2. **Draft** — Follow `meta-ai-config.md` conventions:
   - Respect context budget (<200 lines rules, <500 lines skills)
   - Use `paths:` scoping for rules unless truly global
   - Skills: write description as "what + when to use" (max 1024 chars)
   - Use progressive disclosure — SKILL.md overview, reference files for detail
   - Add `disable-model-invocation: true` for action skills with side effects

3. **Integrate** — Update AGENTS.md tables, meta-rule inventory

4. **Validate** — Run audit checks (see below)

### `audit` — Check All Artifacts

**Context budget audit:**
- AGENTS.md under 280 lines?
- Each global rule under 200 lines?
- Count global rules — too many degrades performance
- Skill descriptions total within 2% context budget?

**Structural audit:**
- Every SKILL.md has `name` + `description`?
- No `allowed-tools` in skill frontmatter?
- All persona skills have `user-invocable: true`?
- Hook scripts executable?

**Dead glob audit:**
- For each scoped rule, do `paths:` patterns match existing files?
- After directory renames, glob patterns silently fail — verify with: `find . -path "pattern" | head -1`

**Cross-reference audit:**
- Rules referencing other rules → targets exist?
- Skills referencing rules → correct filenames?
- Agents referencing rules → still valid?

**Duplication audit:**
- Same instruction in AGENTS.md AND rule? (single source of truth)
- Same domain knowledge in skill AND rule? (skill for on-demand, rule for always-on)

### `refresh` — Sync AI Knowledge with Codebase

1. **Detect drift** — explorer pass:
   - Public types in `subsystem-*.md` still exist in code?
   - New modules/crates lacking subsystem rules?
   - Error variants, trait names, method signatures still match?
   - CLI commands changed (new flags, subcommands)?
   - `deny.toml` / `.licenserc.toml` changed?

2. **Research updates** — researcher pass:
   - Claude Code docs for new features (hooks, frontmatter, agents)
   - New best practices in Rust, async, testing, security
   - Check if `meta-ai-config.md` needs updating

3. **Update stale artifacts** — Read current code, update with accurate info, preserve structure

4. **Self-update** — Check if this skill (`meta-maintain-config`) or `meta-ai-config.md` outdated per research findings. Update them too.

5. **Validate** — Run `audit` mode

### `review` — AI Config Quality Review

Review recent changes to `.claude/` for quality:

1. **Context budget** — Change increase always-loaded context? Justified?
2. **Scoping** — Could this global rule be path-scoped instead?
3. **Progressive disclosure** — SKILL.md body under 500 lines? Move details to reference files?
4. **Description quality** — Skill description specific enough for auto-discovery?
5. **Anti-patterns** — Check against 8 anti-patterns in `meta-ai-config.md`
6. **Consistency** — Change follow existing artifact conventions?
7. **Reusability** — Hook more appropriate than rule? (deterministic + zero context cost)

### `catalog-sync` — Catalog Drift Review

When auditing AI config, verify `.claude/rules.md` reflects reality:

1. Every rule in `.claude/rules/*.md` has entry in `.claude/rules.md`
2. Every catalog entry resolves to real file
3. `AGENTS.md` still links to catalog (`CLAUDE.md` only forwards via `@AGENTS.md`)
4. "By concern" table reflects current development axes (add rows for new concerns; remove for retired)
5. "By auto-load path" table matches actual `paths:` frontmatter in each rule file

Run `task claude:tests` — structural tests catch most drift automatically (`test_catalog_covers_all_rules`, `test_catalog_references_resolve`, `test_context_md_points_to_catalog`). Manual review catches semantic drift (e.g., new concern worth catalog row even if no test complains).

### `research` — Deep-Dive Topic

Invoke canonical multi-agent research primitive from `/hex-plan` (Phases 1-2). No reinvent.

1. **Spawn workers parallel** — per `/hex-plan` Phase 2 axis-splitting:
   - researchers × 2-3, split by axis:
     - *Tooling axis* — Claude Code / AI tooling best practices
     - *Domain axis* — Rust patterns, OCI spec, cargo-deny, etc.
     - *Community axis* — how other projects handle this
   - explorer (optional) — ground external findings in existing `.claude/` artifacts

2. **Synthesize** → Actionable guidance. Persist as `.agents/research/research_[topic].md`
3. **Apply** → Update relevant artifacts

## Refresh Targets

| Artifact | What goes stale | Refresh trigger |
|----------|----------------|-----------------|
| `subsystem-*.md` rules | Types, paths, signatures, error variants | After refactors, new modules |
| `quality-rust.md` (+ other `quality-*.md`) | Language anti-patterns, async conventions, 2026 updates | After edition/release updates, new tooling |
| `arch-principles.md` | Design principles, ADR index, code style conventions | After new patterns, new modules |
| Persona skills | Implementation patterns, fixtures, commands | After new commands, workflows |
| `deps` | License allowlist, tool versions | After deny.toml changes |
| `AGENTS.md` | Build commands, env vars, layout | After new crates, env vars |
| `meta-ai-config.md` | Conventions, budget numbers, anti-patterns | After Claude Code releases |
| **This skill** | Modes, workflow, refresh targets | After Claude Code releases |

## Maintenance Schedule

| Frequency | Action |
|-----------|--------|
| Every feature branch | `audit` before merging AI config changes |
| Monthly | `refresh` to detect drift |
| On Claude Code update | `research "Claude Code new features"` then self-update |
| On new tool integration | `create` for tool's skill/rule, then `audit` |
| When something feels off | `review` recent changes |

## Constraints

- ALWAYS research online before creating AI artifacts
- ALWAYS run at least one research pass for domain knowledge
- ALWAYS check context budget impact (adding always-loaded context?)
- NEVER remove artifacts without checking cross-references first
- NEVER edit `settings.json` hooks without testing hook script
- Prefer hooks over rules for enforcement (deterministic + zero context cost)
- Commits use `chore:` prefix (per project convention)