Agents Bootstrap Layout

Goal

Make a new project "Codex-ready" in one step:

• Place skills where Codex will discover them
• Create a workspace-level AGENTS.md (and optional per-repo AGENTS.md)
• Make polyrepo workflows (frontend+backend) painless

Supported scenarios

A) Current folder is a git repo root B) Current folder is a workspace root containing multiple repos C) Current folder is empty (no git yet)

What to do

1. Determine root scope

• Try git rev-parse --show-toplevel
  • If succeeds: treat that as root
  • If fails: treat current directory as workspace root

2. Create shared skills folder (workspace scope)

• Ensure <root>/.agents/skills/ exists
• Ensure subfolders exist for:
  • agents-init
  • agents-refresh
  • agents-bootstrap-layout
• If these skills already exist elsewhere (e.g. $HOME/.agents/skills), do not duplicate; instead write short pointers in the README.

3. Polyrepo support (optional but recommended) If <root>/frontend and <root>/backend (or similar) are separate repos:

• Prefer launching Codex from <root> for cross-repo work.
• If users often launch from inside each repo, create a repo-level .agents/skills that points to <root>/.agents/skills:
  • On Unix/WSL: symlink .agents/skills -> ../../.agents/skills (adjust relative path)
  • On Windows: use symlink or junction if possible; otherwise copy.

4. Create baseline AGENTS.md files

• If <root>/AGENTS.md does not exist, create it from references/AGENTS.workspace.stub.md.
• If a git repo root exists and <repo>/AGENTS.md does not exist, create it from references/AGENTS.repo.stub.md.
• Never overwrite an existing AGENTS.md; instead, suggest running $agents-refresh.

5. Print next steps for the user

• If repo/workspace is empty: instruct to run $agents-init and answer the questionnaire.
• If workflows exist: instruct to run $agents-init to auto-fill and align with GitHub Actions.

Hard rules

• Never delete files.
• Never overwrite AGENTS.md or workflow files in this skill.
• Keep output actionable and short.

Finish with:

• What folders/files were created (paths)
• Whether symlinks were created or copies were made (and where)
• Exact next command to run (usually $agents-init)