project-guardrails

Étoiles3

Forks2

Mis à jour29 juillet 2026 à 21:24

Blurt's hard "don't do this" rules — architecture decisions that were made deliberately and reverted before. Load this before adding or changing engine/app/build/test code so you don't reintroduce something that was intentionally removed.

Installation

Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.

Source

AssemblyAI

AssemblyAI/blurt

Ouvrir le dépôt GitHub Voir les dépôts du créateur

Téléchargement

Métiers associésSOC

Basé sur la classification professionnelle SOC

Développeurs de logicielsProfessions informatiques et mathématiques·SOC 15-1252

SKILL.md

readonly

name	project-guardrails
description	Blurt's hard "don't do this" rules — architecture decisions that were made deliberately and reverted before. Load this before adding or changing engine/app/build/test code so you don't reintroduce something that was intentionally removed.
user-invocable	false

Blurt guardrails

These are settled decisions. Don't reintroduce them; if a task seems to require one, stop and ask the user first. This is the fast "don't" list; AGENTS.md's "Settled decisions" table is the fuller reference and the source of truth.

Audio

No AVAudioEngine / installTap capture path. MicCapture uses AVAudioRecorder with a fresh recorder per session on purpose — a long-lived engine bound its input graph to one device and went stale on a mic↔built-in switch (-10868, all-zero buffers). Keep recording to a 16 kHz mono 16-bit WAV (the Sync API's geometry) so stop() reads it back with no resample pass.

Transcription pipeline

No streaming STT. The AssemblyAI Sync API returns the full transcript in one response. Overlay goes "Transcribing…" → full text.
No separate LLM cleanup pass. Cleanup rides in the Sync STT request's config.prompt (TranscriptionPrompt). No LLM Gateway client, no StylerProtocol, no post-transcription styling stage.
No local models / model downloads. Transcription is a remote AssemblyAI call. No on-device ASR/LLM, no model cache, no download UI.
Don't reintroduce a "remove filler words (um, uh, like)" directive in the prompt — universal-3-5-pro ignores it; it was deliberately dropped. Same for a language directive: pinning the prompt to English hurt non-English speech, so language is left to the model's own detection.
Injection is always a clipboard paste (save → write → ⌘V → settle → restore), degrading to "left it on the clipboard" when the target is lost. No keystroke-by-keystroke typing path, no length threshold.

App shape

Dock app first — no LSUIElement, no menu-bar-only mode. Blurt has a MenuBarExtra status item (dictation indicator + hotkey discoverability menu, in MenuBar/MenuBarScene.swift) layered on the Dock icon. Keep the Dock icon as the guaranteed entry point: the notch can hide a status item on a crowded menu bar, so nothing may depend on it being visible. A menu-bar-only variant (no Dock icon) was tried and reverted twice for that reason — don't drop the Dock icon or add LSUIElement.
The dictation trigger is a single lone modifier (right ⌘ default), home- grown via CGEventTap + DictationKeyGate. No KeyboardShortcuts package, no key+modifier chord.
Updates are download-only — check → open the DMG in the browser → the user installs it. The mxcl/AppUpdater dependency and its in-place self-updater were removed; don't reintroduce a self-replacing install path, a timer-driven poll, or anything that installs on the user's behalf. Checking automatically once at launch on a configured app (AutomaticUpdateCheck, ≤ once a day, silent unless a newer release exists) is the one automatic part, and it still ends in the same Download/Later alert. Extend UpdateChecker / UpdateCheckModel.

Build / tests

Don't hand-edit App/Blurt/Blurt.xcodeproj/project.pbxproj — it's generated from project.yml; edit that and run xcodegen generate. check.sh fails on pbxproj drift (a PreToolUse hook also blocks edits to it).
The engine has no external SPM dependencies (Foundation/Security/ AVFoundation only). Don't add one to Sources/BlurtEngine/.
Unit tests use Swift Testing, not XCTest (the BlurtUITests XCUITest bundle is the one exception — XCUIAutomation requires XCTest). Never touch the real Keychain in tests — APIKeyStore is the production item; use an isolated service like KeychainStoreTests does (or InMemoryAPIKeyStore), or you'll trigger Keychain password prompts and corrupt the real item's ACL.
UI-test-facing strings (identifiers, window titles, launch arguments, sentinel keys) live once in App/Blurt/Shared/UITestIdentifiers.swift, compiled into both the app and the test bundle. Don't re-add mirrored copies in BlurtUITests/.
Don't redirect the post-build install away from /Applications — TCC won't register apps in DerivedData//tmp, so permission toggles never appear.
Don't add backwards-compat shims for removed types.

Notarization

Every nested mach-o and embedded framework must be signed with the hardened runtime and a secure timestamp (--options runtime --timestamp), or notarization rejects the build. release-build.sh re-signs frameworks for this — don't remove it.

Plus depuis ce dépôt

même dépôt

release

AssemblyAI/blurt

Cut and publish a Blurt release (build, sign, notarize, staple, DMG, GitHub). Use when the user asks to ship/release a new version. User-invoked only — it has real side effects (notarization, git tags, GitHub release).

2026-07-283

check

AssemblyAI/blurt

Verify the repo is green by running scripts/check.sh — the same full health check CI runs (swift test + coverage gate, sanitizers, xcodegen drift, app build, swift-format/swiftlint/periphery/prettier/markdownlint/shellcheck). Use before claiming a change builds, passes, or is ready to commit/PR. Bakes in the macOS-only guard so a Linux/web sandbox flags "verify on a Mac" instead of fabricating a green result; there, scripts/check.sh --portable runs the platform-independent subset (docs/site/scripts/workflows).

2026-07-273

launch-metrics

AssemblyAI/blurt

Print a daily Blurt launch KPI snapshot — Blurt.dmg download count, GitHub stars, and repo traffic/referrers — and compare against the campaign's baseline/good/great bands. Use during launch week, or wrap with /loop for a recurring check.

2026-07-013

Blurt guardrails

Audio

No AVAudioEngine / installTap capture path. MicCapture uses AVAudioRecorder with a fresh recorder per session on purpose — a long-lived engine bound its input graph to one device and went stale on a mic↔built-in switch (-10868, all-zero buffers). Keep recording to a 16 kHz mono 16-bit WAV (the Sync API's geometry) so stop() reads it back with no resample pass.

Transcription pipeline

No streaming STT. The AssemblyAI Sync API returns the full transcript in one response. Overlay goes "Transcribing…" → full text.

No separate LLM cleanup pass. Cleanup rides in the Sync STT request's config.prompt (TranscriptionPrompt). No LLM Gateway client, no StylerProtocol, no post-transcription styling stage.

No local models / model downloads. Transcription is a remote AssemblyAI call. No on-device ASR/LLM, no model cache, no download UI.

Don't reintroduce a "remove filler words (um, uh, like)" directive in the prompt — universal-3-5-pro ignores it; it was deliberately dropped. Same for a language directive: pinning the prompt to English hurt non-English speech, so language is left to the model's own detection.

Injection is always a clipboard paste (save → write → ⌘V → settle → restore), degrading to "left it on the clipboard" when the target is lost. No keystroke-by-keystroke typing path, no length threshold.

App shape

Dock app first — no LSUIElement, no menu-bar-only mode. Blurt has a MenuBarExtra status item (dictation indicator + hotkey discoverability menu, in MenuBar/MenuBarScene.swift) layered on the Dock icon. Keep the Dock icon as the guaranteed entry point: the notch can hide a status item on a crowded menu bar, so nothing may depend on it being visible. A menu-bar-only variant (no Dock icon) was tried and reverted twice for that reason — don't drop the Dock icon or add LSUIElement.

The dictation trigger is a single lone modifier (right ⌘ default), home- grown via CGEventTap + DictationKeyGate. No KeyboardShortcuts package, no key+modifier chord.

Updates are download-only — check → open the DMG in the browser → the user installs it. The mxcl/AppUpdater dependency and its in-place self-updater were removed; don't reintroduce a self-replacing install path, a timer-driven poll, or anything that installs on the user's behalf. Checking automatically once at launch on a configured app (AutomaticUpdateCheck, ≤ once a day, silent unless a newer release exists) is the one automatic part, and it still ends in the same Download/Later alert. Extend UpdateChecker / UpdateCheckModel.

Build / tests

Don't hand-edit App/Blurt/Blurt.xcodeproj/project.pbxproj — it's generated from project.yml; edit that and run xcodegen generate. check.sh fails on pbxproj drift (a PreToolUse hook also blocks edits to it).

The engine has no external SPM dependencies (Foundation/Security/ AVFoundation only). Don't add one to Sources/BlurtEngine/.

Unit tests use Swift Testing, not XCTest (the BlurtUITests XCUITest bundle is the one exception — XCUIAutomation requires XCTest). Never touch the real Keychain in tests — APIKeyStore is the production item; use an isolated service like KeychainStoreTests does (or InMemoryAPIKeyStore), or you'll trigger Keychain password prompts and corrupt the real item's ACL.

UI-test-facing strings (identifiers, window titles, launch arguments, sentinel keys) live once in App/Blurt/Shared/UITestIdentifiers.swift, compiled into both the app and the test bundle. Don't re-add mirrored copies in BlurtUITests/.

Don't redirect the post-build install away from /Applications — TCC won't register apps in DerivedData//tmp, so permission toggles never appear.

Don't add backwards-compat shims for removed types.

Notarization

Every nested mach-o and embedded framework must be signed with the hardened runtime and a secure timestamp (--options runtime --timestamp), or notarization rejects the build. release-build.sh re-signs frameworks for this — don't remove it.