@joshualelon/clawdbot-skill-flow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clawdbot Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# Skill Flow
+
+Multi-step workflow orchestration plugin for [Clawdbot](https://github.com/clawdbot/clawdbot).
+
+Build deterministic, button-driven conversation flows without AI inference overhead. Perfect for scheduled workouts, surveys, onboarding wizards, approval workflows, and any wizard-style interactions.
+
+## Features
+
+- **Deterministic Execution** - Telegram button callbacks route directly to plugin commands, bypassing LLM entirely
+- **Multi-Step Workflows** - Chain steps with conditional branching and variable capture
+- **Channel Rendering** - Telegram inline keyboards with automatic fallback to text-based menus
+- **Input Validation** - Built-in validators for numbers, emails, and phone numbers
+- **Variable Interpolation** - Use `{{variableName}}` in messages to display captured data
+- **Session Management** - Automatic timeout handling (30 minutes) with in-memory state
+- **History Tracking** - JSONL append-only log for completed flows
+- **Cron Integration** - Schedule flows to run automatically via Clawdbot's cron system
+
+## Quick Start
+
+### 1. Install Plugin
+
+```bash
+clawdbot plugins install @joshualelon/clawdbot-skill-flow
+```
+
+### 2. Create a Flow
+
+```bash
+clawdbot message send "/flow-create import $(cat <<'EOF'
+{
+  "name": "daily-checkin",
+  "description": "Daily wellness check-in",
+  "version": "1.0.0",
+  "steps": [
+    {
+      "id": "mood",
+      "message": "How are you feeling today?",
+      "buttons": ["😊 Great", "😐 Okay", "😔 Not great"],
+      "capture": "mood",
+      "next": "sleep"
+    },
+    {
+      "id": "sleep",
+      "message": "How many hours did you sleep?",
+      "buttons": [4, 5, 6, 7, 8, 9, 10],
+      "capture": "sleep",
+      "validate": "number"
+    }
+  ]
+}
+EOF
+)"
+```
+
+### 3. Run the Flow
+
+```bash
+/flow-start daily-checkin
+```
+
+## Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `/flow-start <name>` | Start a flow | `/flow-start pushups` |
+| `/flow-list` | List all flows | `/flow-list` |
+| `/flow-create import <json>` | Create flow from JSON | See Quick Start |
+| `/flow-delete <name>` | Delete a flow | `/flow-delete pushups` |
+| `/flow-step` | Internal command (callback handler) | N/A |
+
+## Example Flows
+
+### Pushups Workout
+
+4-set pushup tracker with rep counting:
+
+```bash
+clawdbot message send "/flow-create import $(cat src/examples/pushups.json)"
+```
+
+### Customer Survey
+
+Satisfaction survey with conditional branching (high vs low scores):
+
+```bash
+clawdbot message send "/flow-create import $(cat src/examples/survey.json)"
+```
+
+### Onboarding Wizard
+
+Multi-step setup with email validation and variable interpolation:
+
+```bash
+clawdbot message send "/flow-create import $(cat src/examples/onboarding.json)"
+```
+
+## Flow Schema
+
+See [API Documentation](./docs/api.md) for complete schema reference.
+
+### Minimal Example
+
+```json
+{
+  "name": "hello-world",
+  "description": "Simple greeting flow",
+  "version": "1.0.0",
+  "steps": [
+    {
+      "id": "greeting",
+      "message": "What's your name?",
+      "capture": "name",
+      "next": "farewell"
+    },
+    {
+      "id": "farewell",
+      "message": "Nice to meet you, {{name}}! 👋"
+    }
+  ]
+}
+```
+
+## Cron Integration
+
+Schedule flows to run automatically:
+
+```bash
+clawdbot cron add \
+  --name "daily-pushups" \
+  --schedule "45 13 * * *" \
+  --session-target isolated \
+  --message "/flow-start pushups" \
+  --channel telegram \
+  --to "+1234567890"
+```
+
+Verify:
+
+```bash
+clawdbot cron list
+```
+
+## Advanced Features
+
+### Conditional Branching
+
+Route users to different steps based on captured variables:
+
+```json
+{
+  "id": "nps",
+  "message": "Rate us 0-10",
+  "buttons": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+  "capture": "nps",
+  "validate": "number",
+  "condition": {
+    "variable": "nps",
+    "greaterThan": 7,
+    "next": "positive-feedback"
+  },
+  "next": "negative-feedback"
+}
+```
+
+### Input Validation
+
+Enforce data types with built-in validators:
+
+- `"validate": "number"` - Numeric input only
+- `"validate": "email"` - Valid email format
+- `"validate": "phone"` - Phone number format
+
+### Variable Interpolation
+
+Display captured data in subsequent messages:
+
+```json
+{
+  "id": "summary",
+  "message": "Thanks {{name}}! You scored {{nps}}/10."
+}
+```
+
+### Button-Specific Routing
+
+Override default `next` on a per-button basis:
+
+```json
+{
+  "id": "confirm",
+  "message": "Continue?",
+  "buttons": [
+    { "text": "Yes", "value": "yes", "next": "step2" },
+    { "text": "No", "value": "no", "next": "cancel" }
+  ]
+}
+```
+
+## How It Works
+
+### Telegram Button Callbacks
+
+When you render a Telegram inline keyboard button:
+
+```typescript
+{
+  text: "20",
+  callback_data: "/flow-step pushups set1:20"
+}
+```
+
+Telegram sends the `callback_data` string back to Clawdbot, which routes it directly to the `/flow-step` command—**no LLM inference required**.
+
+This enables deterministic, instant responses for structured workflows.
+
+### Session Management
+
+- Sessions stored in-memory with 30-minute timeout
+- Session key: `${senderId}-${flowName}`
+- Automatic cleanup every 5 minutes
+- History saved to `~/.clawdbot/flows/<name>/history.jsonl` on completion
+
+### File Structure
+
+```
+~/.clawdbot/flows/
+├── pushups/
+│   ├── metadata.json
+│   └── history.jsonl
+└── survey/
+    ├── metadata.json
+    └── history.jsonl
+```
+
+## Roadmap
+
+### v0.2.0
+- LLM-driven steps (e.g., "Ask user for feedback, then summarize")
+- External service integrations (Google Sheets, webhooks)
+- Flow analytics dashboard (completion rates, drop-off points)
+
+### v0.3.0
+- Visual flow builder (web UI)
+- Loops and repeats
+- Sub-flows (call another flow as a step)
+
+### v1.0.0
+- Production-ready comprehensive tests
+- Performance optimizations
+- Migration guides
+
+## Contributing
+
+Issues and PRs welcome! This plugin follows Clawdbot's coding conventions.
+
+## License
+
+MIT - See [LICENSE](./LICENSE) file
+
+## Links
+
+- [Clawdbot](https://github.com/clawdbot/clawdbot)
+- [Plugin SDK Docs](https://docs.clawd.bot/plugins)
+- [API Reference](./docs/api.md)
+- [Tutorial](./docs/tutorial.md)

package/clawdbot.plugin.json

@@ -0,0 +1,8 @@
+{
+  "id": "skill-flow",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/index.ts

@@ -0,0 +1,65 @@
+/**
+ * Skill Flow Plugin - Multi-step workflow orchestration for Clawdbot
+ */
+
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { createFlowStartCommand } from "./src/commands/flow-start.js";
+import { createFlowStepCommand } from "./src/commands/flow-step.js";
+import { createFlowCreateCommand } from "./src/commands/flow-create.js";
+import { createFlowListCommand } from "./src/commands/flow-list.js";
+import { createFlowDeleteCommand } from "./src/commands/flow-delete.js";
+
+const plugin = {
+  id: "skill-flow",
+  name: "Skill Flow",
+  description:
+    "Multi-step workflow orchestration for deterministic command execution",
+  version: "0.1.0",
+
+  register(api: ClawdbotPluginApi) {
+    // Register commands
+    api.registerCommand({
+      name: "flow-start",
+      description: "Start a workflow",
+      acceptsArgs: true,
+      requireAuth: true,
+      handler: createFlowStartCommand(api),
+    });
+
+    api.registerCommand({
+      name: "flow-step",
+      description: "Handle flow step transition (internal)",
+      acceptsArgs: true,
+      requireAuth: true,
+      handler: createFlowStepCommand(api),
+    });
+
+    api.registerCommand({
+      name: "flow-create",
+      description: "Create a new flow from JSON",
+      acceptsArgs: true,
+      requireAuth: true,
+      handler: createFlowCreateCommand(api),
+    });
+
+    api.registerCommand({
+      name: "flow-list",
+      description: "List all available flows",
+      acceptsArgs: false,
+      requireAuth: true,
+      handler: createFlowListCommand(api),
+    });
+
+    api.registerCommand({
+      name: "flow-delete",
+      description: "Delete a flow",
+      acceptsArgs: true,
+      requireAuth: true,
+      handler: createFlowDeleteCommand(api),
+    });
+
+    api.logger.info("Skill Flow plugin registered successfully");
+  },
+};
+
+export default plugin;

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@joshualelon/clawdbot-skill-flow",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Multi-step workflow orchestration plugin for Clawdbot",
+  "keywords": [
+    "clawdbot",
+    "clawdbot-plugin",
+    "workflow",
+    "automation",
+    "skill",
+    "flow",
+    "telegram"
+  ],
+  "author": "Joshua Le Long <joshualelon>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joshualelon/clawdbot-skill-flow.git"
+  },
+  "homepage": "https://github.com/joshualelon/clawdbot-skill-flow#readme",
+  "bugs": {
+    "url": "https://github.com/joshualelon/clawdbot-skill-flow/issues"
+  },
+  "files": [
+    "src/**/*",
+    "index.ts",
+    "types.d.ts",
+    "README.md",
+    "LICENSE",
+    "clawdbot.plugin.json"
+  ],
+  "clawdbot": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "lockfile": "^1.0.4",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "dependency-cruiser": "^17.0.0",
+    "husky": "^9.0.0",
+    "jscpd": "^4.0.0",
+    "knip": "^5.0.0",
+    "lint-staged": "^15.0.0",
+    "oxlint": "^0.15.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "peerDependencies": {
+    "clawdbot": ">=2026.1.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint src tests index.ts",
+    "lint:fix": "oxlint --fix src tests index.ts",
+    "check:deps": "depcruise src index.ts --config .dependency-cruiser.cjs",
+    "check:dead-code": "knip",
+    "check:duplicates": "jscpd src",
+    "check": "pnpm lint && pnpm typecheck && pnpm check:deps && pnpm check:dead-code && pnpm check:duplicates && pnpm test:coverage",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "oxlint --fix",
+      "tsc --noEmit"
+    ]
+  }
+}

package/src/commands/flow-create.ts

@@ -0,0 +1,69 @@
+/**
+ * /flow-create command - Create a new flow
+ */
+
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { saveFlow } from "../state/flow-store.js";
+import { FlowMetadataSchema } from "../validation.js";
+import type { FlowMetadata } from "../types.js";
+
+export function createFlowCreateCommand(api: ClawdbotPluginApi) {
+  return async (args: { args?: string }) => {
+    const input = args.args?.trim();
+
+    if (!input) {
+      return {
+        text: "Usage: /flow-create import <json>\n\nExample:\n/flow-create import {...}",
+      };
+    }
+
+    // Check for 'import' subcommand
+    const importMatch = input.match(/^import\s+(.+)$/s);
+
+    if (!importMatch) {
+      return {
+        text: "Currently only 'import' mode is supported.\n\nUsage: /flow-create import <json>",
+      };
+    }
+
+    const jsonStr = importMatch[1];
+    if (!jsonStr) {
+      return {
+        text: "Error: No JSON provided",
+      };
+    }
+
+    try {
+      // Parse JSON
+      const data = JSON.parse(jsonStr) as unknown;
+
+      // Validate schema
+      const flow: FlowMetadata = FlowMetadataSchema.parse(data);
+
+      // Save flow
+      await saveFlow(api, flow);
+
+      api.logger.info(`Created flow "${flow.name}"`);
+
+      return {
+        text: `✅ Flow "${flow.name}" created successfully!\n\nStart it with: /flow-start ${flow.name}`,
+      };
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        return {
+          text: `Error: Invalid JSON\n\n${error.message}`,
+        };
+      }
+
+      if (error instanceof Error) {
+        return {
+          text: `Error: Invalid flow definition\n\n${error.message}`,
+        };
+      }
+
+      return {
+        text: "Error: Failed to create flow",
+      };
+    }
+  };
+}

package/src/commands/flow-delete.ts

@@ -0,0 +1,36 @@
+/**
+ * /flow-delete command - Delete a flow
+ */
+
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { deleteFlow, loadFlow } from "../state/flow-store.js";
+
+export function createFlowDeleteCommand(api: ClawdbotPluginApi) {
+  return async (args: { args?: string }) => {
+    const flowName = args.args?.trim();
+
+    if (!flowName) {
+      return {
+        text: "Usage: /flow-delete <flow-name>\n\nExample: /flow-delete pushups",
+      };
+    }
+
+    // Check if flow exists
+    const flow = await loadFlow(api, flowName);
+
+    if (!flow) {
+      return {
+        text: `Flow "${flowName}" not found.\n\nUse /flow-list to see available flows.`,
+      };
+    }
+
+    // Delete flow
+    await deleteFlow(api, flowName);
+
+    api.logger.info(`Deleted flow "${flowName}"`);
+
+    return {
+      text: `✅ Flow "${flowName}" deleted successfully.`,
+    };
+  };
+}

package/src/commands/flow-list.ts

@@ -0,0 +1,33 @@
+/**
+ * /flow-list command - List all available flows
+ */
+
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { listFlows } from "../state/flow-store.js";
+
+export function createFlowListCommand(api: ClawdbotPluginApi) {
+  return async () => {
+    const flows = await listFlows(api);
+
+    if (flows.length === 0) {
+      return {
+        text: "No flows found.\n\nCreate one with: /flow-create import {...}",
+      };
+    }
+
+    let message = `📋 Available Flows (${flows.length}):\n\n`;
+
+    for (const flow of flows) {
+      message += `• ${flow.name}\n`;
+      message += `  ${flow.description}\n`;
+
+      if (flow.triggers?.cron) {
+        message += `  🕒 Cron: ${flow.triggers.cron}\n`;
+      }
+
+      message += `  Start: /flow-start ${flow.name}\n\n`;
+    }
+
+    return { text: message };
+  };
+}

package/src/commands/flow-start.ts

@@ -0,0 +1,56 @@
+/**
+ * /flow-start command - Start a flow
+ */
+
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { loadFlow } from "../state/flow-store.js";
+import { createSession, getSessionKey } from "../state/session-store.js";
+import { startFlow } from "../engine/executor.js";
+
+export function createFlowStartCommand(api: ClawdbotPluginApi) {
+  return async (args: {
+    args?: string;
+    senderId: string;
+    channel: string;
+  }) => {
+    const flowName = args.args?.trim();
+
+    // Validate input
+    if (!flowName) {
+      return {
+        text: "Usage: /flow-start <flow-name>\n\nExample: /flow-start pushups\n\nUse /flow-list to see available flows.",
+      };
+    }
+
+    // Load flow
+    const flow = await loadFlow(api, flowName);
+
+    if (!flow) {
+      return {
+        text: `Flow "${flowName}" not found.\n\nUse /flow-list to see available flows.`,
+      };
+    }
+
+    // Verify flow has steps
+    if (!flow.steps || flow.steps.length === 0) {
+      return {
+        text: `Flow "${flowName}" has no steps.`,
+      };
+    }
+
+    // Create session
+    const session = createSession({
+      flowName: flow.name,
+      currentStepId: flow.steps[0]!.id,
+      senderId: args.senderId,
+      channel: args.channel,
+    });
+
+    api.logger.info(
+      `Started flow "${flowName}" for user ${args.senderId} (session: ${getSessionKey(args.senderId, flowName)})`
+    );
+
+    // Render first step
+    return startFlow(api, flow, session);
+  };
+}