58 lines
2.8 KiB
Markdown
58 lines
2.8 KiB
Markdown
---
|
|
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`.
|