@cubis/foundry 0.3.76 → 0.3.78

package/workflows/workflows/agent-environment-setup/platforms/codex/rules/AGENTS.md

@@ -43,7 +43,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 or @specialist?
+├─ [EXPLICIT] User named a workflow, @specialist, or exact skill?
 │   → Honor that route exactly. Stop.
 │
 ├─ [SINGLE-DOMAIN] Multi-step but contained in one specialty?
@@ -63,6 +63,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 invoke a specialist posture when direct execution suffices.
 - Never chain more than one `skill_search` per request.
 - Codex compatibility aliases (`$workflow-*`, `$agent-*`) are accepted as hints only — not primary route surfaces.
@@ -367,6 +368,7 @@ Use this matrix to match incoming tasks to the correct skill and primary special
 | 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 +416,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/codex/skills/deep-research/SKILL.md

@@ -0,0 +1,89 @@
+---
+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.
+---
+# 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. |
+
+## Codex Research Flow
+
+- Start in the repo. Gather code, config, tests, and docs before using any external source.
+- When external evidence is required, prefer official docs first and keep community evidence clearly labeled as secondary because Codex environments may be network-restricted or stale.
+- End with a concrete next route: direct execution, a workflow, an agent posture, or one exact follow-up skill.
+
+## Codex Platform Notes
+
+- Specialists are internal reasoning postures, not spawned subagent processes.
+- Reference the repo-root AGENTS instructions for posture definitions and switching contracts.
+- Codex operates under network restrictions — skills should not assume outbound HTTP access.
+- Use `$ARGUMENTS` to access user-provided arguments when the skill is invoked.
+- All skill guidance executes within the sandbox; file I/O is confined to the workspace.

package/workflows/workflows/agent-environment-setup/platforms/codex/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.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/deep-research/evals/evals.json

@@ -0,0 +1,56 @@
+[
+  {
+    "name": "latest-capability-verification",
+    "description": "Validate that the skill performs repo-first research, prioritizes official documentation, labels secondary evidence, and recommends a next route.",
+    "prompt": "Research whether the latest official Claude Code hook surface supports reinforcing route honoring before implementation. Start with the current repo state, then use official docs if needed. If community sources add useful practical context, include them but label them appropriately. End with the next workflow, agent, or skill we should use.",
+    "assertions": [
+      {
+        "id": "repo-first",
+        "description": "Starts with repo or local evidence before using external sources."
+      },
+      {
+        "id": "official-first",
+        "description": "Treats official docs or upstream sources as the primary evidence."
+      },
+      {
+        "id": "secondary-labeled",
+        "description": "Labels any Reddit or community evidence as secondary rather than authoritative."
+      },
+      {
+        "id": "gaps-called-out",
+        "description": "States any unresolved gaps, conflicts, or unknowns."
+      },
+      {
+        "id": "next-route",
+        "description": "Ends with a concrete recommended next route."
+      }
+    ]
+  },
+  {
+    "name": "tool-comparison",
+    "description": "Validate that the skill compares options with a clear frame, ties findings back to repo impact, and produces a decision-ready output.",
+    "prompt": "Compare whether our CLI should keep enforcement in Gemini command wrappers only or also add Claude hook templates. Use the repo state first, then official docs for current platform capabilities, and include community evidence only if it adds implementation nuance. Finish with a recommendation and the next route to take.",
+    "assertions": [
+      {
+        "id": "comparison-frame",
+        "description": "Defines concrete comparison axes such as repo impact, enforcement surface, and maintenance cost."
+      },
+      {
+        "id": "repo-impact",
+        "description": "Connects each option back to the current repo or bundle behavior."
+      },
+      {
+        "id": "fact-vs-inference",
+        "description": "Separates verified facts from inference or interpretation."
+      },
+      {
+        "id": "decision-oriented",
+        "description": "Produces a recommendation or explicit defer condition."
+      },
+      {
+        "id": "no-research-sprawl",
+        "description": "Keeps the answer structured instead of turning into an unfiltered dump of sources."
+      }
+    ]
+  }
+]

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/deep-research/examples/01-latest-docs-check.md

@@ -0,0 +1,12 @@
+# Example: Latest Docs Check
+
+## User Request
+
+> Research whether Claude Code hooks can reinforce route honoring before we add new workflow rules.
+
+## Expected Shape
+
+1. Inspect the repo's current Claude rule and hook support first.
+2. Verify the current official Claude docs for hooks, event names, and config format.
+3. Separate those verified facts from any community commentary about hook effectiveness.
+4. End with the recommended next route, for example `@researcher` continuing the research or `/create` applying the validated hook template changes.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/deep-research/examples/02-ecosystem-comparison.md

@@ -0,0 +1,12 @@
+# Example: Ecosystem Comparison
+
+## User Request
+
+> Compare whether our CLI should keep Gemini command enforcement only, or add another platform-native hook layer for Claude as well.
+
+## Expected Shape
+
+1. Start with repo constraints and current platform bundle behavior.
+2. Compare the official platform capabilities using primary docs.
+3. Add any useful community evidence as clearly labeled secondary input.
+4. Produce a recommendation tied to the repo: which platform gets which enforcement surface, and why.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/deep-research/examples/03-research-to-implementation-handoff.md

@@ -0,0 +1,12 @@
+# Example: Research To Implementation Handoff
+
+## User Request
+
+> Research the latest Codex, Claude, and Gemini MCP behavior, then tell me the next route to update our workflow rules safely.
+
+## Expected Shape
+
+1. Gather repo evidence first.
+2. Verify current official docs for each platform.
+3. Summarize verified facts, secondary evidence, and gaps.
+4. End with a precise next route such as `/plan` for a policy change or `skill-creator` for skill/rule packaging work.

package/workflows/workflows/agent-environment-setup/platforms/codex/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/codex/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/codex/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/codex/skills/spec-driven-delivery/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: spec-driven-delivery
+description: Use when turning a non-trivial request into a Git-tracked spec pack, maintaining traceability during execution, and updating specs before code when requirements or architecture change.
+---
+# Spec-Driven Delivery
+
+## Purpose
+
+Create and maintain a lightweight source of truth for non-trivial work. This skill turns requirements, decisions, acceptance criteria, and architecture impact into a spec pack under the `docs/specs/<spec-id>/` workspace area, then keeps that pack aligned as implementation evolves.
+
+## When to Use
+
+- Planning a medium or large feature before implementation
+- Capturing acceptance criteria, traceability, and architecture impact in Git
+- Reusing or refreshing an existing spec pack for a follow-up change
+- Bridging native plan-mode output into durable project documents
+- Keeping implementation, verification, and documentation aligned across sessions
+
+## Instructions
+
+1. **Classify the task first** because trivial work should not pay spec overhead. Use this skill only when the task is multi-step, cross-session, cross-domain, risky, or likely to change architecture, testing strategy, or team coordination.
+2. **Look for an existing spec pack before creating a new one** because duplicate specs create drift. Reuse the closest matching spec directory when the current request extends an active initiative.
+3. **Create a stable `spec_id` and spec root** because the same identifier should survive planning, execution, review, and follow-up changes.
+4. **Write the minimum viable pack** because the goal is durable coordination, not bureaucracy. Keep the brief, acceptance, tasks, traceability, and handoff documents concise and testable.
+5. **Use `sadd` when turning requirements into assertions** because spec quality depends on extracting testable behavior instead of leaving requirements vague.
+6. **Record architecture impact explicitly** because implementation must stay aligned with the project architecture contract and current-state tech map. Mark whether the change affects architecture style, module boundaries, dependency rules, design system, deployment shape, or testing strategy.
+7. **Update the spec before implementation changes behavior** because traceability breaks when code changes first and docs lag behind.
+8. **Keep the task graph execution-ready** because `/implement-track` and `/orchestrate` should be able to act on the spec without replanning. Every task should have ownership, dependencies, acceptance criteria, and a verification path.
+9. **Route external research through `deep-research`** because repo-first planning still needs disciplined escalation when freshness or public comparison matters.
+10. **Emit a clear next route** because spec work usually hands off into `/create`, `/implement-track`, `/orchestrate`, or `/architecture`.
+11. **Report `doc_impact` and `traceability_status`** because feature work should surface whether the architecture contract or tech map must be refreshed at the end.
+12. **Keep the pack alive during execution** because a stale spec is worse than none. Update acceptance, tasks, and traceability when scope or constraints change.
+
+## Output Format
+
+Deliver:
+
+1. **Spec summary** — `spec_id`, `spec_root`, goal, scope, and why spec mode is warranted
+2. **Acceptance and traceability state** — requirements, open gaps, and `traceability_status`
+3. **Execution-ready plan** — tasks, owners, dependencies, and verification checkpoints
+4. **Architecture and doc impact** — `architecture_impact` plus `doc_impact`
+5. **Recommended next route** — exact workflow, agent, or skill to continue from the spec
+
+## References
+
+| File | Load when |
+| --- | --- |
+| `../sadd/SKILL.md` | Need requirement mining, GIVEN-WHEN-THEN specs, or traceability patterns. |
+| `../architecture-doc/SKILL.md` | Need ADRs, system boundaries, or architecture-document structure. |
+| `../deep-research/SKILL.md` | Need repo-first research escalation or evidence labeling rules. |
+
+## Examples
+
+| File | Use when |
+| --- | --- |
+| `../sadd/references/spec-mining.md` | Turning loose requirements into testable spec entries. |
+| `../sadd/references/coverage-mapping.md` | Building a traceability matrix that links specs, tests, and code. |
+
+## Codex Platform Notes
+
+- Specialists are internal reasoning postures, not spawned subagent processes.
+- Reference the repo-root AGENTS instructions for posture definitions and switching contracts.
+- Codex operates under network restrictions — skills should not assume outbound HTTP access.
+- Use `$ARGUMENTS` to access user-provided arguments when the skill is invoked.
+- All skill guidance executes within the sandbox; file I/O is confined to the workspace.

package/workflows/workflows/agent-environment-setup/platforms/codex/workflows/accessibility.md

@@ -74,4 +74,4 @@ ACCESSIBILITY_WORKFLOW_RESULT:
   follow_up_items: [<string>] | []
 ```
 
-> **Codex note:** This workflow runs inside a network-restricted sandbox. Specialists are reasoning postures defined in AGENTS.md, not spawned processes.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. Otherwise follow AGENTS.md specialist postures inline while keeping the same routing and verification contract.

package/workflows/workflows/agent-environment-setup/platforms/codex/workflows/architecture.md

@@ -0,0 +1,82 @@
+---
+command: "/architecture"
+description: "Refresh the project architecture contract and current-state map in ENGINEERING_RULES.md and TECH.md with explicit structure, design-system, testing, and flow guidance."
+triggers:
+  [
+    "architecture",
+    "design system",
+    "adr",
+    "clean architecture",
+    "system map",
+    "app structure",
+    "technical governance",
+    "flow diagram",
+  ]
+---
+
+# Architecture Workflow
+
+## When to use
+
+Use this when the task is to declare, refresh, or validate the project architecture contract and current-state map, especially after structure changes, scale changes, design-system changes, migrations, or major feature additions.
+
+## Routing
+
+- Primary coordinator: `the project-planner posture`
+- Documentation support: `the documentation-writer posture`
+- Research support: `the researcher posture`
+- Domain validation: `the backend-specialist posture`, `the frontend-specialist posture`, `the database-architect posture`
+
+## Skill Routing
+
+- Primary skills: `architecture-doc`, `system-design`, `tech-doc`, `frontend-design`
+- Supporting skills (optional): `api-design`, `database-design`, `sadd`, `deep-research`
+- Load the four primary skills directly for this workflow. Add `api-design` or `database-design` when service or data boundaries are central, `sadd` when tying the architecture update to an active spec pack, and `deep-research` only when outside evidence is required.
+
+## Workflow steps
+
+1. Inspect the repo first and read `ENGINEERING_RULES.md` followed by `TECH.md` if they exist.
+2. Determine the current architecture style, module boundaries, design-system source of truth, and testing strategy from the codebase.
+3. Update only the managed architecture sections in `ENGINEERING_RULES.md` and `TECH.md`.
+4. Add or refresh Mermaid diagrams and flow narratives inside `TECH.md` when they clarify system behavior.
+5. Record whether the update was driven by a broader spec and whether future implementation must follow newly declared rules.
+
+## Context notes
+
+- This workflow is route-fixed and skill-fixed: do not start with `route_resolve` or `skill_search`.
+- `ENGINEERING_RULES.md` is normative. `TECH.md` is descriptive. Keep them aligned but not redundant.
+- Preserve manual content outside the managed architecture sections.
+- Mark non-applicable sections explicitly instead of silently omitting them.
+
+## Verification
+
+- Managed architecture sections exist in both target docs.
+- Architecture style, dependency rules, and design-system guidance are explicit.
+- `TECH.md` includes flow text and at least one Mermaid diagram when the repo has meaningful flow complexity.
+- The update records `doc_impact` and whether future feature work must refresh the docs again.
+
+## Output Contract
+
+```yaml
+ARCHITECTURE_WORKFLOW_RESULT:
+  primary_agent: project-planner
+  supporting_agents: [documentation-writer?, researcher?, backend-specialist?, frontend-specialist?, database-architect?]
+  primary_skills: [architecture-doc, system-design, tech-doc, frontend-design]
+  supporting_skills: [api-design?, database-design?, sadd?, deep-research?]
+  managed_targets:
+    rules_doc: ENGINEERING_RULES.md
+    tech_doc: TECH.md
+  files_updated: [ENGINEERING_RULES.md, TECH.md]
+  architecture_contract:
+    style: <string>
+    dependency_rules: [<string>]
+    design_system_source: <string>
+  technical_snapshot:
+    topology: [<string>]
+    flows: [<string>]
+    diagrams: [<string>] | []
+  doc_impact: rules | tech | both
+  next_actions: [<string>] | []
+```
+
+> **Codex note:** Prefer native Codex delegation when the host exposes it. Otherwise follow AGENTS.md specialist postures inline while keeping the same routing and verification contract.

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

@@ -36,6 +36,7 @@ Use this for backend architecture, API design, service implementation, or Postma
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach API specifications, schema diagrams, Postman collections, and relevant service code.
+- Read `ENGINEERING_RULES.md` and `TECH.md` before changing service boundaries or shared backend structure.
 
 ## Skill Routing
 
@@ -50,6 +51,7 @@ Use this for backend architecture, API design, service implementation, or Postma
 3. Implement backend logic with proper error handling and validation.
 4. Write integration tests covering happy path and error cases.
 5. Review for security, performance, and reliability.
+6. Set `doc_impact` if the change alters service boundaries, shared contracts, or operational shape.
 
 ## Verification
 
@@ -74,10 +76,11 @@ BACKEND_WORKFLOW_RESULT:
   implementation:
     files_changed: [<path>]
     tests_added: [<path>]
+  doc_impact: none | tech | rules | both
   verification:
     checks_run: [<command-or-test>]
     evidence: [<string>]
   follow_up_items: [<string>] | []
 ```
 
-> **Codex note:** This workflow runs inside a network-restricted sandbox. Specialists are reasoning postures defined in AGENTS.md, not spawned processes.
+> **Codex note:** Prefer native Codex delegation when the host exposes it. Otherwise follow AGENTS.md specialist postures inline while keeping the same routing and verification contract.