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 OpenCode 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
• node frontend/packages/openmates-cli/dist/cli.js --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.

## 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.