Improve Agents Md

improve-agents-md

Generate and manage AGENTS.md (rendered as CLAUDE.md) using a single base template with dynamic tooling values from tooling.yml.

Architecture

assets/
  AGENTS.md.template     # Single base template with {{VAR}} placeholders
  tooling.yml            # Per-type tooling values (package_manager, linter, etc.)
  extras/pep723.md       # Optional section injected for Python types
  templates/shared/      # Shared templates (.gitignore)
tools/
  bootstrap.py           # Entrypoint: setup, update, validate
  template_engine.py     # Reads tooling.yml, renders template, injects extras
  project_type.py        # Auto-detect project type from file indicators
  preserve_custom.py     # Backup + CLAUDE.md migration detection

Modes

setup

Generate AGENTS.md for a project:

1. Detect project type (or accept --type override)
2. Back up existing files if --force
3. Load tooling values from tooling.yml for detected type
4. Render AGENTS.md.template with tooling substitution
5. Inject extras (e.g., PEP 723 section for Python types)
6. Write rendered AGENTS.md to project root
7. Create CLAUDE.md and GEMINI.md as symlinks to AGENTS.md

update

Re-render AGENTS.md with latest template:

1. Re-detect project type (or accept --type override)
2. Preserve customizations if --force
3. Re-render AGENTS.md with current tooling values

validate

Check AGENTS.md content:

1. Verify AGENTS.md exists
2. Check for unresolved {{VAR}} placeholders
3. Verify required sections present
4. Check CLAUDE.md is a symlink to AGENTS.md
5. Warn if legacy PROJECT_AGENTS.md is present
6. Check template assets exist

Flags

Dynamic Rendering

Template variables resolved from tooling.yml:

Null values in tooling.yml become (customizable) in output.

Extras Injection

Types with extras: [pep723] in tooling.yml get the PEP 723 section injected after ## Style & Conventions.

Questionnaire

Questions only asked when tooling.yml has null values for a type:

• python-pip: Type checker (pyright/mypy/skip) + Linter (ruff/flake8/pylint)
• generic: Project type selection (maps to known type or stays customizable)
• Ambiguous detection: Primary project type confirmation

Supported Project Types

Customization Preservation

• If CLAUDE.md exists as a regular file, its content is backed up before migration
• AGENTS.md is the primary file; CLAUDE.md and GEMINI.md are symlinks
• Timestamped backup created before any destructive operation
• Legacy PROJECT_AGENTS.md is no longer created; validate warns if present