FlowOS — Deterministic Development Orchestration Engine

FlowOS is a deterministic software development orchestration engine. It converts ideas into structured, execution-ready development blueprints — without AI guesswork.

It does not generate code directly. It generates structured .flow/ packages that guide developers and AI coding agents to build software consistently, without ambiguity or context loss.

Core Philosophy

Structure First. Intelligence Second.

The system is designed around deterministic logic:

• Deterministic outputs — Same input always produces the same blueprint
• Rule-based decision making — 20+ rules for architecture, modules, and stack
• Structured project flows — Phases with dependencies and constraints
• Persistent project memory — Track decisions, completed phases, pending items
• Deferred resolution — Unknowns become structured nodes for later resolution

Features

• Adaptive Questionnaire — Questions change based on platform (Web / Mobile / Desktop / Multi-Platform) and app type
• 24 Decision Rules — Platform confidence, complexity, scale-up plans, app type, desktop languages, features, deferred decisions
• 15 Architecture Types — Framework-based, Cross-platform, Microservices, Serverless, Event-driven, PWA, Clean Architecture, Hexagonal, Layered, Native Desktop, Offline-first, and more
• Stack Recommendations — Platform-specific suggestions for frontend, backend, database with weighted options
• Desktop Support — C# (.NET), C++, Rust, Python; frameworks: WPF, WinForms, Qt, Electron, Tauri, MAUI
• Scale-up Planning — Scale-up input drives architecture toward Clean/Hexagonal Architecture
• Phase Generator — Up to 8 phases (Init, Architecture, Auth, Data, Logic, Interface, Payments, Real-time)
• Custom Features — Comma-separated custom feature input
• Deferred Resolution — Unknown backend/database choices become interactive prompts
• .flow/ Export — Full project profile, phases, memory, rules, and agent-ready files (CLAUDE.md, CURSOR_RULES.md, SKILL.md)
• GitHub Integration — Push generated .flow/ files to any GitHub repository using a Personal Access Token or GitHub App via OAuth Device Flow

Installation

npm install -g flowos

Or run locally:

git clone <repo-url>
cd dotflowCLI
npm install
npm run build

Usage

# Start the interactive project wizard
flowos init

# Initialize in a specific directory
flowos init ./my-project

Push to GitHub

Push the generated .flow/ blueprint to a GitHub repository:

# Using a Personal Access Token
flowos init --push --token ghp_xxx --owner username --repo repo-name

# Using GitHub App Device Flow (no PAT needed)
flowos init --push --app Iv1.xxxxxx --owner username --repo repo-name

# Push an existing .flow/ directory
flowos push --token ghp_xxx --owner username --repo repo-name

# With environment variable
export GITHUB_TOKEN=ghp_xxx
flowos init --push --owner username --repo repo-name

Authentication methods:

• --token — Classic PAT with repo scope
• --app — GitHub App Client ID (uses OAuth Device Flow — enter the printed code at github.com/login/device)
• GITHUB_TOKEN environment variable

Development Mode

npm run dev       # Run with tsx (no build step)
npm run build     # Compile TypeScript
npm start init    # Run compiled version

What You Get

After running flowos init, a .flow/ directory is created with:

.flow/
├── project/
│   ├── 00_project_profile.md   # Name, description, platform, architecture
│   ├── 01_scope.md             # Feature breakdown
│   ├── 02_architecture.md      # Architecture type, stack, recommendations
│   ├── 03_constraints.md       # Project constraints
│   └── 04_rules.md             # Project rules
├── phases/                     # One file per phase with tasks & constraints
├── memory/
│   ├── project_state.md        # Current progress
│   ├── decisions.md            # Architectural decisions log
│   ├── completed.md            # Completed phases
│   └── pending.md              # Unresolved items
├── rules/                      # Architecture, coding, UI, naming rules
└── exports/
    ├── FULL_CONTEXT.md         # Full project context
    ├── CLAUDE.md               # Claude AI instructions
    ├── CURSOR_RULES.md         # Cursor IDE rules
    └── SKILL.md                # FlowOS skill definition

System Architecture

FlowOS operates in 4 layers:

1. Input Layer — Adaptive CLI questionnaire that captures user intent
2. Rule Engine — 24 deterministic rules that process inputs and generate architecture decisions
3. Blueprint Layer — Internal blueprint model (project, architecture, phases, stack, deferred nodes)
4. Export Layer — .flow/ directory generation

Deferred Resolution System

When the system cannot determine a required decision (e.g., backend or database), it creates a deferred_resolution node:

1. System extracts full project context
2. Rule engine defines allowed solution boundaries
3. Interactive prompt asks user to choose from valid options
4. Decision is locked into the blueprint

Requirements

• Node.js 18+
• npm

Project Structure

src/
├── index.ts                    # CLI entry point (Commander)
├── types/
│   └── index.ts                # TypeScript interfaces
├── core/
│   └── deferred-resolution.ts  # Interactive deferred resolution
├── github/
│   ├── push.ts                 # GitHub Contents API (create/update files)
│   └── device-flow.ts          # GitHub App OAuth Device Flow authentication
└── engine/
    ├── questionnaire.ts        # Adaptive CLI questionnaire
    ├── rule-engine.ts          # Decision engine + recommendation + phases
    ├── blueprint.ts            # Blueprint composition
    └── exporter.ts             # .flow/ directory export

License

ISC