@edupia-tutor/spec-driven-docs 0.14.0

package/modules/react/module.yaml

@@ -0,0 +1,14 @@
+name: "React"
+version: "1.0.0"
+description: "React 18 SPA with hooks, React Query, and Zustand"
+language: "TypeScript"
+framework: "React"
+stack_type: "frontend"
+default_layer_order:
+  - Types / interfaces
+  - API client (React Query hooks)
+  - State store (Zustand)
+  - Custom hooks (business logic)
+  - UI components (presentational)
+  - Page / feature components (container)
+test_framework: "Vitest + React Testing Library"

package/modules/react/stack-profile.yaml

@@ -0,0 +1,63 @@
+build:
+  compile: "npm run build"
+  test: "npm test"
+  run: "npm run dev"
+  lint: "npm run lint"
+
+architecture:
+  style: "Feature-based (components → hooks → queries → store)"
+  key_rules:
+    - "Business logic lives in custom hooks, not in components"
+    - "Server state managed by React Query (useQuery / useMutation)"
+    - "Client-only UI state managed by Zustand or useState"
+    - "Components must be pure functions — no direct API calls inside JSX"
+    - "Shared UI primitives in components/ui/, feature logic in features/{name}/"
+    - "Never fetch data directly in a component — use a custom hook"
+  folder_structure: |
+    src/
+    ├── api/              ← axios instance, interceptors
+    ├── components/
+    │   └── ui/           ← reusable primitives (Button, Modal, Table...)
+    ├── features/
+    │   └── {domain}/
+    │       ├── components/   ← feature-specific UI
+    │       ├── hooks/        ← useOrderList, useCreateOrder...
+    │       ├── queries/      ← React Query definitions
+    │       ├── store/        ← Zustand slice (if needed)
+    │       └── types.ts
+    ├── pages/            ← route-level page components
+    └── lib/              ← utilities, formatters, constants
+
+coding_standards:
+  naming:
+    components: "PascalCase (e.g., OrderList, CreateOrderModal)"
+    hooks: "camelCase with 'use' prefix (e.g., useOrderList, useCreateOrder)"
+    query_keys: "SCREAMING_SNAKE_CASE array (e.g., ['ORDER_LIST', customerId])"
+    stores: "camelCase + Store suffix (e.g., useCartStore)"
+    files:
+      component: "{Feature}.tsx"
+      hook: "use{Feature}.ts"
+      query: "{feature}.queries.ts"
+      store: "{feature}.store.ts"
+      types: "{feature}.types.ts"
+  patterns:
+    data_fetching: "React Query (TanStack Query v5)"
+    global_state: "Zustand slices"
+    forms: "React Hook Form + Zod validation"
+    api_client: "Axios with interceptors for auth + error handling"
+    error_boundary: "React ErrorBoundary wraps each feature route"
+
+testing:
+  unit: "Vitest + React Testing Library"
+  e2e: "Playwright or Cypress"
+  patterns:
+    - "Test behavior, not implementation — query by role/label, not className"
+    - "Mock React Query with a QueryClient wrapper in test setup"
+    - "Use MSW (Mock Service Worker) to mock API calls in tests"
+    - "renderWithProviders() helper wraps component with QueryClient + Router"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{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/{domain}/{prd-slug}/bdd/{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/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  verifies: "// @trace.verifies={UC-ID}"
+  test_type: "// @trace.test_type=unit|integration"

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@edupia-tutor/spec-driven-docs",
+  "version": "0.14.0",
+  "description": "AI-First Spec-Driven Development workflow framework for Claude Code",
+  "bin": {
+    "spec-driven-docs": "./bin/index.js"
+  },
+  "scripts": {
+    "build": "node bin/build.js",
+    "prepublishOnly": "node bin/build.js",
+    "pub": "npm publish --access=public",
+    "dev": "node bin/build.js && node bin/index.js --init",
+    "prepack": "node -e \"const fs=require('fs'); ['README.md','PUBLISHING.md','SETUP_GUIDE.md'].forEach(f=>{ if(fs.existsSync(f)) fs.renameSync(f,'__'+f); });\"",
+    "postpack": "node -e \"const fs=require('fs'); ['README.md','PUBLISHING.md','SETUP_GUIDE.md'].forEach(f=>{ if(fs.existsSync('__'+f)) fs.renameSync('__'+f,f); });\""
+  },
+  "files": [
+    "bin/",
+    "commands/",
+    "core/",
+    "hooks/",
+    "modules/",
+    "rules/",
+    "scripts/",
+    "skills/",
+    "steps/",
+    "templates/",
+    "docs/"
+  ],
+  "keywords": [
+    "claude-code",
+    "spec-driven",
+    "ai-first",
+    "bdd",
+    "traceability",
+    "workflow"
+  ],
+  "author": "Edupia Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/edupia-tutor/spec-driven-docs"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/rules/data-protection.md

@@ -0,0 +1,80 @@
+# Data Protection Rules
+
+> These rules are loaded by `steps/context-loader.md` at the start of every command.
+> AI agents MUST follow these rules without exception.
+
+---
+
+## NEVER Read — Sensitive Files
+
+The following file patterns contain credentials, secrets, or private keys.
+**Do NOT read, display, log, or reference their contents under any circumstance.**
+
+### Environment & Secrets
+- `.env`
+- `.env.*` (e.g., `.env.local`, `.env.production`, `.env.staging`)
+- `*.secret`
+- `secrets/` (entire directory)
+- `.secrets/` (entire directory)
+- `*credentials*`
+
+### Cryptographic Keys & Certificates
+- `*.key`
+- `*.pem`
+- `*.p12`
+- `*.pfx`
+- `*.jks`
+- `*.keystore`
+- `*.crt` / `*.cert`
+
+### Framework-Specific Config Files (may contain DB passwords, API keys)
+- `application-prod.yml` / `application-prod.properties`
+- `application-production.yml`
+- `appsettings.Production.json`
+- `appsettings.Staging.json`
+- `database.yml` (Rails)
+- `config/master.key` (Rails)
+- `storage/oauth-private.key`
+
+### Files Matching Dangerous Keywords
+Any file whose name contains (case-insensitive):
+- `password`
+- `passwd`
+- `secret`
+- `private_key`
+- `api_key`
+- `access_token`
+- `auth_token`
+
+---
+
+## NEVER Write or Modify
+
+- Any file listed above
+- `*.lock` files that are not package lock files (e.g., `*.lock` outside of `package-lock.json`, `yarn.lock`, `composer.lock`)
+
+---
+
+## NEVER Execute via Bash
+
+- Commands that print secrets: `printenv`, `env | grep -i secret`, `cat .env`
+- Commands that expose credentials: `docker inspect`, `kubectl get secret -o yaml`
+- Git commands that may expose history of secrets: `git show`, `git log -p` on config files
+
+---
+
+## Safe Alternatives
+
+If context about environment configuration is needed:
+
+1. Ask the user to describe the configuration **without sharing actual values**.
+2. Reference the **structure** of config (keys, not values): "I see you use `DATABASE_URL` — I'll generate code that reads from that variable."
+3. Use placeholder values in generated code: `process.env.DATABASE_URL` or `${DATABASE_URL}`.
+
+---
+
+## If a Sensitive File is Accidentally Accessed
+
+1. Do NOT display or repeat any content from the file.
+2. Immediately stop and notify the user: "I've detected a sensitive file. I will not read or use its contents."
+3. Ask the user what they actually need (usually it's the structure, not the values).

package/rules/workflow.md

@@ -0,0 +1,44 @@
+# Workflow Rules
+
+> General AI behavior rules for all spec-driven-docs commands.
+> Loaded by `steps/context-loader.md` at the start of every command.
+
+---
+
+## Checkpoints
+
+- **Always** show a CHECKPOINT before making significant changes.
+- A CHECKPOINT must include: what will be done, which files will be created/modified, estimated scope.
+- Wait for explicit "Y" or user confirmation before proceeding.
+- Exception: read-only analysis commands (`/review-code`, `/validate-traces`, `/debug`) may skip CHECKPOINT.
+
+## Scope Control
+
+- Work only within the scope explicitly confirmed at CHECKPOINT.
+- Do NOT create files outside the directories specified in `project-context.yaml → paths`.
+- If new scope is discovered mid-command, STOP and ask: "I found additional scope [{description}]. Should I include it? (Y/N)"
+
+## Code Generation
+
+- Never generate code for files not backed by a `.feature` spec (unless `/fix-bug` or `/debug`).
+- Always add `@trace.implements` tags on controller-level methods.
+- Never overwrite existing business logic without explicit confirmation.
+- Build must pass before committing: run `{conventions.build_command}` and fix errors (max 3 retries).
+
+## File Operations
+
+- Prefer **editing** existing files over replacing them entirely.
+- When creating new files, check if a similar file already exists first.
+- Never delete files unless explicitly instructed.
+
+## Communication
+
+- Report in the language the user writes in (Vietnamese if user uses Vietnamese, English otherwise).
+- Keep reports structured: status, artifacts created, next recommended command.
+- If unsure about business intent, ask — do not guess and generate wrong spec.
+
+## Error Handling
+
+- If a tool call fails (file not found, build error, etc.), report the specific error clearly.
+- Do NOT silently skip errors or pretend success.
+- Suggest a concrete fix, not just "please check the error".

package/scripts/init.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# init.sh — First-time setup of Spec-Driven Docs framework in a consumer project.
+#
+# Usage:
+#   bash scripts/init.sh
+#   bash scripts/init.sh --module java-spring
+#   bash scripts/init.sh --module java-spring --hooks
+#
+# What it does:
+#   1. Copies framework files to .agent/ (commands, steps, hooks, rules, templates, modules)
+#   2. Creates lightweight shortcut files in .claude/commands/ that delegate to .agent/
+#   3. Writes .agent/FRAMEWORK_VERSION for upgrade.sh to track installed version
+#
+# After init:
+#   - Commit .agent/ to git so the entire team shares the framework
+#   - Run /setup-ai-first in Claude Code to complete project setup
+#   - To upgrade later: bash scripts/upgrade.sh
+
+set -euo pipefail
+
+echo ""
+echo "╔══════════════════════════════════════════╗"
+echo "║   Spec-Driven Docs — Project Init         ║"
+echo "╚══════════════════════════════════════════╝"
+echo ""
+
+# ── Prerequisite check ────────────────────────────────────────────────────────
+
+if ! command -v node &> /dev/null; then
+  echo "❌ Node.js is required. Install from https://nodejs.org"
+  exit 1
+fi
+
+# ── Run installer via npx ─────────────────────────────────────────────────────
+
+echo "Running: npx @edupia-tutor/spec-driven-docs --init $*"
+echo ""
+
+npx -y @edupia-tutor/spec-driven-docs --init "$@"
+
+echo ""
+echo "✅ Init complete!"
+echo ""
+echo "Recommended next steps:"
+echo "  git add .agent/ .claude/commands/"
+echo "  git commit -m 'chore: init spec-driven-docs framework'"
+echo ""
+echo "Then open Claude Code and run: /setup-ai-first"
+echo ""