@cubis/foundry 0.3.82 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/ci-cd-pipeline/SKILL.md

@@ -67,8 +67,12 @@ Provide complete pipeline configuration files with inline comments explaining no
 
 ## Gemini Platform Notes
 
-- Use `activate_skill` to invoke skills by name from Gemini CLI or Gemini Code Assist.
-- Skill files are stored under `.gemini/skills/` in the project root.
-- Gemini does not support `context: fork` — all skill execution is inline.
+- Workflow and agent routes are compiled into `.gemini/commands/*.toml` TOML command files.
+- Commands use `{{args}}` for user input, `!{shell command}` for shell output, `@{file}` for file content.
+- Specialists are internal postures (modes of reasoning), not spawned subagent processes.
+- Gemini does not support `context: fork` — all skill execution is inline within the current session.
+- Skills are loaded via MCP when the Cubis Foundry MCP server is configured. Local `.agents/skills/` paths serve as hints.
 - User arguments are passed as natural language in the activation prompt.
-- Reference files are loaded relative to the skill directory under `.gemini/skills/<skill-id>/`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
+- Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.
+- MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available when MCP is connected.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/code-review/SKILL.md

@@ -61,8 +61,12 @@ When conducting a code review, provide:
 
 ## Gemini Platform Notes
 
-- Use `activate_skill` to invoke skills by name from Gemini CLI or Gemini Code Assist.
-- Skill files are stored under `.gemini/skills/` in the project root.
-- Gemini does not support `context: fork` — all skill execution is inline.
+- Workflow and agent routes are compiled into `.gemini/commands/*.toml` TOML command files.
+- Commands use `{{args}}` for user input, `!{shell command}` for shell output, `@{file}` for file content.
+- Specialists are internal postures (modes of reasoning), not spawned subagent processes.
+- Gemini does not support `context: fork` — all skill execution is inline within the current session.
+- Skills are loaded via MCP when the Cubis Foundry MCP server is configured. Local `.agents/skills/` paths serve as hints.
 - User arguments are passed as natural language in the activation prompt.
-- Reference files are loaded relative to the skill directory under `.gemini/skills/<skill-id>/`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
+- Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.
+- MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available when MCP is connected.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/csharp-best-practices/SKILL.md

@@ -76,8 +76,12 @@ No helper scripts are required for this skill right now. Keep execution in `SKIL
 
 ## Gemini Platform Notes
 
-- Use `activate_skill` to invoke skills by name from Gemini CLI or Gemini Code Assist.
-- Skill files are stored under `.gemini/skills/` in the project root.
-- Gemini does not support `context: fork` — all skill execution is inline.
+- Workflow and agent routes are compiled into `.gemini/commands/*.toml` TOML command files.
+- Commands use `{{args}}` for user input, `!{shell command}` for shell output, `@{file}` for file content.
+- Specialists are internal postures (modes of reasoning), not spawned subagent processes.
+- Gemini does not support `context: fork` — all skill execution is inline within the current session.
+- Skills are loaded via MCP when the Cubis Foundry MCP server is configured. Local `.agents/skills/` paths serve as hints.
 - User arguments are passed as natural language in the activation prompt.
-- Reference files are loaded relative to the skill directory under `.gemini/skills/<skill-id>/`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
+- Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.
+- MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available when MCP is connected.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/database-design/SKILL.md

@@ -70,8 +70,12 @@ Load on demand. Do not preload all reference files.
 
 ## Gemini Platform Notes
 
-- Use `activate_skill` to invoke skills by name from Gemini CLI or Gemini Code Assist.
-- Skill files are stored under `.gemini/skills/` in the project root.
-- Gemini does not support `context: fork` — all skill execution is inline.
+- Workflow and agent routes are compiled into `.gemini/commands/*.toml` TOML command files.
+- Commands use `{{args}}` for user input, `!{shell command}` for shell output, `@{file}` for file content.
+- Specialists are internal postures (modes of reasoning), not spawned subagent processes.
+- Gemini does not support `context: fork` — all skill execution is inline within the current session.
+- Skills are loaded via MCP when the Cubis Foundry MCP server is configured. Local `.agents/skills/` paths serve as hints.
 - User arguments are passed as natural language in the activation prompt.
-- Reference files are loaded relative to the skill directory under `.gemini/skills/<skill-id>/`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
+- Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.
+- MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available when MCP is connected.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/deep-research/SKILL.md

@@ -82,8 +82,12 @@ Use these when the task shape already matches.
 
 ## Gemini Platform Notes
 
-- Use `activate_skill` to invoke skills by name from Gemini CLI or Gemini Code Assist.
-- Skill files are stored under `.gemini/skills/` in the project root.
-- Gemini does not support `context: fork` — all skill execution is inline.
+- Workflow and agent routes are compiled into `.gemini/commands/*.toml` TOML command files.
+- Commands use `{{args}}` for user input, `!{shell command}` for shell output, `@{file}` for file content.
+- Specialists are internal postures (modes of reasoning), not spawned subagent processes.
+- Gemini does not support `context: fork` — all skill execution is inline within the current session.
+- Skills are loaded via MCP when the Cubis Foundry MCP server is configured. Local `.agents/skills/` paths serve as hints.
 - User arguments are passed as natural language in the activation prompt.
-- Reference files are loaded relative to the skill directory under `.gemini/skills/<skill-id>/`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
+- Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.
+- MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available when MCP is connected.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/deep-research/examples/01-latest-docs-check.md

@@ -9,4 +9,4 @@
 1. Inspect the repo's current Claude rule and hook support first.
 2. Verify the current official Claude docs for hooks, event names, and config format.
 3. Separate those verified facts from any community commentary about hook effectiveness.
-4. End with the recommended next route, for example `@researcher` continuing the research or `/create` applying the validated hook template changes.
+4. End with the recommended next route, for example `@explorer` handing off to `@planner` or `/plan` applying the validated research result.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/deep-research/references/research-output.md

@@ -47,7 +47,7 @@ Research should end with one clear recommendation:
 
 - direct execution
 - a specific workflow like `/plan` or `/create`
-- a specialist like `@researcher` or `@frontend-specialist`
+- a concrete next route such as `@explorer`, `@planner`, or `@implementer`
 - an exact skill like `stitch` or `deep-research`
 
 Keep this recommendation concrete enough that the next step does not need another routing pass.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/django-drf/SKILL.md

@@ -61,8 +61,12 @@ No helper scripts are required for this skill right now. Keep execution in `SKIL
 
 ## Gemini Platform Notes
 
-- Use `activate_skill` to invoke skills by name from Gemini CLI or Gemini Code Assist.
-- Skill files are stored under `.gemini/skills/` in the project root.
-- Gemini does not support `context: fork` — all skill execution is inline.
+- Workflow and agent routes are compiled into `.gemini/commands/*.toml` TOML command files.
+- Commands use `{{args}}` for user input, `!{shell command}` for shell output, `@{file}` for file content.
+- Specialists are internal postures (modes of reasoning), not spawned subagent processes.
+- Gemini does not support `context: fork` — all skill execution is inline within the current session.
+- Skills are loaded via MCP when the Cubis Foundry MCP server is configured. Local `.agents/skills/` paths serve as hints.
 - User arguments are passed as natural language in the activation prompt.
-- Reference files are loaded relative to the skill directory under `.gemini/skills/<skill-id>/`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
+- Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.
+- MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available when MCP is connected.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/docker-compose-dev/SKILL.md

@@ -67,8 +67,12 @@ Provide complete `docker-compose.yml` and `Dockerfile` content with inline comme
 
 ## Gemini Platform Notes
 
-- Use `activate_skill` to invoke skills by name from Gemini CLI or Gemini Code Assist.
-- Skill files are stored under `.gemini/skills/` in the project root.
-- Gemini does not support `context: fork` — all skill execution is inline.
+- Workflow and agent routes are compiled into `.gemini/commands/*.toml` TOML command files.
+- Commands use `{{args}}` for user input, `!{shell command}` for shell output, `@{file}` for file content.
+- Specialists are internal postures (modes of reasoning), not spawned subagent processes.
+- Gemini does not support `context: fork` — all skill execution is inline within the current session.
+- Skills are loaded via MCP when the Cubis Foundry MCP server is configured. Local `.agents/skills/` paths serve as hints.
 - User arguments are passed as natural language in the activation prompt.
-- Reference files are loaded relative to the skill directory under `.gemini/skills/<skill-id>/`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
+- Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.
+- MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available when MCP is connected.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/expo-app/SKILL.md

@@ -86,8 +86,12 @@ Guide the design and implementation of production-grade Expo applications using
 
 ## Gemini Platform Notes
 
-- Use `activate_skill` to invoke skills by name from Gemini CLI or Gemini Code Assist.
-- Skill files are stored under `.gemini/skills/` in the project root.
-- Gemini does not support `context: fork` — all skill execution is inline.
+- Workflow and agent routes are compiled into `.gemini/commands/*.toml` TOML command files.
+- Commands use `{{args}}` for user input, `!{shell command}` for shell output, `@{file}` for file content.
+- Specialists are internal postures (modes of reasoning), not spawned subagent processes.
+- Gemini does not support `context: fork` — all skill execution is inline within the current session.
+- Skills are loaded via MCP when the Cubis Foundry MCP server is configured. Local `.agents/skills/` paths serve as hints.
 - User arguments are passed as natural language in the activation prompt.
-- Reference files are loaded relative to the skill directory under `.gemini/skills/<skill-id>/`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
+- Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.
+- MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available when MCP is connected.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/fastapi/SKILL.md

@@ -67,8 +67,12 @@ Provide implementation code, Pydantic model definitions, dependency functions, c
 
 ## Gemini Platform Notes
 
-- Use `activate_skill` to invoke skills by name from Gemini CLI or Gemini Code Assist.
-- Skill files are stored under `.gemini/skills/` in the project root.
-- Gemini does not support `context: fork` — all skill execution is inline.
+- Workflow and agent routes are compiled into `.gemini/commands/*.toml` TOML command files.
+- Commands use `{{args}}` for user input, `!{shell command}` for shell output, `@{file}` for file content.
+- Specialists are internal postures (modes of reasoning), not spawned subagent processes.
+- Gemini does not support `context: fork` — all skill execution is inline within the current session.
+- Skills are loaded via MCP when the Cubis Foundry MCP server is configured. Local `.agents/skills/` paths serve as hints.
 - User arguments are passed as natural language in the activation prompt.
-- Reference files are loaded relative to the skill directory under `.gemini/skills/<skill-id>/`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
+- Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.
+- MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available when MCP is connected.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/flutter-mobile-qa/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: flutter-mobile-qa
+description: "Use when planning or running Flutter mobile QA with Android MCP as the primary device path, explicit ADB fallback, screenshot/UI-tree evidence, logcat triage, and structured test reporting."
+---
+# Flutter Mobile QA
+
+## Purpose
+
+Provide a repeatable workflow for AI-driven QA of Flutter applications running on Android emulators or devices. This skill combines structured test planning, Android-MCP-primary device control, deterministic screenshot/UI-tree evidence, logcat triage, and Flutter-specific readiness guidance so the agent behaves like a cautious QA engineer instead of a blind script runner.
+
+## When to Use
+
+- Running smoke, regression, onboarding, checkout, or settings flows on a Flutter app.
+- Testing APK installs, emulator boot, login flows, deep links, navigation, or offline recovery.
+- Investigating mobile crashes, ANRs, rendering regressions, or widget interaction failures.
+- Wiring a workspace to an Android/ADB MCP server such as `android-mcp-server`.
+- Preparing CI-friendly emulator test guidance and evidence collection for mobile QA.
+
+## Instructions
+
+1. **Confirm the MCP surface before planning tests** because mobile QA is only reliable when the emulator/device control path is known. Load `references/platform-setup.md` first if the Android MCP server is not already configured.
+
+2. **Prefer a Flutter-aware server when available, but support generic Android MCP as the baseline** because Flutter semantics and route inspection are richer than raw UIAutomator output. If only generic Android MCP is present, lean on semantics labels, content descriptions, visible text, and stable widget keys exposed through accessibility.
+
+3. **Start every session with device readiness checks** because stale emulators and wrong APK builds waste time. Typical order: list devices or AVDs, boot the emulator if needed, install or verify the APK, launch the package, then capture a baseline screenshot and UI tree.
+
+4. **Write a test charter before acting** because mobile tests sprawl easily. State the flow under test, success criteria, known dependencies, credential needs, and what evidence counts as pass or fail.
+
+5. **Use the Observe -> Decide -> Act -> Assert loop for every meaningful step** because the UI can drift after each interaction. Prefer `screenshot`, `get_ui_tree`, and log inspection over assumptions. Load `references/android-mcp-tools.md` for the tool decision table.
+
+6. **Prefer high-signal interaction tools over low-level coordinates** because mobile layouts shift across devices and text scales. Use element-targeting helpers such as `tap_element`, `tap_and_wait`, `wait_for_element`, and `type_text` before falling back to raw coordinate taps.
+
+7. **Treat `adb_shell` as restricted** because it enables arbitrary device shell execution. Do not use it unless the user explicitly approves a device-level action that cannot be expressed with safer tools, and record the exact command in the final report.
+
+8. **Keep evidence local and deterministic** because mobile bugs are hard to reproduce. Save screenshots, logs, UI trees, and reports under `artifacts/mobile-qa/` or another workspace-local test artifact directory. Do not write evidence into random local paths.
+
+9. **Clear logs before reproducing suspected crashes** because mobile logcat is noisy. When triaging a failure, clear logs, reproduce once, then collect filtered logs immediately so the report reflects only the failing attempt.
+
+10. **Expect Flutter instrumentation gaps and call them out explicitly** because many test failures are product readiness issues, not agent mistakes. Load `references/flutter-readiness.md` when widgets cannot be reliably targeted or when route assertions are ambiguous.
+
+11. **Use one controlled retry for flaky interactions, not open-ended loops** because emulator timing issues are real but repeated blind retries hide bugs. Prefer Android MCP for the retry, and only drop to ADB when the operator explicitly allows fallback. A safe retry is: relaunch app or return to the last stable screen, recapture screenshot/UI tree, try once more, then stop and report evidence.
+
+12. **Handle credentials as session inputs, never repo state** because test credentials are sensitive and environment-specific. Ask for them when needed, prefer non-production accounts, and never commit them into app fixtures, prompts, or project config.
+
+13. **Tie the final verdict to observable evidence** because “it seemed to work” is not a test result. Every pass/fail claim should cite a screenshot state, UI tree fact, log line, or explicit route/assertion outcome.
+
+14. **Use CI only for reproducible emulator flows** because unstable devices produce false failures. Load `references/ci-emulator.md` when the user wants automation in GitHub Actions or another CI runner.
+
+15. **Anchor visual QA to the design engine when present** because a pass/fail verdict for mobile UI should reflect the intended design system, not just whether taps work. When `docs/foundation/DESIGN.md` or the mobile overlays directory under `docs/foundation/design/mobile/` exists, read the relevant design state first and mention any clear drift between the intended design language and the rendered app.
+
+## Output Format
+
+```markdown
+## Mobile QA Charter
+- Flow:
+- Target package:
+- Environment:
+- Credentials needed:
+
+## Execution Log
+1. [action] -> [observation]
+2. [action] -> [observation]
+
+## Assertions
+- Passed:
+- Failed:
+- Blocked:
+
+## Evidence
+- Screenshots:
+- UI-tree snapshots:
+- Log captures:
+
+## Risks And Follow-ups
+- Risk:
+- Recommended fix:
+```
+
+## References
+
+| File | Load when |
+| --- | --- |
+| `references/platform-setup.md` | Configuring Android MCP across Claude, Codex, Copilot, Gemini, or Antigravity. |
+| `references/android-mcp-tools.md` | Choosing safe Android MCP tools and understanding restricted operations. |
+| `references/flutter-readiness.md` | Verifying semantics labels, widget keys, routes, and app instrumentation for reliable QA. |
+| `references/ci-emulator.md` | Preparing pinned emulator + MCP setup for CI or shared QA runners. |
+| `agents/test-planner.md` | Breaking a mobile flow into stable checkpoints and assertions. |
+| `agents/device-operator.md` | Translating the plan into safe MCP tool calls on the emulator or device. |
+| `agents/evidence-reporter.md` | Turning screenshots, UI trees, and logs into a concise failure or pass report. |
+
+## Examples
+
+- "Boot the Android emulator, install the debug APK, run the login flow, and tell me where it fails with screenshots and logs."
+- "Verify the Flutter settings screen still works offline and report any crash or stuck-loading states."
+
+## Gemini Platform Notes
+
+- Workflow and agent routes are compiled into `.gemini/commands/*.toml` TOML command files.
+- Commands use `{{args}}` for user input, `!{shell command}` for shell output, `@{file}` for file content.
+- Specialists are internal postures (modes of reasoning), not spawned subagent processes.
+- Gemini does not support `context: fork` — all skill execution is inline within the current session.
+- Skills are loaded via MCP when the Cubis Foundry MCP server is configured. Local `.agents/skills/` paths serve as hints.
+- User arguments are passed as natural language in the activation prompt.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
+- Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.
+- MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available when MCP is connected.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/flutter-mobile-qa/agents/device-operator.md

@@ -0,0 +1,6 @@
+# Device Operator
+
+- Translate the plan into safe Android MCP calls.
+- Prefer `tap_element`, `tap_and_wait`, `wait_for_element`, and `type_text`.
+- Avoid `adb_shell` unless the user explicitly approves or no safer tool exists.
+- Re-capture screenshot and UI tree after meaningful state changes.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/flutter-mobile-qa/agents/evidence-reporter.md

@@ -0,0 +1,6 @@
+# Evidence Reporter
+
+- Save artifacts under `artifacts/mobile-qa/`.
+- Pair every failure claim with a screenshot or log reference.
+- Keep the report short: charter, execution log, failed assertion, evidence, next step.
+- Call out app instrumentation gaps separately from runtime failures.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/flutter-mobile-qa/agents/test-planner.md

@@ -0,0 +1,6 @@
+# Mobile Test Planner
+
+- Break the requested flow into stable checkpoints.
+- Identify required credentials, environment setup, and expected visible states.
+- Prefer assertions tied to screenshots, UI tree facts, and route or activity state.
+- Flag ambiguous targeting before execution starts.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/flutter-mobile-qa/examples/01-login-smoke.md

@@ -0,0 +1,14 @@
+# Example: Login Smoke Flow
+
+Prompt:
+
+> Use the configured Android MCP server to boot the emulator if needed, install the debug APK, run the login flow with the provided staging credentials, and report each checkpoint with screenshots and logs if anything fails.
+
+Expected behavior:
+
+1. Confirm the device state.
+2. Launch the package.
+3. Capture a baseline screenshot.
+4. Enter credentials.
+5. Submit with `tap_and_wait`.
+6. Assert the home screen loads and no crash appears in logs.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/flutter-mobile-qa/examples/02-crash-triage.md

@@ -0,0 +1,13 @@
+# Example: Crash Triage
+
+Prompt:
+
+> Reproduce the crash on the notifications settings screen, clear logs before the repro, and give me a concise bug report with screenshot evidence, the failing action, and the relevant log lines.
+
+Expected behavior:
+
+1. Clear logs.
+2. Navigate to the failing screen.
+3. Reproduce once.
+4. Capture screenshot, current activity, and filtered logs.
+5. Report root symptom, likely trigger, and smallest next debugging step.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/flutter-mobile-qa/references/android-mcp-tools.md

@@ -0,0 +1,66 @@
+# Android MCP Tools For Mobile QA
+
+## Safe-by-default tools
+
+Use these first.
+
+| Tool | Use for | Notes |
+| --- | --- | --- |
+| `list_devices` | Confirm target devices | First call when the session starts. |
+| `list_avds` | Discover emulator names | Use before `start_emulator`. |
+| `start_emulator` | Boot a known AVD | Wait for the device before app actions. |
+| `screenshot` | Visual state capture | Save evidence under `artifacts/mobile-qa/`. |
+| `get_ui_tree` | Element discovery | Use before tap decisions. |
+| `wait_for_element` | Stable synchronization | Prefer this over fixed sleeps. |
+| `get_current_activity` | Foreground screen sanity check | Useful after deep links or relaunches. |
+| `get_device_info` | Device metadata | Record once per test session. |
+| `get_logs` | Failure evidence | Filter by package after repro. |
+| `clear_logs` | Clean reproduction window | Run before crash repro attempts. |
+
+## Standard interaction tools
+
+Use these when the target element is known.
+
+| Tool | Preferred use |
+| --- | --- |
+| `tap_element` | First-choice interaction when text, resource ID, or content description is available |
+| `tap_and_wait` | First-choice navigation action when the UI should settle after the tap |
+| `type_text` | Text entry into the focused field |
+| `press_key` | Back/home/enter/menu and similar device controls |
+| `scroll_to_element` | Reaching off-screen targets |
+| `tap` | Fallback only when element targeting is impossible |
+| `swipe` | Lists, carousels, pull-to-refresh, or viewport movement |
+
+## Restricted tools
+
+Use only with explicit justification.
+
+| Tool | Risk | Foundry rule |
+| --- | --- | --- |
+| `pull_file` | Writes files locally and can leak private app data | Only pull files into a workspace-local artifact directory. |
+| `adb_shell` | Arbitrary device shell execution | Require explicit user approval or a clearly bounded troubleshooting need. Record the command in the report. |
+
+## Preferred loop
+
+1. `screenshot`
+2. `get_ui_tree`
+3. choose the next safe action
+4. `tap_and_wait` or `type_text`
+5. `screenshot`
+6. `get_ui_tree`
+7. if failure suspected, `get_logs`
+
+## Flutter-specific targeting order
+
+1. Content description derived from `Semantics(label: ...)`
+2. Visible text that is stable and user-facing
+3. Resource ID when the host view exposes one
+4. Raw coordinates only as the last resort
+
+## Artifact discipline
+
+- Save screenshots under `artifacts/mobile-qa/screenshots/`
+- Save logs under `artifacts/mobile-qa/logs/`
+- Keep filenames tied to the flow and checkpoint, for example:
+  - `artifacts/mobile-qa/screenshots/login-before-submit.png`
+  - `artifacts/mobile-qa/logs/login-submit-error.log`

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/flutter-mobile-qa/references/ci-emulator.md

@@ -0,0 +1,59 @@
+# CI Emulator Setup
+
+## Goal
+
+Run reproducible Android-emulator QA flows in CI with pinned tooling and workspace-local artifacts.
+
+## Baseline GitHub Actions shape
+
+```yaml
+name: mobile-qa
+
+on:
+  workflow_dispatch:
+  pull_request:
+
+jobs:
+  android-emulator:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: subosito/flutter-action@v2
+        with:
+          flutter-version: "stable"
+
+      - run: flutter pub get
+      - run: flutter build apk --debug
+
+      - uses: reactivecircus/android-emulator-runner@v2
+        with:
+          api-level: 34
+          arch: x86_64
+          profile: pixel_7
+          script: |
+            npm exec --yes android-mcp-server@1.3.0 >/tmp/android-mcp.log 2>&1 &
+            adb wait-for-device
+            adb install build/app/outputs/flutter-apk/app-debug.apk
+```
+
+## CI rules
+
+- Pin the MCP package version.
+- Keep screenshots and logs under `artifacts/mobile-qa/`.
+- Use debug or profile APKs that preserve meaningful logs and testability.
+- Fail fast if the emulator never boots or the APK install fails.
+
+## Suggested artifact paths
+
+- `artifacts/mobile-qa/screenshots/`
+- `artifacts/mobile-qa/logs/`
+- `artifacts/mobile-qa/report.md`
+
+## When not to automate
+
+- Real third-party login with CAPTCHA or MFA
+- Hardware features that are unavailable in the emulator
+- Non-deterministic push notification delivery
+
+In those cases, keep the test manual or semi-automated and collect evidence rather than forcing flaky CI.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/flutter-mobile-qa/references/flutter-readiness.md

@@ -0,0 +1,78 @@
+# Flutter Readiness For AI-Driven QA
+
+## Goal
+
+Make the Flutter app observable enough that a mobile QA agent can reason about it without brittle coordinate guessing.
+
+## Required signals
+
+### Stable semantics labels
+
+Use `Semantics(label: "...")` or widgets that expose meaningful accessibility labels. These become high-signal targets for UI inspection and interaction.
+
+### Stable widget keys
+
+Use `ValueKey` for primary controls, especially:
+
+- login or submit buttons
+- bottom-nav items
+- important toggles
+- search fields
+- modal confirm or cancel actions
+
+### Predictable route names
+
+Expose named routes or another stable navigation signal so the test report can say which screen the app actually reached.
+
+### Clean log messages
+
+Emit clear error logs for:
+
+- network failures
+- auth failures
+- route guard failures
+- uncaught exceptions
+
+## Recommended Flutter patterns
+
+```dart
+ElevatedButton(
+  key: const ValueKey('login_button'),
+  onPressed: onLogin,
+  child: const Text('Login'),
+)
+```
+
+```dart
+Semantics(
+  label: 'Email address',
+  child: TextField(
+    key: const ValueKey('email_input'),
+  ),
+)
+```
+
+## Common failure modes
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Agent cannot find a button reliably | No semantics label or stable key | Add `Semantics` or `ValueKey` |
+| Agent taps the wrong item in a list | Repeated labels with no scoping | Add more specific labels or keys |
+| Route assertions are ambiguous | Anonymous navigation or duplicate titles | Expose stable route names or screen markers |
+| Crash exists but report is weak | Logs are noisy or generic | Add explicit error logging around failure boundaries |
+
+## QA-friendly app checklist
+
+- Primary CTA buttons have `ValueKey`
+- Important inputs have labels
+- Loading, error, and empty states are visible and distinct
+- Offline and retry states are testable without hidden gestures
+- Navigation destinations have stable names or screen IDs
+
+## Reporting rule
+
+When readiness gaps block progress, treat them as product findings:
+
+- do not hide them behind repeated retries
+- record the exact missing label, key, or route signal
+- suggest the smallest instrumentation change needed