Metadata-Version: 2.4
Name: pm-tool
Version: 0.1.3
Summary: Project management CLI for AI assistants
Author-email: metulah <metulah@proton.me>
License-Expression: MIT
Project-URL: Homepage, https://github.com/metulah/pm
Project-URL: Repository, https://github.com/metulah/pm
Keywords: cli,project management,task management,ai,assistant,developer tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Bug Tracking
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: toml>=0.10.2
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: publish
Requires-Dist: build>=1.2; extra == "publish"
Requires-Dist: twine>=6.1; extra == "publish"
Dynamic: license-file

# Project Management CLI for AI Assistants

A command-line tool designed specifically for AI assistants to manage projects and tasks.

## Overview

This tool provides a standardized way for AI assistants to manage projects, tasks, and dependencies through a simple CLI interface. It's designed to be used programmatically by AI assistants, with structured JSON output for easy parsing.

## Features

- **Project Management**: Create, read, update (including status: ACTIVE, COMPLETED, ARCHIVED), and delete projects
- **Task Management**: Create, read, update, and delete tasks with status tracking
- **Dependency Tracking**: Manage dependencies between tasks with circular dependency prevention
- **Structured Output**: JSON-formatted responses (default) or human-readable text (`--format text`)
- **SQLite Storage**: Lightweight, file-based database for easy deployment

## Installation

```bash
pip install pm-tool
```

## Documentation

For quick help on specific commands, you can use the `--help` option:

```bash
pm --help
pm project --help
pm task --help
```

## Project and Task Lifecycles

### Project Lifecycle

```mermaid
stateDiagram-v2
[*] --> PROSPECTIVE: Create
PROSPECTIVE --> ACTIVE: Start work
ACTIVE --> COMPLETED: Finish work
ACTIVE --> ARCHIVED: Archive
ACTIVE --> CANCELLED: Cancel
COMPLETED --> ARCHIVED: Archive
```

### Task Lifecycle

```mermaid
stateDiagram-v2
[*] --> NOT_STARTED: Create
NOT_STARTED --> IN_PROGRESS: Start work
IN_PROGRESS --> COMPLETED: Finish work
IN_PROGRESS --> BLOCKED: Encounter issue
BLOCKED --> IN_PROGRESS: Resolve issue
IN_PROGRESS --> PAUSED: Pause work
PAUSED --> IN_PROGRESS: Resume work
IN_PROGRESS --> ABANDONED: Abandon task
NOT_STARTED --> ABANDONED: Abandon task
```

The project and task lifecycles illustrate the typical status transitions for projects and tasks in the PM tool. Understanding these lifecycles helps users navigate the tool more effectively.

````


## Usage

**Global Options:**

- `--format {json|text}`: Specify the output format (default: `json`).
- `--db-path PATH`: Specify the path to the database file (default: `pm.db`).

These options should be placed _before_ the command group (e.g., `pm --format text project list`).

**Note on Identifiers:** Commands that accept `<project_id>` or `<task_id>` now also accept the auto-generated **slug** for that project or task (e.g., `my-project-name`, `my-task-name`). Using slugs is often more convenient than using the full UUID.

### Project Commands

```bash
# Create a project
pm project create --name "My Project" --description "Project description" [--status STATUS]

# List all projects
pm project list

# Show project details
pm project show <project_id_or_slug>

# Update a project
pm project update <project_id_or_slug> --name "New Name" --description "New description" [--status STATUS] # Prints reminder on status change

# Delete a project
pm project delete <project_id_or_slug> [--force] # Use --force to delete project and its tasks
````

### Task Commands

```bash
# Create a task
pm task create --project <project_id_or_slug> --name "My Task" --description "Task description" --status "NOT_STARTED"

# List tasks (optionally filtered)
pm task list
pm task list --project <project_id_or_slug>
pm task list --status "IN_PROGRESS"

# Show task details
pm task show <project_id_or_slug> <task_id_or_slug>

# Update a task
pm task update <project_id_or_slug> <task_id_or_slug> --name "New Name" --status "COMPLETED" # Prints reminder checklist to stderr on status change

# Delete a task
pm task delete <project_id_or_slug> <task_id_or_slug>
```

### Dependency Commands

```bash
# Add a dependency
pm task dependency add <project_id_or_slug> <task_id_or_slug> --depends-on <dependency_id_or_slug>

# Remove a dependency
pm task dependency remove <project_id_or_slug> <task_id_or_slug> --depends-on <dependency_id_or_slug>

# List dependencies
pm task dependency list <project_id_or_slug> <task_id_or_slug>
```

### Note Commands

```bash
# Add a note to a project or task
pm note add --project <project_id_or_slug> --content "Project note"
pm note add --project <project_id_or_slug> --task <task_id_or_slug> --content "Task note"

# List notes for a project or task
pm note list --project <project_id_or_slug>
pm note list --project <project_id_or_slug> --task <task_id_or_slug>

# Show a note
pm note show <note_id>

# Update a note
pm note update <note_id> --content "Updated content"

# Delete a note
pm note delete <note_id>
```

### Template Commands

```bash
# Create a task template
pm template create --name "My Task Template" --description "Template description"

# List templates
pm template list

# Show template details (including subtask templates)
pm template show <template_id>

# Add a subtask template
pm template add-subtask <template_id> --name "Subtask Template Name" [--description "Desc"] [--optional]

# Apply a template to a task (creates subtasks)
pm template apply <template_id> --task <task_id>

# Delete a template
pm template delete <template_id>
```

### Guideline Commands

```bash
# Show default guidelines
pm welcome

# Show default + specific built-in guidelines (e.g., coding, vcs)
pm welcome -g coding -g vcs

# Show default + guideline from a file path
pm welcome -g @path/to/my_guideline.md

# List custom guidelines saved in .pm/guidelines/
pm guideline list

# Show a specific custom guideline
pm guideline show <custom_guideline_name>

# Create/Update a custom guideline
pm guideline create <name> --content "Guideline content"
pm guideline update <name> --content "New content"

# Copy a built-in guideline to custom directory for modification
pm guideline copy <builtin_name> --new-name <custom_name>

# Delete a custom guideline
pm guideline delete <custom_guideline_name>
```

## Development

### Running Tests

```bash
python3 -m pytest
```

## Next Steps

1. **AI Metadata Integration**

   - Add support for storing AI-specific metadata with tasks
   - Track reasoning paths and decision points
   - Record confidence levels for decisions

2. **Handoff System**

   - Implement structured handoff between AI sessions
   - Track context and state between sessions
   - Provide clear transition points

3. **Storage Abstraction**

   - Create abstract storage interface
   - Support multiple backend options
   - Add remote storage capabilities

4. **Graph Capabilities**

   - Implement advanced dependency visualization
   - Add graph-based querying
   - Support complex dependency analysis

5. **Integration with Other Tools**
   - Add webhooks for notifications
   - Implement API for external access
   - Create plugins for popular AI platforms
