# Workflow Local Dev

> Support local workflow platform development in the DAP workspace across frontend, backend, and infra teams. Provides access to Kubernetes (Kind), Tilt service management, database queries, and troubleshooting. Use when building backend/API features, adjusting infra configurations, checking logs, running tests, or debugging issues against locally deployed workflow engine components.

- Skill: `lgariv-dn/workflow-local-dev` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add lgariv-dn/workflow-local-dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lgariv-dn/workflow-local-dev/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: lgariv-dn (https://skillmd.com/u/lgariv-dn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lgariv-dn/workflow-local-dev

---


# Workflow Local Development

## Quick Reference

### Key Commands

| Task | Command |
|------|---------|
| Check pods | `kubectl get pods --context kind-kind` |
| Restart component | `tilt trigger workflow-<service>` |
| View component logs | `tilt logs workflow-<service>` |

### Locally Deployed Components

These workflow services are deployed locally as shared dependencies:
`workflow-catalog`, `workflow-executions-api`, `workflow-engine-worker`, `workflow-consumer`, `workflow-validator`, `workflows-worker`, `standalone-tasks-worker`

---

## Utility Scripts

Execute these scripts for common operations:

### Check Pod Status
```bash
bash .cursor/skills/workflow-local-dev/scripts/check-pods.sh
```

### Restart a Service
```bash
bash .cursor/skills/workflow-local-dev/scripts/restart-service.sh <service-name>
# Example: bash .cursor/skills/workflow-local-dev/scripts/restart-service.sh catalog
```

### Tail Service Logs
```bash
bash .cursor/skills/workflow-local-dev/scripts/tail-logs.sh <service-name>
# Example: bash .cursor/skills/workflow-local-dev/scripts/tail-logs.sh executions-api
```

### Query Database
```bash
bash .cursor/skills/workflow-local-dev/scripts/db-query.sh "<SQL query>"
# Example: bash .cursor/skills/workflow-local-dev/scripts/db-query.sh "SELECT * FROM workflow_engine.workflows ORDER BY created_at DESC LIMIT 5"
```

---

## Development Workflow

Use this flow primarily when containers fail locally or when you need to debug runtime behavior.

1. **Capture current status**: `kubectl get pods --context kind-kind`
2. **Rebuild/restart component**: `tilt trigger workflow-<service>`
3. **Watch logs or health**: `kubectl logs -f <pod> --context kind-kind`
4. **Inspect configuration or data** (if needed): `bash .cursor/skills/workflow-local-dev/scripts/db-query.sh "<SQL query>"`

---

## Troubleshooting

### Pod Issues
```bash
kubectl get pods --context kind-kind
kubectl describe pod <pod-name> --context kind-kind
kubectl logs -f <pod-name> --context kind-kind
```

### Temporal Workflows
Open http://localhost:8081 (Temporal UI) and search by workflow ID.

### Database State
```bash
# Use the db-query script (runs psql inside the postgres pod)
bash .cursor/skills/workflow-local-dev/scripts/db-query.sh "SELECT * FROM workflow_engine.workflows ORDER BY created_at DESC LIMIT 5"
```

### Pulsar Messages
```bash
pulsar-admin topics stats persistent://public/dap/<topic>
pulsar-client consume persistent://public/dap/<topic> -s test-sub -n 10
```

---

## Using Kubernetes MCP (When Available)

If the Kubernetes MCP server is enabled, you can use MCP tools instead of shell commands for a more integrated experience. The MCP defaults to the `kind-kind` context.

### List Pods

```
Tool: pods_list
Arguments: { "labelSelector": "app=workflow-catalog" }
```

Or list all pods:
```
Tool: pods_list
Arguments: {}
```

### Get Pod Logs

```
Tool: pods_log
Arguments: {
  "name": "workflow-catalog-xxxxx",
  "namespace": "default",
  "tail": 100
}
```

For previous container logs (after crash):
```
Tool: pods_log
Arguments: {
  "name": "workflow-catalog-xxxxx",
  "namespace": "default",
  "previous": true
}
```

### Execute Commands in Pods (e.g., Database Queries)

```
Tool: pods_exec
Arguments: {
  "name": "postgres-xxxxx",
  "namespace": "default",
  "command": ["psql", "-U", "postgres", "-d", "temporal", "-c", "SELECT * FROM workflow_engine.workflows ORDER BY created_at DESC LIMIT 5"]
}
```

### Delete Pod (Force Restart)

```
Tool: pods_delete
Arguments: {
  "name": "workflow-catalog-xxxxx",
  "namespace": "default"
}
```

### Get Pod Details

```
Tool: pods_get
Arguments: {
  "name": "workflow-catalog-xxxxx",
  "namespace": "default"
}
```

### List Cluster Events (Troubleshooting)

```
Tool: events_list
Arguments: { "namespace": "default" }
```

> **Note**: When using MCP tools, you don't need to specify `context` as it defaults to `kind-kind`. The MCP approach is useful when you want the agent to directly interact with the cluster without spawning shell processes.

---

## Additional Resources

- For complete service URLs and infrastructure details, see [reference.md](reference.md)