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