@cubis/foundry 0.3.76 → 0.3.77

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/deep-research/references/comparison-checklist.md

@@ -0,0 +1,57 @@
+# Comparison Checklist
+
+Use this when evaluating tools, frameworks, APIs, or platforms.
+
+## 1. Scope the Comparison
+
+Define:
+
+- what is being compared
+- whether the comparison is about implementation fit, operational cost, or product capability
+- what time horizon matters: immediate migration, medium-term maintenance, or long-term platform fit
+
+## 2. Compare on Stable Axes
+
+Use a short set of dimensions:
+
+- integration fit with the current repo
+- maturity and maintenance signal
+- official documentation quality
+- configuration complexity
+- ecosystem and tooling support
+- operational constraints
+- migration cost
+
+Do not compare on vague criteria like "better DX" without concrete evidence.
+
+## 3. Capture Repo Impact
+
+Tie each option back to the current codebase:
+
+- what code would change
+- which workflows or agents would own the work
+- what risks are specific to this repo
+- whether new MCP tools or skills would be required
+
+## 4. Separate Product Claims from Team Constraints
+
+An option can be technically stronger and still be a worse fit for the repo.
+
+Keep these separate:
+
+- product capability
+- ecosystem quality
+- team familiarity
+- migration blast radius
+- existing architecture constraints
+
+## 5. Decision Frame
+
+Finish with one of:
+
+- recommend option A
+- recommend option B
+- defer decision pending one missing verification
+- keep current approach because switching cost outweighs gain
+
+If the evidence is mixed, say what would change the recommendation.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/deep-research/references/research-output.md

@@ -0,0 +1,69 @@
+# Research Output Contract
+
+## Required Sections
+
+### 1. Research question
+
+State:
+
+- the exact topic
+- why research was necessary
+- whether freshness or public comparison mattered
+- the decision this research is meant to support
+
+### 2. Verified facts
+
+List the strongest findings first.
+
+For each fact:
+
+- state the claim in one sentence
+- cite the source class: repo, official docs, upstream repo, standard
+- include the relevant link or file path
+- include date/version when it matters
+
+### 3. Secondary / community evidence
+
+Only include this when it adds signal the primary sources did not provide.
+
+For each item:
+
+- label it as secondary evidence
+- state what practical signal it adds
+- avoid presenting it as settled fact
+
+### 4. Gaps / unknowns
+
+Document:
+
+- unresolved conflicts
+- missing official confirmation
+- assumptions that still need validation
+- risks if the team proceeds anyway
+
+### 5. Recommended next route
+
+Research should end with one clear recommendation:
+
+- direct execution
+- a specific workflow like `/plan` or `/create`
+- a specialist like `@researcher` or `@frontend-specialist`
+- an exact skill like `stitch` or `deep-research`
+
+Keep this recommendation concrete enough that the next step does not need another routing pass.
+
+## Compression Rules
+
+- Prefer 5 strong findings over 20 weak ones.
+- Do not paste long quotes from docs when a citation plus summary will do.
+- If multiple sources say the same thing, summarize once and cite the strongest source.
+- If research found nothing reliable, say that directly.
+
+## Handoff Pattern
+
+When handing off to implementation or planning, include:
+
+- the decision summary
+- the highest-confidence constraints
+- the unresolved risks
+- the next route to take

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/deep-research/references/source-ladder.md

@@ -0,0 +1,81 @@
+# Source Ladder
+
+## Goal
+
+Use the smallest amount of external research that still produces a decision-ready answer. Keep the evidence traceable and ordered by trust.
+
+## 1. Repo / Local Evidence First
+
+Start by inspecting:
+
+- application code and tests
+- README files and internal docs
+- generated workflow or skill assets
+- lockfiles, config files, and package manifests
+- existing integration code and migration history
+
+If the repo already answers the question, stop there. Do not browse externally just because web research feels safer.
+
+## 2. Primary External Sources
+
+Use these next:
+
+- official vendor docs
+- upstream repositories and release notes
+- standards bodies and reference specs
+- maintainer-authored examples
+
+Prefer sources that expose:
+
+- exact feature names
+- current version constraints
+- config formats
+- dates or changelog context
+
+When the topic is time-sensitive, capture the date you verified the source and the version or doc page involved.
+
+## 3. Secondary / Community Sources
+
+Use these only after primary evidence:
+
+- Reddit threads
+- issue comments
+- independent blog posts
+- forum discussions
+- third-party comparison articles
+
+Community evidence is useful for:
+
+- practical gotchas
+- migration pain points
+- missing-doc workarounds
+- real-world adoption patterns
+
+Community evidence is not enough on its own for authoritative claims about product behavior, supported configuration, or security guarantees.
+
+## 4. Conflict Handling
+
+When sources disagree:
+
+1. Prefer repo evidence for the current codebase state.
+2. Prefer official docs over community claims for product behavior.
+3. Prefer newer dated material when the sources cover the same feature.
+4. If the conflict remains unresolved, report it as a gap instead of guessing.
+
+## 5. Evidence Labels
+
+Use these labels in research output:
+
+- **Verified fact** — backed by repo evidence or a primary source
+- **Secondary evidence** — backed only by community or indirect sources
+- **Inference** — reasoned conclusion not directly stated by a source
+- **Gap** — could not be verified confidently
+
+## 6. Stop Conditions
+
+Stop researching when:
+
+- the decision is already clear
+- new sources only repeat the same point
+- the remaining uncertainty is small and clearly documented
+- the task should move into implementation or planning

package/workflows/workflows/agent-environment-setup/platforms/gemini/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/gemini/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/gemini/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/shared/agents/orchestrator.md

@@ -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/shared/agents/project-planner.md

@@ -24,7 +24,7 @@ Decompose complex requests into implementable plans with clear ownership, depend
 - Load `architecture-designer` for system design tradeoffs in the plan.
 - Load `api-designer` when the plan involves API contract decisions.
 - Load `database-skills` when the plan involves data modeling or migration.
-- Load `deep-research` 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
@@ -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/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/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.