@keystrokehq/skills 0.0.1

package/keystroke-trigger-authoring/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: keystroke-trigger-authoring
+description: Build Keystroke cron, webhook, polling, and provider triggers with @keystrokehq/core. Use when the user wants to author, test, or explain trigger code, including webhook verification, polling schedules, filter and idempotency callbacks, and mapping trigger input into workflows or task-driven agent runs.
+---
+
+# Keystroke Trigger Authoring
+
+Use this skill when an agent needs to write or change Keystroke trigger code.
+
+Keep this skill focused on authored trigger code:
+- use `../keystroke-workflow-authoring/SKILL.md` for workflow structure
+- use `../keystroke-task-authoring/SKILL.md` for task authoring
+- use `../keystroke-credential-binding/SKILL.md` when the trigger needs credentials
+- use `../keystroke-agent-authoring/SKILL.md` for messaging gateways and conversational agent entry
+
+## Quick start
+
+### Workflow trigger
+
+```ts
+import { webhookTrigger, Workflow } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const paymentWebhook = webhookTrigger({
+  name: 'Payment Webhook',
+  description: 'Receives payment events from an external provider.',
+  source: {
+    type: 'custom',
+    method: 'POST',
+    path: '/payments',
+  },
+  payload: z.object({
+    id: z.string(),
+    type: z.string(),
+    data: z.object({
+      amount: z.number(),
+    }),
+  }),
+  filter: (payload) => payload.type === 'payment.completed',
+  idempotencyKey: (payload) => payload.id,
+});
+```
+
+Attach the trigger to a workflow via the `triggers` array. Call the trigger as a function to bind a `transform`:
+
+```ts
+export const paymentWorkflow = new Workflow({
+  id: 'payment-workflow',
+  name: 'Payment Workflow',
+  input: z.object({ eventId: z.string(), amount: z.number() }),
+  output: z.object({ ok: z.boolean() }),
+  triggers: [
+    paymentWebhook({
+      transform: (payload) => ({
+        eventId: payload.id,
+        amount: payload.data.amount,
+      }),
+    }),
+  ],
+  run: async (input) => ({ ok: true }),
+});
+```
+
+### Task trigger
+
+```ts
+import { cronTrigger, Task } from '@keystrokehq/core';
+import { z } from 'zod';
+import { reminderAgent } from './reminder.agent';
+
+const dailyReminderTrigger = cronTrigger({
+  name: 'Daily Reminder Trigger',
+  description: 'Runs every morning.',
+  input: z.object({
+    mode: z.literal('daily'),
+  }),
+  payload: {
+    mode: 'daily',
+  },
+  schedule: '0 9 * * *',
+});
+
+export const dailyReminderTask = new Task({
+  id: 'daily-reminder-task',
+  name: 'Daily Reminder Task',
+  agent: reminderAgent,
+  prompt: 'Send the daily reminder for trigger {{trigger.name}}.',
+  triggers: [dailyReminderTrigger],
+});
+```
+
+## Authoring model
+
+Teach this mental model clearly:
+- a trigger defines how external input enters a workflow or task
+- triggers are authored separately from workflows, tasks, and agents
+- workflow triggers are listed in `Workflow({ triggers: [...] })`
+- a bare trigger in the array means the trigger payload passes through directly as workflow input
+- calling the trigger as a function with `{ transform }` creates a bound trigger for payload-to-input mapping
+- task triggers are listed inline in `Task.triggers`
+- a `MessagingGateway` is not a trigger
+
+## Trigger types
+
+Teach these public trigger factory functions from `@keystrokehq/core`:
+- `cronTrigger`
+- `webhookTrigger`
+- `pollingTrigger`
+- `providerTrigger`
+
+Default to cron, webhook, and polling first. Use provider triggers when the user specifically needs provider-event authoring.
+
+The factories return a `CallableTrigger` — an object with trigger properties (`.name`, `.toManifest()`, etc.) that is also callable as a function to create a bound trigger with optional `transform` and `filter`. Webhook and polling triggers also expose `.filter` and `.idempotencyKey` callbacks; cron triggers do not.
+
+## Manual API Execution
+
+Even without a trigger, every workflow and agent can be executed on-demand via the Keystroke API.
+
+### Executing a Workflow
+Users can explicitly start a workflow run without needing a cron or webhook trigger.
+- **Endpoint**: `POST /api/v1/workflows/execute`
+- **Body requirements**: Needs `projectId`, `authoredWorkflowId`, and the input payload in an `args` array. May optionally include `workflowGlobals` and `credentialBindings`.
+
+### Executing an Agent Conversation
+Users can start a new agent conversation directly.
+- **Endpoint**: `POST /api/v1/agents/[agentId]/conversations`
+- **Body requirements**: Needs a `title`.
+- **Response**: Returns the `conversationId` for subsequent interactions.
+
+## Workflow triggers
+
+Use workflow triggers when:
+- a schedule should start a workflow
+- a webhook should resolve into workflow input
+- polling should feed workflow input
+- the automation needs durable orchestration after the trigger fires
+
+Workflow trigger rules:
+- define the trigger in `*.trigger.ts`
+- list it in `Workflow({ triggers: [...] })`
+- for a bare trigger (no transform), place it directly: `triggers: [myTrigger]`
+- for a bound trigger with transform, call it: `triggers: [myTrigger({ transform: (payload) => ({...}) })]`
+- test the mapping by creating a bound trigger and calling `bound.transform?.(payload)`
+
+## Task triggers
+
+Use task triggers when:
+- the real job is "trigger -> prompt -> agent run"
+- the user does not need a full workflow orchestration layer
+
+Task trigger rules:
+- define the trigger normally
+- list it in `Task.triggers`
+- send users to the task skill for prompt and lifecycle details
+
+## Trigger rules
+
+- Keep each exported trigger in its own `*.trigger.ts` file.
+- Use `verify` for authenticity or admission checks (webhook triggers only).
+- Use `filter` for event gating (webhook and polling triggers only — cron triggers do not support `filter`).
+- Use `idempotencyKey` for deduplication or stable identity (webhook and polling triggers only — cron triggers do not support `idempotencyKey`).
+- `filter` and `idempotencyKey` receive the typed parsed payload as the first argument. Only `verify` receives credentials.
+- For webhook providers, verify against the raw request data the runtime gives you.
+- Keep the webhook path rooted with `/` and provide only the suffix that follows the organization id in the URL — e.g. `path: '/payments'` is served at `/api/v1/webhooks/{orgId}/payments`. Do **not** include the `/webhooks/` prefix; the router supplies it.
+
+## Agent Guidelines for Custom Triggers
+
+When an agent needs to write custom triggers, it must follow these rules:
+1. **Always use prebuilt triggers** if they exist before writing custom ones.
+2. **Collect context first**: Do you have all the information you need from the user to build the trigger? If not, ask the user to clarify what they are looking for. **Do Not Guess**.
+3. **Understand API payloads**: If the trigger handles webhooks or fetches from an API endpoint, search the provider's docs to understand the payloads. If possible, hit available endpoints to inspect the actual payloads.
+4. **Always write and run tests**: You must always write tests for custom triggers that handle non-trivial logic in callbacks. Always run the tests to verify that the new triggers run (see `references/testing.md`).
+5. **Handle missing credentials**: If you cannot run tests because of missing credentials, ask the user to configure them following the `../keystroke-credential-binding/SKILL.md` skill. The user will need to upload credentials before deploying anyway.
+
+## Testing path
+
+Default trigger testing guidance:
+- test trigger-specific callbacks such as `verify`, `filter`, or `poll` directly on the trigger
+- test webhook parsing with `trigger.payload.parse(JSON.parse(request.rawBody))`
+- test polling validation with `trigger.parseResponse(response)`
+- test workflow input mapping by creating a bound trigger and calling `bound.transform?.(payload)`
+- keep broader workflow testing in the workflow skill
+
+## References
+
+Read these files as needed:
+- `references/source-map.md` for the public trigger surface
+- `references/patterns.md` for field-by-field examples, including provider triggers
+- `references/testing.md` for trigger and bound trigger tests

package/keystroke-trigger-authoring/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill_name": "keystroke-trigger-authoring",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "How do I create a Keystroke webhook trigger for a Stripe event and map the incoming payload into my workflow input?",
+      "expected_output": "Explains webhookTrigger() factory setup, required and optional fields, and the bound trigger transform pattern via Workflow({ triggers: [trigger({ transform })] }).",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "I need a polling trigger that checks an external API every 15 minutes and only launches the workflow for new items. What should that look like?",
+      "expected_output": "Explains pollingTrigger() factory setup, schedule, poll/response, optional filter and idempotency behavior, and listing the trigger in Workflow({ triggers: [...] }) with optional transform binding.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "What is the right way to test a Keystroke trigger? I want to validate webhook verify/filter logic and the input transform into the workflow.",
+      "expected_output": "Points to trigger-specific callback tests (verify, filter, payload.parse) plus bound trigger transform testing via bound.transform?.(payload).",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I want a cron-driven agent job. Do I attach a trigger to the agent, attach it to a task, or something else?",
+      "expected_output": "Explains that workflow triggers are listed in Workflow({ triggers: [...] }), task triggers are listed inline on Task.triggers, and messaging gateways are not triggers.",
+      "files": []
+    }
+  ]
+}

package/keystroke-trigger-authoring/references/patterns.md

@@ -0,0 +1,265 @@
+# Trigger Examples
+
+Use these examples when the user wants concrete trigger patterns.
+
+Assume `digestWorkflow` and `paymentWorkflow` are `Workflow` instances whose `input` schemas match the trigger examples below.
+
+File layout reminder:
+
+- keep workflows in `*.workflow.ts` files
+- keep each exported trigger in its own `*.trigger.ts` file
+- keep any credential set used by a trigger in its own `*.credential-set.ts` file
+
+## Shared advanced fields
+
+```ts
+import type { ExecutionIdentityPolicy } from '@keystrokehq/core/types';
+
+const executionIdentityPolicy: ExecutionIdentityPolicy = {
+  subjectMode: 'requiredWhenUserProvidedCredential',
+};
+```
+
+Use `executionIdentityPolicy` when the trigger should require a subject only in specific credential cases. Use `modeDefault` when the trigger should default to a specific trigger mode such as `'subscribable'`.
+
+## `cronTrigger`
+
+```ts
+import { cronTrigger } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const nightlyDigestTrigger = cronTrigger({
+  name: 'Nightly Digest Trigger',
+  description: 'Runs every night.',
+  enabled: true,
+  modeDefault: 'subscribable',
+  executionIdentityPolicy,
+  input: z.object({
+    mode: z.literal('nightly'),
+  }),
+  payload: {
+    mode: 'nightly',
+  },
+  schedule: '0 0 * * *',
+  timezone: 'UTC',
+});
+```
+
+Use this when the workflow input can be defined as static payload on a schedule.
+
+A cron trigger can be placed bare in the `triggers` array when its payload matches the workflow input:
+
+```ts
+export const digestWorkflow = new Workflow({
+  id: 'digest',
+  name: 'Digest',
+  input: z.object({ mode: z.literal('nightly') }),
+  output: z.object({ ok: z.boolean() }),
+  triggers: [nightlyDigestTrigger],
+  run: async () => ({ ok: true }),
+});
+```
+
+## `webhookTrigger`
+
+```ts
+import { webhookTrigger } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const paymentWebhook = webhookTrigger({
+  name: 'Payment Webhook',
+  description: 'Handles payment events.',
+  enabled: true,
+  modeDefault: 'subscribable',
+  source: {
+    type: 'custom',
+    method: 'POST',
+    path: '/payments',
+    verify: async (request) => {
+      if (!request.headers['x-signature']) {
+        throw new Error('Missing signature header');
+      }
+    },
+    response: {
+      successStatus: 202,
+      successBody: {
+        accepted: true,
+      },
+    },
+  },
+  payload: z.object({
+    id: z.string(),
+    type: z.string(),
+    amount: z.number(),
+  }),
+  filter: (payload) => payload.type === 'payment.completed',
+  idempotencyKey: (payload) => payload.id,
+});
+```
+
+Use `request.rawBody` in `verify` when a provider expects raw request verification. To parse a webhook body, use `trigger.payload.parse(JSON.parse(request.rawBody))`.
+
+## Binding a webhook trigger to a workflow with `transform`
+
+When the webhook payload shape differs from the workflow input, call the trigger with a `transform`:
+
+```ts
+export const paymentWorkflow = new Workflow({
+  id: 'payment-workflow',
+  name: 'Payment Workflow',
+  input: z.object({ eventId: z.string(), amount: z.number() }),
+  output: z.object({ ok: z.boolean() }),
+  triggers: [
+    paymentWebhook({
+      transform: (payload) => ({
+        eventId: payload.id,
+        amount: payload.amount,
+      }),
+    }),
+  ],
+  run: async () => ({ ok: true }),
+});
+```
+
+## `pollingTrigger`
+
+```ts
+import { pollingTrigger } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const orderPolling = pollingTrigger({
+  name: 'Order Polling',
+  description: 'Polls for the newest order.',
+  enabled: true,
+  schedule: '*/15 * * * *',
+  response: z.object({
+    orderId: z.string(),
+    status: z.string(),
+  }),
+  poll: async (ctx) => {
+    const previousOrder = ctx.lastResponse?.orderId ?? 'none';
+
+    return {
+      orderId: previousOrder === 'none' ? 'order_123' : 'order_124',
+      status: 'created',
+    };
+  },
+  filter: (payload) => payload.status === 'created',
+  idempotencyKey: (payload) => payload.orderId,
+});
+```
+
+Use this when the workflow should be entered from periodic remote-state checks.
+
+## `pollingTrigger.parseResponse(...)`
+
+```ts
+const parsedResponse = orderPolling.parseResponse({
+  orderId: 'order_123',
+  status: 'created',
+});
+```
+
+Use `parseResponse(...)` when you want the trigger's response schema validation without running polling logic.
+
+## `providerTrigger`
+
+```ts
+import { providerTrigger } from '@keystrokehq/core';
+
+export const githubIssueTrigger = providerTrigger({
+  name: 'GitHub Issue Trigger',
+  description: 'Receives GitHub provider events for issue activity.',
+  provider: 'github',
+  eventTypes: ['issues.opened', 'issues.edited'],
+  filter: async (event) => event.type === 'issues.opened',
+  idempotencyKey: async (event) => event.id,
+});
+```
+
+Use a provider trigger when the user is authoring around normalized provider events instead of a raw webhook or polling loop.
+
+## Bare trigger in workflow (no transform)
+
+```ts
+triggers: [nightlyDigestTrigger]
+```
+
+Use this when the trigger payload already matches the workflow input. The trigger is placed directly in the array.
+
+## Bound trigger with `transform`
+
+```ts
+triggers: [
+  paymentWebhook({
+    transform: (payload) => ({
+      eventId: payload.id,
+      amount: payload.amount,
+    }),
+  }),
+]
+```
+
+Call the trigger as a function with `{ transform }` when the trigger payload and workflow input are different shapes. This returns a `BoundTrigger`.
+
+## Bound trigger with additional `filter`
+
+```ts
+triggers: [
+  paymentWebhook({
+    filter: (payload) => payload.amount > 100,
+    transform: (payload) => ({
+      eventId: payload.id,
+      amount: payload.amount,
+    }),
+  }),
+]
+```
+
+An additional filter on the binding composes with the trigger's own filter.
+
+## Task trigger note
+
+For task-driven agent runs, author the trigger normally and place it in `Task.triggers`.
+
+Use the task skill when the user needs prompt templating, task lifecycle, or focused task deploys.
+
+## Trigger credentials
+
+```ts
+import { CredentialSet, webhookTrigger } from '@keystrokehq/core';
+import { z } from 'zod';
+
+const signingCredentials = new CredentialSet({
+  id: 'webhookSigning',
+  auth: z.object({
+    secret: z.string(),
+  }),
+});
+
+const signedWebhook = webhookTrigger({
+  name: 'Signed Webhook',
+  description: 'Verifies a signed webhook.',
+  source: {
+    type: 'custom',
+    method: 'POST',
+    path: '/signed',
+    credentialSets: [signingCredentials],
+    verify: async (_request, ctx) => {
+      if (!ctx.credentials.webhookSigning.secret) {
+        throw new Error('Missing signing secret');
+      }
+    },
+  },
+  payload: z.object({
+    id: z.string(),
+  }),
+});
+```
+
+## `describe()` and `toManifest()`
+
+```ts
+const triggerSummary = paymentWebhook.describe();
+const triggerManifest = paymentWebhook.toManifest();
+```

package/keystroke-trigger-authoring/references/source-map.md

@@ -0,0 +1,128 @@
+# Trigger Feature Map
+
+Use only the public imports a user repo can rely on:
+
+```ts
+import {
+  cronTrigger,
+  pollingTrigger,
+  providerTrigger,
+  webhookTrigger,
+} from '@keystrokehq/core';
+import type {
+  BoundTrigger,
+  CallableTrigger,
+  ExecutionIdentityPolicy,
+  TriggerBindOptions,
+  TriggerEntry,
+  TriggerInstance,
+} from '@keystrokehq/core/types';
+```
+
+When a trigger explanation also needs to talk about workflow steps or agent tools, use the terminology from the other Keystroke skills:
+
+- `Step`, `Tool`, and `Operation` are aliases for the same `Operation` class
+- use the workflow skill for workflow-side operation guidance
+- use the agent skill for agent-side tool guidance
+
+## Common trigger fields
+
+- `name`
+- `description`
+- `enabled`
+- `credentialSets`
+- `executionIdentityPolicy`
+- `modeDefault`
+
+## Common trigger methods
+
+- `describe()`
+- `toManifest()`
+
+## `cronTrigger` fields
+
+- `input`
+- `payload`
+- `schedule`
+- `timezone`
+
+## `cronTrigger` instance properties
+
+- `.name`
+- `.payload`
+- `.schedule`
+- `.timezone`
+- `.toManifest()`
+- `.describe()`
+
+## `webhookTrigger` fields
+
+- `path`
+- `method`
+- `payload`
+- `verify`
+- `filter`
+- `idempotencyKey`
+- `response`
+
+## `webhookTrigger` instance methods
+
+- `.payload.parse(data)` — validate parsed body against the payload schema
+- `.verify?(request, ctx)` — raw request + credentials for authenticity checks
+- `.filter?(payload, request?)` — typed parsed body, optional raw request (no credentials)
+- `.idempotencyKey?(payload, request?)` — typed parsed body, optional raw request (no credentials)
+
+## `pollingTrigger` fields
+
+- `schedule`
+- `response`
+- `poll`
+- `filter`
+- `idempotencyKey`
+
+## `pollingTrigger` instance methods
+
+- `.poll(ctx)`
+- `.parseResponse(response)`
+- `.filter?(payload)` — typed parsed payload (no credentials)
+- `.idempotencyKey?(payload)` — typed parsed payload (no credentials)
+
+## `providerTrigger` fields
+
+- `provider`
+- `eventTypes`
+- `appRef`
+- `filter`
+- `idempotencyKey`
+
+## Calling a trigger (creating a bound trigger)
+
+All factory-created triggers are callable. Calling one returns a `BoundTrigger`:
+
+- `trigger()` — bare binding (no transform)
+- `trigger({ transform })` — bound with payload-to-input mapping
+- `trigger({ filter })` — bound with additional filter
+- `trigger({ transform, filter })` — bound with both
+
+## `BoundTrigger`
+
+- `.isBoundTrigger` — always `true`
+- `.trigger` — reference to the underlying trigger instance
+- `.filter?` — composed filter (trigger's filter + binding filter)
+- `.transform?` — payload-to-workflow-input mapping function
+
+## Workflow `triggers` array
+
+`Workflow({ triggers: [...] })` accepts a `TriggerEntry[]`:
+- a bare `CallableTrigger` (trigger payload passes through as workflow input)
+- a `BoundTrigger` (returned by calling the trigger with options)
+
+## Task note
+
+- task triggers are declared inline in `Task.triggers`
+- messaging gateways belong to agent authoring, not trigger authoring
+
+## Where to read next
+
+- `patterns.md` for trigger field examples
+- `testing.md` for trigger callback and bound trigger tests