Professional AI Agent Development Framework for JavaScript/TypeScript
npm install @agent-forge/coredocs/ (epics, wireframes, diagrams, architecture)
bash
Install globally
npm install -g agent-forge
Or use npx (no installation required)
npx agent-forge --help
`
$3
`bash
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
`
$3
`bash
In your project directory
cd my-existing-project
agent-forge init
Or specify IDE
agent-forge init --ide cursor
`
$3
`bash
cd my-project
`
$3
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 |
$3
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
$3
`
@af-dev create a REST API endpoint for user management with TypeScript
`
$3
`
@af-hyperion *deliver shopping cart feature with payment integration
`
$3
`
@af-security review this authentication implementation for vulnerabilities
`
$3
`
@af-refactor analyze and improve the database query performance
`
$3
`
@af-ux create wireframes for the user onboarding flow
`
Result: Generates wireframes documentation in docs/wireframes/ with user flows and interaction patterns!
$3
`
@af-ui create a comprehensive design system for our dashboard
`
Result: Generates style guide in docs/wireframes/ with colors, typography, and component specifications!
$3
`
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
$3
Cursor provides the best AgentForge experience with native agent support:
`bash
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
$3
VS Code works through GitHub Copilot and MCP protocol:
`bash
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"
$3
Windsurf has native BMAD support, making integration seamless:
`bash
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:
`typescript
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:
`bash
npm install -g agent-forge
`
---
🛠️ Development
`bash
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
$3
- [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
$3
- [ ] Real vector database providers (Pinecone, Weaviate)
- [ ] Graph memory implementation (Neo4j)
- [ ] Plugin system (GitHub, Jira, Slack)
- [ ] Comprehensive testing
- [ ] Example projects
- [ ] Documentation site
$3
- [ ] 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`)
Built with AgentForge
The future of AI-powered development