DevPlan Orchestrator (devussy)

🚀 An AI-powered development planning tool that transforms your ideas into detailed, executable development plans

Now with a fully functional web interface! 🌐

DevPlan Orchestrator is a Python-based LLM orchestration tool that automatically generates and maintains comprehensive development plans by coordinating multiple AI providers. Perfect for developers, project managers, and teams who want to accelerate their planning process with AI.

Overview

DevPlan Orchestrator accepts user inputs (project requirements, languages, frameworks) and generates detailed, executable development plans. It supports multiple LLM providers (OpenAI, Requesty, generic OpenAI-compatible APIs) and integrates with Git for automatic documentation and version control.

✨ Features

� Web Interface (NEW! 🚧 In Progress): Browser-based UI for non-technical users - no command line needed!
�🎭 Multi-LLM Configuration: Use different models/providers for each pipeline stage - optimize costs and performance
🔌 Provider-Agnostic: Support for OpenAI, Generic OpenAI-compatible APIs, and custom providers
⚡ Async Performance: Efficient concurrent API calls with configurable rate limiting
🔄 Multi-Phase Pipeline: project design → basic plan → detailed plan → handoff prompt
💾 State Persistence: Resumable workflows with checkpoint system - never lose progress
🎯 Git Integration: Automatic commits and version control for all generated artifacts
📝 Documentation Generation: Beautiful, structured documentation with Jinja2 templates
🧪 Battle-Tested: 414 passing tests with 73% code coverage
🛡️ Robust: Exponential backoff retry logic and comprehensive error handling
🎨 Flexible: Customizable templates and configuration for your workflow
🎨 Interactive Mode: Guided questionnaire for easy project setup
🔐 Secure Configuration: Encrypted API key storage with web-based management

Installation

From PyPI (Recommended)

pip install devussy

From Source

Clone the repository

git clone https://github.com/mojomast/devussy-fresh.git
cd devussy-fresh

Install in development mode
```
pip install -e .
```
Or with development dependencies:
```
pip install -e ".[dev]"
```
Configure environment variables Copy .env.example to .env and fill in your API keys:
```
cp .env.example .env
```
Required environment variables:
- OPENAI_API_KEY - Your OpenAI API key (for OpenAI provider)
- GENERIC_API_KEY - API key for generic OpenAI-compatible providers
- GENERIC_API_BASE_URL - Base URL for generic provider
- REQUESTY_API_KEY - API key for Requesty provider (optional)
NEW: Per-Stage API Keys (optional):
- DESIGN_API_KEY - API key specifically for design stage
- DEVPLAN_API_KEY - API key specifically for devplan stage
- HANDOFF_API_KEY - API key specifically for handoff stage
See Multi-LLM Configuration Guide for details on using different models per stage.

Verify Installation

After installation, verify that the CLI is working:

devussy version

You should see version 0.3.2 and the tool information.

Quick Start

Option 1: Web Interface (Recommended for All Users) 🌐

The fully functional browser-based interface! Perfect for both technical and non-technical users.

Start the servers:

# Terminal 1: Start the backend API
python -m src.web.app

# Terminal 2: Start the frontend dev server
cd frontend
npm install  # First time only
npm run dev

Visit: http://localhost:3000

Features:

✨ Project Management: Create, monitor, and manage devplan projects
📊 Analytics Dashboard: View project statistics and success metrics
🔍 Search & Filter: Find projects quickly with real-time search and filters
📋 Template System: Save successful configurations for reuse
- Create templates from completed projects
- Search templates by name/description or filter by tags
- Export/import templates as JSON files
🎨 Dark Mode: Toggle between light and dark themes
📝 Markdown Viewer: Beautiful rendering of documentation with syntax highlighting
📥 File Operations: Download individual files or entire project as ZIP
⚡ Live Progress: Real-time WebSocket streaming during generation
🔐 Configuration Management: Secure API key storage and testing
📄 Pagination: Browse through large project lists easily (12 per page)

Note: Web interface is now fully functional and production-ready (Phases 11-16 complete)!

Backend: 100% complete with comprehensive testing
Frontend: 100% complete with 42 component tests
All features working including real-time updates, templates, dark mode, and more!

Option 2: Interactive CLI Mode (For Command Line Users)

The easiest way to get started is with the interactive questionnaire:

devussy interactive-design

You'll be guided through a series of questions to define your project, and the tool will generate a complete design for you.

Option 3: Command-Line Mode (For Automation)

Initialize a new project:

devussy init-repo ./my-project

Generate a complete development plan:

devussy run-full-pipeline \
  --name "My Web App" \
  --languages "Python,TypeScript" \
  --requirements "Build a REST API with authentication" \
  --frameworks "FastAPI,React"

CLI Commands

`init-repo` - Initialize Repository

Initialize a new project repository with DevPlan Orchestrator structure.

devussy init-repo [PATH] [OPTIONS]

Arguments:

PATH - Path to initialize (defaults to current directory)

Options:

--remote, -r - Git remote URL to add
--force, -f - Force initialization even if directory not empty

Example:

devussy init-repo ./my-project --remote https://github.com/mojomast/devussy.git

`generate-design` - Generate Project Design

Generate a project design from user inputs.

devussy generate-design [OPTIONS]

Required Options:

--name, -n - Project name
--languages, -l - Comma-separated programming languages
--requirements, -r - Project requirements

Optional Options:

--frameworks, -f - Comma-separated frameworks
--apis, -a - Comma-separated external APIs
--config, -c - Path to config file
--provider, -p - LLM provider override (openai, generic, requesty)
--model, -m - Model override
--output-dir, -o - Output directory
--output-path - Specific output file path
--streaming - Enable token streaming
--verbose, -v - Enable verbose logging
--debug - Enable debug mode with full tracebacks

Example:

devussy generate-design \
  --name "E-commerce API" \
  --languages "Python,JavaScript" \
  --requirements "Build a scalable e-commerce backend" \
  --frameworks "FastAPI,PostgreSQL" \
  --apis "Stripe,SendGrid" \
  --verbose

`interactive-design` - Interactive Project Design (✨ NEW!)

Generate a project design through an interactive guided questionnaire. Perfect for users who prefer a conversational experience over command-line flags.

devussy interactive-design [OPTIONS]

Features:

🎯 Guided questionnaire with helpful prompts
💡 Smart conditional questions based on your answers
📝 Examples and help text for each question
💾 Save and resume sessions
🎨 Beautiful CLI interface with progress indicators

Options:

--config, -c - Path to config file
--provider, -p - LLM provider override
--model, -m - Model override
--output-dir, -o - Output directory
--save-session - Save session to file (path)
--resume-session - Resume from saved session (path)
--streaming - Enable token streaming
--verbose, -v - Enable verbose logging
--debug - Enable debug mode

Example - Basic Interactive Session:

devussy interactive-design
# Follow the prompts to answer questions about your project

Example - Save Session:

devussy interactive-design --save-session my-project-session.json

Example - Resume Previous Session:

devussy interactive-design --resume-session my-project-session.json

Questions Asked: The interactive questionnaire covers:

Project name and type (Web App, API, CLI, etc.)
Programming languages
Frameworks (frontend/backend)
Database requirements
Authentication needs
External API integrations
Deployment platform
Testing and CI/CD requirements
Documentation level

Questions adapt based on your answers - for example, frontend framework questions only appear if you're building a web application.

`generate-devplan` - Generate Development Plan

Generate a development plan from an existing project design.

devussy generate-devplan DESIGN_FILE [OPTIONS]

Arguments:

DESIGN_FILE - Path to project design JSON file

Options:

--config, -c - Path to config file
--provider, -p - LLM provider override
--model, -m - Model override
--output-dir, -o - Output directory
--output-path - Specific output file path
--max-concurrent - Maximum concurrent API requests
--streaming - Enable token streaming
--verbose, -v - Enable verbose logging
--debug - Enable debug mode with full tracebacks

Example:

devussy generate-devplan docs/design.json --max-concurrent 10 --verbose

`generate-handoff` - Generate Handoff Prompt

Generate a handoff prompt from a development plan.

devussy generate-handoff DEVPLAN_FILE [OPTIONS]

Arguments:

DEVPLAN_FILE - Path to devplan JSON file

Required Options:

--name, -n - Project name

Options:

--config, -c - Path to config file
--output-dir, -o - Output directory
--output-path - Specific output file path
--verbose, -v - Enable verbose logging
--debug - Enable debug mode with full tracebacks

Example:

devussy generate-handoff docs/devplan.json --name "My Project"

`run-full-pipeline` - Complete Pipeline

Run the complete pipeline from inputs to handoff prompt.

devussy run-full-pipeline [OPTIONS]

Required Options:

--name, -n - Project name
--languages, -l - Comma-separated programming languages
--requirements, -r - Project requirements

Optional Options:

--frameworks, -f - Comma-separated frameworks
--apis, -a - Comma-separated external APIs
--config, -c - Path to config file
--provider, -p - LLM provider override
--model, -m - Model override
--output-dir, -o - Output directory
--max-concurrent - Maximum concurrent API requests
--streaming - Enable token streaming
--verbose, -v - Enable verbose logging
--debug - Enable debug mode with full tracebacks

Example:

devussy run-full-pipeline \
  --name "ML Pipeline" \
  --languages "Python" \
  --requirements "Build a machine learning training pipeline" \
  --frameworks "PyTorch,FastAPI,Docker" \
  --provider openai \
  --model gpt-4 \
  --max-concurrent 5 \
  --verbose

`version` - Display Version

Display version information.

devussy version

Example Workflows

Workflow 1: New Project from Scratch

# Step 1: Initialize repository
devussy init-repo ./my-app

# Step 2: Navigate to directory
cd my-app

# Step 3: Set up environment variables
cp .env.example .env
# Edit .env and add your API keys

# Step 4: Generate complete plan
devussy run-full-pipeline \
  --name "My App" \
  --languages "Python,JavaScript" \
  --requirements "Build a web application with user auth" \
  --frameworks "FastAPI,React"

# Step 5: Review generated files
ls docs/
# Output: project_design.md  devplan.md  handoff_prompt.md

Workflow 2: Incremental Generation

# Step 1: Generate project design
devussy generate-design \
  --name "Data Pipeline" \
  --languages "Python" \
  --requirements "ETL pipeline for processing data" \
  --output-path ./design.json

# Step 2: Review and modify design.json if needed
cat design.json

# Step 3: Generate devplan from design
devussy generate-devplan design.json --output-path ./devplan.json

# Step 4: Generate handoff prompt
devussy generate-handoff devplan.json --name "Data Pipeline"

Workflow 3: Using Different LLM Providers

# Using OpenAI (default)
devussy run-full-pipeline \
  --name "Project" \
  --languages "Python" \
  --requirements "Build an API" \
  --provider openai \
  --model gpt-4

# Using a custom OpenAI-compatible API
export GENERIC_BASE_URL="https://api.example.com/v1"
export GENERIC_API_KEY="your-key"

devussy run-full-pipeline \
  --name "Project" \
  --languages "Python" \
  --requirements "Build an API" \
  --provider generic

Configuration

Configuration is managed through config/config.yaml. Key settings include:

Global LLM Settings

llm_provider: Choose from "openai", "generic", or "requesty"
model: Model identifier (e.g., "gpt-4")
temperature: Sampling temperature (0.0-2.0)
max_tokens: Maximum tokens to generate
api_key: API key (can also be set via environment variables)

Per-Stage LLM Settings (NEW! 🎭)

Override global settings for specific pipeline stages:

design_model: Model for project design generation
devplan_model: Model for devplan generation
handoff_model: Model for handoff prompt generation

Example - Cost Optimization:

# Use GPT-4 for complex design, GPT-3.5-turbo for structured devplan
model: gpt-4
devplan_model: gpt-3.5-turbo

Example - Different API Keys:

export DESIGN_API_KEY="sk-design-account-..."
export DEVPLAN_API_KEY="sk-devplan-account-..."

Other Settings

max_concurrent_requests: Limit concurrent API calls
retry: Retry settings for failed requests
streaming_enabled: Enable/disable token streaming

See config/config.yaml for all available options, or read the Multi-LLM Configuration Guide for detailed usage.

Documentation

Web Interface Guide - Browser-based UI for non-technical users (NEW! 🌐)
Multi-LLM Configuration Guide - Use different models per pipeline stage
Multi-LLM Quick Start - Quick reference for multi-LLM setup
Architecture Overview - System design and module descriptions
Provider Guide - How to add new LLM providers
Testing Guide - Testing strategy and coverage
API Documentation - Auto-generated API docs

Project Structure

devussy/
├── src/                    # Source code
│   ├── clients/            # LLM client implementations
│   │   ├── factory.py      # Client factory for provider selection
│   │   ├── openai_client.py    # OpenAI API client
│   │   ├── generic_client.py   # Generic OpenAI-compatible client
│   │   └── requesty_client.py  # Requesty API client
│   ├── pipeline/           # Pipeline stages
│   │   ├── project_design.py   # Project design generation
│   │   ├── basic_devplan.py    # Basic devplan generation
│   │   ├── detailed_devplan.py # Detailed devplan generation
│   │   ├── handoff_prompt.py   # Handoff prompt generation
│   │   └── compose.py      # Pipeline orchestration
│   ├── cli.py              # Command-line interface
│   ├── config.py           # Configuration management
│   ├── llm_client.py       # Abstract LLM client interface
│   ├── concurrency.py      # Concurrency control
│   ├── retry.py            # Retry logic with exponential backoff
│   ├── templates.py        # Template loading and rendering
│   ├── citations.py        # Citation embedding
│   ├── git_manager.py      # Git operations
│   ├── file_manager.py     # File operations
│   ├── doc_logger.py       # Documentation logging
│   ├── doc_index.py        # Documentation indexing
│   ├── models.py           # Data models
│   ├── logger.py           # Logging configuration
│   ├── run_scheduler.py    # Task scheduling
│   └── state_manager.py    # State persistence
├── tests/                  # Tests (117+ comprehensive tests)
│   └── unit/               # Unit tests
│       ├── test_config.py      # Configuration tests (34 tests)
│       ├── test_llm_clients.py # LLM client tests (29 tests)
│       ├── test_concurrency.py # Concurrency tests (13 tests)
│       ├── test_retry.py       # Retry logic tests (18 tests)
│       ├── test_templates.py   # Template tests (23 tests)
│       ├── test_documentation.py # Documentation tests
│       └── test_git_manager.py # Git integration tests (17 tests)
├── templates/              # Jinja2 prompt templates
│   ├── docs/               # Documentation templates
│   ├── project_design.jinja    # Project design prompt
│   ├── basic_devplan.jinja     # Basic devplan prompt
│   ├── detailed_devplan.jinja  # Detailed devplan prompt
│   └── handoff_prompt.jinja    # Handoff prompt template
├── config/                 # Configuration files
│   └── config.yaml         # Main configuration
├── docs/                   # Generated documentation
│   └── update_log.md       # Documentation update log
├── scripts/                # Build and utility scripts
│   └── build_docs.py       # API documentation generator
└── examples/               # Example projects (future)

Development

Running Tests

pytest tests/

Code Quality

# Format code
black src/

# Check style
flake8 src/

# Sort imports
isort src/

Running with Coverage

pytest --cov=src --cov-report=html tests/

Contributing

See CONTRIBUTING.md for guidelines on:

Setting up development environment
Running tests and linting
Submitting pull requests
Code style expectations

License

This project is licensed under the MIT License - see the LICENSE file for details.

Roadmap

Support

For questions, issues, or feature requests, please open an issue on the GitHub repository.

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github/workflows		.github/workflows
archive		archive
config		config
docs		docs
examples		examples
frontend		frontend
scripts		scripts
src		src
templates		templates
tests		tests
web_projects		web_projects
.env.example		.env.example
.flake8		.flake8
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
HANDOFF.md		HANDOFF.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
MULTI_LLM_GUIDE.md		MULTI_LLM_GUIDE.md
MULTI_LLM_QUICKSTART.md		MULTI_LLM_QUICKSTART.md
QUICKSTART_CONFIG.md		QUICKSTART_CONFIG.md
QUICK_REF.md		QUICK_REF.md
README.md		README.md
WARP.md		WARP.md
WEB_UI_QUICK_REF.md		WEB_UI_QUICK_REF.md
devplan.md		devplan.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
start-dev.ps1		start-dev.ps1
start-web-dev.ps1		start-web-dev.ps1

Folders and files

Latest commit

History

Repository files navigation

DevPlan Orchestrator (devussy)

Overview

✨ Features

Installation

From PyPI (Recommended)

From Source

Verify Installation

Quick Start

Option 1: Web Interface (Recommended for All Users) 🌐

Option 2: Interactive CLI Mode (For Command Line Users)

Option 3: Command-Line Mode (For Automation)

CLI Commands

init-repo - Initialize Repository

generate-design - Generate Project Design

interactive-design - Interactive Project Design (✨ NEW!)

generate-devplan - Generate Development Plan

generate-handoff - Generate Handoff Prompt

run-full-pipeline - Complete Pipeline

version - Display Version

Example Workflows

Workflow 1: New Project from Scratch

Workflow 2: Incremental Generation

Workflow 3: Using Different LLM Providers

Configuration

Global LLM Settings

Per-Stage LLM Settings (NEW! 🎭)

Other Settings

Documentation

Project Structure

Development

Running Tests

Code Quality

Running with Coverage

Contributing

License

Roadmap

Support

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`init-repo` - Initialize Repository

`generate-design` - Generate Project Design

`interactive-design` - Interactive Project Design (✨ NEW!)

`generate-devplan` - Generate Development Plan

`generate-handoff` - Generate Handoff Prompt

`run-full-pipeline` - Complete Pipeline

`version` - Display Version

Packages