gpd

gpd is a Pi extension for durable, human-first planning and building. It keeps project truth in docs/. It runs both workflows in the Pi session and model you choose.

Install

After publication, install the package from npm:

pi install npm:@yofriadi/pi-gpd

Pi discovers the package's declared extension entry on the next launch or reload. Use a versioned package spec such as npm:@yofriadi/[email protected] for a reproducible install.

Contributor setup

For development from a repository clone:

corepack pnpm install
corepack pnpm run verify
corepack pnpm run package:check
pi

Open Pi from the trusted repository. The project-local .pi/extensions/gpd.ts shim is auto-discovered. The shim re-exports the packaged extensions/gpd.ts entry. For a one-off local load, use pi -e ./.pi/extensions/gpd.ts.

Before using a workflow, enable Pi's relevant active tools. These tools include subagent, repository read/search, and file tools. Create user-managed reviewer profiles at:

${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents/plan-reviewer.md
${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents/code-reviewer.md

• Reviewer profiles return exactly one fenced JSON block containing blockers, warnings, nitpicks, and summary.
• Every finding has an issue string and may have a fix string.
• gpd fails closed on any other terminal-review format.

Only interactive Pi TUI sessions are supported.

Commands notify and tools return a non-tui-mode refusal in RPC, print, or JSON modes.

gpd provides no non-interactive alternative.

Manual release

This repository prepares a public package but does not publish it. The release operator owns access to the @yofriadi npm scope.

1. Start with a clean checkout and install dependencies with corepack pnpm install --frozen-lockfile.
2. Run corepack pnpm run verify and corepack pnpm run package:check.
3. Inspect the selected archive with npm pack --dry-run --json --ignore-scripts.
4. Authenticate with npm outside this repository and publish @yofriadi/[email protected] with public scoped access. For example, use npm publish --access public --ignore-scripts.
5. After publication, use a disposable Pi profile with pi install npm:@yofriadi/pi-gpd or an explicit version. Confirm that /plan, /build, complete-plan, lock-build-verification, and complete-build register.

The post-publication install check is a manual operator step. It is not CI or a credential-free build test. Do not store npm credentials, tokens, or release configuration in this repository.

Workflows

Plan

Run /plan [topic] in the session and model you want to use for planning.

• An ordinary plan creates a same-session planning marker and asks only implementation-shaping questions. It writes final-path Status: draft artifacts and runs the background global plan-reviewer.
• Use the exact returned reviewer ID with complete-plan. That gate promotes the PLAN, updates the ROADMAP, records warnings in CONTEXT, and regenerates STATE.
• A mission/constraint PROJECT-only request directly edits docs/PROJECT.md without a marker. It does not invoke review or block a later build.
• A blocker-bearing, missing, failed, or malformed review receipt leaves planning active. Repair the draft, obtain a fresh reviewer receipt, and retry complete-plan.

Build

Run /build [planId] in the session and model you want to use for implementation. If there is one eligible planned item, the ID is optional.

• A new build requires a valid Git worktree and no non-docs/ changes. A matching incomplete build can continue in the same session.
• Before changing source, call lock-build-verification. Its repository-derived selection is immutable and is rerun by final completion.
• Implement the immutable PLAN sequentially. Use a background global code-reviewer and obtain a fresh review receipt after each source change.
• Call complete-build with the latest successful reviewer ID and concise implementation details. It reruns verification, writes the SUMMARY, closes covered requirements, and regenerates STATE.
• If review or final verification fails, the build remains active. Repair the source, rerun the locked verification, obtain a fresh code-reviewer receipt, and retry complete-build. The workflow accepts at most three successful reviews.

During an active build, model-authored write and edit calls to repository docs/ are blocked. The finalizer still writes SUMMARY, REQUIREMENTS, and STATE internally. Source changes remain visible and uncommitted after completion.

Runtime and session behavior

Planning and building never create or replace sessions, select models, or serialize handoffs.

Markers, reviewer receipts, verification locks, and completions live on the active session branch.

A conflicting command refuses only while the current workflow is incomplete.

After completion, either workflow may begin in the same session.

Start a fresh user-selected Pi session when you want clean conversational context.

gpd never creates one for you.

The loaded extension remains stable through a build. Do not reload it during implementation or before completion. Use a separate disposable Pi process to exercise changed extension source before completion. After completion, explicitly reload or restart Pi when ready.

v1 scope

The v1 surface is /plan, /build, complete-plan, lock-build-verification, and complete-build. Role-child workflows, scaffold commands, candidate stores, replay/journal machinery, automatic commits, and print/JSON/RPC modes are not part of gpd.