Agentic Workflow

A local-first AI agent orchestration system with multi-LLM role-based architecture for automated software development.

📖 Wiki | 💬 Discussions | 🐛 Issues | 📦 Releases

Overview

Agentic Workflow is a powerful, local-first orchestration system that leverages multiple specialized LLMs through Ollama to automate software development tasks. Each AI agent operates in a specific role (Planner, Analyzer, Creator, Tester, Inspector, Documenter), working together in a structured pipeline to transform natural language requirements into production-ready code.

Features

• Multi-LLM Orchestration: Uses specialized models optimized for different tasks
• Role-Based Architecture: Six distinct roles working in concert:
  • Planner: Breaks down tasks into actionable steps
  • Analyzer: Evaluates requirements and dependencies
  • Creator: Generates code and implementation
  • Tester: Validates functionality and catches bugs
  • Inspector: Reviews quality and enforces standards
  • Documenter: Creates comprehensive documentation
• Schema Validation: All AI outputs validated with Zod for reliability
• Self-Healing Pipeline: Configurable retry logic with intelligent feedback
• Memory System: Local vector store for context retrieval and learning
• Pipeline Engine: YAML-driven workflow execution
• Local-First: Runs entirely on your machine via Ollama

Prerequisites

• Node.js >= 18.0.0
• Ollama installed and running
• Required models (pulled automatically or manually):

  ollama pull llama3.1:8b
  ollama pull qwen2.5-coder:7b
  ollama pull deepseek-coder:6.7b
  ollama pull qwen2.5-coder:3b
  ollama pull nomic-embed-text

Installation

# Clone the repository
git clone https://github.com/coderooz/agentic-workflow.git
cd agentic-workflow

# Install dependencies
npm install

# Build the project
npm run build

Quick Start

# Run in development mode
npm run dev "Create a simple REST API with user authentication"

# Run the API server
npm run dev:server

Architecture

┌─────────────────────────────────────────┐
│              ORCHESTRATOR                │
│  Controller → Role Router               │
│  Execution Engine → Retry Manager       │
│  State Manager → Pipeline Engine        │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│                  ROLES                   │
│  Planner → Analyzer → Creator           │
│  Tester → Inspector → Documenter        │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│             SUPPORT SYSTEMS              │
│  Schemas (Zod) | Memory (Vector Store)  │
│  Tools (FS, Terminal, Browser, Git)     │
│  Config | Utils | Logger                │
└─────────────────────────────────────────┘

Configuration

Pipeline Settings

Edit src/config/pipeline.config.yaml to customize:

• Pipeline stages and their order
• Entry/exit conditions for each stage
• Maximum retries per stage
• Model assignments per role

Model Configuration

Edit src/config/models.config.ts to:

• Change default models for each role
• Adjust model parameters (temperature, top_p, etc.)
• Add custom model endpoints

Available Scripts

Command	Description
npm run build	Build TypeScript to JavaScript
npm run start	Run the compiled application
npm run dev	Run in development mode with tsx
npm run dev:server	Start the API server
npm run typecheck	Run TypeScript type checking
npm run lint	Run ESLint
npm run lint:fix	Fix ESLint issues automatically
npm run format	Format code with Prettier
npm run format:check	Check code formatting
npm run test	Run test suite

Project Structure

agentic-workflow/
├── src/
│   ├── config/          # Configuration files
│   ├── mcp/             # MCP protocol implementation
│   ├── memory/          # Vector store and context management
│   ├── orchestrator/    # Core orchestration engine
│   │   └── pipeline/    # Pipeline execution
│   ├── roles/           # AI role implementations
│   │   ├── planner/
│   │   ├── analyzer/
│   │   ├── creator/
│   │   ├── tester/
│   │   ├── inspector/
│   │   └── documenter/
│   ├── schemas/         # Zod validation schemas
│   ├── server/          # API server
│   ├── tools/           # Agent tools (FS, terminal, browser, git)
│   └── utils/           # Utility functions
├── .github/             # GitHub templates and workflows
├── package.json
├── tsconfig.json
└── README.md

Development

Adding a New Role

1. Create a new directory under src/roles/
2. Implement the role executor following existing patterns
3. Define the Zod schema in src/schemas/
4. Register the role in the orchestrator

Running Tests

npm run test

Code Style

This project uses ESLint and Prettier. Run the following before committing:

npm run lint:fix
npm run format
npm run typecheck

Contributing

We welcome contributions! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Author

Ranit Saha (Coderooz) — Developer & AI Engineer

• 🌐 coderooz.in — Portfolio & Services
• 📬 Contact Me
• ℹ️ About

License

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

Acknowledgments

• Ollama for local LLM inference
• Zod for schema validation
• All contributors who help improve this project