---
name: agent-docs-refactor
description: Use when creating, updating, splitting, merging, rerouting, renaming, or deleting AGENTS.md and agent-docs, especially when references, child docs, or document responsibilities must change together.
---

# Agent Docs Refactor

## Overview

Use this skill to edit the root `AGENTS.md` or files under `agent-docs/`. It is the production workflow for restructuring the document tree while preserving explicit routing and single-home rule ownership.

## When to Use

- The user asks to optimize, refactor, split, merge, or rewrite AGENTS or `agent-docs`
- A rule must move from one document to another
- A new child doc must be introduced or an obsolete one removed
- Cross-references, routing text, and checklists must be updated together

## Workflow

1. Read the root `AGENTS.md` and affected child docs.
2. Read the smallest relevant references from `../agent-docs/references/`:
   - `root-agents-template.md`
   - `rule-doc-template.md`
   - `inventory-doc-template.md`
   - `child-doc-template.md`
   - `linking-patterns.md`
   - `refactor-checklist.md`
3. Decide the target shape before editing:
   - keep as one rule doc
   - split rule doc from inventory
   - merge overlapping docs
   - delete obsolete leaf doc
4. Apply edits so that:
   - the root remains the starting point
   - every active child doc remains reachable from the root
   - each rule has one authoritative home
   - stale references are removed in the same change
5. If the change alters routing, authority ownership, or document shape, hand off to `agent-docs-consistency`.
6. If the change alters claims that depend on repository facts, hand off to `agent-docs-repo-alignment`.
7. Finish with `agent-docs-verification`.

## Refactor Rules

- Prefer the smallest change that reduces ambiguity or maintenance cost.
- Do not split only for symmetry.
- Do not split when one short document already governs one clear topic.
- Do not keep a child doc that is no longer reachable from the root.
- Do not leave topic-specific rules in the root file once a narrower child doc exists.
- Do not let inventory docs become policy docs.
- Do not add an intermediate file that only repeats links without adding scope or decision logic.
- Do not create a new child doc unless it reduces ambiguity, repetition, or maintenance cost.
- In monorepos, keep common constraints in the root file and keep project-specific rules in documents near that project instead of the general rules layer.
- Do not mix general agent-doc governance with business rules, product instructions, or end-user documentation.
- Titles and filenames should state purpose directly.
- Each opening should explain purpose, trigger, and that the document must be followed in scope.
- Use repository-relative paths in backticks when referencing repo files from AGENTS or `agent-docs`.