@frontmcp/skills 0.0.1

package/catalog/development/create-workflow/SKILL.md

@@ -0,0 +1,709 @@
+---
+name: create-workflow
+description: Create multi-step workflows that connect jobs into managed execution pipelines with dependencies and conditions. Use when orchestrating sequential or parallel job execution.
+tags: [workflow, pipeline, orchestration, steps, jobs]
+priority: 6
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/servers/workflows
+---
+
+# Creating Workflows
+
+Workflows connect multiple jobs into managed execution pipelines with step dependencies, conditions, and triggers. A workflow defines a directed acyclic graph (DAG) of steps where each step runs a named job, and the framework handles ordering, parallelism, error propagation, and trigger management.
+
+## When to Use @Workflow
+
+Use `@Workflow` when you need to orchestrate multiple jobs in a defined order with dependencies between them. Examples include:
+
+- CI/CD pipelines (build, test, deploy)
+- Data processing pipelines (extract, transform, load, verify)
+- Approval workflows (submit, review, approve, execute)
+- Multi-stage provisioning (create resources, configure, validate, notify)
+
+If you only need a single background task, use a `@Job` instead. If you need real-time sequential tool calls guided by an AI, use a `@Skill`.
+
+## Class-Based Pattern
+
+Create a class decorated with `@Workflow`. The decorator requires `name` and `steps` (at least one step).
+
+### WorkflowMetadata Fields
+
+| Field            | Type                               | Required    | Default           | Description                                           |
+| ---------------- | ---------------------------------- | ----------- | ----------------- | ----------------------------------------------------- |
+| `name`           | `string`                           | Yes         | --                | Unique workflow name                                  |
+| `steps`          | `WorkflowStep[]`                   | Yes (min 1) | --                | Array of step definitions                             |
+| `description`    | `string`                           | No          | --                | Human-readable description                            |
+| `trigger`        | `'manual' \| 'webhook' \| 'event'` | No          | `'manual'`        | How the workflow is initiated                         |
+| `webhook`        | `WebhookConfig`                    | No          | --                | Webhook configuration (when trigger is `'webhook'`)   |
+| `timeout`        | `number`                           | No          | `600000` (10 min) | Maximum total workflow execution time in milliseconds |
+| `maxConcurrency` | `number`                           | No          | `5`               | Maximum number of steps running in parallel           |
+| `permissions`    | `WorkflowPermissions`              | No          | --                | Access control configuration                          |
+
+### WorkflowStep Fields
+
+| Field             | Type                                       | Required | Description                                                                 |
+| ----------------- | ------------------------------------------ | -------- | --------------------------------------------------------------------------- |
+| `id`              | `string`                                   | Yes      | Unique step identifier within the workflow                                  |
+| `jobName`         | `string`                                   | Yes      | Name of the registered job to run                                           |
+| `input`           | `object \| (steps: StepResults) => object` | No       | Static input object or function that receives previous step results         |
+| `dependsOn`       | `string[]`                                 | No       | Array of step IDs that must complete before this step runs                  |
+| `condition`       | `(steps: StepResults) => boolean`          | No       | Predicate that determines if the step should run                            |
+| `continueOnError` | `boolean`                                  | No       | If `true`, workflow continues even if this step fails                       |
+| `timeout`         | `number`                                   | No       | Per-step timeout in milliseconds (overrides workflow timeout for this step) |
+| `retry`           | `RetryPolicy`                              | No       | Per-step retry policy (overrides the job's retry policy for this step)      |
+
+### Basic Example
+
+```typescript
+import { Workflow } from '@frontmcp/sdk';
+
+@Workflow({
+  name: 'deploy-pipeline',
+  description: 'Build, test, and deploy a service',
+  steps: [
+    {
+      id: 'build',
+      jobName: 'build-project',
+      input: { target: 'production', optimize: true },
+    },
+    {
+      id: 'test',
+      jobName: 'run-tests',
+      input: { suite: 'all', coverage: true },
+      dependsOn: ['build'],
+    },
+    {
+      id: 'deploy',
+      jobName: 'deploy-to-env',
+      input: (steps) => ({
+        artifact: steps.get('build').outputs.artifactUrl,
+        environment: 'production',
+      }),
+      dependsOn: ['test'],
+    },
+  ],
+})
+class DeployPipeline {}
+```
+
+## Step Dependencies and DAG Execution
+
+Steps form a directed acyclic graph (DAG) based on their `dependsOn` declarations. The framework:
+
+1. Identifies steps with no dependencies and runs them in parallel (up to `maxConcurrency`)
+2. As each step completes, checks which dependent steps have all their dependencies satisfied
+3. Runs newly unblocked steps in parallel
+4. Continues until all steps complete or a step fails (unless `continueOnError` is set)
+
+### Parallel Steps
+
+Steps without mutual dependencies run concurrently:
+
+```typescript
+@Workflow({
+  name: 'data-validation-pipeline',
+  description: 'Validate data from multiple sources in parallel, then merge',
+  maxConcurrency: 3,
+  steps: [
+    // These three steps have no dependencies -- they run in parallel
+    {
+      id: 'validate-users',
+      jobName: 'validate-dataset',
+      input: { dataset: 'users', rules: ['no-nulls', 'email-format'] },
+    },
+    {
+      id: 'validate-orders',
+      jobName: 'validate-dataset',
+      input: { dataset: 'orders', rules: ['no-nulls', 'positive-amounts'] },
+    },
+    {
+      id: 'validate-products',
+      jobName: 'validate-dataset',
+      input: { dataset: 'products', rules: ['no-nulls', 'unique-sku'] },
+    },
+    // This step depends on all three -- runs after all complete
+    {
+      id: 'merge-results',
+      jobName: 'merge-validations',
+      dependsOn: ['validate-users', 'validate-orders', 'validate-products'],
+      input: (steps) => ({
+        userReport: steps.get('validate-users').outputs,
+        orderReport: steps.get('validate-orders').outputs,
+        productReport: steps.get('validate-products').outputs,
+      }),
+    },
+  ],
+})
+class DataValidationPipeline {}
+```
+
+### Diamond Dependencies
+
+Steps can share dependencies, forming diamond patterns:
+
+```typescript
+@Workflow({
+  name: 'build-and-publish',
+  description: 'Build artifacts and publish to multiple registries',
+  steps: [
+    { id: 'compile', jobName: 'compile-source', input: { target: 'es2022' } },
+    {
+      id: 'publish-npm',
+      jobName: 'publish-to-registry',
+      dependsOn: ['compile'],
+      input: (steps) => ({ artifact: steps.get('compile').outputs.bundlePath, registry: 'npm' }),
+    },
+    {
+      id: 'publish-docker',
+      jobName: 'publish-to-registry',
+      dependsOn: ['compile'],
+      input: (steps) => ({ artifact: steps.get('compile').outputs.bundlePath, registry: 'docker' }),
+    },
+    {
+      id: 'notify',
+      jobName: 'send-notification',
+      dependsOn: ['publish-npm', 'publish-docker'],
+      input: (steps) => ({
+        message: `Published to npm (${steps.get('publish-npm').outputs.version}) and Docker (${steps.get('publish-docker').outputs.tag})`,
+      }),
+    },
+  ],
+})
+class BuildAndPublish {}
+```
+
+## Dynamic Input from Previous Steps
+
+Use a function for `input` to pass data from completed steps. The function receives a `StepResults` map where each entry contains the step's state and outputs.
+
+```typescript
+{
+  id: 'transform',
+  jobName: 'transform-data',
+  dependsOn: ['extract'],
+  input: (steps) => ({
+    data: steps.get('extract').outputs.records,
+    schema: steps.get('extract').outputs.schema,
+    rowCount: steps.get('extract').outputs.count,
+  }),
+}
+```
+
+The `steps.get(stepId)` method returns a step result object:
+
+```typescript
+interface StepResult {
+  state: 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+  outputs: Record<string, unknown>; // job output from the completed step
+  error?: string; // error message if the step failed
+  startedAt?: string;
+  completedAt?: string;
+}
+```
+
+## Conditional Steps
+
+Use `condition` to conditionally run a step based on the results of previous steps. The condition receives the same `StepResults` map.
+
+```typescript
+@Workflow({
+  name: 'conditional-deploy',
+  description: 'Deploy only if tests pass and coverage meets threshold',
+  steps: [
+    {
+      id: 'test',
+      jobName: 'run-tests',
+      input: { suite: 'all', coverage: true },
+    },
+    {
+      id: 'deploy',
+      jobName: 'deploy-to-env',
+      dependsOn: ['test'],
+      condition: (steps) => {
+        const testResult = steps.get('test');
+        return testResult.state === 'completed' && testResult.outputs.coverage >= 95;
+      },
+      input: (steps) => ({
+        artifact: steps.get('test').outputs.buildPath,
+        environment: 'staging',
+      }),
+    },
+    {
+      id: 'notify-failure',
+      jobName: 'send-notification',
+      dependsOn: ['test'],
+      condition: (steps) => steps.get('test').state === 'failed',
+      input: { channel: '#alerts', message: 'Test suite failed -- deployment blocked' },
+    },
+  ],
+})
+class ConditionalDeploy {}
+```
+
+When a `condition` returns `false`, the step is marked as `skipped`. Downstream steps that depend on a skipped step check their own conditions with the skipped step's state.
+
+## Error Handling with continueOnError
+
+By default, a failed step stops the entire workflow. Set `continueOnError: true` on a step to allow the workflow to proceed even if that step fails.
+
+```typescript
+@Workflow({
+  name: 'resilient-pipeline',
+  description: 'Pipeline that continues past non-critical failures',
+  steps: [
+    {
+      id: 'extract',
+      jobName: 'extract-data',
+      input: { source: 'primary-db' },
+    },
+    {
+      id: 'enrich',
+      jobName: 'enrich-data',
+      dependsOn: ['extract'],
+      continueOnError: true, // enrichment is optional
+      input: (steps) => ({ data: steps.get('extract').outputs.records }),
+    },
+    {
+      id: 'load',
+      jobName: 'load-data',
+      dependsOn: ['extract', 'enrich'],
+      input: (steps) => {
+        const enrichResult = steps.get('enrich');
+        // Use enriched data if available, fall back to raw
+        const data =
+          enrichResult.state === 'completed'
+            ? enrichResult.outputs.enrichedRecords
+            : steps.get('extract').outputs.records;
+        return { data, destination: 'warehouse' };
+      },
+    },
+  ],
+})
+class ResilientPipeline {}
+```
+
+## Workflow Triggers
+
+### Manual (Default)
+
+The workflow is started by an explicit API call or MCP request:
+
+```typescript
+@Workflow({
+  name: 'manual-deploy',
+  description: 'Manually triggered deployment',
+  trigger: 'manual',
+  steps: [
+    /* ... */
+  ],
+})
+class ManualDeploy {}
+```
+
+### Webhook
+
+The workflow is triggered by an incoming HTTP request. Configure the webhook path, secret, and allowed HTTP methods.
+
+```typescript
+@Workflow({
+  name: 'github-deploy',
+  description: 'Deploy on GitHub push events',
+  trigger: 'webhook',
+  webhook: {
+    path: '/webhooks/github-deploy',
+    secret: process.env.WEBHOOK_SECRET,
+    methods: ['POST'],
+  },
+  steps: [
+    {
+      id: 'build',
+      jobName: 'build-project',
+      input: { branch: 'main' },
+    },
+    {
+      id: 'deploy',
+      jobName: 'deploy-to-env',
+      dependsOn: ['build'],
+      input: (steps) => ({
+        artifact: steps.get('build').outputs.artifactUrl,
+        environment: 'production',
+      }),
+    },
+  ],
+})
+class GithubDeploy {}
+```
+
+#### WebhookConfig Fields
+
+| Field     | Type       | Default                           | Description                                    |
+| --------- | ---------- | --------------------------------- | ---------------------------------------------- |
+| `path`    | `string`   | Auto-generated from workflow name | HTTP path for the webhook endpoint             |
+| `secret`  | `string`   | --                                | Shared secret for webhook signature validation |
+| `methods` | `string[]` | `['POST']`                        | Allowed HTTP methods                           |
+
+### Event
+
+The workflow is triggered by an internal event emitted by the application:
+
+```typescript
+@Workflow({
+  name: 'on-user-signup',
+  description: 'Workflow triggered when a new user signs up',
+  trigger: 'event',
+  steps: [
+    {
+      id: 'create-profile',
+      jobName: 'create-user-profile',
+      input: { template: 'default' },
+    },
+    {
+      id: 'send-welcome',
+      jobName: 'send-email',
+      dependsOn: ['create-profile'],
+      input: (steps) => ({
+        to: steps.get('create-profile').outputs.email,
+        template: 'welcome',
+      }),
+    },
+    {
+      id: 'setup-defaults',
+      jobName: 'setup-user-defaults',
+      dependsOn: ['create-profile'],
+      input: (steps) => ({
+        userId: steps.get('create-profile').outputs.userId,
+      }),
+    },
+  ],
+})
+class OnUserSignup {}
+```
+
+## Function Builder
+
+For workflows that do not need a class, use the `workflow()` function builder:
+
+```typescript
+import { workflow } from '@frontmcp/sdk';
+
+const QuickDeploy = workflow({
+  name: 'quick-deploy',
+  description: 'Simplified deployment workflow',
+  steps: [
+    {
+      id: 'build',
+      jobName: 'build-project',
+      input: { target: 'production' },
+    },
+    {
+      id: 'deploy',
+      jobName: 'deploy-to-env',
+      dependsOn: ['build'],
+      input: (steps) => ({
+        artifact: steps.get('build').outputs.artifactUrl,
+        environment: 'staging',
+      }),
+    },
+  ],
+});
+```
+
+Register it the same way as a class workflow: `workflows: [QuickDeploy]`.
+
+## Registration
+
+Add workflow classes (or function-style workflows) to the `workflows` array in `@App`. Workflows require jobs to be enabled since each step runs a named job.
+
+```typescript
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'pipeline-app',
+  jobs: [BuildProjectJob, RunTestsJob, DeployToEnvJob, SendNotificationJob],
+  workflows: [DeployPipeline, DataValidationPipeline, QuickDeploy],
+})
+class PipelineApp {}
+
+@FrontMcp({
+  info: { name: 'pipeline-server', version: '1.0.0' },
+  apps: [PipelineApp],
+  jobs: {
+    enabled: true,
+    store: {
+      redis: {
+        provider: 'redis',
+        host: 'localhost',
+        port: 6379,
+        keyPrefix: 'mcp:jobs:',
+      },
+    },
+  },
+})
+class PipelineServer {}
+```
+
+## Nx Generator
+
+Scaffold a new workflow using the Nx generator:
+
+```bash
+nx generate @frontmcp/nx:workflow
+```
+
+This creates the workflow file, spec file, and updates barrel exports.
+
+## Complete Example: CI/CD Pipeline
+
+```typescript
+import { Workflow, Job, JobContext, FrontMcp, App, workflow } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// --- Jobs ---
+
+@Job({
+  name: 'checkout-code',
+  description: 'Checkout code from repository',
+  inputSchema: {
+    repo: z.string().describe('Repository URL'),
+    branch: z.string().default('main'),
+  },
+  outputSchema: {
+    workDir: z.string(),
+    commitSha: z.string(),
+  },
+})
+class CheckoutCodeJob extends JobContext {
+  async execute(input: { repo: string; branch: string }) {
+    this.log(`Checking out ${input.repo}@${input.branch}`);
+    return { workDir: '/tmp/build/workspace', commitSha: 'abc123' };
+  }
+}
+
+@Job({
+  name: 'run-linter',
+  description: 'Run linter on codebase',
+  inputSchema: {
+    workDir: z.string(),
+  },
+  outputSchema: {
+    passed: z.boolean(),
+    issues: z.number().int(),
+  },
+})
+class RunLinterJob extends JobContext {
+  async execute(input: { workDir: string }) {
+    this.log(`Linting ${input.workDir}`);
+    return { passed: true, issues: 0 };
+  }
+}
+
+@Job({
+  name: 'run-unit-tests',
+  description: 'Run unit test suite',
+  inputSchema: {
+    workDir: z.string(),
+    coverage: z.boolean().default(true),
+  },
+  outputSchema: {
+    passed: z.boolean(),
+    testCount: z.number().int(),
+    coverage: z.number(),
+  },
+  retry: { maxAttempts: 2, backoffMs: 3000, backoffMultiplier: 1, maxBackoffMs: 3000 },
+})
+class RunUnitTestsJob extends JobContext {
+  async execute(input: { workDir: string; coverage: boolean }) {
+    this.log(`Running unit tests in ${input.workDir}`);
+    this.progress(50, 100, 'Tests running');
+    return { passed: true, testCount: 342, coverage: 96.4 };
+  }
+}
+
+@Job({
+  name: 'build-artifact',
+  description: 'Build production artifact',
+  inputSchema: {
+    workDir: z.string(),
+    commitSha: z.string(),
+  },
+  outputSchema: {
+    artifactUrl: z.string().url(),
+    size: z.number().int(),
+  },
+  timeout: 180000,
+})
+class BuildArtifactJob extends JobContext {
+  async execute(input: { workDir: string; commitSha: string }) {
+    this.log(`Building artifact from ${input.commitSha}`);
+    this.progress(0, 100, 'Compiling');
+    this.progress(100, 100, 'Build complete');
+    return {
+      artifactUrl: `https://artifacts.example.com/builds/${input.commitSha}.tar.gz`,
+      size: 52428800,
+    };
+  }
+}
+
+@Job({
+  name: 'deploy-artifact',
+  description: 'Deploy artifact to target environment',
+  inputSchema: {
+    artifactUrl: z.string().url(),
+    environment: z.string(),
+  },
+  outputSchema: {
+    deploymentId: z.string(),
+    url: z.string().url(),
+  },
+  retry: { maxAttempts: 3, backoffMs: 5000, backoffMultiplier: 2, maxBackoffMs: 30000 },
+  permissions: {
+    actions: ['execute'],
+    roles: ['admin', 'deployer'],
+    scopes: ['deploy:write'],
+  },
+})
+class DeployArtifactJob extends JobContext {
+  async execute(input: { artifactUrl: string; environment: string }) {
+    this.log(`Deploying ${input.artifactUrl} to ${input.environment}`);
+    return {
+      deploymentId: 'deploy-001',
+      url: `https://${input.environment}.example.com`,
+    };
+  }
+}
+
+@Job({
+  name: 'notify-team',
+  description: 'Send notification to the team',
+  inputSchema: {
+    channel: z.string(),
+    message: z.string(),
+  },
+  outputSchema: {
+    sent: z.boolean(),
+  },
+})
+class NotifyTeamJob extends JobContext {
+  async execute(input: { channel: string; message: string }) {
+    this.log(`Notifying ${input.channel}: ${input.message}`);
+    return { sent: true };
+  }
+}
+
+// --- Workflow ---
+
+@Workflow({
+  name: 'ci-cd-pipeline',
+  description: 'Full CI/CD pipeline: checkout, lint, test, build, deploy, notify',
+  trigger: 'webhook',
+  webhook: {
+    path: '/webhooks/ci-cd',
+    secret: process.env.CI_WEBHOOK_SECRET,
+    methods: ['POST'],
+  },
+  timeout: 900000, // 15 minutes
+  maxConcurrency: 3,
+  permissions: {
+    actions: ['create', 'read', 'execute', 'list'],
+    roles: ['admin', 'ci-bot'],
+  },
+  steps: [
+    {
+      id: 'checkout',
+      jobName: 'checkout-code',
+      input: { repo: 'https://github.com/org/repo.git', branch: 'main' },
+    },
+    {
+      id: 'lint',
+      jobName: 'run-linter',
+      dependsOn: ['checkout'],
+      input: (steps) => ({
+        workDir: steps.get('checkout').outputs.workDir,
+      }),
+    },
+    {
+      id: 'test',
+      jobName: 'run-unit-tests',
+      dependsOn: ['checkout'],
+      input: (steps) => ({
+        workDir: steps.get('checkout').outputs.workDir,
+        coverage: true,
+      }),
+    },
+    {
+      id: 'build',
+      jobName: 'build-artifact',
+      dependsOn: ['lint', 'test'],
+      condition: (steps) =>
+        steps.get('lint').state === 'completed' &&
+        steps.get('lint').outputs.passed === true &&
+        steps.get('test').state === 'completed' &&
+        steps.get('test').outputs.passed === true &&
+        steps.get('test').outputs.coverage >= 95,
+      input: (steps) => ({
+        workDir: steps.get('checkout').outputs.workDir,
+        commitSha: steps.get('checkout').outputs.commitSha,
+      }),
+    },
+    {
+      id: 'deploy',
+      jobName: 'deploy-artifact',
+      dependsOn: ['build'],
+      condition: (steps) => steps.get('build').state === 'completed',
+      input: (steps) => ({
+        artifactUrl: steps.get('build').outputs.artifactUrl,
+        environment: 'staging',
+      }),
+    },
+    {
+      id: 'notify-success',
+      jobName: 'notify-team',
+      dependsOn: ['deploy'],
+      condition: (steps) => steps.get('deploy').state === 'completed',
+      input: (steps) => ({
+        channel: '#deployments',
+        message: `Deployed ${steps.get('deploy').outputs.deploymentId} to ${steps.get('deploy').outputs.url}`,
+      }),
+    },
+    {
+      id: 'notify-failure',
+      jobName: 'notify-team',
+      dependsOn: ['lint', 'test'],
+      condition: (steps) => steps.get('lint').state === 'failed' || steps.get('test').state === 'failed',
+      input: {
+        channel: '#alerts',
+        message: 'CI pipeline failed -- check lint and test results',
+      },
+    },
+  ],
+})
+class CiCdPipeline {}
+
+// --- Registration ---
+
+@App({
+  name: 'ci-app',
+  jobs: [CheckoutCodeJob, RunLinterJob, RunUnitTestsJob, BuildArtifactJob, DeployArtifactJob, NotifyTeamJob],
+  workflows: [CiCdPipeline],
+})
+class CiApp {}
+
+@FrontMcp({
+  info: { name: 'ci-server', version: '1.0.0' },
+  apps: [CiApp],
+  jobs: {
+    enabled: true,
+    store: {
+      redis: {
+        provider: 'redis',
+        host: 'localhost',
+        port: 6379,
+        keyPrefix: 'mcp:ci:',
+      },
+    },
+  },
+})
+class CiServer {}
+```