Metadata-Version: 2.4
Name: planpilot
Version: 1.1.1
Summary: Sync roadmap plans (epics, stories, tasks) to GitHub Issues and Projects v2
License: MIT
License-File: LICENSE
Keywords: github,projects,roadmap,sync,issues
Author: aryeko
Requires-Python: >=3.11
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Project-URL: Homepage, https://github.com/aryeko/planpilot
Project-URL: Repository, https://github.com/aryeko/planpilot
Description-Content-Type: text/markdown

# planpilot

[![CI](https://github.com/aryeko/planpilot/actions/workflows/ci.yml/badge.svg)](https://github.com/aryeko/planpilot/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/aryeko/planpilot/graph/badge.svg?token=3I2A515YTI)](https://codecov.io/gh/aryeko/planpilot)
[![PyPI](https://img.shields.io/pypi/v/planpilot)](https://pypi.org/project/planpilot/)
[![Python](https://img.shields.io/pypi/pyversions/planpilot)](https://pypi.org/project/planpilot/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Sync roadmap plans (epics, stories, tasks) to GitHub Issues and Projects v2.

## What it does

**planpilot** takes structured plan files and turns them into a fully linked project board:

```mermaid
flowchart LR
    A["roadmap.md"] --> B["epics.json\nstories.json\ntasks.json"]
    B -->|planpilot| C["GitHub Issues\n+ Projects v2"]
    C --> D["Epic / Story / Task\nissue types"]
    C --> E["Sub-issue\nhierarchy"]
    C --> F["Blocked-by\ndependencies"]
    C --> G["Project fields\nstatus, priority,\niteration, size"]
```

- **One-way sync**: local plan files -> GitHub
- **Idempotent**: safe to rerun -- updates existing issues via markers
- **Dry-run first**: preview all changes before applying
- **Multi-epic**: slice large plans and sync each epic sequentially
- **Provider-agnostic**: adapter pattern supports GitHub today, with Jira/Linear planned
- **Async-first**: built on asyncio for fast, concurrent sync operations

## Architecture

planpilot follows SOLID principles with a modular, provider-agnostic design:

```text
src/planpilot/
├── models/          # Pydantic domain models (Plan, Epic, Story, Task, …)
├── plan/            # Plan loading, validation, and hashing
├── providers/       # Provider adapter pattern (ABC + implementations)
│   └── github/      # GitHub adapter (gh CLI)
├── rendering/       # Issue body rendering (Protocol + Markdown impl)
├── sync/            # Sync engine orchestrator + relation logic
├── config.py        # SyncConfig (pydantic)
├── exceptions.py    # Custom exception hierarchy
├── cli.py           # CLI entry point
└── slice.py         # Multi-epic plan slicing
```

The sync engine depends only on abstract interfaces (`Provider` ABC and `BodyRenderer` Protocol), making it easy to add new providers (Jira, Linear) without touching the core sync logic.

See [docs/architecture.md](docs/architecture.md) for the full architecture guide.

## Requirements

- Python 3.11+
- [`gh` CLI](https://cli.github.com/) installed and authenticated
- GitHub token scopes: `repo`, `project`

## Installation

```bash
pip install planpilot
```

Or with Poetry:

```bash
poetry add planpilot
```

## Quickstart

### 1. Dry-run (preview changes)

```bash
planpilot \
  --repo your-org/your-repo \
  --project-url https://github.com/orgs/your-org/projects/1 \
  --epics-path .plans/epics.json \
  --stories-path .plans/stories.json \
  --tasks-path .plans/tasks.json \
  --sync-path .plans/github-sync-map.json \
  --dry-run
```

### 2. Apply changes

```bash
planpilot \
  --repo your-org/your-repo \
  --project-url https://github.com/orgs/your-org/projects/1 \
  --epics-path .plans/epics.json \
  --stories-path .plans/stories.json \
  --tasks-path .plans/tasks.json \
  --sync-path .plans/github-sync-map.json \
  --apply
```

### 3. Multi-epic plans

The sync tool expects one epic per run. For multi-epic plans, slice first:

```bash
planpilot-slice \
  --epics-path .plans/epics.json \
  --stories-path .plans/stories.json \
  --tasks-path .plans/tasks.json \
  --out-dir .plans/tmp
```

Then sync each epic:

```bash
for f in .plans/tmp/epics.*.json; do
  id=$(basename "$f" .json | sed 's/epics\.//')
  planpilot \
    --repo your-org/your-repo \
    --project-url https://github.com/orgs/your-org/projects/1 \
    --epics-path ".plans/tmp/epics.${id}.json" \
    --stories-path ".plans/tmp/stories.${id}.json" \
    --tasks-path ".plans/tmp/tasks.${id}.json" \
    --sync-path ".plans/github-sync-map.${id}.json" \
    --apply
done
```

## Optional flags

| Flag | Default | Description |
|------|---------|-------------|
| `--label` | `codex` | Label applied to created issues |
| `--status` | `Backlog` | Project status field value |
| `--priority` | `P1` | Project priority field value |
| `--iteration` | `active` | Iteration title, `active`, or `none` |
| `--size-field` | `Size` | Project size field name |
| `--no-size-from-tshirt` | off | Disable t-shirt size mapping |
| `--verbose` | off | Enable verbose logging |

Full CLI reference: [docs/cli-reference.md](docs/cli-reference.md)

## Plan file schemas

See [docs/schemas.md](docs/schemas.md) for the expected structure of `epics.json`, `stories.json`, and `tasks.json`, with full examples.

A complete working example is in the [examples/](examples/) directory, including sample rendered issue bodies and a sync-map output.

## Documentation

- [How It Works](docs/how-it-works.md) -- sync pipeline, idempotency, what gets created
- [CLI Reference](docs/cli-reference.md) -- all flags and commands
- [Plan Schemas](docs/schemas.md) -- JSON format with examples and validation rules
- [Architecture](docs/architecture.md) -- module map, data flow, provider pattern, extension guide
- [Release Guide](RELEASE.md) -- automated versioning, publishing, and release pipeline

## Development

Development tasks use [poethepoet](https://github.com/nat-n/poethepoet):

```bash
poe lint           # ruff check
poe format         # ruff format
poe test           # pytest -v
poe coverage       # pytest + HTML coverage report
poe typecheck      # mypy
poe check          # lint + format-check + tests (all-in-one)
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and development instructions.

## License

[MIT](LICENSE)

