From 76a3a763a51b63e894eb9e65b22cb43720cb88c7 Mon Sep 17 00:00:00 2001 From: Tommaso Casaburi Date: Thu, 23 Apr 2026 14:14:55 +0700 Subject: [PATCH] chore(ai tooling): sync harness configs --- .claude/skills/implement-plan/SKILL.md | 2 +- .claude/skills/profile-browsing/SKILL.md | 7 +++--- .claude/skills/test-apk/SKILL.md | 11 ++++----- .claude/skills/translate/SKILL.md | 4 ++-- .codex/skills/implement-plan/SKILL.md | 4 ++-- .codex/skills/profile-browsing/SKILL.md | 11 +++++---- .codex/skills/test-apk/SKILL.md | 2 +- .codex/skills/translate/SKILL.md | 2 +- .cursor/agents/profiler.md | 1 + .cursor/agents/test-apk.md | 1 + .cursor/skills/implement-plan/SKILL.md | 2 +- .cursor/skills/profile-browsing/SKILL.md | 7 +++--- .cursor/skills/test-apk/SKILL.md | 11 ++++----- .cursor/skills/translate/SKILL.md | 4 ++-- AGENTS.md | 1 + docs/agent-playbooks/hooks-setup.md | 4 ++-- docs/agent-playbooks/skills-and-tools.md | 1 + scripts/agent-init.sh | 29 +++++++++++++++++++++++- 18 files changed, 66 insertions(+), 38 deletions(-) diff --git a/.claude/skills/implement-plan/SKILL.md b/.claude/skills/implement-plan/SKILL.md index b705faba..0e0ba98c 100644 --- a/.claude/skills/implement-plan/SKILL.md +++ b/.claude/skills/implement-plan/SKILL.md @@ -47,7 +47,7 @@ Each subagent prompt must include: - **File paths** and context needed to work independently - **Constraints** or edge cases from the plan -Use `model: "fast"` for straightforward tasks. Omit model for complex ones. +Use the `plan-implementer` agent's configured model unless the harness explicitly requires a supported model override for a straightforward task. Omit overrides for complex or cross-cutting tasks. Wait for all subagents in a batch to complete before starting the next batch. diff --git a/.claude/skills/profile-browsing/SKILL.md b/.claude/skills/profile-browsing/SKILL.md index 4404e382..ab8e103b 100644 --- a/.claude/skills/profile-browsing/SKILL.md +++ b/.claude/skills/profile-browsing/SKILL.md @@ -54,16 +54,15 @@ Keep batches balanced. Add thread views (`/:boardIdentifier/thread/:cid`) as nee ## Step 2: Spawn Profiler Subagents -Read the profiler subagent definition at `.claude/agents/profiler.md`. Then spawn one `shell` Task per batch **in parallel** (single message, multiple Task calls): +Read the profiler subagent definition at `.claude/agents/profiler.md`. Then spawn one `profiler` Task per batch **in parallel** (single message, multiple Task calls): ``` For each batch, create a Task: - subagent_type: "shell" + subagent_type: "profiler" prompt: | - You are a performance profiler. Follow the workflow in .claude/agents/profiler.md. Session name: "prof-N" Routes to profile: /route1, /route2, ... - [Include the full profiler workflow from the agent file] + Any non-default app URL or extra profiling constraints ``` Spawn up to 4 subagents simultaneously. Each opens its own browser session, navigates routes, scrolls, collects both Web Vitals and react-scan data per route, and returns a structured issues list. diff --git a/.claude/skills/test-apk/SKILL.md b/.claude/skills/test-apk/SKILL.md index a4299e1f..47a26f3b 100644 --- a/.claude/skills/test-apk/SKILL.md +++ b/.claude/skills/test-apk/SKILL.md @@ -7,8 +7,8 @@ description: Test and debug Android APK features using a local Android emulator. ## Overview -Delegates APK testing to a **shell subagent** (`model: fast`) to keep the main context clean. -The subagent manages the emulator, builds/installs the APK, executes tests, and returns structured diagnostics. +Delegates APK testing to the dedicated `test-apk` subagent to keep the main context clean. +That subagent manages the emulator, builds and installs only when needed, executes the requested tests, and returns structured diagnostics. ## Workflow @@ -25,14 +25,13 @@ Ask the user (or infer from context) what to test. Common scenarios: | Manual APK interaction | Build, install, launch, capture logcat | | Contract tests (fixtures) | `yarn contract:postimages` | -### Step 2: Delegate to Shell Subagent +### Step 2: Delegate to the `test-apk` Subagent -Spawn a **shell** subagent with `model: fast`. Use the prompt template below, filling in `{TEST_DESCRIPTION}` with the user's requirements. +Spawn the `test-apk` subagent with the prompt template below, filling in `{TEST_DESCRIPTION}` with the user's requirements and any exact commands or classes you want run. ``` Use the Task tool: - subagent_type: "shell" - model: "fast" + subagent_type: "test-apk" prompt: ``` diff --git a/.claude/skills/translate/SKILL.md b/.claude/skills/translate/SKILL.md index 59baf00e..a3d550b8 100644 --- a/.claude/skills/translate/SKILL.md +++ b/.claude/skills/translate/SKILL.md @@ -28,7 +28,7 @@ For each key, check if the English value already exists in `public/translations/ ### Step 3 — Spawn translator subagents -For **each key**, spawn a `translator` subagent (using the Task tool with `subagent_type: "generalPurpose"` and `model: "fast"`). The prompt for each subagent must include: +For **each key**, spawn a `translator` subagent using the Task tool with `subagent_type: "translator"`. The prompt for each subagent must include: - The key name - The English value - An instruction to follow the translator subagent's system prompt @@ -45,7 +45,7 @@ Follow your system prompt for the full workflow (create dictionary file, dry run ``` **Parallelism rules:** -- Spawn up to 4 subagents concurrently (Task tool limit). +- Spawn up to 4 subagents concurrently. - If there are more than 4 keys, batch them: spawn 4, wait for completion, then spawn the next batch. ### Step 4 — Report results diff --git a/.codex/skills/implement-plan/SKILL.md b/.codex/skills/implement-plan/SKILL.md index 960aad58..dcadf525 100644 --- a/.codex/skills/implement-plan/SKILL.md +++ b/.codex/skills/implement-plan/SKILL.md @@ -39,7 +39,7 @@ Batch 3 (parallel): [tasks that depend on batch 2] ### 3. Execute Batches -For each batch, spawn `plan-implementer` subagents using Codex's current delegation tool and select the `plan-implementer` agent by name. +For each batch, spawn `plan-implementer` subagents using Codex's current delegation tool with `agent_type: "plan-implementer"`. Each subagent prompt must include: @@ -47,7 +47,7 @@ Each subagent prompt must include: - **File paths** and context needed to work independently - **Constraints** or edge cases from the plan -If your runtime supports model overrides, use a faster coding model only for straightforward tasks. Omit the override for complex or cross-cutting tasks. +Use the `plan-implementer` agent's configured model unless the harness explicitly requires a supported model override for a straightforward task. Omit overrides for complex or cross-cutting tasks. Wait for all subagents in a batch to complete before starting the next batch. diff --git a/.codex/skills/profile-browsing/SKILL.md b/.codex/skills/profile-browsing/SKILL.md index 1f4d374c..eaed2fe0 100644 --- a/.codex/skills/profile-browsing/SKILL.md +++ b/.codex/skills/profile-browsing/SKILL.md @@ -57,11 +57,12 @@ Keep batches balanced. Add thread views (`/:boardIdentifier/thread/:cid`) as nee Read the profiler subagent definition at `.codex/agents/profiler.toml`. Then spawn one `profiler` subagent per batch **in parallel** using Codex's current delegation tool: ``` -For each batch, create a subagent request that includes: - agent: "profiler" - Session name: "prof-N" - Routes to profile: /route1, /route2, ... - Any non-default app URL or extra profiling constraints +For each batch, create a subagent request: + agent_type: "profiler" + prompt: | + Session name: "prof-N" + Routes to profile: /route1, /route2, ... + Any non-default app URL or extra profiling constraints ``` Spawn up to 4 subagents simultaneously. Each opens its own browser session, navigates routes, scrolls, collects both Web Vitals and react-scan data per route, and returns a structured issues list. diff --git a/.codex/skills/test-apk/SKILL.md b/.codex/skills/test-apk/SKILL.md index 9ac3e0eb..ba6fa802 100644 --- a/.codex/skills/test-apk/SKILL.md +++ b/.codex/skills/test-apk/SKILL.md @@ -31,7 +31,7 @@ Spawn the `test-apk` subagent with the prompt template below, filling in `{TEST_ ``` Use Codex's current delegation tool: - agent: "test-apk" + agent_type: "test-apk" prompt: ``` diff --git a/.codex/skills/translate/SKILL.md b/.codex/skills/translate/SKILL.md index 683b8e83..6963eceb 100644 --- a/.codex/skills/translate/SKILL.md +++ b/.codex/skills/translate/SKILL.md @@ -28,7 +28,7 @@ For each key, check if the English value already exists in `public/translations/ ### Step 3 — Spawn translator subagents -For **each key**, spawn a `translator` subagent using Codex's current delegation tool. The prompt for each subagent must include: +For **each key**, spawn a `translator` subagent using Codex's current delegation tool with `agent_type: "translator"`. The prompt for each subagent must include: - The key name - The English value - An instruction to follow the translator subagent's system prompt diff --git a/.cursor/agents/profiler.md b/.cursor/agents/profiler.md index 6d855e8c..127a611b 100644 --- a/.cursor/agents/profiler.md +++ b/.cursor/agents/profiler.md @@ -1,5 +1,6 @@ --- name: profiler +model: composer-2 description: Performance profiler that browses 5chan routes via playwright-cli, collecting Web Vitals and React rerender data via react-scan. Returns a structured issues list for a batch of routes. Use proactively when profiling browsing performance, finding bottlenecks, or diagnosing excessive React rerenders. --- diff --git a/.cursor/agents/test-apk.md b/.cursor/agents/test-apk.md index 0db6c922..31954a7f 100644 --- a/.cursor/agents/test-apk.md +++ b/.cursor/agents/test-apk.md @@ -1,5 +1,6 @@ --- name: test-apk +model: composer-2 description: Android APK testing specialist that runs the 5chan APK on a local Android emulator. Manages emulator lifecycle, builds and installs debug APK, runs instrumentation tests, captures logcat diagnostics, and debugs WebView upload automation (imgur, postimages). Use proactively when the user asks to test APK features, debug Android uploads, run emulator tests, or investigate WebView automation issues. --- diff --git a/.cursor/skills/implement-plan/SKILL.md b/.cursor/skills/implement-plan/SKILL.md index b705faba..0e0ba98c 100644 --- a/.cursor/skills/implement-plan/SKILL.md +++ b/.cursor/skills/implement-plan/SKILL.md @@ -47,7 +47,7 @@ Each subagent prompt must include: - **File paths** and context needed to work independently - **Constraints** or edge cases from the plan -Use `model: "fast"` for straightforward tasks. Omit model for complex ones. +Use the `plan-implementer` agent's configured model unless the harness explicitly requires a supported model override for a straightforward task. Omit overrides for complex or cross-cutting tasks. Wait for all subagents in a batch to complete before starting the next batch. diff --git a/.cursor/skills/profile-browsing/SKILL.md b/.cursor/skills/profile-browsing/SKILL.md index 09e4dc16..3051f6d8 100644 --- a/.cursor/skills/profile-browsing/SKILL.md +++ b/.cursor/skills/profile-browsing/SKILL.md @@ -54,16 +54,15 @@ Keep batches balanced. Add thread views (`/:boardIdentifier/thread/:cid`) as nee ## Step 2: Spawn Profiler Subagents -Read the profiler subagent definition at `.cursor/agents/profiler.md`. Then spawn one `shell` Task per batch **in parallel** (single message, multiple Task calls): +Read the profiler subagent definition at `.cursor/agents/profiler.md`. Then spawn one `profiler` Task per batch **in parallel** (single message, multiple Task calls): ``` For each batch, create a Task: - subagent_type: "shell" + subagent_type: "profiler" prompt: | - You are a performance profiler. Follow the workflow in .cursor/agents/profiler.md. Session name: "prof-N" Routes to profile: /route1, /route2, ... - [Include the full profiler workflow from the agent file] + Any non-default app URL or extra profiling constraints ``` Spawn up to 4 subagents simultaneously. Each opens its own browser session, navigates routes, scrolls, collects both Web Vitals and react-scan data per route, and returns a structured issues list. diff --git a/.cursor/skills/test-apk/SKILL.md b/.cursor/skills/test-apk/SKILL.md index a4299e1f..47a26f3b 100644 --- a/.cursor/skills/test-apk/SKILL.md +++ b/.cursor/skills/test-apk/SKILL.md @@ -7,8 +7,8 @@ description: Test and debug Android APK features using a local Android emulator. ## Overview -Delegates APK testing to a **shell subagent** (`model: fast`) to keep the main context clean. -The subagent manages the emulator, builds/installs the APK, executes tests, and returns structured diagnostics. +Delegates APK testing to the dedicated `test-apk` subagent to keep the main context clean. +That subagent manages the emulator, builds and installs only when needed, executes the requested tests, and returns structured diagnostics. ## Workflow @@ -25,14 +25,13 @@ Ask the user (or infer from context) what to test. Common scenarios: | Manual APK interaction | Build, install, launch, capture logcat | | Contract tests (fixtures) | `yarn contract:postimages` | -### Step 2: Delegate to Shell Subagent +### Step 2: Delegate to the `test-apk` Subagent -Spawn a **shell** subagent with `model: fast`. Use the prompt template below, filling in `{TEST_DESCRIPTION}` with the user's requirements. +Spawn the `test-apk` subagent with the prompt template below, filling in `{TEST_DESCRIPTION}` with the user's requirements and any exact commands or classes you want run. ``` Use the Task tool: - subagent_type: "shell" - model: "fast" + subagent_type: "test-apk" prompt: ``` diff --git a/.cursor/skills/translate/SKILL.md b/.cursor/skills/translate/SKILL.md index 59baf00e..a3d550b8 100644 --- a/.cursor/skills/translate/SKILL.md +++ b/.cursor/skills/translate/SKILL.md @@ -28,7 +28,7 @@ For each key, check if the English value already exists in `public/translations/ ### Step 3 — Spawn translator subagents -For **each key**, spawn a `translator` subagent (using the Task tool with `subagent_type: "generalPurpose"` and `model: "fast"`). The prompt for each subagent must include: +For **each key**, spawn a `translator` subagent using the Task tool with `subagent_type: "translator"`. The prompt for each subagent must include: - The key name - The English value - An instruction to follow the translator subagent's system prompt @@ -45,7 +45,7 @@ Follow your system prompt for the full workflow (create dictionary file, dry run ``` **Parallelism rules:** -- Spawn up to 4 subagents concurrently (Task tool limit). +- Spawn up to 4 subagents concurrently. - If there are more than 4 keys, batch them: spawn 4, wait for completion, then spawn the next batch. ### Step 4 — Report results diff --git a/AGENTS.md b/AGENTS.md index f0f164bc..1f99d34f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -139,6 +139,7 @@ src/ - Treat `.codex/`, `.cursor/`, and `.claude/` as repo-managed contributor tooling, not private scratch space. - Keep equivalent workflow files aligned across all toolchains when their directories contain the same skill, hook, or agent. +- Keep shared behavior equivalent while preserving harness-specific models, config formats, hook entry points, and tool invocation syntax. - Do not configure `.claude` agents to use `composer-2`; that model is Cursor-only in this repo. Keep `.claude` agent models on Claude-supported options. - Do not configure `.codex/agents/*.toml` with `gpt-5.3-codex` or `gpt-5.3-codex-spark`; standardize Codex agents on `gpt-5.4` unless the user explicitly requests a different model. - When changing shared agent behavior, update the relevant files in `.codex/skills/`, `.cursor/skills/`, `.claude/skills/`, `.codex/agents/`, `.cursor/agents/`, `.claude/agents/`, `.codex/hooks/`, `.cursor/hooks/`, `.claude/hooks/`, and their `hooks.json` or config entry points as needed. diff --git a/docs/agent-playbooks/hooks-setup.md b/docs/agent-playbooks/hooks-setup.md index 1b4e8760..c5a0ea5b 100644 --- a/docs/agent-playbooks/hooks-setup.md +++ b/docs/agent-playbooks/hooks-setup.md @@ -20,7 +20,7 @@ If your AI coding assistant supports lifecycle hooks, configure these for this r - New `useEffect`/memo additions get an explicit second look before the agent finishes - Build/lint/type issues caught early - Security visibility via `corepack yarn npm audit` -- One shared hook implementation for both Codex and Cursor +- One shared hook implementation for Codex, Cursor, and Claude - Temporary task branches stay aligned with the repo's worktree workflow ## Example Hook Scripts @@ -85,4 +85,4 @@ exit 0 Configure hook wiring according to your agent tool docs (`hooks.json`, equivalent, etc.). -In this repo, `.codex/hooks/*.sh` and `.cursor/hooks/*.sh` should stay as thin wrappers that delegate to the shared implementations under `scripts/agent-hooks/`. +In this repo, `.codex/hooks/*.sh`, `.cursor/hooks/*.sh`, and `.claude/hooks/*.sh` should stay as thin wrappers that delegate to the shared implementations under `scripts/agent-hooks/`. Harness-specific startup hooks such as Claude's `SessionStart` can live alongside those wrappers when the other harnesses do not have an equivalent entry point. diff --git a/docs/agent-playbooks/skills-and-tools.md b/docs/agent-playbooks/skills-and-tools.md index 717dc1c2..e22c9069 100644 --- a/docs/agent-playbooks/skills-and-tools.md +++ b/docs/agent-playbooks/skills-and-tools.md @@ -54,6 +54,7 @@ playwright-cli install --skills Skill install locations: +- `.codex/skills/playwright-cli/` - `.cursor/skills/playwright-cli/` - `.claude/skills/playwright-cli/` diff --git a/scripts/agent-init.sh b/scripts/agent-init.sh index 48958356..9d0b4ba2 100755 --- a/scripts/agent-init.sh +++ b/scripts/agent-init.sh @@ -4,7 +4,34 @@ set -euo pipefail run_smoke=0 wait_timeout="${AGENT_INIT_TIMEOUT_SECONDS:-60}" -app_url="${AGENT_APP_URL:-http://5chan.localhost:1355}" + +get_default_app_url() { + if [ "${PORTLESS:-}" = "0" ]; then + echo "http://5chan.localhost:1355" + return + fi + + local branch branch_label + + branch="$(git branch --show-current 2>/dev/null || true)" + + if [ -n "$branch" ] && [ "$branch" != "master" ] && [ "$branch" != "main" ]; then + branch_label="$( + printf '%s' "$branch" \ + | tr '[:upper:]' '[:lower:]' \ + | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-+/-/g' + )" + + if [ -n "$branch_label" ]; then + echo "http://${branch_label}.5chan.localhost:1355" + return + fi + fi + + echo "http://5chan.localhost:1355" +} + +app_url="${AGENT_APP_URL:-$(get_default_app_url)}" while [ "$#" -gt 0 ]; do case "$1" in