ai-workflow-builder

📬 Get AI tips & prompt templates — subscribe to the Slashman Tools newsletter: https://slashmantools.us/subscribe

Turn a single natural-language prompt into a validated, dependency-checked multi-agent AI workflow. Ambiguity is resolved up front by an interactive Grill-Me spec loop — not discovered later in production.

This is the codebase behind workflow-builders.com — a Node.js + React studio for designing production multi-agent systems.

---

🖼️ Demo

Product page: https://workflow-builders.com/?utm_source=github&utm_medium=readme&utm_campaign=ai-workflow-builder — a static landing page with the self-host quick start and a Gumroad CTA. The studio itself is self-hosted: clone or download the code and run it locally in minutes.

---

Why this exists

Building multi-agent AI pipelines today means one of two bad options: hand-write brittle glue code, or write an exhaustive spec before you know what you need. Ambiguous prompts get silently mis-interpreted and fail in production.

ai-workflow-builder closes that gap. You give it one plain-language prompt. It interrogates you (the Grill-Me loop) only about the parts that are genuinely ambiguous — the goal, the inputs, the shape of the output, how success is measured — resolves those into a versioned spec, scaffolds a validated workflow DAG, and generates runnable Python orchestration code from it.

Stack

This is a single npm-workspaces monorepo, not a Python CLI:

Workspace	What it is	Key tech
server/	The REST API	Node 22 · Express 4 · node:sqlite (built-in)
web/	The single-page studio	React 18 · Vite 6

The server is a hexagonal (ports & adapters) modular monolith. The domain/ layer — the Grill engine, spec builder, workflow validator, topological sort, executor, and Python code generator — has zero framework imports and is covered by the bulk of the test suite. Express and SQLite are adapters plugged in at the composition root (server/src/index.js).

Node 22.5+ is required. Persistence uses the built-in node:sqlite module, which only exists on Node ≥ 22.5. On older Node the SQLite adapter — and its tests — cannot load. CI pins Node 22.

Quick start

git clone https://github.com/slashman413/ai-workflow-builder.git
cd ai-workflow-builder
npm install              # installs both workspaces

npm run dev              # server (:4000) + Vite dev server (:5173) together

Then open http://localhost:5173. The Vite dev server proxies /api to the backend, so there is no CORS to configure locally.

Everyday commands

Command	Does
npm run dev	Run API + web dev server concurrently
npm run dev:server / npm run dev:web	Run one side only
npm test	Run the server test suite (node --test)
npm run lint	ESLint the server
npm run build	Build the web SPA to web/dist/
npm start	Start the API in production mode (SQLite)

Configuration (server)

Env var	Default	Purpose
PORT	4000	API listen port
DB_FILE	./data/app.db	SQLite database path (auto-created)
USE_MEMORY	—	Set to 1 to use the non-persistent in-memory repo
NODE_ENV	—	production tightens the CORS allow-list
CORS_ORIGINS	—	Comma-separated origin allow-list override (defaults: production → https://workflow-builders.com; dev → localhost Vite origins). https://*.pages.dev preview deploys and https://*.workflow-builders.com subdomains are always honored
AUTH_MODE	test	clerk verifies every request's session JWT with Clerk (CLERK_SECRET_KEY required)
VAULT_KEK	—	32-byte base64 envelope key for the LLM key vault (required in production)
STRIPE_SECRET_KEY	—	Enables live Stripe billing (Team tier, $99/mo)
STRIPE_WEBHOOK_SECRET	—	whsec_… for signature-verified webhooks (required for billing)
STRIPE_TEAM_PRICE_ID	—	Stripe Price id for the Team tier
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET	—	GitHub OAuth app for repo publishing (repo scope)
GITHUB_REDIRECT_URI	—	OAuth callback URL (defaults to ${API_ORIGIN}/api/github/callback)
POSTHOG_API_KEY	—	Enables PostHog product analytics (privacy-preserving, allowlisted props only)
POSTHOG_HOST	https://us.i.posthog.com	PostHog ingestion host

The REST API

All endpoints are served under /api. The machine-readable contract lives in openapi.yaml and is kept honest by an automated contract test that fails CI if the routes and the spec ever drift.

Method	Path	Purpose
GET	/api/health	Liveness + readiness probe (status, version, uptime, DB check; 503 when DB is down)
POST	/api/projects	Create a project from a prompt
GET	/api/projects	List projects
GET	/api/projects/{id}	Fetch a project
DELETE	/api/projects/{id}	Delete a project
GET	/api/projects/{id}/grill	Get the next Grill-Me questions
POST	/api/projects/{id}/answers	Submit answers, advancing the spec
POST	/api/projects/{id}/workflow/scaffold	Scaffold a workflow DAG from the spec
GET	/api/projects/{id}/workflow	Fetch the current workflow
PUT	/api/projects/{id}/workflow	Save/replace the workflow (validated)
POST	/api/workflow/preflight	Static pre-flight AST validation (cycles, reachability, schema, tool boundaries, security)
POST	/api/workflow/simulate	SAFE execution preview (static validation + mock simulation)
POST	/api/projects/{id}/publish	Export the compiled workflow to GitHub (Team tier)
GET	/api/projects/{id}/publications	Publication ledger for a project
GET	/api/github/auth-url	Start the GitHub OAuth dance (repo scope)
GET	/api/github/status	GitHub connection status + recent publications
DELETE	/api/github/connection	Disconnect the org's GitHub account
GET	/api/billing	Current Stripe subscription state
GET	/api/billing/entitlement	Effective tier + monthly Grill usage (free cap / team gates)
POST	/api/billing/checkout	Create a Stripe Checkout session (Team $99/mo)
POST	/api/billing/portal	Stripe billing portal link
POST	/api/billing/webhook	Stripe webhook (public, signature-verified, idempotent)
POST	/api/telemetry/events	Privacy-preserving analytics capture (allowlisted props only)

See docs/api-reference.md for request/response shapes and error codes.

Monetization, publishing & analytics (Increment 4)

• Pre-flight validator — POST /api/workflow/preflight runs the full static gate before any export: structural DAG checks, reachability (islands, unreachable nodes), schema parameter matching, tool-boundary constraints against the marketplace allow-list, and the security boundary reassertion (executable payload markers are refused; nothing ever executes).
• Code generator — the compiled Python project now ships typed interfaces (interfaces.py), LLM retry + fallback handlers (LLM_MAX_RETRIES, DEFAULT_AGENT_FALLBACK, main(continue_on_error=True)), GitHub Actions CI (.github/workflows/ci.yml), .gitignore and a spec scaffold (spec.yaml, workflow.json).
• GitHub publishing — OAuth (repo scope) connects the user's account; the git-data API scaffolds a repository in 4 requests (<5s SLA). Tokens are sealed with the vault's envelope key; every publish is recorded in the publications ledger.
• Stripe billing — Team tier at $99/mo with a 14-day trial. Webhooks are signature-verified, idempotent (event-id ledger) and out-of-order safe (state is re-fetched, never trusted from the event). Entitlement gates: Free = 10 Grill sessions/month + mocked previews; Team/trial = unlimited Grill loops + repository export.
• PostHog analytics — the user funnel (grill kickoff, lens selections, export completions) is captured with pseudonymous org hashes and an allowlisted property set. Prompt text, API keys and free-form content are structurally impossible to log.

Pre-GA security gates

node scripts/security/secret-scan.mjs      # HIGH/MEDIUM/LOW secret patterns across the tree
node scripts/security/coverage-gate.mjs    # line coverage ≥ 90% (~95% today)
bash scripts/security/security-gate.sh     # npm audit + secret scan + OSV vulnerability check

CI runs lint, test, the coverage gate, and build in the Lint, Test, Build job, and security-gate.sh in the Security Gate job (see .github/workflows/ci-cd.yml).

Increment 4 environment variables

Variable	Required	Used for
STRIPE_SECRET_KEY	for billing	Stripe API (server-side operations)
STRIPE_WEBHOOK_SECRET	for billing	Webhook signature verification (whsec_…)
STRIPE_TEAM_PRICE_ID	for billing	The $99/mo Team tier price (price_…)
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET	for publishing	GitHub OAuth app (repo scope)
GITHUB_REDIRECT_URI	optional	OAuth callback URL (defaults to <API_ORIGIN>/api/github/callback)
POSTHOG_API_KEY / POSTHOG_HOST	optional	Product analytics (falls back to local-only telemetry)

In production the server fails closed: billing/publishing endpoints answer 503 until the relevant credentials are set. In development, without these variables, the API still serves the full pre-auth flow, the Grill loop, mock simulation, and the pre-flight validator.

How it works

   prompt
     │
     ▼
┌──────────────┐   questions   ┌──────────────────┐
│  Prompt      │ ───────────▶  │  Grill-Me loop   │
│  ingestion   │ ◀───────────  │ (clarify spec)   │
└──────────────┘   answers     └───────┬──────────┘
                                        │ resolved, versioned spec
                                        ▼
                               ┌──────────────────┐
                               │ Workflow scaffold│  validated DAG:
                               │  + validator     │  no cycles, no dangling deps
                               └───────┬──────────┘
                                        ▼
                               ┌──────────────────┐
                               │ Python code-gen  │  runnable orchestration
                               └──────────────────┘

Deployment

Two different things ship from this repo:

• workflow-builders.com — a static landing page (web/landing/): product intro, self-host quick start, and a Gumroad CTA. Deployed by the CI/CD pipeline (.github/workflows/ci-cd.yml) on push to main to the Cloudflare Pages project ai-workflow-builder-web. No Clerk, no API origin, no login wall — pure HTML/CSS, zero runtime secrets.
• The studio — self-hosted by buyers. Run it locally in minutes (npm install && npm run dev), or deploy it on any Node 22.5+ host you control (a VPS, a Docker container, Railway, etc.). There is no hosted multi-tenant backend anymore.

Full guide: docs/deployment-guide.md. The old Fly.io deployment plan is archived in docs/archive/.

Documentation

Guide	Read it to…
Usage Guide	Run locally and build your first workflow end to end
API Reference	Call every endpoint with request/response/error detail
Architecture	Understand the hexagonal layering and module seams
Domain Model	Learn the ubiquitous language (project, spec, workflow, node)
Deployment Guide	Deploy the demo landing page + self-host the studio
Contributing	Set up a dev environment and land a change
ADRs	The recorded architecture decisions behind the above

Attribution

Ecosystem integrations and their licenses are tracked in ATTRIBUTIONS.md.

🛒 相關產品

• AI Workflow Builder ($99) - Turn a natural-language prompt into a validated, dependency-checked multi-agent AI workflow — ambiguity resolved up front by the interactive Grill-Me spec loop.

License

MIT.

---

🛍️ Slashman Tools

Part of the Slashman Tools ecosystem — free & open-source AI automation tools:

Tool	What it does
AI Workflow Builder	This repo — prompt → validated multi-agent workflow
AI Prompt Library	500+ curated prompt templates (ChatGPT/Claude/Gemini)
AI Workflow Builder — Premium Guides & Templates ($99)	Advanced workflow templates, n8n recipes & automation blueprints
More tools…	Free AI, finance & productivity tools (中／EN)

Built by @slashman413 · slashmantools.us

---

🚀 Automate Your Workflow

Enjoying this tool? Join our weekly newsletter to get AI tools, automation tips, and digital product strategies directly in your inbox. No spam, just pure value.