Goal

Create an AGENTS.md that makes the agent effective on day 1:

• •Clear repo/workspace map
• •"Golden commands" that match CI
• •Conventions + guardrails
• •Consistent task wrap-up expectations

Supported scenarios

A) Existing repo (single git root)

• •Detect build/test/lint/format/run commands from the repo.
• •Summarize CI-required checks from .github/workflows/*.
• •Write/overwrite <repo>/AGENTS.md using the templates in references/.

B) Empty repo (or too little signal)

• •Ask the user a short questionnaire (below).
• •Create a minimal AGENTS.md with explicit TODOs (no vague placeholders).

C) Polyrepo workspace (e.g. <root>/frontend and <root>/backend are separate git repos)

• •Treat the current directory as workspace root if it is not itself a git root.
• •Detect child repos by locating .git markers under immediate subfolders.
• •Generate:
  1. •<workspace>/AGENTS.md (cross-cutting rules + repo map)
  2. •Optional: <workspace>/frontend/AGENTS.md and <workspace>/backend/AGENTS.md (repo-specific commands)

Discovery algorithm (do this, in order)

1. •Determine scope:
   • •Try git rev-parse --show-toplevel.
     • •If it succeeds, you are in scenario A.
     • •If it fails, you are in scenario B or C. Use the current directory as workspace root.
2. •Detect language/tooling per folder:
   • •.NET: .sln, *.csproj, global.json
   • •Node: package.json, lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock)
   • •Python/others: only if present; otherwise ignore.
3. •Extract "golden commands":
   • •Prefer commands found in CI or repo scripts over inventing new ones.
   • •For Node, read package.json scripts.
   • •For .NET, prefer solution/project commands that run fast and match CI.
4. •Extract CI quality gates:
   • •Inspect .github/workflows/*.yml for: build, test, lint, format, CodeQL, dependency review, SBOM/provenance attestations.
   • •Reflect them as a checklist in AGENTS.md (only what exists today).
5. •Generate AGENTS.md:
   • •Use a template from references/ and fill it with concrete commands and paths.
   • •Keep the file short (~150-200 lines). Prefer links to docs over copy-pasting.
6. •Validate:
   • •If any key command is unknown (especially "Run"/"Dev"), ask the user to provide it.
   • •Never leave "(fill in ...)" placeholders; use explicit TODO: bullets.

Questionnaire (only ask if needed)

Ask the minimum number of questions to remove ambiguity:

1. •Is this a single repo or a workspace containing multiple repos?
2. •What are the main parts? (e.g. backend .NET, frontend React)
3. •For each part:
   • •Package manager (npm/pnpm/yarn) or .NET tooling
   • •Golden commands: install/restore, build, test, lint/format, dev/run
4. •Anything special: DB migrations, codegen (OpenAPI), infra (Terraform), container runtime.

Hard rules to include in the generated AGENTS.md

• •Align with GitHub Actions: prefer commands that CI actually runs.
• •Security basics: never echo secrets; never commit secrets; avoid adding deps without approval.
• •Output expectations: summary + commands run + tests + manual verification steps.

Deliverables

• •Write the appropriate AGENTS.md file(s).
• •If polyrepo: ensure workspace AGENTS.md explains how to run commands per repo folder.
• •If you created repo-level AGENTS.md too, keep them narrower and point to workspace/global rules.

Finish with:

• •What files were created/updated (paths)
• •The key commands captured
• •Any remaining TODOs/questions for the user