refactor(agent-setup): move tooling into .agents

Author: hassiebp

.agents/AGENTS.md

@@ -36,7 +36,6 @@ langfuse-python/
 ├─ langfuse/langchain/       # LangChain integration
 ├─ tests/                    # Test suite
 ├─ static/                   # Test fixtures and sample content
-├─ scripts/                  # Repo scripts
 └─ .agents/                  # Canonical shared agent instructions and config
 ```
 
@@ -65,10 +64,10 @@ High-signal entry points:
 
 ## Build, Test, and Development Commands
 
-- Agent environment bootstrap: `bash scripts/codex/setup.sh`
-- Install dependencies: `poetry install --all-extras`
-- Sync generated agent shims: `python3 scripts/agents/sync-agent-shims.py`
-- Verify generated agent shims: `python3 scripts/agents/sync-agent-shims.py --check`
+- Agent environment bootstrap: `bash .agents/scripts/codex/setup.sh`
+- Install dependencies: `bash .agents/scripts/install.sh --all-extras`
+- Sync generated agent shims: `python3 .agents/scripts/sync-agent-shims.py`
+- Verify generated agent shims: `python3 .agents/scripts/sync-agent-shims.py --check`
 - Install pre-commit hooks: `poetry run pre-commit install`
 - Run all tests: `poetry run pytest -s -v --log-cli-level=INFO`
 - Run tests in parallel: `poetry run pytest -s -v --log-cli-level=INFO -n auto`
@@ -88,7 +87,7 @@ Minimum verification matrix:
 | `langfuse/api/**` | verify source update path from main repo + `poetry run ruff format .` + targeted API tests |
 | Integration modules (`langfuse/openai.py`, `langfuse/langchain/**`) | targeted tests for the touched integration + lint + latest official provider docs review if behavior or API usage changed |
 | Test-only changes | targeted pytest coverage for the updated tests |
-| Agent setup files (`.agents/**`, `scripts/agents/**`, `scripts/codex/**`) | `python3 scripts/agents/sync-agent-shims.py` + `python3 scripts/agents/sync-agent-shims.py --check` + `poetry run pytest tests/test_sync_agent_shims.py` |
+| Agent setup files (`.agents/**`) | `python3 .agents/scripts/sync-agent-shims.py` + `python3 .agents/scripts/sync-agent-shims.py --check` |
 
 CI notes:
 
@@ -202,7 +201,9 @@ Update flow:
 - Shared agent/tool config lives in `.agents/config.json`.
 - Shared agent setup documentation lives in `.agents/README.md`.
 - Shared skills live under `.agents/skills/`.
-- `python3 scripts/agents/sync-agent-shims.py` regenerates tool-specific config
+- `.agents/scripts/` is the home for repo-owned agent bootstrap and sync
+  tooling.
+- `python3 .agents/scripts/sync-agent-shims.py` regenerates tool-specific config
   shims for Claude, Cursor, VS Code, Codex, and shared MCP discovery files.
 - Tool-specific directories such as `.claude/`, `.cursor/`, `.codex/`, and
   `.vscode/` remain because those tools discover project settings from fixed

.agents/README.md

@@ -12,6 +12,7 @@ or `.vscode/`.
 - `AGENTS.md`: canonical shared root instructions
 - `config.json`: shared bootstrap and MCP configuration used to generate
   tool-specific shims
+- `scripts/`: shared bootstrap and sync helpers for agent tooling
 - `skills/`: shared, tool-neutral implementation guidance for recurring
   workflows
 
@@ -30,7 +31,7 @@ Current shape:
 ```json
 {
   "shared": {
-    "setupScript": "bash scripts/codex/setup.sh",
+    "setupScript": "bash .agents/scripts/codex/setup.sh",
     "devCommand": "poetry run bash",
     "devTerminalDescription": "Interactive development shell inside the Poetry environment"
   },
@@ -59,7 +60,7 @@ Current shape:
 
 ## How Shims Are Generated
 
-`scripts/agents/sync-agent-shims.py` reads `.agents/config.json` and writes the
+`.agents/scripts/sync-agent-shims.py` reads `.agents/config.json` and writes the
 tool discovery files that those products require.
 
 Generated local artifacts:
@@ -99,15 +100,16 @@ Do not edit generated shim files by hand. Edit the canonical files in
 After editing `.agents/config.json` or `.agents/skills/**`:
 
 1. Run `python3 scripts/agents/sync-agent-shims.py`
-2. Run `python3 scripts/agents/sync-agent-shims.py --check`
-3. Run `poetry run pytest tests/test_sync_agent_shims.py`
-4. Verify you did not stage generated files under `.claude/skills/` or any of
+2. Run `python3 .agents/scripts/sync-agent-shims.py --check`
+3. Verify you did not stage generated files under `.claude/skills/` or any of
    the generated MCP/runtime config paths
-5. Update `.agents/AGENTS.md` or `CONTRIBUTING.md` if the shared workflow
+4. Update `.agents/AGENTS.md` or `CONTRIBUTING.md` if the shared workflow
    materially changed
 
-`bash scripts/postinstall.sh` runs the sync/check flow as a convenience helper,
-and `bash scripts/codex/setup.sh` uses it during agent environment bootstrap.
+`bash .agents/scripts/install.sh --all-extras` is the canonical repo install
+flow and wires `poetry install` to `bash .agents/scripts/postinstall.sh`.
+`bash .agents/scripts/codex/setup.sh` uses the same path during agent
+environment bootstrap.
 
 ## Adding Shared Skills
 
@@ -121,7 +123,7 @@ Use them for durable, reusable guidance such as:
 
 Do not use skills for one-off notes or tool runtime configuration.
 
-`python3 scripts/agents/sync-agent-shims.py` projects shared skills into
+`python3 .agents/scripts/sync-agent-shims.py` projects shared skills into
 `.claude/skills/` so Claude can discover the same repo-owned skills.
 
 For the skill authoring workflow, see [skills/README.md](skills/README.md).

.agents/config.json

@@ -1,6 +1,6 @@
 {
   "shared": {
-    "setupScript": "bash scripts/codex/setup.sh",
+    "setupScript": "bash .agents/scripts/codex/setup.sh",
     "devCommand": "poetry run bash",
     "devTerminalDescription": "Interactive development shell inside the Poetry environment"
   },

scripts/codex/setup.sh .agents/scripts/codex/setup.shscripts/codex/setup.sh renamed to .agents/scripts/codex/setup.sh

@@ -4,6 +4,5 @@ set -euo pipefail
 
 poetry config virtualenvs.create true --local
 poetry config virtualenvs.in-project true --local
-poetry install --all-extras
 
-bash scripts/postinstall.sh
+bash .agents/scripts/install.sh --all-extras

.agents/scripts/install.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+poetry install "$@"
+
+bash .agents/scripts/postinstall.sh

.agents/scripts/postinstall.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [[ ! -f ".agents/scripts/sync-agent-shims.py" ]]; then
+  echo "Skipping agent shim sync: .agents/scripts/sync-agent-shims.py is not present in this install context."
+  exit 0
+fi
+
+python3 .agents/scripts/sync-agent-shims.py
+python3 .agents/scripts/sync-agent-shims.py --check

scripts/agents/sync-agent-shims.py .agents/scripts/sync-agent-shims.pyscripts/agents/sync-agent-shims.py renamed to .agents/scripts/sync-agent-shims.py

@@ -186,6 +186,11 @@ def print_error(message: str) -> None:
     print(message, file=sys.stderr)
 
 
+def is_writable(path: Path) -> bool:
+    target = path if path.exists() else path.parent
+    return os.access(target, os.W_OK)
+
+
 def sync_file_outputs(
     file_outputs: list[dict[str, Any]], check_mode: bool
 ) -> tuple[bool, list[str]]:
@@ -198,6 +203,9 @@ def sync_file_outputs(
         optional: bool = output.get("optional", False)
 
         if check_mode:
+            if optional and not is_writable(path):
+                warnings.append(f"Skipping optional config check: {path}")
+                continue
             try:
                 current = path.read_text(encoding="utf-8")
             except FileNotFoundError:
@@ -206,7 +214,7 @@ def sync_file_outputs(
                     continue
                 has_mismatch = True
                 print_error(
-                    f'Missing generated config: {path}. Run "python3 scripts/agents/sync-agent-shims.py".'
+                    f'Missing generated config: {path}. Run "python3 .agents/scripts/sync-agent-shims.py".'
                 )
                 continue
 
@@ -240,7 +248,7 @@ def sync_symlink_outputs(
             if not is_matching_symlink(path, target):
                 has_mismatch = True
                 print_error(
-                    f'Out of sync symlink: {path}. Run "python3 scripts/agents/sync-agent-shims.py".'
+                    f'Out of sync symlink: {path}. Run "python3 .agents/scripts/sync-agent-shims.py".'
                 )
             continue
 

.github/workflows/ci.yml

@@ -29,10 +29,6 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: "3.13"
-      - name: Verify agent shim generation
-        run: |
-          python3 scripts/agents/sync-agent-shims.py
-          python3 scripts/agents/sync-agent-shims.py --check
       - name: Install poetry
         uses: abatilo/actions-poetry@v2
       - name: Setup a local virtual environment
@@ -52,7 +48,7 @@ jobs:
           restore-keys: |
             mypy-
       - name: Install dependencies
-        run: poetry install --only=main,dev
+        run: bash .agents/scripts/install.sh --only=main,dev
       - name: Run mypy type checking
         run: poetry run mypy langfuse --no-error-summary
 
@@ -189,7 +185,7 @@ jobs:
             venv-${{ matrix.python-version }}-${{ hashFiles('poetry.lock') }}-${{ github.sha }}
 
       - name: Install the project dependencies
-        run: poetry install --all-extras
+        run: bash .agents/scripts/install.sh --all-extras
 
       - name: Run the automated tests
         run: |

CONTRIBUTING.md

@@ -11,7 +11,7 @@ poetry self add poetry-dotenv-plugin
 ### Install dependencies
 
 ```
-poetry install --all-extras
+bash .agents/scripts/install.sh --all-extras
 ```
 
 ### Shared Agent Setup
@@ -45,15 +45,14 @@ and MCP/bootstrap configuration.
 - Tool-specific skill projections generated locally and not committed:
   - `.claude/skills/*`
 - Shared bootstrap for agent environments:
-  - `bash scripts/codex/setup.sh`
+  - `bash .agents/scripts/codex/setup.sh`
 
 When you change the shared agent setup:
 
 1. Edit `.agents/config.json` or `.agents/skills/**`
-2. Run `python3 scripts/agents/sync-agent-shims.py`
-3. Run `python3 scripts/agents/sync-agent-shims.py --check`
-4. Run `poetry run pytest tests/test_sync_agent_shims.py`
-5. Do not commit the generated MCP config files or runtime shims
+2. Run `python3 .agents/scripts/sync-agent-shims.py`
+3. Run `python3 .agents/scripts/sync-agent-shims.py --check`
+4. Do not commit the generated MCP config files or runtime shims
 
 ### Add Pre-commit
 
@@ -125,7 +124,7 @@ Note: The generated SDK reference is currently work in progress.
 The SDK reference is generated via pdoc. You need to have all extra dependencies installed to generate the reference.
 
 ```sh
-poetry install --all-extras
+bash .agents/scripts/install.sh --all-extras
 ```
 
 To update the reference, run the following command: