# Getting started

## Prerequisites

- Node.js `>=22.19.0`.
- Pi and the peer packages declared by this package.
- A trusted project when you want configured verification commands to run.

Install the published package:

```bash
pi install @rahulvramesh/pi-let
# or project-local configuration
pi install -l @rahulvramesh/pi-let
```

Install from a checkout for one run:

```bash
pi -e /absolute/path/to/pi-let
```

Install as a Pi package:

```bash
pi install /absolute/path/to/pi-let
# or project-local configuration
pi install -l /absolute/path/to/pi-let
```

Pi extensions run with your user permissions. Review the package before installing it.

## Create a goal

The shortest form makes the objective its sole initial criterion and runs without an iteration or token budget:

```text
/goal Fix the flaky integration test
```

Creation immediately replaces any goal on the current branch, persists the new state, and schedules one hidden follow-up worker turn if Pi is idle and has no pending messages. It does not open an interview or dialog.

You can also use explicit natural language such as “set fixing the flaky integration test as a goal.” The LLM then calls `goal_set`; it must not infer goal intent from an ordinary task request. This tool supports criteria and constraints, but not verifier commands, which remain user-approved configuration.

For a precise, non-interactive contract:

```text
/goal \
  --criterion 'Authentication tests pass' \
  --criterion 'LegacyToken is absent from src/auth' \
  --constraint 'Do not change public request or response schemas' \
  --verify 'npm test -- test/auth' \
  --verify 'rg LegacyToken src/auth' --verify-exit 1 \
  Migrate authentication to TokenV2
```

Quotes only split the command arguments; they are not evaluated by a shell. Read [Goal contracts and commands](contracts-and-commands.md) for every option.

## Observe and control work

```text
/goal              # show state
/goal status       # same as above
/goal pause        # abort an in-flight worker if necessary and stop continuations
/goal resume       # activate a non-complete, non-archived goal and queue one turn
/goal archive      # stop and archive the current goal
/goal clear        # remove this branch’s goal with a persisted tombstone
```

`/goal pause` never resumes automatically. `/goal resume` clears the no-progress count and stored blocker, but preserves accumulated iterations and token usage. A completed goal cannot resume; create a replacement goal instead.

A goal restored after session startup or branch navigation is paused for safety. Explicitly resume it when ready:

```text
/goal resume
```

## What the worker sees

While active, pi-let appends a protocol containing the id, revision, iteration count, and JSON contract to Pi’s normal system prompt. It instructs the worker to inspect, implement, verify, and call `goal_complete` only with concrete evidence. Objective text is marked as untrusted task data and cannot alter extension policy or tool permissions.

The hidden initial continuation says to begin work; later continuations include the latest judge gaps and next instruction when present. A normal assistant response never completes a goal.