Instructions

1"""Discover and classify source instruction files for AGENTS.md migration.
2
3Chooses the first supported instruction file for a project/global scope. Neutral
4instruction files are safe for `AGENTS.md` symlinks; content with obvious
5Claude-only lifecycle, hook, subagent, or permission assumptions is treated as
6requiring a generated Codex-specific copy and manual rewrite.
7"""
8
9from __future__ import annotations
10
11from collections.abc import Callable
12from pathlib import Path
13
14from migrate.common import MigrationReportItem
15
16
17INSTRUCTION_SOURCE_CANDIDATES = (
18    Path(".claude") / "CLAUDE.md",
19    Path("CLAUDE.md"),
20    Path("claude.md"),
21    Path("AGENTS.md"),
22)
23
24CLAUDE_ONLY_INSTRUCTION_MARKERS = (
25    "/hooks",
26    ".claude/agents/",
27    ".claude/settings",
28    "Subagent",
29    "subagent",
30    "permissionMode",
31    "ExitPlanMode",
32)
33MAX_AGENTS_MD_BYTES = 32 * 1024
34
35
36def instruction_source_file(
37    source_root: Path,
38    is_global: bool,
39    path_exists_with_exact_case: Callable[[Path], bool],
40) -> Path | None:
41    candidates = INSTRUCTION_SOURCE_CANDIDATES
42    if not is_global:
43        candidates = tuple(
44            candidate
45            for candidate in candidates
46            if candidate != Path(".claude") / "CLAUDE.md"
47        )
48
49    for candidate in candidates:
50        source_file = source_root / candidate
51        if path_exists_with_exact_case(source_file):
52            return source_file
53    return None
54
55
56def should_symlink_instructions(content: str) -> bool:
57    return not any(marker in content for marker in CLAUDE_ONLY_INSTRUCTION_MARKERS)
58
59
60def validate_agents_md_files(target_root: Path) -> list[MigrationReportItem]:
61    report_items: list[MigrationReportItem] = []
62    for agents_file in sorted(target_root.rglob("AGENTS.md")):
63        relative_path = agents_file.relative_to(target_root)
64        size_bytes = agents_file.stat().st_size
65        if size_bytes > MAX_AGENTS_MD_BYTES:
66            report_items.append(
67                MigrationReportItem(
68                    "warning",
69                    relative_path,
70                    f"{size_bytes / 1024:.1f}KB exceeds the 32KB review threshold.",
71                )
72            )
73            continue
74        report_items.append(
75            MigrationReportItem(
76                "ok",
77                relative_path,
78                f"{size_bytes / 1024:.1f}KB is under the 32KB review threshold.",
79            )
80        )
81    return report_items