ClientFlow Forge

ClientFlow Forge is a local automation factory for turning client requirements documents into reviewable n8n workflow drafts.

The workflow is simple from the operator's side: drop a JD, TRD, or PDF into an inbox folder. The system extracts the document, breaks it into implementation requirements, designs an n8n architecture, generates workflow JSON, validates the graph, repairs invalid drafts when needed, and optionally deploys an inactive workflow to n8n.

It was built for client automation work where speed matters, but production safety still matters more.

What It Does

• Watches a local inbox for .md, .txt, .json, .csv, .docx, and .pdf files.
• Extracts and normalizes document text.
• Runs a staged multi-agent pipeline:
  • intake
  • requirements analysis
  • solution architecture
  • workflow generation
  • validation and security review
  • workflow repair loop
  • optional n8n deployment
• Produces full run artifacts for audit and debugging.
• Creates n8n workflows as inactive drafts by default.
• Avoids hardcoded credentials and blocks obvious secret-like values in generated node parameters.

Why This Exists

Many automation projects start from a messy client document: half business requirements, half technical wishlist. Building the first n8n draft manually means reading the doc, identifying systems, mapping credentials, sketching flow logic, creating nodes, checking edge cases, and writing a test plan.

ClientFlow Forge makes that first draft repeatable.

It does not replace final implementation judgment. It gets the workflow to a structured draft state quickly, with assumptions and credential gaps made visible.

Architecture

flowchart LR
  A["Inbox watcher"] --> B["Intake"]
  B --> C["Requirements analyst"]
  C --> D["n8n architect"]
  D --> E["Workflow builder"]
  E --> F["Validator and security review"]
  F -- "valid" --> G["Optional n8n deploy"]
  F -- "invalid" --> H["Debugger"]
  H --> F
  F -- "loop exhausted" --> I["Safe fallback draft"]
  I --> G
  G --> J["Reports and artifacts"]

Loading

More detail is in docs/SYSTEM_DESIGN.md.

Quick Start

Install dependencies:

python -m pip install -r requirements.txt

Copy the example config:

Copy-Item .\config\agent-config.example.json .\config\agent-config.json

Edit:

config/agent-config.json

For local-only generation, keep:

"deploy_to_n8n": false

For n8n deployment, set your n8n URL and provide an API key through the environment:

$env:N8N_API_KEY = "your-key"

Then start one scan:

python .\clientflow_forge\agent.py once

Or start the watcher:

powershell -ExecutionPolicy Bypass -File .\scripts\start-watcher.ps1

Drop files into:

inbox/

Codex, OpenAI, and Local Models

The default provider is the Codex CLI:

"default_llm_provider": "codex"

The runner can also use:

• OpenAI API through OPENAI_API_KEY
• local Ollama as a fallback

Provider fallback order is configured in code so the pipeline can still produce a safe draft if a preferred provider fails.

Output Folders

• processing/ - active run folders
• completed/ - completed run archives
• failed/ - failed run archives
• outbox/ - generated workflow JSON
• reports/ - readable run reports
• logs/ - watcher logs

These folders are ignored by git because they can contain client-specific documents and run artifacts.

Example TRD

An example dental clinic automation brief is included here:

examples/northstar-dental-lead-intake-trd.md

It tests lead intake, data normalization, priority scoring, CRM payloads, Slack alerts, Gmail draft payloads, audit rows, and production cutover notes.

Safety Defaults

• Workflows are drafts.
• active is never set to true during creation.
• Unknown integrations become placeholder payloads.
• Credentials are listed as requirements, not embedded in workflow JSON.
• Validation checks node references, connection schema, canonical node types, active-state leaks, and obvious secret-like strings.

Status

This is an operator-focused project rather than a packaged SaaS. The current implementation favors clear local files, auditable run folders, and n8n compatibility over a database or web UI.