@cubis/foundry 0.3.76 → 0.3.78

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,21 +21,21 @@ 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 `deep-research` when planning requires external information or comparison.
+- 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.
 
 ## Skill References
 
 | 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
@@ -45,6 +45,7 @@ Decompose complex requests into implementable plans with clear ownership, depend
 - Every task needs an owner (agent), acceptance criteria, and verification approach.
 - Plan for rollback — every change should be reversible.
 - Front-load risk — tackle the hardest technical uncertainty first.
+- When outside evidence is needed, send research through `deep-research` first instead of mixing web browsing into every implementation stream.
 
 ## Planning Methodology
 

package/workflows/workflows/agent-environment-setup/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.
-- Load `deep-research` first for all research tasks — it defines the research methodology.
-- Add `architecture-designer` when research involves system design patterns or tradeoffs.
-- Add `database-skills` when research involves data storage options or migration approaches.
+- 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 `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,14 +43,17 @@ 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
 
 - Breadth first, then depth — survey the landscape before drilling into specifics.
+- Repo first, then web — inspect local code, configs, and docs before using external sources.
+- Official docs first — use vendor or maintainer documentation as primary evidence.
+- Community evidence is secondary — Reddit, blog posts, and forum threads can inform implementation, but label them as lower-trust support.
 - Cite sources — every finding should be traceable to evidence.
 - Distinguish fact from inference — clearly label assumptions.
 - Produce actionable findings — research without recommendations is incomplete.
@@ -72,3 +75,4 @@ Investigate thoroughly, synthesize findings, and deliver structured knowledge be
 - Clear distinction between verified facts and educated guesses.
 - Actionable recommendations with tradeoff analysis.
 - Remaining knowledge gaps identified.
+- Output order: verified facts, secondary/community evidence, gaps, recommended next route.

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

@@ -1,9 +1,9 @@
 # Cubis Foundry — Shared Steering Protocol
 
-This is the canonical steering template. Platform-specific rules files are generated from this template
-plus per-platform overrides. Edit only here — never edit platform rules files directly.
+This is the canonical steering source for routing policy and managed MCP block language.
+Keep platform rule files aligned with this template plus per-platform overrides, and do not duplicate the managed block into agent or workflow markdown.
 
-Generation: `npm run generate:platform-assets` (or `cbx workflows sync-rules`)
+Managed-block sync: `npm run inject:mcp-rules:all` (or `cbx workflows sync-rules`)
 
 ---
 
@@ -17,6 +17,14 @@ Follow this decision tree for EVERY user request:
 │   └─ Execute directly. No routing needed. Stop.
 ├─ Did user explicitly name a workflow or agent?
 │   └─ Honor that route first. Stop.
+├─ Did user explicitly name an exact skill ID?
+│   └─ 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?
@@ -28,6 +36,8 @@ 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 `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before planning or implementing.
 
 ---
 
@@ -38,26 +48,56 @@ Follow this decision tree for EVERY user request:
 | **Direct execution** | No routing needed                     | Small, clear, single-step tasks                       | Just do it                                 | "rename this variable"                      |
 | **Workflow**         | Multi-step recipe with verification   | Structured task with known pattern                    | `/plan`, `/create`, `/debug`, `/test`      | "plan the auth system"                      |
 | **Agent**            | Specialist persona with domain skills | Domain expertise needed for execution                 | `@backend-specialist`, `@security-auditor` | "design the API schema"                     |
+| **Named skill**      | Exact skill selected by the user      | User already named the skill and it validates cleanly | `skill_validate` → `skill_get`             | "use stitch for this screen"                |
 | **Skill (MCP)**      | Supporting domain knowledge           | Domain context that a workflow or agent doesn't cover | `skill_get` after `skill_validate`         | loading `typescript-pro` for TS conventions |
 | **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" |
 
 ---
 
 ## 3) Skill Loading Protocol
 
-Skills are **supporting context** — always route first, then load what the route recommends.
+Skills are **supporting context** unless the user explicitly named the exact skill. In that case validate the named skill first, then proceed without route discovery.
 
 1. **Never begin with `skill_search`.** Inspect the repo/task locally first.
-2. Resolve the route (workflow, agent, or direct execution) before loading any skills.
-3. **After routing: if `route_resolve` returned `primarySkillHint` or `primarySkills`, load the first via `skill_validate` → `skill_get` before executing. Not optional for non-trivial tasks.**
-4. If `detectedLanguageSkill` is returned and matches the project, load it too (if not already loaded this session).
-5. Domain still unclear after routing? → ONE narrow `skill_search`. Not two.
-6. Call `skill_get` with `includeReferences: false` by default.
-7. Load reference files one at a time with `skill_get_reference` — only when a specific reference is needed.
-8. Do not auto-prime every specialist. Only load what `primarySkills` recommends or the task clearly needs.
-9. Never pass workflow IDs or agent IDs to skill tools.
+2. If the user explicitly named an exact skill ID, run `skill_validate` on that ID before any `route_resolve` call.
+3. Resolve the route (workflow, agent, or direct execution) before loading any non-explicit skills.
+4. **After routing: if `route_resolve` returned `primarySkillHint` or `primarySkills`, load the first via `skill_validate` → `skill_get` before executing. Not optional for non-trivial tasks.**
+5. If `detectedLanguageSkill` is returned and matches the project, load it too (if not already loaded this session).
+6. Domain still unclear after routing? → ONE narrow `skill_search`. Not two.
+7. Call `skill_get` with `includeReferences: false` by default.
+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.
+
+---
+
+## 4A) Research Escalation
+
+Use external research only when one of these is true:
+
+1. Freshness matters: latest APIs, model behavior, vendor docs, pricing, policies, releases, or client capabilities.
+2. Public comparison matters: tradeoff analysis across tools, frameworks, libraries, or hosted services.
+3. The user explicitly asks to research, compare, verify, or gather outside evidence.
+
+Research source ladder:
+
+1. **Repo/local evidence first** — inspect code, config, docs, tests, and installed artifacts before going outside the workspace.
+2. **Official docs next** — vendor docs, upstream repos, standards, or maintainer documentation are primary evidence.
+3. **Community evidence last** — Reddit, blog posts, issue threads, and forum posts are allowed only as labeled secondary evidence.
+
+Research output contract:
+
+- **Verified facts** — claims backed by primary sources or local repo evidence.
+- **Secondary/community evidence** — useful but lower-trust signals, clearly labeled.
+- **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 project structure, boundaries, design system, or testing strategy, surface `doc_impact` and recommend `/architecture` or a managed-doc refresh before or after implementation.
 
 ---
 
@@ -124,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`       |
@@ -151,7 +193,9 @@ Use the best specialist first:
 2. Keep diffs small and reversible when possible.
 3. Verify with focused checks before finalizing.
 4. State what was NOT validated.
-5. Use web search only when information may be stale or the user explicitly asks.
+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 project structure, scaling assumptions, or design-system rules, update or flag `ENGINEERING_RULES.md` and `TECH.md`.
 
 ---
 

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

@@ -5,6 +5,7 @@
 - Workflows: `.claude/workflows`
 - Agents: `.claude/agents`
 - Skills: `.claude/skills`
+- Hook templates: `.claude/hooks`
 - Rules file: `CLAUDE.md`
 - Scoped rules: `.claude/rules/*.md` (with `paths:` frontmatter)
 
@@ -26,4 +27,5 @@
 - Scoped rules in `.claude/rules/*.md` use `paths:` frontmatter for targeted file-pattern matching.
 - Global rules live in `~/.claude/CLAUDE.md` and apply to all projects.
 - Skills with `context: fork` spawn as isolated subagents for research-heavy or exploratory tasks.
+- Optional hook templates in `.claude/hooks/` can reinforce explicit-route honoring and research escalation at `UserPromptSubmit`.
 - Use `$ARGUMENTS` in skill content for dynamic parameterization from user queries.

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/rules/overrides/gemini.md

@@ -0,0 +1,20 @@
+# Gemini CLI — Platform Overrides
+
+## Platform Paths
+
+- Workflows: `.gemini/workflows`
+- Skills: `.gemini/skills`
+- Commands: `.gemini/commands`
+- Rules file: `.gemini/GEMINI.md` (or `GEMINI.md` at repo root when used directly)
+
+## Platform-Specific Routing
+
+1. **Explicit Gemini command** (`.gemini/commands/*.toml`) — highest priority route.
+2. **Explicit workflow or named skill** — honor it directly before route discovery.
+3. Standard workflow and MCP routing from shared steering.
+
+## Platform Notes
+
+- Gemini CLI uses GEMINI.md plus TOML commands as the primary enforcement surface.
+- Gemini specialist behavior is posture-based; it does not rely on standalone agent markdown in the project profile.
+- Use command wrappers to reinforce route-resolved execution and research escalation when freshness or public comparison matters.

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

@@ -0,0 +1,80 @@
+---
+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: `@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 `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>] | []
+```

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>] | []
 ```

package/workflows/workflows/agent-environment-setup/shared/workflows/implement-track.md

@@ -20,12 +20,14 @@ Use this for large-scale implementation work that spans multiple sessions or mil
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach the implementation plan, milestone definitions, and acceptance criteria per milestone.
+- Reuse `docs/specs/<spec-id>/` when present instead of maintaining a separate progress source of truth.
+- Read `ENGINEERING_RULES.md` first and `TECH.md` next before starting milestone execution.
 
 ## Skill Routing
 
-- Primary skills: `architecture-designer`, `api-designer`
-- Supporting skills (optional): `database-skills`, `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`, `react-expert`, `nextjs-developer`
-- Start with `architecture-designer` for milestone planning. Load domain-specific skills per milestone based on implementation needs.
+- Primary skills: `system-design`, `api-design`
+- Supporting skills (optional): `database-design`, `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`, `react-expert`, `nextjs-developer`
+- Start with `system-design` for milestone planning. Load domain-specific skills per milestone based on implementation needs.
 
 ## Workflow steps
 
@@ -33,7 +35,7 @@ Use this for large-scale implementation work that spans multiple sessions or mil
 2. Execute current milestone with focused implementation.
 3. Run quality gate validation at milestone completion.
 4. Update progress tracking and capture status.
-5. Adjust remaining plan based on learnings.
+5. Adjust remaining plan, spec traceability, and doc refresh needs based on learnings.
 6. Proceed to next milestone or report completion.
 
 ## Verification
@@ -49,8 +51,8 @@ Use this for large-scale implementation work that spans multiple sessions or mil
 IMPLEMENT_TRACK_WORKFLOW_RESULT:
   primary_agent: orchestrator
   supporting_agents: [<milestone-agents>]
-  primary_skills: [architecture-designer, api-designer]
-  supporting_skills: [database-skills?, typescript-pro?, javascript-pro?, python-pro?, golang-pro?, react-expert?, nextjs-developer?]
+  primary_skills: [system-design, api-design]
+  supporting_skills: [database-design?, typescript-pro?, javascript-pro?, python-pro?, golang-pro?, react-expert?, nextjs-developer?]
   milestones:
     - id: <milestone-id>
       description: <string>
@@ -59,5 +61,9 @@ IMPLEMENT_TRACK_WORKFLOW_RESULT:
       validation_evidence: <string>
   overall_progress: <percentage>
   scope_changes: [<string>] | []
+  spec_id: <string> | null
+  spec_root: docs/specs/<spec-id> | null
+  traceability_status: complete | partial | blocked
+  doc_impact: none | tech | rules | both
   follow_up_items: [<string>] | []
 ```

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

@@ -28,12 +28,13 @@ Use this for technology migrations, framework upgrades, dependency updates, or m
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach the migration target, current versions, breaking change lists, and impact assessment.
+- Read `ENGINEERING_RULES.md` and `TECH.md` first because migrations often change accepted patterns and current-state architecture at the same time.
 
 ## Skill Routing
 
-- Primary skills: `legacy-modernizer`, `architecture-designer`
+- Primary skills: `legacy-modernizer`, `system-design`
 - Supporting skills (optional): `static-analysis`, `testing-patterns`, `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`
-- Start with `legacy-modernizer` for migration methodology and `architecture-designer` for system impact. Add `static-analysis` for automated codemod or compatibility analysis.
+- Start with `legacy-modernizer` for migration methodology and `system-design` for system impact. Add `static-analysis` for automated codemod or compatibility analysis.
 
 ## Workflow steps
 
@@ -42,7 +43,8 @@ Use this for technology migrations, framework upgrades, dependency updates, or m
 3. Plan incremental migration steps with rollback points.
 4. Execute migration one step at a time with verification.
 5. Update tests and documentation for new patterns.
-6. Verify full system behavior after migration complete.
+6. Set `doc_impact` when the migration changes architecture, deployment shape, boundaries, or design-system rules.
+7. Verify full system behavior after migration complete.
 
 ## Verification
 
@@ -58,7 +60,7 @@ Use this for technology migrations, framework upgrades, dependency updates, or m
 MIGRATE_WORKFLOW_RESULT:
   primary_agent: code-archaeologist
   supporting_agents: [backend-specialist?, frontend-specialist?, test-engineer?, validator?]
-  primary_skills: [legacy-modernizer, architecture-designer]
+  primary_skills: [legacy-modernizer, system-design]
   supporting_skills: [static-analysis?, testing-patterns?]
   migration:
     from: <string>
@@ -69,5 +71,6 @@ MIGRATE_WORKFLOW_RESULT:
   verification:
     tests_passed: true | false
     performance_impact: <string>
+  doc_impact: none | tech | rules | both
   follow_up_items: [<string>] | []
 ```