@cubis/foundry 0.3.77 → 0.3.79

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

@@ -27,6 +27,7 @@ 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
 

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

@@ -20,6 +20,7 @@ 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
 
@@ -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,6 +31,8 @@ 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
 
@@ -46,7 +47,8 @@ Use this when starting a new feature, project, or significant change that needs
 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
 
@@ -63,6 +65,8 @@ PLAN_WORKFLOW_RESULT:
   supporting_agents: [orchestrator?, backend-specialist?, frontend-specialist?, database-architect?]
   primary_skills: [system-design, api-design]
   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 `PRODUCT.md`, `ARCHITECTURE.md`, `ENGINEERING_RULES.md`, `TECH.md`, or `ROADMAP.md`.
+5. Identify the next execution route and hand off without replanning the same work.
+
+## Context notes
+
+- Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist because they define the accepted product direction, 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

@@ -188,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

@@ -66,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

@@ -77,4 +77,4 @@ Investigate thoroughly, synthesize findings, and deliver structured knowledge be
 - 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.

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

@@ -425,6 +425,8 @@ Keep MCP context lazy and exact. Skills are supporting context, not the route la
 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. Use upstream MCP servers such as `postman`, `stitch`, or `playwright` for real cloud/browser actions when available.
+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/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,87 @@
+---
+command: "/architecture"
+description: "Refresh the project backbone docs in PRODUCT.md, ARCHITECTURE.md, ENGINEERING_RULES.md, TECH.md, ROADMAP.md, and ADR scaffolds 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 backbone docs, especially after structure changes, scale changes, design-system changes, migrations, product-direction shifts, 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 `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order if they exist.
+2. Determine the current product surfaces, architecture style, module boundaries, design-system source of truth, roadmap themes, and testing strategy from the codebase.
+3. Update the managed backbone sections in `PRODUCT.md`, `ARCHITECTURE.md`, `ENGINEERING_RULES.md`, `TECH.md`, and `ROADMAP.md`.
+4. Add or refresh Mermaid diagrams and flow narratives inside `ARCHITECTURE.md` or `TECH.md` when they clarify system behavior.
+5. Seed or refresh `docs/adr/README.md` and keep ADR linkage explicit when decisions should be durable.
+6. 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`.
+- `PRODUCT.md` captures intent, `ARCHITECTURE.md` captures accepted structure, `ENGINEERING_RULES.md` is normative, and `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 backbone sections exist in the target docs.
+- Product intent, architecture style, dependency rules, and design-system guidance are explicit.
+- `ARCHITECTURE.md` or `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:
+    product_doc: PRODUCT.md
+    architecture_doc: ARCHITECTURE.md
+    rules_doc: ENGINEERING_RULES.md
+    tech_doc: TECH.md
+    roadmap_doc: ROADMAP.md
+    adr_dir: docs/adr
+  files_updated: [PRODUCT.md, ARCHITECTURE.md, ENGINEERING_RULES.md, TECH.md, ROADMAP.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.