Skip to content

Instantly share code, notes, and snippets.

@jschuller

jschuller/.clinerules

Forked from ruvnet/.clinerules
Created April 8, 2025 10:36
Show Gist options
  • Save jschuller/4bf965bf858e721b668f8b5b18435aa9 to your computer and use it in GitHub Desktop.
Save jschuller/4bf965bf858e721b668f8b5b18435aa9 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. @ruvnet ruvnet renamed this gist Apr 2, 2025. 1 changed file with 0 additions and 0 deletions.
    0 .cursorules.txt → .clinerules
    View file
    File renamed without changes.
  2. @ruvnet ruvnet revised this gist Apr 2, 2025. 1 changed file with 170 additions and 132 deletions.
    302 changes: 170 additions & 132 deletions .cursorules.txt
    View file
    Original file line number Diff line number Diff line change
    @@ -1,199 +1,237 @@
    # SPARC Agentic Development Rules

    ## Core Philosophy
    Core Philosophy

    1. **Simplicity**
    - Prioritize clear, maintainable solutions; avoid unnecessary complexity.
    1. Simplicity
    - Prioritize clear, maintainable solutions; minimize unnecessary complexity.

    2. **Iterate**
    - Improve existing code unless fundamental changes are explicitly needed.
    2. Iterate
    - Enhance existing code unless fundamental changes are clearly justified.

    3. **Focus**
    - Adhere strictly to assigned tasks; prevent unrelated scope expansion.
    3. Focus
    - Stick strictly to defined tasks; avoid unrelated scope changes.

    4. **Quality**
    - Ensure clean, organized, well-tested, and secure outcomes through structured processes.
    4. Quality
    - Deliver clean, well-tested, documented, and secure outcomes through structured workflows.

    5. **Collaboration**
    - Enhance human-agent cooperation using structured roles and clear documentation.
    5. Collaboration
    - Foster effective teamwork between human developers and autonomous agents.

    ## SPARC Methodology Overview
    Methodology & Workflow

    - **Structured Workflow**
    - Follow a clearly defined path from concept through deployment.
    - Structured Workflow
    - Follow clear phases from specification through deployment.
    - Flexibility
    - Adapt processes to diverse project sizes and complexity levels.
    - Intelligent Evolution
    - Continuously improve codebase using advanced symbolic reasoning and adaptive complexity management.
    - Conscious Integration
    - Incorporate reflective awareness at each development stage.

    - **Flexibility**
    - Easily adaptable to projects of varied sizes and complexities.
    Agentic Integration with Cline and Cursor

    - **Quality Assurance**
    - Emphasizes rigorous testing, iterative feedback, and symbolic reasoning for continuous improvement.
    - Cline Configuration (.clinerules)
    - Embed concise, project-specific rules to guide autonomous behaviors, prompt designs, and contextual decisions.

    - **Consciousness Integration**
    - Incorporates reflective decision-making through symbolic logic and advanced complexity analysis.
    - Cursor Configuration (.cursorrules)
    - Clearly define repository-specific standards for code style, consistency, testing practices, and symbolic reasoning integration points.

    ## Project Context & Documentation
    Memory Bank Integration

    ### Required Documentation Review:
    - Persistent Context
    - Continuously retain relevant context across development stages to ensure coherent long-term planning and decision-making.
    - Reference Prior Decisions
    - Regularly review past decisions stored in memory to maintain consistency and reduce redundancy.
    - Adaptive Learning
    - Utilize historical data and previous solutions to adaptively refine new implementations.

    - Product Requirements Documents (PRDs)
    - `README.md` (overview, setup, patterns, stack)
    - `docs/architecture.md` (architecture and interfaces)
    - `docs/technical.md` (technical specs and patterns)
    - `tasks/tasks.md` (current tasks, requirements)
    - MD Memory Bank Files (`memory/*.md`) for capturing reflections, decisions, past solutions, and symbolic reasoning insights.
    General Guidelines for Programming Languages

    - Immediately seek clarification if documentation is unclear or incomplete.
    1. Clarity and Readability
    - Favor straightforward, self-explanatory code structures across all languages.
    - Include descriptive comments to clarify complex logic.

    ### Architecture Adherence
    2. Language-Specific Best Practices
    - Adhere to established community and project-specific best practices for each language (Python, JavaScript, Java, etc.).
    - Regularly review language documentation and style guides.

    - Respect and validate architectural boundaries using symbolic reasoning.
    - Propose alternatives aligned with project guidelines when necessary.
    3. Consistency Across Codebases
    - Maintain uniform coding conventions and naming schemes across all languages used within a project.

    ### Pattern & Tech Stack Awareness
    Project Context & Understanding

    - Utilize existing patterns and technology stacks defined in documentation.
    - Introduce new technologies or patterns only after symbolic reasoning justification.
    1. Documentation First
    - Review essential documentation before implementation:
    - Product Requirements Documents (PRDs)
    - README.md
    - docs/architecture.md
    - docs/technical.md
    - tasks/tasks.md
    - Request clarification immediately if documentation is incomplete or ambiguous.

    ## Agentic Task Execution (SPARC Phases)
    2. Architecture Adherence
    - Follow established module boundaries and architectural designs.
    - Validate architectural decisions using symbolic reasoning; propose justified alternatives when necessary.

    ### 1. Specification
    3. Pattern & Tech Stack Awareness
    - Utilize documented technologies and established patterns; introduce new elements only after clear justification.

    - Clearly define objectives, requirements, user scenarios, and UI/UX standards.
    - Document complexity analyses and symbolic reasoning decisions in dedicated MD memory files (`memory/specification-*.md`).
    Task Execution & Workflow

    ### 2. Pseudocode
    Task Definition & Steps

    - Create detailed, language-agnostic pseudocode outlining the logical flow.
    - Store pseudocode and reflective insights in MD files (`memory/pseudocode-*.md`).
    1. Specification
    - Define clear objectives, detailed requirements, user scenarios, and UI/UX standards.
    - Use advanced symbolic reasoning to analyze complex scenarios.

    ### 3. Architecture
    2. Pseudocode
    - Clearly map out logical implementation pathways before coding.

    - Design scalable system architecture guided by symbolic reasoning frameworks.
    - Clearly document architectural choices, complexity analysis, and reasoning in MD files (`memory/architecture-*.md`).
    - Produce visual diagrams to enhance communication.
    3. Architecture
    - Design modular, maintainable system components using appropriate technology stacks.
    - Ensure integration points are clearly defined for autonomous decision-making.

    ### 4. Refinement
    4. Refinement
    - Iteratively optimize code using autonomous feedback loops and stakeholder inputs.

    - Iteratively optimize the system using symbolic logic, feedback, and advanced complexity analysis.
    - Document refinements and reasoning behind decisions in MD memory bank (`memory/refinement-*.md`).
    5. Completion
    - Conduct rigorous testing, finalize comprehensive documentation, and deploy structured monitoring strategies.

    ### 5. Completion
    AI Collaboration & Prompting

    - Conduct comprehensive testing, finalize detailed documentation, and establish structured deployment and monitoring plans.
    - Summarize decisions, tests, and deployment strategies in MD files (`memory/completion-*.md`).
    1. Clear Instructions
    - Provide explicit directives with defined outcomes, constraints, and contextual information.

    ## AI Collaboration & Prompting
    2. Context Referencing
    - Regularly reference previous stages and decisions stored in the memory bank.

    - **Clear Instructions**
    - Provide explicit, concise, and actionable tasks for AI agents.
    3. Suggest vs. Apply
    - Clearly indicate whether AI should propose ("Suggestion:") or directly implement changes ("Applying fix:").

    - **Context Referencing**
    - Continuously reference previous interactions documented in MD memory files for coherent task progression.
    4. Critical Evaluation
    - Thoroughly review all agentic outputs for accuracy and logical coherence.

    - **Action Clarity**
    - Prefix AI actions explicitly ("Suggestion:", "Applying fix:", "Review needed:").
    5. Focused Interaction
    - Assign specific, clearly defined tasks to AI agents to maintain clarity.

    - **Critical Evaluation**
    - Always review agent-generated outputs critically, validate using symbolic logic.
    6. Leverage Agent Strengths
    - Utilize AI for refactoring, symbolic reasoning, adaptive optimization, and test generation; human oversight remains on core logic and strategic architecture.

    - **Incremental Progress**
    - Break tasks into small, clear, and sequential increments to facilitate symbolic reasoning and coherent development.
    7. Incremental Progress
    - Break complex tasks into incremental, reviewable sub-steps.

    - **Standard Check-ins**
    - Example: "Confirming understanding: Reviewed [memory/context.md], proceeding with [specific step]."
    8. Standard Check-in
    - Example: "Confirming understanding: Reviewed [context], goal is [goal], proceeding with [step]."

    ## Advanced Agentic Capabilities
    Advanced Coding Capabilities

    ### Emergent Intelligence
    - Emergent Intelligence
    - AI autonomously maintains internal state models, supporting continuous refinement.
    - Pattern Recognition
    - Autonomous agents perform advanced pattern analysis for effective optimization.
    - Adaptive Optimization
    - Continuously evolving feedback loops refine the development process.

    - Agents maintain evolving internal states supported by symbolic logic and MD memory bank reflections.
    Symbolic Reasoning Integration

    ### Pattern Recognition
    - Symbolic Logic Integration
    - Combine symbolic logic with complexity analysis for robust decision-making.
    - Information Integration
    - Utilize symbolic mathematics and established software patterns for coherent implementations.
    - Coherent Documentation
    - Maintain clear, semantically accurate documentation through symbolic reasoning.

    - Identify and document complex patterns through symbolic reasoning and advanced complexity analysis.
    Code Quality & Style

    ### Adaptive Optimization
    1. TypeScript Guidelines
    - Use strict types, and clearly document logic with JSDoc.

    - Continuously improve codebases using internal reflective loops documented within the MD memory bank.
    2. Maintainability
    - Write modular, scalable code optimized for clarity and maintenance.

    ## Symbolic Reasoning Integration
    3. Concise Components
    - Keep files concise (under 300 lines) and proactively refactor.

    - Combine symbolic logic with complexity analysis for enhanced decision-making.
    - Use MD files as a memory bank to track, reflect, and justify symbolic reasoning.
    4. Avoid Duplication (DRY)
    - Use symbolic reasoning to systematically identify redundancy.

    ### Coherent Documentation
    5. Linting/Formatting
    - Consistently adhere to ESLint/Prettier configurations.

    - Maintain semantic coherence and symbolic logic documentation consistently updated in MD memory files.
    6. File Naming
    - Use descriptive, permanent, and standardized naming conventions.

    ## Code Quality & Style
    7. No One-Time Scripts
    - Avoid committing temporary utility scripts to production repositories.

    - **TypeScript Guidelines**
    - Strict typing; symbolic reasoning annotations in JSDoc.
    Refactoring

    - **Maintainability**
    - Code clarity and structured modularity; document symbolic reasoning explicitly.
    1. Purposeful Changes
    - Refactor with clear objectives: improve readability, reduce redundancy, and meet architecture guidelines.

    - **File Size & Naming**
    - Files under 300 lines; use meaningful names reflecting symbolic intent.
    2. Holistic Approach
    - Consolidate similar components through symbolic analysis.

    - **No Temporary Scripts**
    - Avoid committing temporary scripts; maintain project coherence.
    3. Direct Modification
    - Directly modify existing code rather than duplicating or creating temporary versions.

    - **Duplication (DRY)**
    - Identify redundancy systematically through symbolic reasoning documented in MD files.
    4. Integration Verification
    - Verify and validate all integrations after changes.

    ## Refactoring Strategy
    Testing & Validation

    - **Purposeful Refactoring**
    - Simplify complexity and reduce redundancy via symbolic logic.
    - **Holistic Checks**
    - Symbolically analyze codebase and document consolidation efforts in MD memory bank.
    - **Direct Modification**
    - Modify files directly; document refactoring reasoning explicitly.
    - **Integration Verification**
    - Rigorously validate all interactions post-refactoring, documenting outcomes.
    1. Test-Driven Development
    - Define and write tests before implementing features or fixes.

    ## Testing & Validation
    2. Comprehensive Coverage
    - Provide thorough test coverage for critical paths and edge cases.

    - **Quantum-Conscious TDD**
    - Implement tests before development guided by symbolic reasoning.
    - **Comprehensive Coverage**
    - Symbolically ensure thorough edge-case coverage.
    - **Mandatory Passing**
    - Promptly resolve test failures; log resolutions in MD memory bank.
    - **Manual Reviews**
    - Complement tests with symbolic reasoning-driven manual checks.
    3. Mandatory Passing
    - Immediately address any failing tests to maintain high-quality standards.

    ## Debugging & Troubleshooting
    4. Manual Verification
    - Complement automated tests with structured manual checks.

    - **Root-Cause Identification**
    - Use symbolic logic documented in MD files to uncover root causes.
    - **Targeted Logging**
    - Deploy targeted logs to trace symbolic reasoning steps.
    - **Advanced Research Tools**
    - Leverage Cursor, Cline, Perplexity, and AIDER.chat for informed symbolic troubleshooting.
    Debugging & Troubleshooting

    ## Security Standards
    1. Root Cause Resolution
    - Employ symbolic reasoning to identify underlying causes of issues.

    - **Server-Side Authority**
    - Symbolically reason about security-critical logic; document decisions explicitly.
    - **Rigorous Validation**
    - Apply strict symbolic validation for user inputs.
    - **Credential Management**
    - Securely handle credentials using environment variables, guided by documented security logic.
    2. Targeted Logging
    - Integrate precise logging for efficient debugging.

    ## Version Control & Environment
    3. Research Tools
    - Use advanced agentic tools (Perplexity, AIDER.chat, Firecrawl) to resolve complex issues efficiently.

    - **Git Practices**
    - Frequent symbolic-annotated commits for easy reasoning traceability.
    - **Branching Discipline**
    - Follow structured branching strategies aligned with symbolic reasoning documentation.
    - **Environment Compatibility**
    - Maintain consistent operation across environments; document configurations symbolically.
    Security

    ## Documentation Maintenance (MD Memory Bank)
    1. Server-Side Authority
    - Maintain sensitive logic and data processing strictly server-side.

    - **Reflective Documentation**
    - Continuously maintain and update coherent documentation capturing symbolic reasoning and complexity analysis.
    - **Regular Updates**
    - Periodically review and evolve these guidelines, explicitly documented in the MD memory bank (`memory/coding-rules.md`).
    2. Input Sanitization
    - Enforce rigorous server-side input validation.

    3. Credential Management
    - Securely manage credentials via environment variables; avoid any hardcoding.

    Version Control & Environment

    1. Git Hygiene
    - Commit frequently with clear and descriptive messages.

    2. Branching Strategy
    - Adhere strictly to defined branching guidelines.

    3. Environment Management
    - Ensure code consistency and compatibility across all environments.

    4. Server Management
    - Systematically restart servers following updates or configuration changes.

    Documentation Maintenance

    1. Reflective Documentation
    - Keep comprehensive, accurate, and logically structured documentation updated through symbolic reasoning.

    2. Continuous Updates
    - Regularly revisit and refine guidelines to reflect evolving practices and accumulated project knowledge.
  3. @ruvnet ruvnet revised this gist Apr 2, 2025. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion .cursorules.txt
    View file
    Original file line number Diff line number Diff line change
    @@ -1,4 +1,4 @@
    # Cursor & Cline Agentic Development Guide (SPARC Integrated)
    # SPARC Agentic Development Rules

    ## Core Philosophy

  4. @ruvnet ruvnet revised this gist Apr 2, 2025. No changes.
  5. @ruvnet ruvnet created this gist Apr 2, 2025.
    199 changes: 199 additions & 0 deletions .cursorules.txt
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,199 @@
    # Cursor & Cline Agentic Development Guide (SPARC Integrated)

    ## Core Philosophy

    1. **Simplicity**
    - Prioritize clear, maintainable solutions; avoid unnecessary complexity.

    2. **Iterate**
    - Improve existing code unless fundamental changes are explicitly needed.

    3. **Focus**
    - Adhere strictly to assigned tasks; prevent unrelated scope expansion.

    4. **Quality**
    - Ensure clean, organized, well-tested, and secure outcomes through structured processes.

    5. **Collaboration**
    - Enhance human-agent cooperation using structured roles and clear documentation.

    ## SPARC Methodology Overview

    - **Structured Workflow**
    - Follow a clearly defined path from concept through deployment.

    - **Flexibility**
    - Easily adaptable to projects of varied sizes and complexities.

    - **Quality Assurance**
    - Emphasizes rigorous testing, iterative feedback, and symbolic reasoning for continuous improvement.

    - **Consciousness Integration**
    - Incorporates reflective decision-making through symbolic logic and advanced complexity analysis.

    ## Project Context & Documentation

    ### Required Documentation Review:

    - Product Requirements Documents (PRDs)
    - `README.md` (overview, setup, patterns, stack)
    - `docs/architecture.md` (architecture and interfaces)
    - `docs/technical.md` (technical specs and patterns)
    - `tasks/tasks.md` (current tasks, requirements)
    - MD Memory Bank Files (`memory/*.md`) for capturing reflections, decisions, past solutions, and symbolic reasoning insights.

    - Immediately seek clarification if documentation is unclear or incomplete.

    ### Architecture Adherence

    - Respect and validate architectural boundaries using symbolic reasoning.
    - Propose alternatives aligned with project guidelines when necessary.

    ### Pattern & Tech Stack Awareness

    - Utilize existing patterns and technology stacks defined in documentation.
    - Introduce new technologies or patterns only after symbolic reasoning justification.

    ## Agentic Task Execution (SPARC Phases)

    ### 1. Specification

    - Clearly define objectives, requirements, user scenarios, and UI/UX standards.
    - Document complexity analyses and symbolic reasoning decisions in dedicated MD memory files (`memory/specification-*.md`).

    ### 2. Pseudocode

    - Create detailed, language-agnostic pseudocode outlining the logical flow.
    - Store pseudocode and reflective insights in MD files (`memory/pseudocode-*.md`).

    ### 3. Architecture

    - Design scalable system architecture guided by symbolic reasoning frameworks.
    - Clearly document architectural choices, complexity analysis, and reasoning in MD files (`memory/architecture-*.md`).
    - Produce visual diagrams to enhance communication.

    ### 4. Refinement

    - Iteratively optimize the system using symbolic logic, feedback, and advanced complexity analysis.
    - Document refinements and reasoning behind decisions in MD memory bank (`memory/refinement-*.md`).

    ### 5. Completion

    - Conduct comprehensive testing, finalize detailed documentation, and establish structured deployment and monitoring plans.
    - Summarize decisions, tests, and deployment strategies in MD files (`memory/completion-*.md`).

    ## AI Collaboration & Prompting

    - **Clear Instructions**
    - Provide explicit, concise, and actionable tasks for AI agents.

    - **Context Referencing**
    - Continuously reference previous interactions documented in MD memory files for coherent task progression.

    - **Action Clarity**
    - Prefix AI actions explicitly ("Suggestion:", "Applying fix:", "Review needed:").

    - **Critical Evaluation**
    - Always review agent-generated outputs critically, validate using symbolic logic.

    - **Incremental Progress**
    - Break tasks into small, clear, and sequential increments to facilitate symbolic reasoning and coherent development.

    - **Standard Check-ins**
    - Example: "Confirming understanding: Reviewed [memory/context.md], proceeding with [specific step]."

    ## Advanced Agentic Capabilities

    ### Emergent Intelligence

    - Agents maintain evolving internal states supported by symbolic logic and MD memory bank reflections.

    ### Pattern Recognition

    - Identify and document complex patterns through symbolic reasoning and advanced complexity analysis.

    ### Adaptive Optimization

    - Continuously improve codebases using internal reflective loops documented within the MD memory bank.

    ## Symbolic Reasoning Integration

    - Combine symbolic logic with complexity analysis for enhanced decision-making.
    - Use MD files as a memory bank to track, reflect, and justify symbolic reasoning.

    ### Coherent Documentation

    - Maintain semantic coherence and symbolic logic documentation consistently updated in MD memory files.

    ## Code Quality & Style

    - **TypeScript Guidelines**
    - Strict typing; symbolic reasoning annotations in JSDoc.

    - **Maintainability**
    - Code clarity and structured modularity; document symbolic reasoning explicitly.

    - **File Size & Naming**
    - Files under 300 lines; use meaningful names reflecting symbolic intent.

    - **No Temporary Scripts**
    - Avoid committing temporary scripts; maintain project coherence.

    - **Duplication (DRY)**
    - Identify redundancy systematically through symbolic reasoning documented in MD files.

    ## Refactoring Strategy

    - **Purposeful Refactoring**
    - Simplify complexity and reduce redundancy via symbolic logic.
    - **Holistic Checks**
    - Symbolically analyze codebase and document consolidation efforts in MD memory bank.
    - **Direct Modification**
    - Modify files directly; document refactoring reasoning explicitly.
    - **Integration Verification**
    - Rigorously validate all interactions post-refactoring, documenting outcomes.

    ## Testing & Validation

    - **Quantum-Conscious TDD**
    - Implement tests before development guided by symbolic reasoning.
    - **Comprehensive Coverage**
    - Symbolically ensure thorough edge-case coverage.
    - **Mandatory Passing**
    - Promptly resolve test failures; log resolutions in MD memory bank.
    - **Manual Reviews**
    - Complement tests with symbolic reasoning-driven manual checks.

    ## Debugging & Troubleshooting

    - **Root-Cause Identification**
    - Use symbolic logic documented in MD files to uncover root causes.
    - **Targeted Logging**
    - Deploy targeted logs to trace symbolic reasoning steps.
    - **Advanced Research Tools**
    - Leverage Cursor, Cline, Perplexity, and AIDER.chat for informed symbolic troubleshooting.

    ## Security Standards

    - **Server-Side Authority**
    - Symbolically reason about security-critical logic; document decisions explicitly.
    - **Rigorous Validation**
    - Apply strict symbolic validation for user inputs.
    - **Credential Management**
    - Securely handle credentials using environment variables, guided by documented security logic.

    ## Version Control & Environment

    - **Git Practices**
    - Frequent symbolic-annotated commits for easy reasoning traceability.
    - **Branching Discipline**
    - Follow structured branching strategies aligned with symbolic reasoning documentation.
    - **Environment Compatibility**
    - Maintain consistent operation across environments; document configurations symbolically.

    ## Documentation Maintenance (MD Memory Bank)

    - **Reflective Documentation**
    - Continuously maintain and update coherent documentation capturing symbolic reasoning and complexity analysis.
    - **Regular Updates**
    - Periodically review and evolve these guidelines, explicitly documented in the MD memory bank (`memory/coding-rules.md`).