@caddis/cli 0.1.0 → 0.2.1

package/bundles/antigravity-plugin-extras/skills/agent-md-refactor/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: agent-md-refactor
+context: fork
+description: Refactor bloated agent instruction files (AGENTS.md, .cursorrules, .github/ files, etc.) to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation.
+license: MIT
+---
+
+# Agent MD Refactor
+
+Refactor bloated agent instruction files to follow **progressive disclosure principles** - keeping essentials at root and organizing the rest into linked, categorized files.
+
+**Works with:** Claude (CLAUDE.md), Cursor (.cursorrules), GitHub Copilot (.github/), Windsurf (.windsurfrules), and any agent system.
+
+---
+
+## Triggers
+
+Use this skill when:
+- "refactor my AGENTS.md" / "refactor my .cursorrules"
+- "split my agent instructions"
+- "organize my copilot instructions"
+- "my agent config is too long"
+- "progressive disclosure for my instructions"
+- "clean up my agent config"
+
+---
+
+## Quick Reference
+
+| Phase | Action | Output |
+|-------|--------|--------|
+| 1. Analyze | Find contradictions | List of conflicts to resolve |
+| 2. Extract | Identify essentials | Core instructions for root file |
+| 3. Categorize | Group remaining instructions | Logical categories |
+| 4. Structure | Create file hierarchy | Root + linked files |
+| 5. Prune | Flag for deletion | Redundant/vague instructions |
+
+---
+
+## Process
+
+### Phase 1: Find Contradictions
+
+Identify any instructions that conflict with each other.
+
+**Look for:**
+- Contradictory style guidelines (e.g., "use semicolons" vs "no semicolons")
+- Conflicting workflow instructions
+- Incompatible tool preferences
+- Mutually exclusive patterns
+
+**For each contradiction found:**
+```markdown
+## Contradiction Found
+
+**Instruction A:** [quote]
+**Instruction B:** [quote]
+
+**Question:** Which should take precedence, or should both be conditional?
+```
+
+Ask the user to resolve before proceeding.
+
+---
+
+### Phase 2: Identify the Essentials
+
+Extract ONLY what belongs in the root agent file. The root should be minimal - information that applies to **every single task**.
+
+**Essential content (keep in root):**
+| Category | Example |
+|----------|---------|
+| Project description | One sentence: "A React dashboard for analytics" |
+| Package manager | Only if not npm (e.g., "Uses pnpm") |
+| Non-standard commands | Custom build/test/typecheck commands |
+| Critical overrides | Things that MUST override defaults |
+| Universal rules | Applies to 100% of tasks |
+
+**NOT essential (move to linked files):**
+- Language-specific conventions
+- Testing guidelines
+- Code style details
+- Framework patterns
+- Documentation standards
+- Git workflow details
+
+---
+
+### Phase 3: Group the Rest
+
+Organize remaining instructions into logical categories.
+
+**Common categories:**
+| Category | Contents |
+|----------|----------|
+| `typescript.md` | TS conventions, type patterns, strict mode rules |
+| `testing.md` | Test frameworks, coverage, mocking patterns |
+| `code-style.md` | Formatting, naming, comments, structure |
+| `git-workflow.md` | Commits, branches, PRs, reviews |
+| `architecture.md` | Patterns, folder structure, dependencies |
+| `api-design.md` | REST/GraphQL conventions, error handling |
+| `security.md` | Auth patterns, input validation, secrets |
+| `performance.md` | Optimization rules, caching, lazy loading |
+
+**Grouping rules:**
+1. Each file should be self-contained for its topic
+2. Aim for 3-8 files (not too granular, not too broad)
+3. Name files clearly: `{topic}.md`
+4. Include only actionable instructions
+
+---
+
+### Phase 4: Create the File Structure
+
+**Agent-specific directory conventions:**
+
+| Agent | Root File | Linked Files Directory |
+|-------|-----------|----------------------|
+| Claude | `CLAUDE.md` or `AGENTS.md` | `.claude/` or `docs/agent/` |
+| Cursor | `.cursorrules` | `.cursor/` or `docs/cursor/` |
+| GitHub Copilot | `.github/` (any filename) | `.github/` |
+| Windsurf | `.windsurfrules` | `.windsurf/` or `docs/windsurf/` |
+| Generic | `AGENTS.md` | `docs/agent-instructions/` |
+
+**Output structure example (Claude):**
+```
+project-root/
+├── CLAUDE.md                     # Minimal root with links
+└── .claude/                      # Linked instruction files
+    ├── typescript.md
+    ├── testing.md
+    ├── code-style.md
+    ├── git-workflow.md
+    └── architecture.md
+```
+
+**Output structure example (Cursor):**
+```
+project-root/
+├── .cursorrules                  # Minimal root with links
+└── .cursor/                      # Linked instruction files
+    ├── typescript.md
+    ├── testing.md
+    └── code-style.md
+```
+
+**Output structure example (GitHub Copilot):**
+```
+project-root/
+└── .github/
+    ├── agent-instructions.md     # Root file (name it whatever you want)
+    ├── typescript.md             # Linked instruction files
+    ├── testing.md
+    └── code-style.md
+```
+
+**Root file template:**
+```markdown
+# Project Name
+
+One-sentence description of the project.
+
+## Quick Reference
+
+- **Package Manager:** pnpm
+- **Build:** `pnpm build`
+- **Test:** `pnpm test`
+- **Typecheck:** `pnpm typecheck`
+
+## Detailed Instructions
+
+For specific guidelines, see:
+- [TypeScript Conventions]({linked-files-dir}/typescript.md)
+- [Testing Guidelines]({linked-files-dir}/testing.md)
+- [Code Style]({linked-files-dir}/code-style.md)
+- [Git Workflow]({linked-files-dir}/git-workflow.md)
+- [Architecture Patterns]({linked-files-dir}/architecture.md)
+```
+
+**Each linked file template:**
+```markdown
+# {Topic} Guidelines
+
+## Overview
+Brief context for when these guidelines apply.
+
+## Rules
+
+### Rule Category 1
+- Specific, actionable instruction
+- Another specific instruction
+
+### Rule Category 2
+- Specific, actionable instruction
+
+## Examples
+
+### Good
+\`\`\`typescript
+// Example of correct pattern
+\`\`\`
+
+### Avoid
+\`\`\`typescript
+// Example of what not to do
+\`\`\`
+```
+
+---
+
+### Phase 5: Flag for Deletion
+
+Identify instructions that should be removed entirely.
+
+**Delete if:**
+| Criterion | Example | Why Delete |
+|-----------|---------|------------|
+| Redundant | "Use TypeScript" (in a .ts project) | Agent already knows |
+| Too vague | "Write clean code" | Not actionable |
+| Overly obvious | "Don't introduce bugs" | Wastes context |
+| Default behavior | "Use descriptive variable names" | Standard practice |
+| Outdated | References deprecated APIs | No longer applies |
+
+**Output format:**
+```markdown
+## Flagged for Deletion
+
+| Instruction | Reason |
+|-------------|--------|
+| "Write clean, maintainable code" | Too vague to be actionable |
+| "Use TypeScript" | Redundant - project is already TS |
+| "Don't commit secrets" | Agent already knows this |
+| "Follow best practices" | Meaningless without specifics |
+```
+
+---
+
+## Execution Checklist
+
+```
+[ ] Phase 1: All contradictions identified and resolved
+[ ] Phase 2: Root file contains ONLY essentials
+[ ] Phase 3: All remaining instructions categorized
+[ ] Phase 4: File structure created with proper links
+[ ] Phase 5: Redundant/vague instructions removed
+[ ] Verify: Each linked file is self-contained
+[ ] Verify: Root file is under 50 lines
+[ ] Verify: All links work correctly
+[ ] Verify: Agent-specific conventions followed
+```
+
+---
+
+## Anti-Patterns
+
+| Avoid | Why | Instead |
+|-------|-----|---------|
+| Keeping everything in root | Bloated, hard to maintain | Split into linked files |
+| Too many categories | Fragmentation | Consolidate related topics |
+| Vague instructions | Wastes tokens, no value | Be specific or delete |
+| Duplicating defaults | Agent already knows | Only override when needed |
+| Deep nesting | Hard to navigate | Flat structure with links |
+
+---
+
+## Examples
+
+### Before (Bloated Root)
+```markdown
+# AGENTS.md
+
+This is a React project.
+
+## Code Style
+- Use 2 spaces
+- Use semicolons
+- Prefer const over let
+- Use arrow functions
+... (200 more lines)
+
+## Testing
+- Use Jest
+- Coverage > 80%
+... (100 more lines)
+
+## TypeScript
+- Enable strict mode
+... (150 more lines)
+```
+
+### After (Progressive Disclosure - Claude)
+```markdown
+# CLAUDE.md
+
+React dashboard for real-time analytics visualization.
+
+## Commands
+- `pnpm dev` - Start development server
+- `pnpm test` - Run tests with coverage
+- `pnpm build` - Production build
+
+## Guidelines
+- [Code Style](.claude/code-style.md)
+- [Testing](.claude/testing.md)
+- [TypeScript](.claude/typescript.md)
+```
+
+### After (Progressive Disclosure - Cursor)
+```markdown
+# .cursorrules
+
+React dashboard for real-time analytics visualization.
+
+## Commands
+- `pnpm dev` - Start development server
+- `pnpm test` - Run tests with coverage
+- `pnpm build` - Production build
+
+## Guidelines
+- [Code Style](.cursor/code-style.md)
+- [Testing](.cursor/testing.md)
+- [TypeScript](.cursor/typescript.md)
+```
+
+### After (Progressive Disclosure - GitHub Copilot)
+```markdown
+# Agent Instructions
+
+React dashboard for real-time analytics visualization.
+
+## Commands
+- `pnpm dev` - Start development server
+- `pnpm test` - Run tests with coverage
+- `pnpm build` - Production build
+
+## Guidelines
+- [Code Style](.github/code-style.md)
+- [Testing](.github/testing.md)
+- [TypeScript](.github/typescript.md)
+```
+
+---
+
+## Verification
+
+After refactoring, verify:
+
+1. **Root file is minimal** - Under 50 lines, only universal info
+2. **Links work** - All referenced files exist
+3. **No contradictions** - Instructions are consistent
+4. **Actionable content** - Every instruction is specific
+5. **Complete coverage** - No instructions were lost (unless flagged for deletion)
+6. **Self-contained files** - Each linked file stands alone
+7. **Agent conventions followed** - Directory structure matches agent expectations
+
+---