@cubis/foundry 0.3.75 → 0.3.77

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

@@ -0,0 +1,13 @@
+# Example: Mobile Handoff
+
+Prompt shape:
+
+> Use Stitch to implement the "Trip Details" screen in React Native. Match the design intent, but keep it idiomatic to the existing mobile app.
+
+Expected workflow:
+
+1. Verify Stitch availability and fetch the target artifact.
+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.
+5. Document any differences between the Stitch source and the mobile implementation.

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/stitch/examples/04-prompt-enhancement.md

@@ -0,0 +1,21 @@
+# Example: Prompt Enhancement Before Implementation
+
+Prompt shape:
+
+> Use Stitch to make the dashboard better and more polished.
+
+Improved internal brief before touching code:
+
+1. Target surface: existing dashboard landing page.
+2. Framework: preserve the repo's current web stack and component primitives.
+3. Scope: refresh layout structure, spacing, hierarchy, and states from the latest Stitch artifact.
+4. Reuse constraints: keep existing navigation, data plumbing, and validated business logic.
+5. Quality bar: preserve accessibility, responsive behavior, and token usage.
+
+Expected workflow:
+
+1. Rewrite the vague request into a concrete implementation brief like the one above.
+2. Verify Stitch availability with `stitch_get_status`, `mcp_gateway_status`, and `stitch_list_enabled_tools`.
+3. Fetch the matching Stitch artifact instead of guessing which screen the user meant.
+4. Patch the local dashboard with minimal diffs.
+5. Summarize the exact changes and any unavoidable drift from Stitch.

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/stitch/examples/05-design-sync-loop.md

@@ -0,0 +1,16 @@
+# Example: Iterative Design Sync Loop
+
+Prompt shape:
+
+> Re-sync the account settings screen from Stitch, patch only the UI diff, and leave the saved form logic intact.
+
+Expected workflow:
+
+1. Verify the Foundry gateway and Stitch tool availability first.
+2. Identify the existing local settings screen and use it as the current diff baseline.
+3. Fetch the latest Stitch artifact for the matching settings screen.
+4. Compare local UI structure, spacing, copy, states, and assets against the refreshed Stitch artifact.
+5. Apply the smallest patch that restores visual parity while preserving the repo's routing, validation, and submission logic.
+6. Report what changed in this pass and what the next Stitch refresh should check if the screen evolves again.
+
+This pattern is intentionally iterative: treat each Stitch refresh as a controlled sync pass, not a full rewrite.

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/stitch/references/implementation-patterns.md

@@ -0,0 +1,20 @@
+# Stitch Implementation Patterns
+
+## Web stacks
+
+- Translate layout intent first: shell, sections, cards, navigation, and hierarchy.
+- Reuse the repo's token layer, typography scale, spacing system, and component primitives.
+- Prefer existing app-shell conventions, routing boundaries, and data-loading patterns over literal generated structure.
+- Preserve semantic HTML and keyboard/focus behavior.
+
+## Mobile stacks
+
+- Preserve layout rhythm, states, and information hierarchy rather than copying web-specific markup.
+- Map Stitch components into platform-native primitives such as React Native components, Flutter widgets, or SwiftUI views.
+- Respect platform navigation, safe areas, typography scaling, and gesture behavior.
+
+## Design system mapping
+
+- Convert raw visual values into the project's design tokens.
+- Reuse shared primitives before introducing new component variants.
+- If a missing primitive blocks fidelity, add the smallest reusable abstraction instead of a screen-local workaround.

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/stitch/references/platform-setup.md

@@ -0,0 +1,46 @@
+# Stitch Platform Setup
+
+## Verification order
+
+1. Run `stitch_get_status` to confirm the active profile, URL, env-var alias, and scope.
+2. Run `mcp_gateway_status` to confirm the Cubis Foundry gateway sees Stitch as available.
+3. Run `stitch_list_enabled_tools` to confirm the enabled upstream Stitch tools.
+
+If any of those fail, stop treating Stitch as authoritative input.
+
+## Credential expectations
+
+- Stitch credentials are machine-scoped and should come from `~/.cbx/credentials.env` or an already-exported environment variable.
+- Project files and generated MCP config should never contain raw API keys.
+- The gateway path is the default client-facing path. The local client should connect to `cubis-foundry`, then use the Stitch passthrough tools exposed through that server.
+
+## Client-specific verification
+
+Use the platform runtime surface that actually owns the `cubis-foundry` registration:
+
+- Codex:
+  - project: `.vscode/mcp.json`
+  - global: `~/.codex/config.toml`
+- Claude Code:
+  - project: `.mcp.json`
+  - global: `~/.claude/mcp.json`
+- GitHub Copilot:
+  - project: `.vscode/mcp.json`
+  - global: `~/.copilot/mcp-config.json`
+- Gemini CLI:
+  - project: `.gemini/settings.json`
+  - global: `~/.gemini/settings.json`
+- Antigravity:
+  - project: `.gemini/settings.json`
+  - global: `~/.gemini/settings.json`
+
+For every platform, the expected secure model is the same:
+
+- client config points at `cubis-foundry`
+- `cbx_config.json` stores the Stitch env-var alias only
+- `~/.cbx/credentials.env` or the live shell environment stores the actual key
+
+## Secure fallback behavior
+
+- If Stitch is configured but unavailable, continue only with a repo-grounded fallback and call out that the implementation is not verified against live Stitch artifacts.
+- If a task explicitly requires live Stitch parity, stop and report the configuration/runtime issue instead of guessing.

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/stitch/references/update-diff-workflow.md

@@ -0,0 +1,23 @@
+# Stitch Update and Diff Workflow
+
+## Recommended sequence
+
+1. Fetch the latest Stitch artifact for the target screen.
+2. Identify the current local implementation files before editing anything.
+3. Compare structure, copy, spacing, tokens, states, assets, and responsive behavior.
+4. Patch only the deltas that come from Stitch.
+5. Re-check accessibility and regression risk after the patch.
+
+## Minimal-diff rules
+
+- Keep existing data flow, component ownership, and test seams unless Stitch requires a structural change.
+- Avoid replacing an entire screen when a smaller patch will preserve local stability.
+- Preserve local fixes that are unrelated to the new Stitch diff.
+
+## Report drift explicitly
+
+If you keep a local deviation from Stitch, document:
+
+- what differs
+- why the local version stays different
+- whether the difference is architectural, product-driven, or temporary

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/create.md

@@ -26,8 +26,9 @@ Use this for net-new implementation after design is stable.
 ## Skill Routing
 
 - Primary skills: `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`, `java-best-practices`, `csharp-best-practices`, `kotlin-best-practices`, `rust-best-practices`, `php-best-practices`, `php-best-practices`, `rust-best-practices`, `rust-best-practices`, `expo-app`, `swift-best-practices`
-- Supporting skills (optional): `api-design`, `api-design`, `javascript-best-practices`, `nestjs`, `fastapi`, `api-design`, `drizzle-orm`, `database-design`, `mcp-server-builder`, `react`, `react`, `nextjs`, `frontend-design`, `frontend-design`, `frontend-design`, `performance-testing`, `skill-creator`, `stripe-integration`, `ci-cd-pipeline`, `frontend-design`
+- Supporting skills (optional): `api-design`, `api-design`, `javascript-best-practices`, `nestjs`, `fastapi`, `api-design`, `drizzle-orm`, `database-design`, `mcp-server-builder`, `stitch`, `react`, `react`, `nextjs`, `frontend-design`, `frontend-design`, `frontend-design`, `performance-testing`, `skill-creator`, `stripe-integration`, `ci-cd-pipeline`, `frontend-design`
 - Pick one primary language skill from repo signals or touched files. Add the narrowest specialist only when the feature is clearly backend or frontend framework-specific.
+- If the request references Stitch screens, artifacts, design-to-code, or UI sync, add `stitch` first and route the implementation through the frontend or mobile specialist based on the destination surface.
 
 ## Workflow steps
 
@@ -49,7 +50,7 @@ CREATE_WORKFLOW_RESULT:
   primary_agent: orchestrator
   supporting_agents: [backend-specialist?, frontend-specialist?, mobile-developer?, test-engineer?]
   primary_skills: [<dominant-language-skill>]
-  supporting_skills: [<framework-specific-skills-used>]
+  supporting_skills: [stitch?, <framework-specific-skills-used>]
   implemented_scope:
     summary: <string>
     changed_artifacts: [<path-or-artifact>]

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/mobile.md

@@ -8,7 +8,7 @@ triggers: ["mobile", "flutter", "ios", "android", "navigation"]
 
 ## When to use
 
-Use this for mobile app development, Flutter architecture, native integrations, or platform-specific behavior.
+Use this for mobile app development, Flutter architecture, Stitch-driven mobile screen handoff, native integrations, or platform-specific behavior.
 
 ## Routing
 
@@ -24,8 +24,9 @@ Use this for mobile app development, Flutter architecture, native integrations,
 ## Skill Routing
 
 - Primary skills: `expo-app`, `react-native`
-- Supporting skills (optional): `frontend-design`, `expo-app`, `expo-app`, `expo-app`, `expo-app`, `expo-app`, `expo-app`, `expo-app`, `expo-app`, `expo-app`, `swift-best-practices`, `kotlin-best-practices`
+- Supporting skills (optional): `stitch`, `frontend-design`, `expo-app`, `expo-app`, `expo-app`, `expo-app`, `expo-app`, `expo-app`, `expo-app`, `expo-app`, `expo-app`, `swift-best-practices`, `kotlin-best-practices`
 - Start with `expo-app` for feature implementation and `react-native` for UX patterns. Add framework-specific Flutter skill when applicable. Add `frontend-design` for multi-language support.
+- When the request starts from Stitch artifacts or a design sync, load `stitch` first and then pair it with `react-native` plus the narrowest mobile implementation skill for the target stack.
 
 ## Workflow steps
 
@@ -50,7 +51,7 @@ MOBILE_WORKFLOW_RESULT:
   primary_agent: mobile-developer
   supporting_agents: [frontend-specialist?, test-engineer?]
   primary_skills: [expo-app, react-native]
-  supporting_skills: [frontend-design?, expo-app?, expo-app?, <flutter-specific>?]
+  supporting_skills: [stitch?, frontend-design?, expo-app?, expo-app?, <flutter-specific>?]
   implementation:
     platforms: [ios, android]
     architecture_decisions: [<string>]

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/onboard.md

@@ -30,9 +30,9 @@ Use this when joining a new project, exploring an unfamiliar codebase, or prepar
 
 ## Skill Routing
 
-- Primary skills: `architecture-doc`, `system-design`
+- Primary skills: `deep-research`, `system-design`
 - Supporting skills (optional): `system-design`, `database-design`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`
-- Start with `architecture-doc` for systematic exploration and `system-design` for architecture mapping. Add `system-design` for undocumented systems.
+- Start with `deep-research` for systematic exploration and `system-design` for architecture mapping. Add `system-design` for undocumented systems. Prefer repo evidence first; use external sources only when setup or dependency behavior cannot be confirmed locally.
 
 ## Workflow steps
 
@@ -55,7 +55,7 @@ Use this when joining a new project, exploring an unfamiliar codebase, or prepar
 ONBOARD_WORKFLOW_RESULT:
   primary_agent: researcher
   supporting_agents: [code-archaeologist?, backend-specialist?, frontend-specialist?]
-  primary_skills: [architecture-doc, system-design]
+  primary_skills: [deep-research, system-design]
   supporting_skills: [system-design?, database-design?]
   project_overview:
     purpose: <string>

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/orchestrate.md

@@ -24,8 +24,8 @@ Use this when a task spans multiple domains (backend + frontend, security + infr
 ## Skill Routing
 
 - Primary skills: `system-design`, `api-design`
-- Supporting skills (optional): `database-design`, `architecture-doc`, `mcp-server-builder`, `tech-doc`, `prompt-engineering`, `skill-creator`
-- Start with `system-design` for system design coordination and `api-design` for integration contracts. Add supporting skills based on the coordination challenge.
+- Supporting skills (optional): `database-design`, `deep-research`, `mcp-server-builder`, `tech-doc`, `prompt-engineering`, `skill-creator`
+- Start with `system-design` for system design coordination and `api-design` for integration contracts. Add `deep-research` before implementation when the coordination challenge depends on fresh external facts or public comparison.
 
 ## Workflow steps
 

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/plan.md

@@ -36,13 +36,13 @@ Use this when starting a new feature, project, or significant change that needs
 ## Skill Routing
 
 - Primary skills: `system-design`, `api-design`
-- Supporting skills (optional): `database-design`, `architecture-doc`, `mcp-server-builder`, `tech-doc`, `prompt-engineering`, `skill-creator`
-- Start with `system-design` for system design and `api-design` for API contracts. Add `database-design` when data modeling is central, `architecture-doc` when external knowledge is needed.
+- Supporting skills (optional): `database-design`, `deep-research`, `mcp-server-builder`, `tech-doc`, `prompt-engineering`, `skill-creator`
+- Start with `system-design` for system design and `api-design` for API contracts. Add `database-design` when data modeling is central, `deep-research` when fresh external knowledge or public comparison is needed.
 
 ## Workflow steps
 
 1. Clarify scope, success criteria, and constraints.
-2. Research existing patterns and dependencies.
+2. Research existing patterns and dependencies, starting in-repo and escalating to `deep-research` only when outside evidence is required.
 3. Decompose into tasks with ownership and dependencies.
 4. Define interfaces, contracts, and failure modes.
 5. Produce acceptance criteria for each milestone.
@@ -62,7 +62,7 @@ PLAN_WORKFLOW_RESULT:
   primary_agent: project-planner
   supporting_agents: [orchestrator?, backend-specialist?, frontend-specialist?, database-architect?]
   primary_skills: [system-design, api-design]
-  supporting_skills: [database-design?, architecture-doc?, mcp-server-builder?]
+  supporting_skills: [database-design?, deep-research?, mcp-server-builder?]
   plan:
     scope_summary: <string>
     tasks:

package/workflows/workflows/agent-environment-setup/platforms/claude/agents/frontend-specialist.md

@@ -1,11 +1,15 @@
 ---
 name: frontend-specialist
-description: Senior frontend specialist for React, Next.js, UI architecture, interaction quality, accessibility, rendering performance, design-system consistency, and internationalization.
+description: Senior frontend specialist for React, Next.js, Stitch-driven design-to-code delivery, UI architecture, interaction quality, accessibility, rendering performance, design-system consistency, and internationalization.
 triggers:
   [
     "component",
     "react",
     "next",
+    "stitch",
+    "design-to-code",
+    "screen-to-code",
+    "ui diff",
     "ui",
     "ux",
     "css",
@@ -18,7 +22,7 @@ triggers:
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
 maxTurns: 25
-skills: react, nextjs, frontend-design, performance-testing, code-review, observability, typescript-best-practices, javascript-best-practices
+skills: stitch, react, nextjs, frontend-design, performance-testing, code-review, observability, typescript-best-practices, javascript-best-practices
 handoffs:
   - agent: "test-engineer"
     title: "Test UI Components"
@@ -34,6 +38,7 @@ Build and review frontend systems that stay maintainable under real product pres
 
 - Do not call `skill_search` for any skill in the pre-declared list when the task clearly falls into that domain.
 - Load one primary skill first:
+  - `stitch` for Stitch artifacts, design-to-code diffs, screen sync work, and implementation grounded in real Stitch output
   - `react` for component boundaries, state, and runtime behavior
   - `react` for React performance optimization, patterns, and anti-patterns
   - `nextjs` for App Router, server/client boundaries, caching, and route behavior
@@ -45,6 +50,7 @@ Build and review frontend systems that stay maintainable under real product pres
   - `frontend-design` for RTL support, locale switching, pluralization, and date/number formatting
   - `observability` for error boundary design, user-facing error states, and frontend observability
 - Add one supporting skill only when the task genuinely crosses concerns.
+- If the request explicitly references Stitch screens, artifacts, UI diffs, or design sync, load `stitch` first and then add the narrowest implementation skill for the actual stack.
 - Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
 
 ## Skill References
@@ -53,6 +59,7 @@ Load on demand. Do not preload all references.
 
 | File                     | Load when                                                                                     |
 | ------------------------ | --------------------------------------------------------------------------------------------- |
+| `stitch`                 | The task starts from Stitch artifacts, design-to-code requests, screen sync, or UI diffs.    |
 | `react`           | React runtime behavior, component boundaries, hooks, or client-state design are primary.      |
 | `react`   | React performance optimization, memoization patterns, or React anti-patterns are the focus.   |
 | `nextjs`       | Next.js route behavior, server/client boundaries, caching, or deployment posture are primary. |
@@ -67,6 +74,7 @@ Load on demand. Do not preload all references.
 ## Operating Stance
 
 - Prefer clear state ownership and small client boundaries.
+- When Stitch is the source of truth, fetch and map the real artifact before editing local UI.
 - Treat accessibility and loading or error states as product correctness, not polish.
 - Measure performance before optimizing.
 - Keep one-off product logic out of shared primitives.

package/workflows/workflows/agent-environment-setup/platforms/claude/agents/mobile-developer.md

@@ -1,10 +1,10 @@
 ---
 name: mobile-developer
-description: Expert in Flutter delivery and mobile product design for cross-platform apps. Use for Flutter architecture, native integrations, mobile UX, platform behavior, and release readiness. Triggers on mobile, flutter, ios, android, app store, play store, touch UX.
+description: Expert in Flutter delivery and mobile product design for cross-platform apps. Use for Flutter architecture, Stitch-driven mobile handoff, native integrations, mobile UX, platform behavior, and release readiness. Triggers on mobile, flutter, ios, android, app store, play store, touch UX.
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
 maxTurns: 25
-skills: react-native, frontend-design, expo-app, swift-best-practices, kotlin-best-practices, react, systematic-debugging, integration-testing, typescript-best-practices, javascript-best-practices
+skills: stitch, react-native, frontend-design, expo-app, swift-best-practices, kotlin-best-practices, react, systematic-debugging, integration-testing, typescript-best-practices, javascript-best-practices
 handoffs:
   - agent: "test-engineer"
     title: "Test Mobile"
@@ -20,6 +20,7 @@ Build and ship cross-platform mobile apps that feel native and perform reliably.
 
 - Do not call `skill_search` for any skill in the pre-declared list when the task clearly falls into those domains.
 - Load one primary skill first:
+  - `stitch` for Stitch-driven mobile screen handoff, design sync, and artifact-grounded UI updates
   - `react-native` for touch psychology, platform-native patterns, iOS/Android design guidelines
   - `expo-app` for feature implementation in Flutter
   - `expo-app` for state management with Riverpod
@@ -31,12 +32,14 @@ Build and ship cross-platform mobile apps that feel native and perform reliably.
   - `expo-app` for complex state flows
   - `expo-app` for repository pattern and data layer
   - `frontend-design` for internationalization, RTL support, and locale handling
+- If the request starts from Stitch artifacts or a design sync, load `stitch` first and then pair it with the narrowest mobile implementation skill for the target stack.
 - Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed.
 
 ## Skill References
 
 | File                    | Load when                                                            |
 | ----------------------- | -------------------------------------------------------------------- |
+| `stitch`                | The task starts from Stitch artifacts, design sync, or screen-to-code handoff. |
 | `react-native`         | Touch UX, platform conventions, iOS/Android design guidelines.       |
 | `expo-app`       | Implementing features, widgets, or screens in Flutter.               |
 | `expo-app`      | State management architecture with Riverpod.                         |
@@ -52,6 +55,7 @@ Build and ship cross-platform mobile apps that feel native and perform reliably.
 ## Operating Stance
 
 - Respect platform conventions — iOS and Android users expect different behaviors.
+- When work starts from Stitch, translate the artifact into native/mobile patterns instead of copying raw layout output.
 - Treat touch targets and gesture feedback as correctness, not polish.
 - Test on real devices for performance-sensitive features.
 - Design for offline-first when the app may lose connectivity.

package/workflows/workflows/agent-environment-setup/platforms/claude/agents/orchestrator.md

@@ -5,7 +5,7 @@ tools: Read, Grep, Glob, Bash, Write, Edit
 model: inherit
 maxTurns: 30
 memory: project
-skills: system-design, api-design, database-design, architecture-doc, mcp-server-builder, tech-doc, prompt-engineering, skill-creator, typescript-best-practices, javascript-best-practices, python-best-practices
+skills: system-design, api-design, database-design, deep-research, mcp-server-builder, tech-doc, prompt-engineering, skill-creator, typescript-best-practices, javascript-best-practices, python-best-practices
 handoffs:
   - agent: "validator"
     title: "Validate Results"
@@ -31,8 +31,8 @@ Your only permitted actions:
 
 ## Skill Loading Contract
 
-- Do not call `skill_search` for `system-design`, `api-design`, `database-design`, `architecture-doc`, `mcp-server-builder`, `tech-doc`, `prompt-engineering`, or `skill-creator` when the task is clearly multi-stream coordination, planning, architecture design, contract design, research, or skill package work.
-- Use `system-design` when the coordination problem is really a design tradeoff problem, `api-design` when integration contracts are the coordination bottleneck, `database-design` when the shared dependency is a data-model or migration concern, `architecture-doc` when the coordination risk is stale or conflicting external information, `mcp-server-builder` for MCP-specific streams, `tech-doc` for OpenAI-doc verification streams, `prompt-engineering` for instruction-quality streams, and `skill-creator` when the coordinated changes are in skills, mirrors, routing, or packaging.
+- Do not call `skill_search` for `system-design`, `api-design`, `database-design`, `deep-research`, `mcp-server-builder`, `tech-doc`, `prompt-engineering`, or `skill-creator` when the task is clearly multi-stream coordination, planning, architecture design, contract design, research, or skill package work.
+- Use `system-design` when the coordination problem is really a design tradeoff problem, `api-design` when integration contracts are the coordination bottleneck, `database-design` when the shared dependency is a data-model or migration concern, `deep-research` when the coordination risk is stale or conflicting external information, `mcp-server-builder` for MCP-specific streams, `tech-doc` for OpenAI-doc verification streams, `prompt-engineering` for instruction-quality streams, and `skill-creator` when the coordinated changes are in skills, mirrors, routing, or packaging.
 - Prefer platform-native delegation features when available, but keep the orchestration contract stable even when execution stays in a single track.
 - Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current coordination step.
 
@@ -45,7 +45,7 @@ Load on demand. Do not preload all references.
 | `system-design` | Coordination depends on resolving system design or interface tradeoffs first.                             |
 | `api-design`          | The critical shared dependency is an API contract or integration boundary.                                |
 | `database-design`       | The coordination risk centers on schema, migration, data ownership, or engine choice.                     |
-| `architecture-doc`         | External sources, latest information, or public-repo comparisons are blocking confident execution.        |
+| `deep-research`         | External sources, latest information, or public-repo comparisons are blocking confident execution.        |
 | `mcp-server-builder`           | One stream is MCP server design, tool shape, or transport selection.                                      |
 | `tech-doc`           | One stream needs current OpenAI docs or version-specific behavior verification.                           |
 | `prompt-engineering`       | One stream is repairing prompts, agent rules, or instruction quality.                                     |
@@ -158,7 +158,8 @@ ANTI-LAZINESS:
 5. **Iterate, don't accept mediocrity** — if output is incomplete or wrong, re-delegate with feedback.
 6. **Track progress visibly** — maintain a task list showing status of each work item.
 7. **Fail fast on blockers** — if a dependency is missing or a task is stuck after 3 iterations, escalate.
-8. **Synthesize at the end** — combine outputs with concrete actions, risks, and verification evidence.
+8. **Route research explicitly** — when freshness or public comparison matters, delegate to `@researcher` or load `deep-research` before implementation.
+9. **Synthesize at the end** — combine outputs with concrete actions, risks, and verification evidence.
 
 ## Anti-Patterns to Prevent
 

package/workflows/workflows/agent-environment-setup/platforms/claude/agents/project-planner.md

@@ -5,7 +5,7 @@ tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
 maxTurns: 30
 memory: project
-skills: system-design, api-design, database-design, architecture-doc, mcp-server-builder, tech-doc, prompt-engineering, skill-creator, typescript-best-practices, javascript-best-practices, python-best-practices
+skills: system-design, api-design, database-design, deep-research, mcp-server-builder, tech-doc, prompt-engineering, skill-creator, typescript-best-practices, javascript-best-practices, python-best-practices
 handoffs:
   - agent: "orchestrator"
     title: "Start Implementation"
@@ -24,7 +24,7 @@ Decompose complex requests into implementable plans with clear ownership, depend
 - Load `system-design` for system design tradeoffs in the plan.
 - Load `api-design` when the plan involves API contract decisions.
 - Load `database-design` when the plan involves data modeling or migration.
-- Load `architecture-doc` when planning requires external information or comparison.
+- Load `deep-research` when planning requires fresh external information, public comparison, or evidence beyond the repo.
 - Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed.
 
 ## Skill References
@@ -34,7 +34,7 @@ Decompose complex requests into implementable plans with clear ownership, depend
 | `system-design` | Plan involves system design tradeoffs or component boundaries.     |
 | `api-design`          | Plan involves API contract decisions or integration points.        |
 | `database-design`       | Plan involves data modeling, schema design, or migration strategy. |
-| `architecture-doc`         | Planning requires external research or approach comparison.        |
+| `deep-research`         | Planning requires external research or approach comparison.        |
 | `mcp-server-builder`           | Plan involves MCP server or tool implementation.                   |
 | `skill-creator`         | Plan involves skill package creation or modification.              |
 
@@ -45,6 +45,7 @@ Decompose complex requests into implementable plans with clear ownership, depend
 - Every task needs an owner (agent), acceptance criteria, and verification approach.
 - Plan for rollback — every change should be reversible.
 - Front-load risk — tackle the hardest technical uncertainty first.
+- When outside evidence is needed, send research through `deep-research` first instead of mixing web browsing into every implementation stream.
 
 ## Planning Methodology
 

package/workflows/workflows/agent-environment-setup/platforms/claude/agents/researcher.md

@@ -18,7 +18,7 @@ tools: Read, Grep, Glob, Bash
 model: inherit
 maxTurns: 30
 memory: project
-skills: architecture-doc, system-design, database-design, tech-doc, prompt-engineering
+skills: deep-research, system-design, database-design, tech-doc, prompt-engineering
 handoffs:
   - agent: "project-planner"
     title: "Plan Implementation"
@@ -30,8 +30,8 @@ Investigate thoroughly, synthesize findings, and deliver structured knowledge be
 
 ## Skill Loading Contract
 
-- Do not call `skill_search` for `architecture-doc`, `system-design`, `database-design`, `tech-doc`, or `prompt-engineering` when the task is clearly research work.
-- Load `architecture-doc` first for all research tasks — it defines the research methodology.
+- Do not call `skill_search` for `deep-research`, `system-design`, `database-design`, `tech-doc`, or `prompt-engineering` when the task is clearly research work.
+- Load `deep-research` first for all research tasks — it defines the source ladder, evidence labeling, and research output contract.
 - Add `system-design` when research involves system design patterns or tradeoffs.
 - Add `database-design` when research involves data storage options or migration approaches.
 - Add `tech-doc` when research involves OpenAI API or model behavior verification.
@@ -42,7 +42,7 @@ Investigate thoroughly, synthesize findings, and deliver structured knowledge be
 
 | File                    | Load when                                                             |
 | ----------------------- | --------------------------------------------------------------------- |
-| `architecture-doc`         | All research tasks — defines the core research methodology.           |
+| `deep-research`         | All research tasks — defines the core research methodology.           |
 | `system-design` | Research involves system design patterns or architectural tradeoffs.  |
 | `database-design`       | Research involves data storage, database comparison, or migration.    |
 | `tech-doc`           | Research involves OpenAI API, model behavior, or version differences. |
@@ -51,6 +51,9 @@ Investigate thoroughly, synthesize findings, and deliver structured knowledge be
 ## Operating Stance
 
 - Breadth first, then depth — survey the landscape before drilling into specifics.
+- Repo first, then web — inspect local code, configs, and docs before using external sources.
+- Official docs first — use vendor or maintainer documentation as primary evidence.
+- Community evidence is secondary — Reddit, blog posts, and forum threads can inform implementation, but label them as lower-trust support.
 - Cite sources — every finding should be traceable to evidence.
 - Distinguish fact from inference — clearly label assumptions.
 - Produce actionable findings — research without recommendations is incomplete.
@@ -72,3 +75,4 @@ Investigate thoroughly, synthesize findings, and deliver structured knowledge be
 - Clear distinction between verified facts and educated guesses.
 - Actionable recommendations with tradeoff analysis.
 - Remaining knowledge gaps identified.
+- Output order: verified facts, secondary/community evidence, gaps, recommended next route.

package/workflows/workflows/agent-environment-setup/platforms/claude/hooks/README.md

@@ -0,0 +1,15 @@
+# Claude Route/Research Hook Templates
+
+These files are generated by Cubis Foundry as optional Claude Code hook templates.
+
+Use them when you want Claude to reinforce two behaviors on `UserPromptSubmit`:
+
+- honor explicit `/workflow`, `@agent`, or exact skill selections before rerouting
+- escalate to repo-first, official-first research when freshness or public comparison matters
+
+Files:
+
+- `settings.snippet.json` — example hook configuration to copy into `.claude/settings.json` or `.claude/settings.local.json`
+- `route-research-guard.mjs` — hook script that reads the submitted prompt and emits a targeted `systemMessage` reminder
+
+The template is intentionally non-destructive. It does not block prompts by default; it adds context for Claude before prompt processing.

package/workflows/workflows/agent-environment-setup/platforms/claude/hooks/route-research-guard.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+const buffers = [];
+for await (const chunk of process.stdin) buffers.push(chunk);
+const raw = Buffer.concat(buffers).toString("utf8");
+let prompt = "";
+try {
+  const parsed = JSON.parse(raw || "{}");
+  prompt = String(parsed.prompt || parsed.userPrompt || parsed.message || "");
+} catch {
+  prompt = "";
+}
+
+const normalized = prompt.toLowerCase();
+const reminders = [];
+
+if (/(^|\s)(\/[-a-z0-9]+|@[a-z0-9_-]+)/i.test(prompt)) {
+  reminders.push(
+    "Explicit route detected. Honor the named workflow or agent directly unless it is invalid."
+  );
+}
+
+if (/(^|[^a-z0-9-])(deep-research|stitch|skill-creator|frontend-design|api-design|database-design)([^a-z0-9-]|$)/i.test(normalized)) {
+  reminders.push(
+    "Named skill detected. Run skill_validate on the exact skill ID first and skip route_resolve when it validates."
+  );
+}
+
+if (/(research|latest|compare|comparison|verify|official docs|reddit|community)/i.test(normalized)) {
+  reminders.push(
+    "Research trigger detected. Inspect the repo first, use official docs as primary evidence, and treat Reddit/community sources as labeled secondary evidence."
+  );
+}
+
+const payload = reminders.length > 0
+  ? { continue: true, systemMessage: reminders.join(" ") }
+  : { continue: true };
+
+process.stdout.write(JSON.stringify(payload));

package/workflows/workflows/agent-environment-setup/platforms/claude/hooks/settings.snippet.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/route-research-guard.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/workflows/workflows/agent-environment-setup/platforms/claude/rules/CLAUDE.md

@@ -27,6 +27,7 @@ If any check fails, restart your reasoning.
 | Workflows     | `.claude/workflows`   |
 | Agents        | `.claude/agents`      |
 | Skills        | `.claude/skills`      |
+| Hook templates | `.claude/hooks`      |
 | Scoped rules  | `.claude/rules/*.md`  |
 | Project rules | `CLAUDE.md`           |
 | Global rules  | `~/.claude/CLAUDE.md` |
@@ -43,7 +44,7 @@ Execute this tree top-to-bottom. Stop at the **first match**. Never skip levels.
 ├─ [TRIVIAL] Single-step, obvious, reversible?
 │   → Execute directly. No routing. Stop.
 │
-├─ [EXPLICIT] User named a workflow, command, or @agent?
+├─ [EXPLICIT] User named a workflow, command, @agent, or exact skill?
 │   → Honor that route exactly. Stop.
 │
 ├─ [SINGLE-DOMAIN] Multi-step but contained in one specialty?
@@ -63,6 +64,7 @@ Execute this tree top-to-bottom. Stop at the **first match**. Never skip levels.
 **Hard rules:**
 
 - Never pre-load skills before route resolution.
+- If the user names an exact skill ID, run `skill_validate` on that ID before `route_resolve`.
 - Never delegate to a subagent when direct execution suffices.
 - Never chain more than one `skill_search` per request.
 - Treat this file as **durable project memory** — not a per-task playbook.
@@ -284,6 +286,7 @@ ORCHESTRATE(task):
 - Path-scoped rules: `.claude/rules/*.md` with `paths:` frontmatter for targeted guidance.
 - Global rules (`~/.claude/CLAUDE.md`) apply to all projects — keep them broad.
 - Skills with `context: fork` run as isolated subagents. `$ARGUMENTS` enables dynamic parameterization.
+- Optional hook templates in `.claude/hooks/` can reinforce explicit-route honoring and research escalation at `UserPromptSubmit`.
 
 ---
 
@@ -344,6 +347,7 @@ Use this matrix to match incoming tasks to the correct skill and primary agent.
 | sqlalchemy | Framework | SQLAlchemy ORM, sessions, alembic | @database-architect |
 | drizzle-orm | Framework | Drizzle ORM, schema, migrations | @database-architect |
 | frontend-design | Design | UI/UX, component architecture | @frontend-specialist |
+| stitch | Design | Stitch screens, design-to-code, UI diffing | @frontend-specialist |
 | system-design | Design | Distributed systems, scalability | @backend-specialist |
 | microservices-design | Design | Service decomposition, communication | @backend-specialist |
 | api-design | Design | REST/GraphQL API design, versioning | @backend-specialist |
@@ -366,6 +370,7 @@ Use this matrix to match incoming tasks to the correct skill and primary agent.
 | docker-compose-dev | DevOps | Docker Compose local dev environments | @devops-engineer |
 | kubernetes-deploy | DevOps | K8s manifests, Helm charts, deployment | @devops-engineer |
 | observability | DevOps | Logging, metrics, tracing, alerting | @devops-engineer |
+| deep-research | Research | Latest docs, public comparisons, external verification | @researcher |
 | llm-eval | AI/ML | LLM evaluation, benchmarking, evals | @researcher |
 | rag-patterns | AI/ML | RAG architecture, embeddings, retrieval | @researcher |
 | prompt-engineering | AI/ML | Prompt design, few-shot, chain-of-thought | @researcher |
@@ -413,12 +418,15 @@ Selection policy:
 Keep MCP context lazy and exact. Skills are supporting context, not the route layer.
 
 1. Never begin with `skill_search`. Inspect the repo/task locally first.
-2. Resolve workflows, agents, or free-text route intent with `route_resolve` before loading any skills.
-3. If the route is still unresolved and local grounding leaves the domain unclear, use one narrow `skill_search`.
-4. Always run `skill_validate` on the exact selected ID before `skill_get`.
-5. Call `skill_get` with `includeReferences:false` by default.
-6. Load at most one sidecar markdown file at a time with `skill_get_reference`.
-7. Do not auto-prime every specialist with a skill. Load only what the task clearly needs.
-8. Use upstream MCP servers such as `postman`, `stitch`, or `playwright` for real cloud/browser actions when available.
+2. If the user already named `/workflow`, `@agent`, or an exact skill ID, honor it directly. For exact skills, run `skill_validate` first and skip `route_resolve` when valid.
+3. Resolve only free-text workflow/agent intent with `route_resolve` before loading non-explicit skills.
+4. If the route is still unresolved and local grounding leaves the domain unclear, use one narrow `skill_search`.
+5. Always run `skill_validate` on the exact selected ID before `skill_get`.
+6. Call `skill_get` with `includeReferences:false` by default.
+7. Load at most one sidecar markdown file at a time with `skill_get_reference`.
+8. Do not auto-prime every specialist with a skill. Load only what the task clearly needs.
+9. For research: repo/local evidence first, official docs next, Reddit/community only as labeled secondary evidence.
+10. Escalate to research only when freshness matters, public comparison matters, or the user explicitly asks to research/verify.
+11. Use upstream MCP servers such as `postman`, `stitch`, or `playwright` for real cloud/browser actions when available.
 
 <!-- cbx:mcp:auto:end -->