refactor-agents

name	refactor-agents
description	Refactor existing AGENTS.md to follow progressive disclosure principles
allowed-tools	Read Write Edit Grep Glob AskUserQuestion Skill

Refactor AGENTS.md

Optimize an existing AGENTS.md file using progressive disclosure principles. Extracts essentials to root, groups related instructions into sub-files, and flags content for deletion.

Step 1: Load Current State

AGENTS_FILES = Glob("**/AGENTS.md")
ROOT_AGENTS = Read("AGENTS.md")

If no AGENTS.md exists: suggest Skill("init") instead.

Step 2: Find Contradictions

Analyze ROOT_AGENTS for conflicting instructions:

Contradiction Type	Example
Version conflicts	"Use Node 18" vs "Requires Node 20"
Style conflicts	"Use tabs" vs "2-space indent"
Tool conflicts	"Use npm" vs "pnpm install"
Process conflicts	"Always write tests first" vs "Tests optional for prototypes"

For each contradiction found:

AskUserQuestion:
  question: "Found conflicting instructions: [A] vs [B]. Which should we keep?"
  options: [A, B, "Keep both with context", "Remove both"]

Step 3: Identify Essentials

Extract ONLY content that belongs in root AGENTS.md:

Keep in Root	Move to Sub-file
One-sentence project description	Detailed architecture docs
Package manager (if not npm)	Framework-specific patterns
Non-standard build/test commands	Testing conventions
Universal security rules	Component-specific rules
Links to sub-files	Verbose examples

Root target: 60-100 lines (max 200)

Step 4: Group Remaining Content

Categorize instructions into logical groups:

Category	Typical Content
conventions/typescript.md	TS strict mode, type patterns, import style
conventions/testing.md	Test structure, mocking rules, coverage
conventions/git.md	Branch naming, commit format, PR process
conventions/api.md	Endpoint patterns, error handling, auth
conventions/styling.md	CSS approach, component styling, themes

For ambiguous content:

AskUserQuestion:
  question: "Where should '[instruction]' live?"
  options: [category suggestions based on content]

Step 5: Flag for Deletion

Identify instructions that should be removed:

Flag	Reason	Example
REDUNDANT	Agent already knows	"Use meaningful variable names"
VAGUE	Not actionable	"Write clean code"
OBVIOUS	No new information	"Test your changes"
OUTDATED	No longer applies	References deprecated tools
DUPLICATE	Already stated elsewhere	Same rule in multiple places

Present flagged items for confirmation:

AskUserQuestion:
  question: "These instructions seem [redundant/vague/obvious]. Delete them?"
  options: ["Delete all", "Review each", "Keep all"]

Step 6: Generate New Structure

Create the refactored file structure:

AGENTS.md                      # Minimal root (60-100 lines)
.agents/                       # Sub-files directory
  conventions/
    typescript.md
    testing.md
    git.md
  patterns/
    [domain-specific].md

Root AGENTS.md Template

# [Project Name]

[One sentence description]

## Quick Reference

- **Stack:** [tech stack summary]
- **Build:** `[build command]`
- **Test:** `[test command]`
- **Lint:** `[lint command]`

## Conventions

See detailed guides in `.agents/conventions/`:
- [TypeScript](.agents/conventions/typescript.md)
- [Testing](.agents/conventions/testing.md)
- [Git Workflow](.agents/conventions/git.md)

## Security

- Never commit secrets or `.env` files
- [Other universal security rules]

## Before PR

\`\`\`bash
[single command that runs all checks]
\`\`\`

Step 7: Write Files

1. Backup original: mv AGENTS.md AGENTS.md.backup
2. Write new root AGENTS.md
3. Create .agents/ directory structure
4. Write each sub-file

Step 8: Verify

Report refactoring results:

## Refactoring Complete

### Before
- Root AGENTS.md: [X] lines
- Sub-files: [Y]

### After
- Root AGENTS.md: [X] lines (target: 60-100)
- Sub-files: [list with line counts]

### Changes
- Contradictions resolved: [count]
- Instructions moved: [count]
- Instructions deleted: [count]
  - Redundant: [count]
  - Vague: [count]
  - Obvious: [count]

### Backup
Original saved to: AGENTS.md.backup

Error Handling

Condition	Action
No AGENTS.md found	Suggest Skill("init")
Already minimal (<100 lines)	Ask if optimization still wanted
No contradictions found	Skip to Step 3
User cancels at any step	Preserve original, no changes