Sync roadmap plans (epics, stories, tasks) to GitHub Issues and Projects v2.
⭐ If planpilot helps you manage your roadmaps, consider giving it a star!
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 installTell your agent:
Fetch and follow instructions from https://raw.githubusercontent.com/aryeko/planpilot/v2.3.0/skills/INSTALL.agent.md
The agent will install both planpilot and the skill automatically.
Install the skill to the open discovery path used by agent platforms that support filesystem skills:
mkdir -p ~/.agents/skills/roadmap-to-github-project
curl -fsSL "https://raw.githubusercontent.com/aryeko/planpilot/v2.3.0/skills/roadmap-to-github-project/SKILL.md" \
-o ~/.agents/skills/roadmap-to-github-project/SKILL.mdOr from a local checkout:
cp skills/roadmap-to-github-project/SKILL.md \
~/.agents/skills/roadmap-to-github-project/SKILL.mdFull standalone instructions: 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.