alchemiststudiosdotai/agents-md-mapper

AGENTS.md Mapper

Overview

Maintain a concise, current AGENTS.md for a repository as the codebase changes. Treat the file as a navigational map for future coding agents: show where to start, where important things live, how to validate changes, and which deeper docs outrank the map.

When to Use

• Create a new AGENTS.md for a repository that does not have one
• Refresh an existing AGENTS.md that may be stale after refactors, path moves, package splits, or architecture changes
• Update the map after tooling, tests, CI, docs, or ownership signals changed
• Point AGENTS.md at new architecture docs, runbooks, or generated references that became the source of truth
• Add lightweight checks that detect drift between AGENTS.md and repository reality

Core Contract

1. Keep the map compact

• Prefer roughly 90 to 100 lines
• Prefer bullets over paragraphs
• Prefer concrete paths and commands over abstract advice
• Link to deeper docs instead of copying them

2. Treat repository evidence as the source of truth

• Read the repository tree before writing claims about structure
• Read actual config files before listing commands
• Read CI workflows before describing validation
• Read docs and architecture references before summarizing boundaries
• Read recent git history before carrying forward old paths or retired modules

3. Optimize for agent legibility

• Surface entry points, domain boundaries, and validation commands first
• Make the navigation order obvious
• Remove stale or duplicated sections aggressively
• Normalize heading order so future updates stay mechanical

4. Omit unsupported detail

• If evidence is weak, omit the claim
• If a detail is volatile, point to its source doc instead of embedding it
• If two docs disagree, prefer the one supported by current code and CI

Inputs to Inspect

Inspect repository evidence, not guesswork:

• Current top-level tree and major subdirectories
• Key top-level files such as README, pyproject.toml, package.json, Cargo.toml, Makefile, justfile, or task runner configs
• Existing AGENTS.md, if present
• ARCHITECTURE.md, docs/, runbooks, plans, references, and generated indexes
• CI workflows and automation config
• Recent git history, especially merges, path renames, retired modules, and tooling changes
• Ownership signals such as CODEOWNERS, package manifests, and boundary-enforcement config

Workflow

Step 1: Discover repository shape

• Collect the top-level tree and major subdirectories
• Identify package roots, module roots, and major domain folders
• Locate docs indexes, architecture docs, and runbooks
• Capture build, test, lint, and run entrypoints from real config files

Step 2: Read the current map and deeper docs

• Open AGENTS.md if it exists
• Open the main onboarding docs first: README, architecture docs, and docs indexes
• Open the exact files that define task runner commands and CI gates
• Note which docs already serve as the system of record

Step 3: Inspect recent change signals

• Review recent git history for renamed paths, new packages, retired directories, and workflow changes
• Check whether new docs or generated references replaced older explanations
• Check whether CI or task runners added or removed validation steps

Step 4: Compare map versus reality

• Verify that listed paths still exist
• Verify that listed commands still exist and still match task runner or CI usage
• Verify that architecture or package boundaries still match current layout
• Verify that linked docs still exist and remain the best source of truth

Step 5: Rewrite for compression and clarity

• Keep only high-value navigational content
• Collapse repeated guidance into one canonical section
• Replace prose-heavy explanations with stable file paths and exact commands
• Remove outdated paths, retired tools, and stale historical detail

Step 6: Validate before finalizing

• Re-check every path and command
• Remove duplicate or unsupported claims
• Confirm the file remains short, scan-friendly, and grounded in current evidence

What to Put in AGENTS.md

Include these sections when repository evidence supports them:

• Project overview
• Where to start
• Repository map
• Build, test, lint, and run commands
• Architecture or package boundaries
• Key docs and sources of truth
• Change rules or contribution guardrails
• Validation checklist

Exclude these unless they directly change navigation or implementation behavior:

• Long architectural essays
• Full style guides already documented elsewhere
• Exhaustive dependency lists
• Historical detail that does not affect current navigation
• Issue triage policy that does not change implementation work

Decision Rules

• If a section grows past a few bullets, move detail to docs/ or another source doc and link to it
• If commands differ between docs and CI, prefer the version backed by current config
• If the repository already has a strong docs index, make AGENTS.md point to it rather than restating it
• If a repo has no evidence for ownership or architecture boundaries, do not invent them

Output Modes

Produce one of these outputs:

• A fresh AGENTS.md
• A focused patch for the existing AGENTS.md

Use the compact outline in references/agents-md-outline.md as a starting point when the repository supports those sections.

Validation Checklist

• Every listed path exists
• Every listed command is defined in current repo config or CI
• Every linked source-of-truth doc exists
• Stale headings and duplicate sections are removed
• The file stays compact and navigable
• No secrets or environment values appear in the file

Recommended Follow-Up Checks

When automation is requested, add lightweight drift checks such as:

• Fail if a linked path in AGENTS.md no longer exists
• Fail if a listed command disappears from CI or task runner config
• Flag missing references to new top-level domains after major tree changes
• Flag stale sections after large refactors or package moves

Success Criteria

Consider the skill successful when:

• AGENTS.md is short and easy to scan
• Every listed path and command matches the current repository
• The file points to deeper sources of truth instead of copying them
• Stale guidance is removed
• Another coding agent can use AGENTS.md as a reliable repository map