@codihaus/claude-skills 1.0.0 → 1.2.0

package/skills/dev-scout/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-scout
 description: Explore and document existing codebases at various depths
-version: 2.7.0
+version: 2.8.0
 ---
 
 # /dev-scout - Codebase Explorer
@@ -40,6 +40,7 @@ plans/
 │   ├── README.md                # Current summary
 │   ├── structure.md             # File tree, tech stack
 │   ├── features.md              # Existing features
+│   ├── stack.md                 # HOW the project works (API, data, patterns)
 │   └── history/                 # Previous snapshots
 │       └── {date}.md
 │
@@ -49,6 +50,12 @@ plans/
         └── ...
 ```
 
+**stack.md is critical** - it tells `/dev-specs` HOW to write specs that fit the project:
+- Use the right SDK (not raw fetch)
+- Follow existing patterns (composables, hooks, services)
+- Respect data access method (BaaS vs direct DB)
+- Use correct validation/form libraries
+
 ## Modes
 
 | Mode | What It Does | When to Use |
@@ -389,7 +396,177 @@ Document:
 - PR/commit requirements
 ```
 
-### Step 5: Generate Output
+### Step 5: Stack Analysis (CRITICAL)
+
+Generate `stack.md` - tells downstream skills HOW to work with this project.
+
+See `references/stack-patterns.md` for detection patterns.
+
+#### 5.1 Detect API Layer Type
+
+```
+Check for BaaS first (higher priority):
+1. .env vars: DIRECTUS_URL, STRAPI_URL, SUPABASE_URL, etc.
+2. package.json: @directus/sdk, @supabase/supabase-js, etc.
+
+If no BaaS:
+3. Check for API framework: express, fastify, hono
+4. Check for GraphQL: @apollo/client, urql, graphql
+5. Check for tRPC: @trpc/server
+```
+
+#### 5.2 Detect Data Access Pattern
+
+```
+If BaaS detected:
+- Data managed by BaaS (don't suggest raw SQL)
+- Note which collections/content types exist
+
+If no BaaS:
+- Check for ORM: prisma/, drizzle.config.*
+- Check schema files for models
+- Direct DB access pattern
+```
+
+#### 5.3 Detect API Client Pattern
+
+```
+Search for how the project calls APIs:
+
+React projects:
+- hooks/use*.ts → Custom hooks pattern
+- services/*.ts → Service layer pattern
+- @tanstack/react-query → React Query pattern
+
+Vue projects:
+- composables/use*.ts → Composables pattern
+- stores/*.ts → Pinia stores
+- @tanstack/vue-query → Vue Query pattern
+
+Next.js:
+- actions/*.ts → Server Actions
+- app/api/** → API Routes
+- Server components with direct calls
+
+Identify the PRIMARY pattern used (not all).
+```
+
+#### 5.4 Detect Validation & Forms
+
+```
+Validation:
+- zod in package.json → Zod schemas
+- yup → Yup schemas
+- Find: schemas/, validators/, *.schema.ts
+
+Forms:
+- react-hook-form → useForm pattern
+- vee-validate → VeeValidate
+- formik → Formik pattern
+```
+
+#### 5.5 Detect External Services
+
+```
+Parse .env.example or .env:
+- STRIPE_* → Payment (Stripe)
+- RESEND_* → Email (Resend)
+- AWS_S3_* → Storage (S3)
+- SENTRY_* → Monitoring (Sentry)
+
+Match with package.json to confirm SDK.
+```
+
+#### 5.6 Detect Local Services
+
+```
+Parse docker-compose.yml or compose.yml:
+- postgres → PostgreSQL
+- redis → Redis
+- minio → S3-compatible storage
+- directus → Directus CMS
+```
+
+#### 5.7 Detect Available MCPs
+
+```
+Check .claude/settings.local.json or mcp.json:
+- context7 → Library docs lookup
+- playwright → Browser automation
+- shadcn → UI components
+- Custom MCPs → Project-specific tools
+```
+
+#### 5.8 Generate stack.md
+
+Output `plans/scout/stack.md`:
+
+```markdown
+# Project Stack
+
+> Auto-detected by /dev-scout. Verify and update as needed.
+
+## API Layer
+| Aspect | Value |
+|--------|-------|
+| Type | {REST/GraphQL/tRPC/BaaS} |
+| Service | {Directus/Supabase/Custom/etc.} |
+| SDK | {package name if applicable} |
+
+## Data Access
+| Aspect | Value |
+|--------|-------|
+| Method | {BaaS-managed/ORM/Direct SQL} |
+| ORM | {Prisma/Drizzle/none} |
+| Models | {list key models} |
+
+## API Client Pattern
+| Aspect | Value |
+|--------|-------|
+| Pattern | {hooks/composables/services/direct} |
+| Location | {folder path} |
+| Example | {primary function used} |
+
+## Validation & Forms
+| Aspect | Value |
+|--------|-------|
+| Validation | {Zod/Yup/none} |
+| Schemas | {folder path} |
+| Forms | {react-hook-form/vee-validate/native} |
+
+## External Services
+| Service | Provider | Env Var |
+|---------|----------|---------|
+| {type} | {provider} | {var} |
+
+## Local Services (docker-compose)
+| Service | Purpose | Port |
+|---------|---------|------|
+| {name} | {purpose} | {port} |
+
+## Available MCPs
+| MCP | Capability |
+|-----|------------|
+| {name} | {what it provides} |
+
+## Specs Guidelines
+
+Based on this stack, implementation should:
+1. {guideline based on API layer}
+2. {guideline based on data access}
+3. {guideline based on patterns}
+4. {guideline based on validation}
+
+## Stack Knowledge References
+
+For best practices and patterns, downstream skills should read:
+{list only those that apply to this project}
+- `knowledge/stacks/directus/_index.md` - Directus SDK patterns, queries, auth
+- `knowledge/stacks/nuxt/_index.md` - Nuxt composables, SSR, server routes
+- `knowledge/stacks/nextjs/_index.md` - Server Components, Actions, App Router
+```
+
+### Step 6: Generate Output
 
 #### Project-Level Output
 
@@ -721,3 +898,4 @@ Quick codebase analysis with optional tool installation:
 - `references/file-patterns.md` - Search patterns
 - `references/feature-patterns.md` - Feature inference
 - `references/tech-detection.md` - Tech stack detection
+- `references/stack-patterns.md` - Deep stack analysis (API, data, patterns)

package/skills/dev-scout/references/stack-patterns.md

@@ -0,0 +1,371 @@
+# Stack Patterns Detection
+
+Detect HOW the project works, not just what frameworks are used.
+
+## BaaS / Headless CMS
+
+Projects using Backend-as-a-Service or Headless CMS have different patterns than custom backends.
+
+### Detection
+
+| Evidence | Service | SDK |
+|----------|---------|-----|
+| `DIRECTUS_URL` in .env | Directus | `@directus/sdk` |
+| `STRAPI_URL` in .env | Strapi | `@strapi/strapi` |
+| `SANITY_PROJECT_ID` in .env | Sanity | `@sanity/client` |
+| `CONTENTFUL_SPACE_ID` in .env | Contentful | `contentful` |
+| `SUPABASE_URL` in .env | Supabase | `@supabase/supabase-js` |
+| `FIREBASE_*` in .env | Firebase | `firebase` |
+| `APPWRITE_*` in .env | Appwrite | `appwrite` |
+| `POCKETBASE_URL` in .env | PocketBase | `pocketbase` |
+| `PAYLOAD_*` in .env | Payload CMS | `payload` |
+
+### Implications
+
+When BaaS detected:
+- **Don't suggest**: Custom REST endpoints, direct DB queries
+- **Do suggest**: Use SDK methods, follow BaaS patterns
+- **Data model**: Managed by BaaS (collections, content types)
+- **Auth**: Usually provider-managed
+
+## API Layer Type
+
+### REST (Custom)
+
+**Detection**:
+- `/api/**` routes with HTTP method handlers
+- `express`, `fastify`, `hono` in dependencies
+- `routes/`, `controllers/` folders
+
+**Pattern**: Custom endpoints, direct DB access
+
+### REST (BaaS)
+
+**Detection**:
+- BaaS SDK in dependencies
+- No `/api/` routes (or minimal proxy routes)
+- Env vars for BaaS URL
+
+**Pattern**: SDK calls, managed endpoints
+
+### GraphQL
+
+**Detection**:
+- `graphql`, `@apollo/client`, `urql` in dependencies
+- `.graphql` files, `gql` template literals
+- `/api/graphql` endpoint
+
+**Pattern**: Queries, mutations, fragments
+
+### tRPC
+
+**Detection**:
+- `@trpc/server`, `@trpc/client` in dependencies
+- `trpc/` folder with routers
+- Type-safe procedure calls
+
+**Pattern**: Procedures, type inference
+
+## Data Access Patterns
+
+### Direct Database
+
+**Detection**:
+- ORM/Query builder (Prisma, Drizzle, Knex)
+- `prisma/schema.prisma`, `drizzle/` folder
+- Direct SQL files
+
+**Implications**:
+- Can modify schema
+- Write migrations
+- Direct queries
+
+### Managed by BaaS
+
+**Detection**:
+- BaaS SDK, no ORM
+- No `prisma/`, no migrations
+- Content types managed in BaaS admin
+
+**Implications**:
+- Don't create tables, use BaaS admin
+- Query via SDK
+- Schema changes via BaaS dashboard
+
+### Hybrid
+
+**Detection**:
+- BaaS for content + local DB for app data
+- Multiple data sources
+
+**Implications**:
+- Identify which data goes where
+- Document boundary
+
+## API Client Patterns
+
+Where and how the project calls APIs.
+
+### React Patterns
+
+| Pattern | Location | Example |
+|---------|----------|---------|
+| Custom hooks | `hooks/use*.ts` | `useUsers()`, `useApi()` |
+| React Query | `hooks/` + `@tanstack/react-query` | `useQuery()` wrapper |
+| SWR | `hooks/` + `swr` | `useSWR()` wrapper |
+| Services | `services/*.ts` | `userService.getAll()` |
+| Direct fetch | In components | `fetch('/api/...')` |
+
+### Vue Patterns
+
+| Pattern | Location | Example |
+|---------|----------|---------|
+| Composables | `composables/use*.ts` | `useDirectus()`, `useApi()` |
+| Pinia stores | `stores/*.ts` | `useUserStore()` |
+| Services | `services/*.ts` | `userService.getAll()` |
+| Vue Query | `composables/` + `@tanstack/vue-query` | `useQuery()` |
+
+### Next.js Patterns
+
+| Pattern | Location | Example |
+|---------|----------|---------|
+| Server Actions | `actions/*.ts` or inline | `'use server'` functions |
+| API Routes | `app/api/**` | Route handlers |
+| Server Components | `app/**/page.tsx` | Direct DB/API calls |
+| Client hooks | `hooks/` | Client-side fetching |
+
+### Nuxt Patterns
+
+| Pattern | Location | Example |
+|---------|----------|---------|
+| Composables | `composables/use*.ts` | Auto-imported |
+| useFetch | In components | Built-in `useFetch()` |
+| useAsyncData | In components | SSR data fetching |
+| Server routes | `server/api/**` | Nitro API routes |
+
+### Detection Strategy
+
+1. Check for hooks/composables folder
+2. Search for `use` prefix functions
+3. Check for services folder
+4. Look at import patterns in components
+5. Identify the PRIMARY pattern (not all)
+
+## Validation Libraries
+
+| Dependency | Library | Usage |
+|------------|---------|-------|
+| `zod` | Zod | Schema-first, TypeScript inference |
+| `yup` | Yup | Schema builder, common with Formik |
+| `joi` | Joi | Enterprise, detailed validation |
+| `valibot` | Valibot | Lightweight Zod alternative |
+| `@sinclair/typebox` | TypeBox | JSON Schema compatible |
+
+**Pattern detection**:
+```
+Search for:
+- schemas/, validators/ folders
+- *.schema.ts, *.validator.ts files
+- z.object, yup.object, Joi.object imports
+```
+
+## Form Handling
+
+| Dependency | Library | Framework |
+|------------|---------|-----------|
+| `react-hook-form` | React Hook Form | React |
+| `formik` | Formik | React |
+| `vee-validate` | VeeValidate | Vue |
+| `@tanstack/react-form` | TanStack Form | React |
+| `formsnap` | Formsnap | Svelte |
+
+**Pattern detection**:
+```
+Search for:
+- useForm, useFormik imports
+- <Form>, <Field> components
+- form/, forms/ folders
+```
+
+## External Services
+
+### Payment
+
+| Env Var | Service | SDK |
+|---------|---------|-----|
+| `STRIPE_*` | Stripe | `stripe`, `@stripe/stripe-js` |
+| `PAYPAL_*` | PayPal | `@paypal/checkout-server-sdk` |
+| `LEMON_SQUEEZY_*` | Lemon Squeezy | `@lemonsqueezy/lemonsqueezy.js` |
+| `PADDLE_*` | Paddle | `@paddle/paddle-js` |
+
+### Email
+
+| Env Var | Service | SDK |
+|---------|---------|-----|
+| `RESEND_*` | Resend | `resend` |
+| `SENDGRID_*` | SendGrid | `@sendgrid/mail` |
+| `POSTMARK_*` | Postmark | `postmark` |
+| `MAILGUN_*` | Mailgun | `mailgun.js` |
+| `AWS_SES_*` | AWS SES | `@aws-sdk/client-ses` |
+
+### Storage
+
+| Env Var | Service | SDK |
+|---------|---------|-----|
+| `AWS_S3_*`, `S3_*` | AWS S3 | `@aws-sdk/client-s3` |
+| `CLOUDFLARE_R2_*` | Cloudflare R2 | `@aws-sdk/client-s3` (S3 compatible) |
+| `UPLOADTHING_*` | UploadThing | `uploadthing` |
+| `CLOUDINARY_*` | Cloudinary | `cloudinary` |
+
+### Search
+
+| Env Var | Service | SDK |
+|---------|---------|-----|
+| `ALGOLIA_*` | Algolia | `algoliasearch` |
+| `MEILISEARCH_*` | Meilisearch | `meilisearch` |
+| `TYPESENSE_*` | Typesense | `typesense` |
+
+### Analytics
+
+| Env Var | Service |
+|---------|---------|
+| `NEXT_PUBLIC_GA_*`, `GA_*` | Google Analytics |
+| `NEXT_PUBLIC_POSTHOG_*` | PostHog |
+| `MIXPANEL_*` | Mixpanel |
+| `SEGMENT_*` | Segment |
+
+### Monitoring
+
+| Env Var | Service |
+|---------|---------|
+| `SENTRY_*` | Sentry |
+| `DATADOG_*` | Datadog |
+| `LOGROCKET_*` | LogRocket |
+
+## Docker Compose Services
+
+Parse `docker-compose.yml` or `compose.yml`:
+
+| Service Image | Purpose |
+|---------------|---------|
+| `postgres:*` | PostgreSQL database |
+| `mysql:*` | MySQL database |
+| `mongo:*` | MongoDB |
+| `redis:*` | Redis cache/queue |
+| `minio:*` | S3-compatible storage |
+| `mailhog:*`, `mailpit:*` | Local email testing |
+| `directus:*` | Directus CMS |
+| `strapi:*` | Strapi CMS |
+
+## MCP Tools Detection
+
+Check `.claude/settings.local.json` or `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "context7": { ... },
+    "playwright": { ... },
+    "shadcn": { ... }
+  }
+}
+```
+
+**Available MCPs provide capabilities:**
+
+| MCP | Capability |
+|-----|------------|
+| `context7` | Library documentation lookup |
+| `playwright` | Browser automation, screenshots |
+| `shadcn` | UI component source code |
+| Custom MCPs | Project-specific tools |
+
+## Output: stack.md
+
+```markdown
+# Project Stack
+
+> Auto-detected by /dev-scout. Verify and update as needed.
+
+## API Layer
+
+| Aspect | Value |
+|--------|-------|
+| Type | BaaS (Directus) |
+| SDK | @directus/sdk |
+| Pattern | composables/useDirectus.ts |
+
+## Data Access
+
+| Aspect | Value |
+|--------|-------|
+| Access | Managed by Directus |
+| Collections | users, posts, media |
+| Direct DB | No (use SDK) |
+
+## Auth
+
+| Aspect | Value |
+|--------|-------|
+| Provider | Directus Auth |
+| Pattern | middleware/auth.ts |
+| Storage | Directus handles sessions |
+
+## API Client
+
+| Aspect | Value |
+|--------|-------|
+| Pattern | Vue composables |
+| Location | composables/use*.ts |
+| Primary | useDirectus(), useApi() |
+
+## Validation & Forms
+
+| Aspect | Value |
+|--------|-------|
+| Validation | Zod (shared/schemas/) |
+| Forms | VeeValidate |
+
+## External Services
+
+| Service | Provider | Env Var |
+|---------|----------|---------|
+| Email | Resend | RESEND_API_KEY |
+| Storage | S3 via Directus | (managed) |
+| Payment | Stripe | STRIPE_SECRET_KEY |
+
+## Local Development
+
+| Service | Purpose | Port |
+|---------|---------|------|
+| postgres | Database | 5432 |
+| redis | Cache | 6379 |
+| directus | CMS | 8055 |
+
+## Available MCPs
+
+| MCP | Use For |
+|-----|---------|
+| context7 | Library docs |
+| playwright | UI testing |
+
+## Specs Guidelines
+
+Based on this stack, specs should:
+
+1. **API calls**: Use `useDirectus()` composable, not fetch
+2. **Data**: Use Directus collections, not raw SQL
+3. **Auth**: Use Directus auth middleware
+4. **Validation**: Add Zod schemas to shared/schemas/
+5. **Forms**: Use VeeValidate with Zod resolver
+6. **New features**: Follow composables pattern
+```
+
+## Detection Priority
+
+1. **Environment variables** - Most reliable for services
+2. **package.json** - SDKs and libraries
+3. **Config files** - Framework/tool configs
+4. **Code patterns** - How things are actually used
+5. **Docker compose** - Local services
+6. **MCP config** - Available tools

package/skills/dev-specs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-specs
 description: Generate implementation specifications from BRD use cases
-version: 1.4.0
+version: 1.5.0
 ---
 
 # /dev-specs - Implementation Specifications
@@ -11,6 +11,7 @@ version: 1.4.0
 > - **Auto**: Runs `/dev-scout` if scout.md missing
 > - **During**: Calls `/dev-arch` for patterns and architecture decisions
 > - **Reads**: `_quality-attributes.md` (Specification Level)
+> - **Critical**: Reads `stack.md` to use correct SDK, patterns, validation
 > - **After**: Use `/dev-coding` for implementation
 
 Generate precise implementation plans from BRD use cases. Creates per-UC specs with shared components.
@@ -186,6 +187,71 @@ Call `/dev-arch` for patterns to use:
 
 Specs will use these patterns for consistency.
 
+### Phase 0.7: Read Stack Configuration (CRITICAL)
+
+Read `plans/scout/stack.md` to understand HOW to implement:
+
+```
+1. Check: plans/scout/stack.md exists?
+   → No: Warn "Run /dev-scout for better specs"
+
+2. Extract key information:
+   → API Layer: BaaS, REST, GraphQL, tRPC
+   → SDK to use: @directus/sdk, @supabase/supabase-js, etc.
+   → Data access: BaaS-managed, ORM, direct SQL
+   → API client pattern: hooks, composables, services
+   → Validation: Zod, Yup, native
+   → Forms: react-hook-form, vee-validate
+   → External services: What's already configured
+
+3. Load stack knowledge files (IMPORTANT):
+   → Check "Stack Knowledge References" section in stack.md
+   → Read each referenced knowledge/stacks/*.md file
+   → Use "For /dev-specs" sections for patterns
+
+   Examples:
+   - Directus project → Read knowledge/stacks/directus/_index.md
+   - Nuxt project → Read knowledge/stacks/nuxt/_index.md
+   - Next.js project → Read knowledge/stacks/nextjs/_index.md
+
+4. Use this to write specs that FIT the project
+```
+
+**Why this matters:**
+
+| Without stack.md | With stack.md |
+|------------------|---------------|
+| "Create REST endpoint" | "Use Directus collection via SDK" |
+| "Create fetch wrapper" | "Use existing `useApi()` composable" |
+| "Add validation" | "Add Zod schema to shared/schemas/" |
+| "Handle auth" | "Use Directus auth middleware" |
+
+**Stack-aware spec generation:**
+
+| Stack Aspect | Spec Impact |
+|--------------|-------------|
+| BaaS (Directus) | Don't create tables, use collections |
+| Composables pattern | New features use composables, not services |
+| Zod validation | Schema in shared/schemas/*.ts |
+| Server Actions (Next.js) | Use 'use server' not API routes |
+| React Query | Wrap in useQuery, not raw fetch |
+
+**Example: spec for "Add user profile"**
+
+Without stack.md:
+```markdown
+1. Create POST /api/users/profile endpoint
+2. Add Prisma User model
+3. Create ProfileForm with useState
+```
+
+With stack.md (Directus + Vue composables):
+```markdown
+1. Add profile fields to Directus users collection (via admin)
+2. Create useUserProfile composable using useDirectus()
+3. Create ProfileForm using VeeValidate + Zod schema
+```
+
 ### Phase 1: Gather Context
 
 1. **Read BRD use cases** for the feature
@@ -560,10 +626,16 @@ When writing specs, use Context7 to verify API patterns:
 | Skill | Relationship |
 |-------|--------------|
 | `/debrief` | Provides use cases (input) |
-| `/dev-scout` | Provides codebase context (input) |
+| `/dev-scout` | Provides codebase context + stack.md (input) |
 | `/dev-arch` | Provides architecture patterns (input) |
 | `/utils/diagram` | Validates mermaid in specs |
 
+**Key dependency**: `stack.md` from `/dev-scout` tells specs HOW to implement:
+- Which SDK to use (not raw fetch)
+- Which patterns to follow (hooks vs services vs composables)
+- Which validation library (Zod vs Yup)
+- Whether to use BaaS or direct DB
+
 ## Tips
 
 - Run `/dev-scout {feature}` first for better context