@cubis/foundry 0.3.75 → 0.3.77

package/workflows/workflows/agent-environment-setup/shared/agents/researcher.md

@@ -31,7 +31,7 @@ Investigate thoroughly, synthesize findings, and deliver structured knowledge be
 ## Skill Loading Contract
 
 - Do not call `skill_search` for `deep-research`, `architecture-designer`, `database-skills`, `openai-docs`, or `prompt-engineer` when the task is clearly research work.
-- Load `deep-research` first for all research tasks — it defines the research methodology.
+- Load `deep-research` first for all research tasks — it defines the source ladder, evidence labeling, and research output contract.
 - Add `architecture-designer` when research involves system design patterns or tradeoffs.
 - Add `database-skills` when research involves data storage options or migration approaches.
 - Add `openai-docs` when research involves OpenAI API or model behavior verification.
@@ -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/shared/rules/STEERING.md

@@ -1,9 +1,9 @@
 # Cubis Foundry — Shared Steering Protocol
 
-This is the canonical steering template. Platform-specific rules files are generated from this template
-plus per-platform overrides. Edit only here — never edit platform rules files directly.
+This is the canonical steering source for routing policy and managed MCP block language.
+Keep platform rule files aligned with this template plus per-platform overrides, and do not duplicate the managed block into agent or workflow markdown.
 
-Generation: `npm run generate:platform-assets` (or `cbx workflows sync-rules`)
+Managed-block sync: `npm run inject:mcp-rules:all` (or `cbx workflows sync-rules`)
 
 ---
 
@@ -17,6 +17,10 @@ Follow this decision tree for EVERY user request:
 │   └─ Execute directly. No routing needed. Stop.
 ├─ Did user explicitly name a workflow or agent?
 │   └─ Honor that route first. Stop.
+├─ Did user explicitly name an exact skill ID?
+│   └─ Run skill_validate on that exact ID.
+│       ├─ Valid? → Load it and proceed. Stop.
+│       └─ Invalid/unavailable? → Fall through. Do not guess.
 ├─ Is it multi-step work in ONE domain?
 │   └─ Pick the best-fit workflow. Load it. Stop.
 ├─ Is it cross-domain work spanning 2+ specialties?
@@ -28,6 +32,7 @@ Follow this decision tree for EVERY user request:
 ```
 
 > **Rule:** Inspect the repo and task locally BEFORE choosing a route or loading any skill.
+> **Rule:** If the user already chose the route, do not re-route it unless the named workflow, agent, or skill is invalid.
 
 ---
 
@@ -38,6 +43,7 @@ Follow this decision tree for EVERY user request:
 | **Direct execution** | No routing needed                     | Small, clear, single-step tasks                       | Just do it                                 | "rename this variable"                      |
 | **Workflow**         | Multi-step recipe with verification   | Structured task with known pattern                    | `/plan`, `/create`, `/debug`, `/test`      | "plan the auth system"                      |
 | **Agent**            | Specialist persona with domain skills | Domain expertise needed for execution                 | `@backend-specialist`, `@security-auditor` | "design the API schema"                     |
+| **Named skill**      | Exact skill selected by the user      | User already named the skill and it validates cleanly | `skill_validate` → `skill_get`             | "use stitch for this screen"                |
 | **Skill (MCP)**      | Supporting domain knowledge           | Domain context that a workflow or agent doesn't cover | `skill_get` after `skill_validate`         | loading `typescript-pro` for TS conventions |
 | **skill_search**     | Fuzzy discovery tool                  | Domain unclear, no skill ID known yet                 | One narrow search AFTER route_resolve      | "what skill covers Prisma?"                 |
 | **route_resolve**    | Intent → route mapper                 | Free-text request doesn't match any known route       | MCP tool call with task description        | "I need to optimize my database"            |
@@ -47,17 +53,41 @@ Follow this decision tree for EVERY user request:
 
 ## 3) Skill Loading Protocol
 
-Skills are **supporting context** — always route first, then load what the route recommends.
+Skills are **supporting context** unless the user explicitly named the exact skill. In that case validate the named skill first, then proceed without route discovery.
 
 1. **Never begin with `skill_search`.** Inspect the repo/task locally first.
-2. Resolve the route (workflow, agent, or direct execution) before loading any skills.
-3. **After routing: if `route_resolve` returned `primarySkillHint` or `primarySkills`, load the first via `skill_validate` → `skill_get` before executing. Not optional for non-trivial tasks.**
-4. If `detectedLanguageSkill` is returned and matches the project, load it too (if not already loaded this session).
-5. Domain still unclear after routing? → ONE narrow `skill_search`. Not two.
-6. Call `skill_get` with `includeReferences: false` by default.
-7. Load reference files one at a time with `skill_get_reference` — only when a specific reference is needed.
-8. Do not auto-prime every specialist. Only load what `primarySkills` recommends or the task clearly needs.
-9. Never pass workflow IDs or agent IDs to skill tools.
+2. If the user explicitly named an exact skill ID, run `skill_validate` on that ID before any `route_resolve` call.
+3. Resolve the route (workflow, agent, or direct execution) before loading any non-explicit skills.
+4. **After routing: if `route_resolve` returned `primarySkillHint` or `primarySkills`, load the first via `skill_validate` → `skill_get` before executing. Not optional for non-trivial tasks.**
+5. If `detectedLanguageSkill` is returned and matches the project, load it too (if not already loaded this session).
+6. Domain still unclear after routing? → ONE narrow `skill_search`. Not two.
+7. Call `skill_get` with `includeReferences: false` by default.
+8. Load reference files one at a time with `skill_get_reference` — only when a specific reference is needed.
+9. Do not auto-prime every specialist. Only load what `primarySkills` recommends or the task clearly needs.
+10. Never pass workflow IDs or agent IDs to skill tools.
+
+---
+
+## 4A) Research Escalation
+
+Use external research only when one of these is true:
+
+1. Freshness matters: latest APIs, model behavior, vendor docs, pricing, policies, releases, or client capabilities.
+2. Public comparison matters: tradeoff analysis across tools, frameworks, libraries, or hosted services.
+3. The user explicitly asks to research, compare, verify, or gather outside evidence.
+
+Research source ladder:
+
+1. **Repo/local evidence first** — inspect code, config, docs, tests, and installed artifacts before going outside the workspace.
+2. **Official docs next** — vendor docs, upstream repos, standards, or maintainer documentation are primary evidence.
+3. **Community evidence last** — Reddit, blog posts, issue threads, and forum posts are allowed only as labeled secondary evidence.
+
+Research output contract:
+
+- **Verified facts** — claims backed by primary sources or local repo evidence.
+- **Secondary/community evidence** — useful but lower-trust signals, clearly labeled.
+- **Gaps / unknowns** — what could not be verified.
+- **Recommended next route** — workflow, agent, or skill to use after research.
 
 ---
 
@@ -151,7 +181,8 @@ Use the best specialist first:
 2. Keep diffs small and reversible when possible.
 3. Verify with focused checks before finalizing.
 4. State what was NOT validated.
-5. Use web search only when information may be stale or the user explicitly asks.
+5. Use web search only when information may be stale, public comparison matters, or the user explicitly asks.
+6. Prefer official docs first. Treat Reddit/community sources as secondary evidence and label them that way.
 
 ---
 

package/workflows/workflows/agent-environment-setup/shared/rules/overrides/claude.md

@@ -5,6 +5,7 @@
 - Workflows: `.claude/workflows`
 - Agents: `.claude/agents`
 - Skills: `.claude/skills`
+- Hook templates: `.claude/hooks`
 - Rules file: `CLAUDE.md`
 - Scoped rules: `.claude/rules/*.md` (with `paths:` frontmatter)
 
@@ -26,4 +27,5 @@
 - Scoped rules in `.claude/rules/*.md` use `paths:` frontmatter for targeted file-pattern matching.
 - Global rules live in `~/.claude/CLAUDE.md` and apply to all projects.
 - Skills with `context: fork` spawn as isolated subagents for research-heavy or exploratory tasks.
+- Optional hook templates in `.claude/hooks/` can reinforce explicit-route honoring and research escalation at `UserPromptSubmit`.
 - Use `$ARGUMENTS` in skill content for dynamic parameterization from user queries.

package/workflows/workflows/agent-environment-setup/shared/rules/overrides/gemini.md

@@ -0,0 +1,20 @@
+# Gemini CLI — Platform Overrides
+
+## Platform Paths
+
+- Workflows: `.gemini/workflows`
+- Skills: `.gemini/skills`
+- Commands: `.gemini/commands`
+- Rules file: `.gemini/GEMINI.md` (or `GEMINI.md` at repo root when used directly)
+
+## Platform-Specific Routing
+
+1. **Explicit Gemini command** (`.gemini/commands/*.toml`) — highest priority route.
+2. **Explicit workflow or named skill** — honor it directly before route discovery.
+3. Standard workflow and MCP routing from shared steering.
+
+## Platform Notes
+
+- Gemini CLI uses GEMINI.md plus TOML commands as the primary enforcement surface.
+- Gemini specialist behavior is posture-based; it does not rely on standalone agent markdown in the project profile.
+- Use command wrappers to reinforce route-resolved execution and research escalation when freshness or public comparison matters.

package/workflows/workflows/agent-environment-setup/shared/workflows/create.md

@@ -26,8 +26,9 @@ Use this for net-new implementation after design is stable.
 ## Skill Routing
 
 - Primary skills: `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`, `java-pro`, `csharp-pro`, `kotlin-pro`, `rust-pro`, `php-pro`, `ruby-pro`, `c-pro`, `cpp-pro`, `dart-pro`, `swift-pro`
-- Supporting skills (optional): `api-designer`, `api-patterns`, `nodejs-best-practices`, `nestjs-expert`, `fastapi-expert`, `graphql-architect`, `drizzle-expert`, `firebase`, `mcp-builder`, `react-expert`, `react-best-practices`, `nextjs-developer`, `tailwind-patterns`, `frontend-design`, `design-system-builder`, `web-perf`, `skill-creator`, `stripe-best-practices`, `serverless-patterns`, `i18n-localization`
+- Supporting skills (optional): `api-designer`, `api-patterns`, `nodejs-best-practices`, `nestjs-expert`, `fastapi-expert`, `graphql-architect`, `drizzle-expert`, `firebase`, `mcp-builder`, `stitch`, `react-expert`, `react-best-practices`, `nextjs-developer`, `tailwind-patterns`, `frontend-design`, `design-system-builder`, `web-perf`, `skill-creator`, `stripe-best-practices`, `serverless-patterns`, `i18n-localization`
 - 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/shared/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: `flutter-feature`, `mobile-design`
-- Supporting skills (optional): `i18n-localization`, `flutter-riverpod`, `flutter-go-router`, `flutter-design-system`, `flutter-testing`, `flutter-drift`, `flutter-offline-sync`, `flutter-state-machine`, `flutter-repository`, `dart-pro`, `swift-pro`, `kotlin-pro`
+- Supporting skills (optional): `stitch`, `i18n-localization`, `flutter-riverpod`, `flutter-go-router`, `flutter-design-system`, `flutter-testing`, `flutter-drift`, `flutter-offline-sync`, `flutter-state-machine`, `flutter-repository`, `dart-pro`, `swift-pro`, `kotlin-pro`
 - Start with `flutter-feature` for feature implementation and `mobile-design` for UX patterns. Add framework-specific Flutter skill when applicable. Add `i18n-localization` for multi-language support.
+- When the request starts from Stitch artifacts or a design sync, load `stitch` first and then pair it with `mobile-design` 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: [flutter-feature, mobile-design]
-  supporting_skills: [i18n-localization?, flutter-riverpod?, flutter-testing?, <flutter-specific>?]
+  supporting_skills: [stitch?, i18n-localization?, flutter-riverpod?, flutter-testing?, <flutter-specific>?]
   implementation:
     platforms: [ios, android]
     architecture_decisions: [<string>]

package/workflows/workflows/agent-environment-setup/shared/workflows/onboard.md

@@ -32,7 +32,7 @@ Use this when joining a new project, exploring an unfamiliar codebase, or prepar
 
 - Primary skills: `deep-research`, `architecture-designer`
 - Supporting skills (optional): `legacy-modernizer`, `database-skills`, `typescript-pro`, `javascript-pro`, `python-pro`
-- Start with `deep-research` for systematic exploration and `architecture-designer` for architecture mapping. Add `legacy-modernizer` for undocumented systems.
+- Start with `deep-research` for systematic exploration and `architecture-designer` for architecture mapping. Add `legacy-modernizer` for undocumented systems. Prefer repo evidence first; use external sources only when setup or dependency behavior cannot be confirmed locally.
 
 ## Workflow steps
 

package/workflows/workflows/agent-environment-setup/shared/workflows/orchestrate.md

@@ -25,7 +25,7 @@ Use this when a task spans multiple domains (backend + frontend, security + infr
 
 - Primary skills: `architecture-designer`, `api-designer`
 - Supporting skills (optional): `database-skills`, `deep-research`, `mcp-builder`, `openai-docs`, `prompt-engineer`, `skill-creator`
-- Start with `architecture-designer` for system design coordination and `api-designer` for integration contracts. Add supporting skills based on the coordination challenge.
+- Start with `architecture-designer` for system design coordination and `api-designer` 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/shared/workflows/plan.md

@@ -37,12 +37,12 @@ Use this when starting a new feature, project, or significant change that needs
 
 - Primary skills: `architecture-designer`, `api-designer`
 - Supporting skills (optional): `database-skills`, `deep-research`, `mcp-builder`, `openai-docs`, `prompt-engineer`, `skill-creator`
-- Start with `architecture-designer` for system design and `api-designer` for API contracts. Add `database-skills` when data modeling is central, `deep-research` when external knowledge is needed.
+- Start with `architecture-designer` for system design and `api-designer` for API contracts. Add `database-skills` 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.