AgentDevFramework

A unified AI development framework synthesizing the best elements from four leading methodologies—BMAD-METHOD, Spec-Kit, Context Engineering, and PRPs Agentic Engineering—into a compact, rapidly deployable system optimized for one-pass implementation success.

🚀 Quick Start (< 5 Minutes)

Intelligent Initialization (Recommended)

# 1. Clone and install
git clone <your-repo-url>
cd AgentDevFramework
npm install

# 2. Interactive initialization
npm run init

The init script will:

• 🔍 Detect if this is a new or existing project
• 📊 Analyze existing documentation (if any)
• 💡 Recommend optimal workflow (Rapid/Spec-Driven/BMAD)
• ⚙️ Generate tailored configuration
• 📚 Collect documentation URLs
• 🚀 Deploy to your chosen tool

Manual Deployment (Fast)

# 1. Set up environment
cp .env.template .env
# Edit .env with your API keys

# 2. Deploy directly
npm run deploy -- --tool windsurf

Supported Tools: windsurf, cursor, vscode, vscode-insider, kiro, trae, claude-code, gemini-cli, codex-cli

🎯 Core Features

• Unified Agent System: Specialized agents (Analyst, PM, Architect, Dev, QA, SM) with BMAD personas
• Constitutional Governance: 9 immutable principles ensuring quality and preventing technical debt
• Context Engineering: Built-in SELECT/WRITE/COMPRESS/ISOLATE patterns
• PRP Methodology: One-pass implementation with 4-level validation (Syntax, Unit, Integration, Creative)
• Multi-Tool Support: One framework, 9 development tools, one command deployment
• MCP Integration: 7 MCP tools pre-configured (context7, brave-search, mem0, archon, etc.)
• Interactive Documentation: Guided collection or direct URL input for project docs
• Hybrid Workflows: Scales from rapid (Story PRPs) to comprehensive (Planning PRPs with diagrams)
• Information Density: Context-first approach with comprehensive documentation and validation loops

📁 Directory Structure

AgentDevFramework/
├── shared/                  # Shared across all tools
│   ├── agents/             # Agent definitions
│   ├── templates/          # Document templates
│   ├── workflows/          # Workflow definitions
│   ├── memory/             # Constitution & preferences
│   └── mcp/                # MCP configurations
├── tools/                  # Tool-specific configs
│   ├── windsurf/
│   ├── cursor/
│   ├── vscode/
│   ├── vscode-insider/
│   ├── kiro/
│   ├── trae/
│   ├── claude-code/
│   ├── gemini-cli/
│   └── codex-cli/
├── scripts/                # Automation
│   ├── deploy.js          # Main deployment
│   ├── init-docs.js       # Documentation setup
│   └── validate.js        # Configuration validator
└── docs/                   # Framework documentation

🎓 Workflows

Level 1: Rapid Development (PRP)

Story/Task PRP → Execute with 4-Level Validation

Time: 5-15 minutes | Best For: Sprint tasks, bug fixes, solo dev

Level 2: Specification-Driven (Balanced)

Constitution → Base PRP/Spec → Clarify → Plan → Tasks → Implement with 4-Level Validation

Time: 30-60 minutes | Best For: New features, clear scope, teams

Level 3: BMAD Comprehensive

Constitution → Research → Planning PRP/PRD → Architecture → Stories → Dev (TDD) → QA + 4-Level Validation

Time: 2-4 hours | Best For: Complex projects, enterprise, unclear requirements

🤖 Agents

• Analyst: Market research, competitor analysis, project briefs
• PM: PRD creation with epics, stories, requirements
• Architect: System design, tech stack, architecture documents
• Dev: TDD implementation with context engineering
• QA: Risk assessment, test design, quality gates
• SM: Story creation with full context

🔧 MCP Tools

Pre-configured and ready to use:

• context7: Current framework documentation
• brave-search: Web search for latest info
• mem0: Persistent memory across sessions
• clear-thought: Structured reasoning
• archon: Project knowledge management
• openmemory: Alternative memory system
• deepwiki: GitHub repository docs

📜 Constitutional Principles

1. Specification-First Development
2. Test-First Development (TDD)
3. Simplicity First
4. Context-Engineered Documentation
5. Memory Management
6. Modular Agent System
7. Constitutional Checks
8. Security by Design
9. Performance as Requirement

🛠️ Commands

# Deployment
npm run deploy -- --tool <name>                    # Deploy to specific tool
npm run deploy -- --tool <name> --force           # Force overwrite
npm run deploy -- --tool <name> --mcp-only        # Only MCP config

# Documentation Setup
npm run init-docs                                  # Interactive doc collection
npm run init-docs -- --urls file.txt              # From URL file

# Validation
npm run validate                                   # Validate configuration
npm run validate:env                               # Check environment vars
npm run validate:mcp                               # Check MCP setup

# Development
npm run build                                      # Build framework
npm run test                                       # Run tests
npm run format                                     # Format code
npm run lint                                       # Lint code

🎨 Tool-Specific Features

Each tool deployment leverages unique capabilities:

• Windsurf: Cascade for multi-file ops, memories
• Cursor: Composer, rules system
• VSCode: Copilot integration, workspace settings
• Kiro: Product/technical/style separation
• Claude Code: Native slash commands
• Gemini CLI: CLI-optimized prompts
• Codex CLI: Home directory config

📖 Documentation

• Quick Start Guide
• Framework Architecture
• Agent Reference
• Template Guide
• MCP Integration
• Tool Configuration
• Troubleshooting

🔐 Environment Variables

Required in .env:

# MCP Tools
CONTEXT7_API_KEY=          # Optional - higher rate limits
BRAVE_API_KEY=             # Required - free tier available
OPENAI_API_KEY=            # Required for mem0, archon
SUPABASE_URL=              # Required for archon
SUPABASE_SERVICE_ROLE_KEY= # Required for archon
OPENMEMORY_API_KEY=        # Required for openmemory

🚦 Getting Started

1. Choose Your Workflow

Detailed Planning (BMAD-style):

• Use when: Complex projects, team collaboration, enterprise
• Start with: /analyst or /pm
• Creates: PRD, Architecture, Stories

Rapid Development (Context Engineering):

• Use when: Small features, solo dev, prototyping
• Start with: /generate-prp INITIAL.md
• Creates: PRP with validation

Spec-Driven (Spec-Kit style):

• Use when: Clear requirements, need validation gates
• Start with: /constitution → /specify
• Creates: Constitution, Spec, Plan, Tasks

2. Deploy to Your Tool

npm run deploy -- --tool windsurf

3. Set Up Documentation

npm run init-docs

Follow prompts to add project documentation URLs.

4. Start Developing

Use agent commands and MCP tools based on your chosen workflow.

🎯 Best Practices

1. Always start with Constitution: Define principles before coding
2. Use MCP tools liberally: @context7 for current docs, mem0 for memory
3. Follow TDD: Tests before implementation
4. Save key decisions: Use mem0 to preserve reasoning
5. Compress context: Use COMPRESS pattern when context grows
6. Examples are critical: Maintain examples/ folder
7. Constitutional compliance: Validate against principles

🤝 Contributing

Contributions welcome! Please:

1. Follow constitutional principles
2. Validate with npm run validate
3. Format with npm run format
4. Test with multiple tools
5. Update documentation

📄 License

MIT License - see LICENSE file

🙏 Acknowledgements

This framework synthesizes innovations from four leading methodologies:

• BMAD-METHOD by BMad Code, LLC - GitHub
• Spec-Kit by GitHub (Den Delimarsky, John Lam) - GitHub
• Context Engineering by Cole Medin - GitHub
• PRPs Agentic Engineering by Rasmus Widing - GitHub

📞 Support

• 📝 Documentation
• 🐛 Issues
• 💬 Discussions

---

Built with ❤️ for the AI-assisted development community