Add communication guidelines and PR review skill

.claude/skills/review-pr/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: review-pr
+description: Review a pull request for conceptual fit, architecture impact, adversarial failure modes, security risk, docs impact, regression risk, test coverage, and merge readiness. Use when asked to review a PR, check whether a PR is safe to merge, decide if more tests are needed, perform adversarial or security review, or summarize PR risk.
+disable-model-invocation: false
+argument-hint: <PR number or URL>
+allowed-tools: Bash
+---
+
+# Review PR
+
+Review the PR from the user's point of view: make the decision easy, then provide detail only when it changes the decision.
+
+## Workflow
+
+1. Inspect PR metadata, files, diff, and checks.
+2. Read the touched code and nearby architecture boundaries.
+3. Identify whether the change is a behavior change, performance change, refactor, test-only change, docs-only change, or CI/infrastructure change.
+4. Run the required review passes:
+   - architecture fit: does the change match existing module boundaries and project patterns;
+   - adversarial review: what breaks under edge cases, bad inputs, scale, concurrency, cancellation, cache misses, offline mode, or hosted runner differences;
+   - security review: secrets, tokens, path traversal, unsafe downloads, sandbox escapes, user-controlled file paths, network exposure, dependency risk, and data leakage;
+   - docs review: local docs, public site docs, README translations, CLI help, model tables, benchmark pages, and migration notes when behavior is user-visible.
+5. Assess regression risk from the changed behavior and blast radius.
+6. Decide whether existing tests are enough. Include E2E coverage for runtime/model/user-facing behavior, or explicitly state why E2E is not applicable. Add or request tests only when they protect a real risk.
+7. Run the smallest meaningful validation:
+   - unit tests for logic and data structures;
+   - focused E2E for model/runtime behavior;
+   - CLI probe or benchmark only when the PR changes user-facing runtime behavior or performance.
+8. End with a short merge recommendation.
+
+## Output Shape
+
+Start with this format unless the user asks for a detailed code review:
+
+```md
+Status: ready / not ready / needs follow-up
+
+What changed:
+...
+
+Architecture fit:
+...
+
+Adversarial/security/docs:
+Adversarial: ...
+Security: ...
+Docs: ...
+
+Regression risk:
+Low / medium / high, with one-sentence reason.
+
+Tests:
+Unit: ...
+E2E: ...
+Needed: ...
+
+Recommendation:
+Merge / request changes / investigate first.
+```
+
+## Review Rules
+
+- Lead with blockers if any exist.
+- Keep conceptual summary above command details.
+- Do not paste logs unless asked.
+- Be adversarial about failure modes, but do not invent blockers without evidence.
+- Treat security and docs as explicit review passes, even when the conclusion is "no impact."
+- Always report E2E tests run. If none were run, state the reason and whether that is acceptable.
+- Do not add slow permanent E2E tests just to prove a local probe; add permanent tests when they guard realistic future regressions.
+- Prefer same-input comparison against `main` for performance or refactor PRs when output preservation matters.
+- Treat model download, cache, and hosted runner failures as infrastructure unless code behavior caused them.
+- For public API, CLI flags, model variants, or docs-visible behavior, call out required docs updates.
+- For README changes, verify all translated README files are updated.

.codex/skills/speech-swift-benchmark

@@ -0,0 +1 @@
+../../.claude/skills/benchmark

.codex/skills/speech-swift-build

@@ -0,0 +1 @@
+../../.claude/skills/build

.codex/skills/speech-swift-review-pr

@@ -0,0 +1 @@
+../../.claude/skills/review-pr

.codex/skills/speech-swift-test

@@ -0,0 +1 @@
+../../.claude/skills/test

AGENTS.md

@@ -2,6 +2,14 @@
 
 AI speech models for Apple Silicon (MLX Swift). ASR, TTS, speech-to-speech, VAD, diarization, speech enhancement.
 
+## Communication Style
+
+- Communicate at the conceptual level first: what changed, why it matters, risk, tests, and recommendation.
+- Keep status updates short and understandable. Do not dump command logs, low-level mechanics, or long implementation detail unless directly asked.
+- For PRs and fixes, default to this summary shape: what changed, architecture fit, regression risk, tests run or needed, and recommendation.
+- If there are bugs, blockers, or regression risks, lead with them clearly and briefly.
+- When the user asks a direct question, answer it directly before adding supporting detail.
+
 ## Workflow
 
 - **Always work in a separate git worktree** so concurrent agents don't fight over the same working directory. Create one with `git worktree add ../speech-swift-<task> <branch>`, do all edits there, push from there. Multiple agents may be running against this repo at the same time — checking out branches in the shared working copy clobbers their state and silently loses WIP files. Delete the worktree (`git worktree remove`) when the task is done.
@@ -44,13 +52,16 @@ The metallib step compiles MLX Metal shaders — without it, inference runs ~5x
 
 Project skills in `.claude/skills/`:
 
+The same skills are exposed to agents that scan `.codex/skills/` through relative symlinks; keep both paths in sync when adding or renaming a project skill.
+
 | Command | Description |
 |---------|-------------|
 | `/build` or `/build release` | Release build with metallib |
 | `/build debug` | Debug build |
 | `/test` or `/test unit` | Run unit tests (skip E2E) |
 | `/test e2e` | Full test suite with model downloads |
 | `/test FilterName` | Run specific test filter |
+| `/review-pr <PR>` | Review PR architecture fit, regression risk, tests, and merge readiness |
 | `/benchmark asr` | Benchmark ASR speed |
 | `/benchmark tts` | Benchmark TTS speed |
 | `/benchmark vad` | VAD benchmark on VoxConverse |