@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/antigravity/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/antigravity/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/antigravity/skills/django-drf/SKILL.md

@@ -63,7 +63,7 @@ No helper scripts are required for this skill right now. Keep execution in `SKIL
 
 - Skills are stored under `.agents/skills/<skill-id>/SKILL.md` (shared Agent Skills standard path).
 - TOML command files in `.gemini/commands/` provide slash-command entry points for workflows and agent routes.
-- Rules file: `.agents/rules/GEMINI.md`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
 - Use Agent Manager for parallel agent coordination and multi-specialist delegation (equivalent to `@orchestrator`).
 - Specialist routes are compiled into `.gemini/commands/agent-*.toml` command files — not project-local agent markdown.
 - Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.

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

@@ -69,7 +69,7 @@ Provide complete `docker-compose.yml` and `Dockerfile` content with inline comme
 
 - Skills are stored under `.agents/skills/<skill-id>/SKILL.md` (shared Agent Skills standard path).
 - TOML command files in `.gemini/commands/` provide slash-command entry points for workflows and agent routes.
-- Rules file: `.agents/rules/GEMINI.md`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
 - Use Agent Manager for parallel agent coordination and multi-specialist delegation (equivalent to `@orchestrator`).
 - Specialist routes are compiled into `.gemini/commands/agent-*.toml` command files — not project-local agent markdown.
 - Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.

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

@@ -88,7 +88,7 @@ Guide the design and implementation of production-grade Expo applications using
 
 - Skills are stored under `.agents/skills/<skill-id>/SKILL.md` (shared Agent Skills standard path).
 - TOML command files in `.gemini/commands/` provide slash-command entry points for workflows and agent routes.
-- Rules file: `.agents/rules/GEMINI.md`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
 - Use Agent Manager for parallel agent coordination and multi-specialist delegation (equivalent to `@orchestrator`).
 - Specialist routes are compiled into `.gemini/commands/agent-*.toml` command files — not project-local agent markdown.
 - Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.

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

@@ -69,7 +69,7 @@ Provide implementation code, Pydantic model definitions, dependency functions, c
 
 - Skills are stored under `.agents/skills/<skill-id>/SKILL.md` (shared Agent Skills standard path).
 - TOML command files in `.gemini/commands/` provide slash-command entry points for workflows and agent routes.
-- Rules file: `.agents/rules/GEMINI.md`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
 - Use Agent Manager for parallel agent coordination and multi-specialist delegation (equivalent to `@orchestrator`).
 - Specialist routes are compiled into `.gemini/commands/agent-*.toml` command files — not project-local agent markdown.
 - Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.

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

@@ -0,0 +1,105 @@
+---
+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."
+
+## Antigravity Platform Notes
+
+- Skills are stored under `.agents/skills/<skill-id>/SKILL.md` (shared Agent Skills standard path).
+- TOML command files in `.gemini/commands/` provide slash-command entry points for workflows and agent routes.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
+- Use Agent Manager for parallel agent coordination and multi-specialist delegation (equivalent to `@orchestrator`).
+- Specialist routes are compiled into `.gemini/commands/agent-*.toml` command files — not project-local agent markdown.
+- 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 Cubis Foundry MCP is configured.
+- User arguments are passed as natural language via `{{args}}` in TOML command prompts.

package/workflows/workflows/agent-environment-setup/platforms/antigravity/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/antigravity/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/antigravity/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/antigravity/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/antigravity/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/antigravity/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/antigravity/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/antigravity/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

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/flutter-mobile-qa/references/platform-setup.md

@@ -0,0 +1,107 @@
+# Flutter Mobile QA Platform Setup
+
+## Secure defaults
+
+- Use the Android MCP sample as a reference transport, not as a blind trust root.
+- Pin the package version: `android-mcp-server@1.3.0`.
+- Prefer workspace or project config over global config unless the user explicitly wants a machine-wide install.
+- Do **not** commit machine-specific `ANDROID_HOME` values. Let the runtime inherit `ANDROID_HOME` from the shell or rely on default SDK autodiscovery when it works.
+- Treat `adb_shell` as an advanced escape hatch, not a standard step in the happy path.
+
+## Recommended package
+
+- Upstream sample: [martingeidobler/android-mcp-server](https://github.com/martingeidobler/android-mcp-server)
+- Safe Foundry stance:
+  - pin the package version
+  - use repo-local config files where supported
+  - keep SDK paths and credentials out of committed project config
+
+## Client surfaces
+
+| Platform | Project-local config | Global config | Format |
+| --- | --- | --- | --- |
+| Codex | `.vscode/mcp.json` | `codex mcp add ...` or `~/.codex/config.toml` | JSON / CLI |
+| Claude Code | `.mcp.json` | `~/.claude/mcp.json` | JSON |
+| GitHub Copilot | `.vscode/mcp.json` | `~/.copilot/mcp-config.json` | JSON |
+| Gemini CLI | `.gemini/settings.json` | `~/.gemini/settings.json` | JSON |
+| Antigravity | `.gemini/settings.json` | `~/.gemini/settings.json` | JSON |
+
+## Project config snippets
+
+### Claude Code project config
+
+```json
+{
+  "mcpServers": {
+    "android": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "android-mcp-server@1.3.0"]
+    }
+  }
+}
+```
+
+### Codex or GitHub Copilot project config (`.vscode/mcp.json`)
+
+```json
+{
+  "servers": {
+    "android": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "android-mcp-server@1.3.0"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Gemini CLI or Antigravity project config (`.gemini/settings.json`)
+
+```json
+{
+  "mcpServers": {
+    "android": {
+      "command": "npx",
+      "args": ["-y", "android-mcp-server@1.3.0"],
+      "env": {}
+    }
+  }
+}
+```
+
+## Global config shortcuts
+
+### Codex CLI
+
+```bash
+codex mcp add android -- npx -y android-mcp-server@1.3.0
+```
+
+### Claude Code
+
+```bash
+claude mcp add --scope user android -- npx -y android-mcp-server@1.3.0
+```
+
+## Verification order
+
+1. Confirm `adb` works outside the MCP server.
+2. Confirm the emulator or device is visible.
+3. Confirm the MCP client loads the `android` server without parse errors.
+4. Run a low-risk call first: `list_devices` or `get_device_info`.
+5. Only then move to screenshots, UI tree, and interaction tools.
+
+## What not to commit
+
+- Absolute `ANDROID_HOME` values
+- Private keystore paths
+- Test usernames or passwords
+- Saved screenshots or logs outside the workspace artifact directory
+
+## Failure handling
+
+- If the client cannot start the server, verify `node`, `npx`, `adb`, and Android SDK availability before changing prompts.
+- If the server starts but no devices appear, stop and fix the emulator/device state first.
+- If only `adb_shell` can make progress, call out the missing higher-level tool or app instrumentation as a product gap.

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/frontend-design/SKILL.md

@@ -19,6 +19,7 @@ Provide systematic guidance for building distinctive, production-grade frontend
 - Reviewing animation and motion patterns for usability and performance
 - Establishing frontend coding standards for a team or project
 - Beautifying an existing UI that feels flat, generic, or inconsistent
+- Preparing a design brief before Google Stitch generates or edits UI screens
 
 ## Instructions
 
@@ -58,6 +59,12 @@ Provide systematic guidance for building distinctive, production-grade frontend
 
 18. **Test visual regressions alongside functional behavior** — Combine unit tests for logic, integration tests for composition, and visual regression snapshots for appearance so that refactors cannot silently break the user experience.
 
+19. **For Stitch-driven UI work, load only the refs needed for generation quality** — Start with `references/visual-direction.md` and `references/design-tokens.md` before prompting Stitch. Add `references/component-architecture.md` only when you are converting Stitch output into real components. Add `references/accessibility.md`, `references/responsive-patterns.md`, and `references/animation.md` only when the request explicitly needs those concerns. If the task spans multiple screens or iterative Stitch work, pair this skill with `stitch-design-system` so the design language persists across runs.
+
+20. **Use the design engine for serious UI work** — Treat this skill as the public anchor, then load the internal design-engine capabilities as needed: `frontend-design-core` for design-state resolution, `frontend-design-style-selector` for choosing the visual direction, `frontend-design-system` for canonical `docs/foundation/DESIGN.md`, `frontend-design-screen-brief` for task-specific briefs, `frontend-design-mobile-patterns` for Flutter/mobile adaptation, and `frontend-design-implementation-handoff` when converting the result into production UI.
+
+21. **Use only normalized design datasets during execution** — When broader design intelligence is needed, consume the Foundry-owned datasets under `workflows/design-datasets/*.json` rather than copying raw external design pages or prompts into runtime instructions.
+
 ## Output Format
 
 Deliver:
@@ -68,6 +75,7 @@ Deliver:
 4. **Accessibility audit** — WCAG compliance notes: contrast ratios, keyboard flow, ARIA usage
 5. **Responsive behavior** — Breakpoint strategy or container query usage with before/after viewport descriptions
 6. **Usage example** — A concrete code snippet showing the component in a realistic context
+7. **Design-engine handoff** — Which internal design-engine capability should run next, if any
 
 ## References
 
@@ -82,11 +90,13 @@ Load only what the current task requires.
 | `references/responsive-patterns.md` | Task involves responsive layout, container queries, fluid grids, or adaptive design. |
 | `references/animation.md` | Task involves transitions, micro-interactions, easing curves, or motion accessibility. |
 
+For Stitch workflows, always start with `references/visual-direction.md` and `references/design-tokens.md`. Add `component-architecture`, `accessibility`, `responsive-patterns`, or `animation` only when the current screen actually needs them.
+
 ## Antigravity Platform Notes
 
 - Skills are stored under `.agents/skills/<skill-id>/SKILL.md` (shared Agent Skills standard path).
 - TOML command files in `.gemini/commands/` provide slash-command entry points for workflows and agent routes.
-- Rules file: `.agents/rules/GEMINI.md`.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
 - Use Agent Manager for parallel agent coordination and multi-specialist delegation (equivalent to `@orchestrator`).
 - Specialist routes are compiled into `.gemini/commands/agent-*.toml` command files — not project-local agent markdown.
 - Reference files are loaded relative to the skill directory under `.agents/skills/<skill-id>/`.

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/frontend-design-core/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: frontend-design-core
+description: Establish the design-engine execution order, canonical design-state model, and the repo-first constraints for serious frontend or mobile design work.
+---
+# Frontend Design Core
+
+## Purpose
+
+Define the design-engine control flow before any UI generation or implementation work starts. This skill resolves canonical design state, chooses the right overlays, and keeps design prep ahead of Stitch or implementation.
+
+## When to Use
+
+- Starting a design-heavy feature, redesign, or new screen set
+- Resolving `docs/foundation/DESIGN.md` and page/flow/mobile overlays
+- Turning vague UX intent into a design-engine plan before code or Stitch calls
+- Coordinating design work across web, Stitch, and Flutter/mobile outputs
+
+## Instructions
+
+1. **Treat `docs/foundation/DESIGN.md` as canonical** — Every design-heavy task starts from the canonical design system document. `.stitch/DESIGN.md` is a generated compatibility mirror only.
+2. **Resolve overlays in a fixed order** — Start with the canonical design system, then load any relevant overlay from `docs/foundation/design/pages`, `docs/foundation/design/flows`, or `docs/foundation/design/mobile`, then produce the task-specific screen brief.
+3. **Keep external research out of the runtime path** — Use only Foundry-owned normalized datasets from `workflows/design-datasets/*.json` during execution. Do not paste raw external source text into prompts.
+4. **Choose the smallest design capability set** — Use `frontend-design-style-selector` to choose the visual direction, `frontend-design-system` when the design state is missing or stale, `frontend-design-screen-brief` when the task needs a concrete screen brief, `frontend-design-mobile-patterns` for Flutter/mobile-specific adaptation, and `frontend-design-implementation-handoff` when translating the result into production code.
+5. **Do not let Stitch lead the thinking** — Stitch generation or edits happen only after the design state and screen brief are ready.
+
+## Output Format
+
+Deliver:
+
+1. Canonical design inputs used
+2. Applied overlays
+3. Design-engine capability stack selected
+4. Next action: design-system, screen-brief, Stitch, or implementation
+
+## Antigravity Platform Notes
+
+- Skills are stored under `.agents/skills/<skill-id>/SKILL.md` (shared Agent Skills standard path).
+- TOML command files in `.gemini/commands/` provide slash-command entry points for workflows and agent routes.
+- Rules file relative to the mirrored skill directory: `../../rules/GEMINI.md`.
+- Use Agent Manager for parallel agent coordination and multi-specialist delegation (equivalent to `@orchestrator`).
+- Specialist routes are compiled into `.gemini/commands/agent-*.toml` command files — not project-local agent markdown.
+- 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 Cubis Foundry MCP is configured.
+- User arguments are passed as natural language via `{{args}}` in TOML command prompts.