@cubis/foundry 0.3.78 → 0.3.79

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-implement-track.prompt.md

@@ -7,7 +7,7 @@ Use this prompt with the matching workflow file:
 
 Execution contract:
 1. Treat route selection as already resolved by this prompt; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `system-design`, `api-design`, `database-design`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`, `react`, `nextjs`.
 - Local skill file hints if installed: `.github/skills/system-design/SKILL.md`, `.github/skills/api-design/SKILL.md`, `.github/skills/database-design/SKILL.md`, `.github/skills/typescript-best-practices/SKILL.md`, `.github/skills/javascript-best-practices/SKILL.md`, `.github/skills/python-best-practices/SKILL.md`, `.github/skills/golang-best-practices/SKILL.md`, `.github/skills/react/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-migrate.prompt.md

@@ -7,7 +7,7 @@ Use this prompt with the matching workflow file:
 
 Execution contract:
 1. Treat route selection as already resolved by this prompt; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `system-design`, `code-review`, `unit-testing`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`.
 - Local skill file hints if installed: `.github/skills/system-design/SKILL.md`, `.github/skills/code-review/SKILL.md`, `.github/skills/unit-testing/SKILL.md`, `.github/skills/typescript-best-practices/SKILL.md`, `.github/skills/javascript-best-practices/SKILL.md`, `.github/skills/python-best-practices/SKILL.md`, `.github/skills/golang-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-mobile.prompt.md

@@ -7,7 +7,7 @@ Use this prompt with the matching workflow file:
 
 Execution contract:
 1. Treat route selection as already resolved by this prompt; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `expo-app`, `react-native`, `stitch`, `frontend-design`, `swift-best-practices`, `kotlin-best-practices`.
 - Local skill file hints if installed: `.github/skills/expo-app/SKILL.md`, `.github/skills/react-native/SKILL.md`, `.github/skills/stitch/SKILL.md`, `.github/skills/frontend-design/SKILL.md`, `.github/skills/swift-best-practices/SKILL.md`, `.github/skills/kotlin-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-onboard.prompt.md

@@ -7,7 +7,7 @@ Use this prompt with the matching workflow file:
 
 Execution contract:
 1. Treat route selection as already resolved by this prompt; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `deep-research`, `system-design`, `database-design`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`.
 - Local skill file hints if installed: `.github/skills/deep-research/SKILL.md`, `.github/skills/system-design/SKILL.md`, `.github/skills/database-design/SKILL.md`, `.github/skills/typescript-best-practices/SKILL.md`, `.github/skills/javascript-best-practices/SKILL.md`, `.github/skills/python-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-orchestrate.prompt.md

@@ -7,7 +7,7 @@ Use this prompt with the matching workflow file:
 
 Execution contract:
 1. Treat route selection as already resolved by this prompt; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `system-design`, `api-design`, `database-design`, `deep-research`, `mcp-server-builder`, `tech-doc`, `prompt-engineering`, `skill-creator`.
 - Local skill file hints if installed: `.github/skills/system-design/SKILL.md`, `.github/skills/api-design/SKILL.md`, `.github/skills/database-design/SKILL.md`, `.github/skills/deep-research/SKILL.md`, `.github/skills/mcp-server-builder/SKILL.md`, `.github/skills/tech-doc/SKILL.md`, `.github/skills/prompt-engineering/SKILL.md`, `.github/skills/skill-creator/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-plan.prompt.md

@@ -7,7 +7,7 @@ Use this prompt with the matching workflow file:
 
 Execution contract:
 1. Treat route selection as already resolved by this prompt; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `system-design`, `api-design`, `database-design`, `deep-research`, `mcp-server-builder`, `tech-doc`, `prompt-engineering`, `skill-creator`.
 - Local skill file hints if installed: `.github/skills/system-design/SKILL.md`, `.github/skills/api-design/SKILL.md`, `.github/skills/database-design/SKILL.md`, `.github/skills/deep-research/SKILL.md`, `.github/skills/mcp-server-builder/SKILL.md`, `.github/skills/tech-doc/SKILL.md`, `.github/skills/prompt-engineering/SKILL.md`, `.github/skills/skill-creator/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-refactor.prompt.md

@@ -7,7 +7,7 @@ Use this prompt with the matching workflow file:
 
 Execution contract:
 1. Treat route selection as already resolved by this prompt; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `code-review`, `system-design`, `unit-testing`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`.
 - Local skill file hints if installed: `.github/skills/code-review/SKILL.md`, `.github/skills/system-design/SKILL.md`, `.github/skills/unit-testing/SKILL.md`, `.github/skills/typescript-best-practices/SKILL.md`, `.github/skills/javascript-best-practices/SKILL.md`, `.github/skills/python-best-practices/SKILL.md`, `.github/skills/golang-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-release.prompt.md

@@ -7,7 +7,7 @@ Use this prompt with the matching workflow file:
 
 Execution contract:
 1. Treat route selection as already resolved by this prompt; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `ci-cd-pipeline`, `git-workflow`, `tech-doc`, `observability`, `kubernetes-deploy`, `typescript-best-practices`, `javascript-best-practices`.
 - Local skill file hints if installed: `.github/skills/ci-cd-pipeline/SKILL.md`, `.github/skills/git-workflow/SKILL.md`, `.github/skills/tech-doc/SKILL.md`, `.github/skills/observability/SKILL.md`, `.github/skills/kubernetes-deploy/SKILL.md`, `.github/skills/typescript-best-practices/SKILL.md`, `.github/skills/javascript-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-review.prompt.md

@@ -7,7 +7,7 @@ Use this prompt with the matching workflow file:
 
 Execution contract:
 1. Treat route selection as already resolved by this prompt; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `code-review`, `unit-testing`, `owasp-security-review`, `performance-testing`, `react`, `nextjs`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`.
 - Local skill file hints if installed: `.github/skills/code-review/SKILL.md`, `.github/skills/unit-testing/SKILL.md`, `.github/skills/owasp-security-review/SKILL.md`, `.github/skills/performance-testing/SKILL.md`, `.github/skills/react/SKILL.md`, `.github/skills/nextjs/SKILL.md`, `.github/skills/typescript-best-practices/SKILL.md`, `.github/skills/javascript-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-security.prompt.md

@@ -7,7 +7,7 @@ Use this prompt with the matching workflow file:
 
 Execution contract:
 1. Treat route selection as already resolved by this prompt; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `owasp-security-review`, `code-review`, `api-design`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`, `rust-best-practices`.
 - Local skill file hints if installed: `.github/skills/owasp-security-review/SKILL.md`, `.github/skills/code-review/SKILL.md`, `.github/skills/api-design/SKILL.md`, `.github/skills/typescript-best-practices/SKILL.md`, `.github/skills/javascript-best-practices/SKILL.md`, `.github/skills/python-best-practices/SKILL.md`, `.github/skills/golang-best-practices/SKILL.md`, `.github/skills/rust-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-spec.prompt.md

@@ -7,7 +7,7 @@ Use this prompt with the matching workflow file:
 
 Execution contract:
 1. Treat route selection as already resolved by this prompt; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `spec-driven-delivery`, `sadd`, `system-design`, `architecture-doc`, `deep-research`, `api-design`, `database-design`, `tech-doc`.
 - Local skill file hints if installed: `.github/skills/spec-driven-delivery/SKILL.md`, `.github/skills/sadd/SKILL.md`, `.github/skills/system-design/SKILL.md`, `.github/skills/architecture-doc/SKILL.md`, `.github/skills/deep-research/SKILL.md`, `.github/skills/api-design/SKILL.md`, `.github/skills/database-design/SKILL.md`, `.github/skills/tech-doc/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-test.prompt.md

@@ -7,7 +7,7 @@ Use this prompt with the matching workflow file:
 
 Execution contract:
 1. Treat route selection as already resolved by this prompt; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `unit-testing`, `integration-testing`, `playwright-interactive`, `observability`, `systematic-debugging`, `code-review`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`, `java-best-practices`.
 - Local skill file hints if installed: `.github/skills/unit-testing/SKILL.md`, `.github/skills/integration-testing/SKILL.md`, `.github/skills/playwright-interactive/SKILL.md`, `.github/skills/observability/SKILL.md`, `.github/skills/systematic-debugging/SKILL.md`, `.github/skills/code-review/SKILL.md`, `.github/skills/typescript-best-practices/SKILL.md`, `.github/skills/javascript-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-vercel.prompt.md

@@ -7,7 +7,7 @@ Use this prompt with the matching workflow file:
 
 Execution contract:
 1. Treat route selection as already resolved by this prompt; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `nextjs`, `ci-cd-pipeline`, `performance-testing`, `react`, `frontend-design`, `javascript-best-practices`, `typescript-best-practices`.
 - Local skill file hints if installed: `.github/skills/nextjs/SKILL.md`, `.github/skills/ci-cd-pipeline/SKILL.md`, `.github/skills/performance-testing/SKILL.md`, `.github/skills/react/SKILL.md`, `.github/skills/frontend-design/SKILL.md`, `.github/skills/javascript-best-practices/SKILL.md`, `.github/skills/typescript-best-practices/SKILL.md`.

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

@@ -1,6 +1,6 @@
 ---
 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."
+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",
@@ -18,7 +18,7 @@ triggers:
 
 ## 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.
+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
 
@@ -35,24 +35,25 @@ Use this when the task is to declare, refresh, or validate the project architect
 
 ## 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.
+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`.
-- `ENGINEERING_RULES.md` is normative. `TECH.md` is descriptive. Keep them aligned but not redundant.
+- `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 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.
+- 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
@@ -64,9 +65,13 @@ ARCHITECTURE_WORKFLOW_RESULT:
   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
-  files_updated: [ENGINEERING_RULES.md, 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>]

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

@@ -38,12 +38,12 @@ Use this for non-trivial work that needs durable planning in Git before implemen
 1. Determine whether the task is non-trivial enough to justify a spec pack.
 2. Find an existing `docs/specs/<spec-id>/` pack or create a new stable `spec_id`.
 3. Write or refresh the spec pack with brief, acceptance, tasks, traceability, and handoff files.
-4. Record `architecture_impact`, `doc_impact`, and any required updates to `ENGINEERING_RULES.md` or `TECH.md`.
+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 `ENGINEERING_RULES.md` first and `TECH.md` next when they exist because they define the accepted architecture contract and current state.
+- 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.
 

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/accessibility.toml

@@ -4,7 +4,7 @@ Follow the /accessibility workflow from .gemini/workflows/accessibility.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `code-review`, `frontend-design`, `performance-testing`, `react`, `nextjs`, `playwright-interactive`, `typescript-best-practices`, `javascript-best-practices`.
 - Local skill file hints if installed: `.gemini/skills/code-review/SKILL.md`, `.gemini/skills/frontend-design/SKILL.md`, `.gemini/skills/performance-testing/SKILL.md`, `.gemini/skills/react/SKILL.md`, `.gemini/skills/nextjs/SKILL.md`, `.gemini/skills/playwright-interactive/SKILL.md`, `.gemini/skills/typescript-best-practices/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/architecture.toml

@@ -1,10 +1,10 @@
-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."
+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."
 prompt = '''
 Follow the /architecture workflow from .gemini/workflows/architecture.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `architecture-doc`, `system-design`, `tech-doc`, `frontend-design`, `api-design`, `database-design`, `sadd`, `deep-research`.
 - Local skill file hints if installed: `.gemini/skills/architecture-doc/SKILL.md`, `.gemini/skills/system-design/SKILL.md`, `.gemini/skills/tech-doc/SKILL.md`, `.gemini/skills/frontend-design/SKILL.md`, `.gemini/skills/api-design/SKILL.md`, `.gemini/skills/database-design/SKILL.md`, `.gemini/skills/sadd/SKILL.md`, `.gemini/skills/deep-research/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/backend.toml

@@ -4,7 +4,7 @@ Follow the /backend workflow from .gemini/workflows/backend.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `api-design`, `javascript-best-practices`, `owasp-security-review`, `database-design`, `nestjs`, `fastapi`, `microservices-design`, `drizzle-orm`, `stripe-integration`, `ci-cd-pipeline`, `frontend-design`, `typescript-best-practices`, `python-best-practices`, `golang-best-practices`.
 - Local skill file hints if installed: `.gemini/skills/api-design/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`, `.gemini/skills/owasp-security-review/SKILL.md`, `.gemini/skills/database-design/SKILL.md`, `.gemini/skills/nestjs/SKILL.md`, `.gemini/skills/fastapi/SKILL.md`, `.gemini/skills/microservices-design/SKILL.md`, `.gemini/skills/drizzle-orm/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/create.toml

@@ -4,7 +4,7 @@ Follow the /create workflow from .gemini/workflows/create.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`, `java-best-practices`, `csharp-best-practices`, `kotlin-best-practices`, `rust-best-practices`, `php-best-practices`, `expo-app`, `swift-best-practices`, `api-design`, `nestjs`, `fastapi`, `drizzle-orm`, `database-design`, `mcp-server-builder`, `stitch`, `react`, `nextjs`, `frontend-design`, `performance-testing`, `skill-creator`, `stripe-integration`, `ci-cd-pipeline`.
 - Local skill file hints if installed: `.gemini/skills/typescript-best-practices/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`, `.gemini/skills/python-best-practices/SKILL.md`, `.gemini/skills/golang-best-practices/SKILL.md`, `.gemini/skills/java-best-practices/SKILL.md`, `.gemini/skills/csharp-best-practices/SKILL.md`, `.gemini/skills/kotlin-best-practices/SKILL.md`, `.gemini/skills/rust-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/database.toml

@@ -4,7 +4,7 @@ Follow the /database workflow from .gemini/workflows/database.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `database-design`, `drizzle-orm`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`.
 - Local skill file hints if installed: `.gemini/skills/database-design/SKILL.md`, `.gemini/skills/drizzle-orm/SKILL.md`, `.gemini/skills/typescript-best-practices/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`, `.gemini/skills/python-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/debug.toml

@@ -4,7 +4,7 @@ Follow the /debug workflow from .gemini/workflows/debug.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `systematic-debugging`, `observability`, `unit-testing`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`, `java-best-practices`, `csharp-best-practices`, `kotlin-best-practices`, `rust-best-practices`, `integration-testing`, `playwright-interactive`, `skill-creator`.
 - Local skill file hints if installed: `.gemini/skills/systematic-debugging/SKILL.md`, `.gemini/skills/observability/SKILL.md`, `.gemini/skills/unit-testing/SKILL.md`, `.gemini/skills/typescript-best-practices/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`, `.gemini/skills/python-best-practices/SKILL.md`, `.gemini/skills/golang-best-practices/SKILL.md`, `.gemini/skills/java-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/devops.toml

@@ -4,7 +4,7 @@ Follow the /devops workflow from .gemini/workflows/devops.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `ci-cd-pipeline`, `kubernetes-deploy`, `observability`, `git-workflow`, `systematic-debugging`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`.
 - Local skill file hints if installed: `.gemini/skills/ci-cd-pipeline/SKILL.md`, `.gemini/skills/kubernetes-deploy/SKILL.md`, `.gemini/skills/observability/SKILL.md`, `.gemini/skills/git-workflow/SKILL.md`, `.gemini/skills/systematic-debugging/SKILL.md`, `.gemini/skills/typescript-best-practices/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`, `.gemini/skills/python-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/implement-track.toml

@@ -4,7 +4,7 @@ Follow the /implement-track workflow from .gemini/workflows/implement-track.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `system-design`, `api-design`, `database-design`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`, `react`, `nextjs`.
 - Local skill file hints if installed: `.gemini/skills/system-design/SKILL.md`, `.gemini/skills/api-design/SKILL.md`, `.gemini/skills/database-design/SKILL.md`, `.gemini/skills/typescript-best-practices/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`, `.gemini/skills/python-best-practices/SKILL.md`, `.gemini/skills/golang-best-practices/SKILL.md`, `.gemini/skills/react/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/migrate.toml

@@ -4,7 +4,7 @@ Follow the /migrate workflow from .gemini/workflows/migrate.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `system-design`, `code-review`, `unit-testing`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`.
 - Local skill file hints if installed: `.gemini/skills/system-design/SKILL.md`, `.gemini/skills/code-review/SKILL.md`, `.gemini/skills/unit-testing/SKILL.md`, `.gemini/skills/typescript-best-practices/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`, `.gemini/skills/python-best-practices/SKILL.md`, `.gemini/skills/golang-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/mobile.toml

@@ -4,7 +4,7 @@ Follow the /mobile workflow from .gemini/workflows/mobile.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `expo-app`, `react-native`, `stitch`, `frontend-design`, `swift-best-practices`, `kotlin-best-practices`.
 - Local skill file hints if installed: `.gemini/skills/expo-app/SKILL.md`, `.gemini/skills/react-native/SKILL.md`, `.gemini/skills/stitch/SKILL.md`, `.gemini/skills/frontend-design/SKILL.md`, `.gemini/skills/swift-best-practices/SKILL.md`, `.gemini/skills/kotlin-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/onboard.toml

@@ -4,7 +4,7 @@ Follow the /onboard workflow from .gemini/workflows/onboard.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `deep-research`, `system-design`, `database-design`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`.
 - Local skill file hints if installed: `.gemini/skills/deep-research/SKILL.md`, `.gemini/skills/system-design/SKILL.md`, `.gemini/skills/database-design/SKILL.md`, `.gemini/skills/typescript-best-practices/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`, `.gemini/skills/python-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/orchestrate.toml

@@ -4,7 +4,7 @@ Follow the /orchestrate workflow from .gemini/workflows/orchestrate.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `system-design`, `api-design`, `database-design`, `deep-research`, `mcp-server-builder`, `tech-doc`, `prompt-engineering`, `skill-creator`.
 - Local skill file hints if installed: `.gemini/skills/system-design/SKILL.md`, `.gemini/skills/api-design/SKILL.md`, `.gemini/skills/database-design/SKILL.md`, `.gemini/skills/deep-research/SKILL.md`, `.gemini/skills/mcp-server-builder/SKILL.md`, `.gemini/skills/tech-doc/SKILL.md`, `.gemini/skills/prompt-engineering/SKILL.md`, `.gemini/skills/skill-creator/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/plan.toml

@@ -4,7 +4,7 @@ Follow the /plan workflow from .gemini/workflows/plan.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `system-design`, `api-design`, `database-design`, `deep-research`, `mcp-server-builder`, `tech-doc`, `prompt-engineering`, `skill-creator`.
 - Local skill file hints if installed: `.gemini/skills/system-design/SKILL.md`, `.gemini/skills/api-design/SKILL.md`, `.gemini/skills/database-design/SKILL.md`, `.gemini/skills/deep-research/SKILL.md`, `.gemini/skills/mcp-server-builder/SKILL.md`, `.gemini/skills/tech-doc/SKILL.md`, `.gemini/skills/prompt-engineering/SKILL.md`, `.gemini/skills/skill-creator/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/refactor.toml

@@ -4,7 +4,7 @@ Follow the /refactor workflow from .gemini/workflows/refactor.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `code-review`, `system-design`, `unit-testing`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`.
 - Local skill file hints if installed: `.gemini/skills/code-review/SKILL.md`, `.gemini/skills/system-design/SKILL.md`, `.gemini/skills/unit-testing/SKILL.md`, `.gemini/skills/typescript-best-practices/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`, `.gemini/skills/python-best-practices/SKILL.md`, `.gemini/skills/golang-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/release.toml

@@ -4,7 +4,7 @@ Follow the /release workflow from .gemini/workflows/release.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `ci-cd-pipeline`, `git-workflow`, `tech-doc`, `observability`, `kubernetes-deploy`, `typescript-best-practices`, `javascript-best-practices`.
 - Local skill file hints if installed: `.gemini/skills/ci-cd-pipeline/SKILL.md`, `.gemini/skills/git-workflow/SKILL.md`, `.gemini/skills/tech-doc/SKILL.md`, `.gemini/skills/observability/SKILL.md`, `.gemini/skills/kubernetes-deploy/SKILL.md`, `.gemini/skills/typescript-best-practices/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/review.toml

@@ -4,7 +4,7 @@ Follow the /review workflow from .gemini/workflows/review.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `code-review`, `unit-testing`, `owasp-security-review`, `performance-testing`, `react`, `nextjs`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`.
 - Local skill file hints if installed: `.gemini/skills/code-review/SKILL.md`, `.gemini/skills/unit-testing/SKILL.md`, `.gemini/skills/owasp-security-review/SKILL.md`, `.gemini/skills/performance-testing/SKILL.md`, `.gemini/skills/react/SKILL.md`, `.gemini/skills/nextjs/SKILL.md`, `.gemini/skills/typescript-best-practices/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/security.toml

@@ -4,7 +4,7 @@ Follow the /security workflow from .gemini/workflows/security.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `owasp-security-review`, `code-review`, `api-design`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`, `rust-best-practices`.
 - Local skill file hints if installed: `.gemini/skills/owasp-security-review/SKILL.md`, `.gemini/skills/code-review/SKILL.md`, `.gemini/skills/api-design/SKILL.md`, `.gemini/skills/typescript-best-practices/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`, `.gemini/skills/python-best-practices/SKILL.md`, `.gemini/skills/golang-best-practices/SKILL.md`, `.gemini/skills/rust-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/spec.toml

@@ -4,7 +4,7 @@ Follow the /spec workflow from .gemini/workflows/spec.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `spec-driven-delivery`, `sadd`, `system-design`, `architecture-doc`, `deep-research`, `api-design`, `database-design`, `tech-doc`.
 - Local skill file hints if installed: `.gemini/skills/spec-driven-delivery/SKILL.md`, `.gemini/skills/sadd/SKILL.md`, `.gemini/skills/system-design/SKILL.md`, `.gemini/skills/architecture-doc/SKILL.md`, `.gemini/skills/deep-research/SKILL.md`, `.gemini/skills/api-design/SKILL.md`, `.gemini/skills/database-design/SKILL.md`, `.gemini/skills/tech-doc/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/test.toml

@@ -4,7 +4,7 @@ Follow the /test workflow from .gemini/workflows/test.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `unit-testing`, `integration-testing`, `playwright-interactive`, `observability`, `systematic-debugging`, `code-review`, `typescript-best-practices`, `javascript-best-practices`, `python-best-practices`, `golang-best-practices`, `java-best-practices`.
 - Local skill file hints if installed: `.gemini/skills/unit-testing/SKILL.md`, `.gemini/skills/integration-testing/SKILL.md`, `.gemini/skills/playwright-interactive/SKILL.md`, `.gemini/skills/observability/SKILL.md`, `.gemini/skills/systematic-debugging/SKILL.md`, `.gemini/skills/code-review/SKILL.md`, `.gemini/skills/typescript-best-practices/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`.

package/workflows/workflows/agent-environment-setup/platforms/gemini/commands/vercel.toml

@@ -4,7 +4,7 @@ Follow the /vercel workflow from .gemini/workflows/vercel.md.
 
 Execution contract:
 1. Treat route selection as already resolved by this command; do not begin with skill discovery.
-2. Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before non-trivial execution.
+2. Read `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before non-trivial execution.
 Attached skills:
 - Load these exact skill IDs first: `nextjs`, `ci-cd-pipeline`, `performance-testing`, `react`, `frontend-design`, `javascript-best-practices`, `typescript-best-practices`.
 - Local skill file hints if installed: `.gemini/skills/nextjs/SKILL.md`, `.gemini/skills/ci-cd-pipeline/SKILL.md`, `.gemini/skills/performance-testing/SKILL.md`, `.gemini/skills/react/SKILL.md`, `.gemini/skills/frontend-design/SKILL.md`, `.gemini/skills/javascript-best-practices/SKILL.md`, `.gemini/skills/typescript-best-practices/SKILL.md`.

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

@@ -1,6 +1,6 @@
 ---
 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."
+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",
@@ -18,7 +18,7 @@ triggers:
 
 ## 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.
+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
 
@@ -35,24 +35,25 @@ Use this when the task is to declare, refresh, or validate the project architect
 
 ## 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.
+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`.
-- `ENGINEERING_RULES.md` is normative. `TECH.md` is descriptive. Keep them aligned but not redundant.
+- `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 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.
+- 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
@@ -64,9 +65,13 @@ ARCHITECTURE_WORKFLOW_RESULT:
   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
-  files_updated: [ENGINEERING_RULES.md, 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>]

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

@@ -38,12 +38,12 @@ Use this for non-trivial work that needs durable planning in Git before implemen
 1. Determine whether the task is non-trivial enough to justify a spec pack.
 2. Find an existing `docs/specs/<spec-id>/` pack or create a new stable `spec_id`.
 3. Write or refresh the spec pack with brief, acceptance, tasks, traceability, and handoff files.
-4. Record `architecture_impact`, `doc_impact`, and any required updates to `ENGINEERING_RULES.md` or `TECH.md`.
+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 `ENGINEERING_RULES.md` first and `TECH.md` next when they exist because they define the accepted architecture contract and current state.
+- 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.
 

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

@@ -37,7 +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 `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before planning or implementing.
+> **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.
 
 ---
 
@@ -97,7 +97,7 @@ 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 project structure, boundaries, design system, or testing strategy, surface `doc_impact` and recommend `/architecture` or a managed-doc refresh before or after implementation.
+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.
 
 ---
 
@@ -195,7 +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 project structure, scaling assumptions, or design-system rules, update or flag `ENGINEERING_RULES.md` and `TECH.md`.
+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.
 
 ---