scopemate 0.1.0__py3-none-any.whl

scopemate-0.1.0.dist-info/METADATA

@@ -0,0 +1,410 @@
+Metadata-Version: 2.4
+Name: scopemate
+Version: 0.1.0
+Summary: 🪜 A CLI tool for Purpose/Scope/Outcome planning
+Author: Anoop Thomas Mathew
+Author-email: Anoop Thomas Mathew <atmb4u@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/atmb4u/scopemate
+Project-URL: Bug Tracker, https://github.com/atmb4u/scopemate/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: twine>=6.1.0
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# 🪜 scopemate
+
+A CLI tool for breaking down complex tasks into smaller subtasks with LLM-powered scope estimation and planning.
+
+## Conceptual Framework
+
+Scopemate is built around a three-part framework for strategic decision making:
+
+### 🧭 Purpose → Strategic Relevance
+
+**"Why does this matter now?"**
+
+- Is it aligned with a company priority, customer need, or mission-critical goal?
+- If we didn't do it, would anything break or stall?
+- Does this move us closer to where we want to be?
+
+> **✅ If not strategic, it's a distraction.**
+
+### 📦 Scope → Executable Shape
+
+**"Can we actually do this — fast and clearly?"**
+
+- Is it defined tightly enough to start today or this week?
+- Can one person or squad own it end-to-end?
+- What's the smallest useful version we can ship?
+
+> **✅ If it's vague or sprawling, it needs slicing.**
+
+### 🎯 Outcome → Meaningful Result
+
+**"What will change once this is done?"**
+
+- Will this give us clarity, value, or unlock something else?
+- How will we measure success — learning, delivery, or stability?
+- What does "done" look like in a way others can see?
+
+> **✅ If the outcome is fuzzy, stop and clarify.**
+
+## Features
+
+- Break down complex tasks into smaller subtasks
+- LLM-driven scope estimation & breakdown
+- Interactive task breakdown with alternative approaches
+- Automatic fixing of inconsistent time estimates
+- Checkpointing (pause & resume)
+- Auto-detect when child tasks take more time than parents
+- Auto-adjust parent scope estimates based on child complexity
+- Pydantic validation
+- Cross-platform support (Windows, macOS, Linux)
+- Works with Python 3.10 and above
+
+## Requirements
+
+- Python 3.10 or higher
+- OpenAI API key set as environment variable (`OPENAI_API_KEY`)
+
+## Installation
+
+### From PyPI (Recommended)
+
+The easiest way to install scopemate is from PyPI:
+
+```bash
+# Install using pip (any platform)
+pip install scopemate
+
+# Or using pip3 on some systems
+pip3 install scopemate
+```
+
+### Platform-Specific Installation Scripts
+
+#### macOS and Linux
+
+```bash
+# Clone the repository
+git clone https://github.com/atmb4u/scopemate.git
+cd scopemate
+
+# Install using the script (automatically checks Python version)
+./install.sh
+```
+
+#### Windows
+
+```powershell
+# Clone the repository
+git clone https://github.com/atmb4u/scopemate.git
+cd scopemate
+
+# Install using the script (automatically checks Python version)
+.\install.bat
+```
+
+### Manual Installation from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/atmb4u/scopemate.git
+cd scopemate
+
+# Install in development mode
+pip install -e .
+```
+
+### Setting up the OpenAI API Key
+
+scopemate requires an OpenAI API key to function. Set it as an environment variable:
+
+#### macOS/Linux
+```bash
+export OPENAI_API_KEY=your-api-key-here
+```
+
+#### Windows Command Prompt
+```cmd
+set OPENAI_API_KEY=your-api-key-here
+```
+
+#### Windows PowerShell
+```powershell
+$env:OPENAI_API_KEY = "your-api-key-here"
+```
+
+For permanent setup, add this to your shell profile or environment variables.
+
+## Usage
+
+### Quick Start
+
+```bash
+# Run in interactive mode (recommended for first-time users)
+scopemate --interactive
+```
+
+### Command-line Options
+
+```bash
+# Get help and see all available options
+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"
+```
+
+### Interactive Mode Workflow
+
+The interactive mode (`scopemate --interactive`) will guide you through:
+
+1. **Initial Setup**:
+   - Create a new task or load an existing plan
+   - Set the main purpose and intended outcome
+
+2. **Task Definition**:
+   - Define the scope of work
+   - Set dependencies and identify risks
+   - Define acceptance criteria
+
+3. **Task Breakdown**:
+   - Automatically break down complex tasks into manageable subtasks
+   - Review and modify suggested breakdowns
+   - Explore alternative approaches to solving the problem
+
+4. **Validation and Refinement**:
+   - Automatically detect and fix inconsistent time estimates
+   - Check for tasks where children take more time than parents
+   - Adjust parent scope estimates based on child complexity
+
+5. **Save and Export**:
+   - Save your plan to a JSON file
+   - Resume work later using checkpoints
+
+### Output Format
+
+scopemate generates a structured JSON output with the following format:
+
+```json
+{
+  "tasks": [
+    {
+      "id": "TASK-abc123",
+      "title": "Task title",
+      "purpose": {
+        "detailed_description": "Why this task matters",
+        "alignment": ["Strategic goal 1", "Strategic goal 2"],
+        "urgency": "strategic"
+      },
+      "scope": {
+        "size": "complex",
+        "time_estimate": "sprint",
+        "dependencies": ["Dependency 1"],
+        "risks": ["Risk 1", "Risk 2"]
+      },
+      "outcome": {
+        "type": "customer-facing",
+        "detailed_outcome_definition": "What will be delivered",
+        "acceptance_criteria": ["Criterion 1", "Criterion 2"],
+        "metric": "Success measurement",
+        "validation_method": "How to validate"
+      },
+      "meta": {
+        "status": "backlog",
+        "priority": 1,
+        "created": "2023-06-01T12:00:00Z",
+        "updated": "2023-06-01T12:00:00Z",
+        "due_date": null,
+        "confidence": "medium"
+      },
+      "parent_id": null
+    }
+  ]
+}
+```
+
+### Integrating with Other Tools
+
+You can use scopemate's JSON output with other project management tools:
+
+- Import tasks into JIRA using their API
+- Convert to CSV for import into spreadsheets
+- Integrate with custom project dashboards
+
+## Development
+
+### Setting Up Development Environment
+
+#### Prerequisites
+
+- Python 3.10 or higher
+- Git
+
+#### Using pip
+
+```bash
+# Clone the repository
+git clone https://github.com/atmb4u/scopemate.git
+cd scopemate
+
+# Install development dependencies
+pip install -r requirements-dev.txt
+
+# Install the package in development mode
+pip install -e .
+```
+
+#### Using uv (Recommended)
+
+[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver:
+
+```bash
+# Install uv if you don't have it
+pip install uv
+
+# Clone the repository
+git clone https://github.com/atmb4u/scopemate.git
+cd scopemate
+
+# Install development dependencies with uv
+uv pip install -r requirements-dev.txt
+
+# Install the package in development mode
+uv pip install -e .
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run tests with verbose output
+pytest -v
+
+# Run a specific test file
+pytest tests/test_basic.py
+
+# Run tests with coverage report
+pytest --cov=scopemate
+```
+
+### Building Distribution Packages
+
+#### macOS and Linux
+
+```bash
+# Build distribution packages
+./publish.sh
+
+# Upload to PyPI (when ready)
+twine upload dist/*
+```
+
+#### Windows
+
+```powershell
+# Build distribution packages
+.\publish.bat
+
+# Upload to PyPI (when ready)
+twine upload dist/*
+```
+
+### Code Style and Linting
+
+We use ruff for linting and code formatting:
+
+```bash
+# Run linter
+ruff check src tests
+
+# Format code
+ruff format src tests
+```
+
+### Testing Cross-Platform Compatibility
+
+Use tox to test across multiple Python versions:
+
+```bash
+# Install tox
+pip install tox
+
+# Run tox
+tox
+
+# Run tox for a specific Python version
+tox -e py310
+```
+
+## Repository Structure
+
+```
+.
+├── LICENSE             # MIT License
+├── MANIFEST.in         # Package manifest
+├── README.md           # Project documentation
+├── publish.sh          # Build and publish script (Unix)
+├── publish.bat         # Build and publish script (Windows)
+├── install.sh          # Installation script (Unix)
+├── install.bat         # Installation script (Windows)
+├── pyproject.toml      # Project configuration
+├── requirements.txt    # Project dependencies
+├── requirements-dev.txt # Development dependencies
+├── setup.py            # Package setup
+├── tox.ini             # Tox configuration
+├── tests/              # Test directory
+│   ├── __init__.py     # Test package initialization
+│   ├── test_basic.py   # Basic tests
+│   └── test_platform.py # Platform compatibility tests
+└── src/                # Source code
+    └── scopemate/      # Main package
+        ├── __init__.py # Package initialization
+        ├── __main__.py # Entry point
+        ├── breakdown.py # Task breakdown logic
+        ├── cli.py      # Command-line interface
+        ├── core.py     # Core functionality
+        ├── engine.py   # Main application logic
+        ├── interaction.py # User interaction helpers
+        ├── llm.py      # LLM integration
+        ├── models.py   # Data models
+        ├── storage.py  # Task storage
+        └── task_analysis.py # Task analysis helpers
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

scopemate-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+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,,

scopemate-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scopemate-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scopemate = scopemate.cli:main

scopemate-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anoop Thomas Mathew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

scopemate-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+scopemate