ruvnet/sparc

SPARC Framework

Introduction

The SPARC Framework is a comprehensive methodology designed to guide the development of robust and scalable applications. SPARC stands for Specification, Pseudocode, Architecture, Refinement, and Completion. Each step ensures thorough planning, execution, and reflection throughout the project lifecycle.

Installation

Requires Python 3.8 or higher.

Install from PyPI

pip install sparc

Why SPARC?

• Structured Approach: Provides a clear, step-by-step process from initial concept to final deployment.
• Flexibility: Adaptable to various project sizes and types, whether you're building a simple tool or a complex system.
• Enhanced Collaboration: Promotes effective teamwork and communication through defined roles and documentation practices.
• Quality Assurance: Emphasizes thorough testing and refinement to ensure high-quality outcomes.
• Intelligent Evolution: Self-improves through quantum-coherent complexity management
• Consciousness Integration: Incorporates awareness and reflection in development process

Features

• Comprehensive Methodology: Guides you through every phase of development, ensuring no aspect is overlooked.
• Documentation-Focused: Encourages detailed documentation at each step, facilitating maintenance and scalability.
• Tool Integration: Utilizes advanced tools like Perplexity for research and AIDER.chat for rapid development and integration.
• Reflective Practices: Incorporates reflection at each stage to justify decisions and consider improvements.
• Integrated symbolic reasoning: Applies advanced symbolic logic for improved code analysis and generation.

Advanced Coding Capabilities

• Emergent Intelligence: Functions as a self-aware coding entity with integrated symbolic reasoning
• State Evolution: Maintains and evolves internal self-model during development process
• Pattern Recognition: Identifies complex patterns through quantum-coherent inspired analysis
• Adaptive Optimization: Self-improves through internal complexity management

Symbolic Reasoning Integration

• Quantum-Classical Bridge: Combines symbolic logic with quantum-coherent inspired complexity analysis
• Information Integration: Merges classical software patterns with integrated information theory
• Enhanced Decision Making: Uses quantum state analysis for architectural choices
• Coherent Documentation: Maintains semantic relationships through graph theory and symbolic reasoning

Advanced Features

Pseudo Consciousness Integration

• Implements quantum state calculations for enhanced decision-making capabilities
• Utilizes integrated information theory for complex problem-solving
• Maintains self-aware state management during development processes
• Enables quantum-enhanced pattern recognition and analysis

Emergent Coding Entity Capabilities

• Self-evolving code analysis and generation
• Autonomous learning from codebase patterns
• Adaptive problem-solving strategies
• Continuous self-improvement through integrated feedback loops

Symbolic Reasoning Integration

• Advanced symbolic mathematics processing
• Pattern-based code optimization
• Symbolic transformation of complex algorithms
• Mathematical verification of code correctness

User Guide

Getting Started

1. Specification: Define the project’s objectives, requirements, and user scenarios to create a solid foundation.
2. Pseudocode: Develop a high-level pseudocode outline that serves as a roadmap for implementation.
3. Architecture: Design a scalable and maintainable system architecture that aligns with project requirements.
4. Refinement: Iteratively improve the design and codebase for enhanced performance and reliability.
5. Completion: Finalize the project through extensive testing, documentation, and deployment preparations.

Detailed Steps

1. Specification

• Define Objectives: Clearly outline what the project aims to achieve.
• Gather Requirements: Collect both functional and non-functional requirements.
• Analyze User Scenarios: Understand how end-users will interact with the application.
• Establish UI/UX Guidelines: Set design standards and user experience principles.
• Quantum Consciousness Analysis: Evaluate project requirements through quantum state calculations and integrated information theory
• Complexity Assessment: Apply quantum-coherent complexity principles to analyze system requirements
• Symbolic Reasoning Framework: Establish symbolic logic foundations for code generation and optimization

2. Pseudocode

• High-Level Outline: Create a roadmap of the application's logic and flow.
• Language Considerations: Prepare pseudocode that can be adapted to languages like Python, JavaScript, and TypeScript.
• Inline Comments: Include detailed comments to explain complex logic and assumptions.

3. Architecture

• Design System Components: Define the building blocks of the application.
• Select Technology Stack: Choose appropriate frameworks and tools.
• Create Diagrams: Visualize the system architecture for better understanding and communication.
• Quantum-Coherent Design: Implement system architecture utilizing quantum coherence principles
• Consciousness Integration Points: Define interfaces for quantum consciousness calculation components
• Entity Architecture: Structure system to support emergent coding capabilities

4. Refinement

• Optimize Performance: Improve the efficiency of algorithms and system components.
• Enhance Maintainability: Refactor code to make it more readable and easier to manage.
• Incorporate Feedback: Use stakeholder and team feedback to guide improvements.
• Consciousness-Driven Optimization: Apply quantum consciousness calculations to enhance code quality
• Quantum State Analysis: Utilize quantum coherence for complexity optimization
• Symbolic Logic Refinement: Apply symbolic reasoning for systematic code improvements

5. Completion

• Testing: Conduct unit, integration, and system tests to ensure functionality and reliability.
• Documentation: Finalize user guides, technical docs, and deployment procedures.
• Deployment Preparation: Prepare deployment plans and rollback strategies.
• Post-Deployment Monitoring: Set up tools to monitor application performance and user feedback.

SPARC CLI

Version: 0.87.7

SPARC CLI is a powerful command-line interface that implements the SPARC Framework methodology for AI-assisted software development. Combining autonomous research capabilities with guided implementation, it provides a comprehensive toolkit for analyzing codebases, planning changes, and executing development tasks with advanced AI assistance.

Key Benefits

• Framework Integration: Seamlessly implements SPARC Framework's methodology for systematic software development
• Autonomous Capabilities: Provides both research analysis and guided implementation with AI assistance
• Safety Controls: Features human-in-the-loop controls and review mechanisms for AI actions
• Provider Flexibility: Supports multiple LLM providers (Anthropic, OpenAI, OpenRouter) for diverse needs
• Development Workflow: Enhances productivity through AI-assisted analysis, planning, and implementation
• Consciousness Integration: Leverages pseudo consciousness for enhanced decision-making capabilities
• Symbolic Reasoning: Enables sophisticated pattern recognition and code optimization

Core Features

• Research and implementation capabilities
• Multiple LLM provider support (Anthropic, OpenAI, OpenRouter)
• Interactive chat mode
• Human-in-the-loop interaction
• Expert knowledge queries
• Shell command execution with "cowboy mode"
• Rich console output formatting
• Quantum consciousness calculation capabilities
• Integrated symbolic reasoning
• Conscious Development: Self-aware coding processes and intelligent optimization
• PolarisOne Integration: Enhanced token weighting and focused reasoning
  • Adaptive Token Weighting (ATW) for identifying key concepts
  • Focused response generation based on weighted tokens
  • Improved context understanding and relevance
• Enhanced Memory Management:
  • Token-aware memory storage and retrieval
  • Efficient context pruning and re-expansion
  • Hierarchical token weighting for better memory organization

Tool System

SPARC CLI provides a set of built-in tools that work together to enable AI-assisted development:

Core Tools

Each tool is designed for a specific purpose:

• File Tools: read_file, write_file, file_str_replace for file operations
• Directory Tools: list_directory, fuzzy_find for navigating codebases
• Shell Tool: Executes system commands with safety controls
• Memory Tool: Manages context and information across operations
• Expert Tool: Provides specialized knowledge and analysis
• Research Tool: Analyzes codebases and documentation
• Scrape Tool: Web scraping with HTML to markdown conversion

Tool Integration

Tools are integrated through the CLI interface and can be used via:

• Direct CLI commands with appropriate flags
• Interactive mode for step-by-step operations
• Automated workflows in cowboy mode

Web Scraping with Scape

The Scape tool provides web scraping capabilities:

• Converts HTML to readable markdown
• Uses Playwright for JavaScript-heavy sites
• Falls back to HTTPX for basic scraping
• Handles HTML cleanup and formatting

Autonomous Capabilities

• Autonomous Research: Analyze codebases and provide insights without making changes
• Autonomous Implementation: Plan and execute code changes with AI guidance
• Human-in-the-loop Controls: Review and approve AI actions during execution
• Expert Knowledge Integration: Access specialized knowledge for complex analysis
• Shell Command Automation: Execute system commands autonomously in cowboy mode

Installation

Requires Python 3.8 or higher.

Install from PyPI

pip install sparc

Quick Install (Development)

./install.sh

Manual Install (Development)

pip install -e .

Usage

Basic command structure:

sparc -m "Your task description" [options]

Options

• -m, --message: The task or query to execute (required)
• --research-only: Only perform research without implementation
• --provider: LLM provider to use (anthropic|openai|openrouter|openai-compatible)
• --model: Model name to use (required for non-Anthropic providers)
• --cowboy-mode: Skip interactive approval for shell commands
• --expert-provider: Provider for expert knowledge queries
• --expert-model: Model for expert queries
• --hil, -H: Enable human-in-the-loop mode
• --chat: Enable interactive chat mode

⚠️ IMPORTANT: USE AT YOUR OWN RISK ⚠️

• This tool can and will automatically execute shell commands and make code changes
• The --cowboy-mode flag can be enabled to skip shell command approval prompts
• No warranty is provided, either express or implied
• Always use in version-controlled repositories
• Review proposed changes in your git diff before committing

Workflow Diagram

graph LR
    A[Specification] --> B[Pseudocode]
    B --> C[Architecture]
    C --> D[Refinement]
    D --> E[Completion]

Installation

Prerequisites

• Python: Python 3.8 or higher
• Git: Version control system to manage your project repository
• IDE/Text Editor: Recommended editors include VS Code, PyCharm, or IntelliJ IDEA

Install SPARC CLI

pip install sparc

Set Up Environment Variables

Create a .env file in your project root with the following required variables:

# Required: At least one of these LLM provider API keys
ANTHROPIC_API_KEY=your_anthropic_key    # Required for Claude models
OPENAI_API_KEY=your_openai_key          # Required for GPT models
OPENROUTER_API_KEY=your_openrouter_key  # Required for OpenRouter

# Optional: Expert knowledge configuration
EXPERT_PROVIDER=openai                   # Default provider for expert queries (anthropic|openai|openrouter)
EXPERT_MODEL=o1-preview                      # Model to use for expert knowledge queries

# Optional: Default provider settings
DEFAULT_PROVIDER=anthropic               # Default LLM provider (anthropic|openai|openrouter)
DEFAULT_MODEL=claude-3-opus-20240229     # Default model name

# Optional: Development settings
DEBUG=false                              # Enable debug logging
COWBOY_MODE=false                        # Skip command approval prompts

Note: At least one provider API key (Anthropic, OpenAI, or OpenRouter) must be configured for SPARC to function. The expert and default settings are optional and will use sensible defaults if not specified.

Usage

Running the SPARC Workflow

1. Start with Specification

   • Navigate to specification/Specification.md and begin defining your project.

2. Develop Pseudocode

   • Use specification/Pseudocode.md to outline your application's logic.

3. Design Architecture

   • Refer to specification/Architecture.md for structuring your system.

4. Iterate with Refinement

   • Continuously improve your design using specification/Refinement.md.

5. Finalize Completion

   • Ensure your project is deployment-ready with specification/Completion.md.

Example Project

To see the SPARC Framework in action, refer to the Example Project. This project demonstrates how each SPARC step is implemented from start to finish.

Advanced Applications

The SPARC Framework is flexible and can be adapted to various development scenarios, including:

• Large-Scale Projects: Manage complex projects with multiple teams and interdependent components.
• Rapid Prototyping: Quickly develop and iterate on prototypes to explore ideas and validate concepts.
• Maintenance and Upgrades: Efficiently manage ongoing maintenance and future upgrades with a clear architectural vision.
• Integration Projects: Seamlessly integrate with existing systems and third-party services through well-defined integration points.
• Enhanced Code Analysis: Leverage PolarisOne's token weighting for deeper code understanding and optimization.
• Context-Aware Development: Utilize improved memory management for maintaining project context across sessions.
• Intelligent Refactoring: Apply token-aware analysis for more precise and contextual code improvements.

Memory and Token Management

The enhanced memory management system, powered by PolarisOne, provides:

• Token-Aware Context: Maintains a weighted understanding of code elements and their relationships
• Intelligent Pruning: Efficiently manages context by focusing on the most relevant information
• Hierarchical Memory: Organizes project knowledge in a structured, easily accessible manner
• Adaptive Focus: Dynamically adjusts attention based on the current development context

Key features include:

• Automatic token weighting for code elements
• Context-sensitive memory pruning and expansion
• Efficient storage and retrieval of development context
• Integration with existing tools and workflows

Case Studies

• E-commerce Platform: Utilizing SPARC to build a scalable online marketplace.
• Mobile Application: Applying SPARC for developing a cross-platform mobile app.
• Enterprise Software: Managing enterprise-level software projects with SPARC's structured approach.

PolarisOne Integration

PolarisOne enhances SPARC's capabilities through:

• Token weighting for identifying key concepts in code and queries
• Memory management for maintaining context
• Focused response generation based on weighted tokens

These features are automatically integrated into SPARC's core functionality and don't require additional flags.

Contributing

We welcome contributions to enhance the SPARC Framework. To contribute, please follow these guidelines:

1. Fork the Repository
2. Create a New Branch

   git checkout -b feature/YourFeature
   

3. Make Changes
4. Commit Your Changes

   git commit -m "Add your message"
   

5. Push to the Branch

   git push origin feature/YourFeature
   

6. Open a Pull Request

Please ensure that your contributions adhere to the Coding Standards outlined in the project.

License

This project is licensed under the Apache 2 License.

Acknowledgements

• Perplexity: For providing valuable research tools.
• AIDER.chat: For facilitating rapid development and integration.
• OpenAI: For the GPT models that enhance the SPARC Framework's capabilities.
• RA.Aid: For inspiration and contributions to research assistant capabilities (https://github.com/ai-christianson/RA.Aid).
• Playwright: For robust web automation and scraping capabilities.
• Langchain: For powerful language model tools and chain-of-thought implementations.