Anybox 前端规范

核心流程

1. 修改前先阅读目标 UI 代码。优先沿用已有组件结构、class 命名、CSS 归属和 token 用法，不要先发明新抽象。
2. 只读取当前任务需要的 reference：
   • 产品整体风格：references/principles.md
   • token、CSS 归属、主题规则：references/tokens-and-css.md
   • shell、pane、sidebar、surface：references/layout-and-surfaces.md
   • 按钮、菜单、控件、列表行：references/controls-and-menus.md
   • 槽位式卡片列表交互：references/slot-card-list.md
   • ThreadView、trace、side chat、composer 嵌套：references/thread-view.md
   • 设置、插件、MCP、global skills 页面：references/settings-and-management.md
   • UI 修改完成前检查：references/implementation-checklist.md
3. 以本地项目文件为事实来源。常用入口：
   • C:/Projects/Anybox/packages/desktop/src/renderer/src/styles/tokens.css
   • C:/Projects/Anybox/packages/desktop/src/renderer/src/styles/primitives.css
   • C:/Projects/Anybox/packages/desktop/src/renderer/src/styles/shell.css
   • C:/Projects/Anybox/packages/desktop/src/renderer/src/styles/sidebar.css
   • C:/Projects/Anybox/packages/desktop/src/renderer/src/styles/workbench.css
   • C:/Projects/Anybox/packages/desktop/src/renderer/src/styles/thread.css
   • C:/Projects/Anybox/packages/desktop/src/renderer/src/styles/composer.css
   • C:/Projects/Anybox/packages/desktop/src/renderer/src/styles/settings.css
   • C:/Projects/Anybox/packages/desktop/src/renderer/src/styles/responsive.css
4. 保持改动范围收敛。优先改 token 或局部语义 class，不要追加文件末尾的大范围覆盖规则。
5. 最终回复前检查亮色/暗色主题、窄窗口、键盘焦点、溢出和相关测试。

撰写 UI 规范的元规则

新增或改写本 skill 的 UI 组件/交互 reference 时，必须让规范自包含这些主题与 token 约束，不要只依赖通用 token 文档：

• 明确 light 和 dark 双主题都必须支持。
• 明确组件 CSS 只消费不带 -light / -dark 后缀的运行时 token。
• 明确 semantic token 的命名、fallback 与 light/dark 映射规则。
• 明确缺少合适 token 时，先在 tokens.css 补充成对 light/dark semantic token，再暴露运行时 token 给组件使用。
• 明确 default、hover、focus、active、disabled、selected/current、error/invalid 等状态都要在明暗主题下可读。
• 明确禁止硬编码颜色和硬编码 fallback，例如 #fff、#000、固定灰色、固定品牌色或 rgba(...)。
• 明确 focus 使用组件自身的背景、边框、文字、指示器等 token 化状态表达，不使用 outline 或 inset ring。

项目文档来源

任务涉及对应区域时读取这些项目文档：

• C:/Projects/Anybox/docs/thread-view-frontend-design.md
• C:/Projects/Anybox/docs/thread-view-render-flow.html
• C:/Projects/Anybox/packages/desktop/anybox-mobile-client-design-plan.md
• C:/Projects/Anybox/docs/todo-calendar-design.md

如果 UI 行为变更导致这些文档过期，需要在同一次改动里同步更新。

Anybox Mobile Release

Core Rule

Use the mobile-only GitHub Release flow:

• Tags must start with mobile-v, for example mobile-v0.2.0.
• Release assets must include anybox-mobile.apk and anybox-mobile-release.json.
• Do not use releases/latest for mobile update checks; desktop releases can become latest.
• The mobile app checks GitHub Releases API and filters only mobile-v* tags.

Workflow

1. Work from the repository root, normally C:\Projects\fanfande_studio.
2. Inspect current mobile config in packages/mobile-app/app.json.
3. For a native APK release, bump:
   • expo.version
   • expo.android.versionCode with a strictly increasing integer.
4. Build or confirm the APK:

   corepack pnpm mobile:android:build:debug
   

5. Generate GitHub Release assets:

   corepack pnpm mobile:release:github:prepare -- --notes "Release note"
   

6. Upload the generated files from packages/mobile-app/build/github-release/ to a GitHub Release whose tag matches the printed mobile-v* tag.
7. Run verification:

   corepack pnpm --filter anybox-mobile-app typecheck
   corepack pnpm --filter anybox-mobile-app exec expo install --check
   

Fast Path

Before rebuilding, use the fastest checks to avoid repeating slow work:

1. Check whether the existing APK is fresh:

   corepack pnpm mobile:android:delivery-check -- --strict --no-manifest
   

   If APK freshness passes and the version/tag is still correct, reuse packages/mobile-app/build/anybox-mobile-debug.apk.
2. On Windows, set the known local toolchain before Android builds:

   $env:JAVA_HOME="$env:LOCALAPPDATA\AnyboxMobile\AndroidToolchain\jdk-17"
   $env:ANDROID_HOME="$env:LOCALAPPDATA\Android\Sdk"
   $env:ANDROID_SDK_ROOT=$env:ANDROID_HOME
   $env:ANDROID_NDK_HOME="$env:ANDROID_HOME\ndk\27.1.12297006"
   $env:ANDROID_NDK_ROOT=$env:ANDROID_NDK_HOME
   $env:PATH="$env:JAVA_HOME\bin;$env:ANDROID_HOME\platform-tools;$env:ANDROID_HOME\cmdline-tools\latest\bin;$env:PATH"
   

3. If Gradle reports a broken NDK such as ndk\27.0.12077973 missing source.properties, move that incomplete SDK directory out of Android\Sdk\ndk after verifying it only contains installer residue.
4. Avoid --clean unless generated native files are corrupt. A clean prebuild can add many minutes. If prebuild already produced android/ and index.android.bundle, continue with direct Gradle:

   .\gradlew.bat --no-daemon --console=plain assembleDebug
   

   Then copy android/app/build/outputs/apk/debug/app-debug.apk to packages/mobile-app/build/anybox-mobile-debug.apk.
5. GitHub APK uploads are slow for ~170 MB files. Use long timeouts. If gh release create times out and leaves a draft release, do not recreate blindly; inspect it, upload missing assets with gh release upload, then publish with gh release edit --draft=false.

Decision Points

• For JS/style/business logic only, prefer EAS Update if configured.
• For Android permissions, native dependencies, Expo SDK changes, android/, or app metadata changes, publish a new mobile APK release.
• If the user wants GitHub-only updates, keep EAS project ID unset; mobile APK checks still work through GitHub Releases.
• If publishing is requested and GitHub CLI is available, use the gh release create ... command printed by the prepare script. Otherwise report the exact files and tag to upload manually.

Reference

Read references/github-mobile-release.md when the task needs exact asset names, manifest fields, release command shape, or troubleshooting details.

腾讯云 Docker 部署 anyboxProvider

概览

这个 skill 固定用于当前项目的腾讯云部署流程：

• 本地项目目录：C:\Projects\anyboxProvider
• 服务器 SSH 别名：anybox-server
• 服务器实际地址：ubuntu@129.211.1.144
• 服务器部署根目录：/home/ubuntu/
• 服务器项目目录：/home/ubuntu/anyboxProvider
• 部署方式：docker-compose.tencent.yml 和 scripts/tencent-deploy.sh

采用简单优先策略：本地维护并上传 .env.tencent。不要上传 .env、node_modules、dist 或 .git。

部署前检查

先确认服务器上的 Docker 可用：

ssh anybox-server 'docker --version && docker compose version && docker ps'

如果本地 shell 没有配置好 SSH，就让用户在 VS Code 远程终端里手动执行上面的检查命令，不要临时改用其他服务器或其他部署目标。

打包并上传

在本地 Windows PowerShell 中执行：

cd C:\Projects

tar -czf anyboxProvider.tar.gz `
  --exclude=anyboxProvider/node_modules `
  --exclude=anyboxProvider/dist `
  --exclude=anyboxProvider/.env `
  --exclude=anyboxProvider/.git `
  anyboxProvider

scp .\anyboxProvider.tar.gz anybox-server:/home/ubuntu/

如果本地已有旧的压缩包，只能删除 C:\Projects\anyboxProvider.tar.gz，不要删除源项目文件。

在服务器解压

在腾讯云服务器上执行：

cd /home/ubuntu

if [ -d anyboxProvider ]; then
  mv anyboxProvider "anyboxProvider.backup.$(date +%Y%m%d-%H%M%S)"
fi

tar -xzf anyboxProvider.tar.gz
cd anyboxProvider

如果用户临时决定不上传 .env.tencent，更新部署时需要从旧备份复制回来：

cp ../anyboxProvider.backup.*/.env.tencent .env.tencent 2>/dev/null || true

如果存在多个备份目录，显式选择最新的备份目录，不要依赖通配符。

配置生产环境变量

简单优先时，先在本地 C:\Projects\anyboxProvider\.env.tencent 填好生产配置，然后随压缩包一起上传。若本地还没有该文件，先在本地复制模板：

cd C:\Projects\anyboxProvider
Copy-Item .env.tencent.example .env.tencent
notepad .env.tencent

如果要在服务器上直接编辑，也可以执行：

cp .env.tencent.example .env.tencent
nano .env.tencent

至少替换这些值：

APP_DOMAIN=你的域名
APP_BASE_URL=https://你的域名

POSTGRES_PASSWORD=<随机 hex>
DATABASE_URL=postgres://anybox:<同一个 PostgreSQL 密码>@postgres:5432/anybox_provider

REDIS_PASSWORD=<随机 hex>
REDIS_URL=redis://:<同一个 Redis 密码>@redis:6379

SESSION_SECRET=<随机 hex>
ENCRYPTION_KEY=<随机 hex，必须稳定保存和备份>
METRICS_TOKEN=<随机 hex>
ADMIN_TOKEN=<随机 hex>

ADMIN_BOOTSTRAP_EMAIL=<管理员邮箱>
ADMIN_BOOTSTRAP_PASSWORD=<初始管理员密码>

DEFAULT_PROVIDER_API_KEY=<上游模型供应商 API Key>

生成随机值：

openssl rand -hex 32

生产环境不能保留 change_me 或 replace_me 这类占位值。ENCRYPTION_KEY 必须长期保存；丢失后，数据库里已加密的供应商凭据将无法解密。.env.tencent 包含生产密钥，不能提交到 Git，也不要把压缩包发给别人。

执行部署

在 /home/ubuntu/anyboxProvider 中执行：

chmod +x scripts/tencent-deploy.sh
./scripts/tencent-deploy.sh

首次部署时，执行一次初始化管理员：

docker compose -f docker-compose.tencent.yml --env-file .env.tencent --profile tools run --rm seed

初始化完成后，清空 bootstrap 密码并重启运行服务：

nano .env.tencent
docker compose -f docker-compose.tencent.yml --env-file .env.tencent up -d api worker

重启前把这一项改为空：

ADMIN_BOOTSTRAP_PASSWORD=

验证部署

检查容器和接口：

docker compose -f docker-compose.tencent.yml --env-file .env.tencent ps
curl -fsS http://127.0.0.1/livez
curl -fsS https://$APP_DOMAIN/livez
curl -fsS https://$APP_DOMAIN/readyz

如果验证失败，查看日志：

docker compose -f docker-compose.tencent.yml --env-file .env.tencent logs --tail=200 api
docker compose -f docker-compose.tencent.yml --env-file .env.tencent logs --tail=200 caddy
docker compose -f docker-compose.tencent.yml --env-file .env.tencent logs --tail=200 worker

同时确认腾讯云安全组已放行 TCP 80 和 443，域名 A 记录已经指向 129.211.1.144。

更新已有部署

当本地 C:\Projects\anyboxProvider 有代码改动，要同步到服务器时，按这个标准流程执行。默认采用简单优先策略：本地 .env.tencent 是生产配置的来源，会随压缩包一起覆盖服务器上的 .env.tencent。

1. 本地确认

在本地 PowerShell 中确认 .env.tencent 存在，不要把 .env 当作生产配置上传：

Test-Path C:\Projects\anyboxProvider\.env.tencent

如果返回 False，先创建并填写：

cd C:\Projects\anyboxProvider
Copy-Item .env.tencent.example .env.tencent
notepad .env.tencent

2. 重新打包

在本地 PowerShell 中执行：

cd C:\Projects

if (Test-Path .\anyboxProvider.tar.gz) {
  Remove-Item .\anyboxProvider.tar.gz
}

tar -czf anyboxProvider.tar.gz `
  --exclude=anyboxProvider/node_modules `
  --exclude=anyboxProvider/dist `
  --exclude=anyboxProvider/.env `
  --exclude=anyboxProvider/.git `
  anyboxProvider

上传前可以确认压缩包已生成：

Get-Item C:\Projects\anyboxProvider.tar.gz

3. 上传压缩包

scp C:\Projects\anyboxProvider.tar.gz anybox-server:/home/ubuntu/

上传后可远程确认：

ssh anybox-server "ls -lh /home/ubuntu/anyboxProvider.tar.gz"

4. 服务器备份旧项目并解压新版本

在服务器执行：

cd /home/ubuntu

if [ -d anyboxProvider ]; then
  mv anyboxProvider "anyboxProvider.backup.$(date +%Y%m%d-%H%M%S)"
fi

tar -xzf anyboxProvider.tar.gz
cd anyboxProvider

不要删除 Docker volume。PostgreSQL 和 Redis 的数据保存在 Docker volume 里，更新代码时只替换项目目录。

如果这次不想用本地 .env.tencent 覆盖服务器配置，需要在本地打包时额外排除 .env.tencent，然后从最新备份恢复：

cp /home/ubuntu/anyboxProvider.backup.YYYYMMDD-HHMMSS/.env.tencent /home/ubuntu/anyboxProvider/.env.tencent

5. 执行部署脚本

在服务器执行：

cd /home/ubuntu/anyboxProvider
./scripts/tencent-deploy.sh

脚本会重新构建镜像、启动数据库和 Redis、运行迁移，并启动 api、worker、caddy。

6. 验证

docker compose -f docker-compose.tencent.yml --env-file .env.tencent ps
curl -fsS http://127.0.0.1/livez
curl -fsS http://127.0.0.1/readyz

如果域名已经解析并开放 80/443，再验证公网 HTTPS：

curl -fsS https://你的域名/livez
curl -fsS https://你的域名/readyz

失败时先看日志：

docker compose -f docker-compose.tencent.yml --env-file .env.tencent logs --tail=200 api
docker compose -f docker-compose.tencent.yml --env-file .env.tencent logs --tail=200 worker
docker compose -f docker-compose.tencent.yml --env-file .env.tencent logs --tail=200 caddy

7. 什么时候需要 seed

更新代码时通常不要再运行 seed。seed 只在首次初始化管理员账号和演示数据时运行一次。重复运行可能创建额外 demo workspace。

Anybox 腾讯云服务器侧部署

范围

只处理服务器侧流程。不要执行本地打包、scp 上传、生成 anyboxProvider.tar.gz，也不要用本地 .env.tencent 覆盖服务器生产配置。

固定环境：

• SSH 别名：anybox-server
• 服务器用户：ubuntu
• 服务器项目目录：/home/ubuntu/anyboxProvider
• 可选已上传压缩包：/home/ubuntu/anyboxProvider.tar.gz
• Compose 文件：docker-compose.tencent.yml
• 部署脚本：scripts/tencent-deploy.sh
• 生产域名：anybox.com.cn

安全规则

• 不要删除 Docker volumes，不要运行 docker compose down -v。
• 默认保留服务器上的 .env.tencent，只做脱敏检查，不输出密钥。
• ADMIN_BOOTSTRAP_PASSWORD 只允许首次 seed 前临时设置；seed 完成后必须清空。
• 重复运行 seed 会创建新的 Demo Workspace；只在首次初始化管理员或用户明确要求时运行。
• 停止宿主机 nginx 前先确认它是否是旧的 anyboxProvider 反代，不要盲停无关站点。

部署前检查

确认 SSH、Docker、Compose 可用：

ssh anybox-server "hostname; docker --version; docker compose version"

检查当前容器、端口和旧 nginx：

ssh anybox-server "cd /home/ubuntu/anyboxProvider 2>/dev/null && docker compose -f docker-compose.tencent.yml --env-file .env.tencent ps || true; sudo ss -ltnp '( sport = :80 or sport = :443 )' || true; systemctl is-active nginx || true"

检查服务器 .env.tencent 是否存在，并只输出关键项状态：

ssh anybox-server 'cd /home/ubuntu/anyboxProvider && test -f .env.tencent && echo env_exists || echo env_missing'

备份并切换新版本

如果 /home/ubuntu/anyboxProvider.tar.gz 已经在服务器上，按这个流程切换项目目录，并从旧目录恢复生产 .env.tencent：

ssh anybox-server 'set -eu
cd /home/ubuntu
backup=""
if [ -d anyboxProvider ]; then
  backup="anyboxProvider.backup.$(date +%Y%m%d-%H%M%S)"
  mv anyboxProvider "$backup"
  echo "BACKUP=$backup"
fi
tar -xzf anyboxProvider.tar.gz
if [ -n "$backup" ] && [ -f "$backup/.env.tencent" ]; then
  cp "$backup/.env.tencent" anyboxProvider/.env.tencent
  echo "ENV_RESTORED_FROM=$backup/.env.tencent"
fi
cd anyboxProvider
chmod +x scripts/tencent-deploy.sh
ls -l docker-compose.tencent.yml scripts/tencent-deploy.sh .env.tencent
'

如果没有压缩包但项目目录已经是目标版本，跳过解压，只执行：

ssh anybox-server "cd /home/ubuntu/anyboxProvider && chmod +x scripts/tencent-deploy.sh"

运行部署

执行部署脚本：

ssh anybox-server "cd /home/ubuntu/anyboxProvider && ./scripts/tencent-deploy.sh"

脚本会构建镜像、启动 Postgres/Redis、运行迁移，并启动 api、worker、caddy。

常见阻塞处理

80/443 被 nginx 占用

先确认 nginx 配置是不是旧 anyboxProvider 反代：

ssh anybox-server "sudo nginx -T 2>/dev/null | egrep -n 'server_name|listen|proxy_pass|anybox|3000' || true"

如果确认是旧 anyboxProvider 反代，停用 nginx，让 Caddy 接管 80/443：

ssh anybox-server "sudo systemctl stop nginx && sudo systemctl disable nginx"
ssh anybox-server "cd /home/ubuntu/anyboxProvider && docker compose -f docker-compose.tencent.yml --env-file .env.tencent up -d --force-recreate api worker caddy"

ADMIN_BOOTSTRAP_PASSWORD 是占位值

如果 api 或 worker 日志报：

ADMIN_BOOTSTRAP_PASSWORD must not use a placeholder value in production

普通生产运行时直接清空它并重启服务：

ssh anybox-server "cd /home/ubuntu/anyboxProvider && sed -i 's/^ADMIN_BOOTSTRAP_PASSWORD=.*/ADMIN_BOOTSTRAP_PASSWORD=/' .env.tencent && docker compose -f docker-compose.tencent.yml --env-file .env.tencent up -d --force-recreate api worker"

如果这是首次部署且需要创建管理员，先生成一次性强密码，运行 seed，记录管理员密码给用户，然后立刻清空：

ssh anybox-server 'cd /home/ubuntu/anyboxProvider
bootstrap="$(openssl rand -hex 16)"
sed -i "s/^ADMIN_BOOTSTRAP_PASSWORD=.*/ADMIN_BOOTSTRAP_PASSWORD=$bootstrap/" .env.tencent
docker compose -f docker-compose.tencent.yml --env-file .env.tencent --profile tools run --rm seed
sed -i "s/^ADMIN_BOOTSTRAP_PASSWORD=.*/ADMIN_BOOTSTRAP_PASSWORD=/" .env.tencent
docker compose -f docker-compose.tencent.yml --env-file .env.tencent up -d --force-recreate api worker
echo "GENERATED_ADMIN_BOOTSTRAP_PASSWORD=$bootstrap"
'

不要把数据库、Redis、Session、Encryption、Provider API Key 等密钥输出到对话里。

验证

检查容器：

ssh anybox-server "cd /home/ubuntu/anyboxProvider && docker compose -f docker-compose.tencent.yml --env-file .env.tencent ps"

检查健康状态：

ssh anybox-server "printf 'https_livez='; curl -sS -o /tmp/livez.out -w '%{http_code}' https://anybox.com.cn/livez; echo; printf 'https_readyz='; curl -sS -o /tmp/readyz.out -w '%{http_code}' https://anybox.com.cn/readyz; echo; printf 'https_home='; curl -sS -o /tmp/home.out -w '%{http_code}' https://anybox.com.cn/; echo"

从本地绕过 DNS/代理验证公网 HTTPS：

curl.exe --resolve anybox.com.cn:443:129.211.1.144 -sS -o NUL -w "local_https_livez=%{http_code}`n" https://anybox.com.cn/livez
curl.exe --resolve anybox.com.cn:443:129.211.1.144 -sS -o NUL -w "local_https_readyz=%{http_code}`n" https://anybox.com.cn/readyz

确认 bootstrap 已清空、nginx 已停用：

ssh anybox-server 'cd /home/ubuntu/anyboxProvider && val=$(grep -E "^ADMIN_BOOTSTRAP_PASSWORD=" .env.tencent | tail -n1 | cut -d= -f2-); echo bootstrap_password_length=${#val}; echo nginx_active=$(systemctl is-active nginx || true)'

成功标准：

• api 为 healthy
• postgres 和 redis 为 healthy
• worker 为 Up
• caddy 绑定 0.0.0.0:80 和 0.0.0.0:443
• HTTPS /livez、/readyz、首页返回 200
• bootstrap_password_length=0

交付说明

最终回复用户时报告：

• 部署是否成功
• 备份目录名
• 关键健康检查状态码
• 是否创建了管理员；如果本次生成了临时管理员密码，只报告该临时密码并提醒立即修改
• 是否停用了 nginx
• 任何剩余风险，例如 seed 创建了默认 demo 用户或 Caddyfile 仅有格式化警告

Fanfande Frontend Style

核心方向

为 Fanfande Studio 构建安静、成熟、克制、偏桌面生产力工具的前端界面。优先考虑信息层级、稳定布局、紧凑但不拥挤的密度、可预测交互、长期使用不疲劳的视觉系统，以及符合 Electron 桌面应用的鼠标和键盘效率。

把 Obsidian-like 的“低装饰、面板化、克制强调色、原生偏好窗口感”抽象为全局产品气质，而不是局限于设置页。任何页面都应先服务工作流和内容密度，再考虑装饰表达。

工作流程

1. 在写 UI 前先检查目标应用已有 token、基础样式、相邻组件和交互模式。Fanfande Studio 当前优先使用 src/renderer/src/styles/tokens.css、primitives.css、shell.css、sidebar.css、workbench.css、settings.css 等本地样式。
2. 优先消费已有 CSS 变量，不要在已有等价 token 时硬编码颜色、圆角、阴影或动效。常见 token 家族包括 --surface-*、--text-*、--border-*、--brand-*、--semantic-*、--seg-*、--mix-*。
3. 判断当前任务属于哪些 UI 类别，只读取对应 reference。不要一次加载所有 reference。
4. 修改时保持局部一致：复用已有组件结构、class 命名、状态命名和测试约束。只有在现有模式明显无法承载新需求时再新增抽象。
5. 完成前检查亮色/暗色主题、hover、focus-visible、active、selected、disabled、loading、empty、error、窄视口、长中文/英文文本、键盘路径、窗口拖拽区域和 Electron -webkit-app-region。

Reference 选择

• 总体原则和视觉气质：读取 references/principles.md。
• token、颜色、间距、圆角、阴影、动效：读取 references/tokens.md。
• app shell、标题栏、侧栏、主工作区、响应式：读取 references/layout.md。
• sidebar、tabs、breadcrumb、command palette、top menu：读取 references/navigation.md。
• panel、section、card、popover、modal、drawer、tooltip：读取 references/surfaces.md。
• 标题、正文、说明、代码、空状态文案：读取 references/typography.md。
• button、input、select、toggle、checkbox、radio、slider、segmented control：读取 references/controls.md。
• context menu、dropdown、select menu、command menu、action menu：读取 references/menus.md。
• list、table、tree、grid、detail pane、timeline、log viewer：读取 references/data-display.md。
• 表单布局、校验、保存状态、危险操作：读取 references/forms.md。
• toast、banner、loading、skeleton、progress、empty、error recovery：读取 references/feedback.md。
• hover、focus、keyboard、drag/drop、resize、shortcut、selection：读取 references/interactions.md。
• default、hover、focus、active、selected、disabled、readonly、error、warning、success 等状态：读取 references/states.md。
• 常见页面原型和组合方式：读取 references/pages.md。
• 明确不要做的视觉和交互反模式：读取 references/avoid.md。

真实预览

当需要判断文字规范是否符合预期视觉时，打开 assets/style-preview/index.html。这是一个自包含的静态样板间，覆盖 app shell、sidebar、workbench pane、settings rows、buttons、inputs、select、toggle、table、empty state、banner、toast、dropdown menu、dialog 和 theme toggle。

使用预览时不要把它当成必须逐像素复制的业务页面；它是风格基线和组件密度参考。预览界面默认避免在标题下放解释性文案，并压缩非必要 helper text，优先保持视觉精简。实际实现仍应先读取目标项目的相邻组件和本地 token。

文案极简规则

默认不要在标题、section、panel、card、表格行、设置行、菜单项下面常驻解释性文案。界面应先靠结构、标签、状态和控件本身表达含义，而不是用一行灰色小字解释这个区域在做什么。

只在信息会改变用户决策时保留辅助文案，例如错误原因、危险操作后果、权限影响、不可逆变更、空状态下一步、异步任务失败恢复。其余说明放到 tooltip、详情面板、文档入口或按需展开区域。

行内容单行规则

列表行、表格行、设置行、任务行、导航行和选择项默认只显示一行主要内容。不要在同一个行单元里堆“标题 + 灰色说明”的双行结构。

需要展示辅助信息时，优先放到独立列、右侧元信息槽、图标 tooltip、详情面板、展开行或 hover/focus 后出现的补充层。只有错误信息、日志正文、空状态说明、聊天/文档内容这类本身需要阅读的内容区域可以自然多行。

按钮规则

所有 button 默认不要边框，包括 primary、secondary、danger、ghost、icon button、toolbar button、dropdown trigger、menu item 和 chip-like action。用背景色、文字色、图标色、透明度和 focus ring 表达层级与状态。

button 不允许同时出现 icon 和文字。按钮只能是纯文字按钮或纯 icon button。常见工具、状态、快捷动作优先使用 icon button，并用 aria-label、title 或 tooltip 表达含义；需要明确命令文案时使用纯文字按钮。

icon button、toolbar button、sidebar rail button 和 top menu button 的 hover 必须使用统一语义：默认透明背景，hover/focus 只加轻背景和文字/图标色变化，active/selected 使用同一组 active surface 与 active text token。不要在 hover 上做 translateY、缩放、阴影抬升、边框显隐或尺寸变化；focus-visible 只额外显示 focus ring。

is-expanded、aria-expanded 和 aria-pressed 这类控件状态不默认等同 selected/active 视觉。折叠/展开按钮只有在产品明确需要表达“当前选中项”时才使用 active surface；普通展开状态的 hover 仍必须使用 hover token。

当按钮确实带有 active/selected 类时，:hover 和 :focus-visible 仍要保留可见 hover/focus surface，不能被后写的 .is-active 规则压回透明或只剩图标变色。

普通顶栏、工具栏、侧栏 rail 这类浅背景上的 icon button，hover/focus 的背景必须肉眼可辨；不要只改图标颜色，也不要使用弱到接近底色的透明度。默认以当前文字色约 20% 到 24% 的轻背景作为 hover surface，关闭/删除等危险窗口按钮可以使用 danger surface。左侧栏顶部菜单栏的 shell chrome 纯 icon button 是局部例外，按下一组规则执行。

Left sidebar 顶部菜单栏的纯 icon button 模式：作用域只限 .left-sidebar-top-menu 内的 .sidebar-action、.top-menu-view-button 和 .sidebar-toggle-button.is-top-menu。结构使用 ShellTopMenu as="header"，容器用 left-sidebar-top-menu，content 用 left-sidebar-top-menu-content，trailing 用 left-sidebar-top-menu-trailing。按钮必须是无文字的真实 <button>，用 SVG/icon 子元素表达动作，并提供 aria-label、title 或 tooltip。

Left sidebar 顶部菜单栏容器保持桌面 chrome 的低装饰：高度和最小高度使用 --section-toolbar-height / --top-chrome-height（当前约 40px），水平内边距约 12px，按钮间距约 4px，背景使用 --seg-left-sidebar-top-menu-surface，底部分隔线使用已有 mix border token。content 可以横向滚动并隐藏 scrollbar；动作组必须设置 -webkit-app-region: no-drag，避免吃掉窗口拖拽区里的按钮点击。

Left sidebar 顶部菜单栏按钮盒模型使用 --top-chrome-icon-button-size（当前约 28px）同时锁定 width、min-width、height 和 min-height，padding: 0，align-self: center，border 或 border-color 透明，background: transparent，box-shadow: none，border-radius: 8px。不要复用 sidebar rail、activity rail 或 pill button 的尺寸 token。

Left sidebar 顶部菜单栏按钮状态以 icon color 为主：default 使用 --top-chrome-icon 或 --semantic-accent-icon，hover/focus 仍保持透明背景、透明边框、无阴影、无 transform，只切换到 --top-chrome-icon-hover / --semantic-accent-icon-hover；active/pressed 仍保持透明背景，用 active icon token。focus-visible 必须保留 focus outline/ring。该模式不要在 hover 上加背景块、边框、缩放、阴影或位移。

同一组顶栏新增/关闭/切换 icon button 必须使用同一种图标来源和尺寸 token。不要在一个位置用文本 + glyph、另一个位置用 lucide PlusIcon；新增按钮统一使用 PlusIcon，并用 --section-toolbar-icon-size 控制 SVG 尺寸。

顶栏 icon button 的盒模型必须同时锁定 width、min-width、height 和 min-height。不要只写 min-height；后导入的全局按钮尺寸规则会把 hover 背景拉高，导致左右按钮 hover 高度不一致。普通顶栏工具按钮使用顶栏专用尺寸 token，不要复用 sidebar rail / activity rail 的全局 --icon-button-size。

activity rail / sidebar rail 的竖向 icon button 也要有 rail 专用尺寸 token，并用作用域选择器同时覆盖 view button 和 rail toggle。不要让它们回退到全局 --icon-button-size；active 按钮的 :hover 应有独立 hover surface，不能和静态 active 视觉完全相同。

固定尺寸 icon button 放在 full-width grid/flex 容器里时，容器必须显式居中，例如 grid 使用 justify-items: center，flex 使用 align-items: center 或 justify-content: center。缩小按钮尺寸后不要依赖默认对齐，否则 hover 背景会看起来偏左或偏右。

边框主要留给输入框、面板、表格、分隔线、浮层和必要的状态容器。只有当按钮没有边框会造成可发现性或可访问性问题时，才允许作为局部例外。

选择器规则

需要和产品风格统一的选择器不要直接使用原生 <select>。原生 select 展开后的 option 面板由浏览器或系统绘制，无法稳定套用 canvas dropdown 的背景、圆角、hover、selected 和无边框规则。

普通枚举、模式切换、主题选择、技能/MCP/模型选择等可见选择控件，应使用自定义 select/listbox 或 combobox。触发器、选项行和下拉面板必须沿用 canvas dropdown 的轻量样式。

状态表达规则

状态优先用 icon、dot、spinner、progress、颜色和位置表达，不要默认使用文字 badge，例如 Active、Paused、Needs review 这类状态文案不应作为主要视觉。

文字状态只在用户必须区分多个相近业务状态、审计记录、日志、详情页或可访问性文本中出现。图标状态必须提供 aria-label、title、tooltip 或附近详情，让含义可被读取和确认。

不可协商规则

• 不要把产品工具界面做成营销落地页、hero page 或装饰型 dashboard。
• 不要使用装饰性渐变、光斑、玻璃拟态、厚重阴影、大面积品牌色背景或一色系铺满的视觉。
• 不要嵌套卡片。panel 内可以有 row、section、list item，但不要再放一层装饰性 card。
• 不要在工具、面板、设置、表格、列表里使用 hero 级大标题。
• 不要在普通扫描行里使用“主标题 + 辅助说明”的双行内容。行内辅助信息要移到独立列、tooltip、详情面板或展开区。
• 不要给按钮默认加边框。按钮状态通过背景、文字、图标、透明度和 focus ring 表达。
• 不要在 button 中同时放 icon 和文字。使用纯文字按钮或纯 icon button。
• 不要把常见状态默认做成文字 badge。优先用图标、dot、spinner、progress 和语义色表达。
• 不要到处使用胶囊形文字按钮；能用图标表达的工具操作优先用 icon button，并提供 tooltip。
• 不要牺牲稳定尺寸。hover、active、loading 文本、图标、badge、快捷键槽位都不能导致布局跳动。
• 不要让说明文字常驻挤占紧凑控件空间。默认不写标题副文案、panel 描述、row 描述和菜单项说明；复杂说明放到 tooltip、详情区、help text、文档入口或按需展开区。
• 不要破坏输入框、textarea、contenteditable、webview 的原生右键菜单，除非产品明确接管该区域。
• 不要为了统一视觉而忽略可访问性：focus-visible、键盘操作、aria 状态、禁用语义必须完整。

输出习惯

当生成或修改前端代码时，先说明将读取哪些本地样式和 reference；实现后用目标项目已有验证方式检查。涉及明显视觉改动时，应尽量用浏览器或截图做一次实际渲染核对。

Fanfande / Anybox Plugin Structure

Source Of Truth

Use this skill for the current plugin package format used in the Anybox codebase. The old Fanfande paths and .fanfande-plugin/plugin.json layout are historical unless the live target repo proves otherwise.

Treat these files as the implementation source when schema details may have changed:

• packages/anyboxagent/src/plugin/plugin.ts
• packages/anyboxagent/Test/plugin.test.ts
• plugins/Anybox-Plugins/index.json
• plugins/Anybox-Plugins/hyperframes/plugin.json
• plugins/Anybox-Plugins/anybox-plugin-development/docs/anybox-third-party-plugin-development.md

Prefer the running code in plugin.ts over older docs when they disagree.

Current Format Summary

The current built-in plugin registry is an expanded source tree:

plugins/Anybox-Plugins/
  index.json
  <plugin-id>/
    plugin.json
    skills/
    connectors/
    scripts/
    docs/
    assets/

Important rules:

• Put plugin.json at the plugin directory root.
• Do not use plugin.meta.json.
• Do not commit zip artifacts to the built-in expanded registry.
• plugins/Anybox-Plugins/index.json is a JSON array of direct HTTPS plugin.json URLs.
• Directory registry URLs are not supported.
• .anybox-plugin/plugin.json is accepted only as a legacy package manifest location.
• .fanfande-plugin/plugin.json is not the current Anybox runtime format.

Package Layout

For development, use a plugin source root whose children are plugin package folders:

• ANYBOX_PLUGIN_LOCAL_DIR, when set.
• Otherwise the agent data directory's plugins/local.

For managed installs, the runtime copies packages to:

• ANYBOX_PLUGIN_INSTALL_DIR, when set.
• Otherwise the agent data directory's plugins/installed.

Preferred expanded package layout:

<plugin-source-root>/
  <plugin-id>/
    plugin.json
    skills/
      <skill-name>/
        SKILL.md
    connectors/
    scripts/
      server.js
    docs/
    assets/

Versioned package directories are still accepted, mostly for managed installs and legacy packages:

<plugin-source-root>/
  <plugin-id>/
    <version>/
      plugin.json
      skills/
        <skill-name>/
          SKILL.md

The legacy Anybox layout is also accepted:

<plugin-source-root>/
  <plugin-id>/
    <version>/
      .anybox-plugin/
        plugin.json
      skills/

Keep assets, docs, scripts, connectors, and skills next to plugin.json, not inside .anybox-plugin.

Use lowercase stable plugin IDs. The runtime normalizes plugin.json name to lowercase to form pluginID; keep the folder name, manifest name, and registry URL path aligned.

If a package folder contains multiple version subdirectories, the catalog chooses the highest manifest version for the same normalized plugin ID.

Manifest Rules

Write plugin.json as strict JSON. Unknown top-level fields are rejected.

Minimal runtime manifest:

{
  "name": "manifest-lab",
  "version": "0.1.0",
  "description": "Fixture plugin package with MCP, skills, and connectors."
}

Supported runtime top-level fields:

• name: Required. Normalized to lowercase as the plugin ID.
• version: Required. Used for version selection and package matching.
• description: Required. Fallback marketplace description.
• author: String or object with at least name.
• homepage, repository, license: Optional metadata.
• keywords: Optional string array. Merged into catalog tags.
• interface: Optional marketplace and UI metadata.
• mcpServers: Optional array of MCP server templates.
• skills: Optional string or string array of skill root directories; defaults to "skills".
• connectorRequirements: Optional platform connector requirements, such as Gmail.
• connectors: Preferred plugin-owned connector declarations.
• apps: Legacy alias for plugin-owned connectors.
• commands, agents: Reserved fields; accepted but not executed by the plugin runtime.

Repository or remote registry plugin.json files may additionally include registry-only fields:

• skillPreviews: Marketplace preview data for remote catalog entries.
• package: Optional zip download metadata. Include this only when a real downloadable artifact exists.
• id: Optional registry ID override; normally avoid it and use name.

The runtime strips id, skillPreviews, and package before validating the runtime manifest. For the built-in expanded registry, omit package because the package source is already present in the repository.

Include at least one real capability in mcpServers, skills, connectorRequirements, or connectors for an installable package. Metadata-only remote registry entries can appear in the catalog, but they are not installable unless they include a valid package download or a matching local expanded package exists.

Interface Metadata

Use interface for marketplace rendering:

{
  "interface": {
    "displayName": "Manifest Lab",
    "shortDescription": "Review docs and notes.",
    "longDescription": "Longer marketplace detail text.",
    "developerName": "Anybox Tests",
    "category": "Docs",
    "capabilities": ["docs", "review"],
    "websiteURL": "https://example.com",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "iconUrl": "./assets/icon.png",
    "thumbnailUrl": "./assets/thumb.png",
    "heroImageUrl": "./assets/hero.png",
    "screenshots": ["./assets/screen.png"],
    "brandColor": "#2F6FED"
  }
}

Valid catalog categories are Code, Browser, Git, Database, Docs, Automation, and Design. The runtime maps engineering and coding to Code, and productivity and documentation to Docs; prefer exact category names.

Display assets can be https://, data:image/, or package-relative paths.

• Local package-relative assets are exposed as displayable data URLs when the file exists and uses a supported image type.
• Remote registry manifest relative assets are resolved against the manifest URL, for example https://raw.githubusercontent.com/.../<plugin-id>/plugin.json plus ./assets/icon.png.

MCP Servers

Define mcpServers when the plugin adds one or more MCP servers. Each entry accepts:

• id: Optional. Defaults to default.
• name: Optional. Defaults to interface.displayName or manifest name.
• description: Optional. Defaults to manifest description.
• risk: Optional; low, medium, high, or critical. Defaults to medium.
• permissions: Optional user-facing permission strings.
• tools: Optional preview list for marketplace display.
• configFields: Optional install-time plugin config fields.
• runtime: Required stdio or remote MCP runtime.
• installReview: Optional review notes shown before install.

Use tools as display and policy hints, not as implementation:

{
  "name": "list_notes",
  "title": "List Notes",
  "description": "List fixture notes.",
  "readOnly": true,
  "destructive": false
}

Use configFields for plugin-level configuration. Supported field keys are key, label, type, required, secret, placeholder, defaultValue, and description. Valid type values are text, password, url, and path. Required fields are enforced during install or update.

Stdio Runtime

Use stdio for local MCP servers bundled with the package:

{
  "runtime": {
    "transport": "stdio",
    "command": "node",
    "args": ["${PLUGIN_ROOT}/scripts/server.js"],
    "cwd": "${PLUGIN_ROOT}",
    "env": {
      "DOCS_TOKEN": "${DOCS_TOKEN}"
    },
    "timeoutMs": 1000
  }
}

command, args, env, and cwd support placeholders of the form ${UPPER_CASE_KEY}. The runtime supplies PLUGIN_ROOT and any installed plugin config values.

Remote Runtime

Use remote runtime for direct remote MCP servers:

{
  "runtime": {
    "transport": "remote",
    "serverUrl": "https://docs.example.test/mcp",
    "headers": {
      "authorization": "Bearer ${DOCS_TOKEN}"
    },
    "allowedTools": {
      "readOnly": true
    },
    "requireApproval": "never",
    "timeoutMs": 1000
  }
}

Remote runtime may also include provider, connectorId, authorization, serverDescription, toolPolicies, and requireApproval.

Do not mark a plugin critical unless install should be blocked. The installer rejects critical risk catalog items.

Plugin Skills

Use skills to bundle Codex/Anybox skills inside the plugin package. If omitted, the runtime looks under skills.

<package-root>/
  skills/
    review/
      SKILL.md
    release-notes/
      SKILL.md

The runtime discovers only direct subdirectories under each declared skill root. Each discovered skill directory must contain SKILL.md.

SKILL.md should include normal skill frontmatter:

---
name: Review Notes
description: Review docs produced by this plugin.
---

# Review Notes

Use this skill to review generated documentation notes.

Generated plugin skill IDs use:

plugin:<pluginID>:<skill-directory-name>

For example, manifest-lab with skills/review/SKILL.md becomes plugin:manifest-lab:review.

When using multiple skill roots, keep skill directory names unique. The current ID format uses the immediate skill directory name, not the full root path.

Connectors

Use connectors when the plugin exposes a plugin-owned remote or local connector. apps is still parsed as a legacy alias, but prefer connectors in new manifests.

Each connector entry accepts:

• appID: Required stable ID inside the plugin.
• name: Required display name.
• description, icon, risk, permissions, tools, installReview: Optional metadata.
• credential or configFields: Configuration and secret metadata.
• runtime: Required remote or stdio runtime.

Example API-key connector:

{
  "connectors": [
    {
      "appID": "docs",
      "name": "Docs API",
      "description": "Remote MCP connector for docs search.",
      "risk": "medium",
      "permissions": ["Sends requests to docs.example.test"],
      "tools": [
        {
          "name": "search_docs",
          "description": "Search docs.",
          "readOnly": true
        }
      ],
      "credential": {
        "key": "DOCS_API_KEY",
        "label": "Docs API key",
        "type": "password",
        "required": true,
        "secret": true
      },
      "runtime": {
        "transport": "remote",
        "serverUrl": "https://docs.example.test/mcp",
        "headers": {
          "x-api-key": "${DOCS_API_KEY}"
        },
        "allowedTools": {
          "readOnly": true
        },
        "requireApproval": "always"
      }
    }
  ]
}

Connector secrets are stored in the credential store. The generated global MCP server keeps only connectorId; serverUrl, authorization, and headers are resolved at runtime after the connector is connected.

Use connectorRequirements when a plugin depends on a platform connector managed by Anybox, such as Gmail:

{
  "connectorRequirements": [
    {
      "connector": "gmail",
      "tools": ["gmail_profile", "gmail_search_messages"],
      "permissions": [
        "Read the connected Gmail profile summary.",
        "Search Gmail messages with Gmail search syntax."
      ],
      "required": true,
      "reason": "Read-only Gmail access through the Anybox Gmail connector."
    }
  ]
}

Generated IDs

Use these generated IDs when explaining, testing, or debugging plugin installation:

• Plugin ID: normalized manifest name.
• Default MCP server: plugin.<pluginID>.
• Named MCP server: plugin.<pluginID>.<serverID>.
• Plugin-owned connector credential ID: plugin-connector:<pluginID>:<connectorID>.
• Legacy app connector credential ID: plugin-app:<pluginID>:<appID>.
• Plugin-owned connector MCP server: plugin.<pluginID>.connector.<connectorID>.
• Legacy app connector MCP server: plugin.<pluginID>.app.<appID>.
• Plugin skill: plugin:<pluginID>:<skill-directory-name>.

Registry Manifests

Local registry files are loaded from bundled registry paths and from ANYBOX_PLUGIN_REGISTRY_FILES, split by the OS path delimiter. Registry files still use:

{
  "schemaVersion": 1,
  "plugins": [
    {
      "name": "remote-lab",
      "version": "1.2.3",
      "description": "Remote fixture plugin.",
      "interface": {
        "displayName": "Remote Lab",
        "shortDescription": "Remote fixture.",
        "category": "Docs"
      },
      "skillPreviews": [
        {
          "name": "Review Notes",
          "description": "Review docs.",
          "directory": "review"
        }
      ],
      "mcpServers": []
    }
  ]
}

Remote registry loading uses ANYBOX_PLUGIN_REGISTRY_INDEX_URL, defaulting to:

https://raw.githubusercontent.com/fanfan-de/anybox/master/plugins/Anybox-Plugins/index.json

Set it to off, none, or disabled during local validation.

Remote index.json must be a JSON array of direct HTTPS manifest URLs:

[
  "https://raw.githubusercontent.com/fanfan-de/anybox/master/plugins/Anybox-Plugins/hyperframes/plugin.json"
]

Rules for remote registry entries:

• Every entry must point directly to plugin.json.
• Directory URLs are not supported.
• plugin.meta.json is not supported.
• GitHub blob URLs may be normalized to raw.githubusercontent.com, but raw URLs are preferred.
• Remote relative display assets resolve against the manifest URL.

Remote plugin.json can include skillPreviews for catalog display. Include package only for a real downloadable zip artifact:

{
  "package": {
    "type": "zip",
    "url": "https://cdn.example.test/remote-lab.zip",
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "size": 12345
  }
}

Package downloads must be HTTPS zip files with a matching SHA-256. Archives must not contain symlinks or paths outside the extraction directory. A downloaded package must contain exactly one manifest matching the registry plugin ID and version.

For the built-in expanded registry under plugins/Anybox-Plugins, do not keep zip artifacts and do not keep package fields unless the referenced artifact is intentionally published and validated.

Validation Workflow

When building, migrating, or reviewing a plugin package:

1. Confirm the package root contains root plugin.json.
2. Treat .anybox-plugin/plugin.json as legacy compatibility only.
3. Do not create .fanfande-plugin/plugin.json for current Anybox packages.
4. Check plugin.json is valid JSON and uses only supported schema fields.
5. Check every declared skill root stays inside the package and contains direct skill subdirectories with SKILL.md.
6. Check every stdio runtime path works from ${PLUGIN_ROOT} or declares an explicit cwd.
7. Check required configFields match every placeholder used by MCP runtimes.
8. Check connector placeholders match credential.key or connector config fields.
9. Check connectorRequirements reference platform connector IDs that exist in the app.
10. Check risk is not critical unless blocked installation is intended.
11. For plugins/Anybox-Plugins/index.json, verify every entry ends with /plugin.json.
12. For the built-in expanded registry, verify there are no *.zip, no plugin.meta.json, and no root package fields unless explicitly intended.
13. Run a catalog load against the candidate package:

cd C:\Projects\Anybox\packages\anyboxagent
$env:ANYBOX_PLUGIN_LOCAL_DIR = "C:\path\to\plugin-source-root"
$env:ANYBOX_PLUGIN_REGISTRY_INDEX_URL = "off"
bun -e "import * as Plugin from './src/plugin/plugin.ts'; console.log(JSON.stringify(await Plugin.listCatalog(), null, 2))"

14. Run the plugin regression tests after changing plugin-system code:

cd C:\Projects\Anybox\packages\anyboxagent
bun test Test/plugin.test.ts

Complete Minimal Package

plugin-source-root/
  manifest-lab/
    plugin.json
    skills/
      review/
        SKILL.md
    scripts/
      server.js

{
  "name": "manifest-lab",
  "version": "0.1.0",
  "description": "Fixture plugin package with MCP and skills.",
  "author": {
    "name": "Anybox Tests"
  },
  "interface": {
    "displayName": "Manifest Lab",
    "shortDescription": "Fixture plugin package.",
    "developerName": "Anybox Tests",
    "category": "Docs",
    "logo": "ML"
  },
  "mcpServers": [
    {
      "id": "notes",
      "name": "Manifest Notes",
      "risk": "low",
      "permissions": ["Starts a bundled stdio MCP server"],
      "tools": [
        {
          "name": "list_notes",
          "description": "List fixture notes.",
          "readOnly": true
        }
      ],
      "runtime": {
        "transport": "stdio",
        "command": "node",
        "args": ["${PLUGIN_ROOT}/scripts/server.js"],
        "cwd": "${PLUGIN_ROOT}",
        "timeoutMs": 1000
      }
    }
  ],
  "skills": "skills"
}

前端 UI 样式模板

用途

使用这个 skill 为小型产品级 UI 基础组件套用一致、可复用的样式基础。优先读取目标应用已有的设计 token、组件模式和相邻样式，再用本 skill 的模板补齐缺失部分。

工作流程

1. 在写样式之前，先检查目标应用已有的 token、基础样式和相邻组件。
2. 将本 skill 的语义 token 映射到本地 token，避免在已有等价 token 时硬编码颜色。
3. 只在需要时加载对应参考文档：
   • 右键菜单、自定义上下文菜单：读取 references/context-menu.md。
   • 页面滚动条、长滚动容器：读取 references/scrollbar.md。
4. 基础组件样式要保持紧凑、可操作、可复用。除非组件明确属于某个业务功能，否则避免使用过于业务化的命名。
5. 完成前检查亮色主题、暗色主题、键盘操作、鼠标操作、视口边缘定位、禁用状态和长文本。

基础规则

• 优先使用现有 CSS 变量。常见映射包括 surface、elevated surface、border、primary text、secondary text、focus outline、shadow、radius 和 motion duration。
• 菜单样式优先服从应用已有的 semantic token。常见映射包括 dropdown/menu surface、tree/list row hover surface、hover text、danger text/surface、border、font family、shadow 和 radius。
• 菜单和控件圆角保持克制。普通应用基础组件使用 4px 到 8px，除非当前设计系统明确使用其他圆角；浮层菜单窗口的外层圆角可比菜单项或小控件略大 1px 到 2px，优先使用本地 menu/dropdown radius token。
• 菜单宽度要贴合内容。不要让短标签菜单套用过宽的通用 selector 宽度；图标 + 短文本的应用选择菜单优先让面板用 width: max-content / fit-content 按最长项推断宽度。此类菜单不要继承 184px、220px 这类通用 min-width；用 min-width: 0 或很小的内容下限，只保留视口保护用的 max-width。菜单项本身仍应 width: 100% 填满已推断出的面板宽度，确保每一行 hover/selected 背景等宽。
• 菜单项默认不要有背景块。只有 hover、focus、active、selected 或 highlighted 状态才显示背景；按钮触发的下拉菜单也遵守这一点。
• 交互行使用稳定尺寸：固定最小高度、明确图标槽位、文本省略、可选快捷键槽位。
• 短右键菜单、短下拉菜单和按钮触发的动作菜单默认不显示、不预留右侧滚动条槽位；只有菜单项确实可能超过视口时才允许内部滚动。紧凑弹层即使需要滚动，也优先隐藏可见 scrollbar，避免右侧出现拖动条或空白槽位；谨慎使用 scrollbar-gutter: stable。
• 页面级、主内容区和长列表的可见滚动条采用轻量标准样式：轨道透明或贴合页面背景，不画外框；滑块窄、圆角胶囊、低对比中性灰，默认不抢视觉，hover 或拖动时才略微加深；不要使用彩色、渐变、阴影、加宽滚动条或常驻背景槽。具体实现读取 references/scrollbar.md。
• 紧凑菜单不常驻显示解释性小字。将说明放在 hover tooltip、title、aria-describedby 或详情面板里；菜单行内只保留主标签、状态/动作词和必要图标。
• 破坏性操作使用语义变体。不要依赖菜单项位置来编码危险样式。
• 动作菜单优先使用 role="menu" 和 role="menuitem"。根据应用交互模型一致地使用 aria-disabled 或 disabled。
• 带搜索框的菜单使用同一套菜单 surface、radius、hover、focus token；搜索框固定在顶部，下面的结果区才滚动，但不要显示右侧拖动条或预留 scrollbar 区域。语义上可使用 role="dialog" 包含 searchbox + listbox，不要为了套用普通菜单角色而牺牲搜索输入的可访问性。
• 可能被滚动容器或 overflow 裁剪的浮层菜单，使用 portal 或 fixed 定位渲染。
• 除非产品明确接管该区域，否则保留输入框、textarea、可编辑内容和 webview 中的浏览器原生右键菜单。
• 不要给工具型 UI 添加装饰性卡片、夸张阴影、渐变或营销页式视觉处理。

扩展方式

每个基础组件新增一个聚焦的参考文档，例如 references/button.md 或 references/dialog.md。SKILL.md 只保留导航和共享规则。

Obsidian Like

Core Direction

Create a mature desktop productivity settings interface: quiet, utilitarian, low contrast, spacious, and component-driven. Favor the feel of a native app preferences window over a marketing page or decorative web dashboard.

Use this style primarily for:

• Settings and preferences pages
• Account, update, language, editor, appearance, hotkey, plugin, sync, and advanced configuration screens
• Desktop app dialogs with persistent navigation and dense repeated controls
• Frontend prompts that need an Obsidian-like settings aesthetic

Layout

Use a two-pane desktop layout.

• Left sidebar width: 280px to 300px
• Sidebar background: near-white gray, such as #fbfbfb or #fafafa
• Main background: #ffffff or very light neutral
• Divider between sidebar and content: 1px solid #dedede or softer
• Main content max width: 880px to 920px
• Main content horizontal padding: 56px to 72px on desktop
• Top/right close action: small gray X icon button with minimal hover feedback

Keep the main content aligned with generous whitespace. Do not fill the whole width with dense cards unless the product already uses that pattern.

Sidebar

Build the sidebar as grouped navigation.

• Group labels: small, muted, gray text; examples: Options, Core plugins, Third-party plugins
• Nav rows: icon plus label, about 32px high
• Icons: thin line icons, dark gray, approximately 18px
• Text: 14px to 15px, dark gray
• Selected item: light gray rounded rectangle, 5px to 6px radius, no strong accent color
• Group spacing: visibly separate groups with vertical gaps around 28px to 36px

Use the accent color sparingly; the selected sidebar state should usually be neutral, not purple.

Content Sections

Structure content as section headings followed by grouped setting panels.

• Section title: 18px to 20px, weight 600, near-black
• Section spacing: 28px to 36px between major groups
• Panel background: #fafafa, #f8f8f8, or equivalent neutral surface
• Panel radius: about 12px
• Panel padding: 24px
• Panel shadow: none, or a barely perceptible border/shadow only if needed for separation
• Internal dividers: 1px solid #e2e2e2

Do not nest cards inside cards. A settings panel may contain rows, but rows should not become separate decorative cards.

Setting Rows

Each setting row should feel scannable and compact.

• Row height: usually 72px to 96px, depending on description length
• Left side: setting title and helper text
• Right side: control aligned vertically center
• Title: 15px to 16px, medium or regular weight, near-black
• Description: 13px to 14px, muted gray, compact line height
• Links inside descriptions: purple accent, no default underline

Keep controls close to the right edge of the panel. Leave enough text width so Chinese and English labels do not wrap awkwardly.

Row-First Settings Standard

When restyling an existing desktop settings page, prefer the row-first pattern used by the Appearance settings:

• Use one light neutral rounded panel per related setting group, usually #fafafa with 8px to 10px radius.
• Inside the panel, use rows separated by 1px solid #dedede; do not create separate cards for individual settings.
• Each row uses a two-column grid: left minmax(0, 1fr), right 156px to 220px, with 18px to 32px column gap.
• Row padding should be around 16px 0 inside a 24px padded panel. Minimum row height should be about 76px.
• Left copy uses a title and optional helper description. Title: 15px, weight 500, color near #1f1f1f. Description: 13px, color around #6d6a66, line-height around 1.45.
• Right controls are compact and right-aligned. Selects are about 34px tall, light gray (#eeeeee) with a #d9d9d9 border and 6px radius. Buttons are also about 34px tall.
• Toggles should appear as the right-side control of a row, not as a separate decorative card. Hide nonessential leading icons in setting rows when the Appearance page standard is being used.
• On narrow screens, collapse rows to a single column and stretch the control to the row width.

This pattern should be used for preference-style pages such as General, Appearance, Developer, update settings, language settings, and other app preferences. Do not force dense management surfaces such as provider catalogs, model lists, archived session lists, or marketplace directories into this pattern when their data needs richer list or table treatment.

Controls

Use familiar desktop controls with restrained styling.

• Primary buttons: purple background near #8b5cf6 or #8f63e9, white text, 6px radius
• Secondary buttons: white background, light gray border, dark text, 6px radius
• Buttons: compact height around 34px to 38px; no oversized CTA styling
• Select inputs: white background, light gray border, subtle radius, native or simple arrow
• Toggles: capsule track; purple when on, gray when off, white thumb
• Icon-only controls: use line icons and tooltips when the action is not obvious

Use purple only for affirmative, active, or link states. Avoid using it as a broad background or decorative gradient.

Visual Tokens

Start from these tokens and adapt to the host codebase:

:root {
  --obs-bg: #ffffff;
  --obs-sidebar-bg: #fafafa;
  --obs-surface: #f8f8f8;
  --obs-surface-subtle: #fbfbfb;
  --obs-border: #dedede;
  --obs-border-subtle: #e7e7e7;
  --obs-text: #1f1f1f;
  --obs-text-muted: #666666;
  --obs-text-faint: #8a8a8a;
  --obs-accent: #8b5cf6;
  --obs-accent-hover: #7c4fe8;
  --obs-radius-panel: 12px;
  --obs-radius-control: 6px;
}

Prompt Pattern

When asked to write a design prompt, include:

Create a quiet Obsidian-like desktop settings interface: two-pane layout with a narrow left navigation sidebar, subtle gray selected nav item, centered main content, rounded light-gray settings panels, compact setting rows with dividers, muted helper text, simple secondary buttons, purple accent primary buttons and toggles, low contrast neutral palette, no decorative gradients, no marketing hero, no nested cards.

Avoid

• Marketing landing-page composition
• Large hero sections or oversized headings
• Decorative gradients, blurred blobs, or ornamental illustrations
• Heavy shadows or bright borders
• One-note purple backgrounds
• Card-in-card layouts
• Pill-shaped text buttons everywhere
• Excessive whitespace that makes the settings page feel sparse rather than calm
• In-app explanatory text about how the UI works unless the product genuinely needs it

PDF Skill

When to use

• Read or review PDF content where layout and visuals matter.
• Create PDFs programmatically with reliable formatting.
• Validate final rendering before delivery.

Workflow

1. Prefer visual review: render PDF pages to PNGs and inspect them.
   • Use pdftoppm if available.
   • If unavailable, install Poppler or ask the user to review the output locally.
2. Use reportlab to generate PDFs when creating new documents.
3. Use pdfplumber (or pypdf) for text extraction and quick checks; do not rely on it for layout fidelity.
4. After each meaningful update, re-render pages and verify alignment, spacing, and legibility.

Temp and output conventions

• Use tmp/pdfs/ for intermediate files; delete when done.
• Write final artifacts under output/pdf/ when working in this repo.
• Keep filenames stable and descriptive.

Dependencies (install if missing)

Prefer uv for dependency management.

Python packages:

uv pip install reportlab pdfplumber pypdf

If uv is unavailable:

python3 -m pip install reportlab pdfplumber pypdf

System tools (for rendering):

# macOS (Homebrew)
brew install poppler

# Ubuntu/Debian
sudo apt-get install -y poppler-utils

If installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.

Environment

No required environment variables.

Rendering command

pdftoppm -png $INPUT_PDF $OUTPUT_PREFIX

Quality expectations

• Maintain polished visual design: consistent typography, spacing, margins, and section hierarchy.
• Avoid rendering issues: clipped text, overlapping elements, broken tables, black squares, or unreadable glyphs.
• Charts, tables, and images must be sharp, aligned, and clearly labeled.
• Use ASCII hyphens only. Avoid U+2011 (non-breaking hyphen) and other Unicode dashes.
• Citations and references must be human-readable; never leave tool tokens or placeholder strings.

Final checks

• Do not deliver until the latest PNG inspection shows zero visual or formatting defects.
• Confirm headers/footers, page numbering, and section transitions look polished.
• Keep intermediate files organized or remove them after final approval.

Audio Transcribe

Transcribe audio using OpenAI, with optional speaker diarization when requested. Prefer the bundled CLI for deterministic, repeatable runs.

Workflow

1. Collect inputs: audio file path(s), desired response format (text/json/diarized_json), optional language hint, and any known speaker references.
2. Verify OPENAI_API_KEY is set. If missing, ask the user to set it locally (do not ask them to paste the key).
3. Run the bundled transcribe_diarize.py CLI with sensible defaults (fast text transcription).
4. Validate the output: transcription quality, speaker labels, and segment boundaries; iterate with a single targeted change if needed.
5. Save outputs under output/transcribe/ when working in this repo.

Decision rules

• Default to gpt-4o-mini-transcribe with --response-format text for fast transcription.
• If the user wants speaker labels or diarization, use --model gpt-4o-transcribe-diarize --response-format diarized_json.
• If audio is longer than ~30 seconds, keep --chunking-strategy auto.
• Prompting is not supported for gpt-4o-transcribe-diarize.

Output conventions

• Use output/transcribe/<job-id>/ for evaluation runs.
• Use --out-dir for multiple files to avoid overwriting.

Dependencies (install if missing)

Prefer uv for dependency management.

uv pip install openai

If uv is unavailable:

python3 -m pip install openai

Environment

• OPENAI_API_KEY must be set for live API calls.
• If the key is missing, instruct the user to create one in the OpenAI platform UI and export it in their shell.
• Never ask the user to paste the full key in chat.

Skill path (set once)

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export TRANSCRIBE_CLI="$CODEX_HOME/skills/transcribe/scripts/transcribe_diarize.py"

User-scoped skills install under $CODEX_HOME/skills (default: ~/.codex/skills).

CLI quick start

Single file (fast text default):

python3 "$TRANSCRIBE_CLI" \
  path/to/audio.wav \
  --out transcript.txt

Diarization with known speakers (up to 4):

python3 "$TRANSCRIBE_CLI" \
  meeting.m4a \
  --model gpt-4o-transcribe-diarize \
  --known-speaker "Alice=refs/alice.wav" \
  --known-speaker "Bob=refs/bob.wav" \
  --response-format diarized_json \
  --out-dir output/transcribe/meeting

Plain text output (explicit):

python3 "$TRANSCRIBE_CLI" \
  interview.mp3 \
  --response-format text \
  --out interview.txt

Reference map

• references/api.md: supported formats, limits, response formats, and known-speaker notes.

Zhihu Markdown Publisher

Use this skill to move a local Markdown article into Zhihu's article editor and publish it with images. Treat Zhihu login, CAPTCHA, and final publishing as live external actions.

Required Inputs

Expect a Markdown article path. If the user does not provide one, search the workspace for likely Zhihu drafts under paths such as 03_内容生产/知乎.

The article should have frontmatter:

---
zhihu-title: 文章标题
zhihu-topics:
  - 大语言模型
  - 桌面应用
zhihu-cover:
zhihu-link:
---

Support body images in either Markdown or Obsidian wiki syntax:

![说明](../../assets/screenshot.png)
![[assets/screenshot.png|说明]]

Workflow

1. Run the bundled preparer:

node "<skill-dir>\scripts\prepare-zhihu-article.mjs" "<article.md>" "<output-dir>"

Use a workspace output directory such as 07_自动化脚本/out/zhihu. The script writes:

• <name>.manifest.json: title, topics, cover, image paths, output paths.
• <name>.html: local preview.
• <name>.txt: plain-text fallback.

Stop and fix any missing frontmatter or missing images before using the browser.

2. Open https://zhuanlan.zhihu.com/write in the in-app browser when available. If Zhihu redirects to login, ask the user to finish login/CAPTCHA, then continue.

3. Fill the editor from the manifest:

• Put manifest.title into the title textbox.
• Clear the body if it contains an old draft or duplicate content.
• Paste rich HTML chunks, not raw Markdown, so headings/lists/links render correctly.
• Paste local images as clipboard image items in the original image order.
• Verify figure count equals manifest.images.length.
• Verify raw Markdown heading text such as ## is not present.
• Verify key tail content and links exist.

4. Set publishing metadata:

• Add no more topics than Zhihu accepts. Prefer exact topic suggestions surfaced by Zhihu over forcing frontmatter names.
• If topic search returns ambiguous results, pick fewer high-confidence topics rather than incorrect ones.
• Leave column/question/source settings unchanged unless the user explicitly asks.
• Add a cover only if the page supports it reliably; otherwise rely on the article's first product image.

5. Publish:

• Click final 发布 only if the user explicitly asked to publish in this turn or already approved publishing.
• After success, capture the final URL, usually https://zhuanlan.zhihu.com/p/<id>.
• Update the article frontmatter zhihu-link: with the final URL.
• Re-run the preparer once to verify the source still parses.

Browser Implementation Notes

Use the Browser/in-app browser skill when available. A robust sequence is:

1. Inspect the current DOM and locate the two textboxes: title then body.
2. Fill title.
3. If the body must be cleared, click editor undo until the body is empty if ordinary Ctrl+A does not work. Verify 字数：0 and zero figure elements.
4. Paste chunks:

await tab.clipboard.write([{ entries: [
  { mimeType: "text/html", text: htmlChunk },
  { mimeType: "text/plain", text: plainChunk }
] }]);
await bodyBox.press("Control+V", { timeoutMs: 10000 });

5. Paste each image:

await tab.clipboard.write([{ entries: [{
  mimeType: "image/png",
  base64: imageBytes.toString("base64")
}] }]);
await bodyBox.press("Control+V", { timeoutMs: 10000 });

Use image/jpeg for .jpg or .jpeg. Wait briefly after every image paste so Zhihu finishes inserting/uploading it.

Validation Checklist

Before publishing, check:

• Title textbox contains the intended title.
• Body has the intro and final paragraph.
• GitHub/download links are visible and clickable when present.
• document.querySelectorAll("figure").length equals expected image count.
• No duplicated body content.
• No raw heading markers remain, for example ## 是 Agent 工作台.
• Topics are relevant and visible in publish settings.
• The 发布 button is enabled.

If any validation fails, do not publish. Restore a clean draft and re-fill it.

Anybox 插件开发

使用这个 skill 来为当前仓库的插件运行时创建插件包。遇到文档和代码不一致时，以运行代码为准。

参考来源：

• 完整指南：../../../docs/anybox-third-party-plugin-development.md
• 运行时事实来源：../../../packages/anyboxagent/src/plugin/plugin.ts
• 回归测试和示例：../../../packages/anyboxagent/Test/plugin.test.ts

工作流

1. 明确插件能力：MCP 工具、随包 skill、插件自带 connector，或平台 connector requirement。
2. 选择插件包结构。默认使用版本化目录。
3. 编写 .anybox-plugin/plugin.json，必须是严格 JSON，只使用运行时支持的顶层字段。
4. 在 .anybox-plugin 同级添加运行文件，例如 skills/、connectors/、scripts/、docs/ 和 assets/。
5. 使用 Plugin.listCatalog() 验证 catalog 能发现插件。
6. 如果修改了插件系统运行时代码，运行 bun test Test/plugin.test.ts。

插件包结构

新插件默认使用这个结构：

<install-root>/
  <plugin-id>/
    <version>/
      .anybox-plugin/
        plugin.json
      skills/
        <skill-name>/
          SKILL.md
      connectors/
      scripts/
      docs/
      assets/

注意：

• <install-root> 是包含一个或多个插件包目录的父目录；开发新插件时优先把它作为 ANYBOX_PLUGIN_LOCAL_DIR。
• 当前运行时用 ANYBOX_PLUGIN_LOCAL_DIR 发现固定本地插件仓库，未设置时默认是 Agent data 目录下的 plugins/local。这个目录逻辑上等价于 GitHub 插件仓库，只提供可安装候选项，不受卸载流程删除。
• ANYBOX_PLUGIN_INSTALL_DIR 是受管理安装根目录，用于网络下载或从本地仓库安装时复制出来的插件包。这里的插件逻辑上属于已安装插件，运行时使用这里的副本，卸载时可能删除对应插件包。
• 运行时只读取 .anybox-plugin/plugin.json；新插件必须写 .anybox-plugin/plugin.json。
• skills、connectors、scripts、docs 和 assets 应放在 .anybox-plugin 同级，不要放进 .anybox-plugin 里。
• 插件 ID 使用稳定的小写名称。目录名和 manifest name 尽量保持一致。

Manifest 规则

最小 manifest：

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "My first Anybox plugin."
}

支持的顶层字段包括：

• name、version、description
• author、homepage、repository、license、keywords
• interface
• mcpServers
• skills
• connectorRequirements
• connectors
• apps，仅用于旧兼容
• commands、agents，当前是保留字段

未知顶层字段会被拒绝。

使用 interface 配置 catalog 展示信息：

{
  "interface": {
    "displayName": "Hello Anybox",
    "shortDescription": "A minimal plugin for learning plugin development.",
    "longDescription": "This plugin demonstrates a local stdio MCP server and a bundled Agent skill.",
    "developerName": "Your Name",
    "category": "Automation",
    "capabilities": ["demo", "mcp"],
    "logo": "HA",
    "brandColor": "#2563EB"
  }
}

优先使用已知 catalog 分类：Code、Browser、Git、Database、Docs、Automation 和 Design。

能力模式

不需要独立连接状态或凭据生命周期的工具，使用 mcpServers：

{
  "mcpServers": [
    {
      "id": "hello",
      "name": "Hello Anybox",
      "risk": "low",
      "permissions": ["Starts a local Node.js MCP server bundled with this plugin."],
      "tools": [
        {
          "name": "hello_echo",
          "title": "Echo Text",
          "description": "Echo text back to the user.",
          "readOnly": true
        }
      ],
      "runtime": {
        "transport": "stdio",
        "command": "node",
        "args": ["${PLUGIN_ROOT}/scripts/server.js"],
        "cwd": "${PLUGIN_ROOT}",
        "timeoutMs": 10000
      }
    }
  ]
}

插件需要给 Agent 提供说明时，使用 skills：

{
  "skills": "skills"
}

声明的 skill root 下，每个直接子目录都必须包含 SKILL.md。例如 skills/review/SKILL.md 会生成 plugin:<plugin-id>:review。

插件需要自带 API key 或 OAuth 状态时，使用 connectors：

{
  "connectors": [
    {
      "id": "weather",
      "name": "Weather",
      "risk": "medium",
      "permissions": ["Sends requests to api.weather.example."],
      "credential": {
        "kind": "api_key",
        "key": "WEATHER_API_KEY",
        "label": "Weather API key",
        "type": "password",
        "required": true,
        "secret": true
      },
      "runtime": {
        "transport": "stdio",
        "command": "node",
        "args": ["${PLUGIN_ROOT}/connectors/weather/server.js"],
        "cwd": "${PLUGIN_ROOT}",
        "env": {
          "WEATHER_API_KEY": "${WEATHER_API_KEY}"
        }
      },
      "tools": [
        {
          "name": "weather_current",
          "title": "Current Weather",
          "description": "Read current weather for a city.",
          "readOnly": true
        }
      ]
    }
  ]
}

插件要复用平台已有能力时，使用 connectorRequirements，例如 browser、GitHub 或 workspace files。

Runtime 规则

• 所有 ${PLUGIN_ROOT} 路径都必须留在插件包内部。
• stdio MCP server 的普通日志写 stderr。stdout 只能输出 JSON-RPC 消息。
• 本地 MCP server 必须响应 initialize、tools/list 和 tools/call。
• 只读工具标记 readOnly: true，破坏性操作标记 destructive: true。
• risk 使用 low、medium 或 high；不要使用 critical，除非插件安装应该被阻止。
• 不要提交 API key、OAuth client secret、access token、refresh token、本地 auth store、数据库或缓存目录。

验证

对候选插件来源根目录运行：

cd C:\Projects\anybox\packages\anyboxagent
$env:ANYBOX_PLUGIN_LOCAL_DIR = "C:\path\to\plugin-source-root"
$env:ANYBOX_PLUGIN_REGISTRY_INDEX_URL = "off"
bun -e "import * as Plugin from './src/plugin/plugin.ts'; console.log(JSON.stringify(await Plugin.listCatalog(), null, 2))"

确认输出里包含插件 ID、生成的 MCP server ID、connector-backed MCP server ID 和随包 skill ID。

修改插件系统运行时代码后运行：

cd C:\Projects\anybox\packages\anyboxagent
bun test Test/plugin.test.ts

常见失败

• 插件没有出现在 catalog：检查 ANYBOX_PLUGIN_LOCAL_DIR、目录结构、JSON 合法性、支持的顶层字段，以及必填的 name、version、description。只有验证下载/安装根目录时才检查 ANYBOX_PLUGIN_INSTALL_DIR。
• PLUGIN_CONFIG_INVALID：检查必填 configFields 或 OAuth client 设置。
• 诊断没有发现工具：检查命令是否可执行、runtime 路径、cwd、JSON-RPC 方法处理，以及 stdout 是否混入普通日志。
• Connector 未连接：API key connector 需要保存 key；OAuth connector 需要完成浏览器授权。
• 卸载时源码被删：开发时使用 ANYBOX_PLUGIN_LOCAL_DIR。不要直接把 Git 源码根目录当成 ANYBOX_PLUGIN_INSTALL_DIR；如果必须验证受管理安装根，复制或构建到 dev-install 目录。

Anybox Start Dev

Use the bundled script to start the two long-running development processes required by this repository.

Workflow

1. Run scripts/start-dev.ps1.
2. Let the script open two new PowerShell windows.
3. Keep both windows open for the rest of the verification or testing session.

The script starts exactly these commands:

• Server: cd <repo>/packages/anyboxagent && bun run dev:server
• Client: cd <repo>/packages/desktop && bun run dev

Notes

• Do not replace the commands with alternatives unless the user explicitly changes the workflow.
• Start the two processes in separate windows; do not run one after the other in the same blocking shell.
• If either window exits immediately, inspect the visible error in that window and report it before retrying.
• The script resolves the repository root relative to the skill location, so keep this skill inside the project root at .anybox/skills/anybox-start-dev.

Resource

• scripts/start-dev.ps1: Open the server and client in separate PowerShell windows.

Anybox 插件开发

使用这个 skill 来为当前仓库的插件运行时创建插件包。遇到文档和代码不一致时，以运行代码为准。

参考来源：

• 随包完整指南：../../docs/anybox-third-party-plugin-development.md
• 在源码仓库内调试时，以 packages/anyboxagent/src/plugin/plugin.ts 为运行时事实来源。
• 在源码仓库内修改插件系统代码后，参考 packages/anyboxagent/Test/plugin.test.ts。

工作流

1. 明确插件能力：MCP 工具、随包 skill、插件自带 connector，或平台 connector requirement。
2. 选择插件包结构。默认使用 Codex-like 展开目录。
3. 编写 .anybox-plugin/plugin.json，必须是严格 JSON，只使用运行时支持的顶层字段。
4. 在插件根目录添加运行文件，例如 skills/、connectors/、scripts/、docs/ 和 assets/。
5. 使用 Plugin.listCatalog() 验证 catalog 能发现插件。
6. 如果修改了插件系统运行时代码，运行 bun test Test/plugin.test.ts。

插件包结构

新插件默认使用这个结构：

<install-root>/
  <plugin-id>/
    .anybox-plugin/
      plugin.json
    skills/
      <skill-name>/
        SKILL.md
    connectors/
    scripts/
    docs/
    assets/

注意：

• <install-root> 是包含一个或多个插件包目录的父目录；开发新插件时优先把它作为 ANYBOX_PLUGIN_LOCAL_DIR。
• 当前运行时用 ANYBOX_PLUGIN_LOCAL_DIR 发现固定本地插件仓库，未设置时默认是 Agent data 目录下的 plugins/local。这个目录逻辑上等价于 GitHub 插件仓库，只提供可安装候选项，不受卸载流程删除。
• ANYBOX_PLUGIN_INSTALL_DIR 是受管理安装根目录，用于网络下载或从本地仓库安装时复制出来的插件包。这里的插件逻辑上属于已安装插件，运行时使用这里的副本，卸载时可能删除对应插件包。
• 运行时只读取 .anybox-plugin/plugin.json；根目录 plugin.json 不再作为 manifest 入口。
• skills、connectors、scripts、docs 和 assets 应放在插件根目录。
• 插件 ID 使用稳定的小写名称。目录名和 manifest name 尽量保持一致。
• 如果确实需要多个版本并存，也可以使用 <plugin-id>/<version>/.anybox-plugin/plugin.json，运行时会选择最高版本。

Manifest 规则

最小 manifest：

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "My first Anybox plugin."
}

支持的顶层字段包括：

• name、version、description
• author、homepage、repository、license、keywords
• interface
• mcpServers
• skills
• connectorRequirements
• connectors
• apps，仅用于旧兼容
• commands、agents，当前是保留字段
• skillPreviews is allowed in repository/registry plugin.json files for marketplace preview. package is optional and should only be present when a real downloadable artifact exists.
• Built-in registry index.json entries must point directly to HTTPS .anybox-plugin/plugin.json manifest URLs. Directory URLs are not supported.

未知顶层字段会被拒绝。

使用 interface 配置 catalog 展示信息：

{
  "interface": {
    "displayName": "Hello Anybox",
    "shortDescription": "A minimal plugin for learning plugin development.",
    "longDescription": "This plugin demonstrates a local stdio MCP server and a bundled Agent skill.",
    "developerName": "Your Name",
    "category": "Automation",
    "capabilities": ["demo", "mcp"],
    "logo": "HA",
    "brandColor": "#2563EB"
  }
}

优先使用已知 catalog 分类：Code、Browser、Git、Database、Docs、Automation 和 Design。

能力模式

不需要独立连接状态或凭据生命周期的工具，使用 mcpServers：

{
  "mcpServers": [
    {
      "id": "hello",
      "name": "Hello Anybox",
      "risk": "low",
      "permissions": ["Starts a local Node.js MCP server bundled with this plugin."],
      "tools": [
        {
          "name": "hello_echo",
          "title": "Echo Text",
          "description": "Echo text back to the user.",
          "readOnly": true
        }
      ],
      "runtime": {
        "transport": "stdio",
        "command": "node",
        "args": ["${PLUGIN_ROOT}/scripts/server.js"],
        "cwd": "${PLUGIN_ROOT}",
        "timeoutMs": 10000
      }
    }
  ]
}

插件需要给 Agent 提供说明时，使用 skills：

{
  "skills": "skills"
}

声明的 skill root 下，每个直接子目录都必须包含 SKILL.md。例如 skills/review/SKILL.md 会生成 plugin:<plugin-id>:review。

插件需要自带 API key 或 OAuth 状态时，使用 connectors：

{
  "connectors": [
    {
      "id": "weather",
      "name": "Weather",
      "risk": "medium",
      "permissions": ["Sends requests to api.weather.example."],
      "credential": {
        "kind": "api_key",
        "key": "WEATHER_API_KEY",
        "label": "Weather API key",
        "type": "password",
        "required": true,
        "secret": true
      },
      "runtime": {
        "transport": "stdio",
        "command": "node",
        "args": ["${PLUGIN_ROOT}/connectors/weather/server.js"],
        "cwd": "${PLUGIN_ROOT}",
        "env": {
          "WEATHER_API_KEY": "${WEATHER_API_KEY}"
        }
      },
      "tools": [
        {
          "name": "weather_current",
          "title": "Current Weather",
          "description": "Read current weather for a city.",
          "readOnly": true
        }
      ]
    }
  ]
}

插件要复用平台已有能力时，使用 connectorRequirements，例如 browser、GitHub 或 workspace files。

Runtime 规则

• 所有 ${PLUGIN_ROOT} 路径都必须留在插件包内部。
• stdio MCP server 的普通日志写 stderr。stdout 只能输出 JSON-RPC 消息。
• 本地 MCP server 必须响应 initialize、tools/list 和 tools/call。
• 只读工具标记 readOnly: true，破坏性操作标记 destructive: true。
• risk 使用 low、medium 或 high；不要使用 critical，除非插件安装应该被阻止。
• 不要提交 API key、OAuth client secret、access token、refresh token、本地 auth store、数据库或缓存目录。

验证

对候选插件来源根目录运行：

cd C:\Projects\anybox\packages\anyboxagent
$env:ANYBOX_PLUGIN_LOCAL_DIR = "C:\path\to\plugin-source-root"
$env:ANYBOX_PLUGIN_REGISTRY_INDEX_URL = "off"
bun -e "import * as Plugin from './src/plugin/plugin.ts'; console.log(JSON.stringify(await Plugin.listCatalog(), null, 2))"

确认输出里包含插件 ID、生成的 MCP server ID、connector-backed MCP server ID 和随包 skill ID。

修改插件系统运行时代码后运行：

cd C:\Projects\anybox\packages\anyboxagent
bun test Test/plugin.test.ts

常见失败

• 插件没有出现在 catalog：检查 ANYBOX_PLUGIN_LOCAL_DIR、目录结构、JSON 合法性、支持的顶层字段，以及必填的 name、version、description。只有验证下载/安装根目录时才检查 ANYBOX_PLUGIN_INSTALL_DIR。
• PLUGIN_CONFIG_INVALID：检查必填 configFields 或 OAuth client 设置。
• 诊断没有发现工具：检查命令是否可执行、runtime 路径、cwd、JSON-RPC 方法处理，以及 stdout 是否混入普通日志。
• Connector 未连接：API key connector 需要保存 key；OAuth connector 需要完成浏览器授权。
• 卸载时源码被删：开发时使用 ANYBOX_PLUGIN_LOCAL_DIR。不要直接把 Git 源码根目录当成 ANYBOX_PLUGIN_INSTALL_DIR；如果必须验证受管理安装根，复制或构建到 dev-install 目录。

Capture Tasks from Meeting Notes

Keywords

meeting notes, action items, create tasks, create tickets, extract tasks, parse notes, analyze notes, assigned work, assignees, from meeting, post-meeting, capture tasks, generate tasks, turn into tasks, convert to tasks, action item, to-do, task list, follow-up, assigned to, create Jira tasks, create Jira tickets, meeting action items, extract action items, find action items, analyze meeting

Overview

Automatically extract action items from meeting notes and create Jira tasks with proper assignees. This skill parses unstructured meeting notes (from Confluence or pasted text), identifies action items with assignees, looks up Jira account IDs, and creates tasks—eliminating the tedious post-meeting ticket creation process.

Use this skill when: Users have meeting notes with action items that need to become Jira tasks.

Workflow

Follow this 7-step process to turn meeting notes into actionable Jira tasks:

Step 1: Get Meeting Notes

Obtain the meeting notes from the user.

Option A: Confluence Page URL

If user provides a Confluence URL:

getConfluencePage(
  cloudId="...",
  pageId="[extracted from URL]",
  contentFormat="markdown"
)

URL patterns:

• https://[site].atlassian.net/wiki/spaces/[SPACE]/pages/[PAGE_ID]/[title]
• Extract PAGE_ID from the numeric portion
• Get cloudId from site name or use getAccessibleAtlassianResources

Option B: Pasted Text

If user pastes meeting notes directly:

• Use the text as-is
• No fetching needed

If Unclear

Ask: "Do you have a Confluence link to the meeting notes, or would you like to paste them directly?"

Step 2: Parse Action Items

Scan the notes for action items with assignees.

Common Patterns

Pattern 1: @mention format (highest priority)

@Sarah to create user stories for chat feature
@Mike will update architecture doc

Pattern 2: Name + action verb

Sarah to create user stories
Mike will update architecture doc
Lisa should review the mockups

Pattern 3: Action: Name - Task

Action: Sarah - create user stories
Action Item: Mike - update architecture

Pattern 4: TODO with assignee

TODO: Create user stories (Sarah)
TODO: Update docs - Mike

Pattern 5: Bullet with name

- Sarah: create user stories
- Mike - update architecture

Extraction Logic

For each action item, extract:

1. Assignee Name

   • Text after @ symbol
   • Name before "to", "will", "should"
   • Name after "Action:" or in parentheses
   • First/last name or full name

2. Task Description

   • Text after "to", "will", "should", "-", ":"
   • Remove markers (@, Action:, TODO:)
   • Keep original wording
   • Include enough context

3. Context (optional but helpful)

   • Meeting title/date if available
   • Surrounding discussion context
   • Related decisions

Example Parsing

Input:

# Product Planning - Dec 3

Action Items:
- @Sarah to create user stories for chat feature
- Mike will update the architecture doc
- Lisa: review and approve design mockups

Parsed:

1. Assignee: Sarah
   Task: Create user stories for chat feature
   Context: Product Planning meeting - Dec 3

2. Assignee: Mike
   Task: Update the architecture doc
   Context: Product Planning meeting - Dec 3

3. Assignee: Lisa
   Task: Review and approve design mockups
   Context: Product Planning meeting - Dec 3

Step 3: Ask for Project Key

Before looking up users or creating tasks, identify the Jira project.

Ask: "Which Jira project should I create these tasks in? (e.g., PROJ, PRODUCT, ENG)"

If User is Unsure

Call getVisibleJiraProjects to show options:

getVisibleJiraProjects(
  cloudId="...",
  action="create"
)

Present: "I found these projects you can create tasks in: PROJ (Project Alpha), PRODUCT (Product Team), ENG (Engineering)"

Step 4: Lookup Account IDs

For each assignee name, find their Jira account ID.

Lookup Process

lookupJiraAccountId(
  cloudId="...",
  searchString="[assignee name]"
)

The search string can be:

• Full name: "Sarah Johnson"
• First name: "Sarah"
• Last name: "Johnson"
• Email: "sarah@company.com"

Handle Results

Scenario A: Exact Match (1 result)

✅ Found: Sarah Johnson (sarah.johnson@company.com)
→ Use accountId from result

Scenario B: No Match (0 results)

⚠️ Couldn't find user "Sarah" in Jira.

Options:
1. Create task unassigned (assign manually later)
2. Skip this task
3. Try different name format (e.g., "Sarah Johnson")

Which would you prefer?

Scenario C: Multiple Matches (2+ results)

⚠️ Found multiple users named "Sarah":
1. Sarah Johnson (sarah.johnson@company.com)
2. Sarah Smith (sarah.smith@company.com)

Which user should be assigned the task "Create user stories"?

Best Practices

• Try full name first ("Sarah Johnson")
• If no match, try first name only ("Sarah")
• If still no match, ask user
• Cache results (don't lookup same person twice)

Step 5: Present Action Items

CRITICAL: Always show the parsed action items to the user BEFORE creating any tasks.

Presentation Format

I found [N] action items from the meeting notes. Should I create these Jira tasks in [PROJECT]?

1. [TASK] [Task description]
   Assigned to: [Name] ([email if found])
   Context: [Meeting title/date]

2. [TASK] [Task description]
   Assigned to: [Name] ([email if found])
   Context: [Meeting title/date]

[...continue for all tasks...]

Would you like me to:
1. Create all tasks
2. Skip some tasks (which ones?)
3. Modify any descriptions or assignees

Wait for Confirmation

Do NOT create tasks until user confirms. Options:

• "Yes, create all" → proceed
• "Skip task 3" → create all except #3
• "Change assignee for task 2" → ask for new assignee
• "Edit description" → ask for changes

Step 6: Create Tasks

Once confirmed, create each Jira task.

Determine Issue Type

Before creating tasks, check what issue types are available in the project:

getJiraProjectIssueTypesMetadata(
  cloudId="...",
  projectIdOrKey="PROJ"
)

Choose the appropriate issue type:

• Use "Task" if available (most common)
• Use "Story" for user-facing features
• Use "Bug" if it's a defect
• If "Task" doesn't exist, use the first available issue type or ask the user

For Each Action Item

createJiraIssue(
  cloudId="...",
  projectKey="PROJ",
  issueTypeName="[Task or available type]",
  summary="[Task description]",
  description="[Full description with context]",
  assignee_account_id="[looked up account ID]"
)

Task Summary Format

Use action verbs and be specific:

• ✅ "Create user stories for chat feature"
• ✅ "Update architecture documentation"
• ✅ "Review and approve design mockups"
• ❌ "Do the thing" (too vague)

Task Description Format

**Action Item from Meeting Notes**

**Task:** [Original action item text]

**Context:**
[Meeting title/date]
[Relevant discussion points or decisions]

**Source:** [Link to Confluence meeting notes if available]

**Original Note:**
> [Exact quote from meeting notes]

Example:

**Action Item from Meeting Notes**

**Task:** Create user stories for chat feature

**Context:**
Product Planning Meeting - December 3, 2025
Discussed Q1 roadmap priorities and new feature requirements

**Source:** https://yoursite.atlassian.net/wiki/spaces/TEAM/pages/12345

**Original Note:**
> @Sarah to create user stories for chat feature

Step 7: Provide Summary

After all tasks are created, present a comprehensive summary.

Format:

✅ Created [N] tasks in [PROJECT]:

1. [PROJ-123] - [Task summary]
   Assigned to: [Name]
   https://yoursite.atlassian.net/browse/PROJ-123

2. [PROJ-124] - [Task summary]
   Assigned to: [Name]
   https://yoursite.atlassian.net/browse/PROJ-124

[...continue for all created tasks...]

**Source:** [Link to meeting notes]

**Next Steps:**
- Review tasks in Jira for accuracy
- Add any additional details or attachments
- Adjust priorities if needed
- Link related tickets if applicable

Action Item Pattern Examples

Pattern 1: @Mentions (Most Explicit)

@john to update documentation
@sarah will create the report
@mike should review PR #123

Parsed:

• Assignee: john/sarah/mike
• Task: update documentation / create the report / review PR #123

Pattern 2: Name + Action Verb

John to update documentation
Sarah will create the report
Mike should review PR #123
Lisa needs to test the feature

Parsed:

• Assignee: name before action verb
• Task: text after "to/will/should/needs to"

Pattern 3: Structured Action Format

Action: John - update documentation
Action Item: Sarah - create the report
AI: Mike - review PR #123

Parsed:

• Assignee: name after "Action:" and before "-"
• Task: text after "-"

Pattern 4: TODO Format

TODO: Update documentation (John)
TODO: Create report - Sarah
[ ] Mike: review PR #123

Parsed:

• Assignee: name in parentheses or after ":"
• Task: text between TODO and assignee

Pattern 5: Bullet Lists

- John: update documentation
- Sarah - create the report
* Mike will review PR #123

Parsed:

• Assignee: name before ":" or "-" or action verb
• Task: remaining text

Handling Edge Cases

No Action Items Found

If no action items with assignees are detected:

I analyzed the meeting notes but couldn't find any action items with clear assignees.

Action items typically follow patterns like:
- @Name to do X
- Name will do X
- Action: Name - do X
- TODO: X (Name)

Options:
1. I can search for TODO items without assignees
2. You can point out specific action items to create
3. I can create tasks for bullet points you specify

What would you like to do?

Mixed Formats

If some action items have assignees and some don't:

I found [N] action items:
- [X] with clear assignees
- [Y] without assignees

Should I:
1. Create all [N] tasks ([X] assigned, [Y] unassigned)
2. Only create the [X] tasks with assignees
3. Ask you to assign the [Y] unassigned tasks

Which option would you prefer?

Assignee Name Variations

If the same person is mentioned different ways:

Notes mention: @sarah, Sarah, Sarah J.

These likely refer to the same person. I'll look up "Sarah" once and use 
that account ID for all three mentions. Is that correct?

Duplicate Action Items

If the same task appears multiple times:

I found what appears to be the same action item twice:
1. "@Sarah to create user stories" (line 15)
2. "Action: Sarah - create user stories" (line 42)

Should I:
1. Create one task (combine duplicates)
2. Create two separate tasks
3. Skip the duplicate

What would you prefer?

Long Task Descriptions

If action item text is very long (>200 characters):

The task "[long text...]" is quite detailed.

Should I:
1. Use first sentence as summary, rest in description
2. Use full text as summary
3. Let you edit it to be more concise

Which would you prefer?

Tips for High-Quality Results

Do:

✅ Use consistent @mention format in notes
✅ Include full names when possible
✅ Be specific in action item descriptions
✅ Add context (why/what/when)
✅ Review parsed tasks before confirming

Don't:

❌ Mix multiple tasks for one person in one bullet
❌ Use ambiguous names (just "John" if you have 5 Johns)
❌ Skip action verbs (unclear what to do)
❌ Forget to specify project

Best Meeting Notes Format

# Meeting Title - Date

Attendees: [Names]

## Decisions
[What was decided]

## Action Items
- @FullName to [specific task with context]
- @AnotherPerson will [specific task with context]
- etc.

When NOT to Use This Skill

This skill is for converting meeting action items to Jira tasks only.

Don't use for: ❌ Summarizing meetings (no task creation)
❌ Finding meeting notes (use search skill)
❌ Creating calendar events
❌ Sending meeting notes via email
❌ General note-taking

Use only when: Meeting notes exist and action items need to become Jira tasks.

Examples

Example 1: Simple @Mentions

Input:

Team Sync - Dec 3, 2025

Action Items:
- @Sarah to create user stories for chat feature
- @Mike will update the architecture doc
- @Lisa should review design mockups

Process:

1. Parse → 3 action items found
2. Project → "PROJ"
3. Lookup → Sarah (123), Mike (456), Lisa (789)
4. Present → User confirms
5. Create → PROJ-100, PROJ-101, PROJ-102

Output:

✅ Created 3 tasks in PROJ:

1. PROJ-100 - Create user stories for chat feature
   Assigned to: Sarah Johnson
   
2. PROJ-101 - Update the architecture doc
   Assigned to: Mike Chen
   
3. PROJ-102 - Review design mockups
   Assigned to: Lisa Park

Example 2: Mixed Formats

Input:

Product Review Meeting

Discussed new features and priorities.

Follow-ups:
- Sarah will draft the PRD
- Mike: implement API changes
- TODO: Review security audit (Lisa)
- Update stakeholders on timeline

Process:

1. Parse → Found 4 items (3 with assignees, 1 without)
2. Ask → "Found 3 with assignees, 1 without. Create all or only assigned?"
3. User → "All, make the last one unassigned"
4. Create → 4 tasks (3 assigned, 1 unassigned)

Example 3: Name Lookup Issue

Input:

Sprint Planning

Action Items:
- @John to update tests
- @Sarah to refactor code

Process:

1. Parse → 2 action items
2. Lookup "John" → Found 3 Johns!
3. Ask → "Which John? (John Smith, John Doe, John Wilson)"
4. User → "John Smith"
5. Create → Both tasks assigned correctly

Quick Reference

Primary tool: getConfluencePage (if URL) or use pasted text
Account lookup: lookupJiraAccountId(searchString)
Task creation: createJiraIssue with assignee_account_id

Action patterns to look for:

• @Name to/will/should X
• Name to/will/should X
• Action: Name - X
• TODO: X (Name)
• Name: X

Always:

• Present parsed tasks before creating
• Handle name lookup failures gracefully
• Include context in task descriptions
• Provide summary with links

Remember:

• Human-in-loop is critical (show before creating)
• Name lookup can fail (have fallback)
• Be flexible with pattern matching
• Context preservation is important

Generate Status Report

Keywords

status report, project status, weekly update, daily standup, Jira report, project summary, blockers, progress update, Confluence report, sprint report, project update, publish to Confluence, write to Confluence, post report

Automatically query Jira for project status, analyze issues, and generate formatted status reports published to Confluence.

CRITICAL: This skill should be interactive. Always clarify scope (time period, audience, Confluence destination) with the user before or after generating the report. Do not silently skip Confluence publishing—always offer it.

Workflow

Generating a status report follows these steps:

1. Identify scope - Determine project, time period, and target audience
2. Query Jira - Fetch relevant issues using JQL queries
3. Analyze data - Categorize issues and identify key insights
4. Format report - Structure content based on audience and purpose
5. Publish to Confluence - Create or update a page with the report

Step 1: Identify Scope

IMPORTANT: If the user's request is missing key information, ASK before proceeding with queries. Do not assume defaults without confirmation for Confluence publishing.

Clarify these details:

Project identification:

• Which Jira project key? (e.g., "PROJ", "ENG", "MKTG")
• If the user mentions a project by name but not key, search Jira to find the project key

Time period:

• If not specified, ask: "What time period should this report cover? (default: last 7 days)"
• Options: Weekly (7 days), Daily (24 hours), Sprint-based (2 weeks), Custom period

Target audience:

• If not specified, ask: "Who is this report for? (Executives/Delivery Managers, Team-level, or Daily standup)"
• Executives/Delivery Managers: High-level summary with key metrics and blockers
• Team-level: Detailed breakdown with issue-by-issue status
• Daily standup: Brief update on yesterday/today/blockers

Report destination:

• ALWAYS ASK if not specified: "Would you like me to publish this report to Confluence? If so, which space should I use?"
• If user says yes: Ask for space name or offer to list available spaces
• Determine: New page or update existing page?
• Ask about parent page if creating under a specific section

Step 2: Query Jira

Use the searchJiraIssuesUsingJql tool to fetch issues. Build JQL queries based on report needs.

Common Query Patterns

For comprehensive queries, use the scripts/jql_builder.py utility to programmatically build JQL strings. For quick queries, reference references/jql-patterns.md for examples.

All open issues in project:

project = "PROJECT_KEY" AND status != Done ORDER BY priority DESC, updated DESC

Issues updated in last week:

project = "PROJECT_KEY" AND updated >= -7d ORDER BY priority DESC

High priority and blocked issues:

project = "PROJECT_KEY" AND (priority IN (Highest, High) OR status = Blocked) AND status != Done ORDER BY priority DESC

Completed in reporting period:

project = "PROJECT_KEY" AND status = Done AND resolved >= -7d ORDER BY resolved DESC

Query Strategy

For most reports, execute multiple targeted queries rather than one large query:

1. Completed issues: Get recently resolved tickets
2. In-progress issues: Get active work items
3. Blocked issues: Get blockers requiring attention
4. High priority open: Get critical upcoming work

Use maxResults: 100 for initial queries. If pagination is needed, use nextPageToken from results.

Data to Extract

For each issue, capture:

• key (e.g., "PROJ-123")
• summary (issue title)
• status (current state)
• priority (importance level)
• assignee (who's working on it)
• created / updated / resolved dates
• description (if needed for context on blockers)

Step 3: Analyze Data

Process the retrieved issues to identify:

Metrics:

• Total issues by status (Done, In Progress, Blocked, etc.)
• Completion rate (if historical data available)
• Number of high priority items
• Unassigned issue count

Key insights:

• Major accomplishments (recently completed high-value items)
• Critical blockers (blocked high priority issues)
• At-risk items (overdue or stuck in progress)
• Resource bottlenecks (one assignee with many issues)

Categorization: Group issues logically:

• By status (Done, In Progress, Blocked)
• By priority (Highest → Low)
• By assignee or team
• By component or epic (if relevant)

Step 4: Format Report

Select the appropriate template based on audience. Templates are in references/report-templates.md.

For Executives and Delivery Managers

Use Executive Summary Format:

• Brief overall status (🟢 On Track / 🟡 At Risk / 🔴 Blocked)
• Key metrics (total, completed, in progress, blocked)
• Top 3 highlights (major accomplishments)
• Critical blockers with impact
• Upcoming priorities

Keep it concise - 1-2 pages maximum. Focus on what matters to decision-makers.

For Team-Level Reports

Use Detailed Technical Format:

• Completed issues listed with keys
• In-progress issues with assignee and priority
• Blocked issues with blocker description and action needed
• Risks and dependencies
• Next period priorities

Include more detail - Team needs issue-level visibility.

For Daily Updates

Use Daily Standup Format:

• What was completed yesterday
• What's planned for today
• Current blockers
• Brief notes

Keep it brief - This is a quick sync, not comprehensive analysis.

Step 5: Publish to Confluence

After generating the report, ALWAYS offer to publish to Confluence (unless user explicitly said not to).

If user hasn't specified Confluence details yet, ask:

• "Would you like me to publish this report to Confluence?"
• "Which Confluence space should I use?"
• "Should this be nested under a specific parent page?"

Use the createConfluencePage tool to publish the report.

Page creation:

createConfluencePage(
    cloudId="[obtained from getConfluenceSpaces or URL]",
    spaceId="[numerical space ID]",
    title="[Project Name] - Status Report - [Date]",
    body="[formatted report in Markdown]",
    contentFormat="markdown",
    parentId="[optional - parent page ID if nesting under another page]"
)

Title format examples:

• "Project Phoenix - Weekly Status - Dec 3, 2025"
• "Engineering Sprint 23 - Status Report"
• "Q4 Initiatives - Status Update - Week 49"

Body formatting: Write the report content in Markdown. The tool will convert it to Confluence format. Use:

• Headers (#, ##, ###) for structure
• Bullet points for lists
• Bold (**text**) for emphasis
• Tables for metrics if needed
• Links to Jira issues: [PROJ-123](https://yourinstance.atlassian.net/browse/PROJ-123)

Best practices:

• Include the report date prominently
• Link directly to relevant Jira issues
• Use consistent naming conventions for recurring reports
• Consider creating under a "Status Reports" parent page for organization

Finding the Right Space

If the user doesn't specify a Confluence space:

1. Use getConfluenceSpaces to list available spaces
2. Look for spaces related to the project (matching project name or key)
3. If unsure, ask the user which space to use
4. Default to creating in the most relevant team or project space

Updating Existing Reports

If updating an existing page instead of creating new:

1. Get the current page content:

getConfluencePage(
    cloudId="...",
    pageId="123456",
    contentFormat="markdown"
)

2. Update the page with new content:

updateConfluencePage(
    cloudId="...",
    pageId="123456",
    body="[updated report content]",
    contentFormat="markdown",
    versionMessage="Updated with latest status - Dec 8, 2025"
)

Complete Example Workflow

User request: "Generate a status report for Project Phoenix and publish it to Confluence"

Step 1 - Identify scope:

• Project: Phoenix (need to find project key)
• Time period: Last week (default)
• Audience: Not specified, assume executive level
• Destination: Confluence, need to find appropriate space

Step 2 - Query Jira:

# Find project key first
searchJiraIssuesUsingJql(
    cloudId="...",
    jql='project = "PHOENIX" OR project = "PHX"',
    maxResults=1
)

# Query completed issues
searchJiraIssuesUsingJql(
    cloudId="...",
    jql='project = "PHX" AND status = Done AND resolved >= -7d',
    maxResults=50
)

# Query blocked issues
searchJiraIssuesUsingJql(
    cloudId="...",
    jql='project = "PHX" AND status = Blocked',
    maxResults=50
)

# Query in-progress high priority
searchJiraIssuesUsingJql(
    cloudId="...",
    jql='project = "PHX" AND status IN ("In Progress", "In Review") AND priority IN (Highest, High)',
    maxResults=50
)

Step 3 - Analyze:

• 15 issues completed (metrics)
• 3 critical blockers (key insight)
• Major accomplishment: API integration completed (highlight)

Step 4 - Format: Use Executive Summary Format from templates. Create concise report with metrics, highlights, and blockers.

Step 5 - Publish:

# Find appropriate space
getConfluenceSpaces(cloudId="...")

# Create page
createConfluencePage(
    cloudId="...",
    spaceId="12345",
    title="Project Phoenix - Weekly Status - Dec 3, 2025",
    body="[formatted markdown report]",
    contentFormat="markdown"
)

Tips for Quality Reports

Be data-driven:

• Include specific numbers and metrics
• Reference issue keys directly
• Show trends when possible (e.g., "completed 15 vs 12 last week")

Highlight what matters:

• Lead with the most important information
• Flag blockers prominently
• Celebrate significant wins

Make it actionable:

• For blockers, state what action is needed and from whom
• For risks, provide mitigation options
• For priorities, be specific about next steps

Keep it consistent:

• Use the same format for recurring reports
• Maintain predictable structure
• Include comparable metrics week-over-week

Provide context:

• Link to Jira for details
• Explain the impact of blockers
• Connect work to business objectives when possible

Resources

scripts/jql_builder.py

Python utility for programmatically building JQL queries. Use this when you need to construct complex or dynamic queries. Import and use the helper functions rather than manually concatenating JQL strings.

references/jql-patterns.md

Quick reference of common JQL query patterns for status reports. Use this for standard queries or as a starting point for custom queries.

references/report-templates.md

Detailed templates for different report types and audiences. Reference this to select the appropriate format and structure for your report.

Box Content API

Overview

Implement Box content workflows in application code. Reuse the repository's existing auth and HTTP or SDK stack whenever possible, identify the acting Box identity before coding, and make the smallest end-to-end path work before layering on sharing, metadata, webhooks, or AI.

Route The Request

Workflow

Follow these steps in order when coding against Box.

1. Inspect the repository for existing Box auth, SDK or HTTP client, env vars, webhook handlers, Box ID persistence, and tests.
2. Determine the acting identity before choosing endpoints: connected user, enterprise service account, app user, or platform-provided token.
3. Identify the primary Box object and choose the matching reference from the routing table above.
4. Confirm whether the task changes access or data exposure. Shared links, collaborations, auth changes, large-scale downloads, and broad AI retrieval all need explicit user confirmation before widening access or scope.
5. Read only the matching reference files:
   • Auth setup, actor selection, SDK vs REST: references/auth-and-setup.md
   • Box CLI local verification: references/box-cli.md
   • Workflow router: references/workflows.md
   • Content operations: references/content-workflows.md
   • Bulk file organization, batch moves, folder restructuring: references/bulk-operations.md
   • Webhooks and events: references/webhooks-and-events.md
   • AI and retrieval: references/ai-and-retrieval.md
   • Debugging and failure modes: references/troubleshooting.md
6. Implement the smallest end-to-end flow that proves the integration works.
7. Add a runnable verification step. Prefer the repository's tests first; otherwise use scripts/box_cli_smoke.py when Box CLI is available and authenticated, and scripts/box_rest.py as a fallback.
8. Summarize the deliverable with auth context, Box IDs, env vars or config, and the exact verification command or test.

Guardrails

• Preserve the existing Box auth model unless the user explicitly asks to change it.
• Check the current official Box docs before introducing a new auth path, changing auth scope, or changing Box AI behavior.
• Prefer an official Box SDK when the codebase already uses one or the target language has a maintained SDK. Otherwise use direct REST calls with explicit request and response handling.
• Keep access tokens, client secrets, private keys, and webhook secrets in env vars or the project's secret manager.
• Distinguish file IDs, folder IDs, shared links, metadata template identifiers, and collaboration IDs.
• Treat shared links, collaborations, and metadata writes as permission-sensitive changes. Confirm audience, scope, and least privilege before coding or applying them.
• Require explicit confirmation before widening external access, switching the acting identity, or retrieving more document content than the task truly needs.
• When a task requires understanding document content — classification, extraction, categorization — use Box AI (Q&A, extract) as the first method attempted. Box AI operates server-side and does not require downloading file bodies. Fall back to metadata inspection, previews, or local analysis only if Box AI is unavailable, not authorized, or returns an error on the first attempt.
• Pace Box AI calls at least 1–2 seconds apart. For content-based classification of many files, classify a small sample first to validate the prompt and discover whether cheaper signals (filename, extension, metadata) can sort the remaining files without additional AI calls.
• Avoid downloading file bodies or routing content through external AI pipelines when Box-native methods (Box AI, search, metadata, previews) can answer the question server-side.
• Connected Box tool availability can vary by account. If a Box MCP call returns Tool <name> not found, treat that tool as unavailable for the rest of the current task. Do not retry it with different arguments or call it again later; switch to an available fallback.
• For connected Box app or MCP text reads, use get_file_content or Deep Research fetch only when the file is likely to have markdown or extracted-text content. If Box says markdown or text representation is unavailable, do not retry the same text read; switch to preview, metadata, or the next scoped fallback.
• For connected Box previews, avoid get_file_preview for files known to exceed 3 MB. Reuse size from existing search, listing, or details results when it is already available.
• Request only the fields the application actually needs, and persist returned Box IDs instead of reconstructing paths later.
• Run Box CLI commands strictly one at a time. The CLI does not support concurrent invocations and parallel calls cause auth conflicts and dropped operations. For bulk work (organizing, batch moves, batch metadata), default to REST over CLI.
• Make webhook and event consumers idempotent. Box delivery and retry paths can produce duplicates.
• Keep AI retrieval narrow for search and Q&A tasks. Search and filter first, then retrieve only the files needed for the answer. This does not apply to Box AI classification — when classifying documents, Box AI should be tried first per the content-understanding guardrail above.
• Do not use box configure:environments:get --current as a routine auth check because it can print sensitive environment details.

Verification

• Prefer the repository's existing tests, scripts, or app flows when they already cover the changed Box behavior.
• If no better verification path exists, prefer scripts/box_cli_smoke.py when box is installed and authenticated. Fall back to scripts/box_rest.py with BOX_ACCESS_TOKEN when CLI auth is unavailable or the task specifically needs direct bearer-token verification.
• Confirm CLI auth with box users:get me --json or scripts/box_cli_smoke.py check-auth.
• Verify mutations with a read-after-write call using the same actor, and record the object ID.
• For webhooks, test the minimal happy path, duplicate delivery, and signature failure handling.
• For AI flows, test retrieval quality separately from answer formatting.

Example smoke checks:

python3 scripts/box_cli_smoke.py check-auth
python3 scripts/box_cli_smoke.py get-folder 0 --fields id name item_collection
python3 scripts/box_cli_smoke.py list-folder-items 0 --max-items 20
python3 scripts/box_cli_smoke.py search "invoice" --limit 10
python3 scripts/box_rest.py get-item --item-type folder --item-id 0 --fields id name item_collection

Deliverable

The final answer should include:

• Acting auth context used for the change
• Box object type and IDs touched
• Env vars, secrets, or config expected by the integration
• Files or endpoints added or changed
• Exact verification command, script, or test path
• Any permission-sensitive assumptions that still need confirmation

References

• references/auth-and-setup.md: auth path selection, SDK vs REST choice, existing-codebase inspection, and current Box doc anchors
• references/box-cli.md: CLI-first local auth, smoke-test commands, and safe verification patterns
• references/workflows.md: quick workflow router when the task is ambiguous
• references/content-workflows.md: uploads, folders, listings, downloads, shared links, collaborations, metadata, and file moves
• references/bulk-operations.md: organizing files at scale, batch moves, folder hierarchy creation, serial execution, and rate-limit handling
• references/webhooks-and-events.md: webhook setup, event-feed usage, idempotency, and verification
• references/ai-and-retrieval.md: search-first retrieval, Box AI usage, and external AI guardrails
• references/troubleshooting.md: common failure modes and a debugging checklist
• examples/box-content-api-prompts.md: example prompts for realistic use cases

Browser

Use the Browser MCP tools and Node REPL browser runtime from this plugin to inspect and control Chrome through the Anybox browser extension.

Start with browser_status when connection state is unclear. Prefer browser_open_tab for new work and carry the returned tabId into later calls. Use browser_interactive_snapshot before element-level actions, then pass the returned elementId to browser_click_element or browser_fill. Use browser_wait_for after navigation or actions that change the page.

For multi-step browser workflows, page inspection that needs JavaScript, or raw CDP access, use node_repl_js and initialize the browser runtime:

await setupBrowserRuntime({ globals: globalThis })
globalThis.browser = await agent.browsers.get("extension")

After initialization, use browser.tabs.list(), browser.tabs.open(url), browser.tabs.get(tabId), tab.snapshot(), tab.screenshot(), tab.click(), tab.fill(), tab.evaluate(), tab.cdp.send(), and tab.playwright.*. Use raw evaluate and CDP only when the normal browser_* tools are not sufficient.

iOS App Intents

Overview

Expose the smallest useful action and entity surface to the system. Start with the verbs and objects people would actually want outside the app, then implement a narrow App Intents layer that can deep-link or hand off cleanly into the main app when needed.

Read these references as needed:

• references/first-pass-checklist.md for choosing the first intent and entity surface
• references/example-patterns.md for concrete example shapes to copy and adapt
• references/code-templates.md for generalized App Intents code templates
• references/system-surfaces.md for how to think about Shortcuts, Siri, Spotlight, widgets, and other system entry points

Core workflow

1) Start with actions, not screens

• Identify the 1-3 highest-value actions that should work outside the app UI.
• Prefer verbs like compose, open, find, filter, continue, inspect, or start.
• Do not mirror the entire app navigation tree as intents.

2) Define a small entity surface

• Add AppEntity types only for the objects the system needs to understand or route.
• Keep the entity shape narrower than the app's persistence model.
• Add EntityQuery or other query types only where disambiguation or suggestions are genuinely useful.

3) Decide whether the action completes in place or opens the app

• Use non-opening intents for actions that can complete directly from the system surface.
• Use openAppWhenRun or open-style intents when the user should land in a specific in-app workflow.
• When the app must react inside the main scene, add one clear runtime handoff path instead of scattering ad hoc routing logic.
• If the action can work in both modes, consider shipping both an inline version and an open-app version rather than forcing one compromise.

4) Make the actions discoverable

• Add AppShortcutsProvider entries for the first set of high-value intents.
• Choose titles, phrases, and symbols that make sense in Shortcuts, Siri, and Spotlight.
• Keep shortcut phrases direct and task-oriented.
• Reuse the same action model for widgets and controls when a widget configuration or intent-driven control already needs the same parameters.

5) Validate the runtime handoff

• Build the app and confirm the intents target compiles cleanly.
• Verify the app opens or routes to the expected place when an intent runs.
• Summarize which actions are now exposed, which entities back them, and how the app handles invocation.

Strong defaults

• Prefer a dedicated intents target or module for the system-facing layer.
• Keep intent types thin; business logic should stay in app services or domain models.
• Keep app entities small and display-friendly.
• Use AppEnum for fixed app choices such as tabs, modes, or visibility levels before reaching for a full entity type.
• Prefer one predictable app-intent routing surface in the main app scene or root router.
• Treat App Intents as system integration infrastructure, not only as a Shortcuts feature.

Anti-patterns

• Exposing every screen or tab as its own intent without a real user value.
• Mirroring the entire model graph as AppEntity types.
• Hiding runtime handoff in global side effects with no clear app entry path.
• Adding App Shortcuts with vague phrases or generic titles.
• Treating the first App Intents pass as a broad taxonomy project instead of a small useful release.

Notes

• Apple documentation to use as primary references:
  • https://developer.apple.com/documentation/appintents/making-actions-and-content-discoverable-and-widely-available
  • https://developer.apple.com/documentation/appintents/creating-your-first-app-intent
  • https://developer.apple.com/documentation/appintents/adopting-app-intents-to-support-system-experiences
• In addition to the links above, use web search to consult current Apple Developer documentation when App Intents APIs or platform behavior may have changed.
• A good first pass often includes one open-app intent, one action intent, one or two entity types, and a small AppShortcutsProvider.
• Good example families to cover are:
  • open a destination or editor in the app
  • perform a lightweight action inline without opening the app
  • choose from a fixed enum such as a tab or mode
  • resolve one or more entities through EntityQuery
  • power widget configuration or controls from the same entity surface

iOS Debugger Agent

Overview

Use XcodeBuildMCP to build and run the current project scheme on a booted iOS simulator, interact with the UI, and capture logs. Prefer the MCP tools for simulator control, logs, and view inspection.

Core Workflow

Follow this sequence unless the user asks for a narrower action.

1) Discover the booted simulator

• Call mcp__XcodeBuildMCP__list_sims and select the simulator with state Booted.
• If none are booted, ask the user to boot one (do not boot automatically unless asked).

2) Set session defaults

• Call mcp__XcodeBuildMCP__session-set-defaults with:
  • projectPath or workspacePath (whichever the repo uses)
  • scheme for the current app
  • simulatorId from the booted device
  • Optional: configuration: "Debug", useLatestOS: true

3) Build + run (when requested)

• Call mcp__XcodeBuildMCP__build_run_sim.
• If the build fails, check the error output and retry (optionally with preferXcodebuild: true) or escalate to the user before attempting any UI interaction.
• After a successful build, verify the app launched by calling mcp__XcodeBuildMCP__describe_ui or mcp__XcodeBuildMCP__screenshot before proceeding to UI interaction.
• If the app is already built and only launch is requested, use mcp__XcodeBuildMCP__launch_app_sim.
• If bundle id is unknown:
  1. mcp__XcodeBuildMCP__get_sim_app_path
  2. mcp__XcodeBuildMCP__get_app_bundle_id

UI Interaction & Debugging

Use these when asked to inspect or interact with the running app.

• Describe UI: mcp__XcodeBuildMCP__describe_ui before tapping or swiping.
• Tap: mcp__XcodeBuildMCP__tap (prefer id or label; use coordinates only if needed).
• Type: mcp__XcodeBuildMCP__type_text after focusing a field.
• Gestures: mcp__XcodeBuildMCP__gesture for common scrolls and edge swipes.
• Screenshot: mcp__XcodeBuildMCP__screenshot for visual confirmation.

Logs & Console Output

• Start logs: mcp__XcodeBuildMCP__start_sim_log_cap with the app bundle id.
• Stop logs: mcp__XcodeBuildMCP__stop_sim_log_cap and summarize important lines.
• For console output, set captureConsole: true and relaunch if required.

Troubleshooting

• If build fails, ask whether to retry with preferXcodebuild: true.
• If the wrong app launches, confirm the scheme and bundle id.
• If UI elements are not hittable, re-run describe_ui after layout changes.

iOS ETTrace Performance

Use this skill to capture a focused, symbolicated ETTrace profile from an iOS simulator app. Pair it with ../ios-debugger-agent/SKILL.md when the task also needs simulator build, install, launch, UI driving, logs, or screenshots.

Core Workflow

1. Pick one focused flow and write down the expected start and stop points.
2. Build the exact simulator app that will be installed and profiled.
3. Temporarily link ETTrace into that app target for simulator/debug profiling.
4. Collect UUID-matched dSYMs for the app executable and embedded dynamic frameworks.
5. Capture one launch or runtime trace.
6. Preserve the processed flamegraph JSON immediately after the run.
7. Analyze only the processed JSON and report the flow, artifacts, hotspots, and caveats.

Avoid broad "use the app for a while" captures. One trace should correspond to one user-visible flow.

Setup

Use a writable run folder for each profiling session:

if [ -z "${RUN_DIR:-}" ]; then
  RUN_DIR="$(mktemp -d "${TMPDIR:-/tmp}/codex-ios-ettrace.XXXXXX")"
fi
mkdir -p "$RUN_DIR"

Install the ETTrace runner CLI if it is not already available:

brew install emergetools/homebrew-tap/ettrace

ettrace is the host-side macOS runner. The app must also link an ETTrace.xcframework for the iOS Simulator architecture. This workflow is validated for ETTrace v1.1.0 processed output_<thread>.json files with top-level nodes.

Link ETTrace Into The App

Wire ETTrace into the exact app target being profiled. Keep the integration in a clearly temporary patch and remove it when the profiling task is done unless the user explicitly asks to keep it.

Preferred options:

• Reuse an existing simulator-compatible ETTrace.xcframework if the repo already vendors one.
• If none exists, build a simulator-only copy into RUN_DIR from the upstream ETTrace package.
• Link the framework directly into the app target, not only into tests, resources, data files, or a nested launcher target.
• Confirm launch logs print Starting ETTrace.
• Profile only one ETTrace-instrumented simulator app at a time because simulator mode listens on a fixed localhost port.

Build a simulator framework when needed:

ETTRACE_TAG="${ETTRACE_TAG:-v1.1.0}" # Override to match the installed runner when Homebrew updates.
ETTRACE_SRC="$RUN_DIR/ETTrace-src"
if [ ! -d "$ETTRACE_SRC" ]; then
  git clone --depth 1 --branch "$ETTRACE_TAG" https://github.com/EmergeTools/ETTrace "$ETTRACE_SRC"
fi

rm -rf "$RUN_DIR/ETTrace-iphonesimulator.xcarchive" "$RUN_DIR/ETTrace.xcframework"
pushd "$ETTRACE_SRC" >/dev/null
xcodebuild archive \
  -scheme ETTrace \
  -archivePath "$RUN_DIR/ETTrace-iphonesimulator.xcarchive" \
  -sdk iphonesimulator \
  -destination 'generic/platform=iOS Simulator' \
  BUILD_LIBRARY_FOR_DISTRIBUTION=YES \
  INSTALL_PATH='Library/Frameworks' \
  SKIP_INSTALL=NO \
  CLANG_CXX_LANGUAGE_STANDARD=c++17

xcodebuild -create-xcframework \
  -framework "$RUN_DIR/ETTrace-iphonesimulator.xcarchive/Products/Library/Frameworks/ETTrace.framework" \
  -output "$RUN_DIR/ETTrace.xcframework"
popd >/dev/null

For Bazel apps, a temporary import usually looks like:

load("@rules_apple//apple:apple.bzl", "apple_dynamic_xcframework_import")

package(default_visibility = ["//visibility:public"])

apple_dynamic_xcframework_import(
    name = "ETTrace",
    xcframework_imports = glob(["ETTrace.xcframework/**"]),
)

For Xcode projects, temporarily add the simulator ETTrace.xcframework to the app target's Link Binary With Libraries / Embed Frameworks phases for the debug simulator build you are profiling, then remove that wiring after profiling.

Symbolication Gate

Do not draw conclusions from an unsymbolicated flamegraph. Before every capture, prepare a dSYM folder that includes the app dSYM and any embedded first-party dynamic framework dSYMs.

Collect dSYMs after the final build that produced the installed app:

SKILL_DIR="<absolute path to this loaded skill folder>"
APP="<path-to-built-simulator-App.app>"
DSYMS="$RUN_DIR/dsyms"

"$SKILL_DIR/scripts/collect_ios_dsyms.sh" \
  --app "$APP" \
  --out-dir "$DSYMS" \
  --search-root "$(dirname "$APP")" \
  --search-root "$PWD" \
  --extra-dsym "$RUN_DIR/ETTrace-iphonesimulator.xcarchive/dSYMs/ETTrace.framework.dSYM"

Add --require-framework <FrameworkName> for app-owned dynamic frameworks that must symbolicate; use --require-all-frameworks only when every embedded framework is app-owned or expected to have symbols. If the helper reports a missing required app or framework dSYM, rebuild the exact simulator app with dSYM generation before tracing, or add the build output directory that contains those dSYMs as another --search-root.

Verify important UUIDs before tracing when the report looks suspicious:

dwarfdump --uuid "$APP/$(/usr/libexec/PlistBuddy -c 'Print :CFBundleExecutable' "$APP/Info.plist")"
find "$DSYMS" -maxdepth 1 -type d -name '*.dSYM' -print -exec dwarfdump --uuid {} \;

After ETTrace exits, read its symbolication summary. Treat meaningful first-party "have library but no symbol" lines as a failed trace unless they are tiny noise. Unsymbolicated system-framework or ETTrace internal buckets are usually acceptable.

Capture

For launch traces:

cd "$RUN_DIR"
CAPTURE_MARKER="$RUN_DIR/.ettrace-capture-start"
: > "$CAPTURE_MARKER"
find "$RUN_DIR" -maxdepth 1 \( -name 'output.json' -o -name 'output_*.json' \) -delete
ettrace --simulator --launch --verbose --dsyms "$DSYMS"

Use --launch only when measuring startup or first render. The first launch connection can force quit the app; relaunch from the simulator home screen rather than Xcode if prompted. For first-launch-after-install traces, temporarily set ETTraceRunAtStartup=YES in the app Info.plist, then run ettrace --simulator and launch from the home screen.

For runtime flow traces:

cd "$RUN_DIR"
CAPTURE_MARKER="$RUN_DIR/.ettrace-capture-start"
: > "$CAPTURE_MARKER"
find "$RUN_DIR" -maxdepth 1 \( -name 'output.json' -o -name 'output_*.json' \) -delete
ettrace --simulator --verbose --dsyms "$DSYMS"

Start from a stable screen, start ETTrace, perform exactly one focused flow, wait until visible work is complete, then stop the runner. For wider attribution, add --multi-thread; otherwise start with the main thread.

In Codex, run ettrace with a TTY and answer prompts with write_stdin. Without a TTY, the runner can exit without a useful trace.

Preserve Outputs

The next ETTrace run can overwrite processed flamegraph files, so preserve fresh output_<thread-id>.json files immediately. Do not analyze a saved output.json; ETTrace also serves a viewer route with that name, and raw emerge-output/output.json files are not the processed flamegraph artifacts this workflow expects.

PRESERVED_DIR="$(mktemp -d "$RUN_DIR/run-$(date +%Y%m%d-%H%M%S).XXXXXX")"
: > "$PRESERVED_DIR/summary.txt"
if [ ! -e "$CAPTURE_MARKER" ]; then
  echo "error: capture marker missing; start a fresh ETTrace capture before preserving outputs" >&2
  exit 1
fi
find "$RUN_DIR" -maxdepth 1 -name 'output_*.json' -newer "$CAPTURE_MARKER" -print | while IFS= read -r json; do
  preserved="$PRESERVED_DIR/${json##*/}"
  cp "$json" "$preserved"
  {
    echo "## ${preserved##*/}"
    python3 "$SKILL_DIR/scripts/analyze_flamegraph_json.py" "$preserved"
  } >> "$PRESERVED_DIR/summary.txt"
done
if [ ! -s "$PRESERVED_DIR/summary.txt" ]; then
  echo "error: no fresh processed ETTrace output JSON found in $RUN_DIR" >&2
  exit 1
fi

Analyze only processed output_*.json files in RUN_DIR. Ignore output.json and raw emerge-output/output.json files unless debugging ETTrace itself. If the analyzer rejects the JSON shape, capture again with the Homebrew ETTrace runner and matching app-side ETTrace.xcframework tag instead of trying to interpret the rejected file.

Read The Profile

Start from run-*/summary.txt, then inspect processed JSON directly if needed.

Report:

• exact flow, app build, simulator model/runtime, and run count
• processed flamegraph JSON paths
• top active leaves and inclusive first-party stacks with sample weights or percentages
• whether symbols were complete for app-owned binaries
• caveats such as first-run setup, simulator-only cost, network variance, or low sample count
• before/after deltas only when the same flow was captured with comparable setup

Cleanup

Remove temporary ETTrace app wiring when profiling is complete unless the user asked to keep it. Keep or discard run artifacts based on the active task.

iOS Memgraph Leaks

Use this skill to prove iOS leaks from a live simulator process or an existing .memgraph. Pair it with ../ios-debugger-agent/SKILL.md when the task also needs simulator build, install, launch, UI driving, logs, or screenshots.

Core Workflow

1. Build, launch, and drive the exact flow that should release objects.
2. Capture a memgraph from the running simulator process with scripts/capture_sim_memgraph.sh.
3. Summarize leaks with scripts/summarize_memgraph_leaks.py.
4. For each app-owned leaked type, inspect ownership with leaks --traceTree=<address> <file.memgraph> and grouped leak evidence.
5. Make the smallest root-cause patch, then recapture the same flow on the same simulator when possible.
6. Report proof: before/after leak counts, disappeared root types, remaining leaks, memgraph paths, and test/build results.

Do not claim a leak fix from a smaller memgraph alone. A credible fix explains the ownership path that kept the object alive and shows that the same path or type disappears after the patch.

Capture

Prefer capturing from the simulator already used for the reproduction. Resolve the simulator UDID and app bundle identifier, then capture the running app:

SKILL_DIR="<absolute path to this loaded skill folder>"
SIM="<simulator-udid>"
BUNDLE_ID="<app.bundle.identifier>"
MEMGRAPH_DIR="$(mktemp -d "${TMPDIR:-/tmp}/codex-ios-memgraph.XXXXXX")"

"$SKILL_DIR/scripts/capture_sim_memgraph.sh" \
  --udid "$SIM" \
  --bundle-id "$BUNDLE_ID" \
  --out-dir "$MEMGRAPH_DIR"

Do not derive SKILL_DIR from the target app repo's pwd; installed plugins usually live outside the app being debugged. Store captures in a run-specific temp or user-chosen folder, not under SKILL_DIR.

If the process cannot be found, confirm the bundle identifier and use xcrun simctl spawn "$SIM" launchctl list to inspect running labels.

Summarize

Summarize an existing memgraph:

"$SKILL_DIR/scripts/summarize_memgraph_leaks.py" \
  /path/to/app.memgraph \
  --trace-limit 5 \
  --out /path/to/leak-summary.md

Use --trace-limit sparingly. Trace trees are useful root-cause evidence, but large memgraphs can produce noisy output. If a trace tree says Found 0 roots referencing, treat it as an unreachable/self-retained leak candidate and use the summary's grouped leak tree or leaks --groupByType <file.memgraph> to identify the retained fields and payload chain.

Root Cause Rules

• Identify the first app-owned leaked type in the leak output or trace.
• Determine the intended lifetime: process, session, account, view, request, or task.
• Treat lazy or deferred allocation as a scope reduction, not a leak fix, unless the original eager allocation itself violated the intended lifetime.
• Prove retain-cycle claims with either a traceTree ownership path or an isolated reproduction.
• For unreachable/self-cycle leaks, traceTree may have no root path; use leaks --groupByType plus source verification to find the self-retaining edge.
• Do not claim success just because total leak count went down; prove the specific type or path disappeared.
• Separate real root-cause branches from candidate/noise branches.
• Prefer deleting the retaining edge over adding broad cleanup code.

Report

A useful leak report includes:

• the exact flow and simulator/app build
• the memgraph and summary paths
• app-owned leaked types and counts
• at least one ownership path, or grouped leak tree evidence when the object is unreachable from roots
• the smallest proposed or applied retaining-edge fix
• before/after evidence when a fix was made

If the memgraph shows only framework/runtime noise, say that and recommend the next narrower capture rather than inventing an app leak.

iOS Simulator Browser

Browser Workflow

1. Obtain an explicit Simulator UDID from the existing iOS build/run workflow or from xcrun simctl list devices available.

2. Start serve-sim in a long-running terminal pinned to that simulator. Clean up any tracked stale helper for this simulator before starting, and install a trap so the helper is cleaned up when this terminal exits:

   SIM="<simulator-udid>"
   cleanup_serve_sim() {
     npx --yes serve-sim@latest --kill "$SIM" >/dev/null 2>&1 || true
   }
   trap cleanup_serve_sim EXIT INT TERM HUP
   cleanup_serve_sim
   npx --yes serve-sim@latest "$SIM"
   

3. Open the exact local preview URL printed by serve-sim in the Codex in-app browser.

4. Verify that a real frame is rendering before reporting success. A loaded page alone is not proof that the simulator stream is healthy.

• Keep the terminal alive while the browser mirror is in use. When finished, stop the terminal and wait for it to exit so the trap runs.
• If the terminal disappeared or did not exit cleanly, run npx --yes serve-sim@latest --kill "$SIM" before starting another mirror for that simulator.
• Never run an unscoped serve-sim --kill; another thread may own a different simulator mirror.

SwiftUI Preview Workflow

Use the bundled launcher when the requested previews live in an importable Swift package. Point it at the package manifest and select the target whose previews should be displayed. It generates a disposable host project outside the user's source tree, installs and launches that host in Simulator, and watches the package for edits.

node <skill-root>/scripts/swiftui-preview-browser.mjs \
  /absolute/path/to/Package.swift \
  --package-target "<target>" \
  --device "<simulator-udid>"

• Watch mode is enabled by default. On a Swift package source edit, the launcher rebuilds a generated dylib and hot-swaps it into the running host without relaunching the app.
• The generated host shows every preview variant discovered in the selected Swift Package target with in-simulator page controls. To show a subset instead, pass --preview-filter <regex[, ...]>; it matches display names and code identifiers such as StatusRowView_Previews.
• Once the launcher prints the selected Simulator UDID, start serve-sim for that same UDID and open its printed URL in the in-app browser.

Support Boundary

• Support Swift Package-backed PreviewProvider and #Preview declarations through the generated host.
• Do not edit the user's .xcodeproj, .xcworkspace, Package.swift, schemes, or build settings to force preview support.

Proof

For browser or preview QA, capture a browser screenshot showing the simulator frame. For hot reload QA, also report the launcher's hot reloaded package preview ... in pid ... output and show the changed frame after editing.

SwiftUI Liquid Glass

Overview

Use this skill to build or review SwiftUI features that fully align with the iOS 26+ Liquid Glass API. Prioritize native APIs (glassEffect, GlassEffectContainer, glass button styles) and Apple design guidance. Keep usage consistent, interactive where needed, and performance aware.

Workflow Decision Tree

Choose the path that matches the request:

1) Review an existing feature

• Inspect where Liquid Glass should be used and where it should not.
• Verify correct modifier order, shape usage, and container placement.
• Check for iOS 26+ availability handling and sensible fallbacks.

2) Improve a feature using Liquid Glass

• Identify target components for glass treatment (surfaces, chips, buttons, cards).
• Refactor to use GlassEffectContainer where multiple glass elements appear.
• Introduce interactive glass only for tappable or focusable elements.

3) Implement a new feature using Liquid Glass

• Design the glass surfaces and interactions first (shape, prominence, grouping).
• Add glass modifiers after layout/appearance modifiers.
• Add morphing transitions only when the view hierarchy changes with animation.

Core Guidelines

• Prefer native Liquid Glass APIs over custom blurs.
• Use GlassEffectContainer when multiple glass elements coexist.
• Apply .glassEffect(...) after layout and visual modifiers.
• Use .interactive() for elements that respond to touch/pointer.
• Keep shapes consistent across related elements for a cohesive look.
• Gate with #available(iOS 26, *) and provide a non-glass fallback.

Review Checklist

• Availability: #available(iOS 26, *) present with fallback UI.
• Composition: Multiple glass views wrapped in GlassEffectContainer.
• Modifier order: glassEffect applied after layout/appearance modifiers.
• Interactivity: interactive() only where user interaction exists.
• Transitions: glassEffectID used with @Namespace for morphing.
• Consistency: Shapes, tinting, and spacing align across the feature.

Implementation Checklist

• Define target elements and desired glass prominence.
• Wrap grouped glass elements in GlassEffectContainer and tune spacing.
• Use .glassEffect(.regular.tint(...).interactive(), in: .rect(cornerRadius: ...)) as needed.
• Use .buttonStyle(.glass) / .buttonStyle(.glassProminent) for actions.
• Add morphing transitions with glassEffectID when hierarchy changes.
• Provide fallback materials and visuals for earlier iOS versions.

Quick Snippets

Use these patterns directly and tailor shapes/tints/spacing.

if #available(iOS 26, *) {
    Text("Hello")
        .padding()
        .glassEffect(.regular.interactive(), in: .rect(cornerRadius: 16))
} else {
    Text("Hello")
        .padding()
        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
}

GlassEffectContainer(spacing: 24) {
    HStack(spacing: 24) {
        Image(systemName: "scribble.variable")
            .frame(width: 72, height: 72)
            .font(.system(size: 32))
            .glassEffect()
        Image(systemName: "eraser.fill")
            .frame(width: 72, height: 72)
            .font(.system(size: 32))
            .glassEffect()
    }
}

Button("Confirm") { }
    .buttonStyle(.glassProminent)

Resources

• Reference guide: references/liquid-glass.md
• Prefer Apple docs for up-to-date API details, and use web search to consult current Apple Developer documentation in addition to the references above.

SwiftUI Performance Audit

Quick start

Use this skill to diagnose SwiftUI performance issues from code first, then request profiling evidence when code review alone cannot explain the symptoms.

Workflow

1. Classify the symptom: slow rendering, janky scrolling, high CPU, memory growth, hangs, or excessive view updates.
2. If code is available, start with a code-first review using references/code-smells.md.
3. If code is not available, ask for the smallest useful slice: target view, data flow, reproduction steps, and deployment target.
4. If code review is inconclusive or runtime evidence is required, guide the user through profiling with references/profiling-intake.md.
5. Summarize likely causes, evidence, remediation, and validation steps using references/report-template.md.

1. Intake

Collect:

• Target view or feature code.
• Symptoms and exact reproduction steps.
• Data flow: @State, @Binding, environment dependencies, and observable models.
• Whether the issue shows up on device or simulator, and whether it was observed in Debug or Release.

Ask the user to classify the issue if possible:

• CPU spike or battery drain
• Janky scrolling or dropped frames
• High memory or image pressure
• Hangs or unresponsive interactions
• Excessive or unexpectedly broad view updates

For the full profiling intake checklist, read references/profiling-intake.md.

2. Code-First Review

Focus on:

• Invalidation storms from broad observation or environment reads.
• Unstable identity in lists and ForEach.
• Heavy derived work in body or view builders.
• Layout thrash from complex hierarchies, GeometryReader, or preference chains.
• Large image decode or resize work on the main thread.
• Animation or transition work applied too broadly.

Use references/code-smells.md for the detailed smell catalog and fix guidance.

Provide:

• Likely root causes with code references.
• Suggested fixes and refactors.
• If needed, a minimal repro or instrumentation suggestion.

3. Guide the User to Profile

If code review does not explain the issue, ask for runtime evidence:

• A trace export or screenshots of the SwiftUI timeline and Time Profiler call tree.
• Device/OS/build configuration.
• The exact interaction being profiled.
• Before/after metrics if the user is comparing a change.

Use references/profiling-intake.md for the exact checklist and collection steps.

4. Analyze and Diagnose

• Map the evidence to the most likely category: invalidation, identity churn, layout thrash, main-thread work, image cost, or animation cost.
• Prioritize problems by impact, not by how easy they are to explain.
• Distinguish code-level suspicion from trace-backed evidence.
• Call out when profiling is still insufficient and what additional evidence would reduce uncertainty.

5. Remediate

Apply targeted fixes:

• Narrow state scope and reduce broad observation fan-out.
• Stabilize identities for ForEach and lists.
• Move heavy work out of body into derived state updated from inputs, model-layer precomputation, memoized helpers, or background preprocessing. Use @State only for view-owned state, not as an ad hoc cache for arbitrary computation.
• Use equatable() only when equality is cheaper than recomputing the subtree and the inputs are truly value-semantic.
• Downsample images before rendering.
• Reduce layout complexity or use fixed sizing where possible.

Use references/code-smells.md for examples, Observation-specific fan-out guidance, and remediation patterns.

6. Verify

Ask the user to re-run the same capture and compare with baseline metrics. Summarize the delta (CPU, frame drops, memory peak) if provided.

Outputs

Provide:

• A short metrics table (before/after if available).
• Top issues (ordered by impact).
• Proposed fixes with estimated effort.

Use references/report-template.md when formatting the final audit.

References

• Profiling intake and collection checklist: references/profiling-intake.md
• Common code smells and remediation patterns: references/code-smells.md
• Audit output template: references/report-template.md
• Add Apple documentation and WWDC resources under references/ as they are supplied by the user.
• Optimizing SwiftUI performance with Instruments: references/optimizing-swiftui-performance-instruments.md
• Understanding and improving SwiftUI performance: references/understanding-improving-swiftui-performance.md
• Understanding hangs in your app: references/understanding-hangs-in-your-app.md
• Demystify SwiftUI performance (WWDC23): references/demystify-swiftui-performance-wwdc23.md
• In addition to the references above, use web search to consult current Apple Developer documentation when Instruments workflows or SwiftUI performance guidance may have changed.

SwiftUI UI Patterns

Quick start

Choose a track based on your goal:

Existing project

• Identify the feature or screen and the primary interaction model (list, detail, editor, settings, tabbed).
• Find a nearby example in the repo with rg "TabView\(" or similar, then read the closest SwiftUI view.
• Apply local conventions: prefer SwiftUI-native state, keep state local when possible, and use environment injection for shared dependencies.
• Choose the relevant component reference from references/components-index.md and follow its guidance.
• If the interaction reveals secondary content by dragging or scrolling the primary content away, read references/scroll-reveal.md before implementing gestures manually.
• Build the view with small, focused subviews and SwiftUI-native data flow.

New project scaffolding

• Start with references/app-wiring.md to wire TabView + NavigationStack + sheets.
• Add a minimal AppTab and RouterPath based on the provided skeletons.
• Choose the next component reference based on the UI you need first (TabView, NavigationStack, Sheets).
• Expand the route and sheet enums as new screens are added.

General rules to follow

• Use modern SwiftUI state (@State, @Binding, @Observable, @Environment) and avoid unnecessary view models.
• If the deployment target includes iOS 16 or earlier and cannot use the Observation API introduced in iOS 17, fall back to ObservableObject with @StateObject for root ownership, @ObservedObject for injected observation, and @EnvironmentObject only for truly shared app-level state.
• Prefer composition; keep views small and focused.
• Use async/await with .task and explicit loading/error states. For restart, cancellation, and debouncing guidance, read references/async-state.md.
• Keep shared app services in @Environment, but prefer explicit initializer injection for feature-local dependencies and models. For root wiring patterns, read references/app-wiring.md.
• Prefer the newest SwiftUI API that fits the deployment target and call out the minimum OS whenever a pattern depends on it.
• Maintain existing legacy patterns only when editing legacy files.
• Follow the project's formatter and style guide.
• Sheets: Prefer .sheet(item:) over .sheet(isPresented:) when state represents a selected model. Avoid if let inside a sheet body. Sheets should own their actions and call dismiss() internally instead of forwarding onCancel/onConfirm closures.
• Scroll-driven reveals: Prefer deriving a normalized progress value from scroll offset and driving the visual state from that single source of truth. Avoid parallel gesture state machines unless scroll alone cannot express the interaction.

State ownership summary

Use the narrowest state tool that matches the ownership model:

Choose the ownership location first, then pick the wrapper. Do not introduce a reference model when plain value state is enough.

Cross-cutting references

• In addition to the references below, use web search to consult current Apple Developer documentation when SwiftUI APIs, availability, or platform guidance may have changed.
• references/navigationstack.md: navigation ownership, per-tab history, and enum routing.
• references/sheets.md: centralized modal presentation and enum-driven sheets.
• references/deeplinks.md: URL handling and routing external links into app destinations.
• references/app-wiring.md: root dependency graph, environment usage, and app shell wiring.
• references/async-state.md: .task, .task(id:), cancellation, debouncing, and async UI state.
• references/previews.md: #Preview, fixtures, mock environments, and isolated preview setup.
• references/performance.md: stable identity, observation scope, lazy containers, and render-cost guardrails.

Anti-patterns

• Giant views that mix layout, business logic, networking, routing, and formatting in one file.
• Multiple boolean flags for mutually exclusive sheets, alerts, or navigation destinations.
• Live service calls directly inside body-driven code paths instead of view lifecycle hooks or injected models/services.
• Reaching for AnyView to work around type mismatches that should be solved with better composition.
• Defaulting every shared dependency to @EnvironmentObject or a global router without a clear ownership reason.

Workflow for a new SwiftUI view

1. Define the view's state, ownership location, and minimum OS assumptions before writing UI code.
2. Identify which dependencies belong in @Environment and which should stay as explicit initializer inputs.
3. Sketch the view hierarchy, routing model, and presentation points; extract repeated parts into subviews. For complex navigation, read references/navigationstack.md, references/sheets.md, or references/deeplinks.md. Build and verify no compiler errors before proceeding.
4. Implement async loading with .task or .task(id:), plus explicit loading and error states when needed. Read references/async-state.md when the work depends on changing inputs or cancellation.
5. Add previews for the primary and secondary states, then add accessibility labels or identifiers when the UI is interactive. Read references/previews.md when the view needs fixtures or injected mock dependencies.
6. Validate with a build: confirm no compiler errors, check that previews render without crashing, ensure state changes propagate correctly, and sanity-check that list identity and observation scope will not cause avoidable re-renders. Read references/performance.md if the screen is large, scroll-heavy, or frequently updated. For common SwiftUI compilation errors — missing @State annotations, ambiguous ViewBuilder closures, or mismatched generic types — resolve them before updating callsites. If the build fails: read the error message carefully, fix the identified issue, then rebuild before proceeding to the next step. If a preview crashes, isolate the offending subview, confirm its state initialisation is valid, and re-run the preview before continuing.

Component references

Use references/components-index.md as the entry point. Each component reference should include:

• Intent and best-fit scenarios.
• Minimal usage pattern with local conventions.
• Pitfalls and performance notes.
• Paths to existing examples in the current repo.

Adding a new component reference

• Create references/<component>.md.
• Keep it short and actionable; link to concrete files in the current repo.
• Update references/components-index.md with the new entry.

SwiftUI View Refactor

Overview

Refactor SwiftUI views toward small, explicit, stable view types. Default to vanilla SwiftUI: local state in the view, shared dependencies in the environment, business logic in services/models, and view models only when the request or existing code clearly requires one.

Core Guidelines

1) View ordering (top → bottom)

• Enforce this ordering unless the existing file has a stronger local convention you must preserve.
• Environment
• private/public let
• @State / other stored properties
• computed var (non-view)
• init
• body
• computed view builders / other view helpers
• helper / async functions

2) Default to MV, not MVVM

• Views should be lightweight state expressions and orchestration points, not containers for business logic.
• Favor @State, @Environment, @Query, .task, .task(id:), and onChange before reaching for a view model.
• Inject services and shared models via @Environment; keep domain logic in services/models, not in the view body.
• Do not introduce a view model just to mirror local view state or wrap environment dependencies.
• If a screen is getting large, split the UI into subviews before inventing a new view model layer.

3) Strongly prefer dedicated subview types over computed some View helpers

• Flag body properties that are longer than roughly one screen or contain multiple logical sections.
• Prefer extracting dedicated View types for non-trivial sections, especially when they have state, async work, branching, or deserve their own preview.
• Keep computed some View helpers rare and small. Do not build an entire screen out of private var header: some View-style fragments.
• Pass small, explicit inputs (data, bindings, callbacks) into extracted subviews instead of handing down the entire parent state.
• If an extracted subview becomes reusable or independently meaningful, move it to its own file.

Prefer:

var body: some View {
    List {
        HeaderSection(title: title, subtitle: subtitle)
        FilterSection(
            filterOptions: filterOptions,
            selectedFilter: $selectedFilter
        )
        ResultsSection(items: filteredItems)
        FooterSection()
    }
}

private struct HeaderSection: View {
    let title: String
    let subtitle: String

    var body: some View {
        VStack(alignment: .leading, spacing: 6) {
            Text(title).font(.title2)
            Text(subtitle).font(.subheadline)
        }
    }
}

private struct FilterSection: View {
    let filterOptions: [FilterOption]
    @Binding var selectedFilter: FilterOption

    var body: some View {
        ScrollView(.horizontal, showsIndicators: false) {
            HStack {
                ForEach(filterOptions, id: \.self) { option in
                    FilterChip(option: option, isSelected: option == selectedFilter)
                        .onTapGesture { selectedFilter = option }
                }
            }
        }
    }
}

Avoid:

var body: some View {
    List {
        header
        filters
        results
        footer
    }
}

private var header: some View {
    VStack(alignment: .leading, spacing: 6) {
        Text(title).font(.title2)
        Text(subtitle).font(.subheadline)
    }
}

3b) Extract actions and side effects out of body

• Do not keep non-trivial button actions inline in the view body.
• Do not bury business logic inside .task, .onAppear, .onChange, or .refreshable.
• Prefer calling small private methods from the view, and move real business logic into services/models.
• The body should read like UI, not like a view controller.

Button("Save", action: save)
    .disabled(isSaving)

.task(id: searchText) {
    await reload(for: searchText)
}

private func save() {
    Task { await saveAsync() }
}

private func reload(for searchText: String) async {
    guard !searchText.isEmpty else {
        results = []
        return
    }
    await searchService.search(searchText)
}

4) Keep a stable view tree (avoid top-level conditional view swapping)

• Avoid body or computed views that return completely different root branches via if/else.
• Prefer a single stable base view with conditions inside sections/modifiers (overlay, opacity, disabled, toolbar, etc.).
• Root-level branch swapping causes identity churn, broader invalidation, and extra recomputation.

Prefer:

var body: some View {
    List {
        documentsListContent
    }
    .toolbar {
        if canEdit {
            editToolbar
        }
    }
}

Avoid:

var documentsListView: some View {
    if canEdit {
        editableDocumentsList
    } else {
        readOnlyDocumentsList
    }
}

5) View model handling (only if already present or explicitly requested)

• Treat view models as a legacy or explicit-need pattern, not the default.
• Do not introduce a view model unless the request or existing code clearly calls for one.
• If a view model exists, make it non-optional when possible.
• Pass dependencies to the view via init, then create the view model in the view's init.
• Avoid bootstrapIfNeeded patterns and other delayed setup workarounds.

Example (Observation-based):

@State private var viewModel: SomeViewModel

init(dependency: Dependency) {
    _viewModel = State(initialValue: SomeViewModel(dependency: dependency))
}

6) Observation usage

• For @Observable reference types on iOS 17+, store them as @State in the owning view.
• Pass observables down explicitly; avoid optional state unless the UI genuinely needs it.
• If the deployment target includes iOS 16 or earlier, use @StateObject at the owner and @ObservedObject when injecting legacy observable models.

Workflow

1. Reorder the view to match the ordering rules.
2. Remove inline actions and side effects from body; move business logic into services/models and keep only thin orchestration in the view.
3. Shorten long bodies by extracting dedicated subview types; avoid rebuilding the screen out of many computed some View helpers.
4. Ensure stable view structure: avoid top-level if-based branch swapping; move conditions to localized sections/modifiers.
5. If a view model exists or is explicitly required, replace optional view models with a non-optional @State view model initialized in init.
6. Confirm Observation usage: @State for root @Observable models on iOS 17+, legacy wrappers only when the deployment target requires them.
7. Keep behavior intact: do not change layout or business logic unless requested.

Notes

• Prefer small, explicit view types over large conditional blocks and large computed some View properties.
• Keep computed view builders below body and non-view computed vars above init.
• A good SwiftUI refactor should make the view read top-to-bottom as data flow plus layout, not as mixed layout and imperative logic.
• For MV-first guidance and rationale, see references/mv-patterns.md.
• In addition to the references above, use web search to consult current Apple Developer documentation when SwiftUI APIs, Observation behavior, or platform guidance may have changed.

Large-view handling

When a SwiftUI view file exceeds ~300 lines, split it aggressively. Extract meaningful sections into dedicated View types instead of hiding complexity in many computed properties. Use private extensions with // MARK: - comments for actions and helpers, but do not treat extensions as a substitute for breaking a giant screen into smaller view types. If an extracted subview is reused or independently meaningful, move it into its own file.

AppKit Interop

Quick Start

Use this skill when SwiftUI is close but not quite enough for native macOS behavior. Keep the bridge as small and explicit as possible. SwiftUI should usually remain the source of truth, while AppKit handles the imperative edge.

Choose The Smallest Bridge

• Use pure SwiftUI when the required behavior already exists in scenes, toolbars, commands, inspectors, or standard controls.
• Use NSViewRepresentable when you need a specific AppKit view with lightweight lifecycle needs.
• Use NSViewControllerRepresentable when you need controller lifecycle, delegation, or presentation coordination.
• Use direct AppKit window or app hooks when you need NSWindow, responder-chain, menu validation, panels, or app-level behavior.

Workflow

1. Name the capability gap precisely.

   • Window behavior
   • Text system behavior
   • Menu validation
   • Drag and drop
   • File open/save panels
   • First responder control

2. Pick the smallest boundary that solves it.

   • Avoid porting a whole screen to AppKit when one wrapped control or coordinator would do.

3. Keep ownership explicit.

   • SwiftUI owns value state, selection, and observable models.
   • AppKit objects stay inside the representable, coordinator, or bridge object.

4. Expose a narrow interface back to SwiftUI.

   • Bindings for editable state
   • Small callbacks for events
   • Focused bridge services only when necessary

5. Validate lifecycle assumptions.

   • SwiftUI may recreate representables.
   • Coordinators exist to hold delegate and target-action glue, not as a second app architecture.

References

• references/representables.md: choosing between view and view-controller wrappers, plus coordinator patterns.
• references/window-panels.md: window access, utility windows, and open/save panels.
• references/responder-menus.md: first responder, command routing, and menu validation.
• references/drag-drop-pasteboard.md: pasteboard, file URLs, and desktop drag/drop edges.

Guardrails

• Do not duplicate the source of truth between SwiftUI and AppKit.
• Do not let Coordinator become an unstructured dumping ground.
• Do not store long-lived NSView or NSWindow instances globally without a strong ownership reason.
• Prefer a tiny tested bridge over rewriting the feature in raw AppKit.
• If a pattern can remain entirely in swiftui-patterns, keep it there.

Output Expectations

Provide:

• the exact SwiftUI limitation being crossed
• the smallest recommended bridge type
• the data-flow boundary between SwiftUI and AppKit
• the lifecycle or validation risks to watch

Build / Run / Debug

Quick Start

Use this skill to set up one project-local script/build_and_run.sh entrypoint, wire .codex/environments/environment.toml so the Codex app shows a Run button, then use that script as the default build/run path.

Prefer shell-first workflows:

• ./script/build_and_run.sh as the single kill + build + run entrypoint once it exists
• xcodebuild for Xcode workspaces or projects
• swift build plus raw executable launch inside that script for true SwiftPM command-line tools
• swift build plus project-local .app bundle staging and /usr/bin/open -n launch for SwiftPM AppKit/SwiftUI GUI apps
• optional script flags for lldb, log stream, telemetry verification, or post-launch process checks

Do not assume simulators, touch interaction, or mobile-specific tooling.

If an Xcode-aware MCP surface is already available and the user explicitly wants it, use it only where it fits. Keep that usage narrow and honest: prefer it for Xcode-oriented discovery, logging, or debugging support, and do not force simulator-specific workflows onto pure macOS tasks.

Workflow

1. Discover the project shape.

   • Check whether the workspace is already inside a git repo with git rev-parse --is-inside-work-tree.
   • If no git repo is present, run git init at the project/workspace root before building so Codex app git-backed features are available. Never run git init inside a nested subdirectory when the current workspace already belongs to a parent repo.
   • Look for .xcworkspace, .xcodeproj, and Package.swift.
   • If more than one candidate exists, explain the default choice and the ambiguity.

2. Resolve the runnable target and process name.

   • For Xcode, list schemes and prefer the app-producing scheme unless the user names another one.
   • For SwiftPM, identify executable products when possible.
   • Split SwiftPM launch handling by product type:
     • use raw executable launch only for true command-line tools,
     • use a generated project-local .app bundle for AppKit/SwiftUI GUI apps.
   • Determine the app/process name to kill before relaunching.

3. Create or update script/build_and_run.sh.

   • Make the script project-specific and executable.
   • It should always:
     1. stop the existing running app/process if present,
     2. build the macOS target,
     3. launch the freshly built app or executable.
   • Add optional flags for debugging/log inspection:
     • --debug to launch under lldb or attach the debugger
     • --logs to stream process logs after launch
     • --telemetry to stream unified logs filtered to the app subsystem/category
     • --verify to launch the app and confirm the process exists with pgrep -x <AppName>
   • Keep the default no-flag path simple: kill, build, run.
   • Prefer writing one script that owns this workflow instead of repeatedly asking the agent to manually run swift build, locate the artifact, then invoke an ad hoc run command.
   • For SwiftPM GUI apps, make the script build the product, create dist/<AppName>.app, copy the binary to Contents/MacOS/<AppName>, generate a minimal Contents/Info.plist with CFBundlePackageType=APPL, CFBundleExecutable, CFBundleIdentifier, CFBundleName, LSMinimumSystemVersion, and NSPrincipalClass=NSApplication, then launch with /usr/bin/open -n <bundle>.
   • For SwiftPM GUI --logs and --telemetry, launch the bundle with /usr/bin/open -n first, then stream unified logs with /usr/bin/log stream --info ....
   • Do not recommend direct SwiftPM executable launch for AppKit/SwiftUI GUI apps.
   • Use references/run-button-bootstrap.md as the canonical source for the script shape and exact environment file format. Do not fork a second authoritative snippet in another skill or command.
   • Keep the run script outside app source. It belongs in script/build_and_run.sh, not in App/, Views/, Models/, Stores/, Services/, or Support/.

4. Write .codex/environments/environment.toml at the project root once the script exists.

   • Use this exact placement: .codex/environments/environment.toml.
   • Use the exact action shape in references/run-button-bootstrap.md.
   • This file is what gives the user a Codex app Run button wired to the script.
   • If the project already has this file, update the Run action command to point at ./script/build_and_run.sh instead of creating a duplicate action.
   • Keep this Codex environment config separate from Swift app source files.

5. Build and run through the script.

   • Default to ./script/build_and_run.sh.
   • Use ./script/build_and_run.sh --debug, --logs, --telemetry, or --verify when the user asks for debugger/log/telemetry/process verification support.

6. Summarize failures correctly.

   • Classify the blocker as compiler, linker, signing, build settings, missing SDK/toolchain, script bug, or runtime launch.
   • Quote the smallest useful error snippet and explain what it means.

7. Debug the right way.

   • Use the script's --logs or --telemetry mode for config, entitlement, sandbox, and action-event verification.
   • For SwiftPM GUI apps, if the app bundle launches but its window still does not come forward, check whether the entrypoint needs NSApp.setActivationPolicy(.regular) and NSApp.activate(ignoringOtherApps: true).
   • Use the script's --debug mode or direct lldb if symbolized crash debugging is needed.
   • If the user needs to instrument and verify specific window, sidebar, menu, or menu bar actions, switch to telemetry.
   • Keep evidence tight and user-facing.

8. Use Xcode-aware MCP tooling only when it helps.

   • If the user explicitly asks for XcodeBuildMCP and it is already available, prefer it over ad hoc setup.
   • Use the MCP for Xcode-aware discovery or debug/logging workflows when the available tool surface clearly matches the task.
   • Fall back to shell commands immediately when the MCP does not provide a clean macOS path.

Preferred Commands

• Project discovery:
  • find . -name '*.xcworkspace' -o -name '*.xcodeproj' -o -name 'Package.swift'
• Scheme discovery:
  • xcodebuild -list -workspace <workspace>
  • xcodebuild -list -project <project>
• Build/run:
  • ./script/build_and_run.sh
  • ./script/build_and_run.sh --debug
  • ./script/build_and_run.sh --logs
  • ./script/build_and_run.sh --telemetry
  • ./script/build_and_run.sh --verify

References

• references/run-button-bootstrap.md: canonical build_and_run.sh and .codex/environments/environment.toml contract.

Guardrails

• Prefer the narrowest command that proves or disproves the current theory.
• Do not leave the user with a one-off manual command chain once a stable build_and_run.sh script can own the workflow.
• Do not write .codex/environments/environment.toml before the run script exists, and do not point the Run action at a stale script path.
• Do not launch a SwiftUI/AppKit SwiftPM GUI app as a raw executable unless the user explicitly wants to diagnose that failure mode: it can produce no Dock icon, no foreground activation, and missing bundle identifier warnings. Keep raw executable launch only for true command-line tools.
• Do not claim UI state you cannot inspect directly.
• Do not describe mobile or simulator workflows as if they apply to macOS.
• If build output is huge, summarize the first real blocker and point to follow-up commands.

Output Expectations

Provide:

• the detected project type
• the script path and Codex environment action you configured, if applicable
• the command you ran
• whether build and launch succeeded
• the top blocker if they failed
• the smallest sensible next action

Liquid Glass

Overview

Use this skill to bring a macOS SwiftUI app into the modern macOS design system with the least custom chrome possible. Start with standard app structure, toolbars, search placement, sheets, and controls, then add custom Liquid Glass only where the app needs a distinctive surface.

Prefer system-provided glass and adaptive materials over bespoke blur, opaque backgrounds, or custom toolbar/sidebar skins. Audit existing UI for extra fills, scrims, and clipping before adding more effects.

Workflow

1. Read the relevant scene or root view and identify the structural pattern: NavigationSplitView, TabView, sheet presentation, detail/inspector layout, toolbar, or custom floating controls.
2. Remove custom backgrounds or darkening layers behind system sheets, sidebars, and toolbars unless the product explicitly needs them. These can obscure Liquid Glass and interfere with the automatic scroll-edge effect.
3. Update standard SwiftUI structure and controls first.
4. Add custom glassEffect surfaces only for app-specific UI that standard controls do not cover.
5. Validate that glass grouping, transitions, icon treatment, and foreground activation are visually coherent and still usable with pointer and keyboard.
6. If the UI change also affects launch behavior for a SwiftPM GUI app, use build-run-debug so the app runs as a foreground .app bundle rather than as a raw executable.

App Structure

• Prefer NavigationSplitView for hierarchy-driven macOS layouts. Let the sidebar use the system Liquid Glass material instead of painting over it.
• For hero artwork or large media adjacent to a floating sidebar, use backgroundExtensionEffect so the visual can extend beyond the safe area without clipping the subject.
• Keep inspectors visually associated with the current selection and avoid giving them a heavier custom background than the content they inspect.
• If the app uses tabs, keep TabView for persistent top-level sections and preserve each tab's local navigation state.
• Do not force iPhone-only tab bar minimize/accessory behavior onto a Mac app. On macOS, prefer a conventional top toolbar and native tab/search placement.
• If a sheet already uses presentationBackground purely to imitate frosted material, consider removing it and letting the system's new material render.
• For sheet transitions that should visually originate from a toolbar button, make the presenting item the source of a navigation zoom transition and mark the sheet content as the destination.

Toolbars

• Assume toolbar items are rendered on a floating Liquid Glass surface and are grouped automatically.
• Use ToolbarSpacer to communicate grouping:
  • fixed spacing to split related actions into a distinct group,
  • flexible spacing to push a leading action away from a trailing group.
• Use sharedBackgroundVisibility when an item should stand alone without the shared glass background, for example a profile/avatar item.
• Add badge to toolbar item content for notification or status indicators.
• Expect monochrome icon rendering in more toolbar contexts. Use tint only to convey semantic meaning such as a primary action or alert state, not as pure decoration.
• If content underneath a toolbar has extra darkening, blur, or custom background layers, remove them before judging the new automatic scroll-edge effect.
• For dense windows with many floating elements, tune the content's scroll-edge treatment with scrollEdgeEffectStyle instead of building a custom bar background.

Search

• For a search field that applies across a whole split-view hierarchy, attach searchable to the NavigationSplitView, not to just one column.
• When search is secondary and a compact affordance is better, use searchToolbarBehavior instead of hand-rolling a toolbar button and a separate field.
• For a dedicated search page in a multi-tab app, assign the search role to one tab and place searchable on the TabView.
• Make most of the app's content discoverable from search when the field lives in the top-trailing toolbar location.
• On iPad and Mac, expect the dedicated search tab to show a centered field above browsing suggestions rather than a bottom search bar.

Controls

• Prefer standard SwiftUI controls before creating custom glass components.
• Expect bordered buttons to default to a capsule shape at larger sizes. On macOS, mini/small/medium controls preserve a rounded-rectangle shape for denser layouts.
• Use buttonBorderShape when a button shape needs to be explicit.
• Use controlSize to preserve density in inspectors and popovers, and reserve extra-large sizing for truly prominent actions.
• Use the system glass and glass-prominent button styles for primary actions instead of recreating a translucent button background by hand.
• For sliders with discrete values, pass step to get automatic tick marks or provide specific ticks in a ticks closure.
• For sliders that should expand left and right around a baseline, set neutralValue.
• Use Label or standard control initializers for menu items so icons are consistently placed on the leading edge across platforms.
• For custom shapes that must align concentrically with a sheet, card, or window corner, use a concentric rectangle shape with the containerConcentric corner configuration instead of guessing a radius.

Custom Liquid Glass

• Use glassEffect for custom glass surfaces. The default shape is capsule-like and text foregrounds are automatically made vibrant and legible against changing content underneath.
• Pass an explicit shape to glassEffect when a capsule is not the right fit.
• Add tint only when color carries meaning, such as a status or call to action.
• Use glassEffect(... .interactive()) for custom controls or containers with interactive elements so they scale, bounce, and shimmer like system glass.
• Wrap nearby custom glass elements in one GlassEffectContainer. This is a visual correctness rule, not just organization: separate containers cannot sample each other's glass and can produce inconsistent refraction.
• Use glassEffectID with a local @Namespace when matching glass elements should morph between collapsed and expanded states.

Review Checklist

• Standard structures and controls were updated first before adding custom glass.
• Opaque backgrounds, dark scrims, and custom toolbar/sheet fills that fight the system material were removed unless intentionally required.
• searchable is attached at the correct container level for the intended search scope.
• Toolbar grouping uses ToolbarSpacer, sharedBackgroundVisibility, and badge instead of one-off hand-built chrome.
• Icon tint is semantic, not decorative.
• Custom glass elements that sit near each other share a GlassEffectContainer.
• Morphing glass transitions use glassEffectID with a namespace and stable identity.
• Any SwiftPM GUI app used to test the result is launched as a .app bundle, not as a raw executable.

Guardrails

• Do not rebuild system sidebars, toolbars, sheets, or controls from scratch if standard SwiftUI APIs already provide the modern macOS behavior.
• Do not apply custom opaque backgrounds behind a NavigationSplitView sidebar, system toolbar, or sheet just because an older version needed one.
• Do not scatter related glass elements across multiple GlassEffectContainers.
• Do not tint every icon or glass surface for visual variety alone.
• Do not assume an iPhone tab/search behavior is the right answer on macOS. Prefer desktop-native toolbar, split-view, and inspector placement.
• Do not leave a GUI SwiftPM app launching as a bare executable when reviewing Liquid Glass behavior; missing foreground activation can make a design bug look like a rendering bug.

When To Use Other Skills

• Use swiftui-patterns when the main question is scene architecture, sidebar/detail layout, commands, or settings rather than Liquid Glass-specific treatment.
• Use view-refactor when the main issue is file structure, state ownership, and extracting large views before design changes.
• Use appkit-interop when the design requires window, panel, responder-chain, or AppKit-only control behavior.
• Use build-run-debug when you need to launch, verify, or inspect logs for the app after the visual update.

Packaging & Notarization

Quick Start

Use this skill when the work is about shipping the app rather than merely running it locally: archives, exported app bundles, notarization readiness, hardened runtime, or distribution validation.

Workflow

1. Confirm the distribution goal.

   • Local archive validation
   • Signed distributable app
   • Notarization troubleshooting

2. Inspect the artifact.

   • Validate app bundle structure.
   • Check nested frameworks, helper tools, and entitlements.

3. Inspect signing and runtime prerequisites.

   • Hardened runtime
   • Signing identity
   • Nested code signatures
   • Required entitlements

4. Explain notarization readiness or failure.

   • Separate packaging issues from trust-policy symptoms.
   • Point to the minimum follow-up validation commands.

Guardrails

• Do not present notarization as required for ordinary local debug runs.
• Call out when you lack the actual exported artifact and are inferring from project settings.
• Keep advice concrete and verifiable.

Output Expectations

Provide:

• what artifact or settings were inspected
• whether the app looks distribution-ready
• the top missing prerequisite or failure mode
• the next validation or repair step

Signing & Entitlements

Quick Start

Use this skill when the failure smells like codesigning rather than compilation: launch refusal, missing entitlement, invalid signature, sandbox mismatch, hardened runtime confusion, or trust-policy rejection.

Workflow

1. Inspect the bundle or binary.

   • Locate the .app or executable.
   • Identify the main binary inside Contents/MacOS/.

2. Read signing details.

   • Use codesign -dvvv --entitlements :- <path>.
   • Use spctl -a -vv <path> when Gatekeeper behavior matters.
   • Use plutil -p for entitlements or Info.plist inspection.

3. Classify the failure.

   • Unsigned or ad hoc signed
   • Wrong identity
   • Entitlement mismatch
   • Hardened runtime issue
   • App Sandbox issue
   • Nested code signing issue
   • Distribution/notarization prerequisite issue

4. Explain the minimum fix path.

   • Say exactly what is wrong.
   • Show the shortest set of validation or repair commands.
   • Distinguish local development problems from distribution problems.

Useful Commands

• codesign -dvvv --entitlements :- <app-or-binary>
• spctl -a -vv <app-or-binary>
• security find-identity -p codesigning -v
• plutil -p <path-to-entitlements-or-plist>

Guardrails

• Never invent missing entitlements.
• Do not conflate notarization with local debug signing.
• If the real issue is a build setting or provisioning profile, say so directly.

Output Expectations

Provide:

• what artifact was inspected
• what signing state it is in
• the exact failure class
• the minimum fix or validation sequence

SwiftPM for macOS

Quick Start

Use this skill when Package.swift is the primary entrypoint or when SwiftPM is the fastest path to a reproducible result.

Workflow

1. Inspect the package.

   • Read Package.swift.
   • Identify executable, library, and test products.

2. Build with SwiftPM.

   • Use swift build by default.
   • Use release mode only when the user explicitly needs it.

3. Run the right product.

   • Use swift run <product> when an executable exists.
   • If multiple executables exist, explain the default choice.

4. Test narrowly.

   • Use swift test.
   • Apply filters when a specific test target or case is known.

5. Summarize failures.

   • Module/import resolution
   • Package graph or dependency issue
   • Linker failure
   • Runtime failure
   • Test regression

Guardrails

• Prefer SwiftPM over Xcode when both exist and the package path is clearly simpler.
• Do not assume an app bundle exists in a pure package workflow.
• Explain when the package is library-only and therefore not directly runnable.

Output Expectations

Provide:

• the package products you found
• the command you ran
• whether build, run, or test succeeded
• the top blocker if not

SwiftUI Patterns

Quick Start

Choose a track based on your goal:

Existing project

• Identify the feature or scene and the primary interaction model: document, editor, sidebar-detail, utility window, settings, or menu bar extra.
• Read the nearest existing scene or root view before inventing a new desktop structure.
• Choose the relevant reference from references/components-index.md.
• If SwiftUI cannot express the required platform behavior cleanly, use the appkit-interop skill rather than forcing a shaky workaround.

New app scaffolding

• Choose the scene model first: WindowGroup, Window, Settings, MenuBarExtra, or DocumentGroup.
• If the app combines a normal main window and a MenuBarExtra, use WindowGroup(..., id:) for the primary window when it should appear at launch. Treat Window(...) as a better fit for auxiliary/on-demand singleton windows; in menu-bar-heavy apps, a Window(...) scene may not present the main window automatically at launch.
• Before creating the scaffold, check whether the workspace is already inside a git repo with git rev-parse --is-inside-work-tree. If not, run git init at the project root so Codex app git-backed features are available from the start. Do not initialize a nested repo inside an existing parent checkout.
• For a new app scaffold, also create one project-local script/build_and_run.sh and .codex/environments/environment.toml so the Codex app Run button works immediately. Use the exact bootstrap contract from build-run-debug and its references/run-button-bootstrap.md file rather than inventing a second variant here.
• Decide which state is app-wide, scene-scoped, or window-scoped before writing views.
• Sketch file and module boundaries before writing the full UI. For any non-trivial app, create the folder structure first and split files by responsibility from the start.
• Use a single Swift file only for tiny throwaway examples or snippets: roughly under 50 lines, one screen, no persistence, no networking/process client, and no reusable models. Anything beyond that should be multi-file immediately.
• Use system-adaptive colors and materials by default (Color.primary, Color.secondary, semantic foreground styles, .regularMaterial, etc.) so the app follows Light/Dark mode automatically. Do not hardcode white or light backgrounds unless the user explicitly asks for a fixed theme, and do not reach for opaque windowBackgroundColor fills for root panes by default.
• Pick the references for the first feature surface you need: windowing, commands, split layouts, or settings.

New App File Structure

For any non-trivial macOS app, start with this shape instead of putting the app, all views, models, stores, services, and helpers in one Swift file:

• App/<AppName>App.swift: the @main app type and AppDelegate only.
• Views/ContentView.swift: root layout and high-level composition only.
• Views/SidebarView.swift, Views/DetailView.swift, Views/ComposerView.swift, etc.: feature views named after their primary type.
• Models/*.swift: value models, identifiers, and selection enums.
• Stores/*.swift: persistence and state stores.
• Services/*.swift: app-server, network, process, or platform clients.
• Support/*.swift: small formatters, resolvers, extensions, and glue helpers.

Keep files small and named after the primary type they contain. If a file starts collecting unrelated views, models, stores, networking clients, and helper extensions, split it before adding more behavior.

Pre-Edit Checklist For New App Scaffolds

Before writing the full UI:

1. Choose the scene model.
2. Choose state ownership: app-wide, scene-scoped, window-scoped, or view-local.
3. Sketch file and module boundaries.
4. Create the folder structure before filling in the UI.
5. Keep script/build_and_run.sh and .codex/environments/environment.toml separate from app source.

General Rules To Follow

• Design for pointer, keyboard, menus, and multiple windows.
• Keep scenes explicit. A separate settings window, utility window, or menu bar extra should be modeled as its own scene, not hidden inside one monolithic ContentView.
• Prefer system desktop affordances: commands, toolbars, sidebars, inspectors, contextual menus, and searchable.
• For menu bar apps, keep MenuBarExtra item titles and action labels short and scannable. Cap visible menu item text at 30 characters; if source content is longer, truncate or summarize it before rendering and open the full content in a dedicated window or detail surface.
• If a MenuBarExtra app should still behave like a regular Dock app with a visible main window/process, install an NSApplicationDelegate via @NSApplicationDelegateAdaptor, call NSApp.setActivationPolicy(.regular) during launch, and activate the app with NSApp.activate(ignoringOtherApps: true). If the app is intentionally menu-bar-only, document that .accessory / no-Dock behavior is a deliberate product choice.
• Prefer system-adaptive colors, materials, and semantic foreground styles. Avoid fixed white/light backgrounds in scaffolding and examples unless the requested design explicitly calls for a custom non-adaptive theme.
• Do not paint NavigationSplitView sidebars or root window panes with opaque custom Color(...) or Color(nsColor: .windowBackgroundColor) fills by default. Prefer native macOS sidebar/window materials and system-provided backgrounds unless the user explicitly asks for a custom opaque surface. In sidebar-detail-inspector layouts, let the sidebar keep the standard source-list/material appearance and reserve custom backgrounds for detail or inspector content cards where needed.
• Use @SceneStorage for per-window ephemeral state and @AppStorage for durable user preferences.
• Keep selection state explicit and stable. macOS layouts often pivot around sidebar selection rather than push navigation.
• Prefer NavigationSplitView or a deliberate manual split layout over iOS-style stacked flows when the app benefits from always-visible structure.
• For List(...).listStyle(.sidebar) and NavigationSplitView sidebars, prefer flat native rows with standard system selection/highlight behavior. Keep rows visually lightweight and Mail-like: at most one leading icon, one strong title line, and one optional secondary detail line in .secondary. Avoid stacked metadata rows, repeated inline utility icons, or dense multi-column status text in the sidebar. Reserve card-style and metadata-heavy surfaces for detail or inspector panes unless the user explicitly asks for a highly custom sidebar treatment.
• Keep primary actions discoverable from both UI chrome and keyboard shortcuts when appropriate.
• Use SwiftUI-native scenes and views first. If you need low-level window, responder-chain, text system, or panel control, switch to appkit-interop.

For concrete sidebar row and split-view background examples, read references/split-inspectors.md.

State Ownership Summary

Use the narrowest state tool that matches the ownership model:

Choose the ownership location first, then the wrapper. Do not turn simple desktop state into a view model by reflex.

Cross-Cutting References

• references/components-index.md: entry point for scene and component guidance.
• references/windowing.md: choosing between WindowGroup, Window, DocumentGroup, and window-opening patterns.
• references/settings.md: dedicated settings scenes, SettingsLink, and preference layouts.
• references/commands-menus.md: command menus, keyboard shortcuts, focused values, and desktop action routing.
• references/split-inspectors.md: sidebars, split views, selection-driven layout, and inspectors.
• references/menu-bar-extra.md: menu bar extra structure and when it fits.

Anti-Patterns

• One huge ContentView pretending the whole app is a single screen.
• A single Swift file containing the @main app, all views, models, stores, networking/process clients, formatters, and extensions. This is acceptable only for tiny throwaway snippets under the new-app threshold above.
• Touch-first interaction models ported directly from iOS without desktop affordances.
• Hiding core actions behind gestures with no menu, toolbar, or keyboard path.
• Building a menu-bar-plus-window app around only a Window(...) scene and then expecting the main window to appear at launch. Use WindowGroup(..., id:) for the primary launch window and reserve Window(...) for auxiliary/on-demand windows.
• Rendering full unbounded document titles, prompts, or message text directly inside a menu bar extra. Menu item labels should stay at or below 30 characters, with longer content moved into a dedicated window or detail view.
• Treating settings as another navigation destination in the main content window.
• Hardcoding .background(.white), Color.white, or a fixed light palette in a brand-new scaffold without an explicit design requirement.
• Wrapping each sidebar item in large rounded custom cards inside a .sidebar list, which fights native source-list density, alignment, and selection behavior unless the user explicitly asked for a bespoke visual sidebar.
• Building sidebar rows with multiple repeated icons, three or more text lines, or a dense strip of inline metadata counters/timestamps/models. Keep the sidebar row to one icon and one or two text lines, then move richer metadata into the detail pane.
• Painting NavigationSplitView sidebars or root window panes with opaque custom color fills by default, instead of letting the sidebar use native source-list/material appearance and reserving custom backgrounds for actual content cards.
• Using push navigation for layouts that want stable sidebar selection and detail panes.
• Reaching for AppKit before the SwiftUI scene and command APIs have been used properly.

Workflow For A New macOS Scene Or View

1. Define the scene type and ownership model before writing child views.
2. Decide which actions live in content, toolbars, commands, inspectors, or settings.
3. Sketch the selection model and layout: sidebar-detail, editor-inspector, document window, or utility window.
4. Create the file/folder structure for app entrypoint, root layout, feature views, models, stores, services, and support helpers.
5. Build with small, focused subviews and explicit inputs rather than giant computed fragments.
6. Add keyboard shortcuts and menu or toolbar exposure for actions that matter on desktop.
7. Validate the flow with a build and a quick usability pass: multiwindow assumptions, settings entry points, and selection stability.

Component References

Use references/components-index.md as the entry point. Each component reference should include:

• intent and best-fit scenarios
• minimal usage pattern with desktop conventions
• pitfalls and discoverability notes
• when to fall back to appkit-interop

Telemetry

Quick Start

Use this skill to add lightweight app instrumentation that helps debug behavior without turning the codebase into a logging landfill. Prefer Apple's unified logging APIs and verify the events after a build/run loop.

Core Guidelines

• Prefer Logger from the OSLog framework for structured app logs.
• Give each feature a clear subsystem/category pair so runtime filtering stays easy.
• Log meaningful user and app lifecycle events: window opening, sidebar selection changes, menu commands, menu bar extra actions, sync/load milestones, and unexpected fallback paths.
• Keep info logs concise and stable. Use debug logs for noisy state details.
• Do not log secrets, auth tokens, personal data, or raw document contents.
• Add signposts only when measuring timing or performance spans; do not overinstrument by default.

Minimal Logger Pattern

import OSLog

private let logger = Logger(
  subsystem: Bundle.main.bundleIdentifier ?? "SampleApp",
  category: "Sidebar"
)

@MainActor
func selectItem(_ item: SidebarItem) {
  logger.info("Selected sidebar item: \(item.id, privacy: .public)")
  selection = item.id
}

Use feature-specific categories like Windowing, Commands, MenuBar, Sidebar, Sync, or Import so logs can be filtered quickly.

Workflow

1. Identify the behavior that needs observability.

   • Window open/close
   • Sidebar or inspector selection changes
   • Menu or keyboard command actions
   • Menu bar extra actions
   • Background load/sync/import events
   • Error and recovery paths

2. Add the smallest useful instrumentation.

   • Create one Logger per feature area or type.
   • Log action boundaries and key state transitions.
   • Prefer one high-signal line per user action over noisy value dumps.

3. Build and run the app.

   • Use build-run-debug for the build/run loop.
   • If script/build_and_run.sh exists, prefer ./script/build_and_run.sh --telemetry for live telemetry checks or ./script/build_and_run.sh --logs for broader process logs.
   • Exercise the UI or command path that should emit telemetry.

4. Read runtime logs and verify the event fired.

   • Use Console.app with a process/subsystem filter when that is the fastest manual check.
   • Use log stream --style compact --predicate 'process == "AppName"' for live terminal verification.
   • Prefer tighter predicates when you know the subsystem/category: log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'

5. Tighten or remove instrumentation.

   • If the event fires, keep only the logs that remain useful for future debugging.
   • If it does not fire, move the log closer to the suspected control path and rerun.

Verification Checklist

• The app builds after telemetry changes.
• The relevant action emits exactly one clear log line or a small bounded sequence.
• The log can be filtered by process, subsystem, or category.
• No sensitive payloads are written to unified logs.
• Noisy temporary debug logs are removed or demoted before finishing.

Guardrails

• Do not use print as the primary app telemetry mechanism for macOS app code.
• Do not leave a dense trail of permanent debug logs around every state mutation.
• Do not claim an event is wired correctly until you have a concrete verification path through Console, log stream, or captured process output.
• If the debugging task is mostly about crash/backtrace analysis rather than action telemetry, switch to build-run-debug.

Test Triage

Quick Start

Use this skill to run the smallest meaningful test scope first, classify failures precisely, and avoid treating every test failure like a product bug.

Workflow

1. Detect the test harness.

   • Use xcodebuild test for Xcode-based projects.
   • Use swift test for SwiftPM packages.

2. Narrow the scope.

   • If the user gave a target, product, or test filter, use it.
   • If not, prefer the smallest likely failing target before a full suite.

3. Classify the result.

   • Build failure
   • Assertion failure
   • Crash or signal
   • Async timing or flake
   • Environment or fixture setup issue
   • Missing entitlement or host app issue

4. Rerun intelligently.

   • Use focused reruns when a specific case fails.
   • Avoid burning time on full-suite reruns without new information.

5. Summarize clearly.

   • What command ran
   • Which tests failed
   • What kind of failure it was
   • The best next proof step or fix path

Guardrails

• Distinguish compilation failures from test execution failures.
• Call out when a test appears to assume iOS-only or simulator-only behavior.
• Mark likely flakes as such instead of overstating confidence.

Output Expectations

Provide:

• the command used
• the smallest failing scope
• the top failure category
• a concise explanation of the likely cause
• the next rerun or fix step

View Refactor

Overview

Refactor macOS views toward small, explicit, stable scene and view types. Default to native SwiftUI for layout, selection, commands, and settings. Reach for AppKit only at the narrow edges where desktop behavior truly requires it.

Core Guidelines

1) Model scenes explicitly

• Break the app into meaningful scene roots: main window, settings, utility windows, inspectors, or menu bar extras.
• Do not let one giant root view silently own every desktop surface.

2) Keep a predictable file shape

• Follow this ordering unless the file already has a stronger local convention:
• Environment
• private/public let
• @State / other stored properties
• computed var (non-view)
• init
• body
• computed view builders / other view helpers
• helper / async functions

2b) Split files by responsibility

• For non-trivial apps, do not keep the full app, all views, models, stores, networking clients, process clients, and helpers in one Swift file.
• Accept a single Swift file only for tiny throwaway examples or snippets: roughly under 50 lines, one screen, no persistence, no networking/process client, and no reusable models.
• Use App/<AppName>App.swift for the @main app and AppDelegate only.
• Keep Views/ContentView.swift focused on root layout and composition; move feature UI into files such as Views/SidebarView.swift, Views/DetailView.swift, and Views/ComposerView.swift.
• Move value types and selection enums into Models/*.swift, stores into Stores/*.swift, app-server/network/process clients into Services/*.swift, and small formatters/resolvers/extensions into Support/*.swift.
• Keep files small and named after the primary type they contain.

3) Prefer dedicated subview types over many computed some View fragments

• Extract meaningful desktop sections like sidebar rows, detail panels, inspectors, or toolbar content into focused subviews.
• Keep computed some View helpers small and rare.
• Pass explicit data, bindings, and actions into subviews instead of handing down the whole scene model.

4) Keep selection and layout stable

• Prefer one stable split or window layout with local conditionals inside it.
• Avoid top-level branch swapping between radically different roots when selection changes.
• Let the layout be constant; let state drive the content inside it.

5) Extract commands, toolbars, and actions out of body

• Do not bury non-trivial button logic inline.
• Do not mix command routing, menu state, and layout in the same block if they can be named clearly.
• Keep body readable as UI, not as a desktop view controller.

6) Use scene and app storage intentionally

• Use @SceneStorage for per-window ephemeral state when it truly helps restore the scene.
• Use @AppStorage for durable preferences, not transient UI toggles that only matter in one window.
• Keep scene-owned state close to the scene root.

7) Keep AppKit escape hatches narrow

• If a representable or NSWindow bridge exists, isolate it behind a small wrapper or helper.
• Do not let AppKit references spread through unrelated SwiftUI views.
• If the bridge starts owning the feature, re-evaluate the architecture.

8) Observation usage

• For @Observable reference types on modern macOS targets, store them as @State in the owning view.
• Pass observables explicitly to children.
• On older deployment targets, fall back to @StateObject and @ObservedObject where needed.

Workflow

1. Identify the current scene boundary and whether the file is trying to do too much.
2. Reorder the file into a predictable top-to-bottom structure.
3. Extract desktop-specific sections into dedicated subview types.
4. Stabilize the root layout around selection, scenes, and commands rather than top-level branching.
5. Move action logic, command routing, and toolbar behavior into named helpers or separate types.
6. Tighten any AppKit bridge so the imperative edge is small and explicit.
7. Keep behavior intact unless the request explicitly asks for structural and behavioral changes together.

Refactor Checklist

• Split oversized view files before adding more UI.
• Move pure models, identifiers, and selection enums out of view files.
• Move Process, URLSession, app-server, and platform client code out of SwiftUI views into Services/.
• Keep AppDelegate and the @main app entrypoint minimal.
• Build after each major split so compile errors stay local.

Common Smells

• A root view that mixes window scaffolding, settings, toolbar code, command handling, and detail layout.
• A single app file that mixes app entrypoint, root layout, feature views, models, stores, service clients, and support extensions.
• iOS-style push navigation forced into a Mac sidebar-detail problem.
• Several booleans for mutually exclusive inspectors, sheets, or utility windows.
• AppKit objects passed through many SwiftUI layers without a clear ownership reason.
• Large computed view fragments standing in for real subviews.

Notes

• A good macOS refactor should make scene structure, selection flow, and command ownership obvious.
• When the problem is fundamentally a missing desktop pattern, use swiftui-patterns.
• When the problem is fundamentally a boundary with AppKit, use appkit-interop.

Window Management

Overview

Use this skill to tailor each SwiftUI window to its job. Start by identifying which scene owns the window (Window, WindowGroup, or a dedicated utility scene), then customize the toolbar/title area, background material, resize and restoration behavior, and initial or zoomed placement.

Prefer scene and window modifiers over ad hoc AppKit bridges when SwiftUI offers the behavior directly. Keep each window purpose-built: a main browser window, an About window, and a media player window usually want different chrome, resizability, restoration, and placement rules.

These APIs are macOS 15+ SwiftUI window/scene customizations. For older deployment targets, expect to use more AppKit bridging or availability guards.

Workflow

1. Inspect the relevant scene declaration and classify the window role: main app navigation, inspector/detail utility, About/support window, media playback window, welcome window, or a borderless custom surface.
2. Adjust toolbar and title presentation to match the content.
3. If the toolbar background or entire toolbar is hidden, make sure the window still has a usable drag region.
4. Refine window behavior for that role: minimize availability, restoration, resize expectations, and whether the window should appear at launch.
5. Set default placement for newly opened windows and ideal placement for zoom behavior when content and display size matter.
6. Build and launch the app with build-run-debug to verify the result in a real foreground .app bundle.
7. If SwiftUI scene/window modifiers are not enough, switch to appkit-interop for a narrow NSWindow bridge rather than spreading AppKit through the view tree.

Toolbar And Title

• Use .toolbar(removing: .title) when the window title should stay associated with the window for accessibility and menus, but not be visibly drawn in the title bar.
• Use .toolbarBackgroundVisibility(.hidden, for: .windowToolbar) when large media or hero content should visually extend to the top edge of the window.
• If the window still needs close/minimize/full-screen controls, remove only the title and toolbar background. If the toolbar should disappear entirely, use .toolbarVisibility(.hidden, for: .windowToolbar) instead.
• Remove custom toolbar backgrounds and manually painted titlebar fills before layering new SwiftUI toolbar APIs on top.
• Keep the window's logical title meaningful even if hidden; the system can still use it for accessibility and menu items. These are visual changes only.

Drag Regions

• If a toolbar background is hidden or the toolbar is removed entirely, use WindowDragGesture() to extend the draggable area into your content.
• Attach the gesture to a transparent overlay or non-interactive header region that does not steal gestures from real controls.
• For a media player with custom playback controls, insert the drag overlay between the video content and the controls so AVKit or transport controls keep receiving input.
• Pair the drag gesture with .allowsWindowActivationEvents(true) so clicking and immediately dragging a background window still activates and moves it.

Background And Materials

• Use .containerBackground(.thickMaterial, for: .window) when a utility window or About window should replace the default window background with a subtle frosted material.
• Prefer system materials for stylized windows instead of hardcoded translucent colors.
• Use this especially for fixed-content utility windows where a softer backdrop is part of the design.

Window Behavior

• Use .windowMinimizeBehavior(.disabled) for always-reachable utility windows such as a custom About window where minimizing adds little value.
• Disable the green zoom control through fixed sizing or window constraints when the window's content has one intended size.
• Use .restorationBehavior(.disabled) for windows that should not reopen on next launch, such as About panels, transient support/info windows, or first-run welcome surfaces.
• Keep state restoration enabled for primary document or navigation windows when reopening prior size and position is desirable.
• By default, SwiftUI respects the user's system-wide macOS state restoration setting. Use restorationBehavior(...) only when a specific window should intentionally opt into or out of that system behavior.
• Use .defaultLaunchBehavior(.presented) for windows that should appear first on launch, such as a welcome window, and choose that behavior intentionally rather than relying on side effects from scene creation order.

Window Placement

• Use .defaultWindowPlacement { content, context in ... } to control the initial size and optional position of newly opened windows.
• Inside the placement closure, call content.sizeThatFits(.unspecified) to get the content's ideal size.
• Read context.defaultDisplay.visibleRect to get the display's usable region after accounting for the menu bar and Dock.
• Return WindowPlacement(size: size) with a size clamped to the visible rect when media or document content may be larger than the display. If no position is provided, the window is centered by default.
• Use .windowIdealPlacement { content, context in ... } to control what happens when the user chooses Zoom from the Window menu or Option-clicks the green toolbar button. For media windows, preserve aspect ratio and grow to the largest size that fits the display.
• Treat default placement and ideal placement as separate policies:
  • default placement controls where a new window first appears,
  • ideal placement controls how large a zoomed window should become.
• Always consider external displays and rotated/narrow screens when sizing player windows or document windows from content dimensions.

Borderless And Specialized Windows

• Use .windowStyle(.plain) for borderless or highly custom chrome windows, but make sure the content still provides a clear drag/move affordance and visible context.
• For a borderless player, HUD, or welcome window, decide upfront whether losing standard titlebar affordances is worth the custom presentation.
• Keep one clear path back to regular window management if the plain style makes the window feel invisible or hard to move.

For concrete window modifier examples, read references/api-snippets.md.

Review Checklist

• The scene type matches the window's role and lifecycle.
• Hidden titles still leave a meaningful logical title for accessibility and menus.
• Toolbar background removal is intentional and does not hurt titlebar legibility or window control placement.
• Windows with hidden or removed toolbars still have a reliable drag region and support click-then-drag activation from the background.
• Utility windows have restoration/minimize behavior that matches their purpose.
• Restoration overrides are used only when a scene should intentionally differ from the user's system-wide setting.
• Default and ideal placement use content.sizeThatFits(.unspecified) and context.defaultDisplay.visibleRect when content/display size matters.
• Media windows preserve aspect ratio and fit on small or rotated displays.
• Borderless windows still have a usable move/drag affordance.

Guardrails

• Do not use .toolbar(removing: .title) just to hide a title you forgot to set. Keep the underlying window title meaningful.
• Do not hide the toolbar background or the whole toolbar without replacing the lost drag affordance.
• Do not disable restoration on the main document/navigation window unless the user explicitly wants a fresh-start app every launch.
• Do not hardcode one monitor size or assume a single-display setup when sizing player windows.
• Do not reach for NSWindow mutation before checking whether .windowMinimizeBehavior, .restorationBehavior, .defaultWindowPlacement, .windowIdealPlacement, .windowStyle, or .defaultLaunchBehavior already solve the problem.
• Do not leave a plain borderless window without any obvious drag or close path.

When To Use Other Skills

• Use swiftui-patterns for broader scene, commands, settings, sidebar, and inspector architecture.
• Use liquid-glass when the main question is modern macOS visual treatment, Liquid Glass, or system material adoption.
• Use appkit-interop if a custom window behavior truly requires NSWindow, NSPanel, or responder-chain control.
• Use build-run-debug to launch and verify the resulting windows.

Frontend App Builder

Use this skill to create polished frontend apps, dashboards, games, creative websites, hero sections, redesigns, and other visually driven UI. Act first as a senior front-end designer, then as an engineer implementing an approved design spec.

Core Standard

The two priorities of this skill outrank everything else:

1. Create enough great-looking Image Gen design first: clean, airy, distinctive, complete, readable, section-specific when needed, and not repetitive by default.
2. Do not stop until the accepted design and browser implementation match 10/10. Keep fixing visual, interaction, responsive, asset, and typography mismatches until view_image comparison would pass agency sign-off.

Hard Rules

1. Use Image Gen for the visual concept unless the user explicitly opts out or the task is a small UI fix inside an existing design system.
2. Design the complete requested surface before coding. For a full page, app, dashboard, game, or product interface, a header or hero concept is not enough. For multi-section websites and long landing pages, prefer coordinated section-by-section concepts, plus an optional overview for rhythm, over one tall image that loses detail. For apps, dashboards, games, or compact product surfaces, generate the full primary screen plus any needed state, responsive, or asset concepts first.
3. Inside Codex, default multi-section website concepting to one fresh, large, readable Image Gen screenshot per major section. If the request has 1-10 sections, expect roughly 1-10 primary section images. Generate additional section/detail screenshots whenever text, buttons, card anatomy, typography, spacing, or colors are too small to extract. Do not crop or zoom an old full-page image as the main reference; regenerate a fresh standalone section or detail image that preserves the same design system.
4. In Plan mode, generate the design first, then use request_user_input to get design approval before planning implementation details.
5. Once accepted, the concept is a production design spec. No creative liberties during implementation: do not reinterpret layout, visible copy, hierarchy, container model, styling, imagery, density, or sections unless the user approves it or a concrete blocker requires it. General design heuristics never override the accepted concept.
6. The completion bar is agency-signoff faithful implementation: 10/10 fidelity to the accepted spec plus production-quality code. If the browser-rendered UI would receive design-review comments, keep fixing it.
7. Before coding, build a small design system from the accepted image: tokens, typography, component families, variants, spacing, icon treatment, and container rules. Include both content typography and UI chrome typography for tools, editors, and dashboards. Implement from that system so repeated elements stay consistent.
8. For new complex app UIs such as dashboards, admin tools, editors, data-heavy tools, and multi-panel product surfaces, default to React + Vite unless the user specifies another framework, the existing repo already dictates one, or the task is explicitly a single-file/static deliverable.
9. Hero eyebrow, kicker, pretitle, badge, or pill labels above the main heading are prohibited by default. Use one only when the user explicitly requested it or the accepted/reference design already contains it.
10. Verify in the Browser plugin / built-in browser first. Use Playwright Chromium only when Browser/IAB is unavailable or unreliable, and state the fallback reason.
11. Final handoff is blocked until you use view_image on both the accepted concept and the latest browser screenshot. This cannot be skipped or replaced with browser inspection alone. Judge the pair directly: is this agency-signoff faithfully implemented, and would a great, highly skilled design agency sign off on this exact implementation of the accepted design? If not, keep fixing.
12. Remove temporary QA artifacts before handoff unless the user or task explicitly asks to keep them.

Coordinate With Other Installed Skills

This skill owns visual concepting and faithful frontend implementation. Use other installed skills when the app needs capabilities outside frontend design. Provider setup should not block Image Gen concepting, static UI work, or design review that does not exercise provider-backed behavior, but implementation and verification of provider-backed behavior should coordinate through the installed skill for that capability. Avoid placeholder setup instructions when another installed skill covers that setup.

For AI/model-generated output, use openai-developers:openai-platform-api-key when available unless the user names another provider or explicitly says not to use OpenAI. When that skill is available, always use its credential flow instead of fake keys, placeholder env vars, or manual API-key setup instructions.

Image Gen Workflow

Read and follow the installed @imagegen skill. For website-specific briefing guidance, use references/imagegen-website-concepts.md.

Before calling Image Gen:

• Copy the user's concrete requirements into the brief: product/page purpose, audience, required sections or states, workflow, supplied copy, nav labels, CTA labels, data fields, required media, responsive needs, and implementation constraints.
• Ask for the complete requested surface: full page, app screen, dashboard, game screen, or coordinated section/state set. If the deliverable is more than a hero, say the concept must include downstream sections, states, or responsive continuation. If the section count is known or implied, name each section/state that needs its own concept screenshot.
• Repeat the implementation constraints: code-native app UI text and controls, fully rendered product/background assets with their own text and branding when appropriate, separable assets, reusable component families, intentional container model, no default card grids, no invented hero eyebrows/kickers/badges/pills, and practical HTML/CSS/component implementation.
• Preserve information architecture from user content, screenshots, or existing apps. Do not let Image Gen invent unrelated sections, fake metrics, new product claims, extra dashboards, new navigation, or a different product story.
• For multi-section websites or long landing pages, default to one coordinated concept image per major section. Use an optional overview only for structure and rhythm; never rely on one giant compressed board when it makes text, button details, card structure, spacing, or typography hard to analyze.
• For dense apps, dashboards, editors, product surfaces, and complex sections, generate separate state or detail concepts for the areas that would become unreadable in a single full-screen image: tables, sidebars, inspectors, modals, toolbars, charts, forms, cards, pricing blocks, testimonials, or media modules.
• If any concept screenshot is too small, blurry, cropped, crowded, or ambiguous for implementation, generate a fresh standalone section/state/detail screenshot before coding. Keep the same palette, typography mood, component family, asset treatment, density, and section order. Do not crop, slice, zoom, or reuse a tiny part of an earlier image as the source of truth.
• For games, plan a dedicated Image Gen asset pass in addition to the concept: transparent character/state sprites or sprite sheet, terrain/platform tiles, collectibles, hazards, goal/checkpoint objects, props, and 2-3 parallax/background layers when the environment has depth. HUD text, scoring, controls, physics, and collision remain code-native.

Reject or iterate on concepts that are header-only for a full-surface ask, cluttered, generic, repetitive, under-specified, unreadable, over-decorated, off-spec with hero eyebrows/kickers/badges/pills not explicitly requested or present in the reference, or not practical to implement faithfully.

Design Quality Bar

The concept should look like a professional product mockup by a senior product designer:

• One clear creative idea or visual point of view.
• Strong first viewport with clear offer, product signal, and primary action.
• Full-page rhythm: sections, states, transitions, and mobile views feel designed as one system, without repetitive card stacks or repeated section formulas.
• Cohesive section-to-section flow: connect sections with shared spacing, palette, type rhythm, media treatment, and subtle transitions, not by inventing major new UI components.
• Excellent typography: clear hierarchy, scale, weight, line height, label treatment, and control/chrome text that never falls back to browser-default sizing.
• Intentional whitespace and density; no filler cards, hero eyebrow/kicker labels, pills, badges, fake metrics, or icon rows unless explicitly requested or present in the accepted design.
• Simpler by default: use fewer, stronger visual elements instead of filling the page with illustrations, iconography, decorative widgets, or complex UI chrome.
• Coherent visual system: palette, spacing, radius, borders, shadows, gradients, icon style, imagery, and component geometry.
• Icon fidelity matters when icons are present. Match the accepted design's icon metaphor, stroke weight, fill style, corner shape, size, color, alignment, and spacing instead of swapping in generic nearby icons.
• Color fidelity is mandatory. Match the accepted design's actual background, surface, text, border, shadow, and accent colors; if the design uses a white background, use white rather than cream, ivory, beige, warm gray, or any softened off-white substitute.
• Hero media treatment must match the accepted design. If the hero image has no color overlay or tint in the concept, the implementation must not add one. Use edge fades, masks, or background gradients only to blend image edges into the page; do not wash the image with a color overlay.
• High-quality generated assets for logos, brand marks, hero imagery, product renders, background scenes, illustrations, textures, posters, avatars, empty states, and game sprites/tiles/background layers. Product/background assets should be fully rendered with consistent branding and in-image text when that text belongs to the asset.
• Purposeful motion that clarifies hierarchy, reveals state, or makes the product feel tangible.
• Specific, non-generic copy when the user has not provided exact copy.

Default to clean, airy, tasteful 7/10 creativity: distinctive enough to feel designed, restrained enough to build, and not repetitive. Interpret "clean" as edited and legible, not empty or sterile.

Visual Direction Defaults

Use these defaults when the user has not given stronger art direction. Adapt them to the product type instead of forcing every app into a marketing-site style.

• Baseline: roughly 7/10 creativity, low-to-medium density, generous spacing, high implementation clarity, high typography discipline, and image-led moments when the domain benefits from real visuals.
• Before generating concepts, choose a coherent visual direction: one theme paradigm, background character, typography character, hero or primary-screen architecture, section/app rhythm, 2-4 signature component motifs, and 1-2 motion cues. Commit to the combination so the design feels intentional instead of a generic template.
• Hero or first viewport: keep one obvious focal point, a short readable headline or primary task, restrained supporting copy, a visible primary action, and enough negative space to work on a small laptop. Do not overcrowd the opening view with stats, chips, badges, fake controls, or competing mini-panels.
• Header simplicity: default to a clean brand mark, essential navigation, and one primary action or control. Avoid icon-heavy nav, extra buttons, search bars, status widgets, segmented controls, decorative illustrations, or dense product chrome in the header unless the user explicitly asks for them or the product workflow requires them.
• Visual economy: prefer one or two high-quality image or illustration moments over many small decorative visuals. Use iconography only where it clarifies navigation, controls, or product meaning.
• Container discipline: avoid nested cards, giant rounded wrappers around every section, default bento/card grids, and over-framed dashboards unless the concept or product type truly needs them. Prefer open layouts, bands, rails, lists, tables, canvases, or a single purposeful framing move.
• Section rhythm: long pages should vary density, image-to-text ratio, alignment, scale, whitespace, and visual tempo while keeping one coherent brand system. Do not repeat the same centered block or left-text/right-card formula through the whole page.
• Section continuity: when multiple section concepts need to become one page, use connective tissue from the existing design system: gutters, bands, alignment, repeated typography, recurring media frames, color rhythm, and small transitional spacing shifts. Do not invent major new carousels, accordions, pricing cards, dashboards, forms, nav systems, feature grids, or other component families unless the user requested them or the accepted concepts show them.
• Media framing: generated imagery should usually sit in clear, implementation-friendly frames with stable aspect ratios, consistent crop logic, radius, shadows, and spacing. Avoid random image sizes or collage chaos unless the user explicitly asks for that direction.
• UI restraints: small labels, utility pills, pseudo-system markers, fake metrics, and decorative dashboard jargon are allowed only when they clarify the product. If they are just visual filler, remove them before acceptance.

Concept Review Mode

Use only when the user asks to generate concepts first, review options, or wait for approval.

• Generate and show the concept.
• Iterate until the user approves.
• Do not implement while the user is still reviewing.
• Once approved, treat the concept as the active spec and follow the fidelity workflow below.

Before Coding

Turn the accepted concept into a design system and implementation inventory before coding:

• Exact visible copy, nav items, CTA labels, section headings, proof points, data labels, and important UI text.
• Per-section/state image inventory: source concept screenshot, native aspect, visual priority, readable text, typography relationships, spacing, button/control styling, component/container rules, dominant colors, and any unresolved details that required a fresh extraction screenshot.
• Allowed above-the-fold copy list: every visible hero, nav, eyebrow/kicker/pretitle, badge/pill, CTA, label, and proof string allowed from the accepted concept or user-provided copy.
• First viewport composition, section order, downstream states, responsive continuation, and next-section preview.
• Section continuity plan: how adjacent sections connect using the accepted design system, and which major component families are allowed. Treat unshown major components as prohibited unless the user requested them or a required workflow cannot function without them.
• Brand mark, imagery roles, product mockups, dashboards, tables, charts, maps, media rails, forms, HUDs, or other visual artifacts.
• Hero/media treatment inventory: whether each image has no overlay, a color overlay, a gradient overlay, edge fade, mask, transparent background, or matching background color. Record this explicitly before coding.
• Standalone asset needs: if the concept includes a logo, brand mark, product label, packaging, poster, sign, product render, or branded background object, create matching standalone assets with Image Gen editing before implementation so branding stays coherent.
• Game asset needs: if the concept is a game, create matching production art assets with Image Gen before implementation. Include transparent sprite/state assets, tiles/platforms, collectibles, hazards, goal objects, props, and parallax/background layers as needed; use code for collision boxes and game state, not as a substitute for visible art.
• Design tokens sampled or approximated from the image: background, surface, text, muted text, border, shadow, accent, semantic colors, radii, elevation, spacing scale, and motion timing.
• Color lock: explicitly identify whether the concept background is true white, off-white, cream, gray, dark, or tinted, then implement that exact choice. Do not warm up, cool down, mute, or otherwise "tastefully" reinterpret the palette.
• Typography system: font family/fallback, type scale, weights, line heights, tracking, label treatment, heading/body/caption styles, control text styles, and responsive type behavior.
• Icon inventory: every visible icon, glyph, chevron, logo-like mark, toolbar symbol, status symbol, and empty-state symbol; record meaning, source family, outline vs filled style, stroke width, size, color, container, alignment, spacing, and selected/hover/disabled treatment.
• Component families and variants: buttons, navigation, rows, panels, media frames, product mockups, cards only where present, tables, forms, chips, icons, empty states, responsive variants, hover/focus/selected states.
• Component architecture plan for complex app UIs: app shell, navigation, major feature regions, reusable UI primitives, data/state helpers, chart/table/form modules, asset modules, and responsive layout boundaries. A great front-end implementation should have clear component ownership, not one giant App component or one-off copied markup.
• Container model: cards, panels, rails, bands, lists, tables, canvases, drawers, sidebars, modals, or full-bleed sections.
• Core workflow: controls that must respond, selected states, filters, tabs, edits, creation flow, success state, playback, game controls, or generated-result demo.

If the concept omits required downstream sections, states, mobile views, or readable detail for a complex area, generate matching section/state/detail concepts when visual consistency or extraction is uncertain. Otherwise extend in the exact same visual system.

Implementation

• Build the real usable surface first, not a marketing wrapper around a future app.
• Follow the repo's framework, routing, component, styling, state, accessibility, and asset conventions.
• When creating a new complex app UI without an existing framework constraint, use React + Vite by default. Structure it like a senior front-end engineer would: small focused components, a clear app shell, reusable primitives for repeated controls, feature-specific modules for dashboards/tables/charts/forms, separated sample data and state helpers, and shared tokens/styles. Keep App as composition glue instead of a monolithic screen implementation.
• Implement through the design system extracted from the image. Similar elements must use the same component or shared style primitive; differences should be explicit variants, not one-off copied CSS.
• Implement the accepted concept exactly. Preserve copy, hierarchy, section order, density, colors, typography, spacing, radii, borders, shadows, asset framing, and interaction model.
• For multi-section pages, implement in slices that match the accepted section concepts. Start with the first viewport, compare its browser screenshot to the section concept, fix visible drift, then continue section by section. Do not defer all visual comparison until the whole page is coded, and do not merge or simplify section-specific design decisions just because a broad overview image is easier to follow.
• Connect sections into one cohesive page without adding unapproved major UI components. Use spacing, background bands, alignment, typography rhythm, repeated motifs, and media framing to bridge gaps. Do not invent new carousels, accordions, pricing blocks, dashboards, forms, tab systems, feature-card grids, or other large components to make the page feel complete unless they appear in the accepted concept, were requested by the user, or are recorded as a concrete functional necessity.
• Do not add new visible above-the-fold copy, hero eyebrows/kickers, explanatory labels, subtitles, or category text after concept acceptance unless it appears in the accepted concept, came from the user, or is recorded as an intentional deviation. If semantic HTML, SEO, or accessibility requires changing an H1 or heading level, change the element semantics first; do not invent compensating visible copy.
• Do not add decorative hero eyebrow labels, pills, badges, gradients, glows, or overlays that were not in the accepted design. Do not substitute a gradient treatment unless it matches the concept's palette, direction, intensity, and placement. If the accepted hero image has no color overlay, do not add a translucent tint, wash, or colored layer over it. If the image needs help blending into a non-matching page background, use a matching asset, transparent cutout, edge fade, mask, or background gradient around the image rather than a color overlay on top of the image. Do not replace white backgrounds with cream/off-white or otherwise shift the accepted color temperature.
• Define typography on controls deliberately. Do not rely on browser defaults or inherited 16px sizing for buttons, tabs, inputs, toolbars, sidebars, inspector panels, layer rows, status bars, command palettes, or export/share controls.
• Preserve the container model. Do not add cards, bordered panels, floating containers, tiles, or card grids where the spec uses open whitespace, bands, rails, lists, tables, canvases, or full-bleed composition.
• Keep real interactive app UI text, navigation, buttons, forms, tables, controls, and labels code-native. This does not apply to text and branding that belong inside product images, posters, packaging, signs, background scenes, hero photos, or other raster assets. Do not ship a static screenshot as UI.
• Use Image Gen for central non-icon assets. Render product images and background assets completely with the needed text, logos, marks, labels, packaging, signage, and branding. When the asset must layer into the UI, request a transparent background or clean cutout. Quote exact asset text and require verbatim rendering when text matters.
• If the accepted design includes branded product imagery, use Image Gen editing to create standalone versions of the logo/product/packaging/signage assets from the concept or a matching asset pass. Include transparent-background variants when those assets need to layer into the UI. Do not rebuild branded raster assets from generic CSS, mismatched fonts, or approximate labels.
• For games, use Image Gen for visible production art: character/state sprites or sprite sheets, terrain/platform tiles, collectibles, hazards, goals/checkpoints, foreground props, and parallax/background layers. Do not fall back to canvas-drawn shapes because collision, scaling, or animation is simpler. Keep HUD text, score, controls, hit boxes, physics, and game state code-native, and tune collision geometry to the rendered assets. Any code-drawn or vector game art must be listed as an intentional deviation or concrete blocker.
• Do not replace concept assets with rough CSS drawings, generic gradients, placeholder SVGs, or stock-like crops. Images must sit naturally in the composition: background color, lighting, edges, crop, shadow, and transparency should blend with the surrounding design. SVG is fine for faithful icons and directional glyphs.
• Use SVG/icon components for arrows, chevrons, carets, disclosure indicators, pagination arrows, and carousel arrows; do not use plain text glyphs unless the concept intentionally does.
• Implement icons as faithfully as other visual elements. Prefer the repo's existing icon set or lucide only when it matches the accepted design's style; otherwise create a small custom SVG/icon variant that matches the concept. Custom SVG icons must be production-quality vector assets: clear viewBox, clean geometry, consistent stroke widths, aligned joins/caps, balanced negative space, optical centering, scalable paths, no jagged or placeholder-looking shapes, and currentColor or explicit fills only when they match the design system. Do not replace filled icons with outline icons, rounded icons with sharp icons, thick strokes with thin strokes, or specific metaphors with generic symbols. Keep icon color, optical size, baseline alignment, padding, and interactive states consistent with the extracted icon inventory.
• Make app interfaces experiential: local state, meaningful selected states, working filters/tabs/forms, editable or creatable items, success states, playback controls, game controls, or simulated generated output where appropriate.
• Use interactive UI inside a hero only when it genuinely fits: SaaS/software product previews, product demos, or purposeful interactive animation. Do not force fake interactive chrome into a branded, editorial, product, venue, food, consumer, or background-led hero. Faithful implementation and consistent branding are more important than adding interactivity.
• Add motion only where it supports the design. Respect accessibility and prefers-reduced-motion.
• Keep implementation production-oriented: semantic markup, stable responsive dimensions, no fragile hardcoded hacks, and type/lint/test checks when the repo supports them.

Verification

Run the app and verify the visible product, not just the build.

1. Use Browser/IAB first. Load the app, inspect the first viewport, scroll, and click through the core workflow.
2. Check desktop, current browser viewport, and a mobile-sized viewport.
3. Capture or locate the accepted concept and the latest implementation screenshot. Use view_image on both in the same QA pass before final handoff; do not skip this step or substitute a browser glance for it.
4. Capture the implementation at the accepted concept's native dimensions when practical. If not practical, record the blocker and also verify the current browser viewport.
5. Write a fidelity ledger before final: mismatch, concept evidence, render evidence, and fix made or reason not fixed. For multi-section or multi-state specs, include evidence from the relevant section/state concept screenshots, not only the overview. Inspect at least five concrete comparison points covering copy, layout, typography, palette/gradients, asset treatment, spacing/container model, responsive behavior, or motion.
6. Compare side by side for copy, nav, CTA labels, section order, first-viewport balance, next-section visibility, palette, gradient treatment, font personality, type scale, spacing, borders, radii, container model, asset/background blending, motion, and simulated interactions.
7. Run an above-the-fold copy diff against the allowed copy list. Added, removed, renamed, or reordered visible copy must be fixed or listed as an intentional deviation; unapproved additions fail fidelity.
8. Audit typography everywhere, not just the hero or main canvas. Check headings, body, captions, labels, toolbar controls, sidebar rows, tabs, inputs, inspector fields, status bars, command palettes, export/share buttons, table cells, chart labels, and mobile line breaks. Use computed CSS sizes/weights/line-heights when the screenshot suggests drift.
9. Audit icons wherever they appear: nav, buttons, cards, toolbar controls, sidebars, tables, status indicators, empty states, pagination, carousels, and mobile controls. Check metaphor, stroke/fill style, size, color, alignment, optical weight, spacing, and state changes against the accepted concept.
10. For canvas/editor apps, audit app chrome separately from canvas/document text. Default zoom and pan are part of the spec; persisted local state must not hide seed, scale, or typography fixes during verification.
11. Ask explicitly: is this agency-signoff faithfully implemented, and would a great, highly skilled design agency sign off on this exact implementation of the accepted design? If anything would get a design-review comment, write a concrete repair checklist and keep editing. Do not final-answer with fixable visual issues.
12. Verify generated assets load, are framed correctly, and do not obscure text or controls.
13. Verify the core workflow updates real local UI state. Do not ship inert controls, fake media progress, hidden required media, or placeholder interactions.

Functional QA does not count as fidelity QA. Passing build checks, clicking controls, or verifying local state cannot replace the concept-to-screenshot comparison, native-size check, and written mismatch ledger.

Hard stops: clipped primary content, accidental wrapping, prototype-looking layout, rough seeded data, placeholder boxes, generic stock-like assets, unfinished cards, code-drawn game placeholders replacing concept art, invented visible copy, invented hero eyebrows/kickers/pills/badges, mismatched colors or gradients, white backgrounds changed to cream/off-white, unapproved hero image color overlays or tints, missing or generic substituted icons, mismatched icon style or stroke weight, images that do not blend with the background, stale debug artifacts, unreadable text, type-scale drift, browser-default control typography, mobile overflow, unprofessional responsive collapse, or any visible drift from the accepted spec.

Surface Gates

• Landing/company sites: preserve first viewport, hero role, brand/nav/CTA labels, section order, next-section preview, and signature imagery.
• Product/SaaS pages: preserve product mockups, workflow diagrams, feature strips, proof elements, and brand treatment.
• Dashboards/tools: preserve density, sidebars, headers, tables, tabs, timelines, charts, maps, row counts, and selected/detail behavior. Do not turn table-driven concepts into card grids.
• Canvas/editor tools: preserve default zoom/pan, canvas/document text scale, chrome density, toolbars, sidebars, inspector controls, layer rows, status bars, command surfaces, and autosaved/seed-state behavior.
• Timeline/planning tools: preserve grid/time-axis anatomy, row spans, event density, status rails, and command-center fit.
• Clone-like interfaces: preserve the recognizable skeleton before adding polish. Do not add marketing heroes or custom navigation that breaks the product type.
• Games: preserve the art direction with Image Gen assets for sprites, tiles/platforms, collectibles, hazards, goals/checkpoints, props, and background/parallax layers. Verify assets load, scale, animate or swap state correctly, align with collision geometry, and support movement, action/jump/drag behavior, scoring, hazards, and restart.
• Media surfaces: verify real media load, duration, play/pause, seek/progress, and visible frame changes.
• Forms/booking/purchase/restaurant flows: verify the main transaction path and confirmation state.

Final Response

Include the accepted concept path, rendered screenshot method, Browser/IAB verification method or Playwright fallback reason, view_image inspection of the accepted concept and latest implementation screenshot, native-size viewport checked or blocker, at least five inspected comparison points, above-the-fold copy diff result, remaining intentional deviations, and an explicit statement that the implementation was faithfully verified against the accepted design. Also include material mismatches fixed and core interaction path verified. If no material mismatches remain, say so directly.

Frontend Testing Debugging

Invocation Contract

This skill should work from normal user prompts. Do not require the user to spell out Browser routing, screenshots, report shape, or fallback policy.

Use this skill when the user asks to use the Build Web Apps plugin, web dev plugin, frontend dev plugin, or frontend testing/debugging skill for a rendered frontend change, test, or bug investigation.

Examples that should trigger this full workflow:

• please make an improvement to the web dashboard transaction search area and use the web dev plugin
• use the frontend dev plugin to polish this dashboard
• debug this UI with the Build Web Apps plugin
• test this localhost app and fix the broken interaction

From a brief prompt, infer the target surface from the repo, currently open app/browser URL, nearby files, or running dev server. If the target URL is unclear, inspect the repo scripts and running local ports before asking the user.

For any code change to a rendered frontend surface, do the validation loop by default:

1. Identify the target flow.
2. Choose the Browser path below.
3. Make the smallest useful edit.
4. Validate the rendered behavior.
5. Reply with the QA final response report.

Choose The Browser Path

First classify Browser availability:

• Available: the Browser plugin and its browser skill are listed in the session. Read and follow that skill before any browser action.
• Absent: the Browser plugin or browser skill is not listed. Use regular Playwright and record Browser plugin not available.
• Invocation failed: Browser appears available, but the skill/runtime, Node REPL JavaScript setup, tab acquisition, or navigation fails. Treat this as a Browser-path blocker.

Do not use regular Playwright, external Chrome, or shell open first when Browser is available.

Only switch from a failed Browser invocation to regular Playwright if the user already allowed fallback or the task explicitly permits non-Browser validation. In that case, report the exact Browser failure and the fallback decision.

Target Flow

Before browser validation, define the target flow in one sentence:

The flow under test is: [entry route] -> [user action or state] -> [expected rendered result].

If the user asked for general smoke testing, use:

The flow under test is: app loads -> first meaningful screen renders -> primary visible controls respond without runtime errors.

Browser Plugin Loop

Run Browser commands through the Node REPL JavaScript tool described by the Browser skill. Do not invent a separate browser setup path. Keep using the same tab binding unless the Browser skill says otherwise.

Required sequence:

1. Load the Browser runtime exactly as the Browser skill instructs.
2. Name the session with agent.browser.nameSession("...").
3. Acquire a tab with agent.browser.tabs.selected() or agent.browser.tabs.new().
4. Navigate with tab.goto(url).
5. Run the required checks below.
6. Interact with scoped tab.playwright locators or Browser skill interaction APIs.
7. After edits, call await tab.reload(), then repeat the checks and the failing interaction.

For each UI-changing action, collect the cheapest proof that the next state is correct: fresh DOM snapshot, visible text/state, URL change, focused control, toast, modal, screenshot, or console log.

Required Browser Checks

Run these checks before claiming the rendered app works:

1. Page identity: await tab.url() and await tab.title() match the intended page.
2. Not blank: await tab.playwright.domSnapshot() contains meaningful app content, not an empty shell.
3. No framework overlay: the snapshot or screenshot does not show a Next.js, Vite, Webpack, or framework error overlay.
4. Console health: await tab.dev.logs({ levels: ["error", "warn"], limit: 50 }) has no relevant app errors, or each relevant error is explained.
5. Screenshot evidence: await display(await tab.playwright.screenshot({ fullPage: false })) supports visual claims.
6. Interaction proof: at least one target-flow interaction is exercised and followed by a state check.

For visual work, add desktop plus one mobile-sized viewport when practical. For reference-driven work, keep a short mismatch ledger: reference evidence, rendered evidence, fix or intentional deviation.

Playwright Loop

Use this branch when Browser is not available, or when the user has allowed fallback after a Browser invocation failure.

Use this order:

1. Find scripts in package.json.
2. Start the app with the repo's package manager and keep the requested host exact.
3. Prefer the repo's e2e script if present.
4. Otherwise run pnpm exec playwright test or the package-manager equivalent when Playwright is configured.
5. If there is no project Playwright workflow, verify Playwright with pnpm exec playwright --version, then capture a screenshot with pnpm exec playwright screenshot <url> /tmp/frontend-check.png.
6. For deeper debugging, create a small temporary Playwright script outside committed source that opens the URL, captures console errors, screenshots, and runs the target interaction.
7. After edits, rerun the same command or script.

Do not install new browser dependencies unless the task requires it and the user has allowed dependency changes.

Validation Checklist

• Keep the requested host exact.
• Verify controls update real UI state.
• Check the first viewport before scrolling, plus desktop and one mobile-sized viewport when practical.
• Look for clipping, overlap, unreadable text, wrapping, layout shift, missing assets, z-index issues, scroll traps, stale loading, and broken states.
• For reference-driven work, compare the rendered screenshot against the reference and keep a short mismatch ledger.
• A passing build is not enough when rendered validation was requested.

QA Final Response Report

For any non-trivial rendered UI validation run, write the final response like a QA engineer verifying a code change. The response should make it easy for the user or PR reviewer to understand what changed, what was tested, what evidence proves it, and what remains untested.

Use this shape:

• Summary: one or two bullets explaining the user-visible change and whether QA passed.
• Environment: URL, viewport(s), Browser availability classification, and fallback reason if Playwright was used.
• Changes Verified: files or surfaces changed, plus the specific user-facing behavior expected.
• Checks: a pass/fail table for page identity, blank-page check, framework overlay check, console health, screenshot evidence, and interaction proof.
• Interaction Loop: exact interaction path tested, including the control or workflow exercised and the observed state change.
• Evidence: describe the screenshot evidence in the QA sections, then place the actual screenshots together at the end of the response as consecutive images. Include as many screenshots as are useful to prove the relevant before, after, interaction, responsive, error, or fixed states.
• Commands / Browser APIs: list the key command and Browser API sequence used, without dumping noisy logs.
• Remaining Risk: untested viewports, flows, browsers, data states, or known limitations.

If issues were found, lead with Findings before the summary. Each finding should include what the user sees, reproduction steps, screenshot/DOM/console evidence, likely owner or file when known, and the fix made or remaining blocker.

When using Browser screenshots that should be shown to the user, emit or display the screenshot through the Browser runtime so it can be referenced in chat. When using Playwright screenshots, save them outside the repo and reference them in chat. Include multiple screenshots when they help verify distinct states or flows.

Do not interleave screenshots throughout the written report. Put a short Screenshots section at the very end, and make it a consecutive image gallery with one image per line. Add short labels only when they clarify the state, for example Before, After, Filtered results, Empty state, or Mobile.

Do not create separate HTML reports by default. Only create a standalone report file when the user explicitly asks for one, and write it outside the repo unless the user explicitly asks for committed artifacts.

Do not write reports, screenshots, traces, or temporary scripts into the repo unless the user explicitly asks for committed artifacts.

Related Skills

• Use frontend-app-builder when the task is design creation, redesign, or fidelity to an accepted concept.
• Use react-best-practices after meaningful React/Next.js component edits.
• Do not invoke Image Gen for ordinary debugging. Use it only when the task requires creating or revising visual assets, or when frontend-app-builder is already driving a concept-to-implementation fidelity loop.

Final Response

Use the QA final response report format above. Keep it concise, but include enough concrete evidence that a PR reviewer can trust the validation without rerunning it immediately.

If Browser was absent and Playwright was used, end by suggesting that the user install the Browser plugin for a better frontend development experience with in-app navigation, screenshots, DOM snapshots, console logs, and interaction validation.

Vercel React Best Practices

Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 64 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new React components or Next.js pages
• Implementing data fetching (client or server-side)
• Reviewing code for performance issues
• Refactoring existing React/Next.js code
• Optimizing bundle size or load times

Rule Categories by Priority

Quick Reference

1. Eliminating Waterfalls (CRITICAL)

• async-defer-await - Move await into branches where actually used
• async-parallel - Use Promise.all() for independent operations
• async-dependencies - Use better-all for partial dependencies
• async-api-routes - Start promises early, await late in API routes
• async-suspense-boundaries - Use Suspense to stream content

2. Bundle Size Optimization (CRITICAL)

• bundle-barrel-imports - Import directly, avoid barrel files
• bundle-dynamic-imports - Use next/dynamic for heavy components
• bundle-defer-third-party - Load analytics/logging after hydration
• bundle-conditional - Load modules only when feature is activated
• bundle-preload - Preload on hover/focus for perceived speed

3. Server-Side Performance (HIGH)

• server-auth-actions - Authenticate server actions like API routes
• server-cache-react - Use React.cache() for per-request deduplication
• server-cache-lru - Use LRU cache for cross-request caching
• server-dedup-props - Avoid duplicate serialization in RSC props
• server-hoist-static-io - Hoist static I/O (fonts, logos) to module level
• server-serialization - Minimize data passed to client components
• server-parallel-fetching - Restructure components to parallelize fetches
• server-after-nonblocking - Use after() for non-blocking operations

4. Client-Side Data Fetching (MEDIUM-HIGH)

• client-swr-dedup - Use SWR for automatic request deduplication
• client-event-listeners - Deduplicate global event listeners
• client-passive-event-listeners - Use passive listeners for scroll
• client-localstorage-schema - Version and minimize localStorage data

5. Re-render Optimization (MEDIUM)

• rerender-defer-reads - Don't subscribe to state only used in callbacks
• rerender-memo - Extract expensive work into memoized components
• rerender-memo-with-default-value - Hoist default non-primitive props
• rerender-dependencies - Use primitive dependencies in effects
• rerender-derived-state - Subscribe to derived booleans, not raw values
• rerender-derived-state-no-effect - Derive state during render, not effects
• rerender-functional-setstate - Use functional setState for stable callbacks
• rerender-lazy-state-init - Pass function to useState for expensive values
• rerender-simple-expression-in-memo - Avoid memo for simple primitives
• rerender-split-combined-hooks - Split hooks with independent dependencies
• rerender-move-effect-to-event - Put interaction logic in event handlers
• rerender-transitions - Use startTransition for non-urgent updates
• rerender-use-deferred-value - Defer expensive renders to keep input responsive
• rerender-use-ref-transient-values - Use refs for transient frequent values
• rerender-no-inline-components - Don't define components inside components

6. Rendering Performance (MEDIUM)

• rendering-animate-svg-wrapper - Animate div wrapper, not SVG element
• rendering-content-visibility - Use content-visibility for long lists
• rendering-hoist-jsx - Extract static JSX outside components
• rendering-svg-precision - Reduce SVG coordinate precision
• rendering-hydration-no-flicker - Use inline script for client-only data
• rendering-hydration-suppress-warning - Suppress expected mismatches
• rendering-activity - Use Activity component for show/hide
• rendering-conditional-render - Use ternary, not && for conditionals
• rendering-usetransition-loading - Prefer useTransition for loading state
• rendering-resource-hints - Use React DOM resource hints for preloading
• rendering-script-defer-async - Use defer or async on script tags

7. JavaScript Performance (LOW-MEDIUM)

• js-batch-dom-css - Group CSS changes via classes or cssText
• js-index-maps - Build Map for repeated lookups
• js-cache-property-access - Cache object properties in loops
• js-cache-function-results - Cache function results in module-level Map
• js-cache-storage - Cache localStorage/sessionStorage reads
• js-combine-iterations - Combine multiple filter/map into one loop
• js-length-check-first - Check array length before expensive comparison
• js-early-exit - Return early from functions
• js-hoist-regexp - Hoist RegExp creation outside loops
• js-min-max-loop - Use loop for min/max instead of sort
• js-set-map-lookups - Use Set/Map for O(1) lookups
• js-tosorted-immutable - Use toSorted() for immutability
• js-flatmap-filter - Use flatMap to map and filter in one pass

8. Advanced Patterns (LOW)

• advanced-event-handler-refs - Store event handlers in refs
• advanced-init-once - Initialize app once per app load
• advanced-use-latest - useLatest for stable callback refs

How to Use

Read individual rule files for detailed explanations and code examples:

rules/async-parallel.md
rules/bundle-barrel-imports.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

shadcn/ui

A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.

IMPORTANT: Run all CLI commands using the project's package runner: npx shadcn@latest, pnpm dlx shadcn@latest, or bunx --bun shadcn@latest — based on the project's packageManager. Examples below use npx shadcn@latest but substitute the correct runner for the project.

Current Project Context

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "No shadcn project found. Run shadcn init first."}'`

The JSON above contains the project config and installed components. Use npx shadcn@latest docs <component> to get documentation and example URLs for any component.

Principles

1. Use existing components first. Use npx shadcn@latest search to check registries before writing custom UI. Check community registries too.
2. Compose, don't reinvent. Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
3. Use built-in variants before custom styles. variant="outline", size="sm", etc.
4. Use semantic colors. bg-primary, text-muted-foreground — never raw values like bg-blue-500.

Critical Rules

These rules are always enforced. Each links to a file with Incorrect/Correct code pairs.

Styling & Tailwind → styling.md

• className for layout, not styling. Never override component colors or typography.
• No space-x-* or space-y-*. Use flex with gap-*. For vertical stacks, flex flex-col gap-*.
• Use size-* when width and height are equal. size-10 not w-10 h-10.
• Use truncate shorthand. Not overflow-hidden text-ellipsis whitespace-nowrap.
• No manual dark: color overrides. Use semantic tokens (bg-background, text-muted-foreground).
• Use cn() for conditional classes. Don't write manual template literal ternaries.
• No manual z-index on overlay components. Dialog, Sheet, Popover, etc. handle their own stacking.

Forms & Inputs → forms.md

• Forms use FieldGroup + Field. Never use raw div with space-y-* or grid gap-* for form layout.
• InputGroup uses InputGroupInput/InputGroupTextarea. Never raw Input/Textarea inside InputGroup.
• Buttons inside inputs use InputGroup + InputGroupAddon.
• Option sets (2–7 choices) use ToggleGroup. Don't loop Button with manual active state.
• FieldSet + FieldLegend for grouping related checkboxes/radios. Don't use a div with a heading.
• Field validation uses data-invalid + aria-invalid. data-invalid on Field, aria-invalid on the control. For disabled: data-disabled on Field, disabled on the control.

Component Structure → composition.md

• Items always inside their Group. SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
• Use asChild (radix) or render (base) for custom triggers. Check base field from npx shadcn@latest info. → base-vs-radix.md
• Dialog, Sheet, and Drawer always need a Title. DialogTitle, SheetTitle, DrawerTitle required for accessibility. Use className="sr-only" if visually hidden.
• Use full Card composition. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Don't dump everything in CardContent.
• Button has no isPending/isLoading. Compose with Spinner + data-icon + disabled.
• TabsTrigger must be inside TabsList. Never render triggers directly in Tabs.
• Avatar always needs AvatarFallback. For when the image fails to load.

Use Components, Not Custom Markup → composition.md

• Use existing components before custom markup. Check if a component exists before writing a styled div.
• Callouts use Alert. Don't build custom styled divs.
• Empty states use Empty. Don't build custom empty state markup.
• Toast via sonner. Use toast() from sonner.
• Use Separator instead of <hr> or <div className="border-t">.
• Use Skeleton for loading placeholders. No custom animate-pulse divs.
• Use Badge instead of custom styled spans.

Icons → icons.md

• Icons in Button use data-icon. data-icon="inline-start" or data-icon="inline-end" on the icon.
• No sizing classes on icons inside components. Components handle icon sizing via CSS. No size-4 or w-4 h-4.
• Pass icons as objects, not string keys. icon={CheckIcon}, not a string lookup.

CLI

• Never decode or fetch preset codes manually. Pass them directly to npx shadcn@latest init --preset <code>.

Key Patterns

These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above.

// Form layout: FieldGroup + Field, not div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validation: data-invalid on Field, aria-invalid on the control.
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Invalid email.</FieldDescription>
</Field>

// Icons in buttons: data-icon, no sizing classes.
<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>

// Spacing: gap-*, not space-y-*.
<div className="flex flex-col gap-4">  // correct
<div className="space-y-4">           // wrong

// Equal dimensions: size-*, not w-* h-*.
<Avatar className="size-10">   // correct
<Avatar className="w-10 h-10"> // wrong

// Status colors: Badge variants or semantic tokens, not raw colors.
<Badge variant="secondary">+20.1%</Badge>    // correct
<span className="text-emerald-600">+20.1%</span> // wrong

Component Selection

Key Fields

The injected project context contains these key fields:

• aliases → use the actual alias prefix for imports (e.g. @/, ~/), never hardcode.
• isRSC → when true, components using useState, useEffect, event handlers, or browser APIs need "use client" at the top of the file. Always reference this field when advising on the directive.
• tailwindVersion → "v4" uses @theme inline blocks; "v3" uses tailwind.config.js.
• tailwindCssFile → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
• style → component visual treatment (e.g. nova, vega).
• base → primitive library (radix or base). Affects component APIs and available props.
• iconLibrary → determines icon imports. Use lucide-react for lucide, @tabler/icons-react for tabler, etc. Never assume lucide-react.
• resolvedPaths → exact file-system destinations for components, utils, hooks, etc.
• framework → routing and file conventions (e.g. Next.js App Router vs Vite SPA).
• packageManager → use this for any non-shadcn dependency installs (e.g. pnpm add date-fns vs npm install date-fns).

See cli.md — info command for the full field reference.

Component Docs, Examples, and Usage

Run npx shadcn@latest docs <component> to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.

npx shadcn@latest docs button dialog select

When creating, fixing, debugging, or using a component, always run npx shadcn@latest docs and fetch the URLs first. This ensures you're working with the correct API and usage patterns rather than guessing.

Workflow

1. Get project context — already injected above. Run npx shadcn@latest info again if you need to refresh.
2. Check installed components first — before running add, always check the components list from project context or list the resolvedPaths.ui directory. Don't import components that haven't been added, and don't re-add ones already installed.
3. Find components — npx shadcn@latest search.
4. Get docs and examples — run npx shadcn@latest docs <component> to get URLs, then fetch them. Use npx shadcn@latest view to browse registry items you haven't installed. To preview changes to installed components, use npx shadcn@latest add --diff.
5. Install or update — npx shadcn@latest add. When updating existing components, use --dry-run and --diff to preview changes first (see Updating Components below).
6. Fix imports in third-party components — After adding components from community registries (e.g. @bundui, @magicui), check the added non-UI files for hardcoded import paths like @/components/ui/.... These won't match the project's actual aliases. Use npx shadcn@latest info to get the correct ui alias (e.g. @workspace/ui/components) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
7. Review added components — After adding a component or block from any registry, always read the added files and verify they are correct. Check for missing sub-components (e.g. SelectItem without SelectGroup), missing imports, incorrect composition, or violations of the Critical Rules. Also replace any icon imports with the project's iconLibrary from the project context (e.g. if the registry item uses lucide-react but the project uses hugeicons, swap the imports and icon names accordingly). Fix all issues before moving on.
8. Registry must be explicit — When the user asks to add a block or component, do not guess the registry. If no registry is specified (e.g. user says "add a login block" without specifying @shadcn, @tailark, etc.), ask which registry to use. Never default to a registry on behalf of the user.
9. Switching presets — Ask the user first: reinstall, merge, or skip?
   • Reinstall: npx shadcn@latest init --preset <code> --force --reinstall. Overwrites all components.
   • Merge: npx shadcn@latest init --preset <code> --force --no-reinstall, then run npx shadcn@latest info to list installed components, then for each installed component use --dry-run and --diff to smart merge it individually.
   • Skip: npx shadcn@latest init --preset <code> --force --no-reinstall. Only updates config and CSS, leaves components as-is.
   • Important: Always run preset commands inside the user's project directory. The CLI automatically preserves the current base (base vs radix) from components.json. If you must use a scratch/temp directory (e.g. for --dry-run comparisons), pass --base <current-base> explicitly — preset codes do not encode the base.

Updating Components

When the user asks to update a component from upstream while keeping their local changes, use --dry-run and --diff to intelligently merge. NEVER fetch raw files from GitHub manually — always use the CLI.

1. Run npx shadcn@latest add <component> --dry-run to see all files that would be affected.
2. For each file, run npx shadcn@latest add <component> --diff <file> to see what changed upstream vs local.
3. Decide per file based on the diff:
   • No local changes → safe to overwrite.
   • Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
   • User says "just update everything" → use --overwrite, but confirm first.
4. Never use --overwrite without the user's explicit approval.

Quick Reference

# Create a new project.
npx shadcn@latest init --name my-app --preset base-nova
npx shadcn@latest init --name my-app --preset a2r6bw --template vite

# Create a monorepo project.
npx shadcn@latest init --name my-app --preset base-nova --monorepo
npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo

# Initialize existing project.
npx shadcn@latest init --preset base-nova
npx shadcn@latest init --defaults  # shortcut: --template=next --preset=base-nova

# Add components.
npx shadcn@latest add button card dialog
npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add --all

# Preview changes before adding/updating.
npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff button.tsx
npx shadcn@latest add @acme/form --view button.tsx

# Search registries.
npx shadcn@latest search @shadcn -q "sidebar"
npx shadcn@latest search @tailark -q "stats"

# Get component docs and example URLs.
npx shadcn@latest docs button dialog select

# View registry item details (for items not yet installed).
npx shadcn@latest view @shadcn/button

Named presets: base-nova, radix-nova Templates: next, vite, start, react-router, astro (all support --monorepo) and laravel (not supported for monorepo) Preset codes: Base62 strings starting with a (e.g. a2r6bw), from ui.shadcn.com.

Detailed References

• rules/forms.md — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
• rules/composition.md — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
• rules/icons.md — data-icon, icon sizing, passing icons as objects
• rules/styling.md — Semantic colors, variants, className, spacing, size, truncate, dark mode, cn(), z-index
• rules/base-vs-radix.md — asChild vs render, Select, ToggleGroup, Slider, Accordion
• cli.md — Commands, flags, presets, templates
• customization.md — Theming, CSS variables, extending components

Supabase Postgres Best Practices

Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.

When to Apply

Reference these guidelines when:

• Writing SQL queries or designing schemas
• Implementing indexes or query optimization
• Reviewing database performance issues
• Configuring connection pooling or scaling
• Optimizing for Postgres-specific features
• Working with Row-Level Security (RLS)

Rule Categories by Priority

How to Use

Read individual rule files for detailed explanations and SQL examples:

references/query-missing-indexes.md
references/schema-partial-indexes.md
references/_sections.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect SQL example with explanation
• Correct SQL example with explanation
• Optional EXPLAIN output or metrics
• Additional context and references
• Supabase-specific notes (when applicable)

References

• https://www.postgresql.org/docs/current/
• https://supabase.com/docs
• https://wiki.postgresql.org/wiki/Performance_Optimization
• https://supabase.com/docs/guides/database/overview
• https://supabase.com/docs/guides/auth/row-level-security

Canva Branded Presentation

Overview

Use this skill to turn a brief, outline, or existing Canva content into a branded presentation. Gather the source content first, choose the right brand kit, and generate presentation candidates before creating the editable deck.

Preferred Deliverables

• A clear presentation brief with title, scope, key messages, and a narrative arc.
• A slide plan with concrete titles, goals, bullets, and visual guidance.
• A new editable Canva presentation created from the user's preferred candidate.

Workflow

1. Identify the content source before generating. Accept direct text, a Canva design link, or a Canva document/design name that can be found through search.
2. Read the source content when it lives in Canva. Use the available Canva search and editing tools to locate the design, open it, and extract the material that should drive the deck.
3. List the available brand kits. If there is only one, use it automatically. If there are multiple, ask the user to choose before generating.
4. Build a strong generation prompt. Include a working title, topic, key messages, visual style, story arc, and a slide-by-slide plan.
5. Generate presentation candidates in Canva and show the options to the user before creating the final design.
6. Create the editable presentation from the selected candidate and return the Canva link.

Write Safety

• Keep the original source design untouched unless the user explicitly asks to modify it.
• If multiple matching source designs or brand kits appear, identify the exact one before generating.
• Preserve specific names, dates, metrics, and claims from the source content unless the user asks to change them.
• If the brief is sparse, expand it thoughtfully, but call out major assumptions that shape the narrative.

Output Conventions

• When helpful, summarize the deck direction before generation: title, audience, key message, and slide count.
• For larger decks, present a concise slide plan before or alongside candidate generation.
• When showing results, distinguish clearly between generated candidates and the final editable deck.
• Return the final Canva design link once the chosen candidate has been created.

Example Requests

• "Create a branded presentation from this launch outline."
• "Turn this Canva doc into a polished deck using our brand kit."
• "Make an on-brand sales presentation from this brief."
• "Generate a presentation from this Canva design link."

Light Fallback

If the source design or brand kit cannot be found, say that Canva access may be unavailable or pointed at the wrong account and ask the user to reconnect or identify the right design or brand kit.

Canva Resize For Social Media

Overview

Use this skill to take one Canva design and create a multi-platform set of resized variants. Identify the source design, generate the requested social formats, export each version, and present the results in a scan-friendly way.

Preferred Deliverables

• A confirmed source design with the right title and edit context.
• Resized variants for the requested social platforms.
• Direct export links and Canva edit links for each successful output.

Workflow

1. Identify the source design from a design ID, Canva URL, design name, or the current conversation context.
2. Confirm the source design exists and is accessible before starting any resize work.
3. Resize the design into the standard target formats for Facebook post, Facebook story, Instagram post, Instagram story, and LinkedIn post. Run independent resize operations in parallel when the tool flow supports it.
4. Continue with the formats that succeed even if one or more resize attempts fail.
5. Export each successful resized design as a high-quality PNG and collect the download links.
6. Present the finished set grouped by platform, including both the PNG download link and the Canva edit link.

Write Safety

• Keep the original design unchanged and work from resized copies.
• If a name search returns multiple designs, identify the right one before resizing.
• Use exact target dimensions for each platform rather than approximations.
• Report partial failures clearly instead of hiding them behind a generic success message.

Output Conventions

• Lead with a short summary of which formats were created successfully.
• List each platform separately with its dimensions, export link, and edit link.
• Mention when two outputs share the same dimensions, such as Facebook Story and Instagram Story.
• If some formats fail, separate successes from failures so the user can act quickly.

Example Requests

• "Resize this Canva design for Facebook, Instagram, and LinkedIn."
• "Make all the social versions of this campaign graphic."
• "Take my flyer design and export all the social post sizes."
• "Resize this Canva link for every major social format."

Light Fallback

If the source design cannot be found or exported, say that Canva access may be unavailable or scoped to the wrong design and ask the user to reconnect or identify the exact design to use.

Canva Translate Design

Overview

Use this skill to create a translated copy of an existing Canva design. Find the source design, duplicate it safely, translate text elements into the target language, and save the localized version only after the user approves.

Preferred Deliverables

• A translated copy of the original Canva design in the requested language.
• A concise note about any text-length or layout risks introduced by translation.
• A final Canva link to the saved translated design.

Workflow

1. Locate the design from a Canva URL or by searching for its title. If multiple matches appear, identify the right design before continuing.
2. Create a copy of the design so the original stays untouched.
3. Start an editing transaction on the copied design and gather the text elements that need translation.
4. Translate each text element into the requested language while preserving meaning, line breaks, and important formatting cues.
5. Apply the translated text in a single batched edit when possible, and update the design title to reflect the target language.
6. Show the translated preview or summarize the pending result, ask for approval to save, then commit the transaction and return the new design link.

Write Safety

• Always work on a copy rather than the original design.
• Preserve proper nouns, product names, and brand language unless the user asks for deeper localization.
• Warn the user when translation is likely to expand text enough to require layout cleanup in Canva.
• Treat the final save as an explicit action that follows user approval.

Output Conventions

• State the source design and target language up front.
• Call out any translation assumptions, especially around brand names or ambiguous phrases.
• Mention likely layout risks before the final save when text expansion is significant.
• Return the saved translated design link after commit.

Example Requests

• "Translate my Canva poster into Spanish."
• "Make a French version of this design."
• "Localize this Canva design for German."
• "Create a Portuguese copy of this brochure."

Light Fallback

If the source design cannot be found or opened for editing, say that Canva access may be unavailable or pointed at the wrong account and ask the user to reconnect or identify the exact design to translate.

Initialize Cinema Project

This skill turns an ordinary local folder into an anybox for cinema project. The project folder is the source of truth. AnyBox remains the controller; external browser or canvas UIs are only presentation and interaction surfaces over this local project.

Hard Rules

• Use only generic shell commands and normal file creation/editing tools.
• Do not call any custom cinema_*, video_workspace_*, or provider-specific project initialization tools.
• Do not require model deployment. This product assumes users bring their own provider API keys later.
• Do not store API keys inside the project folder during initialization.
• Do not overwrite existing user files. If a file already exists, inspect it and repair only clearly missing Cinema metadata when it is safe.
• Keep the process idempotent: running this skill again should not duplicate folders, duplicate manifest sections, or destroy project data.

Project Root

Use the user-specified folder as the project root. If no folder is specified, use the current working directory.

Before writing anything, run generic inspection commands:

pwd
ls -la
test -e .anybox-cinema/project.json && echo "cinema-project: exists" || echo "cinema-project: missing"

If the current folder is obviously the wrong location, stop and ask the user for the intended project folder. Otherwise continue.

Target Structure

Create this structure for a new project, leaving placeholders where product details are not final:

<project-root>/
  .anybox-cinema/
    project.json
    providers.json
    canvas.json
    events.jsonl
    README.md
  scripts/
    README.md
  assets/
    README.md
  references/
    README.md
  prompts/
    README.md
  generated/
    README.md
  renders/
    README.md
  exports/
    README.md

Directory intent:

• .anybox-cinema/: project metadata owned by anybox for cinema.
• assets/: user-owned source media such as images, clips, audio, and fonts.
• references/: mood boards, reference shots, style frames, and research notes.
• prompts/: reusable prompt drafts and prompt experiments.
• generated/: raw AI generation outputs before editorial selection.
• renders/: assembled previews, cuts, and intermediate renders.
• exports/: final deliverables.
• scripts/: optional local helper scripts. Leave empty unless the user asks for automation.

New Project Workflow

1. Confirm the project root with pwd and inspect existing files with ls -la.
2. If .anybox-cinema/project.json exists, treat the folder as an existing Cinema project and follow the repair workflow.
3. Create the target directories with mkdir -p.
4. Create missing metadata files using normal file creation/editing tools. If only shell is available, use shell heredocs carefully and only for files that do not already exist.
5. Add exactly one initialization event to .anybox-cinema/events.jsonl when creating a new project.
6. Report the created files and the next useful action.

Recommended generic shell setup:

mkdir -p .anybox-cinema scripts assets references prompts generated renders exports
PROJECT_ID="$(uuidgen 2>/dev/null | tr '[:upper:]' '[:lower:]' || date -u +cinema-%Y%m%d%H%M%S)"
NOW="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
PROJECT_NAME="$(basename "$PWD")"

Metadata Templates

Use these templates for missing files. Replace placeholder values such as <project-id>, <project-name>, and <iso-time> with real values.

.anybox-cinema/project.json

{
  "schemaVersion": 1,
  "projectType": "anybox-for-cinema",
  "id": "<project-id>",
  "name": "<project-name>",
  "createdAt": "<iso-time>",
  "updatedAt": "<iso-time>",
  "status": "draft",
  "description": "",
  "language": "",
  "format": {
    "aspectRatio": "16:9",
    "durationSeconds": null,
    "fps": 24,
    "resolution": ""
  },
  "paths": {
    "assets": "assets",
    "references": "references",
    "prompts": "prompts",
    "generated": "generated",
    "renders": "renders",
    "exports": "exports"
  },
  "ui": {
    "preferredSurface": "external-browser",
    "canvasStyle": "node-canvas",
    "controller": "anybox"
  },
  "placeholders": {
    "story": "",
    "visualStyle": "",
    "targetProviders": []
  }
}

.anybox-cinema/providers.json

This file records provider slots only. Do not write secrets here.

{
  "schemaVersion": 1,
  "policy": "bring-your-own-key",
  "secretStorage": "anybox-managed",
  "providers": [],
  "notes": [
    "Provider credentials are configured in AnyBox or the plugin connector layer, not in this project file.",
    "This file may later store non-secret routing preferences, model labels, or project-level provider presets."
  ]
}

.anybox-cinema/canvas.json

The canvas is node-first and should be compatible with an Updream-like workspace: dark infinite canvas, draggable cards, connection lines, context menu, minimap, and floating toolbar.

{
  "schemaVersion": 1,
  "canvasType": "node-canvas",
  "viewport": {
    "x": 0,
    "y": 0,
    "zoom": 1
  },
  "nodes": [
    {
      "id": "node-story-brief",
      "type": "text",
      "title": "Story Brief",
      "position": {
        "x": 80,
        "y": 80
      },
      "size": {
        "width": 360,
        "height": 220
      },
      "data": {
        "text": "",
        "placeholder": "Write the film idea, theme, references, and constraints here."
      }
    },
    {
      "id": "node-agent-director",
      "type": "agent",
      "title": "Director Agent",
      "position": {
        "x": 520,
        "y": 120
      },
      "size": {
        "width": 360,
        "height": 220
      },
      "data": {
        "role": "director",
        "placeholder": "Use AnyBox Agent to plan shots, prompts, and generation tasks."
      }
    }
  ],
  "edges": [],
  "nodeTypes": [
    "text",
    "image",
    "video",
    "audio",
    "shot",
    "agent",
    "generation-task",
    "output"
  ]
}

.anybox-cinema/events.jsonl

For a new project, create the file and append one JSON line:

{"time":"<iso-time>","type":"project.initialized","actor":"anybox","message":"Initialized anybox for cinema project."}

For an existing project, append repair events only when a repair actually changed files.

README Files

Each directory may contain a short README.md explaining its purpose. Keep these files minimal and do not add marketing copy.

Suggested .anybox-cinema/README.md:

# anybox for cinema

This folder stores local metadata for an anybox for cinema project.

AnyBox is the controller. Browser or canvas interfaces should treat this folder as project state and should not store provider secrets here.

Suggested media directory README pattern:

# <Directory Name>

Placeholder for project files. This directory is managed by the user and AnyBox.

Existing Project Repair Workflow

If .anybox-cinema/project.json exists:

1. Read .anybox-cinema/project.json, .anybox-cinema/providers.json, and .anybox-cinema/canvas.json if present.

2. Validate JSON with a generic parser if one is available, for example:

   node -e "JSON.parse(require('fs').readFileSync('.anybox-cinema/project.json', 'utf8')); console.log('project.json: ok')"
   

3. If JSON is invalid, do not overwrite it automatically. Report the invalid file and ask before replacing or rewriting it.

4. If metadata files are missing, recreate only the missing files.

5. If directories are missing, recreate them with mkdir -p.

6. Append a project.repaired event only when files or directories changed.

Completion Response

After initialization or repair, tell the user:

• The project root.
• Whether it was newly initialized or repaired.
• The important files created or changed.
• The next recommended step, usually one of:
  • write a project brief in .anybox-cinema/project.json or the Story Brief canvas node;
  • add reference materials to references/;
  • add source media to assets/;
  • begin designing the external node canvas UI against .anybox-cinema/canvas.json.

CircleCI Builds

Overview

Use this skill to turn failing CircleCI pipelines into actionable fixes with clear evidence. Prioritize fast root-cause isolation, minimal safe patches, and explicit validation criteria.

Read references/transient-vs-deterministic.md when deciding whether a failure should be fixed in code/config, retried, mitigated with rerun behavior, or reported as external/transient. Read ../config/references/test-results-and-splitting.md when the failure involves missing test metadata, flaky test reruns, test splitting, or JUnit XML setup.

Inputs To Gather

• Failing pipeline/workflow/job identifier
• Branch and commit SHA
• First failing step and key log lines
• Whether rerun on same commit reproduces failure

Workflow

1. Identify the primary failing signal.
   • Record the first failing job and step, not every downstream failure.
2. Classify issue type.
   • Config syntax/reference issue
   • Environment/toolchain mismatch
   • Dependency/cache issue
   • Test or build regression
   • External/transient failure
3. Apply the smallest viable fix.
   • Patch only files tied to confirmed root cause.
   • Keep workaround scope narrow.
4. Validate.
   • Run highest-signal local checks when possible.
   • Define expected CircleCI success signals for the rerun.
5. Report residual risk.
   • Call out unverified assumptions and likely follow-up checks.

Guardrails

• Do not hide deterministic failures with blanket retries.
• Avoid mixing unrelated refactors into incident fixes.
• Treat external service outages as report-and-mitigate unless user asks for deeper redesign.
• Keep confidence levels explicit when logs are incomplete.
• Do not recommend automatic reruns or flaky-test workflows until the failure is classified as plausibly transient.

Output Contract

Provide:

1. Failure summary (pipeline/workflow/job/step).
2. Root-cause hypothesis with confidence.
3. Applied changes with file list.
4. Validation plan and expected pass signal.
5. Remaining risk.

Chunk

Overview

Use this skill to choose the best Chunk workflow (UI or CLI), then execute it with clear prechecks and safe defaults. Keep responses action-oriented and grounded in verified commands and setup requirements.

Workflow

1. Classify the request path.

• Use UI path for org setup, model-provider onboarding, fix buttons, or environment selection in the CircleCI app.
• Use CLI path for terminal-based project setup, validation hooks, prompt/context generation, sandbox operations, or scripted task execution.
• Use mixed path when users want UI setup plus CLI execution in the same flow.

2. Gather minimum context.

• Confirm repository/project, branch, and whether GitHub integration is in place.
• Confirm whether the user is using CircleCI-managed model provider or bring-your-own keys.
• For CLI operations, confirm local OS compatibility and required tokens/auth.

3. Execute using the matching reference.

• For UI/setup flows, load chunk-ui.md.
• For CLI flows, load chunk-cli.md.

4. Close with verification.

• State what was configured or run, what remains blocked, and the next safest command or UI action.

Guardrails

• Treat Chunk features as beta unless the user confirms otherwise.
• Never expose or log secret values (API keys, tokens, bearer credentials).
• Do not invent chunk subcommands or flags; stick to documented command families.
• If sandbox features are requested, call out private preview status and any access gate.
• If a task depends on org-level prerequisites (GitHub App install, org toggles, contexts), verify those first.

Reference Map

• chunk-ui.md: CircleCI app setup, provider onboarding, fix buttons, environment file/setup, and operational troubleshooting.
• chunk-cli.md: Installation, command map, quick-start flows, auth/env variables, and platform constraints.

Output Contract

Provide:

1. Path chosen (UI, CLI, or mixed) and why.
2. Steps executed with exact command/UI actions.
3. Required prerequisites not yet met.
4. Concrete next action to finish the user’s goal.

CircleCI CLI

Overview

Use this skill when the fastest path is CircleCI CLI-driven operations rather than editing config first. Prioritize safe, read-first diagnostics, then run targeted mutating commands only after confirming scope.

Inputs To Gather

• Repository path and target branch
• CircleCI project slug (if needed)
• Whether objective is inspect, rerun, trigger, or validate
• Required token/auth state and org permissions

Workflow

1. Verify CLI and auth state.
   • Confirm circleci is installed and version is available.
   • Confirm token/auth before issuing remote CircleCI commands.
2. Run read-only diagnostics first.
   • Inspect available pipeline/project/trigger state and capture concrete identifiers.
   • Extract first failing scope and step details from supported command output before rerun/trigger actions.
3. Validate config locally when relevant.
   • Run config validation/processing commands before committing risky edits.
4. Run targeted mutation commands.
   • Rerun only required workflow/job scope.
   • Trigger pipelines with explicit parameters and branch context.
5. Report results and next action.
   • Provide exact command results, remaining blockers, and safest follow-up.

Guardrails

• Prefer read-only commands before rerun/trigger/cancel operations.
• Confirm organization/project scope before mutating pipeline state.
• Never print raw secret values from environment variables or tokens.
• If permissions fail, report exact auth/scope gap and safest remediation.
• Respect installed CLI capabilities and avoid inventing commands.
• Do not use circleci api, circleci workflow, or other unavailable legacy commands unless circleci help confirms they exist.

Installed CLI Compatibility

For newer circleci builds that expose domain subcommands (for example pipeline, project, trigger) but not api:

• Verify available commands first with circleci help.
• Use only discovered subcommands from help output.
• Prefer circleci pipeline list|create|run and circleci trigger ... for pipeline operations.
• For cloud job logs, use supported platform tools (CircleCI app/UI or connected CircleCI MCP tooling) if the CLI does not expose a logs command.

Output Contract

Provide:

1. Commands run and purpose.
2. Key outputs (pipeline/workflow/job ids, status, failing step).
3. Actions taken (rerun/trigger/validate) and why.
4. Remaining blockers and next recommended CLI command.

CircleCI Config

Overview

Use this skill to improve CircleCI performance and stability without changing product behavior. Focus on measured bottlenecks first, then implement the smallest safe config changes with clear validation criteria.

Read references/cache-optimization.md when the request involves save_cache, restore_cache, persist_to_workspace, attach_workspace, cache key design, dependency caching, lockfiles, or complaints about low cache hit rates, oversized caches, or wasted persistence steps. Read references/persisting-data.md when the request involves choosing between caches, workspaces, and artifacts, or when data is being moved between jobs inefficiently. Read references/test-results-and-splitting.md when the request involves slow test jobs, parallelism, flaky test visibility, missing JUnit XML, or circleci tests run. Read references/patterns.md when the request involves approvals, branch/tag filters, schedules, deploy flow structure, or environment promotion patterns.

Inputs To Gather

• .yaml and .yml files in .circleci/ and any reusable config fragments
• Current pain points: duration, flakiness, cost, or maintainability
• Baseline metrics: slowest jobs, most frequent retries/failures, queue and run times
• Risk tolerance for structural changes

Workflow

1. Build a baseline.
   • Identify top 1-3 longest jobs and top flaky jobs.
   • Capture before metrics (duration, pass rate, retries).
2. Remove pipeline waste.
   • Eliminate duplicate jobs/workflows.
   • Tighten branch/tag filters and workflow triggers.
3. Improve dependency and artifact flow.
   • Fix cache keys to include deterministic lockfile checks.
   • Use workspaces/artifacts to avoid rebuilding identical outputs.
   • Prefer cache scopes that are narrow, reproducible, and cheap to restore.
4. Apply safe parallelism.
   • Parallelize only proven bottlenecks.
   • Keep fan-out/fan-in readable and deterministic.
5. Validate impact.
   • Define expected metric changes and acceptance criteria before finalizing.

Guardrails

• Prefer configuration fixes before proposing application code changes.
• Do not add blanket retries to hide deterministic failures.
• Preserve deployment safety gates while optimizing build/test stages.
• Keep changes incremental and easy to revert.
• Prefer language-specific cache directories over broad project snapshots.
• Avoid cache keys that rotate every run unless the user explicitly wants effectively write-only caches.

Output Contract

Provide:

1. Baseline bottleneck summary.
2. Proposed or applied config changes with rationale.
3. Expected runtime/reliability impact.
4. Validation plan and rollback note.

CircleCI Smarter Testing

Overview

Beta (Discuss). Create or adjust .circleci/test-suites.yml, wire it into CI, and validate with --doctor until checks pass. Let doctor diagnose YAML, command, JUnit, and testsuite errors before adding extra guidance.

Doctor command (required)

The testsuite CLI uses Bubble Tea and must run with a TTY. When iterating with --doctor, the agent must always run this exact command (substitute the suite name only):

script -q /dev/null circleci run testsuite "<suite name>" --doctor

Do not modify this command: no pipes, tail, redirects, backgrounding, or truncation.

Scope: testsuite setup and validation. Not legacy circleci tests run / timings-only JUnit tuning → circleci-config (test-results-and-splitting.md). Primary doc: Getting started.

Lazy references: read only what the task needs—do not load every reference file up front.

• Runner YAML → references/runners.md (matching section only)
• CI / store_test_results → references/ci-and-junit.md
• TIA, splitting, auto-rerun → references/optional-features.md

Inputs To Gather

• Runner, test root, existing .circleci/config.yml
• Optional: TIA, dynamic splitting, auto-rerun limits
• Hand off: circleci-cli (install/auth/plugin) | circleci-config (JUnit/circleci tests run without testsuite) | circleci-builds (CI fails after doctor-clean config)

Workflow

1. Inspect — runner, layout, existing CI; reuse documented test commands; run testsuite from the test root (no cd in YAML).
2. Baseline — .circleci/test-suites.yml with name, discover, run, outputs.junit (see runners.md).
3. Doctor — run the exact command above; apply its guidance; repeat until pass.
4. Local vs CI — Local needs CLI + testsuite plugin (brew install circleci/tap/circleci-testsuite on macOS; binaries on Linux/WSL). CI uses circleci run testsuite on executors + ci-and-junit.md.
5. Optional features — only if asked; see optional-features.md; doctor after each change.
6. Verify — full circleci run testsuite "<suite name>"; optional TIA/rerun checks per docs.

Guardrails

• Beta unless confirmed otherwise; never skip doctor after editing test-suites.yml.
• No secrets in YAML—use contexts/env vars; document variable names only.
• No local impact JSON in .circleci/; smallest change that passes doctor.
• Do not swap a working testsuite for legacy circleci tests split / circleci tests run unless the user requests migration.

Reference map

• runners.md — test-suites.yml template, Vitest, pytest, pointers for other runners
• ci-and-junit.md — full config.yml, JUnit directory upload
• optional-features.md — TIA, splitting, auto-rerun
• test-results-and-splitting.md — classic test metadata path

Output Contract

Provide:

1. Runner, working directory, files changed, commands run (--doctor and follow-ups).
2. What to commit and open items (beta access, blocked prerequisites).

Cloudflare Agents SDK

Your knowledge of the Agents SDK may be outdated. Prefer retrieval over pre-training for any Agents SDK task.

Retrieval Sources

Fetch current docs from https://github.com/cloudflare/agents/tree/main/docs before implementing.

Cloudflare docs: https://developers.cloudflare.com/agents/

Capabilities

The Agents SDK provides:

• Persistent state - SQLite-backed, auto-synced to clients
• Callable RPC - @callable() methods invoked over WebSocket
• Scheduling - One-time, recurring (scheduleEvery), and cron tasks
• Workflows - Durable multi-step background processing via AgentWorkflow
• MCP integration - Connect to MCP servers or build your own with McpAgent
• Email handling - Receive and reply to emails with secure routing
• Streaming chat - AIChatAgent with resumable streams
• React hooks - useAgent, useAgentChat for client apps

FIRST: Verify Installation

npm ls agents  # Should show agents package

If not installed:

npm install agents

Wrangler Configuration

{
  "durable_objects": {
    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
}

Agent Class

import { Agent, routeAgentRequest, callable } from "agents";

type State = { count: number };

export class Counter extends Agent<Env, State> {
  initialState = { count: 0 };

  // Validation hook - runs before state persists (sync, throwing rejects the update)
  validateStateChange(nextState: State, source: Connection | "server") {
    if (nextState.count < 0) throw new Error("Count cannot be negative");
  }

  // Notification hook - runs after state persists (async, non-blocking)
  onStateUpdate(state: State, source: Connection | "server") {
    console.log("State updated:", state);
  }

  @callable()
  increment() {
    this.setState({ count: this.state.count + 1 });
    return this.state.count;
  }
}

export default {
  fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })
};

Routing

Requests route to /agents/{agent-name}/{instance-name}:

Client: useAgent({ agent: "Counter", name: "user-123" })

Core APIs