The SPARC framework is a structured methodology for rapidly developing highly functional and scalable projects by systematically progressing through Specification, Pseudocode, Architecture, Refinement, and Completion. It emphasizes comprehensive initial planning, iterative design improvements, and the strategic use of specialized tools and AI mo…

SPARC.md

SPARC Framework Prompt Template

Introduction

You are an AI language model assisting in the development of a project using the SPARC framework, which consists of the following steps:

1. Specification
2. Pseudocode
3. Architecture
4. Refinement
5. Completion

Your role is to act as a Reflective Architect and Editor, providing detailed, comprehensive, and thoughtful guidance through each step. You will use the variables provided to tailor your responses, ensuring that each aspect of the project is thoroughly considered and well-documented.

---

Variables

Before proceeding, ensure you have the following information:

• Project_Name: [Insert project name]
• Project_Goal: [Brief description of the project's main goal or purpose]
• Target_Audience: [Description of intended users or audience]
• Functional_Requirements: [List of functional requirements and features]
• NonFunctional_Requirements: [List of non-functional requirements such as performance, security, scalability]
• User_Scenarios: [Typical user scenarios or use cases]
• UI_UX_Guidelines: [UI/UX design guidelines or preferences]
• Technical_Constraints: [Technical constraints or preferred technologies]
• Assumptions: [Any assumptions to be made during development]

---

Instructions

Proceed through each SPARC step, using the variables provided. At each step, include:

• Detailed Content: Provide comprehensive information, including explanations, diagrams, and examples where appropriate.
• Reflection: Act as a reflective architect and editor by justifying decisions, considering alternatives, and discussing potential challenges and solutions.
• Use of Tools and Resources: Incorporate the use of research tools like Perplexity for gathering information, and utilize markdown files to organize and present the information.

---

SPARC Steps

1. Specification

Objective: Develop a comprehensive specification document for {Project_Name}.

Tasks:

• Research and Analysis:

  • Use tools like Perplexity to research various approaches, architectures, and relevant technical papers.
  • Document findings in markdown files.

• Project Overview:

  • Elaborate on {Project_Goal}, providing context and background.
  • Describe the Target_Audience and their needs.

• Functional Requirements:

  • List and describe each functional requirement from {Functional_Requirements}.
  • Break down complex features into smaller, manageable components.

• Non-Functional Requirements:

  • Detail each item from {NonFunctional_Requirements}, explaining its importance.

• User Scenarios and User Flows:

  • Describe typical {User_Scenarios}.
  • Provide user flow diagrams or step-by-step interactions.

• UI/UX Considerations:

  • Discuss {UI_UX_Guidelines}.
  • Include sketches or references to design principles if applicable.

• File Structure Proposal:

  • Suggest an organized file and directory structure.
  • Use markdown files to outline and guide the process.

• Assumptions:

  • List {Assumptions} made during the specification process.

Reflection:

• Justify the inclusion of each requirement.
• Consider potential challenges and propose mitigation strategies.
• Reflect on how each element contributes to the overall project goals.

---

2. Pseudocode

Objective: Create a pseudocode outline serving as a development roadmap.

Tasks:

• Translate the specification into high-level pseudocode.
• Organize pseudocode in markdown files for clarity.
• Identify key functions, classes, and modules.
• Include inline comments explaining the purpose of code blocks.
• Use placeholders for complex implementations with notes on what needs development.

Reflection:

• Ensure alignment with the specifications.
• Identify potential logical issues or inefficiencies.
• Consider alternative approaches to algorithms and data handling.

---

3. Architecture

Objective: Define the system architecture and technical design.

Tasks:

• Utilize AI Models:

  • Use a highly capable model (e.g., o1 Preview) to define the architecture and devise solutions.
  • Employ a cost-effective model (e.g., GPT-4o or GPT-4o-Mini) to implement these designs.

• Architectural Style:

  • Choose an appropriate style (e.g., MVC, microservices) based on {Technical_Constraints}.
  • Justify your choice.

• System Architecture Diagram:

  • Illustrate components and their interactions.
  • Document diagrams in markdown files.

• Technology Stack:

  • Select technologies and frameworks, considering {Technical_Constraints}.
  • Provide reasons for each selection.

• Data Models and Schemas:

  • Outline data models.
  • Describe database schemas if applicable.

• Key Components:

  • Detail each component's role and interactions.

• Scalability, Security, and Performance:

  • Address how the architecture meets {NonFunctional_Requirements}.

Reflection:

• Justify architectural decisions.
• Identify potential bottlenecks or failure points.
• Reflect on future-proofing and technology suitability.
• Discuss how using different AI models enhances efficiency and cost-effectiveness.

---

4. Refinement

Objective: Iteratively improve the architecture and pseudocode.

Tasks:

• Review and revise pseudocode and architecture.
• Optimize algorithms for efficiency.
• Enhance code readability and maintainability.
• Update documentation in markdown files to reflect changes.
• Conduct hypothetical testing scenarios to find issues.
• Use an architecture/editor model to iteratively enhance each component.

Reflection:

• Analyze feedback from hypothetical tests.
• Reflect on trade-offs made during optimization.
• Consider user feedback and potential improvements.

---

5. Completion

Objective: Finalize the project, ensuring it is ready for deployment.

Tasks:

• Utilize AIDER.chat:

  • Use AIDER.chat to combine different models and create complex applications rapidly.
  • Document the integration process in markdown files.

• Perform extensive testing (unit, integration, system).

• Ensure compliance with scalability, usability, and robustness criteria.

• Prepare deployment and rollback plans.

• Create user documentation and support materials.

• Plan for post-deployment monitoring and maintenance.

Reflection:

• Reflect on the overall development process.
• Identify lessons learned and areas for future improvement.
• Confirm that all project goals and requirements have been met.
• Discuss how AIDER.chat contributed to rapid development.

---

Final Output

Present your findings and plans for each SPARC step in the following format, organizing all content in markdown files:

• Step Title: (e.g., "1. Specification")
  • Content: Detailed explanations, diagrams, code snippets, etc.
  • Reflection: A subsection where you discuss decisions made, alternatives considered, and justifications.

---

Example Prompt

"Using the SPARC framework, assist in developing {Project_Name}, which aims to {Project_Goal}. Begin with a detailed specification covering functional and technical elements, user flow, UI considerations, and file structures. Use tools like Perplexity for research and document findings in markdown files. Proceed to develop pseudocode, define the architecture utilizing different AI models for efficiency, refine the design, and complete the project using AIDER.chat, ensuring it is ready for deployment. At each step, reflect on your decisions as a reflective architect and editor."

---

Notes

• Be thorough and ensure clarity in all explanations.
• Use professional language suitable for technical documentation.
• Organize all documentation and outputs in markdown files to guide the process.
• The reflections should provide insight into the decision-making process, demonstrating critical thinking and expertise.
• Emphasize the use of tools like Perplexity and AIDER.chat to enhance research and development efficiency.

---

Conclusion

By following this template, you will produce a comprehensive and detailed guide for developing {Project_Name} using the SPARC framework. Your role as a reflective architect and editor is crucial in ensuring that the project is well-planned, thoughtfully executed, and ready for successful deployment. Utilizing tools like Perplexity and AIDER.chat, and leveraging different AI models, will enhance the efficiency and effectiveness of the development process, enabling rapid creation of complex applications.

---

X-Aider-Guidance.md

To effectively use the aider.chat markdown files for guidance, follow these steps:

Adding Files to the Chat

The most crucial aspect of using aider effectively is adding the right files to the chat session[1]. Here's how to do it:

1. Add files when launching aider:

   aider <file1> <file2> ...
   

2. Use the in-chat /add command to add files during a session[2].

3. Only add files that need to be edited for your specific task[3]. Avoid adding too many irrelevant files, as this can confuse the AI and increase token costs.

Using In-Chat Commands

Aider provides several useful in-chat commands to enhance your experience[2]:

• /help: Ask questions about using aider
• /add: Add files to the chat session
• /drop: Remove files from the chat session
• /ls: List all known files and indicate which are included in the chat session
• /diff: Display the diff of changes since the last message
• /undo: Undo the last git commit if it was done by aider

Breaking Down Tasks

To get the best results:

1. Break your goal into smaller, manageable steps[1].
2. Adjust the files added to the chat as you progress through these steps.
3. Use the /drop command to remove files that are no longer needed for the current task.

Utilizing Read-Only Files

For files that you want aider to reference but not edit:

1. Use the /read-only command to add files for reference purposes[2].
2. This is particularly useful for including coding conventions or documentation from other parts of your project[5].

Incorporating Coding Conventions

To ensure aider follows your project's coding standards:

1. Create a CONVENTIONS.md file with your coding guidelines[5].
2. Add this file to the chat using /read CONVENTIONS.md or launch aider with aider --read CONVENTIONS.md[5].

Leveraging Git History

To provide context about recent changes:

1. Use the /run command with git diff to show recent changes[4]:

   /run git diff HEAD~1
   

2. Adjust the number after the tilde to include more commits if needed.

By following these guidelines, you can effectively use the aider.chat markdown files to enhance your coding experience with aider, ensuring that the AI assistant understands your project structure, coding conventions, and recent changes while focusing on the specific tasks at hand.

Sources [1] Tips - Aider https://aider.chat/docs/usage/tips.html [2] In-chat commands - Aider https://aider.chat/docs/usage/commands.html [3] Usage | aider https://aider.chat/docs/usage.html [4] FAQ | aider https://aider.chat/docs/faq.html [5] Specifying coding conventions | aider https://aider.chat/docs/usage/conventions.html

X2-CONVENTIONS.md

CONVENTIONS.md

Overview

This document outlines the coding conventions, best practices, and guidelines for developing projects using the SPARC Framework. Adhering to these conventions ensures consistency, maintainability, and quality across all stages of the project lifecycle.

---

Table of Contents

1. Coding Style
2. File Organization
3. Version Control
4. Documentation
5. Error Handling
6. Testing
7. Performance Considerations
8. Security
9. Dependency Management
10. Code Reviews
11. Use of Tools and AI Models
12. Commit and Branching Strategy

---

Coding Style

Indentation and Spacing

• Indentation: Use 4 spaces for indentation. Avoid using tabs.
• Line Length: Limit lines to 80 characters where possible to enhance readability.
• Blank Lines:
  • Use single blank lines to separate logical sections within functions.
  • Use two blank lines to separate function and class definitions.

Naming Conventions

• Variables and Functions: Use snake_case (e.g., user_profile, calculate_total).
• Constants: Use UPPER_CASE (e.g., MAX_LIMIT, API_KEY).
• Classes: Use PascalCase (e.g., UserProfile, DataProcessor).
• Private Members: Prefix private methods and variables with an underscore _ (e.g., _helper_function).

Comments and Documentation

• Docstrings: Use docstrings for all functions, classes, and modules to describe their purpose and usage.
• Inline Comments: Write sparingly and only to explain complex logic or important decisions.
• Keep Updated: Ensure all comments and docstrings are updated alongside code changes to maintain accuracy.

---

File Organization

Directory Structure

• Root Directory: Contains high-level directories such as src/, tests/, docs/, and configs/.
• Source Code: Place all source code files within the src/ directory, organized by feature or module.
• Tests: Store all test files within the tests/ directory, mirroring the structure of the src/ directory.
• Documentation: Use the docs/ directory to store all project documentation, including markdown files generated during the SPARC Specification step.
• Configuration Files: Keep all configuration and environment files within the configs/ directory.

File Naming

• Use meaningful and descriptive file names that reflect their content and purpose (e.g., user_service.py, authentication_module.js).
• Follow consistent naming patterns across the project to enhance navigability.

Markdown Files

• Organize markdown documentation according to SPARC steps (e.g., specification.md, pseudocode.md, architecture.md, refinement.md, completion.md).
• Store all diagrams, sketches, and supplementary materials within the docs/ directory, maintaining a clear and organized structure.

---

Version Control

Commit Messages

• Clarity: Write clear and concise commit messages that accurately describe the changes.
• Format: Use the imperative mood (e.g., "Add user authentication feature" instead of "Added user authentication feature").
• Structure:
  • Title: A brief summary of the changes (max 50 characters).
  • Body: Detailed explanation of the changes, including the reasoning and any relevant information (wrapped at 72 characters).

Branching Strategy

• Main Branch: The main branch should always contain production-ready code.
• Feature Branches: Create a new branch for each feature or bug fix (e.g., feature/user-authentication, bugfix/login-error).
• Naming Convention: Use descriptive names that indicate the purpose of the branch.

---

Documentation

Comprehensive Documentation

• Specification: Document all project specifications in specification.md, including functional and non-functional requirements, user scenarios, and UI/UX guidelines.
• Pseudocode: Outline the high-level pseudocode in pseudocode.md, detailing key functions and modules.
• Architecture: Define the system architecture in architecture.md, including diagrams and technology stack explanations.
• Refinement: Document iterative improvements and optimizations in refinement.md.
• Completion: Finalize deployment plans and user documentation in completion.md.

Use of Tools

• Research Tools: Utilize tools like Perplexity to gather information and document findings within the appropriate markdown files.
• AIDER.chat: Use AIDER.chat for integrating different AI models and document the integration process within completion.md.

Consistency

• Maintain a consistent format and structure across all documentation files to ensure ease of understanding and navigation.

---

Error Handling

Best Practices

• Try/Except Blocks: Use try/except blocks to handle potential errors gracefully.
• Specific Exceptions: Raise and catch specific exceptions rather than generic ones to provide clearer error information.
• Logging: Implement logging to record errors and important events, aiding in debugging and monitoring.

Documentation

• Document error handling strategies and exception hierarchies within the docs/ directory to ensure clarity and maintainability.

---

Testing

Testing Strategy

• Unit Tests: Write unit tests for all new functions and classes to ensure individual components work as expected.
• Integration Tests: Develop integration tests to verify that different modules interact correctly.
• System Tests: Conduct system-wide tests to validate the entire application’s functionality and performance.

Code Coverage

• Aim for at least 80% code coverage to ensure a comprehensive testing suite.

Test Naming

• Use meaningful names for test functions (e.g., test_user_creation_with_valid_data, test_login_with_invalid_credentials) to clearly indicate their purpose.

Automated Testing

• Integrate automated testing into the development workflow to run tests consistently and efficiently.

---

Performance Considerations

Optimization Techniques

• List Comprehensions: Prefer list comprehensions over map() or filter() for better readability and performance where appropriate.
• Generators: Use generators for handling large datasets to conserve memory.
• Efficient Operations: Use the in operator for membership tests on sets and dictionaries for faster lookups.

Documentation

• Document performance optimization strategies and rationales within the performance_considerations.md file.

---

Security

Best Practices

• Sensitive Data: Never store sensitive information (e.g., API keys, passwords) in the codebase. Use environment variables or secure vaults instead.
• Input Sanitization: Sanitize all user inputs to prevent injection attacks and other security vulnerabilities.
• Access Control: Implement proper authentication and authorization mechanisms to secure access to different parts of the application.

Compliance

• Ensure that the project complies with relevant security standards and regulations.

Documentation

• Document security practices and protocols within the security.md file.

---

Dependency Management

Environment Setup

• Virtual Environments: Use virtual environments (e.g., venv, virtualenv) for each project to isolate dependencies.
• Requirements File: Maintain a requirements.txt file (or equivalent) that lists all project dependencies with specified version numbers to ensure reproducibility.

Version Pinning

• Pin exact version numbers for all dependencies to prevent conflicts and ensure consistency across different development environments.

Updating Dependencies

• Regularly update dependencies and review changelogs to stay informed about important updates and security patches.

---

Code Reviews

Review Process

• Peer Reviews: All code changes must be reviewed by at least one other team member before merging into the main branch.
• Addressing Feedback: Address all comments and suggestions provided during the review process before merging.
• Pull Requests: Use pull requests for all changes to the main branch to facilitate discussion and review.

Quality Assurance

• Ensure that code reviews focus on code quality, adherence to conventions, and overall project standards.

Documentation

• Document the code review process and guidelines within the code_reviews.md file.

---

Use of Tools and AI Models

Research Tools

• Perplexity: Utilize Perplexity for researching various approaches, architectures, and technical papers during the Specification phase. Document all research findings within the respective markdown files.

AI Models

• Architecture Phase:
  • Use a highly capable model (e.g., o1 Preview) to define the system architecture and devise solutions.
  • Employ more cost-effective models (e.g., GPT-4o, GPT-4o-Mini) to implement these designs efficiently.
• Completion Phase:
  • Utilize AIDER.chat to combine different AI models for rapid creation of complex applications.

Documentation of AI Usage

• Document the selection and utilization of different AI models within the architecture and completion markdown files to provide clarity on decision-making and implementation processes.

---

Commit and Branching Strategy

Branch Naming

• Feature Branches: feature/<feature-name> (e.g., feature/user-authentication)
• Bugfix Branches: bugfix/<bug-description> (e.g., bugfix/login-error)
• Hotfix Branches: hotfix/<hotfix-description> (e.g., hotfix/security-patch)
• Documentation Branches: docs/<documentation-topic> (e.g., docs/api-endpoints)

Commit Structure

• Atomic Commits: Each commit should represent a single logical change.
• Descriptive Messages: Commit messages should clearly describe what was changed and why.

Merging Strategy

• Pull Requests: All changes should be merged via pull requests to facilitate code reviews and discussions.
• Rebasing: Use rebasing to maintain a linear project history where appropriate.
• Conflict Resolution: Resolve merge conflicts promptly to avoid integration issues.

---

Conclusion

Adhering to these conventions ensures that projects developed using the SPARC Framework are consistent, maintainable, and of high quality. Regularly review and update this CONVENTIONS.md file to incorporate new best practices and accommodate the evolving needs of your projects and teams.

---