scopemate 0.1.0__py3-none-any.whl → 0.1.2__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.1.2"
 
 # 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 ""

scopemate/llm.py

@@ -26,12 +26,45 @@ def call_llm(prompt: str, model: str = DEFAULT_MODEL) -> dict:
     """
     Invoke LLM to get a structured JSON response.
     
+    This function is the core LLM integration point for scopemate, handling all
+    communication with the OpenAI API. It's designed to always return structured
+    JSON data that can be easily processed by the application.
+    
+    The function:
+    1. Creates an OpenAI client using the default API credentials
+    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. Sets response_format to force JSON output
+    5. 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): The OpenAI model identifier to use (defaults to DEFAULT_MODEL)
         
     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.
+              
+    Example:
+        ```python
+        # Create a prompt asking for task breakdown
+        prompt = f"Break down this task into subtasks: {task.title}"
+        
+        # Call the LLM and get structured data back
+        response = call_llm(prompt)
+        
+        # Process the structured response
+        if "subtasks" in response:
+            for subtask_data in response["subtasks"]:
+                # Create a new subtask from the data
+                subtask = ScopeMateTask(**subtask_data)
+                tasks.append(subtask)
+        ```
     """
     client = OpenAI()
     response = client.chat.completions.create(

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}")

scopemate/task_analysis.py

@@ -15,11 +15,30 @@ def check_and_update_parent_estimates(tasks: List[ScopeMateTask]) -> List[ScopeM
     """
     Check and update parent task estimates based on child task complexity.
     
+    This function ensures consistency in the task hierarchy by making sure that 
+    parent tasks have appropriate size and time estimates relative to their children.
+    If a child task has a higher complexity or longer time estimate than its parent,
+    the parent's estimates are automatically increased to maintain logical consistency.
+    
+    The function works by:
+    1. Creating maps of task IDs to task objects and parent IDs
+    2. Computing complexity values for all tasks based on their size and time estimates
+    3. Identifying inconsistencies where child tasks have higher complexity than parents
+    4. Updating parent estimates to match or exceed their children's complexity
+    5. Recursively propagating updates up the task hierarchy to maintain consistency
+    
     Args:
-        tasks: List of ScopeMateTask objects
+        tasks: List of ScopeMateTask objects to analyze and update
         
     Returns:
-        Updated list of ScopeMateTask objects
+        Updated list of ScopeMateTask objects with consistent parent-child estimates
+        
+    Example:
+        ```python
+        # Before: parent task has "straightforward" size but child has "complex" size
+        updated_tasks = check_and_update_parent_estimates(tasks)
+        # After: parent task is updated to "complex" or higher to maintain consistency
+        ```
     """
     # Create a map of tasks by ID for easy access
     task_map = {t.id: t for t in tasks}
@@ -229,14 +248,36 @@ def should_decompose_task(task: ScopeMateTask, depth: int, max_depth: int, is_le
     """
     Determine if a task should be broken down based on complexity and time estimates.
     
+    This function applies a set of heuristics to decide whether a task needs further
+    decomposition. The decision is based on multiple factors:
+    
+    1. Task depth in the hierarchy - tasks at or beyond max_depth are never decomposed
+    2. Task complexity - "complex", "uncertain", or "pioneering" tasks should be broken down
+    3. Time estimate - tasks with long durations should be broken down into smaller units
+    4. Leaf status - whether the task already has subtasks
+    
+    The breakdown logic implements a graduated approach where:
+    - Very complex tasks are always broken down (unless at max depth)
+    - Long duration tasks are broken down, especially if they're leaf tasks
+    - Tasks with "week" duration are broken down up to max_depth
+    - Tasks at depth 2+ with "sprint" duration aren't broken down (unless they're "multi-sprint")
+    
     Args:
         task: The ScopeMateTask to evaluate
-        depth: Current depth in the task hierarchy
-        max_depth: Maximum allowed depth
-        is_leaf: Whether this is a leaf task (has no children)
+        depth: Current depth in the task hierarchy (0 for root tasks)
+        max_depth: Maximum allowed depth for the task hierarchy
+        is_leaf: Whether this task currently has no children
         
     Returns:
-        True if the task should be broken down, False otherwise
+        True if the task should be broken down into subtasks, False otherwise
+        
+    Example:
+        ```python
+        task = get_task_by_id("TASK-123")
+        depth = get_task_depth(task, task_depths, tasks)
+        if should_decompose_task(task, depth, max_depth=5, is_leaf=True):
+            subtasks = suggest_breakdown(task)
+        ```
     """
     # Always respect max depth limit
     if depth >= max_depth:

{scopemate-0.1.0.dist-info → scopemate-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scopemate
-Version: 0.1.0
+Version: 0.1.2
 Summary: 🪜 A CLI tool for Purpose/Scope/Outcome planning
 Author: Anoop Thomas Mathew
 Author-email: Anoop Thomas Mathew <atmb4u@gmail.com>
@@ -78,6 +78,7 @@ Scopemate is built around a three-part framework for strategic decision making:
 - Pydantic validation
 - Cross-platform support (Windows, macOS, Linux)
 - Works with Python 3.10 and above
+- Automatic Markdown export of plans for easy sharing
 
 ## Requirements
 
@@ -171,11 +172,10 @@ scopemate --help
 
 # Generate a project plan with purpose and outcome
 scopemate --purpose="Build a REST API for user management" --outcome="A documented API with authentication and user CRUD operations" --output="project_plan.json"
-
-# Fix inconsistent estimates in an existing plan
-scopemate --fix-estimates --input="project_plan.json" --output="fixed_plan.json"
 ```
 
+**Note:** A Markdown version of the output is automatically generated alongside the JSON file. For example, if you specify `--output="project_plan.json"`, a file named `project_plan.md` will also be created.
+
 ### Interactive Mode Workflow
 
 The interactive mode (`scopemate --interactive`) will guide you through:
@@ -205,7 +205,9 @@ The interactive mode (`scopemate --interactive`) will guide you through:
 
 ### Output Format
 
-scopemate generates a structured JSON output with the following format:
+scopemate generates both JSON and Markdown output files:
+
+1. **JSON Output** - Structured data format with the following structure:
 
 ```json
 {
@@ -245,6 +247,14 @@ scopemate generates a structured JSON output with the following format:
 }
 ```
 
+2. **Markdown Output** - Human-readable format automatically generated with the same basename as the JSON file. The Markdown output includes:
+   - A summary of the plan with task counts and complexity breakdown
+   - Hierarchical task structure preserving parent-child relationships
+   - All relevant task details formatted for easy reading
+   - Properly formatted sections for purpose, scope, outcome, and metadata
+
+This dual output approach makes it easy to both process the data programmatically (using the JSON) and share the plan with team members (using the Markdown).
+
 ### Integrating with Other Tools
 
 You can use scopemate's JSON output with other project management tools:
@@ -295,6 +305,23 @@ uv pip install -r requirements-dev.txt
 uv pip install -e .
 ```
 
+#### Using pipx
+
+[pipx](https://github.com/pypa/pipx) is useful for installing and running Python applications in isolated environments:
+
+```bash
+# Install pipx if you don't have it
+pip install pipx
+
+# Clone the repository
+git clone https://github.com/atmb4u/scopemate.git
+cd scopemate
+
+# Install the package in development mode with force flag
+# This is useful when making changes and wanting to test the CLI immediately
+pipx install --force .
+```
+
 ### Running Tests
 
 ```bash

scopemate-0.1.2.dist-info/RECORD

@@ -0,0 +1,17 @@
+scopemate/__init__.py,sha256=sMbeuIqGXqrO47d1LD4gk6r5cLHuZmRtVXR797c8K2s,472
+scopemate/__main__.py,sha256=nPNZe_QEoOHQ_hXf17w72BHz1UFPKuW2g3whTLwuM8E,195
+scopemate/breakdown.py,sha256=mwIDzf7m2GHVkDrRmMyeS8v2pNd99U3vlcPCtOajvs0,21048
+scopemate/cli.py,sha256=qh6iFleQc8Bld0iptyUgRm5Ga3GtZsvE6Y-q6vbm3dk,6891
+scopemate/core.py,sha256=wpXCpb5Kdpqul9edNCx2Da94137XCc1w-3KQc9-Tf3s,700
+scopemate/engine.py,sha256=8yQoxSECJCGuNSIwS-qFoaOGM1iaZ-y4Lo7k5Q6v-mk,16992
+scopemate/interaction.py,sha256=SeqQVME0MATK-m-M7T9nNHkcJ_VCRhlqydL_vQaSMWk,10893
+scopemate/llm.py,sha256=k_1FQdg_TRt_51Yu_g_PjO0pBnmFmWHoK_-KEPGlASM,15526
+scopemate/models.py,sha256=Q3SUoHu_4RejDAocEr83I00wGvxhDoJ1COVqjPsr4DQ,7738
+scopemate/storage.py,sha256=uV1-7IdwJwBENeNoO9Y3WwUUXd-jA2NvKdiERGGhmV8,11642
+scopemate/task_analysis.py,sha256=Mic0FOOy_BWI1_5TQmh__39miOcZBZ7mTUcCkv1DvkI,14967
+scopemate-0.1.2.dist-info/licenses/LICENSE,sha256=4fqQFK5AkkXmg6FBG9Wr06gCR7BMQl02TvsPYt-YL6s,1076
+scopemate-0.1.2.dist-info/METADATA,sha256=APn2Igy4cl3jhcP9gh6gwOHnBLMnN3CPsL4MrvDVabc,11774
+scopemate-0.1.2.dist-info/WHEEL,sha256=lTU6B6eIfYoiQJTZNc-fyaR6BpL6ehTzU3xGYxn2n8k,91
+scopemate-0.1.2.dist-info/entry_points.txt,sha256=XXusGEDxI6NlrYmSBcPDtjV3QvsHWVWPSrt4zD4UcLg,49
+scopemate-0.1.2.dist-info/top_level.txt,sha256=riMrI_jMCfZMb7-ecWBwqOBLdUsnPOxSu2Pgvqx7Too,10
+scopemate-0.1.2.dist-info/RECORD,,

scopemate-0.1.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-scopemate/__init__.py,sha256=3cyRjjI2wC2pG8VeXONVOrow_dJMKUCzre8EtYfrV0s,472
-scopemate/__main__.py,sha256=nPNZe_QEoOHQ_hXf17w72BHz1UFPKuW2g3whTLwuM8E,195
-scopemate/breakdown.py,sha256=lasv2Gt1yziE_GV4DgCBWVg3TIPuggT3Tf77ny5n7Iw,19650
-scopemate/cli.py,sha256=o05Od9NEP76sQRegc3dqs-d-DCpYip2KC1GXjriiCZQ,5059
-scopemate/core.py,sha256=wpXCpb5Kdpqul9edNCx2Da94137XCc1w-3KQc9-Tf3s,700
-scopemate/engine.py,sha256=wlE39lzKoJthi6twestlyEqvEjqNEXQYvNTOfT4aGZw,9521
-scopemate/interaction.py,sha256=qWFU3QM_KPwaGdh4Rw7ewCIeYiT6Wa_H9e6bnmNoJzw,9531
-scopemate/llm.py,sha256=hD37Mk54kchdECKYmCNF3yxg0U-vW-h4y8tpNghlS3Q,14031
-scopemate/models.py,sha256=ZvFn8iegMDgCgoLjvWxj7_C7XLDWrgkF8ySuktfRaqw,4962
-scopemate/storage.py,sha256=lloD_2f2E3q_inHLiL9Kp8F_tyeerG45_rSLKXvGh4Y,3102
-scopemate/task_analysis.py,sha256=I-tH62MfYAwlHbLonjlPKBGa-X_II9QqpWS_OsjLaxU,12644
-scopemate-0.1.0.dist-info/licenses/LICENSE,sha256=4fqQFK5AkkXmg6FBG9Wr06gCR7BMQl02TvsPYt-YL6s,1076
-scopemate-0.1.0.dist-info/METADATA,sha256=Wmb1wOEmCkigLUXIS0d1BujGzV0uTpx9IpNIvyrtIJI,10557
-scopemate-0.1.0.dist-info/WHEEL,sha256=lTU6B6eIfYoiQJTZNc-fyaR6BpL6ehTzU3xGYxn2n8k,91
-scopemate-0.1.0.dist-info/entry_points.txt,sha256=XXusGEDxI6NlrYmSBcPDtjV3QvsHWVWPSrt4zD4UcLg,49
-scopemate-0.1.0.dist-info/top_level.txt,sha256=riMrI_jMCfZMb7-ecWBwqOBLdUsnPOxSu2Pgvqx7Too,10
-scopemate-0.1.0.dist-info/RECORD,,