scopemate 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

scopemate/llm.py

@@ -6,8 +6,14 @@ This module provides functions for interacting with LLMs for task estimation,
 breakdown, and optimization.
 """
 import json
+import os
 from typing import Dict, Any, List, Optional
+from enum import Enum, auto
+
+# Import LLM providers
 from openai import OpenAI
+import google.generativeai as genai
+from anthropic import Anthropic
 
 from .models import (
     ScopeMateTask, Scope, TIME_COMPLEXITY, SIZE_COMPLEXITY,
@@ -17,44 +23,258 @@ from .models import (
 # -------------------------------
 # Configuration
 # -------------------------------
-DEFAULT_MODEL = "o4-mini"
+class LLMProvider(Enum):
+    """Supported LLM providers"""
+    OPENAI = auto()
+    GEMINI = auto()
+    CLAUDE = auto()
+
+# Default configuration
+DEFAULT_PROVIDER = LLMProvider.OPENAI
+DEFAULT_OPENAI_MODEL = "o4-mini"
+DEFAULT_GEMINI_MODEL = "gemini-2.0-flash"
+DEFAULT_CLAUDE_MODEL = "claude-3-7-sonnet-20250219"
+
+# Provider-specific model mapping
+DEFAULT_MODELS = {
+    LLMProvider.OPENAI: DEFAULT_OPENAI_MODEL,
+    LLMProvider.GEMINI: DEFAULT_GEMINI_MODEL,
+    LLMProvider.CLAUDE: DEFAULT_CLAUDE_MODEL
+}
+
+# Get provider from environment variable or use default
+def get_llm_provider() -> LLMProvider:
+    """Get the LLM provider from environment variable or use default"""
+    provider_str = os.environ.get("SCOPEMATE_LLM_PROVIDER", "").upper()
+    if provider_str == "OPENAI":
+        return LLMProvider.OPENAI
+    elif provider_str == "GEMINI":
+        return LLMProvider.GEMINI
+    elif provider_str == "CLAUDE": 
+        return LLMProvider.CLAUDE
+    return DEFAULT_PROVIDER
+
+# Get model for the provider from environment variable or use default
+def get_llm_model(provider: LLMProvider = None) -> str:
+    """Get the LLM model for the provider from environment variable or use default"""
+    if provider is None:
+        provider = get_llm_provider()
+    
+    if provider == LLMProvider.OPENAI:
+        return os.environ.get("SCOPEMATE_OPENAI_MODEL", DEFAULT_OPENAI_MODEL)
+    elif provider == LLMProvider.GEMINI:
+        return os.environ.get("SCOPEMATE_GEMINI_MODEL", DEFAULT_GEMINI_MODEL)
+    elif provider == LLMProvider.CLAUDE:
+        return os.environ.get("SCOPEMATE_CLAUDE_MODEL", DEFAULT_CLAUDE_MODEL)
+    
+    return DEFAULT_MODELS[DEFAULT_PROVIDER]
 
 # -------------------------------
 # LLM Interaction
 # -------------------------------
-def call_llm(prompt: str, model: str = DEFAULT_MODEL) -> dict:
+def call_llm(prompt: str, system_prompt: str = None, model: str = None, provider: LLMProvider = None) -> dict:
     """
     Invoke LLM to get a structured JSON response.
     
+    This function is the core LLM integration point for scopemate, handling all
+    communication with the supported LLM APIs. It's designed to always return structured
+    JSON data that can be easily processed by the application.
+    
+    The function:
+    1. Creates a client for the selected provider (OpenAI, Gemini, or Claude)
+    2. Configures a system prompt that instructs the model to return valid JSON
+    3. Sends the user's prompt with the task-specific instructions
+    4. Parses and returns the JSON response
+    
+    Error handling is built in to gracefully handle JSON parsing failures by
+    printing diagnostic information and returning an empty dictionary rather
+    than crashing.
+    
     Args:
-        prompt: The prompt to send to the LLM
-        model: The model to use (defaults to DEFAULT_MODEL)
+        prompt (str): The prompt to send to the LLM, containing full instructions
+                      and any task data needed for context
+        model (str, optional): The model identifier to use (defaults to provider's default model)
+        provider (LLMProvider, optional): The LLM provider to use (defaults to configured provider)
         
     Returns:
-        A dictionary containing the parsed JSON response
+        dict: A dictionary containing the parsed JSON response from the LLM.
+              Returns an empty dict {} if parsing fails.
     """
-    client = OpenAI()
-    response = client.chat.completions.create(
-        model=model,
-        messages=[
-            {
-                "role": "system", 
-                "content": "You are a JSON assistant specialized in structured data for product management tasks. "
-                           "Respond only with valid JSON. Follow the exact requested format in the user's prompt, "
-                           "using the exact field names and adhering to all constraints on field values."
-            },
-            {"role": "user", "content": prompt}
-        ],
-        response_format={"type": "json_object"}
-    )
+    # Determine which provider to use
+    if provider is None:
+        provider = get_llm_provider()
+    
+    # Determine which model to use
+    if model is None:
+        model = get_llm_model(provider)
     
+    # System prompt is common across providers
+    if system_prompt is None:
+        system_prompt = (
+            "You are a JSON assistant specialized in structured data for product management tasks. "
+            "Respond only with valid JSON. Follow the exact requested format in the user's prompt, "
+            "using the exact field names and adhering to all constraints on field values."
+        )
+    
+    # Call the appropriate provider with JSON response format
+    response_text = _call_provider(prompt, system_prompt, model, provider, response_format="json")
+    
+    # Parse JSON response
     try:
-        return json.loads(response.choices[0].message.content)
+        if response_text:
+            return json.loads(response_text)
+        return {}
     except json.JSONDecodeError as e:
         print(f"[Error] Failed to parse LLM response as JSON: {e}")
-        print(f"Raw response: {response.choices[0].message.content}")
+        print(f"Raw response: {response_text}")
         return {}
 
+def call_llm_text(prompt: str, system_prompt: str = None, model: str = None, provider: LLMProvider = None) -> str:
+    """
+    Invoke LLM to get a plain text response (not JSON).
+    
+    This is similar to call_llm but returns plain text instead of JSON.
+    
+    Args:
+        prompt (str): The prompt to send to the LLM
+        system_prompt (str, optional): The system prompt to use
+        model (str, optional): The model identifier to use (defaults to provider's default model)
+        provider (LLMProvider, optional): The LLM provider to use (defaults to configured provider)
+        
+    Returns:
+        str: The text response from the LLM, or empty string on error
+    """
+    # Determine which provider to use
+    if provider is None:
+        provider = get_llm_provider()
+    
+    # Determine which model to use
+    if model is None:
+        model = get_llm_model(provider)
+    
+    # System prompt is common across providers
+    if system_prompt is None:
+        system_prompt = (
+            "You are a helpful assistant that provides clear and concise answers. "
+            "Respond directly to the question without adding additional explanation or context."
+        )
+    
+    print(f"Calling LLM (text mode) with provider: {provider}, model: {model}")
+    
+    # Call the appropriate provider with text response format
+    return _call_provider(prompt, system_prompt, model, provider, response_format="text")
+
+def _call_provider(prompt: str, system_prompt: str, model: str, provider: LLMProvider, response_format: str = "json") -> str:
+    """
+    Internal helper function to call the appropriate LLM provider.
+    
+    Args:
+        prompt (str): The prompt to send to the LLM
+        system_prompt (str): The system prompt to use
+        model (str): The model to use
+        provider (LLMProvider): The provider to use
+        response_format (str): Either "json" or "text"
+        
+    Returns:
+        str: The raw text response from the LLM
+    """
+    try:
+        if provider == LLMProvider.OPENAI:
+            return _call_openai_provider(prompt, system_prompt, model, response_format)
+        elif provider == LLMProvider.GEMINI:
+            return _call_gemini_provider(prompt, system_prompt, model, response_format)
+        elif provider == LLMProvider.CLAUDE:
+            return _call_claude_provider(prompt, system_prompt, model, response_format)
+        
+        # Fallback to OpenAI if unknown provider
+        print(f"[Warning] Unknown provider {provider}, falling back to OpenAI")
+        return _call_openai_provider(prompt, system_prompt, DEFAULT_OPENAI_MODEL, response_format)
+    except Exception as e:
+        print(f"[Error] LLM API call failed: {e}")
+        return ""
+
+def _call_openai_provider(prompt: str, system_prompt: str, model: str, response_format: str) -> str:
+    """Internal helper function to call OpenAI API"""
+    try:
+        client = OpenAI()
+        
+        # Configure response format for JSON if requested
+        kwargs = {}
+        if response_format == "json":
+            kwargs["response_format"] = {"type": "json_object"}
+        
+        response = client.chat.completions.create(
+            model=model,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": prompt}
+            ],
+            **kwargs
+        )
+        
+        # Return raw content text
+        return response.choices[0].message.content.strip()
+    except Exception as e:
+        print(f"[Error] OpenAI API call failed: {e}")
+        return ""
+
+def _call_gemini_provider(prompt: str, system_prompt: str, model: str, response_format: str) -> str:
+    """Internal helper function to call Gemini API"""
+    try:
+        # Check for API key in environment
+        api_key = os.environ.get("GEMINI_API_KEY", None)
+        if not api_key:
+            print("[Error] No API key found for Gemini. Set GEMINI_API_KEY environment variable.")
+            return ""
+        # Initialize the Gemini client
+        genai.configure(api_key=api_key)
+        
+        # Since system role is not supported, combine system prompt and user prompt
+        combined_prompt = f"{system_prompt}\n\n{prompt}"
+        
+        # Configure response format for JSON if requested
+        generation_config = {}
+        if response_format == "json":
+            generation_config["response_mime_type"] = "application/json"
+        
+        # Generate response using Gemini
+        model_name = model if model != system_prompt else DEFAULT_GEMINI_MODEL
+        model_obj = genai.GenerativeModel(model_name=model_name, generation_config=generation_config)
+        response = model_obj.generate_content(combined_prompt)
+        
+        text = response.text.strip()
+        
+        # Remove quotes if present for text responses
+        if response_format == "text" and text.startswith('"') and text.endswith('"'):
+            text = text[1:-1]
+            
+        return text
+    except Exception as e:
+        print(f"[Error] Gemini API call failed: {e}")
+        return ""
+
+def _call_claude_provider(prompt: str, system_prompt: str, model: str, response_format: str) -> str:
+    """Internal helper function to call Claude API"""
+    try:
+        client = Anthropic()
+        
+        # Configure temperature - lower for JSON for more deterministic output
+        temperature = 0.1 if response_format == "json" else 0.2
+        
+        response = client.messages.create(
+            model=model,
+            system=system_prompt,
+            max_tokens=4096,
+            messages=[
+                {"role": "user", "content": prompt}
+            ],
+            temperature=temperature
+        )
+        
+        return response.content[0].text.strip()
+    except Exception as e:
+        print(f"[Error] Claude API call failed: {e}")
+        return ""
 
 def estimate_scope(task: ScopeMateTask) -> Scope:
     """
@@ -307,35 +527,34 @@ def update_parent_with_child_context(parent_task: ScopeMateTask, child_task: Sco
     return updated_parent
 
 
-def generate_title_from_purpose_outcome(purpose: str, outcome: str) -> str:
+def generate_title_from_purpose_outcome(purpose: str, outcome: str, model: str = None, provider: LLMProvider = None) -> str:
     """
     Use LLM to generate a concise title from purpose and outcome descriptions.
     
     Args:
         purpose: The purpose description
         outcome: The outcome description
+        model (str, optional): The model identifier to use (defaults to provider's default model)
+        provider (LLMProvider, optional): The LLM provider to use (defaults to configured provider)
         
     Returns:
         A concise title string
     """
-    client = OpenAI()
-    response = client.chat.completions.create(
-        model=DEFAULT_MODEL,
-        messages=[
-            {
-                "role": "system", 
-                "content": "You are a concise title generator. Generate a brief, clear title (maximum 60 characters) "
-                          "that captures the essence of a task based on its purpose and outcome description."
-            },
-            {
-                "role": "user", 
-                "content": f"Purpose: {purpose}\n\nOutcome: {outcome}\n\nGenerate a concise title (max 60 chars):"
-            }
-        ]
+    system_prompt = (
+        "You are a concise title generator. Generate a brief, clear title (maximum 60 characters) "
+        "that captures the essence of a task based on its purpose and outcome description. "
+        "Return ONLY the title with no additional text or quotes."
     )
     
-    # Extract title from LLM response
-    title = response.choices[0].message.content.strip()
+    user_prompt = f"Purpose: {purpose}\n\nOutcome: {outcome}\n\nGenerate a concise title (max 60 chars):"
+    
+    # Use the common text-based LLM function
+    title = call_llm_text(user_prompt, system_prompt, model, provider)
+    
+    # Handle empty response
+    if not title:
+        return "Task Title"
+    
     # Limit title length if needed
     if len(title) > 60:
         title = title[:57] + "..."

scopemate/models.py

@@ -144,7 +144,69 @@ class Meta(BaseModel):
 
 
 class ScopeMateTask(BaseModel):
-    """A Purpose/Context/Outcome task representing a unit of work."""
+    """
+    A Purpose/Context/Outcome task representing a unit of work.
+    
+    ScopeMateTask is the core data model in scopemate, representing a single unit of work
+    with well-defined purpose, scope, and outcome. The model follows a comprehensive and
+    structured approach to task definition that ensures clarity in task planning and execution.
+    
+    Each task has:
+    1. Purpose - the "why" behind the task (detailed_description, alignment, urgency)
+    2. Scope - the "how big" and "what's involved" (size, time_estimate, dependencies, risks)
+    3. Outcome - the "what will be delivered" (type, definition, acceptance criteria, metrics)
+    4. Meta - tracking information (status, priority, dates, confidence, team)
+    
+    Tasks can form a hierarchical structure through the parent_id field, allowing complex
+    work to be broken down into manageable subtasks. The hierarchy supports:
+    - Parent tasks: higher-level tasks that can be decomposed
+    - Child tasks: more specific tasks that contribute to a parent
+    - Root tasks: top-level tasks with no parent
+    - Leaf tasks: tasks with no children
+    
+    The model enforces validation rules through Pydantic, ensuring data integrity
+    across all fields (e.g., valid size values, time estimates, status, etc.).
+    
+    Attributes:
+        id (str): Unique identifier for the task
+        title (str): Short descriptive title
+        purpose (Purpose): Why the task matters
+        scope (Scope): Size, time, dependencies and risks
+        outcome (Outcome): Delivered value and validation methods
+        meta (Meta): Status, timing, and tracking information
+        parent_id (Optional[str]): ID of parent task if this is a subtask
+        
+    Example:
+        ```python
+        task = ScopeMateTask(
+            id="TASK-abc123",
+            title="Implement user authentication",
+            purpose=Purpose(
+                detailed_description="We need secure authentication for users",
+                alignment=["Security", "User experience"],
+                urgency="strategic"
+            ),
+            scope=Scope(
+                size="complex",
+                time_estimate="sprint",
+                dependencies=["API design", "Database setup"],
+                risks=["Security vulnerabilities", "Performance issues"]
+            ),
+            outcome=Outcome(
+                type="customer-facing",
+                detailed_outcome_definition="Complete authentication system with login/logout",
+                acceptance_criteria=["User can log in", "User can log out", "Password reset works"]
+            ),
+            meta=Meta(
+                status="backlog",
+                priority=1,
+                created=get_utc_now(),
+                updated=get_utc_now(),
+                team="Backend"
+            )
+        )
+        ```
+    """
     id: str
     title: str = Field(..., description="Short descriptive title")
     purpose: Purpose

scopemate/storage.py

@@ -6,6 +6,7 @@ This module manages persistence of task data to disk and loading from files.
 """
 import os
 import json
+from datetime import datetime
 from typing import List, Dict, Any
 
 from pydantic import ValidationError
@@ -37,28 +38,241 @@ def save_plan(tasks: List[ScopeMateTask], filename: str) -> None:
     """
     Save tasks to a plan file.
     
+    This function serializes a list of ScopeMateTask objects to JSON and writes them
+    to a file. The file format uses a consistent structure with a top-level "tasks"
+    array containing serialized task objects. This ensures compatibility with other
+    tooling and future versions of scopemate.
+    
+    The function handles all serialization details including proper encoding and
+    indentation for readability. Each task is completely serialized with all its
+    nested structures (purpose, scope, outcome, meta) for complete persistence.
+    
     Args:
-        tasks: List of ScopeMateTask objects to save
+        tasks: List of ScopeMateTask objects to save to disk
         filename: Path to save the plan file
+        
+    Side Effects:
+        - Writes to file system at the specified path
+        - Prints confirmation message upon successful save
+        
+    Example:
+        ```python
+        tasks = [task1, task2, task3]  # List of ScopeMateTask objects
+        save_plan(tasks, "project_alpha_plan.json")
+        # Saves all tasks to project_alpha_plan.json with proper formatting
+        ```
     """
     payload = {"tasks": [t.model_dump() for t in tasks]}
     with open(filename, "w", encoding="utf-8") as f:
         json.dump(payload, f, indent=2)
     print(f"✅ Plan saved to {filename}.")
+    
+    # Automatically generate markdown version with the same basename
+    md_filename = os.path.splitext(filename)[0] + ".md"
+    save_markdown_plan(payload, md_filename)
+
+
+def save_markdown_plan(data: Dict[str, Any], filename: str) -> None:
+    """
+    Save tasks to a Markdown file for human readability.
+    
+    This function converts the JSON task data into a well-structured Markdown format
+    for easier reading and sharing with team members who may not use scopemate directly.
+    
+    Args:
+        data: Dictionary containing the tasks data (with "tasks" key)
+        filename: Path to save the Markdown file
+    """
+    markdown = generate_markdown_from_json(data)
+    with open(filename, "w", encoding="utf-8") as f:
+        f.write(markdown)
+    print(f"✅ Markdown version saved to {filename}.")
+
+
+def generate_markdown_from_json(data: Dict[str, Any]) -> str:
+    """
+    Convert scopemate JSON data to a well-structured Markdown format.
+    
+    Args:
+        data: The scopemate JSON data as a dictionary
+        
+    Returns:
+        A string containing the Markdown representation
+    """
+    # Start building markdown content
+    md = ["# Project Scope Plan\n"]
+    md.append(f"*Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}*\n\n")
+    
+    # Add summary section
+    tasks = data.get("tasks", [])
+    md.append(f"## Summary\n\n")
+    md.append(f"This document contains **{len(tasks)}** tasks.\n\n")
+    
+    # Get counts by size complexity
+    size_counts = {}
+    for task in tasks:
+        if "scope" in task and "size" in task["scope"]:
+            size = task["scope"]["size"]
+            size_counts[size] = size_counts.get(size, 0) + 1
+            
+    if size_counts:
+        md.append("**Complexity Breakdown:**\n\n")
+        for size, count in size_counts.items():
+            md.append(f"- {size.capitalize()}: {count} task(s)\n")
+        md.append("\n")
+    
+    # Create hierarchical task structure
+    main_tasks = [t for t in tasks if not t.get("parent_id")]
+    child_tasks = {}
+    for task in tasks:
+        if task.get("parent_id"):
+            if task["parent_id"] not in child_tasks:
+                child_tasks[task["parent_id"]] = []
+            child_tasks[task["parent_id"]].append(task)
+    
+    # Add detailed task section
+    md.append("## Task Details\n\n")
+    
+    # Process main tasks with their children
+    for task in main_tasks:
+        md.extend(format_task_as_markdown(task, child_tasks, 0))
+    
+    return "\n".join(md)
+
+
+def format_task_as_markdown(task: Dict[str, Any], child_tasks: Dict[str, List[Dict[str, Any]]], level: int) -> List[str]:
+    """
+    Format a single task and its children as Markdown.
+    
+    Args:
+        task: The task data
+        child_tasks: Dictionary mapping parent_id to list of child tasks
+        level: Current indentation level
+        
+    Returns:
+        List of markdown formatted lines
+    """
+    md_lines = []
+    
+    # Add task title with appropriate heading level
+    heading_level = "###" + "#" * level
+    task_id = task.get("id", "NO-ID")
+    title = task.get("title", "Untitled Task")
+    md_lines.append(f"{heading_level} {task_id}: {title}\n")
+    
+    # Add purpose section
+    if "purpose" in task:
+        purpose = task["purpose"]
+        md_lines.append("**Purpose:**\n\n")
+        if "detailed_description" in purpose:
+            md_lines.append(f"{purpose['detailed_description']}\n\n")
+        if "alignment" in purpose and purpose["alignment"]:
+            md_lines.append("*Strategic Alignment:* ")
+            md_lines.append(", ".join(purpose["alignment"]))
+            md_lines.append("\n\n")
+        if "urgency" in purpose:
+            md_lines.append(f"*Urgency:* {purpose['urgency'].capitalize()}\n\n")
+    
+    # Add scope section
+    if "scope" in task:
+        scope = task["scope"]
+        md_lines.append("**Scope:**\n\n")
+        if "size" in scope:
+            md_lines.append(f"*Size:* {scope['size'].capitalize()}\n\n")
+        if "time_estimate" in scope:
+            md_lines.append(f"*Time Estimate:* {scope['time_estimate'].capitalize()}\n\n")
+        if "dependencies" in scope and scope["dependencies"]:
+            md_lines.append("*Dependencies:*\n\n")
+            for dep in scope["dependencies"]:
+                md_lines.append(f"- {dep}\n")
+            md_lines.append("\n")
+        if "risks" in scope and scope["risks"]:
+            md_lines.append("*Risks:*\n\n")
+            for risk in scope["risks"]:
+                md_lines.append(f"- {risk}\n")
+            md_lines.append("\n")
+    
+    # Add outcome section
+    if "outcome" in task:
+        outcome = task["outcome"]
+        md_lines.append("**Outcome:**\n\n")
+        if "type" in outcome:
+            md_lines.append(f"*Type:* {outcome['type'].capitalize().replace('-', ' ')}\n\n")
+        if "detailed_outcome_definition" in outcome:
+            md_lines.append(f"{outcome['detailed_outcome_definition']}\n\n")
+        if "acceptance_criteria" in outcome and outcome["acceptance_criteria"]:
+            md_lines.append("*Acceptance Criteria:*\n\n")
+            for ac in outcome["acceptance_criteria"]:
+                md_lines.append(f"- {ac}\n")
+            md_lines.append("\n")
+        if "metric" in outcome and outcome["metric"]:
+            md_lines.append(f"*Success Metric:* {outcome['metric']}\n\n")
+        if "validation_method" in outcome and outcome["validation_method"]:
+            md_lines.append(f"*Validation Method:* {outcome['validation_method']}\n\n")
+    
+    # Add meta section
+    if "meta" in task:
+        meta = task["meta"]
+        md_lines.append("**Meta:**\n\n")
+        if "status" in meta:
+            md_lines.append(f"*Status:* {meta['status'].capitalize()}\n")
+        if "priority" in meta and meta["priority"] is not None:
+            md_lines.append(f"*Priority:* {meta['priority']}\n")
+        if "confidence" in meta:
+            md_lines.append(f"*Confidence:* {meta['confidence'].capitalize()}\n")
+        if "team" in meta and meta["team"]:
+            md_lines.append(f"*Team:* {meta['team']}\n")
+        md_lines.append("\n")
+    
+    # Add separator line if not the last task
+    md_lines.append("---\n\n")
+    
+    # Process children recursively
+    if task.get("id") in child_tasks:
+        for child in child_tasks[task["id"]]:
+            md_lines.extend(format_task_as_markdown(child, child_tasks, level + 1))
+    
+    return md_lines
 
 
 def load_plan(filename: str) -> List[ScopeMateTask]:
     """
     Load tasks from a plan file.
     
+    This function reads a JSON file containing serialized tasks and deserializes them
+    into ScopeMateTask objects. It handles various backward compatibility issues and
+    performs validation on the loaded data to ensure integrity.
+    
+    The function is robust against various common issues:
+    - It properly handles missing parent_id fields for backward compatibility
+    - It removes legacy fields that may exist in older files
+    - It skips invalid tasks with validation errors rather than failing entirely
+    - It provides clear warnings about skipped tasks
+    
     Args:
-        filename: Path to the plan file
+        filename: Path to the plan file to load
         
     Returns:
-        List of ScopeMateTask objects
+        List of validated ScopeMateTask objects from the file
         
     Raises:
-        FileNotFoundError: If the file doesn't exist
+        FileNotFoundError: If the specified file doesn't exist
+        
+    Example:
+        ```python
+        try:
+            tasks = load_plan("project_alpha_plan.json")
+            print(f"Loaded {len(tasks)} tasks successfully")
+            
+            # Process loaded tasks
+            for task in tasks:
+                if task.meta.status == "backlog":
+                    # Do something with backlog tasks...
+                    pass
+        except FileNotFoundError:
+            print("Plan file not found, starting with empty task list")
+            tasks = []
+        ```
     """
     if not os.path.exists(filename):
         raise FileNotFoundError(f"File not found: {filename}")