ship-parallax

name	ship-parallax
description	Use when shipping a feature or fix to the parallax Python CLI — finds an unblocked issue, implements on a feature branch, installs as an isolated parallax-pr<N> command for live CLI testing, and merges to alpha after verification.

Ship Parallax

The full development lifecycle for the parallax CLI. Three entry points:

Invocation	Entry point
/ship-parallax	Auto-find next unblocked issue (P1→P2→P3→P4) → Phase 0
/ship-parallax <issue-number>	Start from a specific issue → Phase 1
/ship-parallax P1 / /ship-parallax P2 / etc.	Find first unblocked issue at that level → Phase 0

---

Phase 0 — Find the Issue

Run in parallel:

head -150 DEV_LOG.md
gh issue list --state open --json number,title,labels,body --limit 10

Filter client-side — skip any issue labeled in progress or blocked.

in progress = another agent is actively working on that issue. Do NOT pick it up. Do NOT "continue" it. Treat every in progress issue as if it does not exist.

Determine target:

• No arg → from the remaining issues, pick the highest-priority one (P1→P2→P3→P4), lowest number first
• Priority arg (e.g. P2) → restrict to that label only
• Issue number arg → skip this phase, go straight to Phase 1

The filtered, sorted list is your candidate set. Pick the first one → proceed to Phase 1.

---

Phase 1 — Pre-flight

git status --porcelain

If alpha is dirty: stop. Ask whether to commit first or carry changes into the new branch.

Mark the issue in progress and set the pane title:

gh issue edit <number> --add-label "in progress"
plexi pane set-title "#<number> — <short-title>"

---

Phase 2 — Worktree Setup

Run from the repo root:

wtp add -b feature/<issue-number>-short-description

If branch already exists: check git worktree list. If no open worktree, add without -b. Run git log --oneline -5 to surface prior commits — treat as partial implementation.

Immediately verify the base:

git -C worktrees/<branch> log --oneline -1
git log --oneline -1

If they don't match: delete the worktree and branch, redo from the repo root. Never proceed on the wrong base.

---

Phase 3 — Formulate

Before writing any code, read the issue and relevant source to produce a tight implementation spec. This step is mandatory — it is what makes subagent dispatch reliable.

Read in parallel:

• Full issue body: gh issue view <number> --json title,body,labels,comments
• DEV_LOG header: head -100 DEV_LOG.md
• Current CLI surface: parallax --help && parallax schema
• Relevant source files: grep for affected modules, then read them

Write an implementation spec (keep in context, do not write to disk):

Files to change:
  - src/parallax/foo.py:42 — <exactly what>
  - src/parallax/bar.py:10 — <exactly what>

Files NOT to touch:
  - <adjacent but out of scope>

Test that must pass:
  - uv run pytest tests/test_foo.py::test_name

Invariants to preserve:
  - <any non-obvious constraints from DEV_LOG or CLAUDE.md>

Assumptions to validate:
  - <what must be true> — validated by: <cheapest CLI/log/source check>
  (Run each check NOW, before writing any code.)

---

Phase 4 — Implement

Scope gate:

• ≤ 3 files: implement inline in the feature worktree. Write tests first, run uv run pytest.
• > 3 files or multiple subsystems: dispatch a Sonnet subagent.

Subagent dispatch

Construct the subagent prompt with everything it needs — do not make it explore:

• The implementation spec (full text from Phase 3)
• Contents of every file it will touch (paste inline)
• Worktree path: worktrees/<branch>/
• Explicit rules: write tests first, run uv run pytest, stage changes but do NOT commit
• Report back: DONE | DONE_WITH_CONCERNS <details> | NEEDS_CONTEXT <what> | BLOCKED <reason>

Handle subagent status:

• DONE: review staged diff, run uv run pytest, check for new Pyright errors (uv run pyright src/ 2>&1 | grep error — zero new errors required), then commit.
• DONE_WITH_CONCERNS: read concerns first. Correctness/scope → address before committing.
• NEEDS_CONTEXT: provide missing context, redispatch with same model.
• BLOCKED: if context problem → provide more + redispatch. If plan wrong → escalate to user.

Orchestrator owns the commit. Subagent stages only. After verifying diff, uv run pytest is green, and uv run pyright src/ shows no new errors:

git -C worktrees/<branch> add <files>
git -C worktrees/<branch> commit -m "<message>"
git -C worktrees/<branch> push origin HEAD

Open a PR targeting alpha — always pass --head explicitly (gh fails with "Head sha can't be blank" if branch isn't on remote):

gh pr create --base alpha --head feature/<branch> --title "<title>" --body "..."

---

Phase 4 — Install & Test

Run from inside the feature worktree:

just pr-install <pr-number>

This installs the CLI as parallax-pr<N> — an isolated command backed by a dedicated virtualenv at ~/.parallax-pr-<N>/. The main parallax install is untouched.

Build the testing plan — every command copy-pasteable, no placeholders:

• Use /tmp/parallax-pr<N>-test/ as test folder — include mkdir and plan.yaml write steps
• Set PARALLAX_TEST_MODE=1, PARALLAX_LOG_DIR=/tmp/parallax-pr<N>-logs, and PARALLAX_USAGE_LOG=/tmp/parallax-pr<N>-usage.ndjson inline on every produce command
• Cover every CLI path the change touches (new flags, subcommands, output formats, edge cases) — not just a smoke test
• When testing dependency removal, verify against pyproject.toml (the source of truth), not the installed venv — transitive deps of kept packages will always be present in the venv.

Dispatch a Sonnet subagent to execute the full testing plan. Give it:

• The installed command name: parallax-pr<N>
• Every test command to run (exact, copy-pasteable)
• Pass criteria and fail criteria for each
• Instruction to report back: exit codes, exact output observed, which criteria passed/failed

The subagent must run every command and return a structured report:

[TEST RESULTS] PR #<n> — <title>

Command: <exact command>
Exit: <code>  Output: <observed output>
Result: PASS | FAIL — <why>

... (one block per command)

Overall: PASS | FAIL

Present the full report to the user.

Command formatting rule: Any command you give the user to run must appear alone in its own code block — never inline inside prose. One command per block, nothing else on the line.

If any path failed — retry loop (max 1 retry):

1. First failure: Diagnose the root cause from the sub-agent output, make the minimal targeted fix on the feature branch, commit, re-run just pr-install <pr-number>, and re-dispatch the sub-agent with the same test plan.

2. Second failure: Stop. Surface the failure to the user with:

   • What command failed
   • Exact output / error observed
   • Why we believe it failed
   • Recommendation: close the PR, update the issue with learnings, re-open for a fresh attempt

   Run these steps after user confirms:

   gh pr close <number> --comment "Closing after two failed CLI test attempts. <what failed, why we think it failed>"
   gh issue edit <number> --remove-label "in progress" --add-label "ready"
   gh issue comment <number> --body "Attempted in PR #<n>. Failed because: <root cause>. Next attempt should: <concrete suggestion>."
   

   Do NOT attempt a third fix. The implementation approach needs rethinking.

STOP. Do not proceed until the user confirms pass.

If testing fails: fix on the feature branch, re-run just pr-install, re-surface the testing block. If the approach is fundamentally wrong: close PR, revert, comment on issue with what failed and why, re-label ready, start fresh.

After user confirms pass — write DEV_LOG on the feature branch before merging:

# Edit DEV_LOG.md in worktrees/<branch>/ — newest-first entry, tag + **Breaks if:** line
git -C worktrees/<branch> add DEV_LOG.md
git -C worktrees/<branch> commit -m "docs: DEV_LOG entry for PR #<n>"
git -C worktrees/<branch> push origin HEAD

The DEV_LOG commit gets squash-merged into alpha — no separate bookkeeping commit needed post-merge.

---

Phase 5 — Merge & Cleanup

After DEV_LOG is committed on the feature branch. Run without stopping:

0. Sync alpha and rebase:

   git -C /Users/ianburke/Documents/GitHub/parallax-v0 pull origin alpha
   git -C worktrees/<branch> rebase origin/alpha
   

   If pull diverges (local alpha has unpushed commits): run git show origin/alpha --stat — if the local-only commits appear in the squash merge, git -C /Users/ianburke/Documents/GitHub/parallax-v0 reset --hard origin/alpha is safe. If they don't appear, surface to user before resetting. If conflicts on rebase: resolve, then git -C worktrees/<branch> push --force-with-lease origin HEAD. DEV_LOG.md conflicts are the most common: always resolve by placing the new entry ABOVE the conflicting HEAD block (DEV_LOG is newest-first). If rebase meaningfully changes the feature, re-surface the testing block before merging.

1. gh pr merge <number> --squash — never pass --delete-branch

   Then check for post-merge hook changes before bumping:

   git -C /Users/ianburke/Documents/GitHub/parallax-v0 status --porcelain
   

   If dirty: commit or stash before continuing — just bump will fail on a dirty tree.

2. Steps 2-6 all run from the repo root — cd once, then chain:

   cd /Users/ianburke/Documents/GitHub/parallax-v0
   just pr-clean <pr-number>
   git pull origin alpha
   wtp remove --force <branch>
   git push origin --delete <branch>
   just bump
   just install
   git push origin alpha
   

   (git push origin alpha keeps local and remote in sync — prevents divergence next cycle)

---

Phase 6 — Complete

gh issue close <number> --comment "Closed by PR #<pr> — verified on alpha <version>"
git status   # must be clean

Output:

- Merged: PR #<n> — <title>
- Closed: Issue #<n> — <title>
- Version: <version>
- DEV_LOG: updated

[COMPLETE]

Then run /improve to surface friction from this session.

After /improve — commit any meta-file changes directly to alpha (no PR needed):

Check for changes in CLAUDE.md, skills, or other config files:

git status --porcelain

If any meta files are dirty, commit them directly to alpha and push:

git add CLAUDE.md .claude/skills/ <other changed meta files>
git commit -m "docs: improve notes from PR #<n> session"
git push origin alpha

If the changes are in ~/.claude/ (global skills, settings), commit them to the dotfiles repo instead — they don't belong in this repo.

---

Rules

• Never branch from main — always from the repo root (alpha)
• Never skip base verification after wtp add
• Never merge before user confirms testing passed
• Never claim [COMPLETE] without user verification
• just pr-install runs from the feature worktree
• just pr-clean, just bump, and just install run from the repo root
• Never pass --delete-branch to gh pr merge — git refuses to delete a branch checked out by a worktree
• Alpha must be clean when the cycle ends
• Subagents stage only — orchestrator owns the commit and the PR
• Never dispatch a subagent without first producing the Phase 3 implementation spec