AGENTS.md for Monorepos skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "AGENTS.md for Monorepos"
  short_description: "Root rules once, package rules where they apply"
  default_prompt: "$agents-md-monorepo Codex keeps running pnpm test inside our Go service. Fix the AGENTS.md layout"

#!/usr/bin/env python3
"""Show the AGENTS.md instruction chain Codex would assemble for a directory.

Mirrors the documented discovery rules: global file from CODEX_HOME
(AGENTS.override.md, else AGENTS.md), then one file per directory from the
project root down to the target directory, choosing the first non-empty file
among AGENTS.override.md, AGENTS.md and any fallback names. Reports sizes
against the project_doc_max_bytes budget and files shadowed by an override.

Usage:
  python3 scripts/agents_chain.py [TARGET_DIR] [--fallback NAME ...]
                                  [--max-bytes N] [--markers .git,.hg]
                                  [--codex-home DIR] [--audit]

Exit codes: 0 ok, 1 project instructions exceed the budget, 2 usage error.
"""
from __future__ import annotations

import argparse
import os
import sys
from pathlib import Path

PRIMARY = ["AGENTS.override.md", "AGENTS.md"]
SKIP_DIRS = {".git", "node_modules", ".venv", "venv", "dist", "build", "target", ".next", "__pycache__"}


def non_empty(path: Path) -> bool:
    try:
        return path.is_file() and path.read_text(encoding="utf-8", errors="replace").strip() != ""
    except OSError:
        return False


def pick(directory: Path, names: list[str]) -> tuple[Path | None, list[Path]]:
    """Return the file Codex would use in this directory and the non-empty files it ignores."""
    chosen = None
    shadowed = []
    for name in names:
        candidate = directory / name
        if non_empty(candidate):
            if chosen is None:
                chosen = candidate
            else:
                shadowed.append(candidate)
    return chosen, shadowed


def find_root(target: Path, markers: list[str]) -> Path | None:
    if not markers:
        return target
    for directory in [target, *target.parents]:
        if any((directory / m).exists() for m in markers):
            return directory
    return None


def chain_dirs(root: Path | None, target: Path) -> list[Path]:
    if root is None:
        return [target]
    rel = target.relative_to(root)
    dirs = [root]
    current = root
    for part in rel.parts:
        current = current / part
        dirs.append(current)
    return dirs


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("target", nargs="?", default=".", help="directory Codex is started from (default: cwd)")
    parser.add_argument("--fallback", action="append", default=[], help="name from project_doc_fallback_filenames (repeatable)")
    parser.add_argument("--max-bytes", type=int, default=32768, help="project_doc_max_bytes (default 32768)")
    parser.add_argument("--markers", default=".git", help="comma-separated project_root_markers; empty string = cwd is root")
    parser.add_argument("--codex-home", default=os.environ.get("CODEX_HOME", str(Path.home() / ".codex")))
    parser.add_argument("--audit", action="store_true", help="also list every instruction file under the root and what shadows it")
    args = parser.parse_args()

    target = Path(args.target).resolve()
    if not target.is_dir():
        print(f"error: {target} is not a directory", file=sys.stderr)
        return 2
    names = PRIMARY + args.fallback
    markers = [m for m in args.markers.split(",") if m]
    root = find_root(target, markers)

    print(f"target:       {target}")
    print(f"project root: {root if root else '(none found; only the target directory is checked)'}")
    print(f"lookup order: {', '.join(names)}")
    print()

    global_file, global_shadowed = pick(Path(args.codex_home).expanduser(), PRIMARY)
    if global_file:
        print(f"[global] {global_file}  {global_file.stat().st_size} B")
        for s in global_shadowed:
            print(f"         ignored: {s} (an override is present)")
    else:
        print(f"[global] none in {args.codex_home}")

    total = 0
    over = False
    order = 0
    for directory in chain_dirs(root, target):
        chosen, shadowed = pick(directory, names)
        if chosen is None:
            continue
        order += 1
        size = len(chosen.read_bytes())
        total += size
        flag = ""
        if total > args.max_bytes and not over:
            over = True
            flag = "  <-- budget reached here; later text is dropped"
        print(f"[{order}] {chosen}  {size} B (cumulative {total} B){flag}")
        for s in shadowed:
            print(f"     ignored: {s}")

    print()
    print(f"project instructions: {total} B of {args.max_bytes} B budget")
    if args.audit and root is not None:
        print("\naudit of instruction files under the root:")
        for dirpath, dirnames, _ in os.walk(root):
            dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
            chosen, shadowed = pick(Path(dirpath), names)
            if chosen:
                rel = Path(dirpath).relative_to(root) or Path(".")
                line = f"  {rel}/{chosen.name}"
                if shadowed:
                    line += "  (shadows " + ", ".join(s.name for s in shadowed) + ")"
                print(line)
    if over:
        print("FAIL: combined project instructions exceed the budget", file=sys.stderr)
        return 1
    print("OK")
    return 0


if __name__ == "__main__":
    sys.exit(main())