agent-context-generator

Agent Context Generator

What You'll Do

• 🔍 Inventory the repository's structure, capture a .gitignore-aware tree output, and record automation entry points (preferring just/make tasks when available)
• 🧭 Capture coding conventions, directory ownership, testing expectations, and review workflows so future agents can navigate confidently
• 🧩 Produce an AGENTS.md file following the opinionated section order below, honoring scope rules for nested directories
• ✅ Embed universal wrap-up tasks: ensure the README is updated after significant code changes and summarize changes per conventional commits while resolving any open questions with the developer

Phase 1 · Understand the Repository

1. Check for existing AGENTS.md
   • Use find alternative (glob or repo tree) to discover current files. Determine scope inheritance so you can update or extend instead of duplicating.
2. Read Core Docs
   • Skim README.md, CONTRIBUTING.md, and other onboarding docs for project philosophy, setup, and workflows.
   • If docs/ or documentation/ exists, scan for architectural or process references worth surfacing.
3. Survey Project Layout
   • Note primary directories, languages, build targets, and ownership (e.g., "src/ui maintained by Frontend team").
   • Check for plans/, docs/, or other knowledge directories. Flag must-read files (ADR indexes, architecture overviews, runbooks) to reference later in AGENTS.md.
4. Build a Git-aware Tree
   • Use the tree command with the --gitignore flag (tree ≥ 2.0) so ignored paths stay hidden: tree --gitignore -a -L 3 > tmp/tree.txt.
   • If your tree build lacks --gitignore, run tree -a -L 3 --prune and manually prune any ignored directories noted in .gitignore, or install an updated version via your package manager.
   • Capture or trim the output before placing it in AGENTS.md (focus on the top 2–3 levels, and note when you omitted details for brevity).
5. Identify Automation Runners
   • If Justfile exists, run just --list (or just --list --unsorted for extra notes).
   • If Makefile exists (and just does not), run make help or inspect phony targets for canonical tasks.
   • Record which commands are recommended for linting, testing, building, syncing data, etc. Link the definitive task names you surface in your notes for inclusion later.
6. Catalog Tooling & Environment
   • List required runtimes, package managers, env vars, secrets handling, and local services.
   • Note down any .env.example, config/, or secrets documentation that agents must review.
7. Clarify Testing & Quality Gates
   • Identify test suites, coverage expectations, linting, formatting, and CI workflows.
8. Resolve Ambiguities Early
   • Whenever conventions, ownership, or workflows seem unclear, prompt the developer with focused questions before drafting the guide.
   • Ask explicitly whether existing plans/ or documentation directories are authoritative or stale, and clarify what canon to reference.