@cubis/foundry 0.3.76 → 0.3.78

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

@@ -20,6 +20,7 @@ Use this for mobile app development, Flutter architecture, Stitch-driven mobile
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach platform targets (iOS, Android, both), Flutter version, and relevant screen/feature context.
+- Read `ENGINEERING_RULES.md` and `TECH.md` before implementing non-trivial mobile work so screens and features follow the declared architecture and design-system rules.
 
 ## Skill Routing
 
@@ -35,6 +36,7 @@ Use this for mobile app development, Flutter architecture, Stitch-driven mobile
 3. Implement with consideration for iOS/Android differences.
 4. Write widget and integration tests.
 5. Review for platform-specific edge cases and UX conventions.
+6. Set `doc_impact` if the feature changes navigation, shared UI rules, or mobile architecture conventions.
 
 ## Verification
 
@@ -62,5 +64,6 @@ MOBILE_WORKFLOW_RESULT:
   platform_notes:
     ios: [<string>] | []
     android: [<string>] | []
+  doc_impact: none | tech | rules | both
   follow_up_items: [<string>] | []
 ```

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

@@ -27,12 +27,13 @@ Use this when joining a new project, exploring an unfamiliar codebase, or prepar
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Provide the repo URL, focus areas, and any specific questions to answer during onboarding.
+- Read `ENGINEERING_RULES.md` first and `TECH.md` next when present so onboarding distinguishes the intended contract from current implementation reality.
 
 ## 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 +56,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/claude/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/claude/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,5 +78,11 @@ 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/claude/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/claude/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,5 +63,6 @@ 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/claude/workflows/spec.md

@@ -0,0 +1,79 @@
+---
+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: `@project-planner`
+- Traceability and requirements support: `@researcher`
+- Cross-domain coordination: `@orchestrator`
+- Documentation and structure support: `@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>] | []
+```

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/backend-specialist.md

@@ -78,4 +78,4 @@ Load on demand. Do not preload all references.
 - Run focused checks when code changes land.
 - Note any API contract or schema changes that affect consumers.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/code-archaeologist.md

@@ -74,4 +74,4 @@ Map, understand, and modernize codebases that lack documentation or clear design
 - Risk-assessed modernization plan with incremental steps.
 - Call out any undocumented behavior that could break during changes.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/database-architect.md

@@ -71,4 +71,4 @@ Load on demand. Do not preload all references.
 - Call out data-integrity risks or missing constraints.
 - Provide EXPLAIN output for performance-sensitive queries.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/debugger.md

@@ -69,4 +69,4 @@ Find the root cause with evidence, fix it with minimum blast radius, and leave r
 - Provide regression check (test, command, or verification step).
 - List remaining gaps or environmental unknowns.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/devops-engineer.md

@@ -66,4 +66,4 @@ Deliver infrastructure and deployment changes that are safe, observable, and rev
 - Provide verification steps for post-deployment health.
 - Call out any manual steps or environment-specific dependencies.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/documentation-writer.md

@@ -55,4 +55,4 @@ Produce clear, accurate, and maintainable technical documentation.
 - Accurate code references with file paths.
 - Call out any sections that need team review or are assumptions.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

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

@@ -86,4 +86,4 @@ Load on demand. Do not preload all references.
 - Call out any accessibility, responsiveness, or render-cost risk left behind.
 - Run focused checks when code changes land.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/game-developer.md

@@ -39,4 +39,4 @@ Build games that are fun, performant, and maintainable across target platforms.
 - Provide frame budget analysis for performance-sensitive changes.
 - Note any physics, rendering, or networking assumptions.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

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

@@ -68,4 +68,4 @@ Build and ship cross-platform mobile apps that feel native and perform reliably.
 - Provide widget test or integration test for new features.
 - Note any platform-specific permissions or configuration needed.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/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
 
@@ -187,4 +188,4 @@ ORCHESTRATION_RESULT:
   follow_up_actions: [<string>] | []
 ```
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/penetration-tester.md

@@ -78,4 +78,4 @@ Map attack surfaces, validate exploitability, and provide actionable remediation
 - Remediation guidance with code examples.
 - Remaining risk assessment after proposed fixes.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/performance-optimizer.md

@@ -59,4 +59,4 @@ Measure first, optimize second, verify always.
 - Before/after comparison with same measurement methodology.
 - Performance budget recommendations.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/product-manager.md

@@ -58,4 +58,4 @@ Turn ambiguous requests into clear, testable feature definitions with prioritize
 - Priority ranking with reasoning.
 - Dependencies and risks identified.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/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
 
@@ -65,4 +66,4 @@ Decompose complex requests into implementable plans with clear ownership, depend
 - Verification plan for each milestone.
 - Clear definition of done for the overall effort.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/qa-automation-engineer.md

@@ -65,4 +65,4 @@ Design and maintain test infrastructure that catches real regressions without fa
 - Flaky test remediation plan when applicable.
 - Test data management approach.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/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,5 +75,6 @@ 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.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/security-auditor.md

@@ -91,4 +91,4 @@ Priority = Reachability × Controllability × Severity − Existing Mitigations
 - Assessment of remaining attack surface after fixes.
 - Compliance notes when relevant (OWASP, SOC2, GDPR).
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/seo-specialist.md

@@ -39,4 +39,4 @@ Optimize for search visibility across traditional search engines and AI-powered
 - Structured data recommendations with schema markup examples.
 - Content optimization suggestions aligned to search intent.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/sre-engineer.md

@@ -85,4 +85,4 @@ Operate production systems with SLO-driven reliability, incident readiness, and
 - Toil assessment with automation recommendations.
 - Capacity analysis with scaling recommendations.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/test-engineer.md

@@ -77,4 +77,4 @@ Speed ↑ |  Unit                  — Pure logic, transforms, validators
 - Call out coverage gaps and known risks.
 - Provide CI integration guidance when applicable.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/validator.md

@@ -74,4 +74,4 @@ If validation fails, report the failure with evidence. Do not attempt to fix it
 - Flagged risks or edge cases not covered by criteria.
 - Recommendation: approve, revise, or reject.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/vercel-expert.md

@@ -46,4 +46,4 @@ Deliver Vercel-powered applications with production-grade deployment, runtime, a
 - Monitoring and alerting setup recommendations.
 - Rollback procedure for deployment issues.
 
-> **Codex note:** Specialists are internal reasoning postures, not spawned processes. Switch postures by adopting the specialist's guidelines inline.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. If delegation is unavailable, switch specialist postures inline and preserve the same scope and verification contract.