@cubis/foundry 0.3.76 → 0.3.78

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

@@ -20,12 +20,13 @@ Use this when a task spans multiple domains (backend + frontend, security + infr
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach the full task description, constraints, acceptance criteria, and relevant context when starting.
+- Read `ENGINEERING_RULES.md` and `TECH.md` before decomposing non-trivial work, then reuse any existing `docs/specs/<spec-id>/` pack as the handoff source of truth.
 
 ## 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
 
@@ -34,7 +35,8 @@ Use this when a task spans multiple domains (backend + frontend, security + infr
 3. Delegate each task to the best specialist agent with full context.
 4. Validate each deliverable against acceptance criteria via independent validation.
 5. Iterate on failed validations with specific feedback (max 3 iterations).
-6. Integrate outputs, verify cross-task consistency, and report results.
+6. Surface `doc_impact` when the coordinated work changes architecture, boundaries, scale, or the design system.
+7. Integrate outputs, verify cross-task consistency, and report results.
 
 ## Verification
 
@@ -51,6 +53,8 @@ ORCHESTRATE_WORKFLOW_RESULT:
   supporting_agents: [<specialist-agents-used>]
   primary_skills: [system-design, api-design]
   supporting_skills: [<supporting-skills-used>]
+  spec_id: <string> | null
+  spec_root: docs/specs/<spec-id> | null
   task_count: <number>
   completed: <number>
   failed: <number>
@@ -61,6 +65,7 @@ ORCHESTRATE_WORKFLOW_RESULT:
       iterations: <number>
       validation_evidence: <string>
   integration_status: clean | conflicts_resolved | issues_remaining
+  doc_impact: none | tech | rules | both
   remaining_risks: [<string>] | []
   follow_up_actions: [<string>] | []
 ```

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

@@ -4,7 +4,6 @@ description: "Build a decision-complete implementation plan with interfaces, fai
 triggers:
   [
     "plan",
-    "spec",
     "design",
     "roadmap",
     "acceptance",
@@ -32,21 +31,24 @@ Use this when starting a new feature, project, or significant change that needs
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach the feature request, problem statement, constraints, and any existing design documents.
+- Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before finalizing a non-trivial plan.
+- Reuse an existing `docs/specs/<spec-id>/` pack when the change already has one instead of creating a parallel planning track.
 
 ## 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.
-6. Identify risks, unknowns, and mitigation strategies.
+6. Record `architecture_impact`, `doc_impact`, and `traceability_status` when the work is non-trivial.
+7. Identify risks, unknowns, and mitigation strategies.
 
 ## Verification
 
@@ -62,7 +64,9 @@ 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?]
+  spec_id: <string> | null
+  spec_root: docs/specs/<spec-id> | null
   plan:
     scope_summary: <string>
     tasks:
@@ -74,6 +78,12 @@ PLAN_WORKFLOW_RESULT:
     interfaces: [<string>]
     risks: [<string>]
     milestones: [<string>]
+  architecture_impact:
+    summary: <string>
+    affects_structure: true | false
+    affects_design_system: true | false
+  doc_impact: none | tech | rules | both
+  traceability_status: complete | partial | blocked
   follow_up_items: [<string>] | []
 ```
 

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

@@ -20,6 +20,7 @@ Use this when improving code structure, reducing tech debt, or modularizing with
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach the target code, pain points, and any constraints on what can change.
+- Read `ENGINEERING_RULES.md` and `TECH.md` first so behavior-preserving structure changes do not drift from the accepted architecture contract.
 
 ## Skill Routing
 
@@ -34,6 +35,7 @@ Use this when improving code structure, reducing tech debt, or modularizing with
 3. Apply one refactoring at a time with behavior preservation.
 4. Verify behavior unchanged after each step.
 5. Document the improved structure and any conventions established.
+6. Set `doc_impact` when the refactor changes project structure, module boundaries, or design-system conventions.
 
 ## Verification
 
@@ -57,6 +59,7 @@ REFACTOR_WORKFLOW_RESULT:
   quality_improvement:
     complexity_before: <string>
     complexity_after: <string>
+  doc_impact: none | tech | rules | both
   tests_added: [<test-file-path>] | []
   follow_up_items: [<string>] | []
 ```

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

@@ -20,6 +20,7 @@ Use this when preparing a release, deploying to production, or managing a rollou
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach the release scope, version number, changelog draft, and deployment target.
+- Read `ENGINEERING_RULES.md` and `TECH.md` before release if the shipped changes touched architecture, scaling assumptions, or design-system rules.
 
 ## Skill Routing
 
@@ -35,6 +36,7 @@ Use this when preparing a release, deploying to production, or managing a rollou
 4. Execute staged rollout with health checks at each stage.
 5. Verify production health post-deployment.
 6. Document rollback procedure and post-release status.
+7. Set `doc_impact` if the release includes architecture-affecting work that should refresh the managed docs.
 
 ## Verification
 
@@ -61,6 +63,7 @@ RELEASE_WORKFLOW_RESULT:
     stages_completed: [<string>]
     health_checks: [<string>]
   rollback_plan: <string>
+  doc_impact: none | tech | rules | both
   follow_up_items: [<string>] | []
 ```
 

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

@@ -0,0 +1,81 @@
+---
+command: "/spec"
+description: "Create or refresh a Git-tracked spec pack for non-trivial work, including acceptance criteria, traceability, architecture impact, and next-route handoff."
+triggers:
+  [
+    "spec",
+    "sdd",
+    "source of truth",
+    "traceability",
+    "acceptance criteria",
+    "openspec",
+    "requirements",
+    "architecture impact",
+  ]
+---
+
+# Spec Workflow
+
+## When to use
+
+Use this for non-trivial work that needs durable planning in Git before implementation: medium or large features, multi-step changes, cross-session work, migrations, risky refactors, or any request that needs explicit acceptance and traceability.
+
+## Routing
+
+- Primary coordinator: `.agent/agents/project-planner`
+- Traceability and requirements support: `.agent/agents/researcher`
+- Cross-domain coordination: `.agent/agents/orchestrator`
+- Documentation and structure support: `.agent/agents/documentation-writer`
+
+## Skill Routing
+
+- Primary skills: `spec-driven-delivery`, `sadd`
+- Supporting skills (optional): `system-design`, `architecture-doc`, `deep-research`, `api-design`, `database-design`, `tech-doc`
+- Start with `spec-driven-delivery` for the pack structure and handoff contract. Add `sadd` when mining requirements into testable assertions, `system-design` or `architecture-doc` when the spec changes structure, and `deep-research` only when repo-local evidence is insufficient.
+
+## Workflow steps
+
+1. Determine whether the task is non-trivial enough to justify a spec pack.
+2. Find an existing `docs/specs/<spec-id>/` pack or create a new stable `spec_id`.
+3. Write or refresh the spec pack with brief, acceptance, tasks, traceability, and handoff files.
+4. Record `architecture_impact`, `doc_impact`, and any required updates to `ENGINEERING_RULES.md` or `TECH.md`.
+5. Identify the next execution route and hand off without replanning the same work.
+
+## Context notes
+
+- Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist because they define the accepted architecture contract and current state.
+- Prefer repo evidence first; escalate to `deep-research` only when freshness, public comparison, or explicit research requests require it.
+- Keep spec packs lean. Trivial one-step tasks should stay on the lightweight path with no new spec directory.
+
+## Verification
+
+- `spec_id` and `spec_root` are stable and explicit.
+- Acceptance criteria are testable and traceable.
+- Task dependencies form a valid execution order.
+- `architecture_impact`, `doc_impact`, and `traceability_status` are present.
+
+## Output Contract
+
+```yaml
+SPEC_WORKFLOW_RESULT:
+  primary_agent: project-planner
+  supporting_agents: [researcher?, orchestrator?, documentation-writer?]
+  primary_skills: [spec-driven-delivery, sadd]
+  supporting_skills: [system-design?, architecture-doc?, deep-research?, api-design?, database-design?, tech-doc?]
+  spec_id: <string>
+  spec_root: docs/specs/<spec-id>
+  architecture_impact:
+    summary: <string>
+    affects_structure: true | false
+    affects_design_system: true | false
+    affects_testing_strategy: true | false
+  doc_impact: none | tech | rules | both
+  traceability_status: complete | partial | blocked
+  documents:
+    created: [<path>] | []
+    updated: [<path>] | []
+  next_route: </create | /implement-track | /orchestrate | /architecture | direct>
+  gaps: [<string>] | []
+```
+
+> **Antigravity note:** Use Agent Manager for parallel agent coordination. Workflow files are stored under `.agent/workflows/`.

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`.
 
 ---
 
@@ -367,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 |
@@ -414,12 +418,17 @@ 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. For non-trivial work, read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist.
+12. If those docs declare architecture or design-system rules, follow them unless the current spec or task explicitly changes them.
+13. Use upstream MCP servers such as `postman`, `stitch`, or `playwright` for real cloud/browser actions when available.
 
 <!-- cbx:mcp:auto:end -->

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/deep-research/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: deep-research
+description: Use when investigating latest vendor behavior, comparing tools or platforms, verifying claims beyond the repo, or gathering external evidence before implementation.
+allowed-tools: Read Grep Glob Bash
+context: fork
+agent: researcher
+user-invocable: true
+argument-hint: "Topic, vendor capability, or public comparison to research"
+---
+
+# Deep Research
+
+## Purpose
+
+Run a disciplined research pass before implementation when the repo alone is not enough. This skill keeps research evidence-driven: inspect the local codebase first, escalate to official docs when freshness or public comparison matters, then use labeled community evidence only when it adds practical context.
+
+## When to Use
+
+- Verifying latest SDK, CLI, API, or platform behavior
+- Comparing tools, frameworks, hosted services, or implementation approaches
+- Checking whether public docs and the local repo disagree
+- Gathering external evidence before planning a migration or new capability
+- Producing a structured research brief that hands off cleanly into implementation
+
+## Instructions
+
+1. **Define the research question before collecting sources** because vague research sprawls quickly. Restate the target topic, freshness requirement, comparison axis, and what decision the findings need to support.
+
+2. **Inspect the repo first** because many questions are already answerable from local code, configs, tests, docs, or generated assets. Do not browse externally until the local evidence is exhausted or clearly insufficient.
+
+3. **Decide whether external research is actually required** because not every task needs web evidence. Escalate only when freshness matters, public comparison matters, or the user explicitly asks to research or verify.
+
+4. **Follow the source ladder strictly** because evidence quality matters. Use official docs, upstream repositories, standards, and maintainer material as primary sources before looking at blogs, issue threads, or Reddit.
+
+5. **Capture concrete source details** because research without provenance is hard to trust. Record exact links, relevant dates, versions, and any repo files that support or contradict the external evidence.
+
+6. **Cross-check important claims across more than one source when possible** because public docs, repos, and community advice can drift. If sources disagree, say so explicitly instead of smoothing over the conflict.
+
+7. **Use Reddit and other community sources only as labeled secondary evidence** because they can surface practical gotchas but are not authoritative. Treat them as implementation color, not final truth.
+
+8. **Separate verified facts from inference** because downstream planning depends on confidence. Mark what is directly supported by repo evidence or official sources versus what you infer from patterns or secondary signals.
+
+9. **Keep the output decision-oriented** because the goal is not to dump links. Tie each finding back to the implementation, workflow, agent, or skill decision it affects.
+
+10. **Recommend the next route explicitly** because research is usually a handoff, not the end of the task. Name the next workflow, agent, or exact skill that should continue the work.
+
+11. **State the remaining gaps and risks** because incomplete research is still useful when the uncertainty is visible. Call out what you could not verify, what may have changed recently, and what assumptions remain.
+
+12. **Avoid over-quoting and over-collecting** because research quality comes from synthesis, not volume. Prefer concise summaries with high-signal citations over long pasted excerpts.
+
+13. **When the task turns into implementation, stop researching and hand off** because mixing discovery and execution usually creates drift. Deliver the research brief first, then route into the correct workflow or specialist.
+
+## Output Format
+
+Deliver:
+
+1. **Research question** — topic, freshness requirement, and decision to support
+2. **Verified facts** — repo evidence and primary-source findings
+3. **Secondary/community evidence** — labeled lower-trust supporting signals
+4. **Gaps / unknowns** — unresolved questions or contradictory evidence
+5. **Recommended next route** — direct execution, workflow, agent, or exact skill to use next
+
+## References
+
+Load only the file needed for the current question.
+
+| File | Load when |
+| --- | --- |
+| `references/source-ladder.md` | Need the repo-first and source-priority policy for official docs versus community evidence. |
+| `references/research-output.md` | Need the structured output format, evidence labeling rules, or handoff pattern. |
+| `references/comparison-checklist.md` | Comparing vendors, frameworks, or tools and need a concrete evaluation frame. |
+
+## Examples
+
+Use these when the task shape already matches.
+
+| File | Use when |
+| --- | --- |
+| `examples/01-latest-docs-check.md` | Verifying a latest capability or doc claim before implementation. |
+| `examples/02-ecosystem-comparison.md` | Comparing multiple tools or platforms with official-first sourcing. |
+| `examples/03-research-to-implementation-handoff.md` | Turning research findings into a concrete next workflow or specialist handoff. |
+
+## Claude Research Flow
+
+- Use `$ARGUMENTS` as the research topic when this skill is invoked directly.
+- Prefer official docs, upstream repos, and maintainer material before blog posts or Reddit threads.
+- If Claude hook templates are installed, let them reinforce repo-first inspection and research escalation, but keep the final research output aligned with this skill's evidence contract.
+
+## Claude Platform Notes
+
+- Use `$ARGUMENTS` to access user-provided arguments passed when the skill is invoked.
+- Reference skill-local files with `${CLAUDE_SKILL_DIR}/references/<file>` for portable paths.
+- When `context: fork` is set, the skill runs in an isolated subagent context; the `agent` field names the fork target.
+- MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available for dynamic skill discovery and loading.
+- Use `allowed-tools` in frontmatter to restrict tool access for security-sensitive skills.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/deep-research/evals/assertions.md

@@ -0,0 +1,17 @@
+# Deep Research Eval Assertions
+
+## Eval 1: Latest Capability Verification
+
+1. **repo-first** — Starts by checking repo or local evidence before jumping to web claims.
+2. **official-first** — Uses official docs or upstream sources as the primary evidence for the capability.
+3. **secondary-labeled** — If community sources are mentioned, labels them as secondary evidence instead of presenting them as authoritative.
+4. **gaps-called-out** — Identifies unresolved uncertainty or missing confirmation.
+5. **next-route** — Ends with a concrete recommended workflow, agent, or skill to use next.
+
+## Eval 2: Tool Comparison
+
+1. **comparison-frame** — Defines the comparison axes instead of producing vague preferences.
+2. **repo-impact** — Connects the comparison back to the current repo or implementation constraints.
+3. **fact-vs-inference** — Separates verified facts from inference or interpretation.
+4. **decision-oriented** — Produces a recommendation or explicit defer condition.
+5. **no-research-sprawl** — Keeps the output concise and structured rather than dumping raw links.