Transform your development workflow with SPARC methodology and AI-powered assistance
create-sparc is a powerful agentic toolkit that changes how you build software by integrating the structured SPARC methodology with advanced AI assistance through Roo Code and Model Context Protocol (MCP) capabilities. This comprehensive platform enables AI agents to securely connect with external services like databases, APIs, and cloud resources, allowing developers to create modular, secure, and maintainable applications with unprecedented efficiency while seamlessly bridging the gap between AI and real-world systems.
You don't need to install this package directly. Use npx to run it:
npx create-sparc initThe SPARC methodology (Specification, Pseudocode, Architecture, Refinement, Completion) breaks down complex development tasks into manageable phases, each handled by specialized AI assistants. This approach ensures:
- Structured Development: Clear progression through well-defined phases
- Modular Architecture: Code naturally organized into maintainable components
- Security by Design: No hard-coded secrets, proper configuration management
- Comprehensive Testing: Built-in test-driven development practices
- Thorough Documentation: Automatically generated, always up-to-date
To fully leverage the SPARC methodology, you'll need the Roo Code extension for Visual Studio Code. This powerful extension provides:
- AI-powered coding assistance with specialized modes for different development phases
- Context-aware interactions that understand your project structure
- Integrated task management with the Boomerang task concept
- Seamless file operations directly within your editor
You can install the Roo Code extension from the VS Code Marketplace.
- Scaffolds new projects with SPARC methodology structure
- Sets up .roo directory and .roomodes file for SPARC modes
- Supports TypeScript projects
- Configurable templates
- Symlink support for efficient file management
- MCP (Model Context Protocol) integration for external services
- Secure credential management
- Comprehensive documentation generation
MCP (Model-Context Protocol) is a powerful bridge between your applications and external services that enables AI-assisted interactions with databases, APIs, and cloud resources. With MCP integration in create-sparc, you can:
MCP allows your AI assistants to directly interact with external services like Supabase, OpenAI, GitHub, AWS, and Firebase through a standardized protocol. This means your Roo Code assistant can:
- Query databases without you writing SQL
- Deploy applications to cloud providers
- Manage infrastructure across multiple platforms
- Interact with APIs using natural language requests
- Generate and analyze data from various sources
MCP prioritizes security through:
- Environment variable references for all sensitive credentials
- Permission scoping that follows the principle of least privilege
- No hardcoded secrets in any configuration files
- Automatic security auditing to detect potential vulnerabilities
- Secure credential management with clear separation from code
The MCP Wizard makes setup simple:
- Interactive configuration guides you through connecting services
- Automatic discovery of available MCP servers
- Validation and verification of all configurations
- Clear documentation for each integration step
- Seamless updates when service requirements change
You can create a new project in two ways:
# Create a full project with a specific name
npx create-sparc init my-project
# Create only .roo and .roomodes files in the current directory
npx create-sparc initYou can also use the shorthand version:
npx create-sparc my-projectOptions:
--template <name>- Template to use (default: "default")--skip-install- Skip dependency installation--use-npm- Use npm as package manager--use-yarn- Use yarn as package manager--use-pnpm- Use pnpm as package manager--no-git- Skip git initialization--typescript- Use TypeScript--no-symlink- Disable symlink creation
If you want to add SPARC methodology to an existing project, you can run:
# Navigate to your project directory
cd my-existing-project
# Initialize SPARC files (.roo and .roomodes) without creating project structure
npx create-sparc initThis will only create the necessary SPARC files in your current directory without modifying your existing project structure.
npx create-sparc add component --name MyComponentOptions:
--name <name>- Component name--type <type>- Component type (default: "component")--path <path>- Custom path for component
npx create-sparc helpSPARC stands for:
- Specification
- Pseudocode
- Architecture
- Refinement
- Completion
This methodology provides a structured approach to software development, ensuring high-quality, maintainable code. SPARC enables you to deconstruct large, intricate projects into manageable subtasks, each delegated to a specialized mode.
The SPARC methodology is fully integrated with Roo Code through the Boomerang task concept. This integration empowers you to build complex, production-ready, secure, and scalable applications by leveraging specialized AI assistants for different phases of development.
By using advanced reasoning models such as Claude 3.7 Sonnet, GPT-4o, and DeepSeek for analytical tasks, alongside instructive models for coding, DevOps, testing, and implementation, you create a robust, automated, and secure workflow.
When you initialize a project with npx create-sparc init, the following specialized modes become available in your Roo Code environment:
- ⚡️ SPARC Orchestrator: Breaks down large objectives into delegated subtasks aligned to the SPARC methodology
- 📋 Specification Writer: Captures full project context and translates it into modular pseudocode with TDD anchors
- 🏗️ Architect: Designs scalable, secure, and modular architectures based on requirements
- 🧠 Auto-Coder: Writes clean, efficient, modular code based on pseudocode and architecture
- 🧪 Tester (TDD): Implements Test-Driven Development by writing tests first and refactoring after minimal implementation
- 🪲 Debugger: Troubleshoots runtime bugs, logic errors, or integration failures
- 🛡️ Security Reviewer: Performs static and dynamic audits to ensure secure code practices
- 📚 Documentation Writer: Writes concise, clear, and modular Markdown documentation
- 🔗 System Integrator: Merges the outputs of all modes into a working, tested, production-ready system
- 📈 Deployment Monitor: Observes the system post-launch, collecting performance, logs, and user feedback
- 🧹 Optimizer: Refactors, modularizes, and improves system performance
- ❓ Ask: Guides users in formulating precise, modular requests to delegate tasks
- 🚀 DevOps: Manages deployments and infrastructure operations across cloud providers
- 📘 SPARC Tutorial: Guides new users through the SPARC development process
- 🔐 Supabase Admin: Designs and implements database schemas, RLS policies, triggers, and functions for Supabase projects
- ♾️ MCP Integration: Connects to and manages external services through MCP interfaces
Each mode operates within its own isolated context, ensuring focused and efficient task management while adhering to best practices—avoiding hard-coded environment variables, maintaining files under 500 lines, and ensuring a modular, extensible design.
The MCP (Model Context Protocol) Wizard is a powerful feature that simplifies the configuration and management of external service integrations in your SPARC projects.
The MCP Wizard is a configuration system that enables seamless integration between your SPARC projects and external services like databases, AI models, cloud providers, and more. It provides:
- Simplified Service Configuration: Easily connect to external services with guided setup
- Secure Credential Management: Store API keys and tokens as environment variable references
- Permission Scoping: Configure appropriate access levels for each service
- AI Assistant Integration: Enable Roo Code to interact with external services
The MCP Configuration Wizard consists of the following components:
- MCP Wizard - Main entry point that orchestrates the configuration process
- Configuration Generator - Creates MCP.json configurations and roomode definitions
- Registry Client - Interacts with the MCP Registry API to discover available servers
- Security Module - Ensures proper handling of sensitive information
- File Manager - Provides safe and reliable file system operations for configurations
The MCP Wizard manages two main configuration files:
-
MCP Configuration File (
.roo/mcp.json): Contains server configurations, including command, arguments, and permission scopes. -
Roomodes File (
.roomodes): Contains roomode definitions for MCP servers, enabling AI assistants to interact with the servers.
Example MCP configuration:
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--access-token",
"${env:SUPABASE_ACCESS_TOKEN}"
],
"alwaysAllow": [
"list_tables",
"execute_sql"
]
}
}
}The MCP.json file follows this schema:
{
"mcpServers": {
"[server-id]": {
"command": "string",
"args": ["string"],
"alwaysAllow": ["string"],
"env": {
"ENV_VAR": "value"
}
}
}
}MCP integration roomodes follow this structure:
{
"slug": "mcp-[server-id]",
"name": "Server Name Integration",
"model": "claude-3-7-sonnet-20250219",
"roleDefinition": "You are a specialized assistant...",
"customInstructions": "Server-specific instructions...",
"groups": ["read", "edit", "mcp"],
"source": "project"
}You can configure MCP servers using the interactive wizard:
npx create-sparc configure-mcpThis will guide you through the process of:
- Discovering available MCP servers
- Configuring server parameters and credentials
- Setting appropriate permission scopes
- Generating and updating configuration files
- Run
npx create-sparc configure-mcp - Select "Add a new MCP server"
- Choose the server from the list or enter a server ID
- Provide the required parameters (API keys, project IDs, etc.)
- Review and confirm the configuration
- Set up the necessary environment variables
- Run
npx create-sparc configure-mcp - Select "Update an existing MCP server"
- Choose the server to update
- Modify the parameters as needed
- Review and confirm the changes
- Run
npx create-sparc configure-mcp - Select "Remove an MCP server"
- Choose the server to remove
- Confirm the removal
The MCP Wizard provides several command-line options:
# Start the interactive wizard
npx create-sparc configure-mcp
# List configured MCP servers
npx create-sparc configure-mcp --list
# Discover available MCP servers
npx create-sparc configure-mcp --discover
# Add a specific MCP server
npx create-sparc configure-mcp --add <server-id>
# Update a configured MCP server
npx create-sparc configure-mcp --update <server-id>
# Remove a configured MCP server
npx create-sparc configure-mcp --remove <server-id>
# Validate current MCP configuration
npx create-sparc configure-mcp --validate
# Create a backup of current configuration
npx create-sparc configure-mcp --backup
# Perform security audit on MCP configuration
npx create-sparc configure-mcp --security-audit
# Automatically fix security issues
npx create-sparc configure-mcp --security-audit --auto-fix
# Validate environment variable references
npx create-sparc configure-mcp --validate-envFor more advanced use cases, you can customize the MCP configuration:
# Use a custom registry URL
npx create-sparc configure-mcp --registry https://your-custom-registry.com/api
# Specify custom paths for configuration files
npx create-sparc configure-mcp --config-path custom/path/mcp.json --roomodes-path custom/path/roomodes
# Run in non-interactive mode (for CI/CD pipelines)
npx create-sparc configure-mcp --add supabase --no-interactiveThe MCP Wizard includes comprehensive security features:
-
Secure Credential Management
- Automatically detects sensitive parameters (API keys, tokens, passwords)
- Converts hardcoded values to environment variable references
- Provides clear instructions for setting up environment variables
- Warning when sensitive information is detected in configuration files
-
Permission Scoping
- Default permissions are set to the minimum required
- Clear warnings are provided when expanding beyond recommended permissions
- Detailed explanations of each permission's implications
- Validation against recommended permission sets
-
Security Auditing
- Scans configurations for security issues
- Categorizes issues by severity (critical, warning, info)
- Provides specific recommendations for each issue
- Generates an overall security report
-
Configuration Protection
- Existing configurations are backed up before modification
- All configurations are validated before saving
- Hash-based file integrity verification
- Automatic recovery from failed operations
-
Warning System
- Alerts about potentially insecure configurations
- Provides clear explanations of security risks
- Offers actionable recommendations
- Can automatically fix common security issues
The MCP Wizard integrates with the MCP Registry API to discover and retrieve information about available MCP servers. The Registry Client provides:
- Server Discovery: Find available MCP servers from the registry
- Detailed Information: Get comprehensive details about each server
- Search Capabilities: Find servers by name, tags, or other criteria
- Caching: Automatic caching for improved performance
- Error Handling: Robust error handling with retry mechanisms
Available MCP servers include:
supabase- Supabase database serveropenai- OpenAI AI operations servergithub- GitHub repository operations serveraws- AWS cloud operations serverfirebase- Firebase app development server
Each server includes:
- Basic metadata (name, description, version, etc.)
- Required and optional arguments
- Recommended permissions
- Example configurations
- Roomode templates
For testing purposes, a mock implementation of the Registry Client is available, which simulates all Registry API endpoints without requiring an actual registry server.
-
Version Control: Add
.roo/mcp.jsonto version control but exclude any files containing actual secrets. -
Environment Variables: Use a
.envfile for local development (added to.gitignore) and proper environment variable management for production. -
Regular Updates: Periodically check for updates to MCP servers and update your configurations.
-
Permission Auditing: Regularly review the permissions granted to each server and remove any that are no longer needed.
-
Documentation: Document the MCP servers used in your project and their configuration requirements for team members.
-
Secure Storage of Environment Variables:
- For development: Use
.envfiles (but don't commit them to version control) - For production: Use a secrets management solution (AWS Secrets Manager, HashiCorp Vault, etc.)
- For development: Use
-
Follow the principle of least privilege: Grant only the permissions that are necessary
-
Use specific package versions: Avoid using "latest" to prevent supply chain attacks
- Specialized AI Assistance: Each development phase is handled by a dedicated AI mode optimized for that specific task
- Context Isolation: Tasks run in isolated contexts, ensuring focused and efficient problem-solving
- Seamless Handoffs: Work flows naturally between different development phases
- Reduced Cognitive Load: Focus on one aspect of development at a time
- Modular Architecture: Ensures code is split into files under 500 lines
- Security by Design: Prevents hard-coded secrets and environment variables
- Test-Driven Development: Enforces thorough test coverage
- Documentation First: Ensures comprehensive documentation
- Consistent Standards: Enforces best practices across all team members
- Knowledge Transfer: Documentation and code structure make onboarding easier
- Parallel Development: Different team members can work on different SPARC phases simultaneously
- Reduced Technical Debt: Structured approach prevents accumulation of shortcuts and workarounds
When you run npx create-sparc init without a project name, it creates two essential SPARC files:
The .roo directory contains configuration files, rules, and templates that define how the SPARC methodology is applied to your project. It includes:
- Rules for code generation
- Templates for components and other project elements
- Configuration for SPARC modes
- Guidelines for development practices
- MCP configuration (mcp.json)
The .roomodes file defines the different modes that can be used with the SPARC methodology in your project. These modes help structure the development process according to the SPARC phases (Specification, Pseudocode, Architecture, Refinement, Completion).
These files are essential for using the SPARC methodology in your project and provide the foundation for structured, efficient development.
- Initialize SPARC in your project: Run
npx create-sparc initin your project directory to set up the necessary SPARC files. - Activate SPARC Orchestrator: In Roo Code, select the "SPARC Orchestrator" as your primary mode to begin the development process.
- Use Boomerang Tasks: Delegate tasks to specialized modes (Specification & Pseudocode, Architect, Code, TDD, etc.) using the Boomerang task concept with clear instructions.
- Context Isolation: Each subtask runs in its own isolated context and returns a concise summary upon completion.
- Iterative Refinement: Modes like TDD, Debug, and Security Reviewer iterate until all tests pass, files remain modular (<500 lines), and no environment variables are hard-coded.
- Integration: The Integrator mode consolidates outputs from all specialized modes into a final, cohesive deliverable.
- Documentation & Monitoring: The Documentation Writer mode produces detailed guides, while the Post-Deployment Monitor tracks live performance and flags issues.
- Continuous Optimization: The Optimizer mode ensures ongoing improvements and adherence to best practices.
- Tool Access Restrictions: Adjust the access permissions for each mode to control which tools they can use.
- Role Definitions: Edit the role definitions to match your organization's language and standards.
- Project-Specific Overrides: The
.roomodesfile in your project root can override global settings for your specific project needs.
Here's a quick example of how to use SPARC methodology with Roo Code for a new project:
-
Initialize a new SPARC project:
mkdir my-sparc-project cd my-sparc-project npx create-sparc init -
Open the project in VS Code with Roo Code extension installed
-
Start with the SPARC Orchestrator mode:
- Select the "⚡️ SPARC Orchestrator" mode in Roo Code
- Describe your project goal: "I want to create a REST API for a todo list application"
-
Follow the guided workflow:
- The Orchestrator will break down your project into phases
- Each phase will be handled by a specialized mode
- You'll receive clear instructions at each step
-
Review and integrate the results:
- The final code will be modular, secure, and well-tested
- Documentation will be comprehensive and up-to-date
- The architecture will follow best practices
This workflow dramatically reduces development time while ensuring high-quality, maintainable code.
Contributions to create-sparc are welcome! Whether you're fixing bugs, improving documentation, or proposing new features, your help is appreciated.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
MIT
Created by Reuven Cohen - Agentic Engineer / aiCTO / Vibe Coach
For questions or support, please open an issue on the GitHub repository.