devflow-ai-sdlc

AI-First Software Development Lifecycle (SDLC) platform. AI agents are the primary execution layer — they read your codebase, plan changes, write code, run builds, and retry on failure. You define the work and approve the plan; the agent drives implementation. Everything stored locally in SQLite with no cloud dependency.

What It Does

DevFlow is an AI-First SDLC platform where AI agents are the core execution engine, not a supplementary tool. The human role is project definition, story writing, and plan approval — the agent handles implementation.

Organise work into Projects → Features → User Stories.
Write AI Prompts per user story; the DevFlow Agent plans and executes them autonomously.
Two-phase agentic execution: AI proposes a step-by-step plan → you approve → agent executes with full codebase awareness, runs build verification, and auto-retries on failure.
RAG-powered context: the agent indexes your project with ChromaDB + sentence-transformers so every task has full, semantically-relevant code context.
Generate UI Mockups from natural language and extract User Stories directly from designs.
Use the AI Console for project-wide chat: refine stories, triage issues, generate test cases, and update specs.
Create rich Documents per project using Markdown with templates, SVG diagrams, and draw.io attachments.
Supports multiple AI backends: local Ollama models, Anthropic Claude, Google Gemini, OpenAI-compatible APIs, and local CLI tools — switchable per workflow.
Everything stored locally in SQLite — no cloud account required.

Features

Projects

Create, rename, and delete projects from the home screen.
Recent projects listed on the dashboard (last 5 opened).
Each project has a name and optional description.

Features & User Stories

Each project contains Features; each feature contains User Stories.
User stories have: Title, Description, Acceptance Criteria, Prompt, and Status.
Status values: Backlog · In Progress · Implemented · In Review · Tested · Done.

User Story Detail

Click a user story to open the detail panel.
Fields: Description, Acceptance Criteria, Prompt.
Each field opens in a popup with Edit and Preview tabs.
Preview renders the content as Markdown.
Popup closes only via the × button — clicking outside does nothing.

Documents

Click Documents (top-right of project page, next to AI Model selector) to open the Documents modal.
Documents belong to a project and are stored in SQLite.

Creating a Document

Click New in the sidebar → choose a template:

Template	Contents
Empty Document	Blank page
Project Overview	Purpose, goals, stakeholders, timeline
Technical Specification	Architecture, components, API design, data model
Meeting Notes	Agenda, discussion, decisions, action items
Release Notes	New features, bug fixes, breaking changes

Edit the title inline. Press Ctrl+S or click Save to persist.

Edit / Preview Tabs

Edit — write content in Markdown.
Preview — rendered view with styled headings, code blocks, lists, blockquotes, and attachment links.

Deleting a Document

Hover a document in the sidebar → click the trash icon.

Document Attachments (SVG & draw.io)

Attachments are stored in SQLite and linked inside Markdown content.

Adding an Attachment

Open the Attachments bar at the bottom of the editor (click to expand).
Click Add SVG or Add draw.io.
Enter a name and paste the SVG/XML code → click Add.

Referencing in Markdown

Each attachment shows its ID as attach:ID.
Use in Markdown: [My Diagram](attach:12)
In Preview this renders as a clickable badge → opens the diagram lightbox.

SVG Attachments

Button	Action
View	Opens SVG in a lightbox (isolated from app CSS)
Delete	Removes the attachment

draw.io Attachments

Button	Action
View	Shows info card — draw.io XML cannot be previewed inline. Includes an Open in draw.io button.
Open in draw.io	Writes file to a temp folder and opens in draw.io desktop app
Sync	Reads the saved temp file back and updates the database
Delete	Removes the attachment

draw.io Edit & Sync Workflow

Click Open in draw.io → diagram opens in draw.io desktop.
Edit and save in draw.io (Ctrl+S).
Return to the app → click Sync → changes saved to database.

If draw.io has not been opened in the current session, Sync shows a reminder toast.

Quick Commands

Reusable prompt snippets accessible from the user story panel.
Create, edit, and delete quick commands from the settings/commands panel.

Terminal

Built-in terminal panel for running shell commands.
Supports long-running processes.
Kill Active / Ctrl+C stops the running process.

AI Configuration

AI models are configured in Settings → AI Models. Each model config has a type that controls how the app calls the model.

Model Types

Type	How it works	Used by
`ollama`	Direct HTTP call to a local Ollama server	Documents, Chat, User Stories, Prompt Queue
`ollama` + DevFlow Agent	Spawns `devflow_agent.py` subprocess	Prompt Queue only
`anthropic`	Anthropic SDK call (Claude)	Prompt Queue, Chat
`api`	Generic HTTP POST to any OpenAI-compatible endpoint	Prompt Queue
`cli`	Runs a local CLI binary (e.g. `claude`, `gemini`)	Prompt Queue, Mockups, Extract Stories

Configuring an Ollama Model

Open Settings → AI Models → Add model
Select type Local (Ollama)
Fill in the fields:

Field	Maps to agent flag	Default	Notes
Base URL	`--base-url`	`http://localhost:11434`	Your Ollama server URL. Use the detect button to auto-populate the model list.
Model	`--model`	`qwen2.5-coder:7b`	Pick from the detected dropdown or type manually. Larger models (32b+) give better results for complex tasks.
Max Tokens	`--max-turns`	`15`	Controls how many agentic loop iterations the agent is allowed. Higher = more autonomous but slower.
Use Devflow Agent loop	enables agent mode	off	Checkbox. When ticked, the Prompt Queue runs `devflow_agent.py` instead of a direct Ollama call.

Optionally tick Set as default model so it pre-selects in all pages.
Click Save.

DevFlow Agent Mode

When Use Devflow Agent loop is enabled, the Prompt Queue runs in two phases:

Phase 1 — Plan

The agent (devflow_agent.py) is called with --plan-only. It:

Reads the repo map and RAG context for the project
Generates a structured JSON plan (2–5 steps) using the configured model
Streams the plan back to the Electron UI for review

The plan is displayed in the Prompt Queue panel. Each step shows a title and description of what will be changed and which files are involved.

Phase 2 — Execute (after approval)

Once you approve the plan, the agent is called with --approved-plan <json>. It:

Executes each step in sequence using the agentic tool loop
Streams step progress markers ([STEP:1/3], [STEP_DONE:1/3], [STEP_FAILED:1/3]) to the UI
Runs build verification after all steps complete and auto-retries on build errors

Run Summary

At the end of every run the agent prints a summary. In the Prompt Queue output panel you will see the raw line; in a terminal (CLI use) it is formatted:

── Run summary ───────────────────────────
  Turns: 8  |  Tool calls: 22
  Tokens: 14820 in / 890 out  |  Elapsed: 47.3s
  Files written:
    • src/components/App.tsx
    • src/utils/db.ts
──────────────────────────────────────────

The Electron app also fires a promptQueue:runSummary event with structured data so future UI panels can display metrics.

Agent Flag Reference

These are all flags devflow_agent.py accepts. Most are set via the model config UI; advanced flags are CLI-only.

Flag	UI field	Default	Description
`--model`	Model	`qwen2.5-coder:32b`	Ollama model for task execution
`--base-url`	Base URL	`http://localhost:11434`	Ollama server endpoint
`--max-turns`	Max Tokens	`15`	Max agentic loop iterations per step
`--max-retries`	—	`2`	Max build-fix attempts after the loop ends
`--max-tool-errors`	—	`3`	Consecutive tool failures before the agent aborts
`--plan-only`	auto	—	Generate plan and exit; set automatically by Electron in Phase 1
`--approved-plan`	auto	—	JSON plan string; set automatically by Electron in Phase 2
`--plan-model`	—	same as `--model`	Use a separate (larger) model for plan generation only
`--verbose`	auto	—	Always passed by Electron; enables per-turn timing and token logs

CLI usage example:

# Run without planning (direct agentic loop)
python agent/devflow_agent.py \
  --project /path/to/project \
  --message "Add input validation to the login form" \
  --model qwen2.5-coder:32b \
  --max-turns 20 \
  --verbose

# Generate a plan only (inspect before running)
python agent/devflow_agent.py \
  --project /path/to/project \
  --message "Refactor auth module to use JWT" \
  --model qwen2.5-coder:32b \
  --plan-only

# Use a larger model for planning, smaller for execution
python agent/devflow_agent.py \
  --project /path/to/project \
  --message "Add dark mode toggle" \
  --model qwen2.5-coder:7b \
  --plan-model qwen2.5-coder:32b

Agent Prerequisites

The DevFlow Agent requires Python dependencies. Install once before first use:

cd agent
pip install -r requirements.txt

Ollama must be running locally:

ollama serve
ollama pull qwen2.5-coder:32b   # or whichever model you configured

Markdown Reference

Supported in both Prompt preview and Document preview:

Syntax	Output
`# H1` through `###### H6`	Headings
`bold`	Bold
`italic`	Italic
`~~text~~`	~~Strikethrough~~
`code`	Inline code
``` fenced block	Code block
`- item` or `* item`	Unordered list
`1. item`	Ordered list
`> text`	Blockquote
`---`	Horizontal rule
`[label](url)`	Hyperlink
`[label](attach:ID)`	Attachment link (opens lightbox)

Developer Setup

Prerequisites

Tool	Version	Notes
Node.js	18+ LTS	https://nodejs.org
npm	comes with Node.js	—
Python	3.x	https://python.org — required to compile `better-sqlite3`
Visual Studio Build Tools (Windows only)	2019 or 2022	https://visualstudio.microsoft.com/visual-cpp-build-tools/ — select "Desktop development with C++" workload
draw.io Desktop (optional)	latest	https://github.com/jgraph/drawio-desktop/releases — only needed for editing draw.io attachments

macOS / Linux: Python and a C++ compiler (Xcode CLT / gcc) are usually pre-installed. Visual Studio is not needed.

Install & Run

# 1. Clone the repo
git clone <repo-url>
cd electron-ai-sdlc

# 2. Install dependencies (also compiles better-sqlite3 native module)
npm install

# 3. Start the app
npm start

If npm install fails on better-sqlite3 — ensure Python and Visual Studio Build Tools are installed, then:
npm install --build-from-source

Scripts

Command	Description
`npm start`	Start the app in development mode
`npm run package`	Bundle app + Electron binary into `out/`
`npm run make`	Build a platform installer from the package

First Run Notes

SQLite database is created automatically on first launch (stored in the OS app-data folder).
All table migrations run on startup — no manual DB setup needed.
Default seed data is inserted once: status values and document templates.

Building Executables

You must build on the target platform. Cross-platform builds are not supported (e.g. cannot build a macOS .dmg from Windows).

Step 1 — Package

Bundles source + Electron binary into a folder.

npm run package

Output: out/electron-ai-sdlc-<platform>-<arch>/

Step 2 — Make Installer

Creates the platform installer from the packaged output.

npm run make

Output: out/make/

Platform Outputs

Windows

npm run make

Output: out/make/squirrel.windows/x64/electron-ai-sdlc Setup.exe
Requires Visual Studio Build Tools for native module compilation.

macOS

npm run make

Output: out/make/zip/darwin/x64/electron-ai-sdlc-darwin-x64-1.0.0.zip
For a signed .dmg, configure packagerConfig.osxSign and osxNotarize in forge.config.js.

Linux

npm run make

DEB: out/make/deb/x64/electron-ai-sdlc_1.0.0_amd64.deb
RPM: out/make/rpm/x64/electron-ai-sdlc-1.0.0.x86_64.rpm

# Install DEB
sudo dpkg -i electron-ai-sdlc_1.0.0_amd64.deb

# Install RPM
sudo rpm -i electron-ai-sdlc-1.0.0.x86_64.rpm

Maker Reference (`forge.config.js`)

Maker	Platform	Output
`maker-squirrel`	Windows	`.exe` installer
`maker-zip`	macOS	`.zip` archive
`maker-deb`	Linux	`.deb` package
`maker-rpm`	Linux	`.rpm` package

asar: true — bundles all source into an .asar archive inside the installer.
plugin-auto-unpack-natives — automatically rebuilds better-sqlite3 for the correct Electron version. No manual rebuild needed.

Tech Stack & Architecture

Layer	Technology
Desktop shell	Electron v41
Database	SQLite via `better-sqlite3` (runs in main process)
IPC	`contextBridge` + `ipcMain.handle` + `ipcRenderer.invoke`
Renderer	Plain ES modules (`file://`) — no bundler, no framework
Styling	Vanilla CSS with CSS variables (dark/light theme)
Build tooling	Electron Forge v7
AI agent	Python subprocess (`devflow_agent.py`) — agentic loop with tool use
Vector search	ChromaDB + `sentence-transformers` (RAG for codebase context)
AI backends	Anthropic SDK, Ollama HTTP, Google Gemini, OpenAI-compatible API, CLI

AI-First Architecture

User → Prompt Queue / AI Console / Mockups
          ↓
    IPC → Node.js Main Process
          ↓
    DevFlow Agent (Python subprocess)
      ├── Agentic loop (LLM → tool calls → execution)
      ├── RAG (ChromaDB semantic code search)
      ├── Full repo map + context injection
      ├── Tool use: file I/O, git, build, test
      └── Auto-retry on build failure

The agent is autonomous: it reads your codebase, understands the context via RAG, makes multi-step tool calls, and retries on failure. You approve the plan; the agent drives execution.

Database Tables

Table	Purpose
`projects`	Top-level projects
`features`	Features per project
`user_stories`	User stories per feature
`prompts`	Implementation prompts per user story
`prompt_history`	Execution history for every agent run
`model_configs`	AI model configurations and credentials
`screen_designs`	AI-generated mockups with prompt history
`screen_prompt_history`	History of mockup generation prompts
`status_master`	Shared status values (Backlog, Done, etc.)
`quick_commands`	Reusable prompt snippets
`document_templates`	Built-in Markdown templates
`project_documents`	Documents per project
`document_attachments`	SVG / draw.io files attached to documents

IPC Channels

db:* — all database read/write operations
chat:* — streaming AI responses (Anthropic, Ollama, CLI)
queue:* — prompt queue execution, plan/approve/execute workflow, agent lifecycle
ollama:* — Ollama model detection and inference
shell:openDrawio — write temp .drawio file and open in desktop app
shell:readFile — read a file path (used for draw.io Sync)
terminal:* — terminal execution and streaming output
dialog:* — native OS file/folder pickers
window:expand — resize the app window
promptQueue:runSummary — structured run metrics emitted after each agent run (turns, tokens, elapsed, files written)

E2E running

npm test # headless npm run test:watch # with visible window npm run test:debug # open HTML report npm run test:report #testing report

Name		Name	Last commit message	Last commit date
Latest commit History 564 Commits
.claude		.claude
agent-cli		agent-cli
agent		agent
assets		assets
docs		docs
src		src
tests/e2e		tests/e2e
.claudeignore		.claudeignore
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
forge.config.js		forge.config.js
mockup-login.html		mockup-login.html
package-lock.json		package-lock.json
package.json		package.json
playwright.config.js		playwright.config.js

Folders and files

Latest commit

History

Repository files navigation