@anhth2/spec-driven-dev-plugin 0.5.0

package/core/modules/php-laravel/stack-profile.yaml

@@ -0,0 +1,56 @@
+build:
+  compile: "composer install"
+  test: "php artisan test"
+  run: "php artisan serve"
+  migrate: "php artisan migrate"
+  seed: "php artisan db:seed"
+
+architecture:
+  style: "Service-Repository (Controller → Service → Repository → Model)"
+  key_rules:
+    - "Controllers must not contain business logic — delegate to Services"
+    - "Services own business logic and transaction boundaries"
+    - "Repositories abstract all Eloquent/DB queries"
+    - "Form Requests handle all input validation (never validate in controller)"
+    - "API Resources transform Model output (never return raw Model/array)"
+    - "Use dependency injection via constructor, not Facades in classes"
+
+coding_standards:
+  naming:
+    controllers: "PascalCase + Controller suffix — Resource style (e.g., OrderController)"
+    services: "PascalCase + Service suffix (e.g., OrderService)"
+    repositories:
+      interface: "PascalCase + RepositoryInterface (e.g., OrderRepositoryInterface)"
+      impl: "PascalCase + Repository (e.g., EloquentOrderRepository)"
+    models: "PascalCase singular (e.g., Order)"
+    form_requests: "PascalCase + Request suffix (e.g., CreateOrderRequest)"
+    resources: "PascalCase + Resource suffix (e.g., OrderResource)"
+    files:
+      controller: "app/Http/Controllers/{Domain}/{Name}Controller.php"
+      service: "app/Services/{Domain}/{Name}Service.php"
+      repository_interface: "app/Repositories/{Name}RepositoryInterface.php"
+      repository_impl: "app/Repositories/Eloquent/{Name}Repository.php"
+      model: "app/Models/{Name}.php"
+      form_request: "app/Http/Requests/{Domain}/{Action}{Name}Request.php"
+      resource: "app/Http/Resources/{Domain}/{Name}Resource.php"
+  patterns:
+    response_wrapper: "JsonResponse with status/data/message structure"
+    pagination: "Laravel paginate() — returns LengthAwarePaginator"
+    exception_base: "App\\Exceptions\\BusinessException"
+    transactions: "DB::transaction(fn () => ...) in Service layer"
+    events: "Laravel Events + Listeners for domain events"
+
+testing:
+  unit: "PHPUnit or Pest"
+  feature: "Laravel Feature Tests (HTTP layer with database)"
+  patterns:
+    - "Use RefreshDatabase or DatabaseTransactions trait"
+    - "Fake external services with Http::fake() or mock()"
+    - "Use actingAs(\$user) for auth context"
+    - "Assert JSON structure with assertJson() / assertJsonStructure()"
+
+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|feature"

package/core/modules/react/architecture-snippets/hooks-query-patterns.md

@@ -0,0 +1,254 @@
+# React — Hooks, React Query & Zustand Patterns
+
+## React Query — Query Hook
+
+```typescript
+// features/order/queries/order.queries.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { orderApi } from '@/api/order.api';
+import type { CreateOrderPayload, Order } from '../types';
+
+// Query key factory — single source of truth for cache invalidation
+export const orderKeys = {
+  all: ['ORDERS'] as const,
+  lists: () => [...orderKeys.all, 'list'] as const,
+  list: (customerId: number) => [...orderKeys.lists(), { customerId }] as const,
+  detail: (id: number) => [...orderKeys.all, 'detail', id] as const,
+};
+
+// @trace.implements=ORD-UC1-SC1
+// @trace.source=specs/bdd/order/ORD-UC1.feature
+export function useOrderList(customerId: number) {
+  return useQuery({
+    queryKey: orderKeys.list(customerId),
+    queryFn: () => orderApi.getByCustomer(customerId),
+    staleTime: 30_000,
+  });
+}
+
+// @trace.implements=ORD-UC2-SC1
+// @trace.source=specs/bdd/order/ORD-UC2.feature
+export function useCreateOrder() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (payload: CreateOrderPayload) => orderApi.create(payload),
+    onSuccess: (_, variables) => {
+      // Invalidate order list for this customer
+      queryClient.invalidateQueries({ queryKey: orderKeys.list(variables.customerId) });
+    },
+  });
+}
+```
+
+## API Client (Axios)
+
+```typescript
+// api/order.api.ts
+import { apiClient } from '@/api/client';
+import type { CreateOrderPayload, Order, PaginatedResponse } from '@/features/order/types';
+
+export const orderApi = {
+  getByCustomer: (customerId: number) =>
+    apiClient.get<PaginatedResponse<Order>>('/v1/orders', { params: { customerId } })
+      .then(res => res.data),
+
+  getById: (id: number) =>
+    apiClient.get<Order>(`/v1/orders/${id}`).then(res => res.data),
+
+  create: (payload: CreateOrderPayload) =>
+    apiClient.post<Order>('/v1/orders', payload).then(res => res.data),
+
+  cancel: (id: number) =>
+    apiClient.patch<void>(`/v1/orders/${id}/cancel`).then(res => res.data),
+};
+```
+
+```typescript
+// api/client.ts — Axios instance with auth interceptor
+import axios from 'axios';
+
+export const apiClient = axios.create({
+  baseURL: import.meta.env.VITE_API_URL,
+  headers: { 'Content-Type': 'application/json' },
+});
+
+apiClient.interceptors.request.use(config => {
+  const token = localStorage.getItem('access_token');
+  if (token) config.headers.Authorization = `Bearer ${token}`;
+  return config;
+});
+
+apiClient.interceptors.response.use(
+  res => res,
+  error => {
+    if (error.response?.status === 401) {
+      // redirect to login
+      window.location.href = '/login';
+    }
+    return Promise.reject(error);
+  }
+);
+```
+
+## Zustand Store (Client State)
+
+```typescript
+// features/cart/store/cart.store.ts
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+import type { CartItem } from '../types';
+
+interface CartStore {
+  items: CartItem[];
+  addItem: (item: CartItem) => void;
+  removeItem: (productId: number) => void;
+  clearCart: () => void;
+  total: () => number;
+}
+
+export const useCartStore = create<CartStore>()(
+  persist(
+    (set, get) => ({
+      items: [],
+
+      addItem: (item) =>
+        set(state => {
+          const existing = state.items.find(i => i.productId === item.productId);
+          if (existing) {
+            return {
+              items: state.items.map(i =>
+                i.productId === item.productId
+                  ? { ...i, quantity: i.quantity + item.quantity }
+                  : i
+              ),
+            };
+          }
+          return { items: [...state.items, item] };
+        }),
+
+      removeItem: (productId) =>
+        set(state => ({ items: state.items.filter(i => i.productId !== productId) })),
+
+      clearCart: () => set({ items: [] }),
+
+      total: () => get().items.reduce((sum, i) => sum + i.price * i.quantity, 0),
+    }),
+    { name: 'cart-storage' }
+  )
+);
+```
+
+## Feature Component (Container)
+
+```tsx
+// features/order/components/OrderListPage.tsx
+// @trace.implements=ORD-UC1-SC1
+// @trace.source=specs/bdd/order/ORD-UC1.feature
+import { useAuth } from '@/hooks/useAuth';
+import { useOrderList } from '../queries/order.queries';
+import { OrderCard } from './OrderCard';
+
+export function OrderListPage() {
+  const { user } = useAuth();
+  const { data: orders, isLoading, isError } = useOrderList(user.id);
+
+  if (isLoading) return <div>Loading...</div>;
+  if (isError)   return <div>Failed to load orders.</div>;
+
+  return (
+    <div className="order-list">
+      {orders?.map(order => (
+        <OrderCard key={order.id} order={order} />
+      ))}
+      {orders?.length === 0 && <p>No orders yet.</p>}
+    </div>
+  );
+}
+```
+
+## React Hook Form + Zod
+
+```tsx
+// features/order/components/CreateOrderForm.tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { useCreateOrder } from '../queries/order.queries';
+
+const createOrderSchema = z.object({
+  customerId: z.number().positive(),
+  items: z.array(z.object({
+    productId: z.number().positive(),
+    quantity: z.number().int().min(1),
+  })).min(1, 'At least one item required'),
+});
+
+type CreateOrderForm = z.infer<typeof createOrderSchema>;
+
+export function CreateOrderForm({ customerId }: { customerId: number }) {
+  const { mutate: createOrder, isPending } = useCreateOrder();
+
+  const { register, handleSubmit, formState: { errors } } = useForm<CreateOrderForm>({
+    resolver: zodResolver(createOrderSchema),
+    defaultValues: { customerId, items: [] },
+  });
+
+  const onSubmit = (data: CreateOrderForm) => createOrder(data);
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      {/* form fields */}
+      {errors.items && <p className="error">{errors.items.message}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create Order'}
+      </button>
+    </form>
+  );
+}
+```
+
+## Test with React Testing Library + MSW
+
+```tsx
+// features/order/__tests__/OrderListPage.test.tsx
+// @trace.verifies=ORD-UC1
+// @trace.test_type=integration
+import { render, screen, waitFor } from '@testing-library/react';
+import { http, HttpResponse } from 'msw';
+import { server } from '@/test/server';
+import { renderWithProviders } from '@/test/utils';
+import { OrderListPage } from '../components/OrderListPage';
+
+describe('OrderListPage', () => {
+  it('displays orders after successful fetch', async () => {
+    server.use(
+      http.get('/v1/orders', () =>
+        HttpResponse.json([
+          { id: 1, status: 'pending', customerId: 42, items: [] },
+        ])
+      )
+    );
+
+    renderWithProviders(<OrderListPage />, { user: { id: 42 } });
+
+    expect(screen.getByText('Loading...')).toBeInTheDocument();
+
+    await waitFor(() =>
+      expect(screen.queryByText('Loading...')).not.toBeInTheDocument()
+    );
+
+    expect(screen.getByText('Order #1')).toBeInTheDocument();
+  });
+
+  it('shows empty state when no orders exist', async () => {
+    server.use(http.get('/v1/orders', () => HttpResponse.json([])));
+
+    renderWithProviders(<OrderListPage />, { user: { id: 42 } });
+
+    await waitFor(() =>
+      expect(screen.getByText('No orders yet.')).toBeInTheDocument()
+    );
+  });
+});
+```

package/core/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/core/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/bdd/{domain}/{UC-ID}.feature"
+  verifies: "// @trace.verifies={UC-ID}"
+  test_type: "// @trace.test_type=unit|integration"

package/core/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/core/rules/workflow.md

@@ -0,0 +1,44 @@
+# Workflow Rules
+
+> General AI behavior rules for all spec-driven-dev 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".