@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/gemini/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,17 +45,9 @@ 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. |
-
 ## Gemini Platform Notes
 
 - Workflow and agent routes are compiled into `.gemini/commands/*.toml` TOML command files.
@@ -64,6 +56,6 @@ Deliver:
 - 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: `.gemini/GEMINI.md`.
+- 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/spring-boot/SKILL.md

@@ -73,6 +73,6 @@ Provide implementation code, configuration properties, bean definitions, and arc
 - 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: `.gemini/GEMINI.md`.
+- 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/sqlalchemy/SKILL.md

@@ -82,6 +82,6 @@ No helper scripts are required for this skill right now. Keep execution in `SKIL
 - 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: `.gemini/GEMINI.md`.
+- 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/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,17 +55,15 @@ 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. |
 
-## Gemini Stitch Flow
+## Gemini Stitch Compatibility Flow
 
-- Activate the `stitch` skill inline, then verify the workspace or global `.gemini/settings.json` entry points at `cubis-foundry`.
-- Keep the flow sequential: gateway preflight, artifact fetch, framework mapping, local patch, verification.
-- When the prompt is vague, first rewrite it into a concrete implementation brief with target route, component boundaries, states, and responsive expectations before editing code.
+- 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 Gemini.
 
 ## Gemini Platform Notes
 
@@ -86,6 +73,6 @@ Use these when the task closely matches the example shape.
 - 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: `.gemini/GEMINI.md`.
+- 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/stitch-design-orchestrator/SKILL.md

@@ -0,0 +1,85 @@
+---
+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. |
+
+## Gemini 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 Gemini: allow one generation or edit action per turn by default, prefer `edit_screens` over full regeneration, and stop after two automatic retries with backoff.
+
+## 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/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/gemini/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/gemini/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/gemini/skills/stitch-design-system/SKILL.md

@@ -0,0 +1,75 @@
+---
+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. |
+
+## Gemini 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 Gemini.
+
+## 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/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/gemini/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

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/stitch-implementation-handoff/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: stitch-implementation-handoff
+description: Convert final Stitch screen artifacts into minimal, repo-native frontend changes by reusing local components, preserving validated logic, and documenting any intentional drift from the design source.
+---
+# Stitch Implementation Handoff
+
+## Purpose
+
+Turn the final Stitch artifact into production-ready UI changes without guessing the design. This skill owns the repo-native mapping step after Stitch generation or editing is finished.
+
+## When to Use
+
+- Implementing a new screen from a finalized Stitch artifact
+- Updating an existing screen from refreshed Stitch output
+- Performing design-to-code diffs against local UI
+- Translating Stitch output into React, Next.js, React Native, Flutter, SwiftUI, or another real project framework
+- Auditing whether the local screen still matches the current Stitch version
+
+## Instructions
+
+1. **Pull the actual final Stitch artifact before coding** — Use the latest screen artifact, metadata, and image/snapshot from Stitch. Do not reconstruct the screen from memory or from a stale prompt.
+
+2. **Map Stitch output into the repo's real stack** — Re-express the artifact in the project's framework, routing model, styling system, tokens, and component primitives.
+
+3. **Prefer local component reuse over one-off markup** — If the project already has buttons, cards, typography, navigation, or layout primitives, use those instead of cloning raw Stitch structure.
+
+4. **Keep diffs minimal on existing screens** — Compare the local implementation against the refreshed Stitch artifact and patch only the changed structure, spacing, copy, tokens, states, and assets.
+
+5. **Preserve business logic and architecture** — Keep local data flow, validation, submission logic, navigation contracts, and test seams unless the task explicitly requires structural changes.
+
+6. **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.
+
+7. **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.
+
+## Output Format
+
+Deliver:
+
+1. **Artifact summary** — which final 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 remaining gaps
+
+## References
+
+| File | Load when |
+| --- | --- |
+| `../stitch/references/platform-setup.md` | Need to verify Stitch availability, gateway status, or secure credential expectations. |
+| `../stitch/references/implementation-patterns.md` | Need guidance for mapping Stitch artifacts into web or mobile stacks and existing design systems. |
+| `../stitch/references/update-diff-workflow.md` | Updating an existing implementation from revised Stitch artifacts or running a UI diff workflow. |
+| `../frontend-design/references/component-architecture.md` | Need to map a Stitch screen into reusable primitives and composite components. |
+
+## Examples
+
+| 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. |
+
+## Gemini Stitch Implementation Handoff
+
+- Pull the final Stitch artifact before coding, then map it into the repo's real framework, tokens, routing, and components.
+- Preserve existing business logic, tests, and accessibility behavior while applying the UI diff.
+- Keep the result repo-native on Gemini: reuse local primitives and explain any intentional drift from the Stitch artifact.
+
+## 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/stitch-implementation-handoff/examples/01-new-screen.md

@@ -0,0 +1,12 @@
+# Example: New Screen From Stitch
+
+Prompt shape:
+
+> Use the finalized Stitch billing screen artifact and implement it in my Next.js app with the existing design system.
+
+Expected workflow:
+
+1. Confirm the final Stitch artifact is current.
+2. Identify the destination route, layout shell, and shared components in the repo.
+3. Implement the screen with project tokens and primitives instead of raw generated markup.
+4. Summarize any intentional deviations from Stitch.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/stitch-implementation-handoff/examples/02-update-existing-screen.md

@@ -0,0 +1,12 @@
+# Example: Update Existing Screen
+
+Prompt shape:
+
+> Re-fetch the latest Stitch profile settings artifact and patch my existing implementation in `app/settings/profile/page.tsx`. Only update the parts that changed.
+
+Expected workflow:
+
+1. Pull the refreshed Stitch artifact first.
+2. Compare the local screen against the latest design.
+3. Apply a minimal diff to structure, tokens, copy, or states.
+4. Preserve working local logic and component boundaries.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/stitch-implementation-handoff/examples/03-mobile-handoff.md

@@ -0,0 +1,12 @@
+# Example: Mobile Handoff
+
+Prompt shape:
+
+> Use the finalized Stitch trip-details artifact as the visual source for the React Native implementation.
+
+Expected workflow:
+
+1. Verify the final Stitch artifact and fetch the current screen metadata.
+2. Map the layout into the app's mobile navigation and component structure.
+3. Reuse tokens, spacing, and shared mobile primitives.
+4. Preserve safe areas, touch targets, text scaling, and loading/error states.