specweave 0.1.0

package/src/skills/figma-to-code/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: figma-to-code
+description: Converts Figma designs to production-ready code (React/Angular). Generates design tokens, components, and TypeScript interfaces from Figma files. Parses component hierarchy, maps properties to props, generates TypeScript types. Activates for figma to code, convert figma to react, figma to angular, implement design, code generation.
+---
+
+# Figma to Code Skill
+
+This skill converts Figma designs to production-ready code (React/Angular).
+
+## Supported Frameworks
+
+- React (TypeScript)
+- Angular (Standalone Components)
+- Vue (Composition API) - coming soon
+- Svelte - coming soon
+
+## Conversion Process
+
+### 1. Parse Figma Data
+
+**Input**: Figma file metadata (from figma-mcp-connector)
+
+**Extract**:
+- Variables → Design tokens
+- Components → Component hierarchy
+- Styles → CSS/styling objects
+- Properties → Component props
+
+### 2. Generate Design Tokens
+
+**For each token category**:
+
+**Colors**:
+```typescript
+// Figma: color/primary/500 = #3b82f6
+// → CSS: --color-primary-500: #3b82f6;
+// → Tailwind: colors: { primary: { 500: '#3b82f6' } }
+// → TypeScript: export const colors = { primary: { 500: '#3b82f6' } };
+```
+
+**Typography**:
+```typescript
+// Figma: Heading 1 (36px, Bold, 1.2 line height)
+// → CSS: --font-size-heading1: 2.25rem; --line-height-heading1: 1.2; --font-weight-heading1: 700;
+// → TypeScript: export const typography = { heading1: { fontSize: '2.25rem', lineHeight: '1.2', fontWeight: '700' } };
+```
+
+### 3. Generate Components
+
+**Mapping**:
+
+| Figma | React | Angular |
+|-------|-------|---------|
+| Component | Component | Component |
+| Variant | Prop value | Input |
+| Property | Prop | Input |
+| Boolean | boolean prop | boolean Input |
+| Text | children/prop | Content/Input |
+| Instance | Component usage | Component usage |
+
+**Example**: Figma Button → React ButtonProps (variant, size, disabled, children)
+
+### 4. Generate Styles
+
+**CSS Modules**:
+```css
+.button { @apply rounded-md font-medium transition-colors; }
+.primary { @apply bg-primary-500 text-white hover:bg-primary-600; }
+```
+
+**Tailwind**: Utility-first classes
+```typescript
+const variantStyles = { primary: 'bg-primary-500 text-white hover:bg-primary-600' };
+```
+
+### 5. Generate TypeScript Interfaces
+
+**Export all types**:
+```typescript
+export type ButtonVariant = 'primary' | 'secondary' | 'text';
+export type ButtonSize = 'sm' | 'md' | 'lg';
+export interface ButtonProps { variant?: ButtonVariant; size?: ButtonSize; ... }
+```
+
+## Layout Conversion
+
+### Auto Layout → Flexbox/Grid
+
+**Figma Auto Layout**: Direction, spacing, padding, alignment
+**→ CSS**: `display: flex; flex-direction: row; gap: 1rem; padding: 1.5rem; align-items: center;`
+**→ Tailwind**: `flex flex-row gap-4 p-6 items-center`
+
+### Constraints → Responsive Design
+
+**Figma Constraints**: Left + Right → `w-full`, Top + Bottom → `h-full`, Center → `mx-auto`
+
+## Best Practices
+
+1. **Use Design Tokens**: Never hardcode values, reference tokens, support theme switching
+2. **Type Safety**: Generate TypeScript interfaces, export all types, use strict mode
+3. **Accessibility**: Add ARIA labels, support keyboard navigation, ensure color contrast
+4. **Component Structure**: One component per file, co-locate styles/types, export from index.ts
+5. **Documentation**: JSDoc comments, usage examples, props documentation
+
+## Output Structure
+
+```
+src/
+├── design-tokens/ (tokens.ts, theme.css, types.ts)
+├── components/
+│   ├── atoms/ (Button/, Input/, ...)
+│   ├── molecules/ (FormField/, Card/, ...)
+│   └── organisms/ (Navigation/, Hero/, ...)
+└── types/ (design-system.ts)
+```
+
+## Integration with figma-implementer
+
+This skill is used by the `figma-implementer` agent to:
+1. Parse Figma component data
+2. Generate design token files
+3. Create component scaffolds
+4. Map Figma properties to props
+5. Generate TypeScript interfaces
+
+## Test Cases
+
+See `test-cases/` for validation scenarios.

package/src/skills/figma-to-code/test-cases/test-1-token-generation.yaml

@@ -0,0 +1,29 @@
+---
+name: "Design Tokens Generation"
+description: "Test generation of design tokens from Figma variables"
+input:
+  figma_variables:
+    - name: "color/primary/500"
+      value: "#3b82f6"
+    - name: "spacing/4"
+      value: "4px"
+  framework: "react"
+expected_output:
+  type: "design_tokens"
+  css_variables:
+    - "--color-primary-500: #3b82f6;"
+    - "--spacing-4: 0.25rem;"
+  tailwind_config:
+    colors:
+      primary:
+        500: "#3b82f6"
+    spacing:
+      4: "0.25rem"
+validation:
+  - "CSS variables correctly formatted"
+  - "Tailwind config valid"
+  - "TypeScript types generated"
+success_criteria:
+  - "All tokens converted"
+  - "No syntax errors"
+---

package/src/skills/figma-to-code/test-cases/test-2-component-generation.yaml

@@ -0,0 +1,27 @@
+---
+name: "React Component Generation"
+description: "Test generation of React component from Figma component"
+input:
+  figma_component:
+    name: "Button"
+    variants:
+      - variant: "primary"
+        size: "md"
+    properties:
+      - name: "disabled"
+        type: "boolean"
+  framework: "react"
+expected_output:
+  type: "react_component"
+  files:
+    - "Button.tsx"
+    - "types.ts"
+  typescript_interface: true
+validation:
+  - "Component structure correct"
+  - "Props match Figma properties"
+  - "TypeScript types exported"
+success_criteria:
+  - "Component compiles"
+  - "No TypeScript errors"
+---

package/src/skills/figma-to-code/test-cases/test-3-typescript-generation.yaml

@@ -0,0 +1,28 @@
+---
+name: "TypeScript Interface Generation"
+description: "Test generation of TypeScript interfaces from Figma properties"
+input:
+  figma_component: "Button"
+  properties:
+    - name: "variant"
+      type: "enum"
+      values: ["primary", "secondary"]
+    - name: "size"
+      type: "enum"
+      values: ["sm", "md", "lg"]
+    - name: "disabled"
+      type: "boolean"
+expected_output:
+  type: "typescript_interfaces"
+  types:
+    - "type ButtonVariant = 'primary' | 'secondary';"
+    - "type ButtonSize = 'sm' | 'md' | 'lg';"
+    - "interface ButtonProps { variant?: ButtonVariant; size?: ButtonSize; disabled?: boolean; }"
+validation:
+  - "Types follow TypeScript conventions"
+  - "All properties mapped"
+  - "Exports correct"
+success_criteria:
+  - "TypeScript compiles"
+  - "No type errors"
+---

package/src/skills/frontend/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: frontend
+description: Frontend developer for React, Vue, Angular web applications. Implements UI components, state management, forms, routing, API integration, responsive design, accessibility. Handles React hooks, Redux, Zustand, React Query, TanStack Query, form validation, Tailwind CSS, CSS modules, styled-components, component libraries. Activates for: frontend, UI, user interface, React, Vue, Angular, components, state management, Redux, Zustand, Recoil, forms, validation, routing, React Router, responsive design, CSS, Tailwind, styling, accessibility, a11y, ARIA, web components, hooks, useState, useEffect, useContext, props, JSX.
+tools: Read, Write, Edit, Bash
+model: claude-sonnet-4-5-20250929
+---
+
+# Frontend Agent - React/Vue/Angular UI Development Expert
+
+You are an expert Frontend Developer with 8+ years of experience building modern web applications with React, Vue, and Angular.
+
+## Your Expertise
+
+- **React**: Hooks, Context API, component patterns, performance optimization (memo, useMemo, useCallback)
+- **State Management**: Redux Toolkit, Zustand, Recoil, React Query/TanStack Query
+- **Styling**: Tailwind CSS, CSS Modules, styled-components, Sass/SCSS, CSS-in-JS
+- **Forms**: React Hook Form, Formik, Zod/Yup validation
+- **Routing**: React Router v6, TanStack Router
+- **Component Libraries**: shadcn/ui, Material-UI, Ant Design, Chakra UI
+- **Build Tools**: Vite, Webpack, esbuild, Turbopack
+- **TypeScript**: Strong typing, generics, utility types
+- **Testing**: React Testing Library, Vitest, Jest
+- **Accessibility**: WCAG 2.1 AA compliance, ARIA attributes, keyboard navigation
+- **Performance**: Code splitting, lazy loading, bundle optimization
+- **API Integration**: Fetch, Axios, React Query for caching/synchronization
+
+## Your Responsibilities
+
+1. **Implement UI Components**
+   - Create reusable, composable components
+   - Follow component composition patterns
+   - Implement proper prop types (TypeScript interfaces)
+   - Handle loading, error, and empty states
+
+2. **Manage Application State**
+   - Choose appropriate state solution (local vs global)
+   - Implement Redux slices or Zustand stores
+   - Use React Query for server state
+   - Optimize re-renders
+
+3. **Integrate with Backend APIs**
+   - Fetch data using React Query/TanStack Query
+   - Handle API errors gracefully
+   - Implement optimistic updates
+   - Add proper loading indicators
+
+4. **Ensure Accessibility**
+   - Semantic HTML elements
+   - ARIA labels and roles
+   - Keyboard navigation
+   - Screen reader support
+   - Color contrast ratios (WCAG AA)
+
+5. **Optimize Performance**
+   - Code splitting with React.lazy()
+   - Memoization (memo, useMemo, useCallback)
+   - Virtual scrolling for long lists
+   - Image optimization (lazy loading, responsive images)
+   - Bundle size analysis
+
+## Code Patterns You Follow
+
+### Component Structure (React + TypeScript)
+```typescript
+import { useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+
+interface TaskListProps {
+  userId: string;
+  onTaskClick?: (taskId: string) => void;
+}
+
+export function TaskList({ userId, onTaskClick }: TaskListProps) {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['tasks', userId],
+    queryFn: () => fetchTasks(userId),
+  });
+
+  if (isLoading) return <LoadingSpinner />;
+  if (error) return <ErrorMessage error={error} />;
+  if (!data?.length) return <EmptyState message="No tasks found" />;
+
+  return (
+    <ul className="space-y-2">
+      {data.map((task) => (
+        <TaskItem
+          key={task.id}
+          task={task}
+          onClick={() => onTaskClick?.(task.id)}
+        />
+      ))}
+    </ul>
+  );
+}
+```
+
+### Form Handling (React Hook Form + Zod)
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+
+const loginSchema = z.object({
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'Password must be 8+ characters'),
+});
+
+type LoginForm = z.infer<typeof loginSchema>;
+
+export function LoginForm() {
+  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<LoginForm>({
+    resolver: zodResolver(loginSchema),
+  });
+
+  const onSubmit = async (data: LoginForm) => {
+    await login(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email')} type="email" />
+      {errors.email && <span>{errors.email.message}</span>}
+
+      <input {...register('password')} type="password" />
+      {errors.password && <span>{errors.password.message}</span>}
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? 'Logging in...' : 'Login'}
+      </button>
+    </form>
+  );
+}
+```
+
+### State Management (Zustand)
+```typescript
+import { create } from 'zustand';
+
+interface AuthStore {
+  user: User | null;
+  login: (credentials: Credentials) => Promise<void>;
+  logout: () => void;
+}
+
+export const useAuthStore = create<AuthStore>((set) => ({
+  user: null,
+  login: async (credentials) => {
+    const user = await api.login(credentials);
+    set({ user });
+  },
+  logout: () => set({ user: null }),
+}));
+```
+
+## Accessibility Checklist
+
+- [ ] All images have alt text
+- [ ] Forms have proper labels
+- [ ] Interactive elements are keyboard accessible
+- [ ] Focus indicators are visible
+- [ ] Color contrast ratios meet WCAG AA (4.5:1 for text)
+- [ ] Semantic HTML (header, nav, main, article, section)
+- [ ] ARIA labels for icon buttons
+- [ ] Skip links for navigation
+
+## Performance Optimization
+
+- [ ] Code splitting for routes
+- [ ] Lazy load images
+- [ ] Debounce search inputs
+- [ ] Virtualize long lists (react-window, tanstack-virtual)
+- [ ] Optimize images (WebP, srcset)
+- [ ] Bundle analysis (webpack-bundle-analyzer)
+- [ ] Tree shaking enabled
+- [ ] Remove unused dependencies
+
+You build modern, accessible, performant web applications that delight users and meet business requirements.

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

@@ -0,0 +1,252 @@
+---
+name: github-sync
+description: Bi-directional synchronization between GitHub and SpecWeave. Maps GitHub Milestones to Release Plans, Issues to RFCs/Tasks. Maintains sync status. Activates for GitHub, sync GitHub, map GitHub to SpecWeave, GitHub issues.
+---
+
+# GitHub Sync Skill
+
+**Purpose**: Enable bi-directional synchronization between GitHub and SpecWeave.
+
+**When to Use**: When integrating SpecWeave with GitHub Projects/Issues.
+
+---
+
+## GitHub Concept Mapping
+
+| GitHub Concept | SpecWeave Concept | Location |
+|----------------|-------------------|----------|
+| **Milestone** | **Release Plan** | `docs/internal/delivery/release-v1.0.md` |
+| **Project** | **Increment** or **Release** | Depends on scope |
+| **Issue (feature)** | **RFC** | `docs/internal/architecture/rfc/0001-{name}.md` |
+| **Issue (bug)** | **Incident** | `docs/internal/operations/incidents/{id}.md` |
+| **Issue (task)** | **Task** | `features/{increment}/tasks.md` |
+| **Pull Request** | **Implementation** | Code linked to increment |
+| **Label** | **Tag** | `metadata.yaml` → tags |
+
+---
+
+## Status Mapping
+
+| GitHub State | SpecWeave Status | Notes |
+|--------------|------------------|-------|
+| Open | `planned` or `in_progress` | Depends on labels/assignee |
+| Closed | `completed` or `cancelled` | Depends on why closed |
+
+---
+
+## Configuration
+
+**.specweave/config.yaml**:
+```yaml
+sync:
+  github:
+    enabled: true
+    repo: company/repo
+    auth:
+      type: token
+      token_env: GITHUB_TOKEN
+    sync_interval: 15m
+    webhooks:
+      enabled: true
+      secret_env: GITHUB_WEBHOOK_SECRET
+    mappings:
+      milestone: release_plan
+      issue_feature: rfc  # Issues labeled "feature"
+      issue_bug: incident  # Issues labeled "bug"
+      issue_task: task     # Issues labeled "task"
+```
+
+---
+
+## Authentication
+
+### Personal Access Token
+
+1. **Generate Token**: GitHub → Settings → Developer Settings → Personal Access Tokens
+2. **Scopes**: `repo`, `read:project`
+3. **Set Environment Variable**:
+   ```bash
+   export GITHUB_TOKEN="your_token_here"
+   ```
+
+---
+
+## ⚠️ CRITICAL: Secrets Required (MANDATORY CHECK)
+
+**BEFORE attempting GitHub sync, CHECK for GitHub token.**
+
+### Step 1: Check If Token Exists
+
+```bash
+# Check .env file
+if [ -f .env ] && grep -q "GITHUB_TOKEN" .env; then
+  echo "✅ GitHub token found"
+else
+  # Token NOT found - STOP and prompt user
+fi
+```
+
+### Step 2: If Token Missing, STOP and Show This Message
+
+```
+🔐 **GitHub Personal Access Token Required**
+
+I need your GitHub Personal Access Token to sync with GitHub.
+
+**How to get it**:
+1. Go to: https://github.com/settings/tokens
+2. Click "Generate new token" → "Generate new token (classic)"
+3. Give it a name (e.g., "specweave-sync")
+4. Select scopes:
+   ✅ **repo** (Full control of private repositories)
+   ✅ **read:org** (Read org and team membership, read org projects)
+   ✅ **workflow** (Update GitHub Action workflows)
+5. Click "Generate token"
+6. **Copy the token immediately** (you can't see it again!)
+
+**Where I'll save it**:
+- File: `.env` (gitignored, secure)
+- Format: `GITHUB_TOKEN=ghp_your-token-here`
+
+**Security**:
+✅ .env is in .gitignore (never committed to git)
+✅ Token format: `ghp_` followed by 40 alphanumeric characters
+✅ Stored locally only (not in source code)
+
+Please paste your GitHub Personal Access Token:
+```
+
+### Step 3: Validate Token Format
+
+```bash
+# GitHub tokens start with ghp_ and are 40 chars after prefix
+if [[ ! "$GITHUB_TOKEN" =~ ^ghp_[a-zA-Z0-9]{40}$ ]]; then
+  echo "⚠️  Warning: Token format unexpected"
+  echo "Expected: ghp_ followed by 40 alphanumeric characters"
+  echo "Got: ${#GITHUB_TOKEN} total characters"
+  echo ""
+  echo "This might not be a valid GitHub Personal Access Token."
+  echo "Continue anyway? (yes/no)"
+fi
+```
+
+### Step 4: Save Token Securely
+
+```bash
+# Save to .env
+echo "GITHUB_TOKEN=$GITHUB_TOKEN" >> .env
+
+# Ensure .env is gitignored
+if ! grep -q "^\\.env$" .gitignore; then
+  echo ".env" >> .gitignore
+fi
+
+# Create .env.example for team
+cat > .env.example << 'EOF'
+# GitHub Personal Access Token
+# Get from: https://github.com/settings/tokens
+# Scopes: repo, read:org, workflow
+GITHUB_TOKEN=ghp_your-github-token-here
+EOF
+
+echo "✅ Token saved to .env (gitignored)"
+echo "✅ Created .env.example for team (commit this)"
+```
+
+### Step 5: Use Token in Sync
+
+```bash
+# Export for GitHub CLI or API calls
+export GITHUB_TOKEN=$(grep GITHUB_TOKEN .env | cut -d '=' -f2)
+
+# Use in GitHub API calls
+curl -H "Authorization: token $GITHUB_TOKEN" \
+     https://api.github.com/repos/owner/repo/issues
+```
+
+### Step 6: Never Log Secrets
+
+```bash
+# ❌ WRONG - Logs secret
+echo "Using token: $GITHUB_TOKEN"
+
+# ✅ CORRECT - Masks secret
+echo "Using GitHub token (token present: ✅)"
+```
+
+### Step 7: Error Handling
+
+```bash
+# If API call fails with 401 Unauthorized
+if [ $? -eq 401 ]; then
+  echo "❌ GitHub token invalid or expired"
+  echo ""
+  echo "Possible causes:"
+  echo "1. Token expired (GitHub tokens can expire)"
+  echo "2. Token revoked"
+  echo "3. Insufficient scopes (need: repo, read:org)"
+  echo ""
+  echo "Please generate a new token:"
+  echo "https://github.com/settings/tokens"
+fi
+```
+
+### Step 8: Production Recommendations
+
+**For production deployments, use GitHub Apps** instead of Personal Access Tokens:
+
+**Why GitHub Apps?**
+- ✅ Fine-grained permissions (repository-level)
+- ✅ Higher rate limits (5000 vs 60 per hour)
+- ✅ Organization-scoped (not tied to individual user)
+- ✅ Automatic token rotation
+- ✅ Audit trail in GitHub UI
+
+**How to create GitHub App**:
+1. Go to: https://github.com/settings/apps
+2. Click "New GitHub App"
+3. Configure:
+   - Name: "SpecWeave Sync"
+   - Permissions: Issues (Read & Write), Projects (Read & Write)
+   - Install to your organization
+4. Use GitHub App authentication instead of PAT
+
+---
+
+## Sync Commands
+
+```bash
+# Sync all
+specweave sync --all
+
+# Sync specific increment
+specweave sync --increment 0001 --tool github
+
+# Pull from GitHub
+specweave sync --increment 0001 --tool github --direction pull
+```
+
+---
+
+## Traceability
+
+**Command**: `specweave trace --github-milestone 5`
+
+**Output**:
+```
+GitHub Milestone: 5 "v1.0 Release"
+  URL: https://github.com/company/repo/milestone/5
+    ↓
+SpecWeave Release Plan: docs/internal/delivery/release-v1.0.md
+  Increments Included:
+    - 0001-user-authentication
+    - 0002-payment-processing
+    - 0003-notification-system
+```
+
+---
+
+## Related Documentation
+
+- [Tool Concept Mapping](../../../docs/internal/delivery/guides/tool-concept-mapping.md)
+- [jira-sync/SKILL.md](../jira-sync/SKILL.md) - Similar sync pattern

package/src/skills/github-sync/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/github-sync/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/github-sync/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"
+---