Add Lab local agent guidance support

Author: willccbb

packages/prime/src/prime_cli/lab_setup.py

@@ -35,7 +35,7 @@
 )
 
 VERIFIERS_REPO = "primeintellect-ai/verifiers"
-VERIFIERS_REF = "7d8a522df67308327cb9b8931ce6a5873a99834a"
+VERIFIERS_REF = "f43e42c1fabfe2604afc95b9ce62779a8f55d487"
 VERIFIERS_CONFIG_REF = "main"
 DOWNLOAD_ATTEMPTS = 3
 DOWNLOAD_RETRY_DELAY_SECONDS = 1.0
@@ -44,8 +44,12 @@
 SUPPORTED_AGENTS = known_agent_names()
 LAB_GITIGNORE_PATTERNS = (
     ".env",
+    "/AGENTS.md",
+    "/CLAUDE.md",
+    "/CLAUDE.local.md",
     "/outputs/",
     "/prime-rl/",
+    "/environments/AGENTS.md",
     "/environments/*/outputs/",
     "/environments/*/dist/",
     "/environments/*/*.egg-info/",
@@ -55,6 +59,17 @@
     ".pytest_cache/",
     ".ruff_cache/",
 )
+LOCAL_CLAUDE_MD = "CLAUDE.local.md"
+LAB_GUIDANCE_GITIGNORE_PATHS = ("AGENTS.md", "CLAUDE.md", LOCAL_CLAUDE_MD, "environments/AGENTS.md")
+LOCAL_CLAUDE_GUIDANCE_TEMPLATE = "\n".join(
+    [
+        "# CLAUDE.local.md",
+        "",
+        "Add personal Claude guidance for this Lab workspace here.",
+        "Prime Lab preserves this file during setup and sync.",
+        "",
+    ]
+)
 PRIME_SKILLS_MANIFEST = ".prime-managed.json"
 WORKSPACE_SKILLS_DIR = Path(".prime") / "skills"
 DeprecatedConfigField = tuple[tuple[str, ...], str]
@@ -220,7 +235,7 @@ def parse_lab_setup_args(args: list[str]) -> LabSetupOptions:
     parser.add_argument(
         "--skip-agents-md",
         action="store_true",
-        help="Skip AGENTS.md, CLAUDE.md, and environments/AGENTS.md.",
+        help="Skip AGENTS.md, CLAUDE.md, CLAUDE.local.md, and environments/AGENTS.md.",
     )
     parser.add_argument(
         "--skip-install",
@@ -269,7 +284,7 @@ def parse_lab_sync_args(args: list[str]) -> LabSyncOptions:
     parser.add_argument(
         "--skip-docs",
         action="store_true",
-        help="Skip AGENTS.md, CLAUDE.md, and environments/AGENTS.md refresh.",
+        help="Skip AGENTS.md, CLAUDE.md, CLAUDE.local.md, and environments/AGENTS.md refresh.",
     )
     parser.add_argument(
         "--no-agent",
@@ -395,6 +410,7 @@ def _run_lab_sync_steps(
     workspace.mkdir(parents=True, exist_ok=True)
     (workspace / "configs").mkdir(exist_ok=True)
     (workspace / "environments").mkdir(exist_ok=True)
+    _append_gitignore(workspace)
     emit(f"Syncing Lab assets in {workspace}\n")
     agents = _resolve_sync_agents(workspace, options.agents, no_agent=options.no_agent)
     guidance_agents = agents
@@ -432,8 +448,9 @@ def _sync_workspace_guidance(
     force: bool = False,
 ) -> None:
     _download_file(AGENTS_MD_SRC, workspace / "AGENTS.md", emit, force=force, quiet=True)
+    _download_file(CLAUDE_MD_SRC, workspace / "CLAUDE.md", emit, force=force, quiet=True)
     if "claude" in agents:
-        _download_file(CLAUDE_MD_SRC, workspace / "CLAUDE.md", emit, force=force, quiet=True)
+        _ensure_claude_local_guidance(workspace)
     _download_file(
         ENVS_AGENTS_MD_SRC,
         workspace / "environments" / "AGENTS.md",
@@ -444,6 +461,13 @@ def _sync_workspace_guidance(
     emit("Refreshed workspace guidance\n")
 
 
+def _ensure_claude_local_guidance(workspace: Path) -> None:
+    path = workspace / LOCAL_CLAUDE_MD
+    if path.exists() or path.is_symlink():
+        return
+    path.write_text(LOCAL_CLAUDE_GUIDANCE_TEMPLATE, encoding="utf-8")
+
+
 def _sync_prime_skills(emit: Emit) -> tuple[str, ...]:
     skills_dir = _global_prime_skills_dir()
     skills_dir.parent.mkdir(parents=True, exist_ok=True)
@@ -864,6 +888,7 @@ def _lab_doctor_checks(options: LabDoctorOptions, workspace: Path) -> list[LabDo
             "Run prime lab doctor --fix.",
         ),
         _gitignore_check(workspace),
+        _lab_guidance_tracking_check(workspace, fix=options.fix),
         _config_validity_check(workspace),
         _config_deprecated_fields_check(workspace),
         _config_environment_reference_check(workspace),
@@ -1116,15 +1141,61 @@ def _gitignore_check(workspace: Path) -> LabDoctorCheck:
     missing = _missing_gitignore_patterns(existing)
     if not missing:
         return LabDoctorCheck(
-            name="Gitignore outputs",
+            name="Lab gitignore",
             status="PASS",
-            message="Standard output and generated source paths are ignored.",
+            message="Standard Lab generated and local paths are ignored.",
         )
     return LabDoctorCheck(
-        name="Gitignore outputs",
+        name="Lab gitignore",
         status="WARN",
         message="Missing " + ", ".join(missing),
-        remediation="Run prime lab doctor --fix to add standard output ignores.",
+        remediation="Run prime lab doctor --fix to add standard Lab ignores.",
+    )
+
+
+def _lab_guidance_tracking_check(workspace: Path, *, fix: bool) -> LabDoctorCheck:
+    tracked = _tracked_git_paths(workspace, LAB_GUIDANCE_GITIGNORE_PATHS)
+    if tracked and fix:
+        _untrack_git_paths(workspace, tracked)
+        tracked = _tracked_git_paths(workspace, LAB_GUIDANCE_GITIGNORE_PATHS)
+    if not tracked:
+        return LabDoctorCheck(
+            name="Lab guidance tracking",
+            status="PASS",
+            message="Lab generated and local guidance files are untracked.",
+        )
+    paths = " ".join(tracked)
+    return LabDoctorCheck(
+        name="Lab guidance tracking",
+        status="WARN",
+        message="Tracked Lab generated/local guidance files: " + ", ".join(tracked),
+        remediation=f"Run git rm --cached {paths} && prime lab sync.",
+    )
+
+
+def _tracked_git_paths(workspace: Path, paths: tuple[str, ...]) -> tuple[str, ...]:
+    try:
+        result = subprocess.run(
+            ["git", "ls-files", "--", *paths],
+            cwd=workspace,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except OSError:
+        return ()
+    if result.returncode != 0:
+        return ()
+    return tuple(line.strip() for line in result.stdout.splitlines() if line.strip())
+
+
+def _untrack_git_paths(workspace: Path, paths: tuple[str, ...]) -> None:
+    subprocess.run(
+        ["git", "rm", "--cached", "--quiet", "--", *paths],
+        cwd=workspace,
+        check=False,
+        capture_output=True,
+        text=True,
     )
 
 
@@ -1422,10 +1493,11 @@ def _write_lab_docs_index(workspace: Path, agents: tuple[str, ...]) -> None:
     docs_dir.mkdir(parents=True, exist_ok=True)
     guidance_files = [
         "- `AGENTS.md`",
+        "- `CLAUDE.md`",
         "- `environments/AGENTS.md`",
     ]
     if "claude" in agents:
-        guidance_files.insert(1, "- `CLAUDE.md`")
+        guidance_files.insert(2, f"- `{LOCAL_CLAUDE_MD}`")
     index = docs_dir / "index.md"
     index.write_text(
         "\n".join(