@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/skill-creator/references/routing-integration.md

@@ -18,15 +18,21 @@ User request
 
 ## Rule File Integration
 
-Each platform has a rule file with a skill routing matrix. When adding a new skill, update the matrix in every platform's rule file.
+Rule behavior is defined canonically in the shared steering layer, then specialized per platform by overrides and generated outputs.
+
+- Update `workflows/workflows/agent-environment-setup/shared/rules/STEERING.md` when the routing contract itself changes.
+- Update `workflows/workflows/agent-environment-setup/shared/rules/overrides/<platform>.md` only for platform-specific deviations.
+- Regenerate platform rule files after canonical edits instead of hand-editing every generated platform file.
+
+Each generated platform rule file still exposes a routing matrix or equivalent skill-routing surface, but the source of truth is the shared steering + override layer.
 
 ### Skill Routing Matrix Format
 
 ```markdown
 | Skill | Category | When to Load | Primary Agent |
 |-------|----------|--------------|---------------|
-| python-best-practices | Language | Python backend, typing, async | @backend-specialist |
-| nextjs | Framework | Next.js App Router, RSC | @frontend-specialist |
+| python-best-practices | Language | Python backend, typing, async | @implementer |
+| nextjs | Framework | Next.js App Router, RSC | @implementer |
 ```
 
 ### Matrix Fields
@@ -50,7 +56,9 @@ Each platform has a rule file with a skill routing matrix. When adding a new ski
 
 ### When to Create Mirrors
 
-Create platform-specific mirrors for Claude Code and Copilot. Other platforms use the canonical version.
+Create or regenerate platform skill mirrors for every supported platform. The authoring source remains canonical under `workflows/skills/`, but the install/runtime surfaces use generated platform mirrors.
+
+This applies to skills only. Do not reuse the skill mirror process for shared agents, workflow markdown, prompt files, or command files.
 
 ### Claude Code Mirror
 
@@ -77,7 +85,18 @@ Same format as Claude (Copilot reads Claude format). Add notes about:
 
 ### Codex / Gemini / Antigravity
 
-No mirror needed. The canonical version is used directly. Routing is handled by the platform rule file.
+These platforms also receive generated skill mirrors. Keep their frontmatter minimal and let the generated rule files plus MCP/routing behavior carry the platform-specific execution model.
+
+## Agent and Workflow Projections
+
+Shared agents and workflows must go through platform-specific generators because their output format differs by platform.
+
+- Codex agents are emitted as `.toml` native agents.
+- Claude and Copilot agents are emitted as markdown with sanitized platform frontmatter.
+- Gemini and Antigravity workflows and agent routes are emitted as TOML command files.
+- Copilot workflows are emitted as prompt files rather than skill mirrors.
+
+If a change affects custom agents, workflow prompts, or command behavior, update the shared source and rerun the platform asset generator instead of relying on `sync-skill-mirrors`.
 
 ## Agent Assignment
 
@@ -85,16 +104,16 @@ Each skill should be assigned a primary agent in the routing matrix. Choose base
 
 | Domain | Primary Agent |
 |--------|---------------|
-| Languages (Python, TS, Go, etc.) | @backend-specialist or @frontend-specialist |
-| Backend frameworks | @backend-specialist |
-| Frontend frameworks | @frontend-specialist |
-| Mobile frameworks | @mobile-developer |
-| Database/ORM | @database-architect |
-| Testing | @test-engineer |
-| Security | @security-auditor |
-| DevOps | @devops-engineer |
-| Design/Architecture | @project-planner |
-| AI/ML | @researcher |
+| Languages (Python, TS, Go, etc.) | @implementer |
+| Backend frameworks | @implementer |
+| Frontend frameworks | @implementer |
+| Mobile frameworks | @implementer |
+| Database/ORM | @planner or @implementer |
+| Testing | @tester |
+| Security | @reviewer |
+| DevOps | @implementer |
+| Design/Architecture | @planner |
+| AI/ML / research | @explorer or @planner |
 | Workflow | @orchestrator |
 | Meta | @orchestrator |
 
@@ -102,17 +121,20 @@ Each skill should be assigned a primary agent in the routing matrix. Choose base
 
 After adding a skill to the routing infrastructure:
 
-1. Run `npm run test:attributes` — validates frontmatter across all skills
-2. Run `npm run check:generated-assets` — verifies platform mirrors are in sync
-3. Verify the skill appears in `npm run generate:skills-index`
-4. Test `route_resolve` with a prompt that should match the new skill
-5. Test `skill_validate` with the new skill's name
-6. Test `skill_get` to confirm the SKILL.md loads correctly
+1. Update canonical skill content under `workflows/skills/<name>/`
+2. Update shared steering or platform overrides if the routing contract changed
+3. Run `npm run generate:all` or the narrower mirror/rule/platform-asset generation commands
+4. Run `npm run test:attributes` — validates frontmatter across all skills
+5. Run `npm run check:generated-assets` — verifies platform mirrors are in sync
+6. Verify the skill appears in `npm run generate:skills-index`
+7. Test `route_resolve` with a prompt that should match the new skill
+8. Test `skill_validate` with the new skill's name
+9. Test `skill_get` to confirm the SKILL.md loads correctly
 
 ## Common Integration Mistakes
 
-1. **Forgetting to update all 5 platform rule files** — every platform needs the skill in its routing matrix
+1. **Editing generated platform rule files directly** — change shared `STEERING.md` or a platform override, then regenerate
 2. **Mismatched names** — directory name, frontmatter name, and routing matrix name must all match
-3. **Wrong agent assignment** — assigning a frontend skill to @backend-specialist causes incorrect context loading
-4. **Missing mirror creation** — Claude and Copilot platforms need mirrors with platform-specific frontmatter
+3. **Wrong agent assignment** — assigning a testing or review skill to the wrong lean agent causes incorrect routing and validation
+4. **Using skill mirror sync for non-skill assets** — agents, prompts, and command files have their own platform-native generation path
 5. **Invalid evals.json** — JSON syntax errors cause the eval runner to skip the skill silently

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/spec-driven-delivery/SKILL.md

@@ -22,7 +22,7 @@ Create and maintain a lightweight source of truth for non-trivial work. This ski
 2. **Look for an existing spec pack before creating a new one** because duplicate specs create drift. Reuse the closest matching spec directory when the current request extends an active initiative.
 3. **Create a stable `spec_id` and spec root** because the same identifier should survive planning, execution, review, and follow-up changes.
 4. **Write the minimum viable pack** because the goal is durable coordination, not bureaucracy. Keep the brief, acceptance, tasks, traceability, and handoff documents concise and testable.
-5. **Use `sadd` when turning requirements into assertions** because spec quality depends on extracting testable behavior instead of leaving requirements vague.
+5. **Turn requirements into testable assertions** because spec quality depends on concrete behavior, acceptance checks, and traceability rather than vague intent.
 6. **Record architecture impact explicitly** because implementation must stay aligned with the project architecture contract and current-state tech map. Mark whether the change affects architecture style, module boundaries, dependency rules, design system, deployment shape, or testing strategy.
 7. **Update the spec before implementation changes behavior** because traceability breaks when code changes first and docs lag behind.
 8. **Keep the task graph execution-ready** because `/implement-track` and `/orchestrate` should be able to act on the spec without replanning. Every task should have ownership, dependencies, acceptance criteria, and a verification path.
@@ -45,22 +45,14 @@ Deliver:
 
 | File | Load when |
 | --- | --- |
-| `../sadd/SKILL.md` | Need requirement mining, GIVEN-WHEN-THEN specs, or traceability patterns. |
 | `../architecture-doc/SKILL.md` | Need ADRs, system boundaries, or architecture-document structure. |
 | `../deep-research/SKILL.md` | Need repo-first research escalation or evidence labeling rules. |
 
-## Examples
-
-| File | Use when |
-| --- | --- |
-| `../sadd/references/spec-mining.md` | Turning loose requirements into testable spec entries. |
-| `../sadd/references/coverage-mapping.md` | Building a traceability matrix that links specs, tests, and code. |
-
 ## 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/spring-boot/SKILL.md

@@ -69,7 +69,7 @@ Provide implementation code, configuration properties, bean definitions, and arc
 
 - 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/sqlalchemy/SKILL.md

@@ -78,7 +78,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/stitch/SKILL.md

@@ -1,54 +1,43 @@
 ---
 name: stitch
-description: Use when implementing or updating UI from Google Stitch artifacts, screen-to-code handoff, design-to-code diffs, or syncing an existing screen with the latest Stitch output through Cubis Foundry MCP.
+description: Compatibility wrapper for explicit `stitch` requests. Use this when older docs or users name `stitch` directly and route them into the design-first Stitch sequence: frontend-design, prompt enhancement, design-system sync, Stitch orchestration, and implementation handoff.
 ---
-# Stitch
+# Stitch Compatibility Wrapper
 
 ## Purpose
 
-Turn Google Stitch artifacts into production-ready UI changes without guessing the design. This skill is for real Stitch-driven implementation and update work: fetch the latest Stitch artifacts through Cubis Foundry MCP, map them into the repo's actual stack and design system, and apply minimal, accessible changes.
+Preserve compatibility for users or older instructions that still say “use stitch”. This package no longer acts as the one broad Stitch skill. It now routes work into the narrower Stitch skill family so UI generation stays design-first and safe against overuse of the remote Stitch service.
 
 ## When to Use
 
-- Implementing a new screen from Stitch artifacts
-- Updating an existing screen from refreshed Stitch output
-- Performing design-to-code diffs against local UI
-- Translating Stitch artifacts into React, Next.js, React Native, Flutter, SwiftUI, or another project framework
-- Auditing whether the local screen still matches the current Stitch version
+- A user explicitly names `stitch` as the skill to use
+- Older generated docs or team notes still reference `stitch`
+- You need a compatibility bridge into the current Stitch skill family
 
 ## Instructions
 
-1. **Verify Stitch is reachable before relying on it**. Check `stitch_get_status` and `mcp_gateway_status` first. If Stitch is misconfigured or unavailable, say so clearly and do not invent screen details. See `references/platform-setup.md`.
+1. **Treat this skill as a compatibility entrypoint, not the final procedure** — Convert the request into the current Stitch sequence instead of trying to do everything from this wrapper alone.
 
-2. **List enabled Stitch tools before choosing a workflow**. Use `stitch_list_enabled_tools` or the Stitch passthrough namespace to confirm which real upstream tools are available in the current environment.
+2. **Load `frontend-design` first** — Start with visual direction and token intent before any Stitch prompt or tool call.
 
-3. **Normalize the request into a concrete implementation brief**. If the prompt is vague, restate the target screen, destination route or component, framework, responsive expectations, and reuse constraints before editing anything. This follows the same prompt-sharpening idea used in Stitch-first design workflows, but the output here should stay implementation-oriented.
+3. **Then load `stitch-prompt-enhancement`** — Turn rough UI intent into a compact, structured Stitch brief. Do not send vague prompts directly to Stitch.
 
-4. **Pull Stitch artifacts before planning implementation**. Fetch the actual screen artifact, code, metadata, and image/snapshot when available. Do not reconstruct the UI from a natural-language guess.
+4. **Use `stitch-design-system` only when needed** — If `docs/foundation/DESIGN.md` is missing, stale, or the work spans multiple screens, generate or refresh it and mirror it to `.stitch/DESIGN.md`.
 
-5. **Map Stitch output into the repo's real stack**. Re-express the artifact in the project's framework, routing model, state layer, styling system, and component primitives. Do not paste generated output blindly. See `references/implementation-patterns.md`.
+5. **Use `stitch-design-orchestrator` for actual Stitch operations** — That skill owns MCP preflight, tool discovery, minimal tool selection, safety limits, and suggestion-aware retries.
 
-6. **Prefer local component reuse over one-off markup**. If the project already has buttons, cards, typography, layout shells, tokens, or navigation primitives, use them instead of cloning raw Stitch structure.
+6. **Use `stitch-implementation-handoff` for repo-native code mapping** — Once Stitch returns the final screen artifact, hand off to the implementation skill instead of pasting generated HTML blindly.
 
-7. **Keep diffs minimal when updating an existing screen**. Compare the local implementation against the latest Stitch artifact and patch only the changed structure, spacing, copy, tokens, states, and assets. Preserve validated business logic and local architecture. See `references/update-diff-workflow.md`.
-
-8. **Use existing local exports or prior implementations as a diff baseline**. If the repo already contains the target screen or a prior Stitch-derived implementation, compare against that first. Refresh from Stitch when the task requires live parity; otherwise use the local baseline to reduce churn.
-
-9. **Preserve accessibility and interaction states**. Maintain semantic structure, keyboard flow, focus treatment, labels, contrast, loading/error/empty states, and responsive behavior while translating the design.
-
-10. **Call out unavoidable drift explicitly**. If the repo's design system, data model, or framework constraints prevent a literal Stitch match, explain the exact deviation and why it was necessary.
-
-11. **Ask only targeted clarification questions**. Ask when the artifact is ambiguous, multiple Stitch screens plausibly match, or the repo has competing destination surfaces. Otherwise proceed with the best repo-grounded implementation.
+7. **Prefer `/implement` with a Stitch UI scope for fresh work** — If the user is starting new work, route into the workflow-first Stitch path instead of staying inside this compatibility wrapper.
 
 ## Output Format
 
 Deliver:
 
-1. **Artifact summary** — which Stitch artifact or screen was used
-2. **Implementation plan** — target files, framework mapping, and any deviations
-3. **Code changes** — minimal production-ready implementation or patch
-4. **Diff notes** — what changed relative to the prior local UI, if applicable
-5. **Verification** — accessibility, responsive behavior, and any remaining gaps
+1. **Resolved Stitch sequence** — which narrower skills should run, in order
+2. **Design prep summary** — visual direction, token scope, and whether a design-system refresh is required
+3. **Execution handoff** — whether the next step is prompt enhancement, Stitch orchestration, or implementation handoff
+4. **Safety notes** — any configuration, rate-control, or ambiguity blockers
 
 ## References
 
@@ -56,9 +45,9 @@ Load only what the current task requires.
 
 | File | Load when |
 | --- | --- |
-| `references/platform-setup.md` | Need to verify Stitch availability, gateway status, profile setup, or secure credential expectations. |
-| `references/implementation-patterns.md` | Need guidance for mapping Stitch artifacts into web/mobile stacks and existing design systems. |
-| `references/update-diff-workflow.md` | Updating an existing implementation from revised Stitch artifacts or running a UI diff workflow. |
+| `../frontend-design/references/visual-direction.md` | Need to establish the design point of view before any Stitch prompt. |
+| `../frontend-design/references/design-tokens.md` | Need to align token vocabulary before Stitch generation or editing. |
+| `../stitch-design-system/references/design-template.md` | Need the canonical `docs/foundation/DESIGN.md` structure and the `.stitch/DESIGN.md` mirror contract. |
 
 ## Examples
 
@@ -66,23 +55,21 @@ Use these when the task closely matches the example shape.
 
 | File | Use when |
 | --- | --- |
-| `examples/01-new-screen.md` | Creating a new screen from Stitch output. |
-| `examples/02-update-existing-screen.md` | Patching an existing screen from updated Stitch artifacts. |
-| `examples/03-mobile-handoff.md` | Translating Stitch into a mobile framework or native stack. |
-| `examples/04-prompt-enhancement.md` | Turning a vague Stitch request into a concrete implementation brief before coding. |
-| `examples/05-design-sync-loop.md` | Running an iterative Stitch refresh-and-patch loop for an existing product surface. |
+| `../stitch-design-orchestrator/examples/01-stitch-ui-route.md` | Need the full workflow-first Stitch sequence. |
+| `../stitch-prompt-enhancement/examples/01-dashboard-prompt.md` | Need to sharpen a vague UI request before Stitch. |
+| `../stitch-implementation-handoff/examples/01-new-screen.md` | Need the implementation-side handoff after Stitch finishes. |
 
-## Antigravity Stitch Flow
+## Antigravity Stitch Compatibility Flow
 
-- Use the `stitch` skill from `.agent/skills/stitch` as the preflight and artifact-retrieval entry point, then hand off focused implementation work through Agent Manager only if the task genuinely benefits from parallelism.
-- Keep Stitch verification with the initiating agent: confirm gateway status, screen identity, and destination files before dispatching any frontend-specialist work.
-- Preserve Antigravity's route-first posture: the result should still be a minimal, repo-native UI patch rather than a pasted design export.
+- Treat this skill as a compatibility wrapper only. Route the real work through `frontend-design`, `stitch-prompt-enhancement`, `stitch-design-system` when needed, `stitch-design-orchestrator`, and `stitch-implementation-handoff`.
+- Verify the Foundry Stitch MCP configuration from `.gemini/settings.json` before choosing any Stitch tool path.
+- Prefer the shared `/implement` Stitch UI flow for new work so the design-first sequence stays intact on Antigravity.
 
 ## 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/stitch-design-orchestrator/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: stitch-design-orchestrator
+description: Orchestrate safe, design-first Google Stitch generation and editing by sequencing frontend-design, prompt enhancement, design-system sync, Stitch MCP tool selection, and implementation handoff.
+---
+# Stitch Design Orchestrator
+
+## Purpose
+
+Coordinate Google Stitch work as a workflow-first, skill-driven sequence. This skill ensures UI generation or editing does not jump straight into remote Stitch calls without first establishing design direction, compact prompt structure, design-system context, and an implementation plan for the repo's real stack.
+
+## When to Use
+
+- Generating a new UI screen with Stitch
+- Editing an existing Stitch screen with a targeted change
+- Creating variants before choosing one direction
+- Running a design-first flow before converting Stitch output into code
+- Keeping Stitch usage safe, bounded, and consistent across multiple screens
+
+## Instructions
+
+1. **Treat Stitch as a remote design engine, not the source of production truth** — Use Stitch to generate or edit visual artifacts, then hand those artifacts into repo-native implementation. Do not paste returned HTML or markup blindly.
+
+2. **Load the design engine first** — Always establish the visual direction, token language, and screen brief before forming a Stitch prompt. Start with `frontend-design`, then resolve `frontend-design-core`, `frontend-design-style-selector`, and `frontend-design-screen-brief` before calling Stitch.
+
+3. **Run `stitch-prompt-enhancement` before any Stitch tool call** — Convert rough user intent into a compact structured brief that names the platform, layout, components, visual mood, and change scope.
+
+4. **Require a design-system context for iterative or multi-screen work** — If `docs/foundation/DESIGN.md` is missing, stale, or the request spans multiple screens, run `frontend-design-system` and `stitch-design-system` to create or refresh `docs/foundation/DESIGN.md`, resolve overlays, and mirror the result to `.stitch/DESIGN.md`.
+
+5. **Verify Stitch availability before trusting it** — Run `stitch_get_status`, `mcp_gateway_status`, and `stitch_list_enabled_tools` before choosing a tool flow. If Stitch is unavailable, stop treating it as authoritative input.
+
+6. **Reuse before creating** — Call `list_projects` before `create_project` and reuse an existing project when it already represents the current feature or product area. Call `list_screens` before planning follow-up work so edits stay attached to the current screen set instead of spawning unnecessary new artifacts.
+
+7. **Choose the minimal tool path** — Use `generate_screen_from_text` for a net-new screen, `edit_screens` for targeted revisions, `generate_variants` for controlled alternatives, and `create_design_system` or `apply_design_system` only when the design system itself is the current task. Default to `GEMINI_3_1_PRO` for complex new screens, multi-screen work, and design-system-heavy tasks. Use `GEMINI_3_FLASH` only when the user explicitly wants a speed-first draft or the task is a lightweight edit. See `references/tool-selection.md`.
+
+8. **Surface Stitch suggestions instead of brute-forcing retries** — If Stitch returns suggestion-bearing components or follow-up guidance, show that guidance and incorporate it before retrying.
+
+9. **Rate-limit yourself** — By default, allow one Stitch generation or edit action per user turn, prefer `edit_screens` over full regeneration once a screen exists, and stop after two automatic retries with backoff. See `references/anti-abuse.md`.
+
+10. **Recover intelligently after timeouts** — For `generate_screen_from_text` and `generate_variants`, a timeout can still leave a finished screen in Stitch. Check `list_screens` before assuming the generation failed, then continue from the recovered screen instead of creating a new project.
+
+11. **Fetch the final screen artifact before implementation handoff** — Use `get_screen` after the final generation or edit pass so the downstream implementation step receives the actual latest artifact, not a guessed description.
+
+12. **Finish with `stitch-implementation-handoff`** — Once the design output is settled, hand off the artifact so the repo implementation reuses local components, tokens, and architecture.
+
+## Output Format
+
+Deliver:
+
+1. **Design prep summary** — visual direction, token scope, and whether design-system refresh is needed
+2. **Tool plan** — which Stitch tools will be used and why
+3. **Safety state** — status checks, retry budget, and any blocker
+4. **Artifact handoff** — which final screen or project artifact is ready for implementation
+
+## References
+
+| File | Load when |
+| --- | --- |
+| `references/tool-selection.md` | Need to choose the right Stitch tool path for new screens, edits, variants, or design-system work. |
+| `references/anti-abuse.md` | Need retry, backoff, or prompt-budget rules before using the remote Stitch service. |
+| `../frontend-design/references/visual-direction.md` | Need to define the interface mood and composition before writing a Stitch prompt. |
+| `../frontend-design/references/design-tokens.md` | Need semantic token language before sending UI instructions to Stitch. |
+
+## Examples
+
+| File | Use when |
+| --- | --- |
+| `examples/01-stitch-ui-route.md` | Routing a new Stitch UI request through the full design-first sequence. |
+
+## Antigravity Stitch Orchestration
+
+- Run this as a workflow-first sequence: design prep, prompt enhancement, optional design-system refresh, Stitch preflight, minimal tool selection, then implementation handoff.
+- Verify `stitch_get_status`, `mcp_gateway_status`, and `stitch_list_enabled_tools` before any generation or edit call.
+- Treat Stitch as a rate-sensitive remote service on Antigravity: allow one generation or edit action per turn by default, prefer `edit_screens` over full regeneration, and stop after two automatic retries with backoff.
+
+## 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/stitch-design-orchestrator/examples/01-stitch-ui-route.md

@@ -0,0 +1,15 @@
+# Example: Workflow-First Stitch UI Route
+
+Prompt shape:
+
+> Use Stitch to generate a billing dashboard screen for our web app, then implement it in the existing frontend.
+
+Expected sequence:
+
+1. Load `frontend-design` with `visual-direction` and `design-tokens`.
+2. Run `stitch-prompt-enhancement`.
+3. Ensure `docs/foundation/DESIGN.md` exists or refresh it with `stitch-design-system`.
+4. Verify Stitch MCP status and list enabled tools.
+5. Use the smallest Stitch tool path.
+6. Fetch the final screen artifact with `get_screen`.
+7. Hand off to `stitch-implementation-handoff`.

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/stitch-design-orchestrator/references/anti-abuse.md

@@ -0,0 +1,30 @@
+# Stitch Anti-Abuse Rules
+
+Treat Stitch as a rate-sensitive remote service.
+
+## Default guardrails
+
+1. One Stitch generation or edit action per user turn by default.
+2. Prefer `edit_screens` over full regeneration once a screen already exists.
+3. Maximum two automatic retries on transient failures.
+4. Use short backoff before retry one and longer backoff before retry two.
+5. Stop after two retries and ask for direction if progress is still blocked.
+6. Reuse an existing `projectId` whenever the work belongs to the same app instead of creating fresh projects for every pass.
+
+## Prompt budget rules
+
+- Do not send raw repo dumps, long transcripts, or whole foundation docs.
+- Send a compact structured brief only.
+- Reuse `projectId` and `screenId` when editing rather than creating unnecessary new Stitch resources.
+- Default to `GEMINI_3_1_PRO` for complex generation. Use `GEMINI_3_FLASH` only for explicit speed-first work or lightweight edits.
+- If Stitch returns suggestions, incorporate them before retrying instead of resending the same prompt.
+- If a generation request times out, check `list_screens` before retrying because the remote render may still have completed.
+
+## Stop conditions
+
+Stop and report when:
+
+- Stitch status or tool discovery failed
+- design context is missing for a multi-screen task
+- repeated retries do not materially change the result
+- the user appears to want a large autonomous loop

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/stitch-design-orchestrator/references/tool-selection.md

@@ -0,0 +1,30 @@
+# Stitch Tool Selection
+
+## Minimal tool routing
+
+- `list_projects`
+  Use before `create_project` when the current product area may already have a Stitch project. Reuse that project unless the user explicitly wants a separate concept track.
+- `generate_screen_from_text`
+  Use for a new screen or page when no existing Stitch screen should be preserved.
+- `list_screens`
+  Use before planning follow-up changes and after timeouts so you can reuse or recover the current screen set.
+- `edit_screens`
+  Use for targeted changes to an existing screen. Prefer this once a screen already exists.
+- `generate_variants`
+  Use when the user explicitly wants a few alternatives before choosing one direction.
+- `create_design_system`
+  Use when the task is to establish a new Stitch design system, not just a screen.
+- `apply_design_system`
+  Use when a known design system should be applied to an existing project or screen set.
+- `get_screen`
+  Use after the final generation/edit pass to fetch the authoritative artifact for implementation handoff.
+
+## Selection rules
+
+1. Prefer the smallest tool that solves the task.
+2. Reuse an existing project before creating a new one when the work belongs to the same app or feature line.
+3. Once a screen exists, default to `edit_screens` instead of full regeneration.
+4. Default to `GEMINI_3_1_PRO` for complex new screens, multi-screen work, or design-system-heavy generation.
+5. Use `GEMINI_3_FLASH` only for explicitly speed-first drafts or narrow edits where lower reasoning quality is acceptable.
+6. Do not call `generate_variants` unless the user actually wants alternatives.
+7. Do not call `create_design_system` or `apply_design_system` for a one-off screen unless design-system work is part of the task.

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

@@ -0,0 +1,74 @@
+---
+name: stitch-design-system
+description: Create or refresh a Stitch-compatible design-system context by maintaining docs/foundation/DESIGN.md as the canonical source and mirroring it to .stitch/DESIGN.md when Stitch flows need persistent visual consistency.
+---
+# Stitch Design System
+
+## Purpose
+
+Maintain the design context that lets Stitch generate consistent screens across a project. This skill keeps `docs/foundation/DESIGN.md` as the canonical design document and mirrors it to `.stitch/DESIGN.md` for Stitch-oriented generation flows.
+
+## When to Use
+
+- A Stitch project needs consistent visual language across multiple screens
+- `docs/foundation/DESIGN.md` is missing or stale
+- A repo already has tokens and component patterns that should be reflected in Stitch prompts
+- A team wants to refresh Stitch design context from an existing screen or artifact
+
+## Instructions
+
+1. **Keep `docs/foundation/DESIGN.md` canonical** — The project-owned design context lives under `docs/foundation/DESIGN.md`. `.stitch/DESIGN.md` is a generated compatibility mirror for Stitch-facing workflows.
+
+2. **Derive from repo evidence first** — Prefer existing tokens, CSS variables, typography scales, component primitives, and brand docs from the repo before extracting from Stitch output.
+
+3. **Use Stitch artifacts only when they add real missing context** — When the repo design system is incomplete, inspect Stitch screens with `get_screen` and extract the visual language from the real artifact.
+
+4. **Describe the system semantically** — Write colors by role, typography by hierarchy, spacing by rhythm, shape by character, and motion by purpose. Include exact values only when they help generation consistency.
+
+5. **Capture component vocabulary** — Document how buttons, cards, forms, navigation, tables, and empty states should look and feel so future prompts stay consistent.
+
+6. **Keep the scope proportional** — Do not build or refresh the design-system document for every one-off component task. Use this skill when the work spans multiple screens, iterative Stitch work, or a real design refresh.
+
+7. **Mirror the canonical file into `.stitch/DESIGN.md`** — When this skill updates the canonical file, it must also update the Stitch compatibility mirror so Stitch-oriented flows read the same design language.
+
+8. **Mark unknowns clearly** — If a color role, typography rule, or motion style is inferred rather than directly evidenced, call that out instead of presenting it as a verified fact.
+
+## Output Format
+
+Deliver:
+
+1. **Canonical design path** — `docs/foundation/DESIGN.md`
+2. **Mirror path** — `.stitch/DESIGN.md`
+3. **Design-system summary** — palette roles, typography, spacing, shape, components, and motion
+4. **Evidence notes** — what came from repo truth vs Stitch artifact inference
+
+## References
+
+| File | Load when |
+| --- | --- |
+| `references/design-template.md` | Need the canonical structure for `docs/foundation/DESIGN.md` and the Stitch mirror. |
+| `../frontend-design/references/design-tokens.md` | Need token structure and semantic value naming. |
+| `../stitch/references/platform-setup.md` | Need to verify Stitch availability before relying on artifact-derived design cues. |
+
+## Examples
+
+| File | Use when |
+| --- | --- |
+| `examples/01-design-context.md` | Need a minimal template for the canonical design doc and Stitch mirror. |
+
+## Antigravity Design Context Sync
+
+- Keep `docs/foundation/DESIGN.md` as the canonical project design document and mirror it to `.stitch/DESIGN.md` for Stitch-facing flows.
+- Refresh this context only when the design language is missing, stale, or needs to stay consistent across multiple screens.
+- Derive the design system from repo truth first, then use Stitch artifacts only to fill missing visual context on Antigravity.
+
+## 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/stitch-design-system/examples/01-design-context.md

@@ -0,0 +1,12 @@
+# Example: Canonical + Mirror Design Context
+
+Expected result:
+
+- `docs/foundation/DESIGN.md` contains the project's canonical design-system summary
+- `.stitch/DESIGN.md` mirrors the same content for Stitch prompting
+
+Use this skill when:
+
+- the project has no persistent design context yet
+- a multi-screen Stitch effort is starting
+- the design system has materially changed since the last Stitch pass

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/stitch-design-system/references/design-template.md

@@ -0,0 +1,47 @@
+# DESIGN.md Template
+
+Use this structure for `docs/foundation/DESIGN.md`, then mirror the same content to `.stitch/DESIGN.md`.
+
+```markdown
+# Design System: [Project Name]
+
+## 1. Visual Theme And Atmosphere
+- product mood
+- audience
+- density and composition
+
+## 2. Color Palette And Roles
+- primary action
+- surface
+- border
+- text primary / secondary
+- semantic states
+
+## 3. Typography Rules
+- display voice
+- body text behavior
+- label and table text behavior
+
+## 4. Component Stylings
+- buttons
+- cards and containers
+- forms
+- navigation
+- tables or lists
+
+## 5. Layout Principles
+- spacing rhythm
+- grid or shell rules
+- responsive priorities
+
+## 6. Motion And Interaction
+- transitions
+- hover and focus behavior
+- reduced-motion expectations
+```
+
+## Mirror contract
+
+- `docs/foundation/DESIGN.md` is canonical
+- `.stitch/DESIGN.md` mirrors it for Stitch-oriented flows
+- both files should describe the same system, not drift apart