espennilsen/agents-md-manager

AGENTS.md Manager

Maintain AGENTS.md project context files across all ~/Dev projects.

Available Operations

1. Audit — Cross-project health check

Scan all projects and report AGENTS.md / .pi/ / td status:

# Use the project_init tool in batch mode

Use project_init with action: "batch" to get a full overview. Then provide a table:

| Project | Stack | AGENTS.md | .pi/ | td | Status | |---------|-------|-----------|------|-----|--------|

Flag projects that:

• Have code but no AGENTS.md (needs init)
• Have AGENTS.md but no .pi/ or td (partially set up)
• Are fully ready ✅

2. Generate — Create AGENTS.md for a project

Use project_init with action: "detect" first to preview, then action: "init" to create.

After auto-generation, review and enhance the output by:

• Reading README.md for project description and purpose
• Checking package.json scripts for accurate quick-start commands
• Looking at src/ structure for meaningful directory descriptions
• Adding project-specific conventions found in configs (ESLint rules, Prettier settings)
• Adding deployment info if found (Dockerfile, CI workflows, deploy scripts)

3. Update — Refresh specific sections

When a project has changed significantly:

1. Read current AGENTS.md
2. Run project_init with action: "detect" to get fresh stack profile
3. Compare detected state against documented state
4. Update only stale sections, preserving manual edits in other sections

Key sections to check:

• Stack: Dependencies changed?
• Quick Start: New scripts added/removed?
• Directory Layout: New top-level dirs?
• Conventions: Linting/formatting tools changed?
• Key Files: New config files?

Use the edit tool for surgical updates — don't rewrite the entire file.

4. Sync Check — Detect drift

Compare AGENTS.md claims against reality:

# Check if referenced directories exist
# Verify scripts in package.json match what's documented
# Confirm referenced config files exist
# Check if new top-level dirs aren't documented

For each project with AGENTS.md:

1. Read the AGENTS.md
2. Run project_init detect to get current profile
3. Compare:
   • Listed directories vs actual directories
   • Documented scripts vs actual package.json scripts
   • Referenced config files vs files on disk
   • Stack description vs detected stack
4. Report drift items with suggested fixes

5. Lint — Quality check

Check AGENTS.md files for common issues:

• Missing sections: No quick start, no directory layout
• Stale paths: References to directories/files that don't exist
• Generic content: Boilerplate without project-specific detail
• Missing td mandate: No task management section
• No description: Missing project purpose/overview
• Broken commands: Script references that don't match package.json

Report with severity:

• 🔴 Critical: Missing or empty AGENTS.md in active project
• 🟡 Important: Stale content, missing key sections
• 🔵 Minor: Formatting, generic descriptions

Batch Mode

When operating on multiple projects:

1. Start with audit to identify which projects need attention
2. Process projects by priority (active first, stale/archived last)
3. Show a summary of changes before applying
4. Always ask before writing to files

Integration with Other Tools

• Use project_init for stack detection and initial generation
• Use workon to switch context when doing deep updates
• Use td to track large-scale AGENTS.md update campaigns
• Use read and edit for surgical file modifications