🚀 AgentForge

Professional AI Agent Development Framework for JavaScript/TypeScript

AgentForge is a production-ready framework for building autonomous AI agent teams that handle complex software development tasks. Built on modern JavaScript/TypeScript with enterprise-grade reliability and support for multiple IDEs (Cursor, VS Code, Windsurf).

✨ Features

• 🎯 Multi-IDE Support - Works with Cursor, VS Code, Windsurf, and any BMAD-compatible IDE
• 📦 Comprehensive Agent Bundles - Self-contained agents with all dependencies embedded (20-140 KB per agent)
• 🤖 Specialized AI Agents - Developer, QA, UX/UI, Architect, Security, Refactor, Product roles
• 📝 Automatic Documentation - Agents generate docs in docs/ (epics, wireframes, diagrams, architecture)
• 🧠 Intelligent Context Sharing - Agents learn from documentation and each other's work
• 📚 Knowledge Base - Automatic documentation indexing and intelligent retrieval
• 🎨 Pattern Library - Built-in coding patterns and best practices
• 🔄 Intelligent Orchestration - Coordinate multiple agents with parallel execution
• 💾 Advanced Memory System - Vector and graph databases for agent learning
• 📊 Built-in Monitoring - Real-time metrics, logging, and observability
• 🔌 Extensible Architecture - Plugin system for GitHub, Jira, Slack integrations
• 🎯 Confidence Scoring - Agents self-assess and request help when needed
• ⚡ High Performance - Async/await, streaming responses, efficient orchestration
• 📦 TypeScript First - Full type safety and excellent IDE support

🚀 Quick Start

Installation

# Install globally
npm install -g agent-forge

# Or use npx (no installation required)
npx agent-forge --help

Create a New Project

# Auto-detect your IDE
agent-forge create my-project

# Or specify your IDE explicitly
agent-forge create my-project --ide cursor
agent-forge create my-project --ide vscode
agent-forge create my-project --ide windsurf

Initialize in Existing Project

# In your project directory
cd my-existing-project
agent-forge init

# Or specify IDE
agent-forge init --ide cursor

Navigate to Your Project

cd my-project

Start Using Agents

The workflow depends on your IDE:

Cursor IDE

1. Open the project in Cursor
2. Type @af-hyperion in the chat
3. Describe what you want to build

VS Code

1. Open the project in VS Code
2. Install GitHub Copilot extension
3. Use GitHub Copilot Chat with AgentForge tools

Windsurf IDE

1. Open the project in Windsurf
2. Type @af-hyperion in the chat
3. Agents work natively with BMAD support

📁 Project Structure

my-project/
├── .cursor/                  # Cursor IDE configuration
│   ├── rules/agent-forge/   # Agent rules for Cursor
│   └── AGENT_FORGE_README.md
├── .vscode/                  # VS Code configuration
│   ├── agent-forge/         # Agent configs for VS Code
│   ├── settings.json
│   └── AGENT_FORGE_README.md
├── .windsurf/                # Windsurf IDE configuration
│   ├── rules/agent-forge/   # Agent rules for Windsurf
│   ├── config.json
│   └── AGENT_FORGE_README.md
├── docs/                     # AUTO-GENERATED DOCUMENTATION
│   ├── epics/               # Product epics
│   ├── user-stories/        # User stories
│   ├── architecture/        # Architecture docs & ADRs
│   ├── diagrams/            # System & flow diagrams
│   ├── wireframes/          # UX/UI wireframes & mockups
│   ├── database/            # DB schemas & ER diagrams
│   ├── api/                 # API documentation
│   └── README.md            # Documentation index
├── .agent-forge/             # Agent configurations
└── src/                      # Your application code

🤖 Available Agents

| Agent | ID | Role | Capabilities | |-------|-----|------|--------------| | Hyperion | @af-hyperion | Lead Implementation Orchestrator | Full delivery workflow coordination, automatic QA/Security/Refactor | | Developer | @af-dev | Code Implementation Specialist | Feature development, bug fixes, self-review, testing | | UX Designer | @af-ux | User Experience Specialist | Wireframes, user flows, user research, usability testing | | UI Designer | @af-ui | Visual Design Specialist | Mockups, style guides, design systems, component libraries | | QA | @af-qa | Quality Navigator | Test planning, execution, verdict assessment (PASS/CONCERNS/FAIL) | | Security | @af-security | Cyber Resilience Lead | Security audits, threat modeling, vulnerability assessment | | Refactor | @af-refactor | Codebase Steward | Code quality analysis, technical debt management, performance | | Architect | @af-arch | System Architect | Architecture design, ADR generation, system diagrams | | Product | @af-product | Product Partner | Requirements analysis, story writing, acceptance criteria, epics |

📄 Automatic Documentation

All design and architecture agents automatically generate documentation in the docs/ directory:

• Product Agent → docs/epics/ and docs/user-stories/
• UX Agent → docs/wireframes/ and user flow diagrams
• UI Agent → docs/wireframes/ (style guides and design systems)
• Architect Agent → docs/architecture/ and docs/diagrams/
• Developer Agent → docs/api/ (technical documentation)

Documentation includes:

• 📋 Epics and user stories (Markdown)
• 🎨 Wireframes and mockups (Markdown + Mermaid diagrams)
• 🏗️ Architecture diagrams (Mermaid format)
• 🗄️ Database ER diagrams (Mermaid format)
• 🎭 Style guides and design systems (Markdown)
• 📊 Flow diagrams and user journeys (Mermaid format)

📖 Example Usage

Simple Feature Request (Any IDE)

@af-dev create a REST API endpoint for user management with TypeScript

Full Delivery Workflow (Cursor/Windsurf)

@af-hyperion *deliver shopping cart feature with payment integration

Security Audit

@af-security review this authentication implementation for vulnerabilities

Code Refactoring

@af-refactor analyze and improve the database query performance

UX Design

@af-ux create wireframes for the user onboarding flow

Result: Generates wireframes documentation in docs/wireframes/ with user flows and interaction patterns!

UI Design

@af-ui create a comprehensive design system for our dashboard

Result: Generates style guide in docs/wireframes/ with colors, typography, and component specifications!

Context Sharing

# All agents automatically read documentation and learn from each other!
# Developer agent sees UX decisions, UX agent sees security concerns, etc.

@af-hyperion *deliver user profile feature

Result:

• ✅ UX Agent reads existing design docs
• ✅ UI Agent follows style guide automatically
• ✅ Developer sees UX wireframes and implements accurately
• ✅ Security Agent reviews and shares concerns
• ✅ All agents learn from each other's decisions!

🔧 IDE-Specific Setup

Cursor IDE Setup

Cursor provides the best AgentForge experience with native agent support:

npx agent-forge init --ide cursor

Features:

• ✅ Inline agent mentions (@af-*)
• ✅ BMAD rule support (.mdc files)
• ✅ Live workspace context
• ✅ Custom commands (*help, *deliver, etc.)
• ✅ Auto-activation

Usage:

1. Open project in Cursor
2. Chat panel: @af-hyperion
3. Type: *help for commands

VS Code Setup

VS Code works through GitHub Copilot and MCP protocol:

npx agent-forge init --ide vscode

Requirements:

• GitHub Copilot extension
• GitHub Copilot Chat extension

Features:

• ✅ MCP protocol support
• ✅ GitHub Copilot integration
• ✅ Tool-based agent invocation

Usage:

1. Open project in VS Code
2. GitHub Copilot Chat: Use natural language
3. Example: "Use the Developer agent to create a user API"

Windsurf IDE Setup

Windsurf has native BMAD support, making integration seamless:

npx agent-forge init --ide windsurf

Features:

• ✅ Native BMAD compatibility
• ✅ Inline agent mentions
• ✅ Full workspace context
• ✅ Custom commands

Usage:

1. Open project in Windsurf
2. Chat panel: @af-hyperion
3. Full feature parity with Cursor

🏗️ Architecture

AgentForge follows a modular, event-driven architecture:

┌─────────────────────────────────────────┐
│         Your Application                │
│  ┌────────────────────────────────────┐ │
│  │      Orchestrator                  │ │
│  │  ┌──────────┐  ┌──────────┐       │ │
│  │  │ Developer │  │    QA    │       │ │
│  │  │  Agent   │  │  Agent   │       │ │
│  │  └──────────┘  └──────────┘       │ │
│  │  ┌──────────┐  ┌──────────┐       │ │
│  │  │ Security │  │ Refactor │       │ │
│  │  │  Agent   │  │  Agent   │       │ │
│  │  └──────────┘  └──────────┘       │ │
│  └────────────────────────────────────┘ │
└─────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│      AgentForge Core                    │
│  ┌────────────┐  ┌──────────┐          │
│  │  Event Bus │  │  Memory  │          │
│  │            │  │  System  │          │
│  └────────────┘  └──────────┘          │
│  ┌────────────┐  ┌──────────┐          │
│  │ LLM Client │  │IDE Adaptr│          │
│  └────────────┘  └──────────┘          │
└─────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│      External Services                  │
│  ┌──────────┐  ┌──────────┐            │
│  │Anthropic │  │  OpenAI  │            │
│  └──────────┘  └──────────┘            │
└─────────────────────────────────────────┘

🔄 Workflows

Coordinate multiple agents to complete complex tasks:

import { Orchestrator } from 'agent-forge';

const workflow = {
  id: 'feature-development',
  name: 'Full Feature Development',
  stages: [
    {
      id: 'design',
      agentId: 'architect',
      task: { /* architecture task */ }
    },
    {
      id: 'implement',
      agentId: 'developer',
      task: { /* implementation task */ },
      dependencies: ['design']
    },
    {
      id: 'test',
      agentId: 'qa',
      task: { /* testing task */ },
      dependencies: ['implement']
    },
    {
      id: 'security',
      agentId: 'security',
      task: { /* security audit */ },
      dependencies: ['implement']
    }
  ]
};

const orchestrator = new Orchestrator();
const result = await orchestrator.executeWorkflow(workflow);

📦 Package Structure

AgentForge is now a single unified package containing:

• Core Framework - Agent system, orchestrator, memory, events
• Context & Documentation - Knowledge base, pattern library, doc generation
• IDE Integration - Multi-IDE support (Cursor, VS Code, Windsurf)
• CLI Tool - Project initialization and management
• Agent Assets - Pre-configured agent rules and templates

Install once, use everywhere:

npm install -g agent-forge

🛠️ Development

# Clone repository
git clone https://github.com/XoAuraHiru/agent-forge.git
cd agent-forge

# Install dependencies
npm install

# Build the package
npm run build

# Test locally
npm link
agent-forge --version
agent-forge create test-project

# Run in development mode
npm run dev

# Build for production (with minification)
npm run build:prod

# Run tests
npm test

🎯 Roadmap

✅ Phase 1: Foundation (Completed)

• [x] Core framework architecture
• [x] Multi-IDE support (Cursor, VS Code, Windsurf)
• [x] BaseAgent implementation
• [x] Orchestrator system
• [x] Memory system
• [x] Event bus
• [x] LLM client
• [x] CLI tool

🚧 Phase 2: Expansion (In Progress)

• [ ] Real vector database providers (Pinecone, Weaviate)
• [ ] Graph memory implementation (Neo4j)
• [ ] Plugin system (GitHub, Jira, Slack)
• [ ] Comprehensive testing
• [ ] Example projects
• [ ] Documentation site

📋 Phase 3: Polish (Planned)

• [ ] Performance optimization
• [ ] Advanced monitoring dashboard
• [ ] Cloud deployment
• [ ] Community features
• [ ] npm publication

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

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

📖 Documentation

Essential Guides

• Agents Reference - All 9 agents, their commands, and examples
• Adding Custom Agents - Step-by-step guide to create new agents
• Implementation Guide - Deep technical documentation

Additional Resources

• IDE Integration - IDE-specific setup
• Testing Guide - How to test agents
• Publishing Guide - Build and publish
• Full Documentation Index - Complete docs navigation

📝 License

MIT © 2025

See LICENSE for more information.

🙏 Acknowledgments

• Built on the BMAD (Build, Measure, Analyze, Deploy) method
• Inspired by modern AI agent frameworks
• Built with ❤️ for the developer community
• Powered by Anthropic Claude and OpenAI GPT

📧 Support

• 🐛 Issue Tracker
• 💬 Discussions
• 📖 Documentation