planpilot 2.4.0__tar.gz → 2.5.0__tar.gz

{planpilot-2.4.0 → planpilot-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: planpilot
-Version: 2.4.0
+Version: 2.5.0
 Summary: Sync roadmap plans (epics, stories, tasks) to GitHub Issues and Projects v2
 License: MIT
 License-File: LICENSE

{planpilot-2.4.0 → planpilot-2.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "planpilot"
-version = "2.4.0"
+version = "2.5.0"
 description = "Sync roadmap plans (epics, stories, tasks) to GitHub Issues and Projects v2"
 readme = "README.md"
 license = "MIT"

{planpilot-2.4.0 → planpilot-2.5.0}/src/planpilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "planpilot",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Claude Code skills and commands for planning workflows: create PRDs, tech specs, and sync plans to GitHub Issues + Projects v2",
   "author": {
     "name": "Arye Kogan",
@@ -13,6 +13,6 @@
   "keywords": ["planning", "github", "roadmap", "issues", "projects", "prd", "spec"],
   "category": "workflow",
   "tags": ["planning", "github-projects", "roadmap", "prd", "tech-spec", "skills", "commands"],
-  "skills": ["./skills/"],
-  "commands": ["./commands/"]
+  "skills": ["../skills/"],
+  "commands": ["../commands/"]
 }

{planpilot-2.4.0 → planpilot-2.5.0}/src/planpilot/__init__.py

@@ -1,6 +1,6 @@
 """Public API surface for PlanPilot."""
 
-__version__ = "2.4.0"
+__version__ = "2.5.0"
 
 from planpilot.core.auth import (
     create_init_token_resolver,

{planpilot-2.4.0 → planpilot-2.5.0}/src/planpilot/skills/INSTALL.agent.md

@@ -14,13 +14,45 @@ python3 --version
 
 If `python3` is not found, try `python --version`. You need Python 3.11+.
 
-If Python is not installed, STOP and tell the user:
+If Python is not installed or below 3.11, STOP and tell the user:
 
 > Python 3.11+ is required. Please install it from https://python.org and try again.
 
-## Step 2: Ensure pipx is available
+## Step 2: Install planpilot
 
-Check if `pipx` is installed:
+All options below put `planpilot` on PATH so it can be invoked directly.
+
+**Option A — via `uv` (recommended):**
+
+Check if `uv` is available:
+
+```bash
+uv --version
+```
+
+If not found, install it:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+> **Note:** Piping to `sh` without checksum verification is the officially recommended method but carries inherent supply-chain risk. For a verified install, see [uv GitHub releases](https://github.com/astral-sh/uv/releases) for SHA-256 hashes.
+
+```bash
+source "$HOME/.local/bin/env" 2>/dev/null || export PATH="$HOME/.local/bin:$PATH"
+```
+
+Then install planpilot:
+
+```bash
+uv tool install planpilot
+```
+
+If this succeeds, skip to Step 3.
+
+**Option B — via `pipx`:**
+
+Check if `pipx` is available:
 
 ```bash
 pipx --version
@@ -44,35 +76,31 @@ If `pipx` is **not found**, install it:
   python3 -m pipx ensurepath
   ```
 
-After installing pipx, you may need to open a new shell or `source ~/.bashrc` / `source ~/.zshrc` for the PATH update to take effect.
-
-## Step 3: Install planpilot
+After installing pipx, you may need to open a new shell or `source ~/.bashrc` / `source ~/.zshrc` for PATH to update.
 
 ```bash
 pipx install planpilot
 ```
 
-If this fails, STOP and tell the user the error output.
-
-## Step 4: Verify planpilot
+If this succeeds, skip to Step 3.
 
-Run (try in order until one succeeds):
+**Option C — via `pip3` (last resort):**
 
 ```bash
-planpilot --version
+pip3 install planpilot
 ```
 
-```bash
-python3 -m planpilot --version
-```
+If this fails, STOP and tell the user the error output.
+
+## Step 3: Verify planpilot
 
 ```bash
-python -m planpilot --version
+planpilot --version
 ```
 
-If none work, STOP and report the failure to the user.
+If this fails, STOP and report the failure to the user.
 
-## Step 5: Install the skills
+## Step 4: Install the skills
 
 Install `plan-sync`:
 
@@ -109,7 +137,7 @@ curl -fsSL "https://raw.githubusercontent.com/aryeko/planpilot/main/src/planpilo
 
 If `curl` is not available, try `wget` for any of the above (replace `curl -fsSL ... -o` with `wget -qO`).
 
-## Step 6: Verify skill install
+## Step 5: Verify skill install
 
 Verify all three skills were installed:
 
@@ -131,7 +159,22 @@ head -5 ~/.agents/skills/create-tech-spec/SKILL.md
 
 Should contain `name: create-tech-spec`.
 
-If any are missing or incorrect, retry Step 5.
+If any are missing or incorrect, retry Step 4.
+
+## Step 6: Update planpilot (if requested)
+
+If the user asks to update planpilot:
+
+```bash
+# If installed via uv
+uv tool upgrade planpilot
+
+# If installed via pipx
+pipx upgrade planpilot
+
+# If installed via pip3
+pip3 install --upgrade planpilot
+```
 
 ## Step 7: Report to user
 

{planpilot-2.4.0 → planpilot-2.5.0}/src/planpilot/skills/INSTALL.md

@@ -26,36 +26,41 @@ The agent will install `planpilot` and all three skills automatically.
 
 ### 1) Prerequisites
 
-Check Python 3 is available:
+Check Python 3.11+ is available:
 
 ```bash
 python3 --version
 ```
 
-Optional strict check (requires Python 3.11+):
+If Python is not installed or below 3.11, install it from https://python.org.
 
-```bash
-python3 - <<'PY'
-import sys
-assert sys.version_info >= (3, 11), f"Need Python 3.11+, got {sys.version}"
-print("OK:", sys.version)
-PY
-```
+### 2) Install `planpilot`
+
+All options below put `planpilot` on your PATH so it can be invoked directly.
+
+**Option A — via `uv` (recommended):**
 
-Check pip is available:
+[`uv`](https://docs.astral.sh/uv/) installs tools in isolated environments with no PEP 668 issues.
+
+If `uv` is not installed:
 
 ```bash
-python3 -m pip --version
+curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
-### 2) Install `pipx` (if not already installed)
+> **Note:** Piping to `sh` without checksum verification is the officially recommended method but carries inherent supply-chain risk. For a verified install, download the binary directly from [uv GitHub releases](https://github.com/astral-sh/uv/releases) and verify the SHA-256 hash before running.
 
-[`pipx`](https://pipx.pypa.io/) installs CLI tools in isolated environments -- avoids PEP 668 / "externally managed environment" errors on macOS Homebrew and system Python.
+Then install planpilot:
 
 ```bash
-pipx --version
+uv tool install planpilot
+planpilot --version
 ```
 
+**Option B — via `pipx`:**
+
+[`pipx`](https://pipx.pypa.io/) installs CLI tools in isolated environments — avoids PEP 668 errors on macOS Homebrew and system Python.
+
 If `pipx` is not found:
 
 ```bash
@@ -70,19 +75,19 @@ pipx ensurepath
 
 You may need to restart your shell after `ensurepath`.
 
-### 3) Install `planpilot`
-
 ```bash
 pipx install planpilot
+planpilot --version
 ```
 
-Verify:
+**Option C — via `pip3` (last resort):**
 
 ```bash
+pip3 install planpilot
 planpilot --version
 ```
 
-### 4) Install the skills into open skill path
+### 3) Install the skills into open skill path
 
 Create destination directories:
 
@@ -92,7 +97,7 @@ mkdir -p ~/.agents/skills/create-tech-spec
 mkdir -p ~/.agents/skills/plan-sync
 ```
 
-#### Option A: Copy from local repo checkout
+#### Local: Copy from local repo checkout
 
 ```bash
 cp src/planpilot/skills/create-prd/SKILL.md \
@@ -105,7 +110,7 @@ cp src/planpilot/skills/plan-sync/SKILL.md \
   ~/.agents/skills/plan-sync/SKILL.md
 ```
 
-#### Option B: Fetch from GitHub raw URL
+#### Remote: Fetch from GitHub raw URL
 
 ```bash
 curl -fsSL "https://raw.githubusercontent.com/aryeko/planpilot/main/src/planpilot/skills/create-prd/SKILL.md" \
@@ -118,9 +123,9 @@ curl -fsSL "https://raw.githubusercontent.com/aryeko/planpilot/main/src/planpilo
   -o ~/.agents/skills/plan-sync/SKILL.md
 ```
 
-For reproducible installs, pin to a release tag (e.g., `v2.4.0`) instead of `main` once a new release is available.
+For reproducible installs, pin to a release tag (e.g., `v2.4.1`) instead of `main` once a new release is available.
 
-### 5) Verify skill install
+### 4) Verify skill install
 
 ```bash
 ls -la ~/.agents/skills/create-prd
@@ -139,13 +144,26 @@ Expected frontmatter should include:
 - `name: create-tech-spec`
 - `name: plan-sync`
 
-### 6) Restart your agent
+### 5) Restart your agent
 
 **Restart your agent** (start a new session) so it discovers the newly installed skill. The skill won't be available until the agent re-scans `~/.agents/skills/`.
 
-### 7) Update / uninstall
+### 6) Update / uninstall
+
+**Update `planpilot`:**
+
+```bash
+# If installed via uv
+uv tool upgrade planpilot
+
+# If installed via pipx
+pipx upgrade planpilot
+
+# If installed via pip3
+pip3 install --upgrade planpilot
+```
 
-Update (re-copy or re-fetch `SKILL.md` for each skill):
+**Update skills** (re-copy or re-fetch `SKILL.md` for each skill):
 
 ```bash
 curl -fsSL "https://raw.githubusercontent.com/aryeko/planpilot/main/src/planpilot/skills/create-prd/SKILL.md" \

{planpilot-2.4.0 → planpilot-2.5.0}/src/planpilot/skills/plan-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-sync
-description: Use when a user has PRD/spec/roadmap files and wants .plans artifacts generated and synced to GitHub Issues + a Projects v2 board in one guided flow. Standalone — planpilot installed from pip, no source tree required.
+description: Use when a user has PRD/spec/roadmap files and wants .plans artifacts generated and synced to GitHub Issues + a Projects v2 board in one guided flow. Standalone — planpilot available via plugin wrapper or manual install (uv/pipx/pip3), no source tree required.
 ---
 
 # Plan Sync
@@ -17,8 +17,7 @@ Before any action, list available skills and invoke all that apply. If installed
 
 ## Prerequisites
 
-- Python 3.11+
-- `planpilot` installed: `pipx install planpilot`
+- `planpilot` CLI accessible — via `uvx planpilot` (zero-install), a global install, or the Claude plugin wrapper (see [INSTALL.md](https://github.com/aryeko/planpilot/blob/main/src/planpilot/skills/INSTALL.md))
 - `gh` CLI installed and authenticated (scopes: `repo`, `project`)
 
 ## When to Use
@@ -458,56 +457,15 @@ Run preflight **before** config check — you need a working `planpilot` to run
 
 #### 5a) Verify planpilot is available
 
-Try the following commands **in order** until one succeeds:
+Try each invocation in order until one succeeds:
 
-```bash
-planpilot --version
-```
-
-If that fails (command not found):
-
-```bash
-python3 -m planpilot --version
-```
-
-If that also fails:
-
-```bash
-python -m planpilot --version
-```
-
-**If none of the above succeed**, run diagnostics:
-
-```bash
-which python3 python pipx
-python3 --version
-pipx list 2>/dev/null | grep -i planpilot
-```
+1. `uvx planpilot --version` → set `PLANPILOT_CMD="uvx planpilot"`
+2. `planpilot --version` → set `PLANPILOT_CMD="planpilot"`
+3. `python3 -m planpilot --version` → set `PLANPILOT_CMD="python3 -m planpilot"`
 
-Report findings to the user and explain:
+If all three fail, STOP and direct the user to install planpilot — see https://github.com/aryeko/planpilot/blob/main/src/planpilot/skills/INSTALL.md.
 
-> `planpilot` is not installed. Would you like me to install it?
-
-If the user agrees:
-
-1. **Ensure `pipx` is available** — check `pipx --version`. If not found, install it:
-
-   ```bash
-   brew install pipx && pipx ensurepath   # macOS
-   # or: sudo apt install -y pipx && pipx ensurepath   # Debian/Ubuntu
-   ```
-
-   The user may need to restart their shell after `ensurepath`.
-
-2. **Install planpilot**:
-
-   ```bash
-   pipx install planpilot
-   ```
-
-3. **Re-verify** with `planpilot --version`. If still failing, check that `~/.local/bin` is on `PATH`.
-
-**Remember which invocation worked** (`planpilot`, `python3 -m planpilot`, or `python -m planpilot`) and use that form for all subsequent commands in this session.
+Record which command succeeded as `PLANPILOT_CMD` — use it for all subsequent planpilot invocations in this session.
 
 #### 5b) Verify GitHub auth
 
@@ -531,9 +489,11 @@ If the user agrees, run the interactive init wizard. **You MUST run this from th
 - `detect_plan_paths()` scans `.plans/` and `plans/` for existing plan files to pre-fill paths.
 - Outside a git repo, both detections are disabled and every value must be entered manually.
 
+Use the invocation form that succeeded in preflight (step 5a). Examples use `planpilot` — substitute `uvx planpilot`, `python3 -m planpilot`, etc. if that's what worked.
+
 ```bash
 cd <repo-root>
-planpilot init
+$PLANPILOT_CMD init
 ```
 
 The wizard asks these questions in order. Forward each to the user with the hints below:
@@ -557,25 +517,23 @@ After the wizard completes, inform the user:
 If the user prefers non-interactive setup with auto-detected defaults:
 
 ```bash
-planpilot init --defaults
+$PLANPILOT_CMD init --defaults
 ```
 
 This generates a config with placeholder `board_url` that must be edited manually.
 
 ### 7) Sync Execution (sync / full)
 
-Use whichever invocation form succeeded in preflight (step 5a). Examples below use `planpilot` — substitute `python3 -m planpilot` or `python -m planpilot` if that's what worked.
-
 Always dry-run first:
 
 ```bash
-planpilot sync --config ./planpilot.json --dry-run
+$PLANPILOT_CMD sync --config ./planpilot.json --dry-run
 ```
 
 Review dry-run output. If everything looks correct:
 
 ```bash
-planpilot sync --config ./planpilot.json --apply
+$PLANPILOT_CMD sync --config ./planpilot.json --apply
 ```
 
 ### 8) Post-Sync Verification (sync / full)
@@ -606,7 +564,7 @@ Report to user:
 - Creating stories that are too large (not PR-sized) or tasks that span multiple days
 - Omitting `goal`, `requirements`, or `acceptance_criteria` (required by validator)
 - Forgetting to set `parent_id` on stories and tasks
-- Assuming `planpilot` command exists without checking — always verify availability first and fall back to `python3 -m planpilot`
+- Assuming `planpilot` is available without checking — always run preflight (step 5a) first
 - Running `planpilot init` outside the git repo root — auto-detection of target and plan paths will fail
 - Not committing `planpilot.json` to git — config must be tracked for reproducible syncs
 - Writing `planpilot.json` by hand with invalid field combinations (e.g. both `unified` and `epics` in `plan_paths`)