Sync roadmap plans (epics, stories, tasks) to GitHub Issues and Projects v2.
⭐ If planpilot helps you manage your roadmaps, consider giving it a star!
Managing roadmaps through GitHub's UI works for small projects, but breaks down fast: manually creating dozens of issues, linking parent/child hierarchies, setting up blocked-by dependencies, and keeping project board fields in sync is tedious and error-prone. Scripting the GitHub API directly means dealing with pagination, rate limits, idempotency, and GraphQL complexity.
planpilot treats your roadmap as code. Define epics, stories, and tasks in JSON files, commit them alongside your source code, and let planpilot handle the rest — creating issues, wiring up sub-issue hierarchies, setting blocked-by relations, and populating project board fields. It's idempotent (safe to rerun), supports dry-run previews, and works across multiple epics in a single run.
planpilot takes structured plan files and turns them into a fully linked project board:
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: sync multiple epics natively in one run
- Provider-agnostic: adapter pattern supports GitHub today, with Jira/Linear planned
- Async-first: built on asyncio for fast, concurrent sync operations
planpilot follows SOLID principles with a modular, provider-agnostic design:
src/planpilot/
├── core/ # Runtime domains (auth/config/contracts/engine/plan/providers/renderers)
├── cli/ # CLI parser/app/commands and persistence helpers
├── sdk.py # SDK composition root and public facade
└── __init__.py # Public API exports
Core domains provide business logic, and the SDK composes runtime pieces. This keeps provider and renderer implementations swappable without changing engine internals.
See docs/design/architecture.md for the full architecture guide.
- Python 3.11+
- GitHub token with
repoandprojectscopes ghCLI only when usingauth: "gh-cli"
# Install pipx if you don't have it
brew install pipx && pipx ensurepath # macOS
# or: sudo apt install -y pipx && pipx ensurepath # Debian/Ubuntu
# Install planpilot
pipx install planpilotpipx installs CLI tools in isolated environments -- avoids PEP 668 / "externally managed environment" errors on macOS Homebrew and system Python.
Alternative: pip (inside a virtualenv)
python3 -m venv .venv && source .venv/bin/activate
pip install planpilotFrom source (Poetry)
poetry installSee planpilot in action without any configuration or GitHub token — the built-in example runs a fully offline dry-run:
git clone https://github.com/aryeko/planpilot.git && cd planpilot
pipx install . # or: pip install .
planpilot sync --config examples/sync-workflow/planpilot.json --dry-runplanpilot - sync complete (dry-run)
Plan ID: 3832d3ffce22
Target: example-org/example-repo
Board: https://github.com/orgs/example-org/projects/1
Items: 6 total (1 epic, 2 stories, 3 tasks)
Created: 6 (1 epic, 2 stories, 3 tasks)
Sync map: /absolute/path/to/examples/sync-workflow/output/sync-map-sample.json.dry-run
[dry-run] No changes were made
planpilot ships three agent skills that form a complete product workflow:
| Skill | Purpose |
|---|---|
create-prd |
Generate structured PRDs from feature ideas |
create-tech-spec |
Create codebase-aware technical specs from PRDs |
plan-sync |
Sync specs to GitHub Issues + Projects v2 |
Install the planpilot plugin directly in Claude Code (the planpilot CLI is installed automatically from PyPI):
claude plugin marketplace add aryeko/planpilot
claude plugin install planpilot@planpilotThen use:
/planpilot:prd— create a PRD from a feature idea/planpilot:spec— create a tech spec from a PRD/planpilot:sync— generate.plansJSON and sync to GitHub
Tell your agent:
Fetch and follow instructions from https://raw.githubusercontent.com/aryeko/planpilot/main/src/planpilot/skills/INSTALL.agent.md
The agent will install planpilot and all three skills automatically.
Install skills to the open discovery path used by agent platforms that support filesystem skills:
for skill in create-prd create-tech-spec plan-sync; do
mkdir -p ~/.agents/skills/$skill
curl -fsSL "https://raw.githubusercontent.com/aryeko/planpilot/main/src/planpilot/skills/$skill/SKILL.md" \
-o ~/.agents/skills/$skill/SKILL.md
doneFull standalone instructions: src/planpilot/skills/INSTALL.md
planpilot initThe interactive wizard auto-detects your git remote and guides you through provider, target repo, board URL, plan layout, and auth. Or create the config manually:
cat > planpilot.json <<'JSON'
{
"provider": "github",
"target": "your-org/your-repo",
"board_url": "https://github.com/orgs/your-org/projects/1",
"plan_paths": {
"epics": ".plans/epics.json",
"stories": ".plans/stories.json",
"tasks": ".plans/tasks.json"
},
"sync_path": ".plans/sync-map.json"
}
JSONplanpilot sync --config ./planpilot.json --dry-runplanpilot sync --config ./planpilot.json --applyplanpilot supports multi-epic plans natively. Keep all epics/stories/tasks in the configured plan files and run once:
planpilot sync --config ./planpilot.json --apply| Flag | Default | Description |
|---|---|---|
--output, -o |
planpilot.json |
Output file path |
--defaults |
off | Generate config with auto-detected defaults (no prompts) |
| Flag | Default | Description |
|---|---|---|
--config |
./planpilot.json |
Path to planpilot.json |
--dry-run |
— | Preview mode (no provider mutations) |
--apply |
— | Apply mode |
--verbose |
off | Enable verbose logging |
| Flag | Default | Description |
|---|---|---|
--config |
./planpilot.json |
Path to planpilot.json |
--dry-run |
— | Preview which issues would be deleted |
--apply |
— | Execute deletions |
--all |
off | Delete all planpilot-managed issues by label, regardless of current plan hash |
--verbose |
off | Enable verbose logging |
| Flag | Default | Description |
|---|---|---|
--config |
./planpilot.json |
Path to planpilot.json |
--dry-run |
— | Preview local sync-map reconciliation |
--apply |
— | Persist reconciled local sync-map |
--plan-id |
auto | Explicit remote plan ID to reconcile |
--verbose |
off | Enable verbose logging |
map sync reconciles local artifacts from provider metadata only; it does not mutate provider items.
In apply mode it writes both the local sync-map and local plan files.
Full CLI reference: docs/modules/cli.md
See docs/reference/plan-schemas.md for plan schema examples and docs/modules/plan.md for validation behavior.
A complete working example is in the examples/ directory, including sample rendered issue bodies and a sync-map output.
- Start here:
- Architecture and behavior:
- Module implementation details:
- Operations:
- Questions / ideas: use GitHub Discussions
- Bugs / feature requests: open a GitHub Issue
Branding assets (logo + social preview images) are in assets/branding/navigator/.
Development tasks use poethepoet:
poe lint # ruff check
poe format # ruff format
poe docs-links # validate local markdown links
poe test # pytest -v --ignore=tests/e2e
poe test-e2e # run offline E2E suite
poe coverage # pytest + HTML coverage report
poe coverage-e2e # E2E-only coverage XML
poe typecheck # mypy
poe check # lint + format-check + typecheck + testsSee CONTRIBUTING.md for setup and development instructions.