# Planwright standalone

Planwright is a local planner shared by a human and an AI coding agent. The
agent authors plans and records evidence through MCP; the human reviews intent,
ratifies plans, and accepts or requests changes through the web UI.

This repository contains the standalone React planner, SQLite core, MCP/CLI,
and reusable workflow engine. Code intelligence comes from external Vex. The
older Next.js application, hosted agent fleet, memory service, token-usage
collector, and built-in code index are retired.

## Run from source

Use Node.js 22.22 or newer, Corepack, and the repository-pinned pnpm version
(`pnpm@11.24.0`). SQLite uses `better-sqlite3`; native compilation may require
your platform's compiler toolchain if a prebuilt binary is unavailable.

```sh
git clone https://github.com/soundheart-studios/planwright.git
cd planwright
corepack pnpm install --frozen-lockfile
make build
```

Initialize a project from its own folder. Replace the CLI path below with your
absolute checkout path:

```sh
cd /path/to/your-project
node /absolute/path/planwright/packages/mcp-server/dist/cli.js init
node /absolute/path/planwright/packages/mcp-server/dist/cli.js web
```

Open **http://127.0.0.1:4400**. Initialization creates the project's
`.planwright/` data, registers it in the local project list, and installs MCP
configuration and workflow instructions for Claude Code and Codex. Reload the
agent connection after initialization. Existing installations with a `pw`
command can use `pw init` and `pw web` directly.

The existing macOS installation also answers at **http://planwright** through
its local front door. A fresh source checkout uses the loopback URL above;
this repository does not install the old hostname relay. The server binds to
loopback and uses a local human actor; it is not a public multi-user service.

From the checkout, `make web` builds and starts the planner. `make web-status`,
`make web-stop`, and `make web-restart` operate on the owned local service.
The UI is a production build, so restart it after source changes.

## The planning loop

1. The agent interviews you and seeds a structured plan with phase outcomes,
   task descriptions, acceptance criteria, test references, and dependencies.
2. You review and ratify the plan. Ratification is human-only; a draft cannot
   execute merely because an agent bound to it.
3. The agent records intent, demonstrates a failing test, implements the work,
   records a passing run, and commits task work. Removal verification proves
   that the tests detect the subject they claim to cover.
4. Each criterion maps to its evidence through `criterionRefs`. Completion
   requires the existing evidence, coverage, drift, and verification gates.
5. Material revisions arrive for human review. Reviews pin their content;
   changed content requires an explicit refresh before acceptance.

The MCP connection identifies the project. Call `plan_list`, then `plan_bind`
with an exact plan ID/name or an unambiguous task ID. Binding selects the plan
for that session; it does not ratify it or grant an exception to any gate.

The UI provides project and plan selection, phase navigation, an all-phases
view, completed-task history, a task inspector, ADRs with task links, and inline
plan/revision review. Reading positions have URLs and survive refresh and
Back/Forward navigation.

Completed tasks show a seven-character commit reference; clicking it copies
the full SHA. New completions use the explicitly accepted run. Completed
legacy tasks without completion metadata can show an existing passing run's
SHA labeled **Historical commit reference**. That display fallback creates no
completion receipt and changes no stored evidence. Copying supports the local
HTTP address as well as the secure-context Clipboard API.

## Reusable workflows

The workflow engine stores immutable definitions and exact revisions. The UI
shows the shared catalog and each plan's pins, local variants, origins, and
recent runs. Agents author workflow definitions through MCP.

```text
workflow_catalog_list {}
workflow_catalog_describe {name: "review", revision: 1}
workflow_bind {name: "review", revision: 1}
workflow_bindings {}
workflow_run {bindingId: "<returned pin id>", input: <declared input>, purpose: "adhoc"}
```

Use a workflow actually present in your catalog and its declared input shape.
Import copies pinned definitions and dependencies into the project. Existing
pins never silently upgrade. Ad hoc runs do not count as task evidence.
Stochastic steps still require their configured provider; catalog persistence
does not prove a provider integration works.

`PLANWRIGHT_WORKFLOW_REGISTRY` selects the shared workflow directory.
`PLANWRIGHT_REGISTRY` selects the project-list JSON file; these are separate
registries. `PLANWRIGHT_LOCAL_STATE` selects local web-service state.

## Data and existing projects

Each project owns its `.planwright/planwright.db`. Local project registration
and service state normally live under `~/.planwright/`. The standalone planner
retains historical database rows and receipt compatibility. Normal access
migrates the selected database additively; the cutover did not blanket-upgrade
all registered projects.

After updating the source, rebuild and refresh a selected project explicitly:

```sh
make install build
cd /path/to/your-project
node /absolute/path/planwright/packages/mcp-server/dist/cli.js upgrade
```

`upgrade --all` refreshes every registered project; use it only when that is
your intended scope. Back up databases consistently before operational changes.
Keep operational backups and rollback records outside the public source tree.

The core also retains case packs and claim/document evidence checkers. Their
historical records remain compatible; the standalone UI concentrates on plans,
ADRs, reviews, and workflows rather than the old case/claim dashboards.

## Development and validation

| Command | Purpose |
| --- | --- |
| `make build` | Build workflows, core, MCP/CLI, and React/HTTP adapters |
| `make test-focused TESTS='path/to/test.test.ts'` | Run an explicit focused test selection |
| `make test` | Run the full retained Vitest suite |
| `make typecheck` | Typecheck the workspace and planner |
| `make check` | Production builds, full tests, isolated build/typecheck probes, types, and compiled runtime checks |
| `make clean-clone` | Install and build an archive of committed HEAD; run before pushing |
| `make web-restart` | Rebuild and restart the owned local planner |

Use per-run temporary fixtures or copied databases for tests. Never write test
data or fabricated approvals into real projects. Repository instructions are in
[AGENTS.md](AGENTS.md), [CLAUDE.md](CLAUDE.md), and [ISOLATION.md](ISOLATION.md).

| Directory | Contents |
| --- | --- |
| `apps/planner` | React UI, HTTP adapters, fixtures, and integration tests |
| `packages/core` | SQLite migrations, plan/evidence gates, journal, and compatibility machinery |
| `packages/mcp-server` | `pw` / `planwright` CLI and MCP tools |
| `packages/workflows` | Workflow definitions, execution, and registry |
| `integrations/claude/planwright` | Experimental HTTP-based Claude mod adapter |
| `docs` | Architecture, compatibility, retirement, and validation records |

Private implementation records and operational logs are not distribution inputs.
See [apps/planner](apps/planner/README.md) for isolated fixture modes.
Native Claude mod-host rendering, live stochastic-provider acceptance, and
packaged distribution remain separate validation work; a passing local source
build does not establish those outcomes.

## Release automation

Soundheart Studios maintains Planwright. Licensing contact: **dev@soundheart.io**.
GitHub Actions validates pull requests and builds native Linux/macOS x64/arm64
archives on version tags. Archives include Node, production dependencies and
third-party notices. Each extracted archive must pass isolated CLI/SQLite/HTTP
smoke checks before a draft release is created for review. See
[release setup and targets](docs/releases.md).

Planwright is licensed under [AGPL-3.0-only](LICENSE), with a
[commercial alternative](LICENSE-COMMERCIAL) available by separate signed
agreement with Soundheart Studios. Contact **dev@soundheart.io**.
Third-party components retain their own licenses; see
[third-party notices](THIRD_PARTY_NOTICES.md).