npx claudepluginhub aryeko/planpilotClaude Code skills and commands for planning workflows: create PRDs, tech specs, and sync plans to GitHub Issues + Projects v2
aryeko
planpilot
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"]
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.
repo and project scopesgh CLI only when using auth: "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 planpilot
pipx installs CLI tools in isolated environments -- avoids PEP 668 / "externally managed environment" errors on macOS Homebrew and system Python.
python3 -m venv .venv && source .venv/bin/activate
pip install planpilot
poetry install
See 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-run
planpilot - 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:
Development marketplace for Superpowers core skills library
Harness-native ECC skills, hooks, rules, MCP conventions, and operator workflows
Open Design — local-first design app exposed to coding agents over MCP. Install once with your agent's plugin command and projects/files/skills are reachable through stdio.