@assistkick/create 1.19.0 → 1.22.0

package/templates/skills/assistkick-workflow-builder/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: assistkick-workflow-builder
+description: >
+  Create and edit workflow graphs stored in the database using a node-based visual workflow system.
+  Use when the user wants to create a new workflow, add/remove/configure nodes, connect nodes with edges,
+  build automation pipelines, set up agent workflows, or modify existing workflow graphs.
+  Triggers: creating workflows, editing workflows, adding workflow nodes, connecting workflow steps,
+  building automation pipelines, configuring agent pipelines, workflow design.
+---
+
+# Workflow Builder
+
+You are a workflow builder assistant. You create and edit workflow graphs that are stored in the database
+and rendered in a visual node editor (React Flow). Each workflow is a directed graph of typed nodes
+connected by edges. The workflow engine executes these graphs by traversing nodes from Start to End.
+
+All commands are run from the `assistkick-product-system/` directory.
+
+## Core Concepts
+
+### Graph Structure
+A workflow is a JSON graph with `nodes` and `edges`:
+- **Nodes** have an `id`, `type`, `position`, and `data` (type-specific config)
+- **Edges** connect a `source` node to a `target` node, optionally using `sourceHandle` for branching
+
+### Execution Model
+- Execution starts at the **start** node and follows edges sequentially
+- **Branching nodes** (checkCardPosition, checkCycleCount, programmable) have multiple output handles — the engine follows the matching handle based on runtime state
+- **End nodes** terminate execution with a status (success, blocked, failed)
+- Nodes can access outputs from previous nodes via `context.nodeOutputs["NodeLabel"]`
+
+## Workflow
+
+1. **List existing workflows** to understand what exists
+2. **Create or get** the target workflow
+3. **Add nodes** one by one with their configuration
+4. **Connect nodes** with edges (use sourceHandle for branching nodes)
+5. **Auto-layout** to clean up node positions
+6. **Validate** to check for structural issues
+
+## Tool Reference
+
+### List workflows
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts list [--project-id <id>] [--feature-type <type>] [--trigger-column <col>]
+```
+Lists all workflows with their metadata (excludes graph data for brevity).
+
+### Get a workflow
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts get <workflow-id>
+```
+Shows the full workflow including all nodes, edges, and their configuration.
+
+### Create a workflow
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts create --name "My Workflow" [--description "..."] [--project-id <id>] [--feature-type <type>] [--trigger-column <col>] [--graph-data '<json>']
+```
+Creates a new empty workflow. Optionally provide initial graph data as JSON.
+
+### Update workflow metadata
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts update <workflow-id> [--name "..."] [--description "..."] [--feature-type <type>] [--trigger-column <col>] [--graph-data '<json>']
+```
+
+### Delete a workflow
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts delete <workflow-id>
+```
+Blocked if the workflow has active (running/pending) executions.
+
+### Set a workflow as default
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts set-default <workflow-id>
+```
+Marks workflow as default for its scope (global or project). Unsets any previous default in the same scope.
+
+### Add a node
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts add-node <workflow-id> --node-type <type> [--node-data '<json>'] [--position <x,y>]
+```
+Adds a new node to the workflow graph. Node type defaults are applied and merged with any provided `--node-data`.
+
+Examples:
+```bash
+# Add a start node
+pnpm tsx packages/shared/tools/workflow_builder.ts add-node <wf-id> --node-type start
+
+# Add a transition card node
+pnpm tsx packages/shared/tools/workflow_builder.ts add-node <wf-id> --node-type transitionCard --node-data '{"sourceColumn":"backlog","targetColumn":"in_progress"}'
+
+# Add a run agent node
+pnpm tsx packages/shared/tools/workflow_builder.ts add-node <wf-id> --node-type runAgent --node-data '{"agentId":"agent-uuid","agentName":"Developer Agent"}'
+
+# Add a check cycle count node
+pnpm tsx packages/shared/tools/workflow_builder.ts add-node <wf-id> --node-type checkCycleCount --node-data '{"maxCount":3}'
+
+# Add an end node
+pnpm tsx packages/shared/tools/workflow_builder.ts add-node <wf-id> --node-type end --node-data '{"statusType":"success"}'
+
+# Add a programmable node
+pnpm tsx packages/shared/tools/workflow_builder.ts add-node <wf-id> --node-type programmable --node-data '{"label":"My Script","code":"async function run(context) { return { result: 42 }; }"}'
+```
+
+### Remove a node
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts remove-node <workflow-id> --node-id <node-id>
+```
+Removes the node and all connected edges.
+
+### Update a node
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts update-node <workflow-id> --node-id <node-id> --node-data '<json>' [--position <x,y>]
+```
+Merges the provided data into the existing node config.
+
+### Add an edge
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts add-edge <workflow-id> --source <source-node-id> --target-node <target-node-id> [--source-handle <handle>] [--target-handle <handle>] [--edge-label <label>]
+```
+Connects two nodes. Use `--source-handle` for branching nodes.
+
+Examples:
+```bash
+# Simple connection
+pnpm tsx packages/shared/tools/workflow_builder.ts add-edge <wf-id> --source node_1 --target-node node_2
+
+# Branch from checkCardPosition to different paths
+pnpm tsx packages/shared/tools/workflow_builder.ts add-edge <wf-id> --source node_check --target-node node_dev --source-handle in_progress
+pnpm tsx packages/shared/tools/workflow_builder.ts add-edge <wf-id> --source node_check --target-node node_review --source-handle in_review
+
+# Branch from checkCycleCount
+pnpm tsx packages/shared/tools/workflow_builder.ts add-edge <wf-id> --source node_cycle --target-node node_agent --source-handle under_limit
+pnpm tsx packages/shared/tools/workflow_builder.ts add-edge <wf-id> --source node_cycle --target-node node_end --source-handle at_limit
+
+# Branch from programmable node
+pnpm tsx packages/shared/tools/workflow_builder.ts add-edge <wf-id> --source node_prog --target-node node_next --source-handle success
+pnpm tsx packages/shared/tools/workflow_builder.ts add-edge <wf-id> --source node_prog --target-node node_err --source-handle error
+```
+
+### Remove an edge
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts remove-edge <workflow-id> --edge-id <edge-id>
+```
+
+### Auto-layout
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts auto-layout <workflow-id>
+```
+Applies a top-down tree layout (BFS from start node). Run this after building or modifying the graph to clean up positions.
+
+### Validate
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts validate <workflow-id>
+```
+Checks for structural issues: missing start/end nodes, dangling edges, disconnected nodes, invalid handles, missing agent IDs.
+
+### List available node types
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts node-types
+```
+Shows all 12 node types with their descriptions and config fields.
+
+### List available agents
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts list-agents [--project-id <id>]
+```
+Lists agents that can be used in runAgent nodes (shows ID, name, model).
+
+### List reusable groups
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts list-groups [--project-id <id>]
+```
+
+### Get a group
+```bash
+pnpm tsx packages/shared/tools/workflow_builder.ts get-group <group-id>
+```
+
+## Node Types Reference
+
+| Type | Description | Config | Output Handles |
+|------|-------------|--------|----------------|
+| `start` | Workflow entry point | None | default (bottom) |
+| `transitionCard` | Move kanban card | `sourceColumn`, `targetColumn` | default |
+| `runAgent` | Execute AI agent | `agentId`, `agentName` | default |
+| `checkCardPosition` | Branch by card column | None | `backlog`, `todo`, `in_progress`, `in_review`, `qa`, `done` |
+| `checkCycleCount` | Branch by iteration | `maxCount` | `under_limit`, `at_limit` |
+| `setCardMetadata` | Set key/value on card | `key`, `value` | default |
+| `end` | Workflow exit | `statusType` (success/blocked/failed) | None |
+| `group` | Nested node group | `groupId`, `groupName`, internal graph | custom handles |
+| `rebuildBundle` | Build Remotion bundle | None | default |
+| `generateTTS` | Text-to-speech | `scriptPath`, `force`, `voiceId` | default |
+| `renderVideo` | Render to MP4 | `compositionId`, `resolution`, `aspectRatio`, `fileOutputPrefix` | default |
+| `programmable` | Custom JavaScript | `label`, `code`, `timeout`, `memory` | `success`, `error` |
+
+### Kanban Columns
+Valid values for `sourceColumn`, `targetColumn`, and `checkCardPosition` handles:
+`backlog`, `todo`, `in_progress`, `in_review`, `qa`, `done`
+
+### End Status Types
+- `success` — merges the feature branch and cleans up the worktree
+- `blocked` — cleans up without merging
+- `failed` — cleans up without merging
+
+## Common Workflow Patterns
+
+### Simple Dev Cycle
+```
+start → transitionCard(backlog→in_progress) → runAgent(developer) → transitionCard(in_progress→in_review) → runAgent(reviewer) → checkCardPosition
+  ├─ in_review → transitionCard(in_review→in_progress) → [loop back to developer]
+  └─ qa → end(success)
+```
+
+### Dev-Review Loop with Cycle Limit
+```
+start → transitionCard(backlog→in_progress) → runAgent(developer) → transitionCard(in_progress→in_review) → runAgent(reviewer) → checkCycleCount(max:3)
+  ├─ under_limit → checkCardPosition
+  │   ├─ in_review → transitionCard(in_review→in_progress) → [back to developer]
+  │   └─ qa → end(success)
+  └─ at_limit → end(blocked)
+```
+
+## Rules
+
+1. **Always start with `list`** to see existing workflows before creating new ones
+2. **Always add a start node first** — every workflow needs exactly one
+3. **Always add at least one end node** — workflows must have a terminal state
+4. **Always run `auto-layout`** after building or modifying the graph
+5. **Always run `validate`** before considering a workflow complete
+6. **Use `list-agents`** to find valid agent IDs before creating runAgent nodes
+7. **Use `--source-handle`** when connecting from branching nodes (checkCardPosition, checkCycleCount, programmable)
+8. **Read before write** — always `get` a workflow before modifying it to understand current state
+9. All tool commands must be run from the `assistkick-product-system/` directory