add-focus-mode

## Purpose Use this skill when the user wants to create or update an OpenMates focus mode. OpenMates focus modes are user-facing chat modes that temporarily change how a mate thinks and responds for a specific goal. They are not Codex modes, editor modes, OS notification modes, or backend app skills. ## Arguments Parse `$ARGUMENTS` as optional hints: - `appId` — parent OpenMates app directory, such as `web`, `code`, `jobs`, or `study` - `focusId` — runtime focus mode id, snake_case preferred, such as `career_insights` If either value is missing, infer it during discovery or ask during the clarifying rounds. Do not invent a final app or ID without user confirmation. ## Workflow Follow this structure closely. The user expects a deliberate plan-before-build flow with two clarification blocks and a draft review gate. Every clarifying question must include `Recommendation:` with the evidence-based preferred answer and rationale plus `Examples:` with task-specific options or outcomes. If uncertain, recommend the safest reversible default and state the uncertainty. ### Step 1: Check Existing Focus Modes First inspect how focus modes already exist and how the target app is structured. Read or search these paths as relevant: - `docs/architecture/apps/focus-modes.md` - `docs/architecture/apps/focus-modes-implementation.md` - `docs/user-guide/apps/focus-modes.md` - `backend/apps/*/focus_modes/*/SKILL.md` - `backend/apps/{appId}/focus_modes/*/SKILL.md` - `backend/apps/{appId}/app.yml` - `frontend/packages/ui/src/i18n/sources/focus_modes/` - `frontend/packages/ui/src/i18n/sources/app_focus_modes/` - `frontend/apps/web_app/tests/focus-mode-*.spec.ts` - `frontend/packages/ui/scripts/generate-apps-metadata.js` Identify whether the request is: - creating a new focus mode - updating an existing focus mode - migrating a legacy focus mode - changing prompt behavior only - changing activation/routing behavior ### Step 2: Ask 3 Clarifying Rounds Ask exactly one clear question per round and wait for the user's answer before continuing. Stop early only if the user explicitly says to skip clarification. Use these topics unless the repo context reveals more urgent blockers: - Round 1: What user goal should this focus mode solve? - Round 2: Which app/category should own it, and should it be new or update an existing mode? - Round 3: When should it activate, and what should be explicitly out of scope? ### Step 3: Search Internal Context Based on the answers, search internal sources for relevant connected information and ideas. Check: - existing focus modes with similar goals or prompts - the owning app's `app.yml`, skills, settings/memories, providers, and icons - GitHub issues for related product ideas, bugs, or prior decisions - architecture docs and user-guide docs for the affected app/domain - tests that cover focus mode settings, activation, rejection, mention, or app behavior Use GitHub Issues by default for tracker searches. Do not create or update an issue unless the user asks. ### Step 4: Search External Context Search externally for ideas and best practices relevant to the requested focus mode. Use: - GitHub search for similar AI assistant modes, prompt packages, agent skills, Claude skills, or domain-specific assistant workflows - web search for best practices in the requested domain - official or authoritative sources when the mode touches health, finance, legal, safety, education, jobs, security, privacy, or other high-risk topics Keep this research practical. Extract patterns that improve the OpenMates focus mode contract; do not copy prompts wholesale. ### Step 5: Ask 3 More Clarifying Rounds Ask exactly one clear question per round and wait for the user's answer before continuing. These questions must be informed by the internal and external research. Use them to resolve: - domain-specific constraints or safety boundaries - privacy or data-use limits - success criteria for what a good answer in this mode looks like - allowed skills/apps and whether the mode should ask before using external data - how proactive, cautious, structured, or conversational the mate should be ### Step 6: Suggest a Draft Present a concise draft and ask for feedback before editing product files. The draft must include: - display name - parent app - runtime focus ID and directory name - default-enabled behavior, including `default_enabled: false` only when the mode intentionally ships off - one-line description - activation/preprocessor hint - process bullets shown in settings - 2-3 “How to use” examples with highlighted trigger words - system prompt outline or full proposed system prompt - skills/apps it may rely on - non-goals - safety, privacy, and data-use rules For updates, show a focused diff-style summary of what will change. ### Step 7: Ask for Feedback Wait for the user's feedback. Do not implement before this gate unless the user explicitly says to proceed without draft approval. ### Step 8: Finalize the Draft Incorporate feedback and show the final version briefly. Confirm any remaining tradeoffs, such as activation breadth, default-enabled behavior, or safety wording. ### Step 8b: Define Phase Gates Before implementation, record the phase gate in the draft, inline contract, or full spec: 1. Implement and test focus-mode behavior through real OpenMates CLI chats against the dev server first. Mocked OpenMates API calls, mocked SDK clients, stubbed servers, direct function calls, and fixture replay do not satisfy this gate. 2. Implement and test npm SDK and pip SDK parity locally against the dev server when focus-mode activation or memory/settings behavior is exposed programmatically. After local CLI and SDK evidence is green, reproduce or wire the same coverage into GitHub Actions for CI/daily tests. 3. Implement web settings, examples, or Playwright coverage only after CLI and required SDK evidence are green. 4. Run deployed Playwright visual smoke for larger web/UI surfaces in both laptop and mobile viewports, fixing and redeploying any objective rendering, error, loading, or responsiveness issue, then ask the user to confirm the deployed dev web behavior works and looks correct before starting Apple parity. Use Firecrawl only as a recorded fallback when Playwright is impractical or blocked. `*.spec.ts` evidence alone is not enough. 5. Start Apple parity only after CLI, SDK, web, and user-confirmation evidence are complete, or after an explicit waiver/blocker is recorded. ### Step 9: Implement the Focus Mode Use the current OpenMates implementation reality, not only the future target architecture. Primary authoring target: - `backend/apps/{appId}/focus_modes/{focus-dir}/SKILL.md` Current compatibility targets that may also need updates: - `backend/apps/{appId}/app.yml` - `frontend/packages/ui/src/i18n/sources/focus_modes/{appId}_{focusId}.yml` - `frontend/packages/ui/src/i18n/sources/app_focus_modes/{appId}.yml` Rules: - Runtime `id` in `SKILL.md` is snake_case and must match OpenMates metadata. - Focus mode directory names are kebab-case for portability. - Keep `SKILL.md`, `app.yml`, and i18n keys aligned while the migration is incomplete. - Do not add `stage`; focus modes are enabled by default unless `default_enabled: false` is explicitly needed. - `preprocessor-hint` should be 1-3 sentences that describe when to select the mode, not the full system prompt. - `## Process` bullets should be user-facing and concrete. - `## System prompt` should define role, workflow, boundaries, tool behavior, and output expectations. - Capability fields such as `allowed-skills` are currently parsed but not fully enforced at runtime; do not rely on them as the only safety control. - If translations are not human-reviewed, do not mark localized files as verified by a human. ### Step 10: Validate Run the smallest checks that prove the change. Usually relevant: - `cd frontend/packages/ui && npm run build:translations` after i18n YAML edits - `cd frontend/packages/ui && npm run generate-apps-metadata` after focus metadata edits, if available in `package.json` - targeted parser or metadata-generation checks for `SKILL.md` - relevant lint or typecheck command for changed areas For any user-facing focus-mode behavior change, run a real OpenMates CLI chat quality check after the metadata is built and, when testing dev behavior, after the change is deployed to dev. Use the test-account helper or the compiled CLI, for example: - `node scripts/openmates_cli_test_account.mjs login --api-url https://api.dev.openmates.org` - `openmates --api-url https://api.dev.openmates.org chats new "<example request>" --json` Run multiple example requests that match the activation hint and inspect the actual assistant output. Record whether the focus mode activated, which skills were used, whether the answer followed the expected structure, and whether the quality met the draft's success criteria. If the CLI cannot be run, document the blocking reason instead of treating parser/build checks as behavior evidence. For user-facing focus-mode behavior, propose the relevant E2E test path and use the repo test runner after deploy when running Playwright: - `python3 scripts/tests.py run --spec focus-mode-settings.spec.ts` - `python3 scripts/tests.py run --spec focus-mode-mention.spec.ts` - `python3 scripts/tests.py run --spec focus-mode-rejection.spec.ts` - a new or updated focus-mode-specific spec if needed Do not run Playwright locally. ### Step 11: Add or Verify an Example Chat Every enabled focus mode must have at least one permanent example chat linked from its focus-mode details page. This applies to both new focus modes and prompt/routing improvements to existing focus modes. Before finishing: - Search `frontend/packages/ui/src/demo_chats/data/example_chats/` for an existing example with `metadata.app_focus_mode_examples` containing `"{appId}.{focusId}"`. - If none exists, create a real OpenMates chat through the CLI or app, share it, and scaffold it with `scripts/create-example-chat-from-share.mjs`. - Prefer a real CLI chat for reproducibility. If the focus mode needs explicit activation, use the CLI focus mention while creating the chat, but remove the internal `@focus:...` wire prefix from public example-chat user text after scaffolding. - Set `metadata.app_focus_mode_examples: ["{appId}.{focusId}"]` and `metadata.active_focus_id: "{appId}-{focusId}"` on the example chat so the focus-mode page can surface it and the demo chat opens with the active focus state visible. - Translate the new example-chat YAML, build translations, validate locales, and run `scripts/audit_example_chats.py` before deploying. - If a real example chat cannot be created, document the blocker explicitly; do not silently finish a focus-mode improvement without an example-chat plan. ## Draft Template Use this structure for Step 6 and Step 8. ```markdown ## Focus Mode Draft Name: App: Focus ID: Directory: Default enabled: Description: Activation hint: Process: - ... How to use: - ... - ... - ... System prompt: ... Allowed skills/apps: Non-goals: Safety and privacy: Open questions: ``` ## Implementation Checklist Before finishing, verify: - `SKILL.md` frontmatter starts and ends with `---` - `id` is snake_case and directory is kebab-case - title matches the display name intent - `## Process`, `## How to use`, and `## System prompt` sections exist when needed - `app.yml` contains or preserves compatible metadata while backend discovery still needs it - i18n YAML source files contain name, description, process, system prompt, and how-to-use strings where required - generated translations/metadata were rebuilt if source files changed - real OpenMates CLI chat requests covered the intended activation behavior and output-quality contract for behavior changes - at least one permanent example chat is linked via `metadata.app_focus_mode_examples` for the focus mode - relevant docs/tests were updated or explicitly deferred ## When to Escalate to a Full Spec Use `create-plan` before implementation if the focus mode changes runtime behavior, adds new persistence, introduces new API routes, changes activation/deactivation semantics, touches encryption/privacy-sensitive data flows, or requires new app skills/providers. Pure prompt/content additions can usually follow this skill without a full spec.