@casualjim/pi-taskplane-planner

Glue between OpenSpec long-horizon planning and Taskplane execution.

This package compiles approved OpenSpec change contracts into Taskplane-native execution packets, runs whole-change conformance, and archives verified delta specs into cumulative truth.

Planning is done by OpenSpec (/opsx:explore, /opsx:propose). Execution is done by Taskplane (/orch). This package bridges the two — it does not duplicate either.

What it provides

• Pi extension commands (thin orchestration glue):
  • /plan-stage — validate an approved OpenSpec change and compile it into Taskplane packets
  • /plan-archive — promote passing delta specs into cumulative truth and archive the change
  • /plan-reopen — mark a change as reopened after a contract defect
• Thin CLI for status and packet operations:
  • planner status [change] — inspect staging and conformance state
  • planner stage <change> — compile approved contracts into Taskplane packets
  • planner archive <change> — archive a verified change
  • planner reopen <change> [reason] — reopen after a contract defect
• Taskplane packet generation
  • one implementation packet per capability spec (coarse-grained, end-to-end steps)
  • one terminal conformance packet for the whole change
• Archive flow that promotes delta specs into cumulative captured truth

Layout

OpenSpec owns the change contract:

openspec/
  changes/
    <change-slug>/
      proposal.md
      design.md
      specs/
        <capability>/spec.md
      conformance.md          ← written by the conformance Taskplane task
  specs/
    <capability>/spec.md      ← cumulative truth (synced on archive)
  changes/
    archive/
      YYYY-MM-DD-<change-slug>/

Taskplane owns execution:

taskplane-tasks/
  CONTEXT.md
  PHASE-IMPLEMENTATION.md
  PHASE-CONFORMANCE.md
  TP-xxx-.../
    PROMPT.md
    STATUS.md

Installation

This package is published to npm as @casualjim/pi-taskplane-planner and requires Node.js 24+.

Install for pi

pi install npm:@casualjim/pi-taskplane-planner

Install the CLI on your PATH

npm install -g @casualjim/pi-taskplane-planner

Then restart or /reload pi. Use pi list to confirm the package is registered.

Workflow

1. Plan with OpenSpec

/opsx:explore my-change
/opsx:propose my-change

This creates openspec/changes/my-change/ with proposal, design, specs, and tasks.

2. Stage into Taskplane packets

/plan-stage my-change

This validates the approved contract and compiles it into Taskplane packets under taskplane-tasks/. Generated packets use coarse-grained end-to-end steps — tests, documentation, and repo gates are folded into the implementation step.

3. Execute with Taskplane

/orch taskplane-tasks/TP-001-.../PROMPT.md taskplane-tasks/TP-002-verify-.../PROMPT.md

4. Archive verified truth

When conformance passes:

planner archive my-change

This syncs delta specs into cumulative truth and moves the change into the archive.

Development

Run tests:

npm test

Run the Node-based package gate used by CI/publishing:

npm run typecheck
npm run check:pack

npm run build remains an alias for the typecheck gate.

Optional runtime E2E (requires a working local Taskplane + pi runtime environment and model/API access):

npm run test:runtime-e2e

This executes a planner-generated implementation packet through real Taskplane runtime orchestration, proves the runtime worker reads PHASE-IMPLEMENTATION.md, then probes a planner-generated conformance packet and proves that the runtime worker reads PHASE-CONFORMANCE.md at the correct phase boundary. The test then writes a deterministic ARCHIVE_READY conformance report from the harness and archives the change.

Publishing

Publishing is automated through GitHub Actions using the same main-branch publish flow as ../pi-heimdall:

• CI runs on pull requests and manual dispatch with npm ci, npm run typecheck, and npm run check:pack
• Publish runs on pushes to main and manual dispatch
• if the package.json version is not already on npm, the workflow publishes it with trusted publishing
• after a successful publish, the workflow bumps the patch version on main with [skip ci] so the repo is ready for the next publish
• npmjs needs a Trusted Publisher entry for this repo
• npm trusted publishing means no long-lived npm token secret is needed in GitHub

Notes

• OpenSpec handles all planning: exploration, proposal creation, design, and spec generation.
• Taskplane handles all execution: worker orchestration, review, and merge.
• This package only bridges the two — it compiles approved OpenSpec contracts into Taskplane packets, manages conformance, and archives results.