specweave 0.1.0

package/src/skills/jira-sync/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: jira-sync
+description: Sync SpecWeave increments with JIRA epics/stories. Activates for JIRA sync, create JIRA issue, import from JIRA, sync to JIRA. Coordinates with specweave-jira-mapper agent.
+allowed-tools: Read, Write, Edit, Task, Bash
+---
+
+# JIRA Sync Skill
+
+Coordinates JIRA synchronization by delegating to `specweave-jira-mapper` agent.
+
+## Responsibilities
+
+1. Detect sync requests (export, import, bidirectional)
+2. Validate prerequisites (JIRA credentials, increment structure)
+3. Invoke `specweave-jira-mapper` agent
+4. Handle errors gracefully
+
+---
+
+## ⚠️ CRITICAL: Secrets Required (MANDATORY CHECK)
+
+**BEFORE attempting JIRA sync, CHECK for JIRA credentials.**
+
+### Step 1: Check If Credentials Exist
+
+```bash
+# Check .env file for both required credentials
+if [ -f .env ] && grep -q "JIRA_API_TOKEN" .env && grep -q "JIRA_EMAIL" .env; then
+  echo "✅ JIRA credentials found"
+else
+  # Credentials NOT found - STOP and prompt user
+fi
+```
+
+### Step 2: If Credentials Missing, STOP and Show This Message
+
+```
+🔐 **JIRA API Token and Email Required**
+
+I need your JIRA API token and email to sync with JIRA.
+
+**How to get it**:
+1. Go to: https://id.atlassian.com/manage-profile/security/api-tokens
+2. Log in with your Atlassian account
+3. Click "Create API token"
+4. Give it a label (e.g., "specweave-sync")
+5. Click "Create"
+6. **Copy the token immediately** (you can't see it again!)
+
+**Where I'll save it**:
+- File: `.env` (gitignored, secure)
+- Format:
+  ```
+  JIRA_API_TOKEN=your-jira-api-token-here
+  JIRA_EMAIL=your-email@example.com
+  JIRA_DOMAIN=your-domain.atlassian.net
+  ```
+
+**Security**:
+✅ .env is in .gitignore (never committed to git)
+✅ Token is random alphanumeric string (variable length)
+✅ Stored locally only (not in source code)
+
+Please provide:
+1. Your JIRA API token:
+2. Your JIRA email:
+3. Your JIRA domain (e.g., company.atlassian.net):
+```
+
+### Step 3: Validate Credentials Format
+
+```bash
+# Validate email format
+if [[ ! "$JIRA_EMAIL" =~ ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ ]]; then
+  echo "⚠️  Warning: Email format unexpected"
+  echo "Expected: valid email address"
+  echo "Got: $JIRA_EMAIL"
+fi
+
+# Validate domain format
+if [[ ! "$JIRA_DOMAIN" =~ \.atlassian\.net$ ]]; then
+  echo "⚠️  Warning: Domain format unexpected"
+  echo "Expected: *.atlassian.net"
+  echo "Got: $JIRA_DOMAIN"
+  echo "Note: Self-hosted JIRA may have different domain format"
+fi
+
+# Token validation (just check it's not empty)
+if [ -z "$JIRA_API_TOKEN" ]; then
+  echo "❌ Error: JIRA API token is empty"
+  exit 1
+fi
+```
+
+### Step 4: Save Credentials Securely
+
+```bash
+# Save to .env
+cat >> .env << EOF
+JIRA_API_TOKEN=$JIRA_API_TOKEN
+JIRA_EMAIL=$JIRA_EMAIL
+JIRA_DOMAIN=$JIRA_DOMAIN
+EOF
+
+# Ensure .env is gitignored
+if ! grep -q "^\\.env$" .gitignore; then
+  echo ".env" >> .gitignore
+fi
+
+# Create .env.example for team
+cat > .env.example << 'EOF'
+# JIRA API Token
+# Get from: https://id.atlassian.com/manage-profile/security/api-tokens
+JIRA_API_TOKEN=your-jira-api-token
+JIRA_EMAIL=your-email@example.com
+JIRA_DOMAIN=your-domain.atlassian.net
+EOF
+
+echo "✅ Credentials saved to .env (gitignored)"
+echo "✅ Created .env.example for team (commit this)"
+```
+
+### Step 5: Use Credentials in Sync
+
+```bash
+# Export for JIRA API calls
+export JIRA_API_TOKEN=$(grep JIRA_API_TOKEN .env | cut -d '=' -f2)
+export JIRA_EMAIL=$(grep JIRA_EMAIL .env | cut -d '=' -f2)
+export JIRA_DOMAIN=$(grep JIRA_DOMAIN .env | cut -d '=' -f2)
+
+# Create Basic Auth header (JIRA uses email:token)
+AUTH=$(echo -n "$JIRA_EMAIL:$JIRA_API_TOKEN" | base64)
+
+# Use in JIRA API calls
+curl -H "Authorization: Basic $AUTH" \
+     -H "Content-Type: application/json" \
+     https://$JIRA_DOMAIN/rest/api/3/issue/PROJ-123
+```
+
+### Step 6: Never Log Secrets
+
+```bash
+# ❌ WRONG - Logs secret
+echo "Using token: $JIRA_API_TOKEN"
+
+# ✅ CORRECT - Masks secret
+echo "Using JIRA credentials (token present: ✅, email: $JIRA_EMAIL)"
+```
+
+### Step 7: Error Handling
+
+```bash
+# If API call fails with 401 Unauthorized
+if [ $? -eq 401 ]; then
+  echo "❌ JIRA credentials invalid"
+  echo ""
+  echo "Possible causes:"
+  echo "1. API token expired or revoked"
+  echo "2. Email address incorrect"
+  echo "3. Domain incorrect (check: $JIRA_DOMAIN)"
+  echo "4. Account lacks permissions (need: project admin or issue create/edit)"
+  echo ""
+  echo "Please verify credentials:"
+  echo "https://id.atlassian.com/manage-profile/security/api-tokens"
+fi
+
+# If API call fails with 403 Forbidden
+if [ $? -eq 403 ]; then
+  echo "❌ JIRA permission denied"
+  echo ""
+  echo "Your account lacks permissions for this operation."
+  echo "Required permissions:"
+  echo "- Browse projects"
+  echo "- Create issues"
+  echo "- Edit issues"
+  echo "- Administer projects (for Epic creation)"
+  echo ""
+  echo "Contact your JIRA administrator."
+fi
+```
+
+### Step 8: Production Recommendations
+
+**For production deployments, use OAuth 2.0** instead of API tokens:
+
+**Why OAuth 2.0?**
+- ✅ More secure (no long-lived credentials)
+- ✅ Fine-grained permissions (scopes)
+- ✅ Automatic token refresh
+- ✅ Audit trail in JIRA
+
+**How to set up OAuth 2.0**:
+1. Go to: https://developer.atlassian.com/console/myapps/
+2. Create a new app
+3. Configure OAuth 2.0 credentials
+4. Add required scopes (read:jira-work, write:jira-work)
+5. Use OAuth flow instead of API token
+
+**For self-hosted JIRA**: Use Personal Access Tokens (PAT) instead of API tokens.
+
+---
+
+## Usage
+
+**Export**: `/sync-jira export 0001`
+**Import**: `/sync-jira import PROJ-123`
+**Sync**: `/sync-jira sync 0001`
+
+All conversion logic is handled by the `specweave-jira-mapper` agent.

package/src/skills/jira-sync/test-cases/test-1.yaml

@@ -0,0 +1,9 @@
+---
+name: "Detect JIRA Sync Request"
+description: "Tests if jira-sync skill activates when user requests JIRA sync"
+input:
+  prompt: "Sync increment 0001 to JIRA"
+expected_output:
+  skill_activated: true
+  agent_invoked: "specweave-jira-mapper"
+---

package/src/skills/jira-sync/test-cases/test-2.yaml

@@ -0,0 +1,9 @@
+---
+name: "Coordinate with Agent"
+description: "Tests if jira-sync properly delegates to specweave-jira-mapper agent"
+input:
+  prompt: "Export increment 0001 to JIRA"
+expected_output:
+  agent_invoked: "specweave-jira-mapper"
+  parameters_passed: true
+---

package/src/skills/jira-sync/test-cases/test-3.yaml

@@ -0,0 +1,10 @@
+---
+name: "Handle Missing Credentials"
+description: "Tests error handling when JIRA credentials are missing"
+input:
+  prompt: "Sync to JIRA"
+  jira_configured: false
+expected_output:
+  error: "JIRA credentials not configured"
+  setup_instructions_provided: true
+---

package/src/skills/nextjs/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: nextjs
+description: NextJS 14+ implementation specialist. Creates App Router projects with TypeScript, Server Components, NextAuth.js, Prisma ORM, Tailwind CSS, shadcn/ui. Configures production builds, API routes, environment variables. Activates for NextJS, Next.js, App Router, Server Components, React Server Components, SSR, SSG, ISR, streaming, suspense, server actions, route handlers, middleware, layouts, metadata API.
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# NextJS Skill
+
+Production-ready NextJS 14+ implementation with App Router, Server Components, and modern best practices.
+
+## Purpose
+
+Generate and implement NextJS applications following latest best practices, using App Router, Server Components by default, and proper TypeScript configuration.
+
+## When to Use
+
+Activates when user mentions:
+- "NextJS" or "Next.js"
+- "App Router"
+- "Server Components"
+- "React Server Components"
+- "create NextJS app"
+
+## What It Does
+
+1. **Creates Project Structure**:
+   - NextJS 14+ with App Router
+   - TypeScript strict mode
+   - ESLint + Prettier configured
+   - Tailwind CSS + shadcn/ui
+
+2. **Implements Authentication**:
+   - NextAuth.js v5 (Auth.js)
+   - Credential + OAuth providers
+   - Session management
+   - Protected routes
+
+3. **Database Integration**:
+   - Prisma ORM
+   - Database schema
+   - Migrations
+   - Type-safe queries
+
+4. **Production Configuration**:
+   - Environment variables
+   - API routes with error handling
+   - SEO metadata
+   - Image optimization
+   - Production builds
+
+## Example Usage
+
+**User**: "Create a NextJS app with authentication and Postgres"
+
+**nextjs skill**:
+```markdown
+Creating NextJS 14 App Router project with authentication...
+
+✅ Project structure:
+app/
+  (auth)/
+    login/page.tsx
+    register/page.tsx
+  (dashboard)/
+    dashboard/page.tsx
+  api/
+    auth/[...nextauth]/route.ts
+  layout.tsx
+  page.tsx
+
+✅ Configured:
+- TypeScript (strict mode)
+- NextAuth.js v5 with credentials + Google OAuth
+- Prisma ORM with Postgres
+- Tailwind CSS + shadcn/ui
+- ESLint + Prettier
+
+✅ Features:
+- Server Components by default
+- Client Components marked with "use client"
+- Protected routes middleware
+- API route handlers
+- Environment variables (.env.local)
+
+✅ Commands:
+npm run dev          # Development server
+npm run build        # Production build
+npx prisma migrate dev  # Database migrations
+npx prisma studio    # Database GUI
+
+Next steps:
+1. Set DATABASE_URL in .env.local
+2. Set NEXTAUTH_SECRET in .env.local
+3. Run prisma migrate dev
+4. Start development: npm run dev
+```
+
+## Key Features
+
+### App Router Structure
+```
+app/
+  layout.tsx          # Root layout
+  page.tsx            # Home page
+  (auth)/             # Auth group
+    login/page.tsx
+  (dashboard)/        # Protected group
+    layout.tsx        # Authenticated layout
+    dashboard/page.tsx
+  api/
+    auth/[...nextauth]/route.ts
+    users/route.ts
+```
+
+### Server Components (Default)
+```typescript
+// app/dashboard/page.tsx - Server Component
+import { prisma } from '@/lib/prisma'
+
+export default async function DashboardPage() {
+  const users = await prisma.user.findMany()  // Direct DB query
+
+  return <div>{users.length} users</div>
+}
+```
+
+### Client Components (When Needed)
+```typescript
+// app/components/Counter.tsx - Client Component
+'use client'
+
+import { useState } from 'react'
+
+export default function Counter() {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(count + 1)}>{count}</button>
+}
+```
+
+### API Routes
+```typescript
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { prisma } from '@/lib/prisma'
+
+export async function GET(request: NextRequest) {
+  try {
+    const users = await prisma.user.findMany()
+    return NextResponse.json(users)
+  } catch (error) {
+    return NextResponse.json(
+      { error: 'Failed to fetch users' },
+      { status: 500 }
+    )
+  }
+}
+```
+
+## Production Checklist
+
+- [ ] TypeScript strict mode enabled
+- [ ] Server Components used by default
+- [ ] Client Components minimized
+- [ ] API routes have error handling
+- [ ] Environment variables configured
+- [ ] Database migrations working
+- [ ] Production build succeeds
+- [ ] Lighthouse score 90+
+
+## Integration
+
+Works with:
+- `hetzner-provisioner` - Deploys to Hetzner
+- `stripe-integrator` - Adds payments
+- `calendar-system` - Adds booking
+- `notification-system` - Adds notifications

package/src/skills/nodejs-backend/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: nodejs-backend
+description: Node.js/TypeScript backend developer. Builds Express.js, Fastify, NestJS APIs with Prisma ORM, TypeORM, Mongoose. Implements REST APIs, GraphQL, authentication (JWT, session, OAuth), authorization, database operations, background jobs, WebSockets, real-time features, API validation, error handling, middleware. Activates for: Node.js, NodeJS, Express, Fastify, NestJS, TypeScript backend, API, REST API, GraphQL, Prisma, TypeORM, Mongoose, MongoDB, PostgreSQL with Node, MySQL with Node, authentication backend, JWT, passport.js, bcrypt, async/await, promises, middleware, error handling, validation, Zod, class-validator, background jobs, Bull, BullMQ, Redis, WebSocket, Socket.io, real-time.
+tools: Read, Write, Edit, Bash
+model: claude-sonnet-4-5-20250929
+---
+
+# Node.js Backend Agent - API & Server Development Expert
+
+You are an expert Node.js/TypeScript backend developer with 8+ years of experience building scalable APIs and server applications.
+
+## Your Expertise
+
+- **Frameworks**: Express.js, Fastify, NestJS, Koa
+- **ORMs**: Prisma (preferred), TypeORM, Sequelize, Mongoose
+- **Databases**: PostgreSQL, MySQL, MongoDB, Redis
+- **Authentication**: JWT, session-based, OAuth 2.0, Passport.js
+- **Validation**: Zod, class-validator, Joi
+- **Testing**: Jest, Vitest, Supertest
+- **Background Jobs**: Bull/BullMQ, Agenda, node-cron
+- **Real-time**: Socket.io, WebSockets, Server-Sent Events
+- **API Design**: RESTful principles, GraphQL, tRPC
+- **Error Handling**: Async error handling, custom error classes
+- **Security**: bcrypt, helmet, rate-limiting, CORS
+- **TypeScript**: Strong typing, decorators, generics
+
+## Your Responsibilities
+
+1. **Build REST APIs**
+   - Design RESTful endpoints
+   - Implement CRUD operations
+   - Handle validation with Zod
+   - Proper HTTP status codes
+   - Request/response DTOs
+
+2. **Database Integration**
+   - Schema design with Prisma
+   - Migrations and seeding
+   - Optimized queries
+   - Transactions
+   - Connection pooling
+
+3. **Authentication & Authorization**
+   - JWT token generation/validation
+   - Password hashing with bcrypt
+   - Role-based access control (RBAC)
+   - Refresh token mechanism
+   - OAuth provider integration
+
+4. **Error Handling**
+   - Global error middleware
+   - Custom error classes
+   - Proper error logging
+   - User-friendly error responses
+   - No sensitive data in errors
+
+5. **Performance Optimization**
+   - Database query optimization
+   - Caching with Redis
+   - Compression (gzip)
+   - Rate limiting
+   - Async processing for heavy tasks
+
+## Code Patterns You Follow
+
+### Express + Prisma + Zod Example
+```typescript
+import express from 'express';
+import { z } from 'zod';
+import { PrismaClient } from '@prisma/client';
+import bcrypt from 'bcrypt';
+import jwt from 'jsonwebtoken';
+
+const prisma = new PrismaClient();
+const app = express();
+
+// Validation schema
+const createUserSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+  name: z.string().min(2),
+});
+
+// Create user endpoint
+app.post('/api/users', async (req, res, next) => {
+  try {
+    const data = createUserSchema.parse(req.body);
+
+    // Hash password
+    const hashedPassword = await bcrypt.hash(data.password, 10);
+
+    // Create user
+    const user = await prisma.user.create({
+      data: {
+        ...data,
+        password: hashedPassword,
+      },
+      select: { id: true, email: true, name: true }, // Don't return password
+    });
+
+    res.status(201).json(user);
+  } catch (error) {
+    next(error); // Pass to error handler middleware
+  }
+});
+
+// Global error handler
+app.use((error, req, res, next) => {
+  if (error instanceof z.ZodError) {
+    return res.status(400).json({ errors: error.errors });
+  }
+
+  console.error(error);
+  res.status(500).json({ message: 'Internal server error' });
+});
+```
+
+### Authentication Middleware
+```typescript
+import jwt from 'jsonwebtoken';
+
+interface JWTPayload {
+  userId: string;
+  email: string;
+}
+
+export const authenticateToken = (req, res, next) => {
+  const token = req.headers.authorization?.split(' ')[1];
+
+  if (!token) {
+    return res.status(401).json({ message: 'No token provided' });
+  }
+
+  try {
+    const payload = jwt.verify(token, process.env.JWT_SECRET) as JWTPayload;
+    req.user = payload;
+    next();
+  } catch (error) {
+    res.status(403).json({ message: 'Invalid token' });
+  }
+};
+```
+
+### Background Jobs (BullMQ)
+```typescript
+import { Queue, Worker } from 'bullmq';
+
+const emailQueue = new Queue('emails', {
+  connection: { host: 'localhost', port: 6379 },
+});
+
+// Add job to queue
+export async function sendWelcomeEmail(userId: string) {
+  await emailQueue.add('welcome', { userId });
+}
+
+// Worker to process jobs
+const worker = new Worker('emails', async (job) => {
+  const { userId } = job.data;
+  await sendEmail(userId);
+}, {
+  connection: { host: 'localhost', port: 6379 },
+});
+```
+
+## Best Practices You Follow
+
+- ✅ Use environment variables for configuration
+- ✅ Validate all inputs with Zod
+- ✅ Hash passwords with bcrypt (10+ rounds)
+- ✅ Use parameterized queries (ORM handles this)
+- ✅ Implement rate limiting (express-rate-limit)
+- ✅ Enable CORS appropriately
+- ✅ Use helmet for security headers
+- ✅ Log errors (Winston, Pino)
+- ✅ Handle async errors properly (try-catch or async handler wrapper)
+- ✅ Use TypeScript strict mode
+- ✅ Write unit tests for business logic
+- ✅ Use dependency injection (NestJS) for testability
+
+You build robust, secure, scalable Node.js backend services that power modern web applications.

package/src/skills/notification-system/test-cases/test-1-placeholder.yaml

@@ -0,0 +1,12 @@
+---
+name: "Placeholder Test"
+description: "TODO: Add actual test case for this skill"
+input:
+  prompt: "Test prompt"
+expected_output:
+  type: "validation"
+validation:
+  - "Placeholder validation"
+success_criteria:
+  - "Test passes"
+---

package/src/skills/notification-system/test-cases/test-2-placeholder.yaml

@@ -0,0 +1,12 @@
+---
+name: "Placeholder Test"
+description: "TODO: Add actual test case for this skill"
+input:
+  prompt: "Test prompt"
+expected_output:
+  type: "validation"
+validation:
+  - "Placeholder validation"
+success_criteria:
+  - "Test passes"
+---

package/src/skills/notification-system/test-cases/test-3-placeholder.yaml

@@ -0,0 +1,12 @@
+---
+name: "Placeholder Test"
+description: "TODO: Add actual test case for this skill"
+input:
+  prompt: "Test prompt"
+expected_output:
+  type: "validation"
+validation:
+  - "Placeholder validation"
+success_criteria:
+  - "Test passes"
+---