• 🔍 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

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.

Outcome: A structured notes list describing layout, tooling, commands, testing, release process, documentation references, pending questions, and update expectations.

1. Header — Title + short purpose statement.
2. Quick Facts — Table or bullet summary (languages, package manager, key scripts, CI).
3. Repository Tour — High-level directory map with responsibilities and ownership hints.
4. Tooling & Setup — Required runtimes, package managers, environment variables, secrets.
5. Common Tasks — Lint/test/build/deploy commands. Prefer listing

   just

   recipes first, then

   make

   targets, then raw commands.
6. Testing & Quality — When and how to run tests, linting, formatting, coverage, and CI expectations.
7. Workflow Expectations — Branching model, review norms, feature flagging, deployment cadence.
8. Documentation Duties — When to update

   README.md

   , architecture diagrams, or other docs.
9. Finish the Task — Mandatory wrap-up checklist for every agent task.

services/api/

Scope: Root project (applies to all subdirectories unless overridden)

• Primary language:
• Package manager:
• Entrypoints:
• CI/CD:

• path/

  — description & owner

• Install instructions (per OS)
• Required environment variables (with purpose)
• Secrets management notes

• just <task>

  — what it does (preferred)

• make <target>

  — what it does
• Raw command fallback when automation missing

• Unit/integration test commands
• Lint/format commands
• Coverage expectations & thresholds
• CI status command or dashboard link

• Branch naming and review rules
• Feature toggles or release cadence
• Any approval or ticket linkage requirements

• Update

  README.md

  when features, setup steps, or developer ergonomics change materially
• List other docs to refresh (architecture, ADRs, etc.)

• Update relevant docs (&

  README.md

  if significant changes landed)
• Summarize changes in conventional commit format (e.g.,

  feat: ...

  ,

  fix: ...

  )

undefined

Scope: ./path/to/directory (inherits root AGENTS.md unless noted)

• What lives here
• Who owns it (team/contact)

• file_or_folder/

  — why it matters

• just <task>

  /

  make <target>

  / command snippets scoped to this directory

• Specific tests, linters, or data fixtures for this directory

• Docs or runbooks to reference
• Open questions captured during discovery

Only create these per-directory guides after confirming with the developer which areas need dedicated context and what information should be emphasized.

**Writing Notes:**
- Keep language direct and actionable. Agents should follow commands verbatim.
- Mention the preferred order of operations (e.g., "Always run `just format` before opening a PR").
- When referencing scripts, include relative paths so agents can jump quickly (e.g., ``scripts/bootstrap.sh``).
- Incorporate a trimmed `tree --gitignore` snapshot (or link to the saved artifact) so readers grasp layout quickly.
- In the Repository Tour, highlight where `plans/`, `docs/`, design docs, or ADRs live if present.
- Call out any unanswered questions as action items, and confirm with the developer before creating any per-directory AGENTS overlays.
- If the project mixes languages/platforms, add subsections per component but keep global guidance first.

---

1. Self-review
   • Does the file respect AGENTS scope rules? (Mention inheritance or overrides.)
   • Are all critical commands documented, especially automation entry points?
   • Is the README update expectation explicit?
   • Did you obtain developer approval before adding any per-directory AGENTS files, and is that approval reflected in the write-up?
   • Does the "Finish the Task" checklist include the conventional commit summary reminder?
2. Formatting
   • Ensure headings use Title Case, commands are wrapped in backticks, and lists are concise.
   • Keep sections under ~8 bullets unless a table is clearer.
3. Handoff Summary
   • When delivering the AGENTS.md to the user, include:
     • A short summary of major sections added/updated.
     • Confirmation that README and conventional commit reminders are present.
     • Any follow-up suggestions (e.g., missing tests or outdated scripts).