flow-orch — Visual Flow Orchestration for VS Code

Visual flow graphs as the authoritative representation of program logic, with AI-assisted generation and two-way code sync.

Overview

flow-orch is a VS Code extension that lets you design, visualize, and generate code from flow graphs. The graph is the canonical model; source code is a projection. You can edit either side and sync bidirectionally.

Key Features

• Visual Flow Editor — Drag-and-drop canvas with node palette, inspector, and minimap
• Authoritative Graph Model — Graph is source of truth; code is generated from it
• Two-Way Sync — Edit code → graph updates. Edit graph → code regenerates.
• LLM-Assisted — Describe what you want in natural language; AI generates nodes and subgraphs
• Safe by Default — All file changes previewed as diffs; explicit approval required; full undo/redo
• Extensible — Pluginable node registry, language adapters (TS/JS v1, Python v2)

Target Languages (v1)

• TypeScript / JavaScript

Prerequisites

• VS Code 1.85+ (December 2023 or later)
• Node.js 20 LTS or later
• npm 10+

Quick Start (Local Dev)

# 1. Clone and install
git clone <repo-url> flow-orch
cd flow-orch
npm install

# 2. Compile TypeScript
npm run compile

# 3. Open in VS Code
code .

# 4. Press F5 to launch Extension Development Host
#    (or Run > Start Debugging)

# 5. In the Extension Dev Host, open a workspace folder
# 6. Run command: flow-orch.open (Ctrl+Shift+P)
# 7. The flow orchestration panel opens in the sidebar

Running the End-to-End Acceptance Test

# Unit tests (fast, no VS Code needed)
npm run test:unit

# Integration tests (requires VS Code)
npm run test:integration

# Full end-to-end acceptance test
#   flow: prompt → preview → apply → test run
npm run test:e2e

# All tests
npm test

Running flow validate in CI

# Headless graph↔code consistency check
npx flow-orch validate --ci
# Exit 0 = consistent, non-zero = unexpected diffs

Publishing

Package the VSIX

npm run vscode:prepublish
npm run package

Upload to Marketplace

1. navigate to https://marketplace.visualstudio.com/manage/publishers
2. select a publisher (must match the publisher attribute of your package.json)
3. upload the vsix

Project Structure

flow-orch/
├── .flow/                      # Per-workspace graph storage
│   └── graph.json              #   Default graph placeholder
├── .vscode/                    # VS Code debug configs
├── docs/
│   ├── IMPLEMENTATION_PLAN.md  #   File-by-file plan and interfaces
│   ├── SPRINT_PLAN.md          #   12-week sprint breakdown
│   └── CI.md                   #   CI pipeline and local dev notes
├── prompts/                    # LLM prompt templates
│   ├── system.txt
│   ├── intent-extraction.txt
│   ├── node-generation.txt
│   └── refactor.txt
├── schemas/                    # JSON Schema definitions
│   ├── graph.json
│   └── node.json
├── src/
│   ├── extension.ts            #   Extension activation and commands
│   ├── flowEditor.ts           #   CustomEditorProvider for *.logicflow.json
│   ├── api/
│   │   ├── graphEngine.ts      #   In-memory graph model + undo/redo
│   │   ├── codeSync.ts         #   Two-way code↔graph sync orchestrator
│   │   ├── llmOrchestrator.ts  #   LLM abstraction (LM API / BYOK / local)
│   │   ├── repoContext.ts      #   Repository indexing
│   │   ├── nodeRegistry.ts     #   Plugin system for node types
│   │   ├── localServer.ts      #   Local HTTP mock server
│   │   └── sqliteDatabase.ts   #   In-memory SQLite for debug sessions
│   ├── parser/
│   │   ├── tsParser.ts         #   ts-morph AST parser + pattern matchers
│   │   └── pyParser.ts         #   Python AST parser via child process
│   ├── codegen/
│   │   ├── ts/
│   │   │   └── generator.ts    #   Graph → IR → ts-morph AST → source
│   │   └── python/
│   │       └── generator.ts    #   Graph → Python source
│   ├── ui/                     #   React components (webview)
│   │   ├── App.tsx
│   │   ├── Canvas.tsx
│   │   ├── NodePalette.tsx
│   │   ├── ServerPanel.tsx
│   │   ├── SchemaPanel.tsx
│   │   ├── DatabaseInspector.tsx
│   │   ├── ExecutionOutput.tsx
│   │   ├── DebugToolbar.tsx
│   │   ├── DebugInspector.tsx
│   │   ├── DiffPreview.tsx
│   │   ├── LLMPanel.tsx
│   │   ├── flowRuntime.ts
│   │   ├── types.ts
│   │   └── editors/
│   │       ├── EditorPanel.tsx
│   │       ├── ActionEditor.tsx
│   │       ├── MockEditor.tsx
│   │       ├── LLMCallEditor.tsx
│   │       ├── shared.tsx
│   │       └── ...
│   └── webview/
│       └── index.tsx            #   Webview entry point
├── tests/
│   ├── unit/
│   │   ├── graphEngine.test.ts
│   │   ├── schemaValidator.test.ts
│   │   ├── codeSync.test.ts
│   │   └── llmOrchestrator.test.ts
│   └── integration/
│       └── endToEnd.test.ts
├── tools/
│   └── CLAUDE_AGENT_PROMPT.md  #   Claude Code agent prompt for iteration
├── package.json
├── tsconfig.json
└── README.md                   #   This file

Configuration

Extension Settings

Secret Storage

BYOK API keys and local tokens are stored in VS Code's SecretStorage:

• flowOrch.byok.apiKey
• flowOrch.local.token

Use the command flow-orch.setApiKey to store a key securely.

Development Commands

Handoff to Engineers

1. Clone this repository.
2. Read docs/IMPLEMENTATION_PLAN.md for file responsibilities and interfaces.
3. Read docs/SPRINT_PLAN.md for the 12-week breakdown.
4. Read tools/CLAUDE_AGENT_PROMPT.md and use it with Claude Code to continue iterating:

   claude --prompt-file tools/CLAUDE_AGENT_PROMPT.md
   

5. All TODO markers in the source indicate spots that need full implementation.
6. Schemas under schemas/ and prompt templates under prompts/ are the contracts.
7. Start from Sprint 0 and work forward through the dependency chain.

Architecture Diagram

[Webview UI] <--> [Extension Host] <--> [Graph Engine] <--> [Code Sync Engine] <--> [File System]
                                         |
                                         v
                                 [LLM Orchestration Layer]
                                         |
                                         v
                                 [Repo Context Manager]

License

MIT

Contributing

See docs/IMPLEMENTATION_PLAN.md for module interfaces and docs/SPRINT_PLAN.md for current priorities.