Instruction file imported from benyue1978/fun-withus-ragspace (.cursor/rules/soloflow.mdc). Copyright stays with the author.

SoloFlow MCP Service Guidelines

This rule file provides guidelines for using the soloflow-mcp service to manage project documentation through Model Context Protocol (MCP).

Core Concepts

• Document Management: All project documents are stored in .soloflow/ directory
• MCP Operations: Use list, read, update, and init operations for document management
• MCP Prompts: Use structured prompts for software engineering best practices
• Absolute Paths: All operations require absolute project root paths for security
• Document Types: Predefined document types ensure consistency
• Project Initialization: Use init command to set up project configuration automatically
• Read Before Update: Always read existing content before updating documents

Supported Document Types

The following document types are supported, all stored in .soloflow/ directory:

• overview.md - Project overview and summary
• requirements.md - Functional and non-functional requirements
• system_architecture.md - Technical architecture design
• test_strategy.md - Testing strategy and plans
• ui_design.md - UI/UX design specifications
• tasks.md - Project task lists and progress
• deployment.md - Deployment and infrastructure docs
• notes.md - Project notes and observations

Available MCP Operations

1. Initialize Project Configuration

Initialize SoloFlow MCP configuration in the specified project root:

{
  "tool": "init",
  "args": {
    "projectRoot": "/Users/username/project"
  }
}

2. List Project Documents

Get all available documents in the project:

{
  "tool": "list",
  "args": {
    "projectRoot": "/Users/username/project"
  }
}

3. Read Document Content

Read a specific document type:

{
  "tool": "read",
  "args": {
    "projectRoot": "/Users/username/project",
    "type": "requirements"
  }
}

4. Update Document Content

Create or update a document:

{
  "tool": "update",
  "args": {
    "projectRoot": "/Users/username/project",
    "type": "requirements",
    "content": "# Project Requirements\n\n## Functional Requirements\n1. User management\n2. Data storage\n3. Report generation"
  }
}

Available MCP Prompts

1. Project Initialization Prompt

Initialize project documentation structure:

{
  "prompt": "init-project",
  "args": {
    "projectName": "My Project"
  }
}

2. Create Document Template Prompt

Create a standard template for a specific document type:

{
  "prompt": "create-doc-template",
  "args": {
    "docType": "requirements",
    "projectName": "My Project"
  }
}

3. Add Task Prompt

Add a new task to the project task list:

{
  "prompt": "add-task",
  "args": {
    "taskTitle": "Implement user authentication",
    "priority": "high",
    "category": "backend",
    "estimatedTime": "2d"
  }
}

4. Check Project Status Prompt

Analyze project documentation completeness and task progress:

{
  "prompt": "check-project-status"
}

5. Code Review Checklist Prompt

Get a standard code review checklist:

{
  "prompt": "code-review-checklist",
  "args": {
    "codeLanguage": "TypeScript"
  }
}

6. Deployment Checklist Prompt

Get a deployment preparation checklist:

{
  "prompt": "deployment-checklist",
  "args": {
    "environment": "production"
  }
}

Development Workflow & Documentation Maintenance

Critical Rule: Read Before Update

ALWAYS read existing document content before updating:

1. Read First: Use read operation to get current document content
2. Analyze Content: Understand existing structure and content
3. Preserve Continuity: Maintain document consistency and history
4. Update Carefully: Apply changes while preserving existing information
5. Verify Completeness: Ensure all changes are properly documented

Document Update Process

1. Read Existing Content: Always use read operation first
2. Analyze Current State: Understand existing structure and content
3. Plan Updates: Determine what needs to be added or modified
4. Preserve History: Keep existing content and add update history
5. Cross-Reference: Ensure consistency across all related documents
6. Verify Changes: Confirm all updates are complete and accurate

Fallback Document Access

• When MCP Service Unavailable: If soloflow-mcp service cannot be called, directly read/write files in .soloflow/ directory
• Direct File Operations: Use standard file system operations to access .soloflow/*.md files
• Example: readFile .soloflow/requirements.md, writeFile .soloflow/requirements.md

Task Execution Standards

• Reference Current Documentation: Always check .soloflow/ directory contents before starting any task
• Completion Criteria: Task is only complete when:
  • All tests pass (npm test or equivalent)
  • Code changes are tested and verified
  • Documentation is updated
• Task Documentation: After completing any task, update tasks.md with:
  • Completed task status
  • New tasks discovered during implementation
  • Updated timeline if needed

Documentation Update Triggers

Always update relevant documentation when:

• Requirements Change: User requests new features or modifies existing requirements
• Architecture Changes: System design or technical architecture is modified
• Implementation Discoveries: Important findings during development that affect design
• API Changes: MCP operations or interfaces are modified
• Security Updates: Security-related changes or vulnerabilities discovered
• Prompt Usage: When using prompts to generate or modify documents

Documentation Update Process

1. Identify Affected Documents: Determine which .soloflow/ documents need updates
2. Read Existing Content: Always read current content before making changes
3. Update Content: Modify relevant documents with new information
4. Cross-Reference: Ensure consistency across all related documents
5. Version Control: Add update history entries to modified documents
6. Verify Completeness: Ensure all changes are properly documented

Usage Scenarios

Scenario 1: Initialize New Project

When starting a new project and need to set up SoloFlow MCP:

{
  "tool": "init",
  "args": {
    "projectRoot": "/Users/username/project"
  }
}

Scenario 2: Check Project Documentation

When you need to understand what documents exist in the project:

{
  "tool": "list",
  "args": {
    "projectRoot": "/Users/username/project"
  }
}

Scenario 3: Read Requirements Document

When you need to review project requirements:

{
  "tool": "read",
  "args": {
    "projectRoot": "/Users/username/project",
    "type": "requirements"
  }
}

Scenario 4: Update Task List (with Read First)

When you need to update project tasks:

1. First, read existing content:

   {
     "tool": "read",
     "args": {
       "projectRoot": "/Users/username/project",
       "type": "tasks"
     }
   }

2. Then, update with new content:

   {
     "tool": "update",
     "args": {
       "projectRoot": "/Users/username/project",
       "type": "tasks",
       "content": "# Project Tasks\n\n## To Do\n- [ ] Implement user authentication\n- [ ] Add data validation\n\n## Completed\n- [x] Project initialization\n- [x] Basic architecture setup"
     }
   }

Scenario 5: Create System Architecture Document

When you need to document system architecture:

{
  "tool": "update",
  "args": {
    "projectRoot": "/Users/username/project",
    "type": "system_architecture",
    "content": "# System Architecture\n\n## Overall Architecture\n\n```mermaid\ngraph TD\n    A[Frontend] --> B[API]\n    B --> C[Database]\n```\n\n## Tech Stack\n- Frontend: React + TypeScript\n- Backend: Node.js + Express\n- Database: PostgreSQL"
  }
}

Scenario 6: Use Prompts for Software Engineering

When you need structured guidance for software engineering practices:

1. Initialize project with prompts:

   {
     "prompt": "init-project",
     "args": {
       "projectName": "My Web Application"
     }
   }

2. Create document templates:

   {
     "prompt": "create-doc-template",
     "args": {
       "docType": "requirements"
     }
   }

3. Add tasks with prompts:

   {
     "prompt": "add-task",
     "args": {
       "taskTitle": "Implement user authentication",
       "priority": "high",
       "category": "backend"
     }
   }

4. Check project status:

   {
     "prompt": "check-project-status"
   }

5. Get code review checklist:

   {
     "prompt": "code-review-checklist",
     "args": {
       "codeLanguage": "TypeScript"
     }
   }

6. Get deployment checklist:

   {
     "prompt": "deployment-checklist",
     "args": {
       "environment": "production"
     }
   }

Security Considerations

• Absolute Paths Required: projectRoot must be an absolute path
• Access Control: Only ${projectRoot}/.soloflow/*.md files are accessible
• Type Validation: type parameter must be a predefined document type
• No Concurrent Writes: Concurrent write operations are not supported
• Initialization Safety: init command only creates configuration files, never overwrites existing documents
• Read Before Update: Always read existing content to preserve document continuity

Best Practices

Project Initialization Workflow

1. Run Init Command: Use init to set up project configuration
2. Check Existing Documents: Use list operation to see current state
3. Create Core Documents: Use update to create essential documents
4. Use Prompts: Leverage prompts for structured guidance
5. Maintain Documentation: Regularly update documents as project evolves

Document Naming Convention

• All documents use Markdown format
• Filenames are fixed as <type>.md
• Support for Mermaid diagrams, code blocks, and rich text content

Document Structure Template

Each document should include:

# Document Title

## Overview
Brief description of the document's purpose and content.

## Detailed Content
Specific document content...

## Update History
- 2025-07-24: Initial version
- 2025-07-25: Added new features

Workflow Process

1. Initialize Project: Use init operation to set up configuration
2. Check Existing Documents: Use list operation
3. Read Documents: Use read operation to get content
4. Update Documents: Use update operation to modify content
5. Use Prompts: Leverage prompts for structured guidance

Prompt Usage Guidelines

1. Choose Appropriate Prompt: Select the right prompt for your task
2. Provide Required Parameters: Fill in necessary parameters
3. Review Generated Content: Always review prompt-generated content
4. Customize as Needed: Modify generated content to fit your specific needs
5. Update Documentation: Always update relevant documentation after using prompts

Quick Start Guide

Step 1: Initialize Project

{
  "tool": "init",
  "args": {
    "projectRoot": "/Users/username/project"
  }
}

Step 2: Check Project Documents

{
  "tool": "list",
  "args": {
    "projectRoot": "/Users/username/project"
  }
}

Step 3: Create Requirements Document

{
  "tool": "update",
  "args": {
    "projectRoot": "/Users/username/project",
    "type": "requirements",
    "content": "# Project Requirements\n\n## Functional Requirements\n1. User management\n2. Data storage\n3. Report generation\n\n## Non-functional Requirements\n- Performance: Response time < 2 seconds\n- Availability: 99.9%\n- Security: Data encryption"
  }
}

Step 4: Create Task List

{
  "tool": "update",
  "args": {
    "projectRoot": "/Users/username/project",
    "type": "tasks",
    "content": "# Project Tasks\n\n## This Week\n- [ ] Complete user authentication module\n- [ ] Implement data validation\n- [ ] Write unit tests\n\n## Next Week\n- [ ] Integrate third-party services\n- [ ] Performance optimization\n- [ ] Documentation completion"
  }
}

Step 5: Use Prompts for Guidance

{
  "prompt": "check-project-status"
}

Troubleshooting

Common Errors

1. Path Error: Ensure projectRoot is an absolute path
2. Type Error: Ensure type is a predefined document type
3. File Not Found: Use update operation to create new documents
4. Init Error: Ensure you have write permissions in the project directory
5. Prompt Error: Ensure prompt parameters are correctly formatted

Debugging Tips

• Use init operation to set up project configuration
• Use list operation to check project structure
• Confirm .soloflow/ directory exists after initialization
• Verify document type is correct
• Always read existing content before updating
• Use prompts for structured guidance

Related Documentation

• requirements.md - Detailed functional requirements
• system_architecture.md - Technical architecture design
• test_strategy.md - Testing plans and strategies
• tasks.md - Project task lists and progress

Update History

• 2025-07-30: Added MCP Prompts support and Read Before Update rule
• 2025-07-24: Initial version with basic MCP operations