Skip to content

feat(adf): add charter adf tidy command to sweep vendor file bloat back into ADF modules #23

@SmartBrandStrategies

Description

@SmartBrandStrategies

Problem

After charter adf migrate converts vendor config files (CLAUDE.md, .cursorrules, agents.md, GEMINI.md, copilot-instructions.md) into thin pointers, AI agents continue writing rules and context directly into those files. Over time, vendor files accumulate content that belongs in .ai/*.adf modules, defeating the purpose of ADF's modular context system.

Proposed Solution

New charter adf tidy command that:

  1. Scans known vendor config files for content beyond the thin pointer
  2. Extracts new content (diff against the pointer-only baseline)
  3. Classifies extracted content using the existing classifyElement pipeline (imperative/advisory/neutral, heading-based and trigger-based module routing)
  4. Routes classified content to the appropriate .adf modules
  5. Restores the thin pointer in the vendor file
  6. Reports what was moved and where

CLI Interface

# Dry run — show what would be tidied
charter adf tidy --dry-run

# Tidy all detected vendor files
charter adf tidy

# Tidy a specific file
charter adf tidy --source CLAUDE.md

# JSON output for agent consumption
charter adf tidy --format json

Output

Tidied 3 vendor files:
  CLAUDE.md: 12 items → core.adf (7), frontend.adf (3), backend.adf (2)
  .cursorrules: 4 items → core.adf (4)
  agents.md: 0 items (already clean)

Acceptance Criteria

  • Detects content beyond thin pointer markers in vendor files
  • Classifies and routes using existing classifyElement + buildMigrationPlan pipeline
  • Deduplicates against existing ADF content (Jaccard similarity, same as migrate)
  • Restores thin pointer after extraction
  • --dry-run shows plan without modifying files
  • --format json with structured output
  • Tests covering: clean file (no-op), bloated file (extract + route), dedup against existing ADF content

Dependencies

  • Reuses parseMarkdownSections, classifyElement, buildMigrationPlan from @stackbilt/adf
  • Reuses thin pointer detection from doctor command (POINTER_MARKERS constant)

Notes

This is the primitive that the pre-commit hook integration (#14 TBD) will call. Design the command to be composable — exit code 0 when clean, 1 when content was found (in --dry-run --ci mode).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions