claude-dev-env 1.94.0 → 2.0.0

package/skills/codex-review/test_skill_scaffold.py

@@ -0,0 +1,192 @@
+"""Scaffold contract tests for the codex-review skill package."""
+
+from __future__ import annotations
+
+import importlib
+import tomllib
+from pathlib import Path
+
+
+SKILL_DIRECTORY = Path(__file__).resolve().parent
+SKILL_PATH = SKILL_DIRECTORY / "SKILL.md"
+PACKAGE_MAP_PATH = SKILL_DIRECTORY / "CLAUDE.md"
+REFERENCE_DIRECTORY = SKILL_DIRECTORY / "reference"
+PACKAGE_ROOT = SKILL_DIRECTORY.parents[1]
+PYPROJECT_PATH = PACKAGE_ROOT / "pyproject.toml"
+EVER_SHIPPED_SKILLS_PATH = PACKAGE_ROOT / "bin" / "ever-shipped-skills.mjs"
+CONSTANTS_PACKAGE_NAME = "codex_review_scripts_constants"
+CONSTANTS_PACKAGE_DIR = "skills/codex-review/scripts/codex_review_scripts_constants"
+SKILL_NAME = "codex-review"
+MAXIMUM_SKILL_BODY_LINE_COUNT = 500
+
+
+def _read_skill_text() -> str:
+    return SKILL_PATH.read_text(encoding="utf-8")
+
+
+def test_constants_package_imports() -> None:
+    constants_package = importlib.import_module(CONSTANTS_PACKAGE_NAME)
+
+    assert constants_package.__name__ == CONSTANTS_PACKAGE_NAME
+
+
+def test_pyproject_registers_constants_package() -> None:
+    parsed_pyproject = tomllib.loads(PYPROJECT_PATH.read_text(encoding="utf-8"))
+    setuptools_table = parsed_pyproject["tool"]["setuptools"]
+    all_packages = setuptools_table["packages"]
+    package_directory_by_name = setuptools_table["package-dir"]
+
+    assert CONSTANTS_PACKAGE_NAME in all_packages
+    assert package_directory_by_name[CONSTANTS_PACKAGE_NAME] == CONSTANTS_PACKAGE_DIR
+
+
+def test_ever_shipped_skills_lists_codex_review() -> None:
+    ever_shipped_text = EVER_SHIPPED_SKILLS_PATH.read_text(encoding="utf-8")
+
+    assert f"'{SKILL_NAME}'" in ever_shipped_text
+
+
+def test_skill_md_exists_with_trigger_description() -> None:
+    skill_text = _read_skill_text()
+
+    assert "name: codex-review" in skill_text
+    assert "/codex-review" in skill_text
+    assert "codex review" in skill_text
+    assert "run codex review" in skill_text
+    assert "babysit codex review" in skill_text
+    assert "codex as a PR reviewer" in skill_text
+
+
+def test_skill_composes_opt_out_and_fix_protocol_by_name() -> None:
+    skill_text = _read_skill_text()
+
+    assert "reviews_disabled.py" in skill_text
+    assert "--reviewer codex" in skill_text
+    assert "pr-fix-protocol" in skill_text
+    assert "reviewer-gates" in skill_text
+
+
+def test_skill_documents_gate_exit_contract() -> None:
+    skill_text = _read_skill_text()
+
+    assert "--reviewer codex" in skill_text
+    assert "Exit 0" in skill_text
+    assert "Exit 1" in skill_text
+    assert "Any other exit" in skill_text
+    assert "blocker" in skill_text
+    assert "CLAUDE_REVIEWS_DISABLED=codex" in skill_text
+    assert "not among them" not in skill_text
+    assert "codex is not among" not in skill_text
+
+
+def test_skill_documents_flow_skeleton() -> None:
+    skill_text = _read_skill_text()
+    skill_text_lower = skill_text.lower()
+
+    assert "shape probe" in skill_text_lower
+    assert "classif" in skill_text_lower
+    assert "`down`" in skill_text
+    assert "`clean`" in skill_text
+    assert "`findings`" in skill_text
+    assert "`codex_down`" in skill_text
+    assert "base branch" in skill_text_lower
+    assert "uncommitted" in skill_text_lower
+    assert "untracked" in skill_text_lower
+
+
+def test_skill_classifying_path_is_exec_with_json() -> None:
+    skill_text = _read_skill_text()
+    cli_contract_text = (REFERENCE_DIRECTORY / "cli-contract.md").read_text(
+        encoding="utf-8"
+    )
+
+    assert "codex exec" in skill_text
+    assert "--json" in skill_text
+    assert (
+        "codex exec … review --json" in skill_text
+        or "codex exec [options] review --json" in skill_text
+    )
+    assert "non-classifying" in skill_text.lower() or "Non-classifying" in skill_text
+    assert "codex exec" in cli_contract_text
+    assert "--json" in cli_contract_text
+    assert "non-classifying" in cli_contract_text.lower()
+
+
+def test_cli_contract_probe_lists_minimum_shape_signals() -> None:
+    cli_contract_text = (REFERENCE_DIRECTORY / "cli-contract.md").read_text(
+        encoding="utf-8"
+    )
+
+    assert "codex exec review --help" in cli_contract_text
+    assert "Minimum shape signals" in cli_contract_text
+    assert "Fail-closed rule" in cli_contract_text
+    assert "--uncommitted" in cli_contract_text
+    assert "--base" in cli_contract_text
+    assert "--commit" in cli_contract_text
+    assert "--json" in cli_contract_text
+    assert "`review`" in cli_contract_text
+
+
+def test_scripts_surface_names_capture_wrapper_and_constants() -> None:
+    skill_text = _read_skill_text()
+    package_map_text = PACKAGE_MAP_PATH.read_text(encoding="utf-8")
+    constants_map_text = (
+        SKILL_DIRECTORY / "scripts" / "codex_review_scripts_constants" / "CLAUDE.md"
+    ).read_text(encoding="utf-8")
+    wrapper_path = SKILL_DIRECTORY / "scripts" / "run_codex_review.py"
+
+    assert wrapper_path.is_file()
+    assert "run_codex_review.py" in skill_text
+    assert "run_codex_review.py" in package_map_text
+    assert "capture only" in skill_text.lower() or "capture-only" in skill_text.lower()
+    assert "completed" in skill_text
+    assert "codex_down" in skill_text
+    assert "non-classifying" in skill_text.lower()
+    assert "run_constants.py" in constants_map_text
+    assert "run_codex_review.py" in constants_map_text
+
+
+def test_uncommitted_includes_untracked() -> None:
+    skill_text = _read_skill_text()
+    cli_contract_text = (REFERENCE_DIRECTORY / "cli-contract.md").read_text(
+        encoding="utf-8"
+    )
+    loop_integration_text = (REFERENCE_DIRECTORY / "loop-integration.md").read_text(
+        encoding="utf-8"
+    )
+
+    assert "untracked" in skill_text.lower()
+    assert "staged + unstaged + untracked" in cli_contract_text.lower()
+    assert "untracked" in loop_integration_text.lower()
+    assert "--uncommitted" in skill_text
+    assert "--uncommitted" in loop_integration_text
+
+
+def test_skill_body_stays_under_line_cap() -> None:
+    skill_line_count = len(_read_skill_text().splitlines())
+
+    assert skill_line_count < MAXIMUM_SKILL_BODY_LINE_COUNT
+
+
+def test_package_map_claude_md_exists() -> None:
+    package_map_text = PACKAGE_MAP_PATH.read_text(encoding="utf-8")
+
+    assert "codex-review" in package_map_text
+    assert "SKILL.md" in package_map_text
+    assert "reference/" in package_map_text
+    assert "cli-contract.md" in package_map_text
+    assert "codex_down" in package_map_text
+    assert "review --json" in package_map_text
+
+
+def test_reference_shell_pages_exist() -> None:
+    assert (REFERENCE_DIRECTORY / "cli-contract.md").is_file()
+    assert (REFERENCE_DIRECTORY / "loop-integration.md").is_file()
+    assert (REFERENCE_DIRECTORY / "CLAUDE.md").is_file()
+
+
+def test_constants_package_directory_exists() -> None:
+    constants_directory = SKILL_DIRECTORY / "scripts" / "codex_review_scripts_constants"
+
+    assert (constants_directory / "__init__.py").is_file()
+    assert (constants_directory / "CLAUDE.md").is_file()

package/skills/grok-spawn/CLAUDE.md

@@ -0,0 +1,28 @@
+# grok-spawn
+
+**Trigger:** `/grok-spawn`, "spawn grok workers", "grok worker fleet", "run this with grok workers", "headless grok batch".
+
+Orchestrator playbook for fleets of headless grok CLI workers. Composes
+`grok_worker_preflight.py` and `spawn_grok_batch.py` by name. Holds no spawn
+logic of its own. The calling session verifies results and owns every commit,
+push, and GitHub post.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `reference/` | Prompt-part templates and tool-profile flag docs the hub cites on demand. |
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Entry protocol: when to use, gotchas, preflight → batch spec → launch → collect → verify. |
+| `reference/worker-briefs.md` | Readonly investigation brief, build brief (edits and tests only), report contract. |
+| `reference/flag-profiles.md` | Readonly vs build flag sets, shared flags, leader-socket and stagger rules, `--agent` note. |
+
+## Entry point
+
+No skill-local scripts. Runtime lives in `$HOME/.claude/scripts/`
+(`grok_worker_preflight.py`, `spawn_grok_batch.py`, `grok_headless_runner.py`)
+after install. Constants live in `scripts/dev_env_scripts_constants/`.

package/skills/grok-spawn/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: grok-spawn
+description: >-
+  Spawn headless grok worker fleets via preflight and spawn_grok_batch.
+  Triggers: /grok-spawn, spawn grok workers, grok worker fleet, run this with
+  grok workers, headless grok batch.
+---
+
+# Grok Spawn
+
+Orchestrator playbook for fleets of headless grok CLI workers. This skill names
+the scripts and the brief templates; it holds no spawn logic of its own.
+
+## Gotchas
+
+- Workers never commit, push, or call `gh`. The calling session stages, verifies,
+  commits, pushes, and posts to GitHub.
+- Grok has no `SendMessage` and no Claude Agent tool. Work that needs live
+  teammate chat or Claude-only tools stays in this session or a Claude agent.
+- Each worker gets its own `--leader-socket`. Sharing one socket across processes
+  races and fails.
+- Preflight is a soft gate: a fallthrough reason means skip the fleet and use
+  the next tier, not a hard crash of the whole run.
+- Prompt parts are plain files. Conversation-relative phrases ("as above") mean
+  nothing to a headless worker — every brief stands alone.
+- `spawn_grok_batch.py` re-runs preflight before launch. An early preflight call
+  still helps you abort before writing the batch spec.
+
+## When this skill applies
+
+Use when the user asks for a **grok worker fleet**, a **headless grok batch**, or
+types `/grok-spawn`.
+
+Good fits:
+
+- Fan-out read-only research across several paths or files
+- Parallel bite-sized build work where each worker owns a closed scope
+
+**Do not use** when the work needs:
+
+- Live `SendMessage` coordination between agents
+- Claude-only tools (Agent tool, warm session-advisor, Claude MCP surfaces the
+  grok CLI does not load the same way)
+
+For a single interactive Grok Build handoff paste, use `/grokify` instead.
+
+**Refusal:** no concrete worker tasks — reply `What should the grok workers do?
+List each role in one line.` and stop.
+
+## Process
+
+Copy this checklist and check items off as you go.
+
+```
+[ ] 1. Preflight (#96 soft gate)
+[ ] 2. Write prompt-part files (briefs + report contract)
+[ ] 3. Write the batch JSON spec
+[ ] 4. Run spawn_grok_batch.py
+[ ] 5. Read the batch summary and per-worker reports
+[ ] 6. Verify, then own every git and gh step yourself
+```
+
+### 1. Preflight
+
+Scripts ship under `$HOME/.claude/scripts/` after install (or the package
+`scripts/` tree in this repo).
+
+```bash
+python "$HOME/.claude/scripts/grok_worker_preflight.py" \
+  --role bugteam \
+  --run-temp-dir "<run-state-dir>"
+```
+
+Optional live ping (cached under the run state dir):
+
+```bash
+python "$HOME/.claude/scripts/grok_worker_preflight.py" \
+  --role bugteam \
+  --ping \
+  --run-temp-dir "<run-state-dir>"
+```
+
+Stdout is one line:
+
+- `grok_preflight: ok` — continue
+- `grok_preflight: fallthrough reason=<reason>` — report the reason, skip the
+  fleet, fall to the next tier
+
+Pick a fresh run state directory for the fleet (sockets, prompts, reports, ping
+cache). Reuse that same path for preflight and the batch launcher.
+
+### 2. Write prompt-part files
+
+For each worker, write one or more part files on disk. Assemble from:
+
+| Part | Source |
+|---|---|
+| Role brief | [`reference/worker-briefs.md`](reference/worker-briefs.md) — readonly or build template |
+| Report contract | Same file — every worker ends with the report sections |
+| Task body | Task-specific scope, paths, acceptance lines (you author this) |
+
+Order matters: the batch launcher joins part bodies in list order after the
+tool-profile header. Put the brief first, task body next, report contract last.
+
+Flag sets and profile meaning:
+[`reference/flag-profiles.md`](reference/flag-profiles.md).
+
+### 3. Write the batch JSON spec
+
+Shape:
+
+```json
+{
+  "role": "bugteam",
+  "should_ping": false,
+  "workers": [
+    {
+      "role_name": "investigate-hooks",
+      "prompt_parts": [
+        "/abs/path/to/readonly-brief.md",
+        "/abs/path/to/task-body.md",
+        "/abs/path/to/report-contract.md"
+      ],
+      "cwd": "/abs/path/to/worktree",
+      "tool_profile": "readonly",
+      "timeout_seconds": 600,
+      "is_repo_only": true,
+      "max_turns": 8,
+      "agent_name": null
+    }
+  ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `role` | Preflight role whose agent files must be installed (default `bugteam`) |
+| `should_ping` | When true, preflight runs the opt-in live ping |
+| `workers` | Non-empty list of worker objects |
+| `role_name` | Label on the summary report for this worker |
+| `prompt_parts` | Ordered absolute paths to part files |
+| `cwd` | Working directory for that worker |
+| `tool_profile` | `readonly` or `build` |
+| `timeout_seconds` | Per-worker timeout (default 600) |
+| `is_repo_only` | Readonly only: when true, also pass `--disable-web-search` |
+| `max_turns` | Turn cap (default 8) |
+| `agent_name` | Optional `--agent` name, or `null` |
+
+Put the spec file under the run state directory (or any path you pass to
+`--spec`).
+
+### 4. Launch the batch
+
+```bash
+python "$HOME/.claude/scripts/spawn_grok_batch.py" \
+  --spec "<batch-spec.json>" \
+  --run-temp-dir "<run-state-dir>"
+```
+
+The launcher:
+
+1. Runs preflight once for the whole batch
+2. Staggers worker starts (15s between index 0, 1, 2, …)
+3. Mints per-worker prompt, report, leader-socket, and debug paths
+4. Prints one JSON summary on stdout
+
+Exit code `0` only when preflight is usable and every worker is ok.
+
+### 5. Collect reports
+
+Read the stdout JSON:
+
+| Key | Meaning |
+|---|---|
+| `is_preflight_usable` | Soft gate result |
+| `preflight_reason` | Fallthrough reason, or null |
+| `workers` | Per-worker reports |
+
+Each worker entry carries `role_name`, `tool_profile`, `returncode`,
+`classification`, `is_ok`, `report_text`, `output_file`, `leader_socket`,
+`prompt_file`, `debug_file`.
+
+Open each `output_file` (or use `report_text`) and check the report contract
+sections. Failed workers (`is_ok` false) keep their classification
+(`usage_limit`, `auth_failure`, `timeout`, `error`) for routing; read their
+`debug_file` for the grok-side log of the run.
+
+A negative `returncode` means no grok process produced it: `-1` timeout, `-2`
+launch failure, `-3` the launcher itself raised before the process started (a
+missing prompt-part file, for example).
+
+### 6. Verify and own git / gh
+
+The calling session:
+
+1. Diffs the worktrees the build workers touched
+2. Re-runs the named tests
+3. Maps each acceptance line to evidence
+4. Stages, commits, pushes, and posts GitHub updates as needed
+
+Build workers stop at stage-ready edits and a written report. They do not run
+`git commit`, `git push`, or `gh`.
+
+## Composition
+
+| Script | Role |
+|---|---|
+| `grok_worker_preflight.py` | Soft gate (#96): binary, auth, install, optional ping |
+| `spawn_grok_batch.py` | Batch launch, stagger, report collect |
+| `grok_headless_runner.py` | One-worker runner (called by the batch launcher) |
+
+Sibling skill: `/grokify` for a single paste-ready interactive Grok Build handoff.
+
+## File index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Trigger, gotchas, process, batch shape, composition |
+| `CLAUDE.md` | Package map for this skill folder |
+| `reference/worker-briefs.md` | Readonly brief, build brief, report contract templates |
+| `reference/flag-profiles.md` | Readonly vs build flags, shared flags, socket and stagger rules |
+
+## Folder map
+
+- `SKILL.md` — hub and process.
+- `reference/` — brief templates and flag profiles.

package/skills/grok-spawn/reference/flag-profiles.md

@@ -0,0 +1,132 @@
+# Flag profiles
+
+Exact flag sets used by `spawn_grok_batch.py` and `grok_headless_runner.py`.
+Constants live in `scripts/dev_env_scripts_constants/grok_worker_constants.py`
+and `scripts/dev_env_scripts_constants/timing.py`.
+
+You choose a profile per worker via `tool_profile` on the batch spec. The
+launcher builds the argv; do not hand-roll a parallel flag set unless you are
+debugging outside the batch launcher.
+
+---
+
+## Shared base flags (every worker)
+
+The headless runner always passes:
+
+| Flag | Value / source |
+|---|---|
+| `--prompt-file` | Assembled per-worker prompt path under the run state dir |
+| `--cwd` | Worker `cwd` from the batch spec |
+| `--output-format` | `json` |
+| `--always-approve` | present (auto-approve tool runs) |
+| `--max-turns` | Worker `max_turns` (default `8`) |
+| `--leader-socket` | Unique per-worker socket path under the run state dir |
+| `--debug-file` | Unique per-worker debug log (batch launcher adds this) |
+
+Optional:
+
+| Flag | When |
+|---|---|
+| `--agent <name>` | Worker `agent_name` is a non-null string |
+| `--model <id>` | Only when `GROK_MODEL_PIN` in constants is non-empty |
+
+The runner does not pass `--permission-mode` or `--reasoning-effort`. If you
+invoke `grok` by hand outside the launcher, those CLI flags stay available on
+the binary; the batch path does not set them.
+
+---
+
+## Profile: `readonly`
+
+Batch field: `"tool_profile": "readonly"`.
+
+Extra flags the batch launcher appends:
+
+```
+--disallowed-tools Write,Edit,Bash
+```
+
+When `"is_repo_only": true`, also:
+
+```
+--disable-web-search
+```
+
+Prompt header prepended by the launcher:
+
+```
+Tool profile: readonly. Do not write, edit, or run shell commands.
+```
+
+Use for investigation, file:line mapping, and plan input. Pair with the
+read-only brief in `worker-briefs.md`.
+
+---
+
+## Profile: `build`
+
+Batch field: `"tool_profile": "build"`.
+
+Extra tool-restriction flags: none (full tool surface).
+
+Prompt header prepended by the launcher:
+
+```
+Tool profile: build. Never commit, push, or call gh.
+```
+
+Use for edits and tests inside a closed file allow list. Pair with the build
+brief in `worker-briefs.md`. The lead session owns git and `gh`.
+
+---
+
+## Leader socket rule
+
+Every process — preflight probes, live ping, and each worker — gets its own
+`--leader-socket` path under the run state directory.
+
+- Batch workers: `grok-leader-<uuid>.sock` (minted per launch)
+- Preflight auth probe: `grok-preflight-auth.sock`
+- Preflight ping: `grok-preflight-ping.sock`
+
+Never point two live processes at the same socket path.
+
+---
+
+## Stagger
+
+`WORKER_STAGGER_SECONDS` is `15`. Worker index `i` sleeps `i * 15` seconds
+before start (index 0 starts at once, index 1 after 15s, index 2 after 30s).
+The batch launcher applies this; you do not sleep in the skill.
+
+---
+
+## `--agent` and user-level Claude config
+
+When `agent_name` is set, the runner passes `--agent <name>`. Grok loads the
+named agent charter from the **user-level** Claude config home (`~/.claude/`):
+
+- `agents/` — agent definition files (for example `code-quality-agent.md`,
+  `clean-coder.md`)
+- `skills/`, `rules/`, `hooks/` — the rest of the installed Claude config the
+  grok CLI reads for that run
+
+Preflight role `bugteam` checks that `code-quality-agent.md` and
+`clean-coder.md` exist under `~/.claude/agents/` and that the
+`claude-dev-env` install manifest is present. Install or reinstall
+`claude-dev-env` before a fleet that relies on those agents.
+
+Pass `agent_name: null` (or omit the field) when the worker should run without
+a named agent charter.
+
+---
+
+## Profile choice cheat sheet
+
+| Work | `tool_profile` | `is_repo_only` | `agent_name` |
+|---|---|---|---|
+| Map call sites in-repo only | `readonly` | `true` | `null` or an audit agent |
+| Research that may need the web | `readonly` | `false` | `null` |
+| Closed edit + tests | `build` | ignored | often `clean-coder` |
+| Audit-style read under a charter | `readonly` | as needed | `code-quality-agent` |