Agents Init

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