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

scopemate/__init__.py

@@ -4,7 +4,7 @@ This package provides tools for breaking down complex tasks using
 the Purpose/Scope/Outcome planning approach.
 """
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 
 # Public API
 from .models import (

scopemate/breakdown.py

@@ -21,11 +21,39 @@ def suggest_breakdown(task: ScopeMateTask) -> List[ScopeMateTask]:
     """
     Use LLM to suggest a breakdown of a task into smaller subtasks.
     
+    This function is a critical part of the scopemate workflow. It uses a Large Language
+    Model to analyze a task and suggest appropriate subtasks that collectively accomplish
+    the parent task's goal. The function handles both complexity-based and time-based
+    breakdowns, ensuring that complex tasks are simplified and long-duration tasks are
+    broken into manageable timeframes.
+    
+    The function works through these stages:
+    1. Analyze if the breakdown is needed due to complexity or time duration
+    2. Formulate a specialized prompt for the LLM with appropriate constraints
+    3. Process the LLM's response to extract valid subtask definitions
+    4. Convert the raw LLM output into proper ScopeMateTask objects
+    5. Present the suggestions to the user through an interactive selection process
+    
+    The subtasks generated are guaranteed to be:
+    - Smaller in scope than the parent task
+    - Less complex than the parent task
+    - Shorter in duration than the parent task
+    - Collectivey covering all aspects needed to accomplish the parent task
+    
     Args:
-        task: The ScopeMateTask to break down
+        task: The ScopeMateTask to break down into smaller subtasks
         
     Returns:
-        List of ScopeMateTask objects representing subtasks
+        List of ScopeMateTask objects representing the subtasks, after user interaction
+        
+    Example:
+        ```python
+        parent_task = get_task_by_id("TASK-123")
+        subtasks = suggest_breakdown(parent_task)
+        if subtasks:
+            print(f"Created {len(subtasks)} subtasks")
+            tasks.extend(subtasks)
+        ```
     """
     # Check if we're breaking down due to size complexity or time estimate
     is_complex = task.scope.size in ["complex", "uncertain", "pioneering"]

scopemate/cli.py

@@ -9,12 +9,14 @@ outcome, and output file.
 import sys
 import argparse
 import uuid
+import json
+import os
 from typing import List
 
 from .models import (
     ScopeMateTask, Purpose, Scope, Outcome, Meta, get_utc_now
 )
-from .storage import save_plan
+from .storage import save_plan, save_markdown_plan, generate_markdown_from_json
 from .llm import estimate_scope, generate_title_from_purpose_outcome
 from .breakdown import suggest_breakdown
 from .task_analysis import check_and_update_parent_estimates
@@ -101,36 +103,76 @@ def process_task_with_breakdown(task: ScopeMateTask) -> List[ScopeMateTask]:
 
 
 def command_line() -> None:
-    """Process command line arguments and execute appropriate actions."""
+    """
+    Process command line arguments and execute appropriate actions.
+    
+    This function is the primary entry point for the scopemate CLI, responsible 
+    for parsing command-line arguments and routing execution to the appropriate
+    workflow based on those arguments. It supports two main modes of operation:
+    
+    1. Interactive mode (--interactive): Launches the full guided workflow with
+       the TaskEngine for an interactive task creation and breakdown experience.
+       
+    2. Non-interactive mode (--purpose and --outcome): Creates a task directly
+       from command-line arguments, generates subtasks using LLM, and saves the
+       resulting task hierarchy to a JSON file with an automatic Markdown version.
+       
+    The function validates required arguments depending on the mode, provides
+    helpful error messages when arguments are missing, and handles the entire
+    lifecycle of task creation, breakdown, and saving in non-interactive mode.
+    
+    Command line arguments:
+        --interactive: Flag to launch interactive workflow
+        --purpose: Text describing why the task matters (required in non-interactive mode)
+        --outcome: Text describing what will be delivered (required in non-interactive mode)
+        --output: Path to save the output JSON file (default: scopemate_plan.json)
+        
+    Side Effects:
+        - Saves task data to a file on disk (both JSON and Markdown versions)
+        - Prints progress and error messages to stdout
+        - Exits with non-zero status code on errors
+    
+    Example Usage:
+        ```bash
+        # Interactive mode
+        scopemate --interactive
+        
+        # Non-interactive mode
+        scopemate --purpose "Improve website performance" \
+                 --outcome "Page load time under 2 seconds" \
+                 --output "perf_project.json"
+        ```
+        
+    Note: Markdown files are automatically generated with the same base name 
+    as the JSON file (e.g., "perf_project.md" for "perf_project.json").
+    """
     parser = argparse.ArgumentParser(
-        description="🪜  scopemate v.0.1.0 - Break down complex projects with LLMs",
-        epilog="Purpose: why it matters\n"
-               "Outcome: what will change once it's done\n"
-               "Scope: how will be delivered (this is where LLM can help)",
+        description="🪜  scopemate - Break down complex projects with LLMs",
         formatter_class=argparse.RawTextHelpFormatter
     )
     
     parser.add_argument(
         "--interactive",
         action="store_true",
-        help="Launch guided workflow to define task, generate LLM-powered breakdowns, and estimate scope"
+        help="💡 Interactive mode"
     )
     
     parser.add_argument(
         "--outcome", 
-        help="🎯 Outcome: Clearly define what will be delivered and how success will be measured (asks: What will change once this is done?)"
+        help="🎯 What will change once this is done?"
     )
 
     parser.add_argument(
         "--purpose", 
-        help="🧭 Purpose: Clearly define why this project matters strategically (asks: Why does this matter now?)"
+        help="🧭 Why does this matter now?"
     )
     
     parser.add_argument(
         "--output", 
         default="scopemate_plan.json",
-        help="JSON file to save the task breakdown and scope estimates (default: scopemate_plan.json)"
+        help="🗂️  (default: scopemate_plan.json)"
     )
+
     args = parser.parse_args()
     
     # Check if running in interactive mode
@@ -154,8 +196,12 @@ def command_line() -> None:
     print("Generating subtasks...")
     all_tasks = process_task_with_breakdown(task)
     
-    # Save plan to output file
+    # Save plan to output file (this will also create the MD version)
     save_plan(all_tasks, args.output)
+    
+    # Show message about MD file creation
+    md_filename = os.path.splitext(args.output)[0] + ".md"
+    print(f"✅ Both JSON and Markdown versions have been saved. You can share {md_filename} with team members.")
 
 
 def main():

scopemate/engine.py

@@ -25,10 +25,25 @@ from .interaction import prompt_user, build_root_task, print_summary
 class TaskEngine:
     """
     Main engine for scopemate that coordinates task creation, breakdown, and management.
+    
+    The TaskEngine is the central coordinator of the scopemate application, managing the entire
+    lifecycle of tasks from creation to breakdown to final output. It handles loading and saving
+    task data, organizing the task hierarchy, and orchestrating the breakdown of complex tasks
+    into simpler subtasks.
+    
+    Attributes:
+        tasks (List[ScopeMateTask]): List of all tasks in the current session
+        task_depths (Dict[str, int]): Mapping of task IDs to their depth in the hierarchy
+        max_depth (int): Maximum allowed depth for task nesting (default: 5)
     """
     
     def __init__(self):
-        """Initialize the TaskEngine."""
+        """
+        Initialize the TaskEngine with empty task list and depth tracking.
+        
+        Creates a new TaskEngine instance with an empty task list and depth tracking dictionary.
+        Sets the default maximum depth for task hierarchies to 5 levels.
+        """
         self.tasks: List[ScopeMateTask] = []
         self.task_depths: Dict[str, int] = {}
         self.max_depth: int = 5  # Maximum depth of task hierarchy
@@ -37,8 +52,21 @@ class TaskEngine:
         """
         Load tasks from checkpoint file if it exists.
         
+        Checks for the existence of a checkpoint file and prompts the user about whether
+        to resume from this checkpoint. If the user confirms, loads the tasks from the
+        checkpoint file into the engine.
+        
         Returns:
-            True if checkpoint was loaded, False otherwise
+            bool: True if checkpoint was loaded successfully, False otherwise
+            
+        Example:
+            ```python
+            engine = TaskEngine()
+            if engine.load_from_checkpoint():
+                print(f"Loaded {len(engine.tasks)} tasks from checkpoint")
+            else:
+                print("Starting with a new task list")
+            ```
         """
         if checkpoint_exists():
             resume = prompt_user(
@@ -58,11 +86,24 @@ class TaskEngine:
         """
         Load tasks from a user-specified file.
         
+        Prompts the user about whether to load an existing plan. If confirmed,
+        asks for the filename and attempts to load tasks from that file.
+        
         Args:
-            default_filename: Default filename to suggest
+            default_filename (str): Default filename to suggest to the user
             
         Returns:
-            True if file was loaded, False otherwise
+            bool: True if file was loaded successfully, False otherwise
+            
+        Raises:
+            FileNotFoundError: Handled internally, prints error message if file not found
+            
+        Example:
+            ```python
+            engine = TaskEngine()
+            if engine.load_from_file("my_project_plan.json"):
+                print(f"Loaded {len(engine.tasks)} tasks from file")
+            ```
         """
         choice = prompt_user("Load existing plan?", default="n", choices=["y","n"])
         if choice.lower() == "y":
@@ -76,12 +117,58 @@ class TaskEngine:
         return False
     
     def create_new_task(self) -> None:
-        """Create a new root task interactively."""
+        """
+        Create a new root task interactively.
+        
+        Initiates an interactive dialog to build a new root task, adds it to the task list,
+        and automatically saves a checkpoint. The dialog collects all necessary information
+        for a well-defined task including title, purpose, scope, and expected outcomes.
+        
+        Side Effects:
+            - Appends new task to self.tasks
+            - Saves checkpoint to disk
+            
+        Example:
+            ```python
+            engine = TaskEngine()
+            engine.create_new_task()  # Interactively creates a new root task
+            ```
+        """
         self.tasks.append(build_root_task())
         save_checkpoint(self.tasks)
     
     def breakdown_complex_tasks(self) -> None:
-        """Process all tasks and break down complex ones."""
+        """
+        Process all tasks and break down complex ones.
+        
+        This is a core function that analyzes all tasks to identify those that are too complex 
+        or have long durations, then interactively breaks them down into smaller subtasks.
+        It maintains the task hierarchy, updates parent-child relationships, and ensures
+        estimate consistency across the task tree.
+        
+        The function uses a breadth-first approach to process tasks, breaking down parent tasks
+        before their children, and saving checkpoints after each breakdown.
+        
+        Algorithm:
+            1. Initialize task depths to track hierarchy
+            2. Process each task and check if it needs breakdown
+            3. For tasks needing breakdown, use LLM to suggest subtasks
+            4. Add approved subtasks to the task list
+            5. Update parent estimates based on subtask characteristics
+            6. Save checkpoint after each task breakdown
+            
+        Side Effects:
+            - Modifies self.tasks by adding subtasks
+            - Updates self.task_depths with new depth information
+            - Saves checkpoints to disk after each breakdown
+            
+        Example:
+            ```python
+            engine = TaskEngine()
+            engine.load_from_file("my_project.json")
+            engine.breakdown_complex_tasks()  # Interactively breaks down complex tasks
+            ```
+        """
         # Initialize depth tracking
         self.task_depths = _initialize_task_depths(self.tasks)
         
@@ -127,7 +214,28 @@ class TaskEngine:
                     save_checkpoint(self.tasks)
     
     def handle_long_duration_tasks(self) -> None:
-        """Find and handle long duration leaf tasks."""
+        """
+        Find and handle long duration leaf tasks.
+        
+        Identifies leaf tasks (tasks with no children) that have long duration estimates,
+        presents them to the user, and offers the opportunity to break them down further.
+        This helps ensure that all tasks in the final plan are of manageable size.
+        
+        The function uses task_analysis.find_long_duration_leaf_tasks to identify candidates
+        for further breakdown, then interactively processes user-selected tasks.
+        
+        Side Effects:
+            - May modify self.tasks by adding subtasks for long-duration leaf tasks
+            - Updates parent estimates via check_and_update_parent_estimates
+            - Saves checkpoints to disk after each breakdown
+            
+        Example:
+            ```python
+            engine = TaskEngine()
+            engine.load_from_file("my_project.json")
+            engine.handle_long_duration_tasks()  # Interactively processes long-duration tasks
+            ```
+        """
         # Find long duration leaf tasks
         long_duration_leaf_tasks = find_long_duration_leaf_tasks(self.tasks)
         
@@ -172,7 +280,27 @@ class TaskEngine:
                     print("Invalid selection, skipping breakdown.")
     
     def finalize_plan(self) -> None:
-        """Review and save the final plan."""
+        """
+        Review and save the final plan.
+        
+        Performs a final consistency check on all task estimates, displays a summary
+        of the entire task hierarchy to the user, and prompts for saving the finalized
+        plan to a permanent file. If saved, removes the temporary checkpoint file.
+        
+        Side Effects:
+            - Ensures consistency in parent-child estimate relationships
+            - Saves final plan to user-specified file
+            - May delete checkpoint file if plan is saved
+            
+        Example:
+            ```python
+            engine = TaskEngine()
+            engine.load_from_file("my_project.json")
+            engine.breakdown_complex_tasks()
+            engine.handle_long_duration_tasks()
+            engine.finalize_plan()  # Review and save final plan
+            ```
+        """
         # Final check of parent-child estimate consistency
         self.tasks = check_and_update_parent_estimates(self.tasks)
         
@@ -187,7 +315,30 @@ class TaskEngine:
             print(f"Plan left in checkpoint '{CHECKPOINT_FILE}'. Run again to resume.")
     
     def run(self) -> None:
-        """Run the full interactive workflow."""
+        """
+        Run the full interactive workflow.
+        
+        Executes the complete scopemate workflow from start to finish:
+        1. Displays introduction to the user
+        2. Loads existing checkpoint or creates new task
+        3. Processes and breaks down complex tasks
+        4. Handles long-duration leaf tasks
+        5. Finalizes and saves the plan
+        
+        This is the main entry point for using the TaskEngine to build a complete
+        task breakdown plan interactively.
+        
+        Side Effects:
+            - Interacts with the user via console
+            - Modifies task list based on user input
+            - Creates/updates files on disk for checkpoints and final plan
+            
+        Example:
+            ```python
+            engine = TaskEngine()
+            engine.run()  # Runs the complete interactive workflow
+            ```
+        """
         # Display introduction
         print("=== scopemate Action Plan Builder ===")
         print("This tool helps break down complex tasks and maintain consistent time estimates.")
@@ -210,13 +361,40 @@ class TaskEngine:
         self.finalize_plan()
 
     def run_interactive(self) -> None:
-        """Run the interactive mode of the application."""
+        """
+        Run the interactive mode of the application.
+        
+        This is a placeholder method for running an alternative interactive mode.
+        Currently just prints the header and would be extended in future versions.
+        
+        Example:
+            ```python
+            engine = TaskEngine()
+            engine.run_interactive()  # Would run an alternative interactive mode
+            ```
+        """
         print("=== scopemate Action Plan Builder ===")
 
 
 def interactive_builder():
     """
     Legacy function for backward compatibility that runs the TaskEngine.
+    
+    Creates a TaskEngine instance and runs the full workflow, handling
+    KeyboardInterrupt exceptions by saving progress to a checkpoint.
+    
+    This function provides backward compatibility with older versions
+    that used this entry point directly.
+    
+    Side Effects:
+        - Creates and runs a TaskEngine instance
+        - Handles KeyboardInterrupt by saving checkpoint
+        
+    Example:
+        ```python
+        from scopemate.engine import interactive_builder
+        interactive_builder()  # Runs the complete workflow
+        ```
     """
     engine = TaskEngine()
     try:

scopemate/interaction.py

@@ -25,13 +25,43 @@ def prompt_user(
     """
     Prompt user for input with optional default and choices validation.
     
+    This function is the primary method for all user interaction in scopemate. It
+    handles displaying prompts, validating input against constraints, and providing
+    default values when the user presses Enter without typing anything.
+    
+    The function implements a validation loop that ensures users can only provide
+    valid input. If choices are specified, the function performs case-insensitive
+    validation against those choices and re-prompts when input is invalid.
+    
+    Features:
+    - Displays a prompt with an optional default value in square brackets
+    - Supports empty input with a default fallback value
+    - Validates input against a predefined set of case-insensitive choices
+    - Provides clear error messages when input doesn't match required choices
+    - Loops until valid input is received
+    
     Args:
-        prompt: The prompt text to display
-        default: Optional default value if user enters nothing
-        choices: Optional list of valid choices
+        prompt (str): The prompt text to display to the user
+        default (Optional[str]): Default value to use if user submits empty input
+        choices (Optional[List[str]]): List of valid input choices for validation
         
     Returns:
-        User's validated input as a string
+        str: The validated user input
+        
+    Example:
+        ```python
+        # Simple prompt with no constraints
+        name = prompt_user("Enter your name")
+        
+        # Prompt with a default value
+        team = prompt_user("Select team", default="Backend")
+        
+        # Prompt with choices validation
+        response = prompt_user("Continue?", default="y", choices=["y", "n"])
+        if response.lower() == "y":
+            # Proceed with action
+            pass
+        ```
     """
     while True:
         suffix = f" [{default}]" if default is not None else ""