dynamic-cursor-rules 1.7.8

Generate and manage documentation and task tracking for Cursor IDE projects

Cursor Rules

A high-performance framework for managing custom instructions for AI assistants.

Installation

pip install dynamic-cursor-rules

For LLM integration features:

pip install dynamic-cursor-rules[llm]

Usage

from cursor_rules import RuleSet, Rule, parse_file, RuleExecutor

# Create a rule set
ruleset = RuleSet(name="My Rules", description="Custom rules for my assistant")

# Add some rules
ruleset.add_rule(Rule(
    content="Always respond in a friendly tone.",
    id="tone_friendly",
    priority=10,
    tags=["tone"]
))

# Save rules to a file
ruleset.save("my_rules.json")

# Load rules from different formats
markdown_ruleset = parse_file("rules.md")

# Apply rules in a production environment
executor = RuleExecutor(ruleset)
context = {
    "user_input": "Tell me about Python",
    "tags": ["programming"]
}
result = executor.apply_rules(context)
print(result["instructions"])

Features

• Parse rules from Markdown, YAML, and JSON formats
• Prioritize and tag rules for contextual application
• Validate rule sets to ensure correctness
• Apply rules within AI assistant workflows
• Generate .cursorrules files for Cursor IDE integration
• Extract and track tasks from project initialization documents
• Generate complete documentation suites from initialization documents
• Beautiful, interactive CLI with progress indicators and visual feedback
• Simple and elegant API
• Integration with LLM providers (OpenAI, Anthropic)

Rule Management

Markdown Format

# My Rules

Rules for my AI assistant

## Be Concise

Keep responses short and to the point.

## Use Examples

Provide concrete examples when explaining concepts.

YAML

name: My Rules
description: Rules for my AI assistant
rules:
  - id: be_concise
    content: Keep responses short and to the point.
    priority: 10
    tags: [style]
  - id: use_examples
    content: Provide concrete examples when explaining concepts.
    priority: 5
    tags: [teaching]

Task Tracking

Cursor Rules can extract and manage tasks from project initialization documents:

from cursor_rules import extract_action_plan_from_doc, synchronize_with_cursorrules

# Extract tasks from a markdown project document
action_plan = extract_action_plan_from_doc("project_init.md")

# List tasks by phase
for phase in action_plan.phases:
    print(f"Phase: {phase.title}")
    for task in phase.tasks:
        print(f"- {task.title} [Status: {task.status.name}]")

# Update task status
task = action_plan.get_task_by_id("task_id")
if task:
    task.status = TaskStatus.COMPLETED

# Save the action plan to a file
action_plan.save_to_file("project_tasks.json")

# Load an action plan from a file
loaded_plan = ActionPlan.load_from_file("project_tasks.json")

# Sync with a ruleset
ruleset = RuleSet.load("project_rules.json")
synchronize_with_cursorrules(action_plan, ruleset)

Command Line Interface

You can also manage tasks from the command line:

# Generate an action plan from a markdown file
cursor-tasks generate project_init.md -o project_tasks.json

# List all tasks
cursor-tasks list -f project_tasks.json

# List tasks by phase
cursor-tasks list -f project_tasks.json -p "Backend Development"

# Update task status
cursor-tasks update -f project_tasks.json -t task_id -s completed

# Sync with a ruleset
cursor-tasks sync -f project_tasks.json -r project_rules.json

Document Generation

Cursor Rules can generate a complete set of project documentation from a single initialization document:

from cursor_rules import DocumentGenerator

# Create a document generator
generator = DocumentGenerator("project_init.md")

# Generate all documents
generated_files = generator.generate_all_documents()

# Print the paths to generated files
for doc_name, file_path in generated_files.items():
    print(f"{doc_name}: {file_path}")

The generated documentation includes:

• Product Requirements Document (PRD): Contains project vision, target users, user stories, and requirements
• Technical Stack Document: Details the technology stack, architecture, and development environment based on the PRD
• .cursorrules file: Provides project-specific rules for Cursor IDE derived from the PRD
• Action Items: Structured development tasks organized by implementation phases

Document Generation Architecture

Cursor Rules uses a strict PRD-centric document generation approach:

1. The initialization document is first parsed to create a comprehensive PRD
2. The PRD then becomes the single source of truth for all other documents
3. Action items are generated exclusively from the PRD, never from the initialization document
4. The generation process requires LLM capabilities and will fail explicitly rather than using fallbacks
5. All tasks and subtasks represent actual development work, organized by implementation phases
6. This strict sequential workflow ensures consistency across all project documentation

Dynamic Rules

Cursor Rules includes a powerful dynamic rules system that automatically adapts to your project's changing state:

from cursor_rules import DynamicRuleManager, ProjectState, ProjectPhase, Component

# Create a project state
project_state = ProjectState(
    name="My Project",
    description="A dynamic project",
    phase=ProjectPhase.SETUP,
    tech_stack={"frontend": ["React"], "backend": ["Node.js"]}
)

# Create a dynamic rule manager
rule_manager = DynamicRuleManager("/path/to/project", project_state)

# Generate rules based on current project state
rule_files = rule_manager.generate_dynamic_rules()

# Update the project state as development progresses
rule_manager.update_project_state(
    phase=ProjectPhase.FEATURE_DEVELOPMENT,
    active_features=["authentication", "dashboard"]
)

# Regenerate rules to reflect the new state
updated_rule_files = rule_manager.generate_dynamic_rules()

Key Features of Dynamic Rules

1. Project State Tracking: Monitors project phase, active features, components, and tech stack
2. Adaptive Rule Generation: Creates different rule sets based on the current project state
3. Code Change Detection: Automatically detects changes in the codebase and updates rules accordingly
4. Phase-Specific Rules: Different rules for different project phases (setup, development, refinement, etc.)
5. Rule Versioning: Maintains history of previous rule versions for reference and rollback
6. Component-Aware Rules: Generates specific rules for different components of your application

Command Line Interface

# Update project state and regenerate rules
cursor-rules update-rules --phase feature_development --features "auth,dashboard"

# View current project state
cursor-rules state

# Force regeneration of all rules
cursor-rules update-rules --force

Command Line Interface

Generate documents with a beautiful, interactive interface:

# Generate all documentation from an initialization document
cursor-rules documents project_init.md

This creates:

• A .cursor directory at the root with the .cursorrules file
• A documentation directory with all project documents (PRD, Technical Stack, Tasks)
• A development-log.md file to track changes

License

MIT

Examples

The package includes several example scripts to demonstrate its functionality:

# Complete workflow example demonstrating all features
python examples/complete_workflow_example.py

# Document generation from initialization document
python examples/document_generation_example.py

# Task manager example
python examples/task_manager_example.py

# Rule generation example
python examples/rule_generation_example.py

These examples demonstrate key features like:

• Generating .cursorrules files from markdown documents
• Creating complete documentation suites (PRD, Technical Stack, Tasks)
• Extracting and managing tasks
• Versioning .cursorrules files
• Monitoring codebase changes
• Working with LLM providers

API Key Configuration

For features that use LLM integration, you need to configure your API keys:

# Set up OpenAI API key
cursor-rules llm config --provider openai --api-key your_key_here

# Set up Anthropic API key
cursor-rules llm config --provider anthropic --api-key your_key_here

# List configured providers
cursor-rules llm list

# Test your configuration
cursor-rules llm test

You can also use environment variables:

# Linux/macOS
export OPENAI_API_KEY=your_key_here
export ANTHROPIC_API_KEY=your_key_here

# Windows PowerShell
$env:OPENAI_API_KEY = "your_key_here"
$env:ANTHROPIC_API_KEY = "your_key_here"

For detailed instructions, see the API Key Setup Guide.