@synapta/skills 0.1.1 → 0.2.0

package/skills/concept-discovery/expected_outputs/sample-page-user-list.md

@@ -0,0 +1,83 @@
+# User List
+
+> **Route:** `/users`
+> **Module:** User Management
+> **Generated:** 2026-03-17
+
+## Overview
+
+Displays all system users in a searchable, paginated table. Supports creating, editing, and deleting users. Only ADMIN and MANAGER roles can access this page.
+
+## Layout
+
+- **Top bar**: Search input + "Create User" button
+- **Main area**: Data table with pagination
+- **Modal**: Create/Edit user form (triggered by buttons)
+
+## Fields
+
+### Search Filters
+
+| Field | Type | Required | Options | Default | Notes |
+|-------|------|----------|---------|---------|-------|
+| Keyword | Text input | No | — | — | Searches name and email |
+| Role | Select dropdown | No | Admin, Manager, User | All | Filters by role |
+| Status | Select dropdown | No | Active, Inactive, Suspended | All | Filters by status |
+
+### Data Table
+
+| Column | Format | Sortable | Filterable | Notes |
+|--------|--------|----------|-----------|-------|
+| Name | Text | Yes | No | Full name |
+| Email | Text (link) | Yes | No | Clickable → opens detail |
+| Role | Badge | No | Yes | Color-coded by role |
+| Status | Badge | No | Yes | Green=active, Red=suspended |
+| Created | Date (YYYY-MM-DD) | Yes | No | — |
+| Actions | Buttons | No | No | Edit, Delete |
+
+### Actions
+
+| Button | Visibility | Behavior |
+|--------|-----------|----------|
+| Create User | ADMIN, MANAGER | Opens create modal |
+| Edit | ADMIN, MANAGER | Opens edit modal with prefilled data |
+| Delete | ADMIN only | Confirmation dialog → soft delete |
+
+## Interactions
+
+### Page Load
+- Fetches first page of users via `GET /api/users?page=1&size=20`
+- Default sort: `created_at` descending
+
+### Search
+- **Trigger:** User types in search field (300ms debounce)
+- **Behavior:** Re-fetches users with `keyword` param, resets to page 1
+- **Special rules:** Minimum 2 characters to trigger search
+
+### Create User
+- **Trigger:** Click "Create User" button
+- **Modal content:** Name (required, max 50), Email (required, email format), Role (required, select), Status (default: Active)
+- **Validation:** Name required + max length, Email required + format check
+- **API:** `POST /api/users` with form data
+- **On success:** Toast "User created", close modal, refresh list
+- **On failure:** Show API error below form
+
+### Delete User
+- **Trigger:** Click "Delete" button on row
+- **Behavior:** Confirmation dialog "Are you sure you want to delete {name}?"
+- **API:** `DELETE /api/users/:id`
+- **On success:** Toast "User deleted", refresh list
+
+## API Dependencies
+
+| API | Method | Path | Trigger | Notes |
+|-----|--------|------|---------|-------|
+| List users | GET | /api/users | Load, search, paginate | Params: page, size, keyword, role, status |
+| Create user | POST | /api/users | Submit create form | Body: name, email, role |
+| Delete user | DELETE | /api/users/:id | Confirm delete | — |
+
+## Page Relationships
+
+- **From:** Dashboard (click "View Users" link)
+- **To:** User Detail (click email or row)
+- **Data coupling:** Creating/deleting a user triggers dashboard stats refresh

package/skills/concept-discovery/expected_outputs/sample-prd-readme.md

@@ -0,0 +1,43 @@
+# My App — Product Requirements Document
+
+## System Overview
+
+My App is a user management platform for internal teams. It provides CRUD operations for users, a dashboard with key metrics, and system settings. Built with Next.js 14 (App Router) and Tailwind CSS.
+
+## Module Overview
+
+| Module | Pages | Core Functionality |
+|--------|-------|--------------------|
+| Dashboard | Dashboard | Key metrics, activity feed |
+| User Management | User list, User detail | CRUD users, role assignment |
+| Settings | Settings | System configuration |
+
+## Page Inventory
+
+| # | Page Name | Route | Module | Doc Link |
+|---|-----------|-------|--------|----------|
+| 1 | Home | / | — | [→](./pages/01-home.md) |
+| 2 | Dashboard | /dashboard | Dashboard | [→](./pages/02-dashboard.md) |
+| 3 | User List | /users | User Mgmt | [→](./pages/03-user-list.md) |
+| 4 | User Detail | /users/:id | User Mgmt | [→](./pages/04-user-detail.md) |
+| 5 | Settings | /settings | Settings | [→](./pages/05-settings.md) |
+
+## API Inventory
+
+| # | Method | Path | Status | Notes |
+|---|--------|------|--------|-------|
+| 1 | GET | /api/users | Integrated | Paginated list |
+| 2 | POST | /api/users | Integrated | Create user |
+| 3 | GET | /api/users/:id | Integrated | User detail |
+| 4 | PUT | /api/users/:id | Integrated | Update user |
+| 5 | GET | /api/dashboard/stats | Mock | Dashboard metrics |
+
+## Global Notes
+
+### Permission Model
+Role-based access: ADMIN (full access), MANAGER (read + edit), USER (read-only).
+
+### Common Interaction Patterns
+- All delete operations require confirmation modal
+- Lists default to `created_at` descending, 20 items per page
+- Form validation shows inline errors below each field

package/skills/concept-discovery/references/framework-patterns.md

@@ -0,0 +1,228 @@
+# Framework-Specific Patterns
+
+Quick reference for identifying routes, components, state, and APIs across frontend and backend frameworks.
+
+## React (CRA / Vite)
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `react-router-dom` — `<Route path="...">` or `createBrowserRouter` |
+| Components | `.tsx` / `.jsx` files, default exports |
+| State | Redux (`store/`), Zustand, Jotai, Recoil, React Context |
+| API | `axios`, `fetch`, TanStack Query (`useQuery`), SWR (`useSWR`) |
+| Forms | React Hook Form, Formik, Ant Design Form, custom `useState` |
+| i18n | `react-i18next`, `react-intl` |
+
+## Next.js (App Router)
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `app/` directory — `page.tsx` = route, folders = segments |
+| Layouts | `layout.tsx` per directory |
+| Loading | `loading.tsx`, `error.tsx`, `not-found.tsx` |
+| API routes | `app/api/` or `pages/api/` (Pages Router) |
+| Server actions | `"use server"` directive |
+| Middleware | `middleware.ts` at root |
+
+## Next.js (Pages Router)
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `pages/` directory — filename = route |
+| Data fetching | `getServerSideProps`, `getStaticProps`, `getStaticPaths` |
+| API routes | `pages/api/` |
+
+## Vue 3
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `vue-router` — `routes` array in `router/index.ts` |
+| Components | `.vue` SFCs (`<template>`, `<script setup>`, `<style>`) |
+| State | Pinia (`stores/`), Vuex (`store/`) |
+| API | `axios`, `fetch`, VueQuery |
+| Forms | VeeValidate, FormKit, custom `ref()` / `reactive()` |
+| i18n | `vue-i18n` |
+
+## Nuxt 3
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `pages/` directory (file-system routing) |
+| Layouts | `layouts/` |
+| API routes | `server/api/` |
+| Data fetching | `useFetch`, `useAsyncData`, `$fetch` |
+| State | `useState`, Pinia |
+| Middleware | `middleware/` |
+
+## Angular
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `app-routing.module.ts` or `Routes` array |
+| Components | `@Component` decorator, `*.component.ts` |
+| State | NgRx (`store/`), services with `BehaviorSubject` |
+| API | `HttpClient` in services |
+| Forms | Reactive Forms (`FormGroup`), Template-driven forms |
+| i18n | `@angular/localize`, `ngx-translate` |
+| Guards | `CanActivate`, `CanDeactivate` |
+
+## Svelte / SvelteKit
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `src/routes/` (file-system routing with `+page.svelte`) |
+| Layouts | `+layout.svelte` |
+| Data loading | `+page.ts` / `+page.server.ts` (`load` function) |
+| API routes | `+server.ts` |
+| State | Svelte stores (`writable`, `readable`, `derived`) |
+
+## NestJS
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `@Controller('prefix')` + `@Get()/@Post()/@Put()/@Delete()` decorators |
+| Modules | `*.module.ts` — `@Module({ controllers, providers, imports })` |
+| Services | `*.service.ts` — injected via constructor, contains business logic |
+| DTOs | `*.dto.ts` — `class-validator` decorators define validation rules |
+| Entities | `*.entity.ts` — TypeORM `@Entity()` / Prisma schemas |
+| Auth | `@UseGuards(AuthGuard)`, `@Roles('admin')`, Passport strategies |
+| Middleware | `*.middleware.ts`, registered in module `configure()` |
+| Pipes | `ValidationPipe`, `ParseIntPipe` — input transformation |
+| Config | `ConfigModule`, `.env` files, `config/` directory |
+
+## Express / Fastify
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `router.get('/path', handler)`, `app.post('/path', ...)` |
+| Middleware | `app.use(...)`, `router.use(...)` |
+| Controllers | Route handler files in `routes/`, `controllers/` |
+| Models | Mongoose schemas (`*.model.ts`), Sequelize models, Prisma |
+| Auth | `passport`, `jsonwebtoken`, middleware auth checks |
+| Validation | `express-validator`, `joi`, `zod`, custom middleware |
+
+## Django
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `urls.py` — `urlpatterns = [path('...', view)]` |
+| Views | `views.py` — function-based or class-based views (`APIView`, `ViewSet`) |
+| Models | `models.py` — `class MyModel(models.Model)` with field definitions |
+| Forms | `forms.py` — `ModelForm`, `Form` with validation |
+| Serializers | `serializers.py` (DRF) — `ModelSerializer`, field-level validation |
+| Admin | `admin.py` — `@admin.register`, `list_display`, `search_fields`, `list_filter` |
+| Templates | `templates/` — Jinja2/Django template HTML files |
+| Middleware | `MIDDLEWARE` in `settings.py` |
+| Auth | `django.contrib.auth`, `rest_framework.permissions`, `@login_required` |
+| Signals | `signals.py` — `post_save`, `pre_delete` hooks (hidden business logic) |
+| Management commands | `management/commands/` — CLI operations |
+| Celery tasks | `tasks.py` — async/background operations |
+
+## Django REST Framework (DRF)
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Endpoints | `router.register('prefix', ViewSet)` in `urls.py` |
+| ViewSets | `viewsets.py` — `ModelViewSet` (full CRUD), `ReadOnlyModelViewSet` |
+| Serializers | `serializers.py` — field types, validators, nested relations |
+| Permissions | `permission_classes = [IsAuthenticated, IsAdminUser]` |
+| Filtering | `django-filter`, `search_fields`, `ordering_fields` |
+| Pagination | `DEFAULT_PAGINATION_CLASS` in settings, per-view override |
+| Throttling | `DEFAULT_THROTTLE_CLASSES`, per-view `throttle_classes` |
+
+## FastAPI
+
+| Aspect | Where to Look |
+|--------|--------------|
+| Routes | `@app.get('/path')`, `@router.post('/path')` decorators |
+| Models | Pydantic `BaseModel` classes — request/response schemas |
+| Dependencies | `Depends(...)` — auth, DB sessions, shared logic |
+| DB | SQLAlchemy models, Tortoise ORM, or raw SQL |
+| Auth | `OAuth2PasswordBearer`, JWT middleware, `Depends(get_current_user)` |
+| Background | `BackgroundTasks`, Celery integration |
+
+## Common Patterns Across Frameworks
+
+### Mock Detection
+```
+# Likely mock
+setTimeout(() => resolve(data), 500)
+Promise.resolve(mockData)
+import { data } from './fixtures'
+faker.name.firstName()
+
+# Likely real
+axios.get('/api/users')
+fetch('/api/data')
+httpClient.post(url, body)
+useSWR('/api/resource')
+```
+
+### Permission Patterns
+```
+# React
+{hasPermission('admin') && <Button>Delete</Button>}
+<ProtectedRoute roles={['admin', 'manager']}>
+
+# Vue
+v-if="user.role === 'admin'"
+v-permission="'user:delete'"
+
+# Angular
+*ngIf="authService.hasRole('admin')"
+canActivate: [AuthGuard]
+```
+
+### Form Validation
+```
+# React Hook Form
+{ required: 'Name is required', maxLength: { value: 50, message: 'Too long' } }
+
+# VeeValidate (Vue)
+rules="required|email|max:100"
+
+# Angular Reactive Forms
+Validators.required, Validators.minLength(3), Validators.pattern(...)
+
+# NestJS (class-validator)
+@IsString() @IsNotEmpty() @MaxLength(50) name: string;
+@IsEmail() email: string;
+@IsEnum(UserRole) role: UserRole;
+
+# Django Forms
+name = forms.CharField(max_length=50, required=True)
+email = forms.EmailField()
+
+# DRF Serializers
+name = serializers.CharField(max_length=50)
+email = serializers.EmailField(required=True)
+
+# FastAPI (Pydantic)
+name: str = Field(max_length=50)
+email: EmailStr
+```
+
+### Database Model Patterns
+```
+# Django
+class Order(models.Model):
+    status = models.CharField(max_length=20, choices=STATUS_CHOICES)
+    user = models.ForeignKey(User, on_delete=models.CASCADE)
+    total = models.DecimalField(max_digits=10, decimal_places=2)
+
+# TypeORM (NestJS)
+@Entity()
+export class Order {
+    @Column({ type: 'enum', enum: OrderStatus })
+    status: OrderStatus;
+    @ManyToOne(() => User)
+    user: User;
+}
+
+# Prisma
+model Order {
+    status  OrderStatus
+    user    User @relation(fields: [userId], references: [id])
+    total   Decimal
+}
+```

package/skills/concept-discovery/references/prd-quality-checklist.md

@@ -0,0 +1,65 @@
+# PRD Quality Checklist
+
+Use this checklist to validate generated PRDs before delivery.
+
+## Completeness
+
+- [ ] Every route/page has a corresponding document
+- [ ] All form fields listed with type, required, validation, default
+- [ ] All table columns listed with format, sortable, filterable
+- [ ] All action buttons documented with visibility conditions
+- [ ] All API endpoints listed with method, path, trigger, params
+- [ ] Mock vs integrated APIs clearly distinguished
+- [ ] All enums exhaustively listed with every value
+- [ ] Page load behavior documented for every page
+- [ ] Page relationships mapped (inbound, outbound, data coupling)
+
+## Accuracy
+
+- [ ] Route paths match actual code
+- [ ] Field names match UI labels (not variable names)
+- [ ] Validation rules match actual code logic
+- [ ] Permission conditions match auth guard implementations
+- [ ] API paths match actual service layer calls
+- [ ] Enum values match source constants (no fabrication)
+- [ ] Uncertain items marked `[TBC]` with explanation
+
+## Readability
+
+- [ ] Business language used (not implementation details)
+- [ ] Each page doc is self-contained
+- [ ] No component names used as page names
+- [ ] Interactions described as user action → system response
+- [ ] Modals/drawers documented within their parent page
+- [ ] README system overview written for non-technical reader
+
+## Structure
+
+- [ ] `prd/README.md` exists with system overview + page inventory
+- [ ] `prd/pages/` contains numbered page files
+- [ ] `prd/appendix/enum-dictionary.md` exists
+- [ ] `prd/appendix/api-inventory.md` exists
+- [ ] `prd/appendix/page-relationships.md` exists
+- [ ] Cross-references use relative links
+
+## Backend-Specific Checks
+
+- [ ] All controller/view endpoints documented with method, path, auth
+- [ ] DTO/serializer fields listed with type, required, validation
+- [ ] Database model relationships mapped (FK, M2M, O2O)
+- [ ] Django admin customizations documented (list_display, actions, inlines)
+- [ ] Background tasks/Celery jobs documented with trigger and schedule
+- [ ] Middleware pipeline documented (auth, logging, rate limiting)
+- [ ] Environment-dependent behavior noted (dev vs prod differences)
+- [ ] Database migrations reviewed for field constraints and defaults
+
+## Common Issues to Watch
+
+| Issue | How to Detect | Fix |
+|-------|--------------|-----|
+| Missing modal content | Search for `Modal`, `Dialog`, `Drawer` components | Add as subsection in parent page |
+| Undocumented field linking | Search for conditional renders based on field values | Add to interaction logic |
+| Hidden permissions | Search for `v-if`, `v-show`, role checks, auth guards | Add visibility conditions |
+| Stale mock data | Compare mock shapes with API types/interfaces | Flag as `[Mock - verify with backend]` |
+| Missing error states | Search for error boundaries, catch blocks, toast errors | Add failure paths to interactions |
+| Unlinked pages | Cross-reference route params with navigation calls | Complete page relationships |