npm package: @metasession/workflows
Description: Engineering workflows and skills for AI coding assistants (Windsurf, Claude Code, Cursor, VS Code + Copilot)
Author: Metasession
Latest version: 2.0.0

# @metasession/workflows

Engineering **workflows** and **skills** for AI coding assistants. Install curated process workflows and code-generation skills for **Windsurf**, **Claude Code**, **Cursor**, and **VS Code + Copilot**.

> **v2.0** — Now with Skills: composable, code-generating instructions that scaffold production-ready features, components, services, and tests.

## Quick Start

```bash
# Install everything (workflows + skills)
npx @metasession/workflows init

# Install only workflows
npx @metasession/workflows init --workflows-only

# Install only skills
npx @metasession/workflows init --skills-only

# Add a specific workflow
npx @metasession/workflows add code-review

# Add a specific skill
npx @metasession/workflows add-skill create-feature

# List everything
npx @metasession/workflows list
```

## Workflows vs Skills

| | Workflows | Skills |
|---|-----------|--------|
| **Purpose** | Guide development processes | Generate code artifacts |
| **Output** | Decisions, reviews, deployments | Files, components, services, tests |
| **Invocation** | `/<workflow-name>` | "Use the `<skill>` skill to..." |
| **Example** | `/code-review` | "Use **create-feature** to build assessments" |
| **Directory** | `.windsurf/workflows/` | `.windsurf/skills/` |

**Skills compose together.** The `create-feature` skill orchestrates 8 sub-skills to scaffold an entire full-stack feature:

```
create-feature
├── create-zod-schema        → lib/schemas/
├── create-service            → lib/services/
├── create-api-route          → app/api/
├── create-hook               → hooks/
├── create-component          → components/
├── create-dashboard-page     → app/admin/
├── create-rbac-policy        → RLS + middleware
└── create-bdd-test           → tests/bdd/
```

## Supported IDEs

| IDE | Workflows | Skills | Slash Commands |
|-----|-----------|--------|----------------|
| **Windsurf** | `.windsurf/workflows/` | `.windsurf/skills/` | ✅ Yes |
| **Claude Code** | `.claude/commands/` | `.claude/skills/` | ✅ Yes |
| **Cursor** | `.cursor/workflows/` | `.cursor/skills/` | ❌ Rules-based |
| **VS Code + Copilot** | `.github/workflows-copilot/` | `.github/skills-copilot/` | ❌ Instructions-based |

## Commands

### `init`

Initialize workflows and skills for your project:

```bash
npx @metasession/workflows init
npx @metasession/workflows init --ide windsurf
npx @metasession/workflows init --workflows-only
npx @metasession/workflows init --skills-only
```

### `add`

Add specific workflow(s):

```bash
npx @metasession/workflows add code-review
npx @metasession/workflows add                    # interactive selection
npx @metasession/workflows add --all              # all workflows
npx @metasession/workflows add code-review --ide cursor
```

### `add-skill`

Add specific skill(s):

```bash
npx @metasession/workflows add-skill create-feature
npx @metasession/workflows add-skill                        # interactive selection
npx @metasession/workflows add-skill --all                  # all skills
npx @metasession/workflows add-skill create-feature --with-deps  # include sub-skills
```

### `list`

List all available workflows and skills:

```bash
npx @metasession/workflows list
npx @metasession/workflows list --workflows-only
npx @metasession/workflows list --skills-only
npx @metasession/workflows list --search "api"
npx @metasession/workflows list --category "Development"
```

### `list-skills`

List available skills with time-saved estimates:

```bash
npx @metasession/workflows list-skills
npx @metasession/workflows list-skills --category "Core Scaffolding"
npx @metasession/workflows list-skills --search "database"
```

### `skill-tree`

Show the dependency tree for a composable skill:

```bash
npx @metasession/workflows skill-tree create-feature
```

### `remove`

Remove a workflow or skill:

```bash
npx @metasession/workflows remove code-review
npx @metasession/workflows remove create-feature --skill
```

### `info`

Get details about a workflow or skill (auto-detects type):

```bash
npx @metasession/workflows info code-review
npx @metasession/workflows info create-feature
```

### `detect`

Detect AI coding assistants in your project:

```bash
npx @metasession/workflows detect
```

## Available Workflows (24)

### 🎯 Ideation & Planning
- **`feature-request`** — Submit and validate feature requests
- **`technical-spike`** — Conduct time-boxed technical investigations
- **`architecture-decision`** — Create Architecture Decision Records (ADRs)

### 📋 PRD & Design
- **`create-prd`** — Create comprehensive Product Requirements Documents
- **`api-design`** — Design RESTful APIs with security and compliance

### 💻 Development
- **`create-github-issue`** — Create well-structured GitHub issues
- **`work-on-github-issue`** — Full workflow from issue to PR
- **`address-pull-request-comments`** — Address code review feedback
- **`code-review`** — Conduct thorough code reviews
- **`refactoring`** — Safely refactor code with proper testing

### 🧪 Testing
- **`write-unit-tests`** — Write comprehensive unit tests
- **`e2e-testing`** — Write end-to-end tests with Playwright

### 🚀 Deployment
- **`deploy-staging`** — Deploy to staging environment
- **`deploy-production`** — Deploy to production with approvals
- **`rollback`** — Execute emergency rollback procedures
- **`hotfix`** — Deploy emergency hotfixes

### 🔒 Compliance & Security
- **`security-review`** — Conduct OWASP-based security reviews
- **`gdpr-compliance`** — Ensure GDPR/NDPA compliance
- **`accessibility-audit`** — Conduct WCAG 2.1 AA accessibility audits

### 🛠️ Support & Operations
- **`bug-triage`** — Triage and prioritize bug reports
- **`incident-response`** — Respond to production incidents

### 📝 Documentation
- **`update-docs`** — Update documentation for code changes
- **`changelog`** — Generate and maintain changelog entries
- **`release-notes`** — Create user-friendly release notes

## Available Skills (15)

### ⚡ Core Scaffolding
| Skill | Time Saved | Description |
|-------|-----------|-------------|
| **`create-feature`** ◆ | 4-8 hours | Full-stack feature: page + API + service + hook + component + tests |
| **`create-api-route`** | 30-60 min | Next.js App Router API route with auth, validation, audit logging |
| **`create-service`** | 30-60 min | Service layer with Supabase, pagination, soft-delete, error handling |
| **`create-component`** | 20-40 min | React component with shadcn/ui, accessibility, responsive design |
| **`create-hook`** | 20-30 min | TanStack Query hook with cache management, mutations, toast notifications |
| **`create-zod-schema`** | 15-20 min | Validation schema with type inference, custom errors, reusable validators |

### 🧪 Testing
| Skill | Time Saved | Description |
|-------|-----------|-------------|
| **`create-bdd-test`** | 1-2 hours | Cucumber feature files + Playwright step definitions |

### 🏗️ Domain-Specific
| Skill | Time Saved | Description |
|-------|-----------|-------------|
| **`create-email-template`** | 30-60 min | Resend email with HTML/text, branding, dynamic content |
| **`create-ai-feature`** | 1-2 hours | OpenAI integration with streaming, structured output, error handling |
| **`create-approval-workflow`** | 2-4 hours | Multi-step approval with state machine, RBAC, notifications |
| **`create-dashboard-page`** | 1-2 hours | Admin page with stats cards, Recharts, data tables, loading states |

### 🔐 Database & Security
| Skill | Time Saved | Description |
|-------|-----------|-------------|
| **`create-supabase-migration`** | 30-60 min | Migration + rollback + RLS + indexes + audit triggers |
| **`create-rbac-policy`** | 1-2 hours | Role-based access: RLS policies + API middleware + UI guards |

### 🚀 Optimization
| Skill | Time Saved | Description |
|-------|-----------|-------------|
| **`performance-optimize`** | 2-4 hours | React/Next.js audit: bundle, rendering, Core Web Vitals, caching |
| **`database-query-optimize`** | 1-3 hours | Supabase/PostgreSQL: N+1, indexes, RLS perf, query plans |

> ◆ = orchestrates sub-skills (use `--with-deps` to install all)

## Usage in Your IDE

**Workflows** — type the slash command:

```
/code-review
/create-github-issue
/deploy-production
```

**Skills** — reference by name in your prompt:

```
"Use the create-feature skill to build a new assessments feature"
"Use create-api-route to add a PATCH endpoint for interviews"
"Run performance-optimize on the requisitions page"
```

**Cursor:** Reference workflows/skills in your prompts or add to `.cursorrules`.

**VS Code + Copilot:** Reference in Copilot Chat or add to `.github/copilot-instructions.md`.

## Programmatic Usage

```typescript
import {
  // Workflows
  getAllWorkflows,
  getWorkflow,
  searchWorkflows,
  installWorkflow,
  installAllWorkflows,
  // Skills
  getAllSkills,
  getSkill,
  searchSkills,
  getSkillDependencyTree,
  installSkill,
  installAllSkills,
  installSkillWithDependencies,
  // IDE
  detectIDEs,
  getIDEConfig,
} from '@metasession/workflows';

// List all workflows and skills
const workflows = getAllWorkflows();   // 24 workflows
const skills = getAllSkills();         // 15 skills

// Detect IDEs in a project
const detected = await detectIDEs('/path/to/project');

// Install a workflow
await installWorkflow('/path/to/project', 'code-review', 'windsurf');

// Install a skill
await installSkill('/path/to/project', 'create-feature', 'windsurf');

// Install a skill with all its sub-skills
await installSkillWithDependencies('/path/to/project', 'create-feature', 'windsurf');

// View skill dependency tree
const tree = getSkillDependencyTree('create-feature');
// → [create-feature, create-zod-schema, create-service, create-api-route, ...]
```

## Contributing

1. Fork the repository
2. Add workflows to `workflows/` or skills to `skills/`
3. Update `src/registry.ts` (workflows) or `src/skill-registry.ts` (skills)
4. Submit a PR

### Adding a Skill

Skills use YAML frontmatter + markdown:

```markdown
---
description: Brief description for when to use this skill
---

# Skill Name

Steps, templates, checklists, and best practices...
```

## License

MIT