@cubis/foundry 0.3.77 → 0.3.79

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

@@ -0,0 +1,81 @@
+---
+command: "/spec"
+description: "Create or refresh a Git-tracked spec pack for non-trivial work, including acceptance criteria, traceability, architecture impact, and next-route handoff."
+triggers:
+  [
+    "spec",
+    "sdd",
+    "source of truth",
+    "traceability",
+    "acceptance criteria",
+    "openspec",
+    "requirements",
+    "architecture impact",
+  ]
+---
+
+# Spec Workflow
+
+## When to use
+
+Use this for non-trivial work that needs durable planning in Git before implementation: medium or large features, multi-step changes, cross-session work, migrations, risky refactors, or any request that needs explicit acceptance and traceability.
+
+## Routing
+
+- Primary coordinator: `the project-planner posture`
+- Traceability and requirements support: `the researcher posture`
+- Cross-domain coordination: `the orchestrator posture`
+- Documentation and structure support: `the documentation-writer posture`
+
+## 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>] | []
+```
+
+> **Gemini note:** Commands route into workflow files under `.gemini/workflows/`. Specialists are inline postures coordinated through GEMINI.md guidance, not separate agent artifacts.

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

@@ -4,7 +4,7 @@ description: Backend specialist for API contracts, service logic, schema-aware b
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
 maxTurns: 25
-skills: api-designer, api-patterns, architecture-designer, auth-architect, database-skills, database-design, database-optimizer, drizzle-expert, firebase, microservices-architect, nodejs-best-practices, nestjs-expert, fastapi-expert, graphql-architect, stripe-best-practices, serverless-patterns, i18n-localization, typescript-pro, javascript-pro, python-pro, golang-pro, java-pro, csharp-pro, kotlin-pro, rust-pro, php-pro, ruby-pro
+skills: api-design, api-patterns, system-design, auth-architect, database-design, database-design, database-optimizer, drizzle-expert, firebase, microservices-architect, nodejs-best-practices, nestjs-expert, fastapi-expert, graphql-architect, stripe-best-practices, serverless-patterns, i18n-localization, typescript-pro, javascript-pro, python-pro, golang-pro, java-pro, csharp-pro, kotlin-pro, rust-pro, php-pro, ruby-pro
 handoffs:
   - agent: "test-engineer"
     title: "Test Backend"
@@ -20,10 +20,10 @@ Build backend systems that stay correct under production pressure.
 
 - Do not call `skill_search` for any skill in the pre-declared list when the task clearly falls into that domain.
 - Load one primary skill first based on the dominant concern:
-  - `api-designer` for API contract shape, versioning, or endpoint design
+  - `api-design` for API contract shape, versioning, or endpoint design
   - `api-patterns` for REST/RPC conventions and HTTP semantics
   - `auth-architect` for authentication, authorization, session, RBAC, or SSO flows
-  - `database-skills` for schema design, query optimization, or migration planning
+  - `database-design` for schema design, query optimization, or migration planning
   - `nestjs-expert` for NestJS-specific module, provider, or decorator patterns
   - `fastapi-expert` for FastAPI route, dependency injection, or Pydantic model patterns
   - `graphql-architect` for GraphQL schema, resolver, or subscription design
@@ -40,10 +40,10 @@ Load on demand. Do not preload all references.
 
 | File                      | Load when                                                                    |
 | ------------------------- | ---------------------------------------------------------------------------- |
-| `api-designer`            | Designing new API contracts, versioning, or endpoint shape.                  |
+| `api-design`            | Designing new API contracts, versioning, or endpoint shape.                  |
 | `api-patterns`            | REST/RPC conventions, HTTP status codes, or pagination patterns.             |
 | `auth-architect`          | Auth flows, token management, session design, or access control.             |
-| `database-skills`         | Schema design, query optimization, or migration strategy.                    |
+| `database-design`         | Schema design, query optimization, or migration strategy.                    |
 | `nestjs-expert`           | NestJS modules, providers, guards, interceptors, or decorators.              |
 | `fastapi-expert`          | FastAPI routes, middleware, Pydantic models, or async patterns.              |
 | `graphql-architect`       | GraphQL schema design, resolvers, or subscription patterns.                  |

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

@@ -4,7 +4,7 @@ description: Expert database architect for schema design, query optimization, mi
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
 maxTurns: 25
-skills: architecture-designer, database-skills, database-design, database-optimizer, drizzle-expert, postgres, mysql, sqlite, mongodb, redis, supabase, firebase, vitess, neki, typescript-pro, javascript-pro, python-pro, golang-pro, java-pro, php-pro, ruby-pro
+skills: system-design, database-design, database-design, database-optimizer, drizzle-expert, postgres, mysql, sqlite, mongodb, redis, supabase, firebase, vitess, neki, typescript-pro, javascript-pro, python-pro, golang-pro, java-pro, php-pro, ruby-pro
 handoffs:
   - agent: "backend-specialist"
     title: "Implement Schema Changes"
@@ -22,7 +22,7 @@ Design and operate data systems that stay correct, performant, and evolvable und
 - Load one primary skill first based on the dominant concern:
   - `database-design` for schema normalization, entity modeling, or relationship design
   - `database-optimizer` for query performance, index strategy, or execution plan analysis
-  - `database-skills` for cross-cutting database operations and migration patterns
+  - `database-design` for cross-cutting database operations and migration patterns
   - `drizzle-expert` for Drizzle ORM schema, queries, or TypeScript-first database access
   - `postgres` / `mysql` / `sqlite` / `mongodb` / `redis` for engine-specific patterns
   - `supabase` / `firebase` / `vitess` / `neki` for platform-specific database behavior
@@ -37,7 +37,7 @@ Load on demand. Do not preload all references.
 | -------------------- | --------------------------------------------------------------------------- |
 | `database-design`    | Schema normalization, entity relationships, or data modeling decisions.     |
 | `database-optimizer` | Query performance, index strategy, or EXPLAIN analysis.                     |
-| `database-skills`    | Cross-cutting operations, migration patterns, or general database guidance. |
+| `database-design`    | Cross-cutting operations, migration patterns, or general database guidance. |
 | `drizzle-expert`     | Drizzle ORM schema definitions, queries, or migrations.                     |
 | `postgres`           | PostgreSQL-specific features, extensions, or tuning.                        |
 | `mysql`              | MySQL-specific features, replication, or optimization.                      |

package/workflows/workflows/agent-environment-setup/shared/agents/orchestrator.md

@@ -5,7 +5,7 @@ tools: Read, Grep, Glob, Bash, Write, Edit
 model: inherit
 maxTurns: 30
 memory: project
-skills: architecture-designer, api-designer, database-skills, deep-research, mcp-builder, openai-docs, prompt-engineer, skill-creator, typescript-pro, javascript-pro, python-pro
+skills: system-design, api-design, database-design, deep-research, mcp-server-builder, openai-docs, prompt-engineering, skill-creator, typescript-pro, javascript-pro, python-pro
 handoffs:
   - agent: "validator"
     title: "Validate Results"
@@ -31,8 +31,8 @@ Your only permitted actions:
 
 ## Skill Loading Contract
 
-- Do not call `skill_search` for `architecture-designer`, `api-designer`, `database-skills`, `deep-research`, `mcp-builder`, `openai-docs`, `prompt-engineer`, or `skill-creator` when the task is clearly multi-stream coordination, planning, architecture design, contract design, research, or skill package work.
-- Use `architecture-designer` when the coordination problem is really a design tradeoff problem, `api-designer` when integration contracts are the coordination bottleneck, `database-skills` when the shared dependency is a data-model or migration concern, `deep-research` when the coordination risk is stale or conflicting external information, `mcp-builder` for MCP-specific streams, `openai-docs` for OpenAI-doc verification streams, `prompt-engineer` 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`, `openai-docs`, `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, `openai-docs` 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.
 
@@ -42,13 +42,13 @@ Load on demand. Do not preload all references.
 
 | File                    | Load when                                                                                                 |
 | ----------------------- | --------------------------------------------------------------------------------------------------------- |
-| `architecture-designer` | Coordination depends on resolving system design or interface tradeoffs first.                             |
-| `api-designer`          | The critical shared dependency is an API contract or integration boundary.                                |
-| `database-skills`       | The coordination risk centers on schema, migration, data ownership, or engine choice.                     |
+| `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.                     |
 | `deep-research`         | External sources, latest information, or public-repo comparisons are blocking confident execution.        |
-| `mcp-builder`           | One stream is MCP server design, tool shape, or transport selection.                                      |
+| `mcp-server-builder`           | One stream is MCP server design, tool shape, or transport selection.                                      |
 | `openai-docs`           | One stream needs current OpenAI docs or version-specific behavior verification.                           |
-| `prompt-engineer`       | One stream is repairing prompts, agent rules, or instruction quality.                                     |
+| `prompt-engineering`       | One stream is repairing prompts, agent rules, or instruction quality.                                     |
 | `skill-creator`         | The coordinated work includes creating, repairing, or adapting skill packages across generated platforms. |
 
 ## When to Use

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

@@ -22,7 +22,7 @@ triggers:
 tools: Read, Grep, Glob, Bash
 model: inherit
 maxTurns: 25
-skills: security-engineer, vulnerability-scanner, auth-architect, api-designer, typescript-pro, javascript-pro, python-pro, golang-pro, rust-pro
+skills: security-engineer, vulnerability-scanner, auth-architect, api-design, typescript-pro, javascript-pro, python-pro, golang-pro, rust-pro
 handoffs:
   - agent: "security-auditor"
     title: "Review Findings"
@@ -39,7 +39,7 @@ Map attack surfaces, validate exploitability, and provide actionable remediation
   - `security-engineer` for OWASP methodology, threat modeling, and secure architecture review
   - `vulnerability-scanner` for dependency scanning, SAST/DAST tooling, and CVE assessment
   - `auth-architect` for authentication bypass, privilege escalation, or session hijacking analysis
-  - `api-designer` for API security review, input validation gaps, or rate limiting assessment
+  - `api-design` for API security review, input validation gaps, or rate limiting assessment
 - Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed.
 
 ## Skill References
@@ -49,7 +49,7 @@ Map attack surfaces, validate exploitability, and provide actionable remediation
 | `security-engineer`     | OWASP methodology, threat modeling, or secure architecture review. |
 | `vulnerability-scanner` | Dependency scanning, SAST/DAST analysis, or CVE assessment.        |
 | `auth-architect`        | Auth bypass, privilege escalation, or session hijacking analysis.  |
-| `api-designer`          | API security gaps, input validation, or rate limiting review.      |
+| `api-design`          | API security gaps, input validation, or rate limiting review.      |
 
 ## Operating Stance
 

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

@@ -19,7 +19,7 @@ triggers:
 tools: Read, Grep, Glob, Bash
 model: inherit
 maxTurns: 25
-skills: architecture-designer, api-designer, skill-creator, typescript-pro, javascript-pro
+skills: system-design, api-design, skill-creator, typescript-pro, javascript-pro
 ---
 
 # Product Manager
@@ -28,9 +28,9 @@ Turn ambiguous requests into clear, testable feature definitions with prioritize
 
 ## Skill Loading Contract
 
-- Do not call `skill_search` for `architecture-designer` or `api-designer` when the task is clearly product definition, requirements, or feature scoping.
-- Load `architecture-designer` when the product decision has system design implications.
-- Load `api-designer` when the feature definition needs API contract clarity.
+- Do not call `skill_search` for `system-design` or `api-design` when the task is clearly product definition, requirements, or feature scoping.
+- Load `system-design` when the product decision has system design implications.
+- Load `api-design` when the feature definition needs API contract clarity.
 - Load `skill-creator` only when defining requirements for skill packages.
 - Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed.
 
@@ -38,8 +38,8 @@ Turn ambiguous requests into clear, testable feature definitions with prioritize
 
 | File                    | Load when                                                           |
 | ----------------------- | ------------------------------------------------------------------- |
-| `architecture-designer` | Product decision has system design or architecture implications.    |
-| `api-designer`          | Feature needs API contract definition or integration specification. |
+| `system-design` | Product decision has system design or architecture implications.    |
+| `api-design`          | Feature needs API contract definition or integration specification. |
 | `skill-creator`         | Defining requirements for skill packages.                           |
 
 ## Operating Stance

package/workflows/workflows/agent-environment-setup/shared/agents/project-planner.md

@@ -5,7 +5,7 @@ tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
 maxTurns: 30
 memory: project
-skills: architecture-designer, api-designer, database-skills, deep-research, mcp-builder, openai-docs, prompt-engineer, skill-creator, typescript-pro, javascript-pro, python-pro
+skills: system-design, api-design, database-design, deep-research, mcp-server-builder, openai-docs, prompt-engineering, skill-creator, typescript-pro, javascript-pro, python-pro
 handoffs:
   - agent: "orchestrator"
     title: "Start Implementation"
@@ -21,9 +21,9 @@ Decompose complex requests into implementable plans with clear ownership, depend
 ## Skill Loading Contract
 
 - Do not call `skill_search` for any skill in the pre-declared list when the task is clearly project planning, architecture design, or task decomposition.
-- Load `architecture-designer` for system design tradeoffs in the plan.
-- Load `api-designer` when the plan involves API contract decisions.
-- Load `database-skills` when the plan involves data modeling or migration.
+- Load `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 `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.
 
@@ -31,11 +31,11 @@ Decompose complex requests into implementable plans with clear ownership, depend
 
 | File                    | Load when                                                          |
 | ----------------------- | ------------------------------------------------------------------ |
-| `architecture-designer` | Plan involves system design tradeoffs or component boundaries.     |
-| `api-designer`          | Plan involves API contract decisions or integration points.        |
-| `database-skills`       | Plan involves data modeling, schema design, or migration strategy. |
+| `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. |
 | `deep-research`         | Planning requires external research or approach comparison.        |
-| `mcp-builder`           | Plan involves MCP server or tool implementation.                   |
+| `mcp-server-builder`           | Plan involves MCP server or tool implementation.                   |
 | `skill-creator`         | Plan involves skill package creation or modification.              |
 
 ## Operating Stance

package/workflows/workflows/agent-environment-setup/shared/agents/researcher.md

@@ -18,7 +18,7 @@ tools: Read, Grep, Glob, Bash
 model: inherit
 maxTurns: 30
 memory: project
-skills: deep-research, architecture-designer, database-skills, openai-docs, prompt-engineer
+skills: deep-research, system-design, database-design, openai-docs, prompt-engineering
 handoffs:
   - agent: "project-planner"
     title: "Plan Implementation"
@@ -30,12 +30,12 @@ Investigate thoroughly, synthesize findings, and deliver structured knowledge be
 
 ## Skill Loading Contract
 
-- Do not call `skill_search` for `deep-research`, `architecture-designer`, `database-skills`, `openai-docs`, or `prompt-engineer` when the task is clearly research work.
+- Do not call `skill_search` for `deep-research`, `system-design`, `database-design`, `openai-docs`, 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 `architecture-designer` when research involves system design patterns or tradeoffs.
-- Add `database-skills` when research involves data storage options or migration approaches.
+- Add `system-design` when research involves system design patterns or tradeoffs.
+- Add `database-design` when research involves data storage options or migration approaches.
 - Add `openai-docs` when research involves OpenAI API or model behavior verification.
-- Add `prompt-engineer` when research involves prompt design or instruction optimization.
+- Add `prompt-engineering` when research involves prompt design or instruction optimization.
 - Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed.
 
 ## Skill References
@@ -43,10 +43,10 @@ Investigate thoroughly, synthesize findings, and deliver structured knowledge be
 | File                    | Load when                                                             |
 | ----------------------- | --------------------------------------------------------------------- |
 | `deep-research`         | All research tasks — defines the core research methodology.           |
-| `architecture-designer` | Research involves system design patterns or architectural tradeoffs.  |
-| `database-skills`       | Research involves data storage, database comparison, or migration.    |
+| `system-design` | Research involves system design patterns or architectural tradeoffs.  |
+| `database-design`       | Research involves data storage, database comparison, or migration.    |
 | `openai-docs`           | Research involves OpenAI API, model behavior, or version differences. |
-| `prompt-engineer`       | Research involves prompt design or instruction optimization.          |
+| `prompt-engineering`       | Research involves prompt design or instruction optimization.          |
 
 ## Operating Stance
 

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

@@ -30,7 +30,7 @@ triggers:
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
 maxTurns: 25
-skills: security-engineer, auth-architect, vulnerability-scanner, static-analysis, api-designer, graphql-architect, nodejs-best-practices, nestjs-expert, fastapi-expert, typescript-pro, javascript-pro, python-pro, golang-pro, rust-pro
+skills: security-engineer, auth-architect, vulnerability-scanner, static-analysis, api-design, graphql-architect, nodejs-best-practices, nestjs-expert, fastapi-expert, typescript-pro, javascript-pro, python-pro, golang-pro, rust-pro
 handoffs:
   - agent: "penetration-tester"
     title: "Run Exploit Simulation"
@@ -61,7 +61,7 @@ Review code and architecture for exploitability with evidence-first triage and a
 | `auth-architect`        | Auth flow review, token management, session design, or access control audit. |
 | `vulnerability-scanner` | Dependency scanning, SAST/DAST results, or CVE triage.                       |
 | `static-analysis`       | Automated code analysis, linting for security rules, or code quality tools.  |
-| `api-designer`          | API security review — rate limiting, input validation, auth headers.         |
+| `api-design`          | API security review — rate limiting, input validation, auth headers.         |
 | `graphql-architect`     | GraphQL-specific security — depth limiting, introspection, authorization.    |
 
 ## Exploitability-First Triage

package/workflows/workflows/agent-environment-setup/shared/rules/STEERING.md

@@ -21,6 +21,10 @@ Follow this decision tree for EVERY user request:
 │   └─ Run skill_validate on that exact ID.
 │       ├─ Valid? → Load it and proceed. Stop.
 │       └─ Invalid/unavailable? → Fall through. Do not guess.
+├─ Is it non-trivial work with requirements, traceability, or spec language?
+│   └─ Prefer /spec unless the user already chose another valid route. Stop.
+├─ Is it architecture, design-system, ADR, or structure-governance work?
+│   └─ Prefer /architecture unless the user already chose another valid route. Stop.
 ├─ Is it multi-step work in ONE domain?
 │   └─ Pick the best-fit workflow. Load it. Stop.
 ├─ Is it cross-domain work spanning 2+ specialties?
@@ -33,6 +37,7 @@ Follow this decision tree for EVERY user request:
 
 > **Rule:** Inspect the repo and task locally BEFORE choosing a route or loading any skill.
 > **Rule:** If the user already chose the route, do not re-route it unless the named workflow, agent, or skill is invalid.
+> **Rule:** For non-trivial work, read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before planning or implementing.
 
 ---
 
@@ -48,6 +53,8 @@ Follow this decision tree for EVERY user request:
 | **skill_search**     | Fuzzy discovery tool                  | Domain unclear, no skill ID known yet                 | One narrow search AFTER route_resolve      | "what skill covers Prisma?"                 |
 | **route_resolve**    | Intent → route mapper                 | Free-text request doesn't match any known route       | MCP tool call with task description        | "I need to optimize my database"            |
 | **Orchestrator**     | Multi-specialist coordinator          | Work genuinely spans 2+ domains                       | `/orchestrate` or `@orchestrator`          | "build full-stack feature with auth"        |
+| **Spec workflow**    | Git-tracked spec pack                 | Non-trivial work needs durable scope, acceptance, and traceability | `/spec`                           | "turn this feature into an implementation spec" |
+| **Architecture workflow** | Architecture and design-system memory | Need to refresh structure, flows, ADRs, or design-system rules | `/architecture`                 | "update the clean architecture contract" |
 
 ---
 
@@ -65,6 +72,7 @@ Skills are **supporting context** unless the user explicitly named the exact ski
 8. Load reference files one at a time with `skill_get_reference` — only when a specific reference is needed.
 9. Do not auto-prime every specialist. Only load what `primarySkills` recommends or the task clearly needs.
 10. Never pass workflow IDs or agent IDs to skill tools.
+11. For `/architecture` and strict subprocess architecture generation, treat the skill bundle as already resolved. Attach the named skills directly instead of discovering them lazily.
 
 ---
 
@@ -89,6 +97,8 @@ Research output contract:
 - **Gaps / unknowns** — what could not be verified.
 - **Recommended next route** — workflow, agent, or skill to use after research.
 
+When the research result shows a change to product direction, project structure, boundaries, design system, or testing strategy, surface `doc_impact` and recommend `/architecture` or a managed-doc refresh before or after implementation.
+
 ---
 
 ## 4) Specialists
@@ -154,7 +164,9 @@ Use the best specialist first:
 
 | Intent Pattern                          | Workflow           | Primary Agent          |
 | --------------------------------------- | ------------------ | ---------------------- |
+| Build a spec pack with traceability     | `/spec`            | `@project-planner`     |
 | Plan a feature, design, or architecture | `/plan`            | `@project-planner`     |
+| Refresh architecture or design-system docs | `/architecture` | `@project-planner`     |
 | Implement a feature with quality gates  | `/create`          | varies by domain       |
 | Debug a complex issue                   | `/debug`           | `@debugger`            |
 | Write or verify tests                   | `/test`            | `@test-engineer`       |
@@ -183,6 +195,7 @@ Use the best specialist first:
 4. State what was NOT validated.
 5. Use web search only when information may be stale, public comparison matters, or the user explicitly asks.
 6. Prefer official docs first. Treat Reddit/community sources as secondary evidence and label them that way.
+7. If the task changes product direction, project structure, scaling assumptions, or design-system rules, update or flag `PRODUCT.md`, `ARCHITECTURE.md`, `ENGINEERING_RULES.md`, `TECH.md`, and `ROADMAP.md` as needed.
 
 ---
 

package/workflows/workflows/agent-environment-setup/shared/rules/overrides/codex.md

@@ -16,8 +16,8 @@
 ## Sandbox Constraints
 
 - Codex runs in an isolated sandbox — no persistent external network access by default.
-- All specialist references are **postures within the current session** — Codex does not spawn isolated subagents.
-- `@specialist` means: adopt that specialist's domain, reasoning style, and scope constraints internally.
+- Prefer native Codex delegation when the host exposes it cleanly. If native delegation is unavailable, treat specialist references as in-session postures.
+- `@specialist` means: use the platform's native delegation surface when available, otherwise adopt that specialist's domain, reasoning style, and scope constraints inline.
 - Prefer local file inspection over external fetches. Default to repo-grounded reasoning.
 - Foundry MCP tools (`skill_get`, `skill_search`, `skill_validate`, `route_resolve`) are available when the MCP server is connected. After `route_resolve`, load the returned `primarySkillHint` or `primarySkills[0]` via `skill_validate` → `skill_get` before executing non-trivial tasks.
 
@@ -25,5 +25,5 @@
 
 - Codex supports three autonomy levels: `suggest` (propose only), `auto-edit` (edit with confirmation), `full-auto` (autonomous execution).
 - Codex operates in a sandboxed environment — destructive operations are inherently limited.
-- Orchestration in Codex is sequential (no parallel subagent spawning) — adopt specialist postures one at a time.
+- Orchestration in Codex is capability-based: use native delegation when available, otherwise coordinate specialist postures sequentially.
 - Keep workflow instructions self-contained since network access for external docs may be restricted.

package/workflows/workflows/agent-environment-setup/shared/workflows/architecture.md

@@ -0,0 +1,85 @@
+---
+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: `@project-planner`
+- Documentation support: `@documentation-writer`
+- Research support: `@researcher`
+- Domain validation: `@backend-specialist`, `@frontend-specialist`, `@database-architect`
+
+## 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>] | []
+```

package/workflows/workflows/agent-environment-setup/shared/workflows/backend.md

@@ -36,12 +36,13 @@ 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
 
-- Primary skills: `api-designer`, `api-patterns`, `nodejs-best-practices`
-- Supporting skills (optional): `auth-architect`, `database-skills`, `database-design`, `nestjs-expert`, `fastapi-expert`, `graphql-architect`, `microservices-architect`, `drizzle-expert`, `firebase`, `stripe-best-practices`, `serverless-patterns`, `i18n-localization`, `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`
-- Start with `api-designer` for API contract work and `nodejs-best-practices` for Node.js services. Add framework-specific skill when applicable.
+- Primary skills: `api-design`, `api-patterns`, `nodejs-best-practices`
+- Supporting skills (optional): `auth-architect`, `database-design`, `database-design`, `nestjs-expert`, `fastapi-expert`, `graphql-architect`, `microservices-architect`, `drizzle-expert`, `firebase`, `stripe-best-practices`, `serverless-patterns`, `i18n-localization`, `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`
+- Start with `api-design` for API contract work and `nodejs-best-practices` for Node.js services. Add framework-specific skill when applicable.
 
 ## Workflow steps
 
@@ -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
 
@@ -65,8 +67,8 @@ Use this for backend architecture, API design, service implementation, or Postma
 BACKEND_WORKFLOW_RESULT:
   primary_agent: backend-specialist
   supporting_agents: [database-architect?, security-auditor?, test-engineer?]
-  primary_skills: [api-designer, api-patterns, nodejs-best-practices]
-  supporting_skills: [auth-architect?, database-skills?, <framework-skill>?]
+  primary_skills: [api-design, api-patterns, nodejs-best-practices]
+  supporting_skills: [auth-architect?, database-design?, <framework-skill>?]
   api_changes:
     endpoints_created: [<string>] | []
     endpoints_modified: [<string>] | []
@@ -74,6 +76,7 @@ BACKEND_WORKFLOW_RESULT:
   implementation:
     files_changed: [<path>]
     tests_added: [<path>]
+  doc_impact: none | tech | rules | both
   verification:
     checks_run: [<command-or-test>]
     evidence: [<string>]

package/workflows/workflows/agent-environment-setup/shared/workflows/create.md

@@ -22,11 +22,12 @@ Use this for net-new implementation after design is stable.
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach logs, screenshots, failing output, and relevant paths when context is incomplete.
+- Read `ENGINEERING_RULES.md` first and `TECH.md` next for non-trivial work so new code follows the declared architecture and design-system rules.
 
 ## Skill Routing
 
 - Primary skills: `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`, `java-pro`, `csharp-pro`, `kotlin-pro`, `rust-pro`, `php-pro`, `ruby-pro`, `c-pro`, `cpp-pro`, `dart-pro`, `swift-pro`
-- Supporting skills (optional): `api-designer`, `api-patterns`, `nodejs-best-practices`, `nestjs-expert`, `fastapi-expert`, `graphql-architect`, `drizzle-expert`, `firebase`, `mcp-builder`, `stitch`, `react-expert`, `react-best-practices`, `nextjs-developer`, `tailwind-patterns`, `frontend-design`, `design-system-builder`, `web-perf`, `skill-creator`, `stripe-best-practices`, `serverless-patterns`, `i18n-localization`
+- Supporting skills (optional): `api-design`, `api-patterns`, `nodejs-best-practices`, `nestjs-expert`, `fastapi-expert`, `graphql-architect`, `drizzle-expert`, `firebase`, `mcp-server-builder`, `stitch`, `react-expert`, `react-best-practices`, `nextjs-developer`, `tailwind-patterns`, `frontend-design`, `design-system-builder`, `web-perf`, `skill-creator`, `stripe-best-practices`, `serverless-patterns`, `i18n-localization`
 - Pick one primary language skill from repo signals or touched files. Add the narrowest specialist only when the feature is clearly backend or frontend framework-specific.
 - If the request references Stitch screens, artifacts, design-to-code, or UI sync, add `stitch` first and route the implementation through the frontend or mobile specialist based on the destination surface.
 
@@ -35,7 +36,8 @@ Use this for net-new implementation after design is stable.
 1. Confirm target files and contracts.
 2. Implement smallest coherent increment.
 3. Validate behavior with focused tests.
-4. Capture remaining gaps and follow-ups.
+4. Capture `doc_impact` when the feature changes architecture, boundaries, scale, or design-system rules.
+5. Capture remaining gaps and follow-ups.
 
 ## Verification
 
@@ -55,6 +57,7 @@ CREATE_WORKFLOW_RESULT:
     summary: <string>
     changed_artifacts: [<path-or-artifact>]
   behavioral_impact: [<string>]
+  doc_impact: none | tech | rules | both
   verification:
     checks_run: [<command-or-test>]
     evidence: [<string>]

package/workflows/workflows/agent-environment-setup/shared/workflows/database.md

@@ -20,12 +20,13 @@ Use this for schema design, query optimization, migration planning, or database
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach existing schema, migration history, query patterns, and performance requirements.
+- Read `ENGINEERING_RULES.md` and `TECH.md` before changing data ownership, persistence boundaries, or shared schema conventions.
 
 ## Skill Routing
 
-- Primary skills: `database-design`, `database-optimizer`, `database-skills`
+- Primary skills: `database-design`, `database-optimizer`, `database-design`
 - Supporting skills (optional): `drizzle-expert`, `postgres`, `mysql`, `sqlite`, `mongodb`, `redis`, `supabase`, `firebase`, `vitess`, `typescript-pro`, `javascript-pro`, `python-pro`
-- Start with `database-design` for schema work, `database-optimizer` for performance, or `database-skills` for general database operations. Add engine-specific skill when applicable.
+- Start with `database-design` for schema work, `database-optimizer` for performance, or `database-design` for general database operations. Add engine-specific skill when applicable.
 
 ## Workflow steps
 
@@ -34,6 +35,7 @@ Use this for schema design, query optimization, migration planning, or database
 3. Plan migration with rollback strategy.
 4. Optimize queries and indexes for known access patterns.
 5. Validate data integrity constraints.
+6. Set `doc_impact` if the change alters data boundaries, core entities, or persistence patterns that future work should follow.
 
 ## Verification
 
@@ -48,7 +50,7 @@ Use this for schema design, query optimization, migration planning, or database
 DATABASE_WORKFLOW_RESULT:
   primary_agent: database-architect
   supporting_agents: [backend-specialist?, test-engineer?]
-  primary_skills: [database-design, database-optimizer, database-skills]
+  primary_skills: [database-design, database-optimizer, database-design]
   supporting_skills: [<engine-specific-skill>?, drizzle-expert?]
   schema_changes:
     tables_affected: [<string>]
@@ -57,6 +59,7 @@ DATABASE_WORKFLOW_RESULT:
   query_optimization:
     queries_reviewed: <number>
     indexes_recommended: [<string>] | []
+  doc_impact: none | tech | rules | both
   integrity_checks: [<string>]
   follow_up_items: [<string>] | []
 ```