@anhth2/spec-driven-dev-plugin 0.9.1 → 0.9.2

package/modules/flutter/stack-profile.yaml

@@ -0,0 +1,59 @@
+build:
+  compile: "flutter build apk / flutter build ios"
+  test: "flutter test"
+  run: "flutter run"
+  lint: "flutter analyze"
+
+architecture:
+  style: "Feature-based (presentation → domain → data)"
+  key_rules:
+    - "Widget tree is pure UI — business logic lives in BLoC/Cubit or Riverpod providers"
+    - "Repositories abstract data sources; services contain domain logic"
+    - "State management: BLoC (complex flows) or Riverpod (simple/medium)"
+    - "Never call API directly inside a Widget build() method"
+    - "Shared UI widgets in lib/shared/widgets/, feature widgets in lib/features/{name}/presentation/"
+    - "Use const constructors wherever possible for performance"
+  folder_structure: |
+    lib/
+    ├── core/
+    │   ├── theme/        ← AppTheme, colors, text styles
+    │   ├── router/       ← GoRouter or auto_route
+    │   └── utils/
+    ├── shared/
+    │   └── widgets/      ← reusable UI widgets (AppButton, AppInput...)
+    ├── features/
+    │   └── {domain}/
+    │       ├── data/         ← repositories, data sources, models
+    │       ├── domain/       ← entities, use cases, repo interfaces
+    │       └── presentation/ ← pages, widgets, BLoC/Cubit
+    └── main.dart
+
+coding_standards:
+  naming:
+    widgets: "PascalCase (e.g., OrderListPage, CreateOrderForm)"
+    blocs: "PascalCase + Bloc/Cubit suffix (e.g., OrderListCubit)"
+    repositories: "PascalCase + Repository suffix (e.g., OrderRepository)"
+    files:
+      page: "{feature}_page.dart"
+      widget: "{feature}_widget.dart"
+      cubit: "{feature}_cubit.dart"
+      repository: "{feature}_repository.dart"
+      model: "{feature}_model.dart"
+  patterns:
+    state_management: "BLoC / Cubit (flutter_bloc) or Riverpod"
+    navigation: "GoRouter or auto_route"
+    networking: "Dio with interceptors"
+    serialization: "json_serializable / freezed"
+
+testing:
+  unit: "flutter_test + mocktail"
+  widget: "flutter_test WidgetTester"
+  integration: "integration_test package"
+  patterns:
+    - "Test BLoC/Cubit in isolation with fake repositories"
+    - "Widget tests pump the widget tree and find by key or semantics label"
+    - "Use goldenFileComparator for snapshot tests of complex widgets"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/bdd/{domain}/{UC-ID}.feature"

package/modules/ios-swiftui/module.yaml

@@ -0,0 +1,13 @@
+name: "iOS (SwiftUI)"
+version: "1.0.0"
+description: "Native iOS development with SwiftUI + Swift"
+language: "Swift"
+framework: "SwiftUI"
+stack_type: "mobile"
+default_layer_order:
+  - Models / entities
+  - Repository (data sources)
+  - UseCase (business operations)
+  - ViewModel (ObservableObject state)
+  - View (SwiftUI presentation)
+test_framework: "XCTest + Quick/Nimble"

package/modules/ios-swiftui/stack-profile.yaml

@@ -0,0 +1,55 @@
+build:
+  compile: "xcodebuild -scheme {AppName} -configuration Release"
+  test: "xcodebuild test -scheme {AppName}"
+  run: "Open in Xcode → Run (⌘R)"
+  lint: "swiftlint"
+
+architecture:
+  style: "MVVM + Clean Architecture (View → ViewModel → UseCase → Repository)"
+  key_rules:
+    - "Views are pure SwiftUI — no business logic, no direct API calls"
+    - "ViewModels are ObservableObject classes; bind via @StateObject / @ObservedObject"
+    - "UseCases encapsulate single business operations"
+    - "Repositories abstract data sources (network, cache, local DB)"
+    - "Dependency injection via environment or constructor injection"
+    - "Use Combine or async/await for async flows — never DispatchQueue in ViewModel"
+  folder_structure: |
+    Sources/
+    ├── Core/
+    │   ├── Network/      ← URLSession wrapper, interceptors
+    │   ├── Theme/        ← Color, Font, Spacing tokens
+    │   └── Utils/
+    ├── Shared/
+    │   └── Components/   ← reusable SwiftUI views (AppButton, AppTextField...)
+    ├── Features/
+    │   └── {Domain}/
+    │       ├── Views/
+    │       ├── ViewModels/
+    │       ├── UseCases/
+    │       └── Repository/
+
+coding_standards:
+  naming:
+    views: "PascalCase + View suffix (e.g., OrderListView, CreateOrderView)"
+    viewmodels: "PascalCase + ViewModel suffix (e.g., OrderListViewModel)"
+    usecases: "PascalCase + UseCase suffix (e.g., CreateOrderUseCase)"
+    files:
+      view: "{Feature}View.swift"
+      viewmodel: "{Feature}ViewModel.swift"
+      usecase: "{Feature}UseCase.swift"
+  patterns:
+    async: "async/await + Combine"
+    navigation: "NavigationStack (iOS 16+)"
+    persistence: "Core Data or SwiftData"
+    networking: "URLSession or Alamofire"
+
+testing:
+  unit: "XCTest + Quick/Nimble"
+  ui: "XCUITest"
+  patterns:
+    - "Test ViewModel by injecting mock repositories"
+    - "UI tests use accessibility identifiers — set .accessibilityIdentifier on Views"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/bdd/{domain}/{UC-ID}.feature"

package/modules/nuxt/module.yaml

@@ -0,0 +1,14 @@
+name: "Nuxt"
+version: "1.0.0"
+description: "Nuxt 3 with SSR/SSG, Composition API, Pinia, and useFetch"
+language: "TypeScript"
+framework: "Nuxt 3"
+stack_type: "frontend"
+default_layer_order:
+  - Types / interfaces
+  - Server API routes (server/api/)
+  - Composables (useFetch / useAsyncData)
+  - State store (Pinia)
+  - UI components (presentational)
+  - Page components (pages/)
+test_framework: "Vitest + Vue Test Utils + @nuxt/test-utils"

package/modules/nuxt/stack-profile.yaml

@@ -0,0 +1,58 @@
+build:
+  compile: "npm run build"
+  test: "npm run test"
+  run: "npm run dev"
+  lint: "npm run lint"
+
+architecture:
+  style: "Pages + Composables + Server routes (SSR/SSG)"
+  key_rules:
+    - "Pages in pages/ are route-level containers — no business logic"
+    - "Business logic in composables/ using useAsyncData or useFetch"
+    - "Server-side logic in server/api/ routes (nitro)"
+    - "Client-only state in Pinia stores; server state via useAsyncData"
+    - "Shared UI primitives in components/ui/, auto-imported by Nuxt"
+    - "Use useRoute/useRouter instead of $route/$router in Composition API"
+    - "'use client' equivalent: wrap client-only code in onMounted or <ClientOnly>"
+  folder_structure: |
+    ├── components/
+    │   └── ui/           ← auto-imported UI primitives (BaseButton, BaseInput...)
+    ├── composables/      ← auto-imported composables (useOrderList...)
+    ├── pages/            ← file-based routing
+    ├── server/
+    │   └── api/          ← nitro server routes (GET /api/orders.ts)
+    ├── stores/           ← Pinia stores (auto-imported)
+    ├── plugins/          ← Nuxt plugins
+    └── utils/            ← auto-imported utilities
+
+coding_standards:
+  naming:
+    components: "PascalCase (auto-imported, e.g., OrderList, BaseButton)"
+    composables: "camelCase with 'use' prefix (auto-imported, e.g., useOrderList)"
+    stores: "camelCase + Store suffix via defineStore()"
+    server_routes: "method.path.ts (e.g., get.orders.ts or [id].get.ts)"
+    files:
+      component: "{Feature}.vue"
+      composable: "use{Feature}.ts"
+      store: "{feature}.store.ts"
+      server_route: "{resource}.get.ts / {resource}.post.ts"
+  patterns:
+    data_fetching: "useAsyncData() for SSR data, useFetch() for client fetches"
+    global_state: "Pinia stores"
+    forms: "VeeValidate + Zod"
+    api_client: "$fetch (ofetch) — built-in to Nuxt, SSR-compatible"
+    ssr_hydration: "useState() for shared SSR/client state to avoid hydration mismatch"
+
+testing:
+  unit: "Vitest + @nuxt/test-utils"
+  e2e: "Playwright via @nuxt/test-utils/e2e"
+  patterns:
+    - "Use mountSuspended() for components that need Nuxt context"
+    - "Use registerEndpoint() to mock server routes in tests"
+    - "Test pages with renderSuspended() from @nuxt/test-utils"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/bdd/{domain}/{UC-ID}.feature"
+  verifies: "// @trace.verifies={UC-ID}"
+  test_type: "// @trace.test_type=unit|integration"

package/modules/react-native/module.yaml

@@ -0,0 +1,14 @@
+name: "React Native"
+version: "1.0.0"
+description: "Cross-platform mobile (iOS + Android) with React Native / Expo"
+language: "TypeScript"
+framework: "React Native"
+stack_type: "mobile"
+default_layer_order:
+  - Types / interfaces
+  - API client (React Query hooks)
+  - State store (Zustand)
+  - Custom hooks (business logic)
+  - UI components (presentational)
+  - Screen / feature components (container)
+test_framework: "Jest + React Native Testing Library"

package/modules/react-native/stack-profile.yaml

@@ -0,0 +1,56 @@
+build:
+  compile: "npx expo export / npx react-native build-android"
+  test: "jest"
+  run: "npx expo start / npx react-native run-ios"
+  lint: "eslint . && tsc --noEmit"
+
+architecture:
+  style: "Feature-based (screens → hooks → queries → store)"
+  key_rules:
+    - "Business logic lives in custom hooks, not in screen components"
+    - "Server state managed by React Query (TanStack Query)"
+    - "Navigation state managed by React Navigation"
+    - "Native modules wrapped in a service layer — never called directly in components"
+    - "Shared UI primitives in src/components/ui/, feature screens in src/features/{name}/"
+  folder_structure: |
+    src/
+    ├── api/              ← axios instance, interceptors
+    ├── components/
+    │   └── ui/           ← reusable primitives (AppButton, AppInput...)
+    ├── features/
+    │   └── {domain}/
+    │       ├── components/
+    │       ├── hooks/
+    │       ├── queries/
+    │       └── screens/
+    ├── navigation/       ← React Navigation stacks/tabs
+    ├── store/            ← Zustand slices
+    └── lib/              ← utils, formatters, constants
+
+coding_standards:
+  naming:
+    components: "PascalCase (e.g., OrderListScreen, CreateOrderForm)"
+    hooks: "camelCase with 'use' prefix (e.g., useOrderList)"
+    screens: "PascalCase + Screen suffix (e.g., OrderDetailScreen)"
+    files:
+      screen: "{Feature}Screen.tsx"
+      component: "{Feature}.tsx"
+      hook: "use{Feature}.ts"
+  patterns:
+    state_management: "Zustand + React Query"
+    navigation: "React Navigation v6 (Stack + Tab + Drawer)"
+    networking: "Axios"
+    forms: "React Hook Form + Zod"
+    storage: "MMKV or AsyncStorage"
+
+testing:
+  unit: "Jest + React Native Testing Library"
+  e2e: "Detox or Maestro"
+  patterns:
+    - "Test by accessibility label or testID — never by style/className"
+    - "Mock native modules in jest setup"
+    - "Use renderWithProviders() with NavigationContainer + QueryClient"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/bdd/{domain}/{UC-ID}.feature"

package/modules/vue/module.yaml

@@ -0,0 +1,14 @@
+name: "Vue"
+version: "1.0.0"
+description: "Vue 3 SPA with Composition API, Pinia, and Vue Query"
+language: "TypeScript"
+framework: "Vue 3"
+stack_type: "frontend"
+default_layer_order:
+  - Types / interfaces
+  - API client (Vue Query / composables)
+  - State store (Pinia)
+  - Composables (business logic)
+  - UI components (presentational)
+  - Page / feature components (container)
+test_framework: "Vitest + Vue Test Utils"

package/modules/vue/stack-profile.yaml

@@ -0,0 +1,65 @@
+build:
+  compile: "npm run build"
+  test: "npm run test"
+  run: "npm run dev"
+  lint: "npm run lint"
+
+architecture:
+  style: "Feature-based (components → composables → queries → store)"
+  key_rules:
+    - "Business logic lives in composables, not in component setup()"
+    - "Server state managed by Vue Query (@tanstack/vue-query)"
+    - "Client-only UI state managed by Pinia stores"
+    - "Components must be pure — no direct API calls inside <template> or setup()"
+    - "Shared UI primitives in components/ui/, feature logic in features/{name}/"
+    - "Never fetch data directly in a component — use a composable"
+    - "Props defined with defineProps<{}>(), emits with defineEmits<{}>()"
+  folder_structure: |
+    src/
+    ├── api/              ← axios instance, interceptors
+    ├── components/
+    │   └── ui/           ← reusable primitives (BaseButton, BaseInput...)
+    ├── features/
+    │   └── {domain}/
+    │       ├── components/   ← feature-specific UI
+    │       ├── composables/  ← useOrderList, useCreateOrder...
+    │       ├── queries/      ← Vue Query definitions
+    │       ├── store/        ← Pinia slice (if needed)
+    │       └── types.ts
+    ├── pages/            ← route-level page components (Vue Router)
+    ├── router/           ← route definitions
+    └── lib/              ← utilities, formatters, constants
+
+coding_standards:
+  naming:
+    components: "PascalCase (e.g., OrderList, CreateOrderModal)"
+    composables: "camelCase with 'use' prefix (e.g., useOrderList, useCreateOrder)"
+    stores: "camelCase + Store suffix (e.g., useCartStore) — defined with defineStore()"
+    query_keys: "SCREAMING_SNAKE_CASE string/array (e.g., ['ORDER_LIST', customerId])"
+    files:
+      component: "{Feature}.vue"
+      composable: "use{Feature}.ts"
+      query: "{feature}.queries.ts"
+      store: "{feature}.store.ts"
+      types: "{feature}.types.ts"
+  patterns:
+    data_fetching: "Vue Query (TanStack Query v5 for Vue)"
+    global_state: "Pinia stores"
+    forms: "VeeValidate + Zod"
+    api_client: "Axios with interceptors for auth + error handling"
+    reactivity: "ref() for primitives, reactive() for objects, computed() for derived state"
+
+testing:
+  unit: "Vitest + Vue Test Utils"
+  e2e: "Playwright or Cypress"
+  patterns:
+    - "Test behavior, not implementation — query by role/label via @testing-library/vue"
+    - "Mock Vue Query with VueQueryPlugin wrapper in test setup"
+    - "Use MSW (Mock Service Worker) to mock API calls in tests"
+    - "mountWithProviders() helper wraps component with Pinia + VueQuery + Router"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/bdd/{domain}/{UC-ID}.feature"
+  verifies: "// @trace.verifies={UC-ID}"
+  test_type: "// @trace.test_type=unit|integration"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anhth2/spec-driven-dev-plugin",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "AI-First Spec-Driven Development workflow plugin for Claude Code",
   "bin": {
     "spec-driven-dev": "./bin/index.js"

package/skills/code/SKILL.md

@@ -202,13 +202,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/skills/debug/SKILL.md

@@ -117,13 +117,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/skills/design-spec/SKILL.md

@@ -191,13 +191,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/skills/discovery/SKILL.md

@@ -96,13 +96,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/skills/test/SKILL.md

@@ -374,13 +374,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 
@@ -777,13 +778,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/steps/context-loader.md

@@ -86,13 +86,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/templates/product-definition.template.md

@@ -72,9 +72,9 @@
 - {Function 2}
 
 ### User Story
-As a {User role}
-I want to {User goal}
-So that {Business value}
+- **As a** {User role}
+- **I want to** {User goal}
+- **So that** {Business value}
 
 ---
 

package/templates/project-context.yaml

@@ -50,7 +50,9 @@ paths:
   # .agent/project-context.yaml to ".agent/project-lessons.md" (resolved per service_root).
   lessons_file: "specs/domain-knowledge/lessons-learned.md"
 
-  # Tech Docs
+  # Tech Docs (BE-authored API contract).
+  # In umbrella mode with spec_source set, context-loader auto-routes this to
+  # {spec_source}/specs/tech-docs so FE/App read the contract via the spec submodule.
   tech_docs_dir: "tech-docs"
 
   # Design Specs (FE/App platforms only — web, app)
@@ -94,6 +96,7 @@ domains:
 # When spec_source is set, context-loader auto-derives:
 #   prd_dir              → {spec_source}/specs/prd
 #   design_spec_dir      → {spec_source}/specs/design-spec
+#   tech_docs_dir        → {spec_source}/specs/tech-docs   # shared API contract (per-service tech_docs_dir below wins in multi-service)
 #   domain_knowledge_dir → {spec_source}/specs/domain-knowledge
 # (You can still override these manually in paths: section below.)
 #