diff --git a/.claude/skills/review-pr/SKILL.md b/.claude/skills/review-pr/SKILL.md new file mode 100644 index 00000000..c0bcc8b8 --- /dev/null +++ b/.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: +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. diff --git a/.codex/skills/speech-swift-benchmark b/.codex/skills/speech-swift-benchmark new file mode 120000 index 00000000..d43ef545 --- /dev/null +++ b/.codex/skills/speech-swift-benchmark @@ -0,0 +1 @@ +../../.claude/skills/benchmark \ No newline at end of file diff --git a/.codex/skills/speech-swift-build b/.codex/skills/speech-swift-build new file mode 120000 index 00000000..20266cf0 --- /dev/null +++ b/.codex/skills/speech-swift-build @@ -0,0 +1 @@ +../../.claude/skills/build \ No newline at end of file diff --git a/.codex/skills/speech-swift-review-pr b/.codex/skills/speech-swift-review-pr new file mode 120000 index 00000000..3cc4e71c --- /dev/null +++ b/.codex/skills/speech-swift-review-pr @@ -0,0 +1 @@ +../../.claude/skills/review-pr \ No newline at end of file diff --git a/.codex/skills/speech-swift-test b/.codex/skills/speech-swift-test new file mode 120000 index 00000000..a1ca03df --- /dev/null +++ b/.codex/skills/speech-swift-test @@ -0,0 +1 @@ +../../.claude/skills/test \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index d3ce604f..0687b024 100644 --- a/AGENTS.md +++ b/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- `, 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,6 +52,8 @@ 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 | @@ -51,6 +61,7 @@ Project skills in `.claude/skills/`: | `/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 ` | 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 |